Class YearMonth
- All Implemented Interfaces:
Serializable
,Comparable<YearMonth>
,Calendrical
,CalendricalMatcher
,DateAdjuster
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 ClassesModifier and TypeClassDescription(package private) static final class
Rule implementation. -
Field Summary
FieldsModifier and TypeFieldDescriptionprivate final MonthOfYear
The month-of-year, not null.private static final DateTimeFormatter
Parser.private static final long
A serialization identifier for this class.private final int
The year. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionadjustDate
(LocalDate date) Adjusts a date to have the value of this year-month, returning a new date.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.atDay
(int dayOfMonth) Returns a date formed from this year-month at the specified day-of-month.int
Compares this year-month to another year-month.boolean
Is this year-month equal to the specified year-month.<T> T
get
(CalendricalRule<T> rule) Gets the value of the specified calendrical rule.Gets the chronology that this year-month uses, which is the ISO calendar system.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
Is this year-month after the specified year-month.boolean
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
Gets the length of this month in days.boolean
matchesCalendrical
(Calendrical calendrical) Checks if the year-month extracted from the calendrical matches this.minus
(PeriodProvider periodProvider) Returns a copy of thisYearMonth
with the specified period subtracted.minusMonths
(long months) Returns a copy of this YearMonth with the specified period in months subtracted.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
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
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.plus
(PeriodProvider periodProvider) Returns a copy of thisYearMonth
with the specified period added.plusMonths
(long months) Returns a copy of this YearMonth with the specified period in months added.plusYears
(long years) Returns a copy of this YearMonth with the specified period in years added.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.toString()
Outputs this year-month as aString
, such as2007-12
.toString
(DateTimeFormatter formatter) Outputs this year-month as aString
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.with
(MonthOfYear monthOfYear) Returns a copy of this YearMonth with the month-of-year altered.Returns a copy of this YearMonth with the year altered.withMonthOfYear
(int monthOfYear) Returns a copy of thisYearMonth
with the month-of-year altered.withYear
(int year) Returns a copy of thisYearMonth
with the year altered.
-
Field Details
-
serialVersionUID
private static final long serialVersionUIDA serialization identifier for this class.- See Also:
-
PARSER
Parser. -
year
private final int yearThe year. -
month
The month-of-year, not null.
-
-
Constructor Details
-
YearMonth
Constructor.- Parameters:
year
- the year to represent, validated from MIN_YEAR to MAX_YEARmonthOfYear
- the month-of-year to represent, not null
-
-
Method Details
-
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
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
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
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
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
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
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
-
with
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_YEARnewMonth
- the month-of-year to represent, validated not null- Returns:
- the year-month, never null
-
getChronology
Gets the chronology that this year-month uses, which is the ISO calendar system.- Returns:
- the ISO chronology, never null
-
get
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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:
-
compareTo
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
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
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
Is this year-month equal to the specified year-month. -
hashCode
public int hashCode()A hash code for this year-month. -
toString
Outputs this year-month as aString
, such as2007-12
.The output will be in the format
yyyy-MM
: -
toString
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
Gets the rule for the year-month.- Returns:
- the rule for the year-month, never null
-