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 as2007-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 Summary
All Methods Static Methods Instance Methods Concrete Methods 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 enumMonthOfYear
.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 thisYearMonth
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 ofYearMonth
from a year and month.static YearMonth
of(int year, MonthOfYear monthOfYear)
Obtains an instance ofYearMonth
from a year and month.static YearMonth
of(Calendrical calendrical)
Obtains an instance ofYearMonth
from a Calendrical.static YearMonth
parse(String text)
Obtains an instance ofYearMonth
from a text string such as2007-12
.static YearMonth
parse(String text, DateTimeFormatter formatter)
Obtains an instance ofYearMonth
from a text string using a specific formatter.YearMonth
plus(PeriodProvider periodProvider)
Returns a copy of thisYearMonth
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 thisYearMonth
.static CalendricalRule<YearMonth>
rule()
Gets the rule for the year-month.String
toString()
Outputs this year-month as aString
, such as2007-12
.String
toString(DateTimeFormatter formatter)
Outputs this year-month as aString
using the formatter.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 thisYearMonth
with the month-of-year altered.YearMonth
withYear(int year)
Returns a copy of thisYearMonth
with the year altered.
-
-
-
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 ofYearMonth
from a year and month.- Parameters:
year
- the year to represent, from MIN_YEAR to MAX_YEARmonthOfYear
- 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 ofYearMonth
from a year and month.- Parameters:
year
- the year to represent, from MIN_YEAR to MAX_YEARmonthOfYear
- 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 ofYearMonth
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 foundInvalidCalendarFieldException
- if the value for either field is invalid
-
parse
public static YearMonth parse(String text)
Obtains an instance ofYearMonth
from a text string such as2007-12
.The following formats are accepted in ASCII:
- {year}-{monthOfYear}
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 ofYearMonth
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 nullformatter
- the formatter to use, not null- Returns:
- the parsed year-month, never null
- Throws:
UnsupportedOperationException
- if the formatter cannot parseCalendricalException
- 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 interfaceCalendrical
- 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 aYear
.- Returns:
- the year, from MIN_YEAR to MAX_YEAR
-
getMonthOfYear
public MonthOfYear getMonthOfYear()
Gets the month-of-year field, which is an enumMonthOfYear
.This method returns the enum
MonthOfYear
for the month. This avoids confusion as to whatint
values mean. If you need access to the primitiveint
value then the enum provides theint 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 thisYearMonth
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 thisYearMonth
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 thisYearMonth
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
usingPeriod.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 aPeriod
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 thisYearMonth
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
usingPeriod.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 aPeriod
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 thisYearMonth
.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 useLocalDate.matches(javax.time.calendar.CalendricalMatcher)
rather than this method.- Specified by:
matchesCalendrical
in interfaceCalendricalMatcher
- 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 ofLocalDate
: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 interfaceDateAdjuster
- 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 nullresolver
- 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 ofLocalDate
. 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 interfaceComparable<YearMonth>
- Parameters:
other
- the other year-month to compare to, not null- Returns:
- the comparator value, negative if less, positive if greater
- Throws:
NullPointerException
- ifother
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
- ifother
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
- ifother
is null
-
equals
public boolean equals(Object other)
Is this year-month equal to the specified year-month.
-
hashCode
public int hashCode()
A hash code for this year-month.
-
toString
public String toString()
Outputs this year-month as aString
, such as2007-12
.The output will be in the format
yyyy-MM
:
-
toString
public String toString(DateTimeFormatter formatter)
Outputs this year-month as aString
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 printCalendricalPrintException
- 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
-
-