PlainDate (Time4J-Core 2.0 API)

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>, GregorianDate, ChronoDisplay, Normalizer<CalendarUnit>, Temporal<Calendrical<?,?>>
```
@CalendarType(value="iso8601")
public final class PlainDate
extends Calendrical<IsoDateUnit,PlainDate>
implements GregorianDate, Normalizer<CalendarUnit>
```
Represents a plain calendar date in conformance to ISO-8601-standard.

The value range also contains negative years down to -999999999. These years cannot be interpreted in a historical 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-historical mathematical abstraction).

Following elements which are declared as constants are registered by this class:
Furthermore, all elements of class Weekmodel and class EpochDays are supported.
Author:

Meno Hochschild

See Also:
Serialized Form

Field Summary

Fields
Modifier and Type	Field and Description
`static CalendarDateElement`	`COMPONENT` Element with the calendar date in the value range `[-999999999-01-01]` until `[+999999999-12-31]`.
`static ProportionalElement<Integer,PlainDate>`	`DAY_OF_MONTH` Element with the day of month in the value range `1-28/29/30/31`.
`static ProportionalElement<Integer,PlainDate>`	`DAY_OF_QUARTER` Element with the day within a quarter of year in the value range `1-90/91/92`.
`static NavigableElement<Weekday>`	`DAY_OF_WEEK` Element with the day of week in the value range `MONDAY-SUNDAY`.
`static ProportionalElement<Integer,PlainDate>`	`DAY_OF_YEAR` Element with the day of year in the value range `1-365/366`).
`static ProportionalElement<Integer,PlainDate>`	`MONTH_AS_NUMBER` Element with the calendar month in numerical form and the value range `1-12`.
`static NavigableElement<Month>`	`MONTH_OF_YEAR` Element with the calendar month as enum in the value range `JANUARY-DECEMBER`).
`static NavigableElement<Quarter>`	`QUARTER_OF_YEAR` Element with the quarter of year in the value range `Q1-Q4`.
`static OrdinalWeekdayElement`	`WEEKDAY_IN_MONTH` Element with the ordinal day-of-week within given calendar month in the value range `1-5`.
`static AdjustableElement<Integer,PlainDate>`	`YEAR` Element with the proleptic iso-year without any era reference and the value range `-999999999` until `999999999`.
`static AdjustableElement<Integer,PlainDate>`	`YEAR_OF_WEEKDATE` Defines an element for the week-based year in an ISO-8601-weekdate.

Method Summary

Methods
Modifier and Type	Method and Description
`PlainTimestamp`	`at(PlainTime time)` Creates a new local timestamp with this date and given wall time.
`PlainTimestamp`	`atStartOfDay()` Creates a new local timestamp with this date at midnight at the begin of associated day.
`PlainTimestamp`	`atTime(int hour, int minute)` Is equivalent to `at(PlainTime.of(hour, minute))`.
`PlainTimestamp`	`atTime(int hour, int minute, int second)` Is equivalent to `at(PlainTime.of(hour, minute, second))`.
`static TimeAxis<IsoDateUnit,PlainDate>`	`axis()` Provides a static access to the associated chronology on base of epoch days which contains the chronological rules.
`static ChronoFormatter<PlainDate>`	`formatter(DisplayMode mode, Locale locale)` Creates a new formatter which uses the given display mode and locale for formatting and parsing plain dates.
`static ChronoFormatter<PlainDate>`	`formatter(String formatPattern, ChronoPattern patternType, Locale locale)` Creates a new formatter which uses the given pattern and locale for formatting and parsing plain dates.
`static PlainDate`	`from(GregorianDate date)` Common conversion method for proleptic gregorian dates.
`int`	`getDayOfMonth()` Yields the day of month.
`int`	`getMonth()` Yields the gregorian month as integer.
`int`	`getYear()` Yields the proleptic year according to ISO-8601.
`boolean`	`isLeapYear()` Is the year of this date a leap year?
`boolean`	`isWeekend(Locale country)` Does this date fall on a week-end in given country?
`int`	`lengthOfMonth()` Calculates the length of associated month in days.
`int`	`lengthOfYear()` Calculates the length of associated year in days.
`static ChronoFormatter<PlainDate>`	`localFormatter(DisplayMode mode)` Creates a new formatter which uses the given display mode in the default locale for formatting and parsing plain dates.
`static ChronoFormatter<PlainDate>`	`localFormatter(String formatPattern, ChronoPattern patternType)` Creates a new formatter which uses the given pattern in the default locale for formatting and parsing plain dates.
`Duration<CalendarUnit>`	`normalize(TimeSpan<? extends CalendarUnit> timespan)` Normalized given timespan using years, months and days.
`static PlainDate`	`of(int year, int dayOfYear)` Creates a new ordinal date conforming to ISO-8601.
`static PlainDate`	`of(int year, int month, int dayOfMonth)` Creates a new calendar date conforming to ISO-8601.
`static PlainDate`	`of(int yearOfWeekdate, int weekOfYear, Weekday dayOfWeek)` Creates a new week-date conforming to ISO-8601.
`static PlainDate`	`of(int year, Month month, int dayOfMonth)` Creates a new calendar date conforming to ISO-8601.
`static PlainDate`	`of(long amount, EpochDays epoch)` Creates a new date based on count of days since given epoch.
`String`	`toString()` Creates a canonical representation of the form "YYYY-MM-DD" as documented in ISO-8601.

