Package net.time4j

Class PlainDate

java.lang.Object
net.time4j.engine.ChronoEntity<T>
net.time4j.engine.TimePoint<U,​D>
net.time4j.engine.Calendrical<IsoDateUnit,​PlainDate>
net.time4j.PlainDate
All Implemented Interfaces:
Serializable, Comparable<PlainDate>, TemporalAccessor, GregorianDate, CalendarDate, ChronoDisplay, Normalizer<CalendarUnit>, Temporal<CalendarDate>, ThreetenAdapter, LocalizedPatternSupport
@CalendarType("iso8601") public final class PlainDate extends Calendrical<IsoDateUnit,​PlainDate> implements GregorianDate, Normalizer<CalendarUnit>, ThreetenAdapter, LocalizedPatternSupport

Represents a plain calendar date in conformance to ISO-8601-standard using the gregorian calendar rules for all times.

The value range also contains negative years down to -999999999. These years cannot be directly interpreted in a historic way, as in general no past year, too. Instead such related dates can and must rather be interpreted as a different way of counting days - like epoch days. The rules of gregorian calendar are applied in a proleptic way that is backwards into the past even before the earliest introduction of gregorian calendar in Rome (a non-historic mathematical abstraction).

However, this class enables full historization via a historic extension mechanism (i18n-module). When formatting or parsing based on the expert engine of Time4J, it is sufficient to specify a historic era (pattern symbol G) using the history of calendar reforms in a locale, and Time4J will automatically apply different rules of calendar history. It is also possible to explicitly model a suitable history by creating an instance of net.time4j.history.ChronoHistory and to feed the format engine with this information. Furthermore, this history object yields specialized elements for querying and manipulating an ISO-8601 calendar date in a historic context.

Following elements which are declared as constants are registered by this class:

Furthermore, all elements of classes Weekmodel, EpochDays and ChronoHistory are supported.

