Class HistoricDate

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Comparable<HistoricDate>, Calendrical, DateProvider

    public final class HistoricDate
    extends java.lang.Object
    implements DateProvider, Calendrical, java.lang.Comparable<HistoricDate>, java.io.Serializable
    A date in the Historic calendar system.

    HistoricDate is an immutable class that represents a date in the Historic calendar system. The rules of the calendar system are described in HistoricChronology. The date has a precision of one day and a range within the era from year 1 to year 999,999,999 (inclusive).

    Instances of this class may be created from any other object that implements DateProvider including LocalDate. Similarly, instances of this class may be passed into the factory method of any other implementation of DateProvider.

    HistoricDate is immutable and thread-safe.

    See Also:
    Serialized Form
    • Field Detail

      • STANDARD_CUTOVER

        public static final LocalDate STANDARD_CUTOVER
        The standard cutover date between the Julian and Gregorian calendar system of 1582-10-15.
      • MAX_YEAR

        public static final int MAX_YEAR
        The maximum valid year of era. This is currently set to 999,999,999 but may be changed to increase the valid range in a future version of the specification.
        See Also:
        Constant Field Values
      • serialVersionUID

        private static final long serialVersionUID
        A serialization identifier for this class.
        See Also:
        Constant Field Values
      • chrono

        private final HistoricChronology chrono
        The cutover between the Julian and Gregorian calendar systems.
      • year

        private final transient int year
        The historic year.
      • month

        private final transient MonthOfYear month
        The historic month.
      • day

        private final transient int day
        The historic day-of-month.
    • Constructor Detail

      • HistoricDate

        HistoricDate​(HistoricChronology chrono,
                     int year,
                     MonthOfYear month,
                     int day)
        Constructs an instance with the specified date.
        Parameters:
        chono - the chronology, not null
        year - the year to represent, valid
        month - the month-of-year to represent, not null
        day - the day-of-month to represent, valid
    • Method Detail

      • of

        public static HistoricDate of​(int historicYear,
                                      MonthOfYear monthOfYear,
                                      int dayOfMonth)
        Obtains an instance of LocalDate from a year, month and day using the standard cutover of 1582-10-15.

        The day must be valid for the year and month or an exception will be thrown.

        Parameters:
        historicYear - the year to represent, from -(MAX_YEAR-1) to MAX_YEAR
        monthOfYear - the month-of-year to represent, not null
        dayOfMonth - the day-of-month to represent, from 1 to 31
        Returns:
        the local date, never null
        Throws:
        IllegalCalendarFieldValueException - if the value of any field is out of range
        InvalidCalendarFieldException - if the day-of-month is invalid for the month-year
      • of

        public static HistoricDate of​(LocalDate cutover,
                                      int historicYear,
                                      MonthOfYear monthOfYear,
                                      int dayOfMonth)
        Obtains an instance of LocalDate from a year, month and day specifying the cutover date to use.

        The day must be valid for the year and month or an exception will be thrown.

        Parameters:
        historicYear - the year to represent, from -(MAX_YEAR-1) to MAX_YEAR
        monthOfYear - the month-of-year to represent, not null
        dayOfMonth - the day-of-month to represent, from 1 to 31
        Returns:
        the local date, never null
        Throws:
        IllegalCalendarFieldValueException - if the value of any field is out of range
        InvalidCalendarFieldException - if the day-of-month is invalid for the month-year
      • of

        public static HistoricDate of​(Calendrical calendrical)
        Obtains an instance of HistoricDate from a calendrical.

        This can be used extract the date directly from any implementation of Calendrical, including those in other calendar systems.

        Parameters:
        calendrical - the calendrical to extract from, not null
        Returns:
        the Historic date, never null
        Throws:
        UnsupportedRuleException - if the day-of-week cannot be obtained
      • previousValid

        private HistoricDate previousValid​(int historicYear,
                                           MonthOfYear monthOfYear,
                                           int dayOfMonth)
        Obtains an instance of HistoricDate using the previous valid algorithm.
        Parameters:
        historicYear - the year to represent
        monthOfYear - the month-of-year to represent, not null
        dayOfMonth - the day-of-month to represent, from 1 to 31
        Returns:
        the historic date, never null
      • getChronology

        public HistoricChronology getChronology()
        Gets the chronology that this date uses, which is the historic calendar system.
        Returns:
        the historic chronology, never null
      • get

        public <T> T get​(CalendricalRule<T> rule)
        Gets the value of the specified calendar field.

        This method queries the value of the specified calendar field. If the calendar field is not supported then an exception is thrown.

        Specified by:
        get in interface Calendrical
        Parameters:
        rule - the field to query, not null
        Returns:
        the value for the field
        Throws:
        UnsupportedRuleException - if no value for the field is found
      • getEra

        public HistoricEra getEra()
        Gets the historic era.

        The era provides a context for the year-of-era. This calendar system defines two eras, BCE and CE.

        Returns:
        the era, never null
      • getYearOfEra

        public int getYearOfEra()
        Gets the historic year-of-era value.

        The year-of-era is a value that matches the historic definition. Thus, both 1 AD and 1 BCE are represented as year-of-era 1.

        Returns:
        the year, from 1 to MAX_YEAR
      • getYear

        public int getYear()
        Gets the historic year value, which can be negative.

        The year is value that is continuous. Thus, 1 AD is represented as year 1, and 1 BCE is represented as year 0.

        Returns:
        the year, from -(MAX_YEAR-1) to MAX_YEAR
      • getMonthOfYear

        public MonthOfYear getMonthOfYear()
        Gets the historic month-of-year value.
        Returns:
        the month-of-year, never null
      • getDayOfMonth

        public int getDayOfMonth()
        Gets the historic day-of-month value.
        Returns:
        the day-of-month, from 1 to 30
      • getDayOfYear

        public int getDayOfYear()
        Gets the historic day-of-year value.
        Returns:
        the day-of-year, from 1 to 366
      • getDayOfWeek

        public DayOfWeek getDayOfWeek()
        Gets the historic day-of-week.
        Returns:
        the day-of-week, never null
      • isLeapYear

        public boolean isLeapYear()
        Checks if the date represented is a leap year.
        Returns:
        true if this date is in a leap year
      • withYear

        public HistoricDate withYear​(int historicYear)
        Returns a copy of this date with the year value altered.

        The result of setting the year may leave the day-of-month invalid. To avoid this, the day-of-month is changed to the largest valid value.

        This instance is immutable and unaffected by this method call.

        Parameters:
        historicYear - the year to represent, from MIN_YEAR to MAX_YEAR
        Returns:
        a HistoricDate based on this date with the specified year, never null
        Throws:
        IllegalCalendarFieldValueException - if the year is out of range
      • withMonthOfYear

        public HistoricDate withMonthOfYear​(MonthOfYear monthOfYear)
        Returns a copy of this date with the month-of-year value altered.

        The result of setting the month may leave the day-of-month invalid. To avoid this, the day-of-month is changed to the largest valid value.

        This instance is immutable and unaffected by this method call.

        Parameters:
        monthOfYear - the month-of-year to represent, from 1 to 12
        Returns:
        a HistoricDate based on this date with the specified month, never null
      • withDayOfMonth

        public HistoricDate withDayOfMonth​(int dayOfMonth)
        Returns a copy of this date with the day-of-month value altered.

        The specified day-of-month must be valid for the month and year.

        This instance is immutable and unaffected by this method call.

        Parameters:
        dayOfMonth - the day-of-month to represent, from 1 to 31
        Returns:
        a HistoricDate based on this date with the specified day, never null
        Throws:
        IllegalCalendarFieldValueException - if the day is out of range
        InvalidCalendarFieldException - if the day-of-month is invalid for the year and month
      • withDayOfYear

        public HistoricDate withDayOfYear​(int dayOfYear)
        Returns a copy of this date with the day-of-year value altered.

        This instance is immutable and unaffected by this method call.

        Parameters:
        dayOfYear - the day-of-year to represent, from 1 to 366
        Returns:
        a HistoricDate based on this date with the specified day, never null
        Throws:
        IllegalCalendarFieldValueException - if the day-of-year is out of range
        InvalidCalendarFieldException - if the day-of-year is invalid for the year
      • plusYears

        public HistoricDate plusYears​(int years)
        Returns a copy of this date with the specified number of years added.

        The result of changing the year may leave the day-of-month invalid. To avoid this, the day-of-month is changed to the largest valid value.

        This instance is immutable and unaffected by this method call.

        Parameters:
        years - the years to add, positive or negative
        Returns:
        a HistoricDate based on this date with the specified years added, never null
        Throws:
        IllegalCalendarFieldValueException - if the year range is exceeded
      • plusMonths

        public HistoricDate plusMonths​(int months)
        Returns a copy of this date with the specified number of months added.

        The result of changing the month may leave the day-of-month invalid. To avoid this, the day-of-month is changed to the largest valid value.

        This instance is immutable and unaffected by this method call.

        Parameters:
        months - the months to add, positive or negative
        Returns:
        a HistoricDate based on this date with the specified months added, never null
        Throws:
        IllegalCalendarFieldValueException - if the year range is exceeded
      • plusDays

        public HistoricDate plusDays​(int days)
        Returns a copy of this date with the specified number of days added.

        This instance is immutable and unaffected by this method call.

        Parameters:
        days - the days to add, positive or negative
        Returns:
        a HistoricDate based on this date with the specified days added, never null
        Throws:
        IllegalCalendarFieldValueException - if the year range is exceeded
      • toLocalDate

        public LocalDate toLocalDate()
        Converts this date to an ISO-8601 calendar system LocalDate.
        Specified by:
        toLocalDate in interface DateProvider
        Returns:
        the equivalent date in the ISO-8601 calendar system, never null
      • compareTo

        public int compareTo​(HistoricDate otherDate)
        Compares this date to the specified date.

        The comparison is based on the year, month, day and cutover date.

        Specified by:
        compareTo in interface java.lang.Comparable<HistoricDate>
        Parameters:
        otherDate - the other date instance to compare to, not null
        Returns:
        the comparator value, negative if less, positive if greater
      • isAfter

        public boolean isAfter​(HistoricDate otherDate)
        Checks is this date is after the specified date.

        The comparison is based on the year, month, day and cutover date.

        Parameters:
        otherDate - the other date instance to compare to, not null
        Returns:
        true if this day is after the specified day
      • isBefore

        public boolean isBefore​(HistoricDate otherDate)
        Checks is this date is before the specified date.

        The comparison is based on the year, month, day and cutover date.

        Parameters:
        otherDate - the other date instance to compare to, not null
        Returns:
        true if this day is before the specified day
      • equals

        public boolean equals​(java.lang.Object otherDate)
        Checks is this date is equal to the specified date.

        The comparison is based on the year, month, day and cutover date.

        Overrides:
        equals in class java.lang.Object
        Parameters:
        otherDate - the other date instance to compare to, null returns false
        Returns:
        true if this day is equal to the specified day
      • hashCode

        public int hashCode()
        A hash code for this date.
        Overrides:
        hashCode in class java.lang.Object
        Returns:
        a suitable hash code
      • toString

        public java.lang.String toString()
        Outputs the date as a String, such as '1723-13-01 (Historic 2010-10-15)'.

        The output will be in the format 'yyyy-MM-dd (Historic 2010-10-15)' where 2010-10-15 is the cutover date.

        Overrides:
        toString in class java.lang.Object
        Returns:
        the formatted date string, never null
      • rule

        public static CalendricalRule<HistoricDate> rule()
        Gets the field rule for HistoricDate.
        Returns:
        the field rule for the date, never null