Methods inherited from class net.time4j.engine.Calendrical
compareTo, equals, getStartOfDay, hashCode, isAfter, isBefore, isSimultaneous, transform

Methods inherited from class net.time4j.engine.TimePoint
max, min, minus, minus, plus, plus, until, until

Methods inherited from class net.time4j.engine.ChronoEntity
contains, get, get, getMaximum, getMinimum, getTimezone, hasTimezone, isValid, isValid, isValid, matches, with, with, with, with

Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait

- Field Detail
  - 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)); // Ausgabe: 2012

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

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

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

  date = date.with(YEAR.atFloor()); // erster Tag des Jahres
  System.out.println(date); // Ausgabe: 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 historical 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",
                    standalone="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",
                    standalone="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
```
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); // Ausgabe: 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 Detail
  - 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.
    
    Returns:
    found calendar date based on given epoch days
    
    Throws:
    
    IllegalArgumentException - if first argument is out of range
  - from
```
public static PlainDate from(GregorianDate date)
```
    Common conversion method for proleptic gregorian dates.
    
    Parameters:
    date - ISO-date
    
    Returns:
    PlainDate
  - 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)
  - 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
  - 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()
  - localFormatter
```
public static ChronoFormatter<PlainDate> localFormatter(String formatPattern,
                                        ChronoPattern patternType)
```
    Creates a new formatter which uses the given pattern in the default locale for formatting and parsing plain dates.
    
    Note: The formatter can be adjusted to other locales however.
    
    Parameters:
    formatPattern - format definition as pattern
    patternType - pattern dialect
    
    Returns:
    format object for formatting PlainDate-objects using system locale
    
    Throws:
    
    IllegalArgumentException - if resolving of pattern fails
    See Also:
    PatternType, ChronoFormatter.with(Locale)
  - localFormatter
```
public static ChronoFormatter<PlainDate> localFormatter(DisplayMode mode)
```
    Creates a new formatter which uses the given display mode in the default locale for formatting and parsing plain dates.
    
    Note: The formatter can be adjusted to other locales however.
    
    Parameters:
    mode - formatting style
    
    Returns:
    format object for formatting PlainDate-objects using system locale
    
    Throws:
    
    IllegalStateException - if format pattern cannot be retrieved
    See Also:
    ChronoFormatter.with(Locale)
  - formatter
```
public static ChronoFormatter<PlainDate> formatter(String formatPattern,
                                   ChronoPattern patternType,
                                   Locale locale)
```
    Creates a new formatter which uses the given pattern and locale for formatting and parsing plain dates.
    
    Note: The formatter can be adjusted to other locales however.
    
    Parameters:
    formatPattern - format definition as pattern
    patternType - pattern dialect
    locale - locale setting
    
    Returns:
    format object for formatting PlainDate-objects using given locale
    
    Throws:
    
    IllegalArgumentException - if resolving of pattern fails
    See Also:
    PatternType, localFormatter(String,ChronoPattern)
  - formatter
```
public static ChronoFormatter<PlainDate> formatter(DisplayMode mode,
                                   Locale locale)
```
    Creates a new formatter which uses the given display mode and locale for formatting and parsing plain dates.
    
    Note: The formatter can be adjusted to other locales however.
    
    Parameters:
    mode - formatting style
    locale - locale setting
    
    Returns:
    format object for formatting PlainDate-objects using given locale
    
    Throws:
    
    IllegalStateException - if format pattern cannot be retrieved
    See Also:
    localFormatter(DisplayMode)
  - 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)
  - 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)

Class PlainDate

Field Summary

Method Summary

Methods inherited from class net.time4j.engine.Calendrical

Methods inherited from class net.time4j.engine.TimePoint

Methods inherited from class net.time4j.engine.ChronoEntity

Methods inherited from class java.lang.Object

Field Detail

COMPONENT

YEAR

YEAR_OF_WEEKDATE

QUARTER_OF_YEAR

MONTH_OF_YEAR

MONTH_AS_NUMBER

DAY_OF_MONTH

DAY_OF_WEEK

DAY_OF_YEAR

DAY_OF_QUARTER

WEEKDAY_IN_MONTH

Method Detail

of

of

of

of

of

from

atStartOfDay

at

atTime

atTime

getYear

getMonth

getDayOfMonth

lengthOfMonth

lengthOfYear

isLeapYear

isWeekend

localFormatter

localFormatter

formatter

formatter

toString

normalize

axis