Author:
Meno Hochschild
See Also:
Serialized Form

  • Field Details

    • COMPONENT

      public static final CalendarDateElement COMPONENT

      Element with the calendar date in the value range [-999999999-01-01] until [+999999999-12-31].

      Example of usage: 

        PlainTimestamp tsp = PlainTimestamp.of(2014, 8, 21, 14, 30);
  tsp = tsp.with(PlainDate.COMPONENT, PlainDate.of(2015, 1, 1));
  System.out.println(tsp); // output: 2015-01-01T14:30
      Since:
      1.2

    • YEAR

      @FormattableElement(format="u") public static final AdjustableElement<Integer,​PlainDate> YEAR

      Element with the proleptic iso-year without any era reference and the value range -999999999 until 999999999.

      Examples: 

        import static net.time4j.PlainDate.YEAR;

  PlainDate date = PlainDate.of(2012, 2, 29);
  System.out.println(date.get(YEAR)); // output: 2012

  date = date.with(YEAR, 2014);
  System.out.println(date); // output: 2014-02-28

  date = date.with(YEAR.incremented()); // nächstes Jahr
  System.out.println(date); // output: 2015-02-28

  date = date.with(YEAR.atCeiling()); // letzter Tag des Jahres
  System.out.println(date); // output: 2015-12-31

  date = date.with(YEAR.atFloor()); // erster Tag des Jahres
  System.out.println(date); // output: 2015-01-01

      The term "proleptic" means that the rules of the gregorian calendar and the associated way of year counting is applied backward even before the introduction of gregorian calendar. The year 0 is permitted - and negative years, too. For historic year numbers, this mathematical extrapolation is not recommended and usually wrong.

    • YEAR_OF_WEEKDATE

      @FormattableElement(format="Y") public static final AdjustableElement<Integer,​PlainDate> YEAR_OF_WEEKDATE

      Defines an element for the week-based year in an ISO-8601-weekdate.

      The week-based year is usually the same as the calendar year. However, at the begin or end of a calendar year the situation is different because the first week of the weekdate can start after New Year and the last week of the weekdate can end before the last day of the calendar year. Examples:

      • Sunday, [1995-01-01] => [1994-W52-7]
      • Tuesday, [1996-31-12] => [1997-W01-2]

      Note: This element has a special basic unit which can be used such that the day of the week will be conserved instead of the day of month after adding one week-based year: 

        PlainDate date = PlainDate.of(2014, JANUARY, 2); // Thursday
  IsoDateUnit unit = CalendarUnit.weekBasedYears();
  System.out.println(date.plus(1, unit)); // output: 2015-01-01
      See Also:
      CalendarUnit.weekBasedYears(), Weekmodel.ISO

    • QUARTER_OF_YEAR

      @FormattableElement(format="Q", alt="q") public static final NavigableElement<Quarter> QUARTER_OF_YEAR

      Element with the quarter of year in the value range Q1-Q4.

    • MONTH_OF_YEAR

      @FormattableElement(format="M", alt="L") public static final NavigableElement<Month> MONTH_OF_YEAR

      Element with the calendar month as enum in the value range JANUARY-DECEMBER).

      Examples: 

        import static net.time4j.PlainDate.MONTH_OF_YEAR;
  import static net.time4j.Month.*;

  PlainDate date = PlainDate.of(2012, 2, 29);
  System.out.println(date.get(MONTH_OF_YEAR)); // output: February

  date = date.with(MONTH_OF_YEAR, APRIL);
  System.out.println(date); // output: 2012-04-29

  date = date.with(MONTH_OF_YEAR.incremented()); // next month
  System.out.println(date); // output: 2012-05-29

  date = date.with(MONTH_OF_YEAR.maximized()); // last month of year
  System.out.println(date); // output: 2012-12-29

  date = date.with(MONTH_OF_YEAR.atCeiling()); // last day of month
  System.out.println(date); // output: 2012-12-31

  date = date.with(MONTH_OF_YEAR.atFloor()); // first day of month
  System.out.println(date); // output: 2012-12-01

  date = date.with(MONTH_OF_YEAR.setToNext(JULY)); // move to July
  System.out.println(date); // output: 2013-07-01

    • MONTH_AS_NUMBER

      @FormattableElement(format="M") public static final ProportionalElement<Integer,​PlainDate> MONTH_AS_NUMBER

      Element with the calendar month in numerical form and the value range 1-12.

      Normally the enum-variant is recommended due to clarity and type-safety. The enum-form can also be formatted as text. However, if users want to set any month number in a lenient way with possible carry-over then they can do it like in following example: 

        import static net.time4j.PlainDate.MONTH_AS_NUMBER;

  PlainDate date = PlainDate.of(2012, 2, 29);
  date = date.with(MONTH_AS_NUMBER.setLenient(13);
  System.out.println(date); // output: 2013-01-29
      See Also:
      MONTH_OF_YEAR

    • DAY_OF_MONTH

      @FormattableElement(format="d") public static final ProportionalElement<Integer,​PlainDate> DAY_OF_MONTH

      Element with the day of month in the value range 1-28/29/30/31.

    • DAY_OF_WEEK

      @FormattableElement(format="E") public static final NavigableElement<Weekday> DAY_OF_WEEK

      Element with the day of week in the value range MONDAY-SUNDAY.

      A localized form is available by Weekmodel.localDayOfWeek(). In US sunday is considered as first day of week, different from definition used here (monday as start of calendar week according to ISO-8601). Therefore, if users need localized weekday-numbers, users can use the expression Weekmodel.of(Locale.US).localDayOfWeek() in a country like US.

    • DAY_OF_YEAR

      @FormattableElement(format="D") public static final ProportionalElement<Integer,​PlainDate> DAY_OF_YEAR

      Element with the day of year in the value range 1-365/366).

    • DAY_OF_QUARTER

      public static final ProportionalElement<Integer,​PlainDate> DAY_OF_QUARTER

      Element with the day within a quarter of year in the value range 1-90/91/92.

    • WEEKDAY_IN_MONTH

      @FormattableElement(format="F") public static final OrdinalWeekdayElement WEEKDAY_IN_MONTH

      Element with the ordinal day-of-week within given calendar month in the value range 1-5.

      Example: 

        import static net.time4j.PlainDate.WEEKDAY_IN_MONTH;
  import static net.time4j.Weekday.*;

  PlainDate date = PlainDate.of(2013, 3, 1); // first of march 2013
  System.out.println(date.with(WEEKDAY_IN_MONTH.setToThird(WEDNESDAY)));
  // output: 2013-03-20 (third Wednesday in march)

  • Method Details

    • of

      public static PlainDate of​(int year, int month, int dayOfMonth)

      Creates a new calendar date conforming to ISO-8601.

      Parameters:
      year - proleptic iso year [(-999,999,999)-999,999,999]
      month - gregorian month in range (1-12)
      dayOfMonth - day of month in range (1-31)
      Returns:
      new or cached calendar date instance
      Throws:
      IllegalArgumentException - if any argument is out of range
      See Also:
      of(int, Month, int), of(int, int), of(int, int, Weekday)

    • of

      public static PlainDate of​(int year, Month month, int dayOfMonth)

      Creates a new calendar date conforming to ISO-8601.

      Parameters:
      year - proleptic iso year [(-999,999,999)-999,999,999]
      month - gregorian month in range (January-December)
      dayOfMonth - day of month in range (1-31)
      Returns:
      new or cached calendar date instance
      Throws:
      IllegalArgumentException - if any argument is out of range
      See Also:
      of(int, int, int)

    • of

      public static PlainDate of​(int year, int dayOfYear)

      Creates a new ordinal date conforming to ISO-8601.

      Parameters:
      year - proleptic iso year [(-999,999,999)-999,999,999]
      dayOfYear - day of year in the range (1-366)
      Returns:
      new or cached ordinal date instance
      Throws:
      IllegalArgumentException - if any argument is out of range

    • of

      public static PlainDate of​(int yearOfWeekdate, int weekOfYear, Weekday dayOfWeek)

      Creates a new week-date conforming to ISO-8601.

      Parameters:
      yearOfWeekdate - week-based-year according to ISO-definition
      weekOfYear - week of year in the range (1-52/53)
      dayOfWeek - day of week in the range (MONDAY-SUNDAY)
      Returns:
      new or cached week date instance
      Throws:
      IllegalArgumentException - if any argument is out of range

    • of

      public static PlainDate of​(long amount, EpochDays epoch)

      Creates a new date based on count of days since given epoch.

      Parameters:
      amount - count of days
      epoch - reference date scale
      Returns:
      found calendar date based on given epoch days
      Throws:
      IllegalArgumentException - if first argument is out of range

    • nowInSystemTime

      public static PlainDate nowInSystemTime()

      Obtains the current date in system time.

      Convenient short-cut for: SystemClock.inLocalView().today().

      Returns:
      current calendar date in system time zone using the system clock
      Since:
      3.23/4.19
      See Also:
      SystemClock.inLocalView(), ZonalClock.today()

    • from

      public static PlainDate from​(GregorianDate date)

      Common conversion method for proleptic gregorian dates.

      Parameters:
      date - ISO-date
      Returns:
      PlainDate

    • from

      public static PlainDate from​(LocalDate date)

      Short cut for TemporalType.LOCAL_DATE.translate(date).

      Parameters:
      date - Threeten-equivalent of this instance
      Returns:
      PlainDate
      Since:
      4.0
      See Also:
      TemporalType.LOCAL_DATE

    • atStartOfDay

      public PlainTimestamp atStartOfDay()

      Creates a new local timestamp with this date at midnight at the begin of associated day.

      Returns:
      local timestamp as composition of this date and midnight
      See Also:
      at(PlainTime)

    • atStartOfDay

      public PlainTimestamp atStartOfDay​(TZID tzid)

      Creates a new local timestamp with this date at earliest valid time at the begin of associated day in given timezone.

      Parameters:
      tzid - timezone id
      Returns:
      local timestamp as composition of this date and earliest valid time
      Throws:
      IllegalArgumentException - if given timezone cannot be loaded
      UnsupportedOperationException - if the underlying timezone repository does not expose any public transition history
      Since:
      2.2
      See Also:
      atStartOfDay(), atFirstMoment(TZID)

    • atStartOfDay

      public PlainTimestamp atStartOfDay​(String tzid)

      Creates a new local timestamp with this date at earliest valid time at the begin of associated day in given timezone.

      Parameters:
      tzid - timezone id
      Returns:
      local timestamp as composition of this date and earliest valid time
      Throws:
      IllegalArgumentException - if given timezone cannot be loaded
      UnsupportedOperationException - if the underlying timezone repository does not expose any public transition history
      Since:
      2.2
      See Also:
      atStartOfDay(), atFirstMoment(String)

    • atFirstMoment

      public Moment atFirstMoment​(TZID tzid)

      Creates a new moment which corresponds to this date at earliest valid time at the begin of associated day in given timezone.

      Parameters:
      tzid - timezone id
      Returns:
      first valid moment corresponding to start of day in given timezone
      Throws:
      IllegalArgumentException - if given timezone cannot be loaded
      UnsupportedOperationException - if the underlying timezone repository does not expose any public transition history
      Since:
      3.22/4.18
      See Also:
      atStartOfDay(TZID)

    • atFirstMoment

      public Moment atFirstMoment​(String tzid)

      Creates a new moment which corresponds to this date at earliest valid time at the begin of associated day in given timezone.

      Parameters:
      tzid - timezone id
      Returns:
      first valid moment corresponding to start of day in given timezone
      Throws:
      IllegalArgumentException - if given timezone cannot be loaded
      UnsupportedOperationException - if the underlying timezone repository does not expose any public transition history
      Since:
      3.22/4.18
      See Also:
      atStartOfDay(String)

    • at

      public PlainTimestamp at​(PlainTime time)

      Creates a new local timestamp with this date and given wall time.

      If the time T24:00 is used then the resulting timestamp will automatically be normalized such that the timestamp will contain the following day instead.

      Parameters:
      time - wall time
      Returns:
      local timestamp as composition of this date and given time

    • atTime

      public PlainTimestamp atTime​(int hour, int minute)

      Is equivalent to at(PlainTime.of(hour, minute)).

      Parameters:
      hour - hour of day in range (0-24)
      minute - minute of hour in range (0-59)
      Returns:
      local timestamp as composition of this date and given time
      Throws:
      IllegalArgumentException - if any argument is out of range

    • atTime

      public PlainTimestamp atTime​(int hour, int minute, int second)

      Is equivalent to at(PlainTime.of(hour, minute, second)).

      Parameters:
      hour - hour of day in range (0-24)
      minute - minute of hour in range (0-59)
      second - second of hour in range (0-59)
      Returns:
      local timestamp as composition of this date and given time
      Throws:
      IllegalArgumentException - if any argument is out of range

    • getYear

      public int getYear()
      Description copied from interface: GregorianDate

      Yields the proleptic year according to ISO-8601.

      The term proleptic means that the gregorian calendar rules are applied backwards even before the introduction of this calendar. Second: The year numbering is just the mathematical one as defined in ISO-8601 such that there is a year zero and even negative years: -2 = BC 3, -1 = BC 2, 0 = BC 1, 1 = AD 1, 2 = AD 2, ...

      Specified by:
      getYear in interface GregorianDate
      Returns:
      proleptic iso year in range GregorianMath.MIN_YEAR - GregorianMath.MAX_YEAR

    • getMonth

      public int getMonth()
      Description copied from interface: GregorianDate

      Yields the gregorian month as integer.

      Specified by:
      getMonth in interface GregorianDate
      Returns:
      gregorian month in range (1 = January, ..., 12 = December)

    • getDayOfMonth

      public int getDayOfMonth()
      Description copied from interface: GregorianDate

      Yields the day of month.

      Specified by:
      getDayOfMonth in interface GregorianDate
      Returns:
      day of month in range 1 <= dayOfMonth <= 31

    • getDayOfWeek

      public Weekday getDayOfWeek()

      Determines the day of week.

      Returns:
      Weekday
      Since:
      3.13/4.10

    • getDayOfYear

      public int getDayOfYear()

      Yields the day of year.

      Returns:
      int
      Since:
      3.13/4.10

    • lengthOfMonth

      public int lengthOfMonth()

      Calculates the length of associated month in days.

      Returns:
      int in value range 28-31

    • lengthOfYear

      public int lengthOfYear()

      Calculates the length of associated year in days.

      Returns:
      365 or 366 if associated year is a leap year

    • isLeapYear

      public boolean isLeapYear()

      Is the year of this date a leap year?

      Returns:
      boolean

    • isWeekend

      public boolean isWeekend​(Locale country)

      Does this date fall on a week-end in given country?

      Parameters:
      country - country setting with two-letter ISO-3166-code
      Returns:
      true if in given country this date is on weekend else false
      See Also:
      Weekmodel.weekend()

    • isValid

      public static boolean isValid​(int year, int month, int dayOfMonth)

      Queries if given parameter values form a well defined calendar date.

      This method only checks the range limits, not if the date is historically correct.

      Parameters:
      year - the proleptic year to be checked
      month - the month to be checked
      dayOfMonth - the day of month to be checked
      Returns:
      true if valid else false
      Since:
      3.34/4.29
      See Also:
      of(int, int, int)

    • plus

      public PlainDate plus​(long amount, CalendarUnit unit)

      Adds given amount in units to this date and yields the result of addition.

      Covers the most important units and is overloaded for performance reasons.

      Parameters:
      amount - the amount of units to be added to this date (maybe negative)
      unit - the unit to be used in addition
      Returns:
      result of addition as changed copy while this instance remains unaffected
      Throws:
      ArithmeticException - in case of numerical overflow
      Since:
      4.18
      See Also:
      plus(long, IsoDateUnit)

    • minus

      public PlainDate minus​(long amount, CalendarUnit unit)

      Subtracts given amount in units from this date and yields the result of subtraction.

      Covers the most important units and is overloaded for performance reasons.

      Parameters:
      amount - the amount of units to be subtracted from this date (maybe negative)
      unit - the unit to be used in subtraction
      Returns:
      result of subtraction as changed copy while this instance remains unaffected
      Throws:
      ArithmeticException - in case of numerical overflow
      Since:
      4.18
      See Also:
      minus(long, IsoDateUnit)

    • print

      public String print​(TemporalFormatter<PlainDate> printer)

      Creates a formatted output of this instance.

      Parameters:
      printer - helps to format this instance
      Returns:
      formatted string
      Since:
      5.0

    • parse

      public static PlainDate parse​(String text, TemporalFormatter<PlainDate> parser)

      Parses given text to an instance of this class.

      Parameters:
      text - text to be parsed
      parser - helps to parse given text
      Returns:
      parsed result
      Throws:
      IndexOutOfBoundsException - if the text is empty
      ChronoException - if the text is not parseable
      Since:
      5.0

    • equals

      public boolean equals​(Object obj)
      Description copied from class: Calendrical

      Based on the epoch day number and the calendar system.

      In other words: Two date object are equal if they have the same temporal position on the local timeline and have the same calendrical type. Subclasses which define further state attributes must override this method.

      If an only temporal comparison is required then the method Calendrical.isSimultaneous(CalendarDate) is to be used.

      Overrides:
      equals in class Calendrical<IsoDateUnit,​PlainDate>
      See Also:
      Chronology.getChronoType()

    • hashCode

      public int hashCode()
      Description copied from class: Calendrical

      Based on the epoch day number.

      Overrides:
      hashCode in class Calendrical<IsoDateUnit,​PlainDate>

    • toString

      public String toString()

      Creates a canonical representation of the form "YYYY-MM-DD" as documented in ISO-8601.

      Specified by:
      toString in interface GregorianDate
      Specified by:
      toString in class TimePoint<IsoDateUnit,​PlainDate>
      Returns:
      canonical ISO-8601-formatted string

    • normalize

      public Duration<CalendarUnit> normalize​(TimeSpan<? extends CalendarUnit> timespan)

      Normalized given timespan using years, months and days.

      This normalizer can also convert from days to months. Example: 

        Duration<CalendarUnit> dur = Duration.of(30, CalendarUnit.DAYS);
  Duration<CalendarUnit> result =
      PlainDate.of(2012, 2, 28).normalize(dur);
  System.out.println(result); // output: P1M1D (leap year!)
      Specified by:
      normalize in interface Normalizer<CalendarUnit>
      Parameters:
      timespan - to be normalized
      Returns:
      normalized duration in years, months and days
      See Also:
      Duration.with(Normalizer)

    • toTemporalAccessor

      public LocalDate toTemporalAccessor()
      Description copied from interface: ThreetenAdapter

      Converts this object to a TemporalAccessor.

      Any implementation is required to return a new object with a different concrete type, not this instance.

      Specified by:
      toTemporalAccessor in interface ThreetenAdapter
      Returns:
      converted Threeten-object (always as new object)

    • getFormatPattern

      public String getFormatPattern​(FormatStyle style, Locale locale)
      Description copied from interface: LocalizedPatternSupport

      Defines a CLDR-compatible localized format pattern suitable for printing.

      The default implementation delegates to the underlying chronology.

      Specified by:
      getFormatPattern in interface LocalizedPatternSupport
      Parameters:
      style - format style
      locale - language and country setting
      Returns:
      localized format pattern

    • axis

      public static TimeAxis<IsoDateUnit,​PlainDate> axis()

      Provides a static access to the associated chronology on base of epoch days which contains the chronological rules.

      Returns:
      chronological system as time axis (never null)

    • threeten

      public static Chronology<LocalDate> threeten()

      Obtains a bridge chronology for the type java.time.LocalDate.

      Returns:
      rule engine adapted for the type java.time.LocalDate
      Since:
      5.0
      See Also:
      axis()