public final class YearMonth extends Object implements Calendrical, CalendricalMatcher, DateAdjuster, Comparable<YearMonth>, Serializable
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.
Modifier and Type | Method and 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(Calendrical calendrical)
Obtains an instance of
YearMonth from a Calendrical. |
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 |
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. |
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. |
public static YearMonth now()
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.
public static YearMonth now(Clock 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
.
clock
- the clock to use, not nullpublic static YearMonth of(int year, MonthOfYear monthOfYear)
YearMonth
from a year and month.year
- the year to represent, from MIN_YEAR to MAX_YEARmonthOfYear
- the month-of-year to represent, not nullIllegalCalendarFieldValueException
- if the year value is invalidpublic static YearMonth of(int year, int monthOfYear)
YearMonth
from a year and month.year
- the year to represent, from MIN_YEAR to MAX_YEARmonthOfYear
- the month-of-year to represent, from 1 (January) to 12 (December)IllegalCalendarFieldValueException
- if either field value is invalidpublic static YearMonth of(Calendrical calendrical)
YearMonth
from a Calendrical.
This method will create a year-month from the Calendrical by extracting the year and month-of-year fields.
calendrical
- the calendrical to use, not nullUnsupportedRuleException
- if either field cannot be foundInvalidCalendarFieldException
- if the value for either field is invalidpublic static YearMonth parse(String text)
YearMonth
from a text string such as 2007-12
.
The following formats are accepted in ASCII:
The month-of-year has 2 digits and has values from 1 to 12.
text
- the text to parse such as '2007-12', not nullCalendricalException
- if the text cannot be parsedpublic static YearMonth parse(String text, DateTimeFormatter formatter)
YearMonth
from a text string using a specific formatter.
The text is parsed using the formatter, returning a year-month.
text
- the text to parse, not nullformatter
- the formatter to use, not nullUnsupportedOperationException
- if the formatter cannot parseCalendricalException
- if the text cannot be parsedpublic ISOChronology getChronology()
public <T> T get(CalendricalRule<T> 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.
get
in interface Calendrical
rule
- the rule to use, not nullpublic int getYear()
This method returns the primitive int
value for the year.
Additional information about the year can be obtained by creating a Year
.
public MonthOfYear getMonthOfYear()
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.
public YearMonth with(Year year)
This instance is immutable and unaffected by this method call.
year
- the year to set in the returned year-month, not nullYearMonth
based on this year-month with the requested year, never nullpublic YearMonth with(MonthOfYear monthOfYear)
This instance is immutable and unaffected by this method call.
monthOfYear
- the month-of-year to set in the returned year-month, not nullYearMonth
based on this year-month with the requested month, never nullpublic YearMonth withYear(int year)
YearMonth
with the year altered.
This instance is immutable and unaffected by this method call.
year
- the year to set in the returned year-month, from MIN_YEAR to MAX_YEARYearMonth
based on this year-month with the requested year, never nullIllegalCalendarFieldValueException
- if the year value is invalidpublic YearMonth withMonthOfYear(int monthOfYear)
YearMonth
with the month-of-year altered.
This instance is immutable and unaffected by this method call.
monthOfYear
- the month-of-year to set in the returned year-month, from 1 (January) to 12 (December)YearMonth
based on this year-month with the requested month, never nullIllegalCalendarFieldValueException
- if the month-of-year value is invalidpublic YearMonth plus(PeriodProvider periodProvider)
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.
periodProvider
- the period to add, not nullYearMonth
based on this year-month with the period added, never nullCalendricalException
- if the specified period cannot be converted to a Period
ArithmeticException
- if the result exceeds the supported rangepublic YearMonth plusYears(long years)
This instance is immutable and unaffected by this method call.
years
- the years to add, positive or negativeYearMonth
based on this year-month with the years added, never nullCalendricalException
- if the result exceeds the supported rangepublic YearMonth plusMonths(long months)
This instance is immutable and unaffected by this method call.
months
- the months to add, positive or negativeYearMonth
based on this year-month with the months added, never nullCalendricalException
- if the result exceeds the supported rangepublic YearMonth minus(PeriodProvider periodProvider)
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.
periodProvider
- the period to subtract, not nullYearMonth
based on this year-month with the period subtracted, never nullCalendricalException
- if the specified period cannot be converted to a Period
ArithmeticException
- if the result exceeds the supported rangepublic YearMonth minusYears(long years)
This instance is immutable and unaffected by this method call.
years
- the years to subtract, positive or negativeYearMonth
based on this year-month with the years subtracted, never nullCalendricalException
- if the result exceeds the supported rangepublic YearMonth minusMonths(long months)
This instance is immutable and unaffected by this method call.
months
- the months to subtract, positive or negativeYearMonth
based on this year-month with the months subtracted, never nullCalendricalException
- if the result exceeds the supported rangepublic YearMonth rollMonthOfYear(int months)
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.
months
- the months to roll by, positive or negativeYearMonth
based on this year-month with the month rolled, never nullpublic boolean matchesCalendrical(Calendrical calendrical)
This method implements the CalendricalMatcher
interface.
It is intended that applications use LocalDate.matches(javax.time.calendar.CalendricalMatcher)
rather than this method.
matchesCalendrical
in interface CalendricalMatcher
calendrical
- the calendrical to match, not nullpublic LocalDate adjustDate(LocalDate 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.
adjustDate
in interface DateAdjuster
date
- the date to be adjusted, not nullpublic LocalDate adjustDate(LocalDate date, DateResolver resolver)
This instance is immutable and unaffected by this method call.
date
- the date to be adjusted, not nullresolver
- the date resolver to use if the day-of-month becomes invalid, not nullIllegalCalendarFieldValueException
- if the date cannot be resolved using the resolverpublic int lengthInDays()
This returns the length in days of the month. The year is used to determine the correct length of February.
public boolean isValidDay(int dayOfMonth)
This method checks whether this year and month and the input day form a valid date.
dayOfMonth
- the day-of-month to validate, from 1 to 31, invalid value returns falsepublic LocalDate atDay(int dayOfMonth)
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.
dayOfMonth
- the day-of-month to use, from 1 to 31InvalidCalendarFieldException
- when the day is invalid for the year-monthisValidDay(int)
public int compareTo(YearMonth other)
compareTo
in interface Comparable<YearMonth>
other
- the other year-month to compare to, not nullNullPointerException
- if other
is nullpublic boolean isAfter(YearMonth other)
other
- the other year-month to compare to, not nullNullPointerException
- if other
is nullpublic boolean isBefore(YearMonth other)
other
- the other year-month to compare to, not nullNullPointerException
- if other
is nullpublic boolean equals(Object other)
public int hashCode()
public String toString()
String
, such as 2007-12
.
The output will be in the format yyyy-MM
:
public String toString(DateTimeFormatter formatter)
String
using the formatter.formatter
- the formatter to use, not nullUnsupportedOperationException
- if the formatter cannot printCalendricalPrintException
- if an error occurs during printingpublic static CalendricalRule<YearMonth> rule()
Copyright © 2014. All rights reserved.