Class YearMonth

  • All Implemented Interfaces:
    Serializable, Comparable<YearMonth>, Calendrical, CalendricalMatcher, DateAdjuster

    public final class YearMonth
    extends Object
    implements Calendrical, CalendricalMatcher, DateAdjuster, Comparable<YearMonth>, Serializable
    A year-month in the ISO-8601 calendar system, such as 2007-12.

    YearMonth is an immutable calendrical that represents the combination of a year and month. Any field that can be derived from a year and month, such as quarter-of-year, can be obtained.

    This class does not store or represent a day, time or time-zone. Thus, for example, the value "October 2007" can be stored in a YearMonth.

    The ISO-8601 calendar system is the modern civil calendar system used today in most of the world. It is equivalent to the proleptic Gregorian calendar system, in which todays's rules for leap years are applied for all time. For most applications written today, the ISO-8601 rules are entirely suitable. Any application that uses historical dates should consider using HistoricDate.

    YearMonth is immutable and thread-safe.

    Author:
    Michael Nascimento Santos, Stephen Colebourne
    See Also:
    Serialized Form
    • Method Detail

      • now

        public static YearMonth now()
        Obtains the current year-month from the system clock in the default time-zone.

        This will query the system clock in the default time-zone to obtain the current year-month. The zone and offset will be set based on the time-zone in the clock.

        Using this method will prevent the ability to use an alternate clock for testing because the clock is hard-coded.

        Returns:
        the current year-month using the system clock, never null
      • now

        public static YearMonth now​(Clock clock)
        Obtains the current year-month from the specified clock.

        This will query the specified clock to obtain the current year-month. Using this method allows the use of an alternate clock for testing. The alternate clock may be introduced using dependency injection.

        Parameters:
        clock - the clock to use, not null
        Returns:
        the current year-month, never null
      • of

        public static YearMonth of​(int year,
                                   MonthOfYear monthOfYear)
        Obtains an instance of YearMonth from a year and month.
        Parameters:
        year - the year to represent, from MIN_YEAR to MAX_YEAR
        monthOfYear - the month-of-year to represent, not null
        Returns:
        the year-month, never null
        Throws:
        IllegalCalendarFieldValueException - if the year value is invalid
      • of

        public static YearMonth of​(int year,
                                   int monthOfYear)
        Obtains an instance of YearMonth from a year and month.
        Parameters:
        year - the year to represent, from MIN_YEAR to MAX_YEAR
        monthOfYear - the month-of-year to represent, from 1 (January) to 12 (December)
        Returns:
        the year-month, never null
        Throws:
        IllegalCalendarFieldValueException - if either field value is invalid
      • of

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

        This method will create a year-month from the Calendrical by extracting the year and month-of-year fields.

        Parameters:
        calendrical - the calendrical to use, not null
        Returns:
        the year-month, never null
        Throws:
        UnsupportedRuleException - if either field cannot be found
        InvalidCalendarFieldException - if the value for either field is invalid
      • parse

        public static YearMonth parse​(String text)
        Obtains an instance of YearMonth from a text string such as 2007-12.

        The following formats are accepted in ASCII:

        • {year}-{monthOfYear}
        The year has between 4 and 10 digits with values from MIN_YEAR to MAX_YEAR. If there are more than 4 digits then the year must be prefixed with the plus symbol. Negative years are allowed, but not negative zero.

        The month-of-year has 2 digits and has values from 1 to 12.

        Parameters:
        text - the text to parse such as '2007-12', not null
        Returns:
        the parsed year-month, never null
        Throws:
        CalendricalException - if the text cannot be parsed
      • parse

        public static YearMonth parse​(String text,
                                      DateTimeFormatter formatter)
        Obtains an instance of YearMonth from a text string using a specific formatter.

        The text is parsed using the formatter, returning a year-month.

        Parameters:
        text - the text to parse, not null
        formatter - the formatter to use, not null
        Returns:
        the parsed year-month, never null
        Throws:
        UnsupportedOperationException - if the formatter cannot parse
        CalendricalException - if the text cannot be parsed
      • getChronology

        public ISOChronology getChronology()
        Gets the chronology that this year-month uses, which is the ISO calendar system.
        Returns:
        the ISO chronology, never null
      • get

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

        This method queries the value of the specified calendrical rule. If the value cannot be returned for the rule from this year-month then null will be returned.

        Specified by:
        get in interface Calendrical
        Parameters:
        rule - the rule to use, not null
        Returns:
        the value for the rule, null if the value cannot be returned
      • getYear

        public int getYear()
        Gets the year field.

        This method returns the primitive int value for the year. Additional information about the year can be obtained by creating a Year.

        Returns:
        the year, from MIN_YEAR to MAX_YEAR
      • getMonthOfYear

        public MonthOfYear getMonthOfYear()
        Gets the month-of-year field, which is an enum MonthOfYear.

        This method returns the enum MonthOfYear for the month. This avoids confusion as to what int values mean. If you need access to the primitive int value then the enum provides the int value.

        Additional information can be obtained from the MonthOfYear. This includes month lengths, textual names and access to the quarter-of-year and month-of-quarter values.

        Returns:
        the month-of-year, never null
      • with

        public YearMonth with​(Year year)
        Returns a copy of this YearMonth with the year altered.

        This instance is immutable and unaffected by this method call.

        Parameters:
        year - the year to set in the returned year-month, not null
        Returns:
        a YearMonth based on this year-month with the requested year, never null
      • with

        public YearMonth with​(MonthOfYear monthOfYear)
        Returns a copy of this YearMonth with the month-of-year altered.

        This instance is immutable and unaffected by this method call.

        Parameters:
        monthOfYear - the month-of-year to set in the returned year-month, not null
        Returns:
        a YearMonth based on this year-month with the requested month, never null
      • withYear

        public YearMonth withYear​(int year)
        Returns a copy of this YearMonth with the year altered.

        This instance is immutable and unaffected by this method call.

        Parameters:
        year - the year to set in the returned year-month, from MIN_YEAR to MAX_YEAR
        Returns:
        a YearMonth based on this year-month with the requested year, never null
        Throws:
        IllegalCalendarFieldValueException - if the year value is invalid
      • withMonthOfYear

        public YearMonth withMonthOfYear​(int monthOfYear)
        Returns a copy of this YearMonth with the month-of-year altered.

        This instance is immutable and unaffected by this method call.

        Parameters:
        monthOfYear - the month-of-year to set in the returned year-month, from 1 (January) to 12 (December)
        Returns:
        a YearMonth based on this year-month with the requested month, never null
        Throws:
        IllegalCalendarFieldValueException - if the month-of-year value is invalid
      • plus

        public YearMonth plus​(PeriodProvider periodProvider)
        Returns a copy of this YearMonth with the specified period added.

        This adds the specified period to this year-month, returning a new year-month. Before addition, the period is converted to a Period using Period.of(PeriodProvider). The calculation only uses the years and months fields. Other fields are ignored.

        This instance is immutable and unaffected by this method call.

        Parameters:
        periodProvider - the period to add, not null
        Returns:
        a YearMonth based on this year-month with the period added, never null
        Throws:
        CalendricalException - if the specified period cannot be converted to a Period
        ArithmeticException - if the result exceeds the supported range
      • plusYears

        public YearMonth plusYears​(long years)
        Returns a copy of this YearMonth with the specified period in years added.

        This instance is immutable and unaffected by this method call.

        Parameters:
        years - the years to add, positive or negative
        Returns:
        a YearMonth based on this year-month with the years added, never null
        Throws:
        CalendricalException - if the result exceeds the supported range
      • plusMonths

        public YearMonth plusMonths​(long months)
        Returns a copy of this YearMonth with the specified period in months added.

        This instance is immutable and unaffected by this method call.

        Parameters:
        months - the months to add, positive or negative
        Returns:
        a YearMonth based on this year-month with the months added, never null
        Throws:
        CalendricalException - if the result exceeds the supported range
      • minus

        public YearMonth minus​(PeriodProvider periodProvider)
        Returns a copy of this YearMonth with the specified period subtracted.

        This subtracts the specified period from this year-month, returning a new year-month. Before subtraction, the period is converted to a Period using Period.of(PeriodProvider). The calculation only uses the years and months fields. Other fields are ignored.

        This instance is immutable and unaffected by this method call.

        Parameters:
        periodProvider - the period to subtract, not null
        Returns:
        a YearMonth based on this year-month with the period subtracted, never null
        Throws:
        CalendricalException - if the specified period cannot be converted to a Period
        ArithmeticException - if the result exceeds the supported range
      • minusYears

        public YearMonth minusYears​(long years)
        Returns a copy of this YearMonth with the specified period in years subtracted.

        This instance is immutable and unaffected by this method call.

        Parameters:
        years - the years to subtract, positive or negative
        Returns:
        a YearMonth based on this year-month with the years subtracted, never null
        Throws:
        CalendricalException - if the result exceeds the supported range
      • minusMonths

        public YearMonth minusMonths​(long months)
        Returns a copy of this YearMonth with the specified period in months subtracted.

        This instance is immutable and unaffected by this method call.

        Parameters:
        months - the months to subtract, positive or negative
        Returns:
        a YearMonth based on this year-month with the months subtracted, never null
        Throws:
        CalendricalException - if the result exceeds the supported range
      • rollMonthOfYear

        public YearMonth rollMonthOfYear​(int months)
        Rolls the month-of-year, adding the specified number of months to a copy of this YearMonth.

        This method will add the specified number of months to the month-day, rolling from December back to January if necessary. The year is not altered.

        This instance is immutable and unaffected by this method call.

        Parameters:
        months - the months to roll by, positive or negative
        Returns:
        a YearMonth based on this year-month with the month rolled, never null
      • adjustDate

        public LocalDate adjustDate​(LocalDate date)
        Adjusts a date to have the value of this year-month, returning a new date.

        This method implements the DateAdjuster interface. It is intended that, instead of calling this method directly, it is used from an instance of LocalDate:

           date = date.with(yearMonth);
         

        This implementation handles the case where the day-of-month is invalid for the new month and year using the DateResolvers.previousValid() resolver.

        This instance is immutable and unaffected by this method call.

        Specified by:
        adjustDate in interface DateAdjuster
        Parameters:
        date - the date to be adjusted, not null
        Returns:
        the adjusted date, never null
      • adjustDate

        public LocalDate adjustDate​(LocalDate date,
                                    DateResolver resolver)
        Adjusts a date to have the value of this year-month, using a resolver to handle the case when the day-of-month becomes invalid.

        This instance is immutable and unaffected by this method call.

        Parameters:
        date - the date to be adjusted, not null
        resolver - the date resolver to use if the day-of-month becomes invalid, not null
        Returns:
        the adjusted date, never null
        Throws:
        IllegalCalendarFieldValueException - if the date cannot be resolved using the resolver
      • lengthInDays

        public int lengthInDays()
        Gets the length of this month in days.

        This returns the length in days of the month. The year is used to determine the correct length of February.

        Returns:
        the length of the month in days, from 28 to 31
      • isValidDay

        public boolean isValidDay​(int dayOfMonth)
        Checks if the day-of-month is valid for this year-month.

        This method checks whether this year and month and the input day form a valid date.

        Parameters:
        dayOfMonth - the day-of-month to validate, from 1 to 31, invalid value returns false
        Returns:
        true if the day is valid for this year-month
      • atDay

        public LocalDate atDay​(int dayOfMonth)
        Returns a date formed from this year-month at the specified day-of-month.

        This method merges this and the specified day to form an instance of LocalDate. This method can be used as part of a chain to produce a date:

         LocalDate date = year.atMonth(month).atDay(day);
         

        This instance is immutable and unaffected by this method call.

        Parameters:
        dayOfMonth - the day-of-month to use, from 1 to 31
        Returns:
        the date formed from this year-month and the specified day, never null
        Throws:
        InvalidCalendarFieldException - when the day is invalid for the year-month
        See Also:
        isValidDay(int)
      • compareTo

        public int compareTo​(YearMonth other)
        Compares this year-month to another year-month.
        Specified by:
        compareTo in interface Comparable<YearMonth>
        Parameters:
        other - the other year-month to compare to, not null
        Returns:
        the comparator value, negative if less, positive if greater
        Throws:
        NullPointerException - if other is null
      • isAfter

        public boolean isAfter​(YearMonth other)
        Is this year-month after the specified year-month.
        Parameters:
        other - the other year-month to compare to, not null
        Returns:
        true if this is after the specified year-month
        Throws:
        NullPointerException - if other is null
      • isBefore

        public boolean isBefore​(YearMonth other)
        Is this year-month before the specified year-month.
        Parameters:
        other - the other year-month to compare to, not null
        Returns:
        true if this point is before the specified year-month
        Throws:
        NullPointerException - if other is null
      • equals

        public boolean equals​(Object other)
        Is this year-month equal to the specified year-month.
        Overrides:
        equals in class Object
        Parameters:
        other - the other year-month to compare to, null returns false
        Returns:
        true if this point is equal to the specified year-month
      • hashCode

        public int hashCode()
        A hash code for this year-month.
        Overrides:
        hashCode in class Object
        Returns:
        a suitable hash code
      • toString

        public String toString()
        Outputs this year-month as a String, such as 2007-12.

        The output will be in the format yyyy-MM:

        Overrides:
        toString in class Object
        Returns:
        the formatted year-month, never null
      • rule

        public static CalendricalRule<YearMonth> rule()
        Gets the rule for the year-month.
        Returns:
        the rule for the year-month, never null