Class YearMonth

java.lang.Object
javax.time.calendar.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.

See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    (package private) static final class 
    YearMonth.Rule
    Rule implementation.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private final MonthOfYear
    month
    The month-of-year, not null.
    private static final DateTimeFormatter
    PARSER
    Parser.
    private static final long
    serialVersionUID
    A serialization identifier for this class.
    private final int
    year
    The year.

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    private
    YearMonth(int year, MonthOfYear monthOfYear)
    Constructor.

  • Method Summary

    Modifier and Type
    Method
    Description
    LocalDate
    adjustDate(LocalDate date)
    Adjusts a date to have the value of this year-month, returning a new date.
    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.
    LocalDate
    atDay(int dayOfMonth)
    Returns a date formed from this year-month at the specified day-of-month.
    int
    compareTo(YearMonth other)
    Compares this year-month to another year-month.
    boolean
    equals(Object other)
    Is this year-month equal to the specified year-month.
    <T> T
    get(CalendricalRule<T> rule)
    Gets the value of the specified calendrical rule.
    ISOChronology
    getChronology()
    Gets the chronology that this year-month uses, which is the ISO calendar system.
    MonthOfYear
    getMonthOfYear()
    Gets the month-of-year field, which is an enum MonthOfYear.
    int
    getYear()
    Gets the year field.
    int
    hashCode()
    A hash code for this year-month.
    boolean
    isAfter(YearMonth other)
    Is this year-month after the specified year-month.
    boolean
    isBefore(YearMonth other)
    Is this year-month before the specified year-month.
    boolean
    isValidDay(int dayOfMonth)
    Checks if the day-of-month is valid for this year-month.
    int
    lengthInDays()
    Gets the length of this month in days.
    boolean
    matchesCalendrical(Calendrical calendrical)
    Checks if the year-month extracted from the calendrical matches this.
    YearMonth
    minus(PeriodProvider periodProvider)
    Returns a copy of this YearMonth with the specified period subtracted.
    YearMonth
    minusMonths(long months)
    Returns a copy of this YearMonth with the specified period in months subtracted.
    YearMonth
    minusYears(long years)
    Returns a copy of this YearMonth with the specified period in years subtracted.
    static YearMonth
    now()
    Obtains the current year-month from the system clock in the default time-zone.
    static YearMonth
    now(Clock clock)
    Obtains the current year-month from the specified clock.
    static YearMonth
    of(int year, int monthOfYear)
    Obtains an instance of YearMonth from a year and month.
    static YearMonth
    of(int year, MonthOfYear monthOfYear)
    Obtains an instance of YearMonth from a year and month.
    static YearMonth
    of(Calendrical calendrical)
    Obtains an instance of YearMonth from a Calendrical.
    static YearMonth
    parse(String text)
    Obtains an instance of YearMonth from a text string such as 2007-12.
    static YearMonth
    parse(String text, DateTimeFormatter formatter)
    Obtains an instance of YearMonth from a text string using a specific formatter.
    YearMonth
    plus(PeriodProvider periodProvider)
    Returns a copy of this YearMonth with the specified period added.
    YearMonth
    plusMonths(long months)
    Returns a copy of this YearMonth with the specified period in months added.
    YearMonth
    plusYears(long years)
    Returns a copy of this YearMonth with the specified period in years added.
    YearMonth
    rollMonthOfYear(int months)
    Rolls the month-of-year, adding the specified number of months to a copy of this YearMonth.
    static CalendricalRule<YearMonth>
    rule()
    Gets the rule for the year-month.
    String
    toString()
    Outputs this year-month as a String, such as 2007-12.
    String
    toString(DateTimeFormatter formatter)
    Outputs this year-month as a String using the formatter.
    private YearMonth
    with(int newYear, MonthOfYear newMonth)
    Returns a copy of this year-month with the new year and month, checking to see if a new object is in fact required.
    YearMonth
    with(MonthOfYear monthOfYear)
    Returns a copy of this YearMonth with the month-of-year altered.
    YearMonth
    with(Year year)
    Returns a copy of this YearMonth with the year altered.
    YearMonth
    withMonthOfYear(int monthOfYear)
    Returns a copy of this YearMonth with the month-of-year altered.
    YearMonth
    withYear(int year)
    Returns a copy of this YearMonth with the year altered.

    Methods inherited from class Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Field Details

    • serialVersionUID

      private static final long serialVersionUID
      A serialization identifier for this class.
      See Also:

    • PARSER

      private static final DateTimeFormatter PARSER
      Parser.

    • year

      private final int year
      The year.

    • month

      private final MonthOfYear month
      The month-of-year, not null.

  • Constructor Details

    • YearMonth

      private YearMonth(int year, MonthOfYear monthOfYear)
      Constructor.
      Parameters:
      year - the year to represent, validated from MIN_YEAR to MAX_YEAR
      monthOfYear - the month-of-year to represent, not null

  • Method Details

    • 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

    • with

      private YearMonth with(int newYear, MonthOfYear newMonth)
      Returns a copy of this year-month with the new year and month, checking to see if a new object is in fact required.
      Parameters:
      newYear - the year to represent, validated from MIN_YEAR to MAX_YEAR
      newMonth - the month-of-year to represent, validated not null
      Returns:
      the year-month, never null

    • 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

    • matchesCalendrical

      public boolean matchesCalendrical(Calendrical calendrical)
      Checks if the year-month extracted from the calendrical matches this.

      This method implements the CalendricalMatcher interface. It is intended that applications use LocalDate.matches(CalendricalMatcher) rather than this method.

      Specified by:
      matchesCalendrical in interface CalendricalMatcher
      Parameters:
      calendrical - the calendrical to match, not null
      Returns:
      true if the calendrical matches, false otherwise

    • 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:

    • 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

    • toString

      public String toString(DateTimeFormatter formatter)
      Outputs this year-month as a String using the formatter.
      Parameters:
      formatter - the formatter to use, not null
      Returns:
      the formatted year-month string, never null
      Throws:
      UnsupportedOperationException - if the formatter cannot print
      CalendricalPrintException - if an error occurs during printing

    • rule

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