Class MonthDay
- All Implemented Interfaces:
Serializable
,Comparable<MonthDay>
,Calendrical
,CalendricalMatcher
,DateAdjuster
--12-03
.
MonthDay
is an immutable calendrical that represents the combination
of a year and month. Any field that can be derived from a month and day, such as
quarter-of-year, can be obtained.
This class does not store or represent a year, time or time-zone.
Thus, for example, the value "3rd December" can be stored in a MonthDay
.
Since a MonthDay
does not possess a year, the leap day of
29th of February is considered valid.
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
.
MonthDay 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 int
The day-of-month.private final MonthOfYear
The month-of-year, not null.private static final DateTimeFormatter
Parser.private static final long
A serialization identifier for this class. -
Constructor Summary
ConstructorsModifierConstructorDescriptionprivate
MonthDay
(MonthOfYear monthOfYear, int dayOfMonth) Constructor, previously validated. -
Method Summary
Modifier and TypeMethodDescriptionadjustDate
(LocalDate date) Adjusts a date to have the value of this month-day, returning a new date.adjustDate
(LocalDate date, DateResolver resolver) Adjusts a date to have the value of this month-day, using a resolver to handle the case when the day-of-month becomes invalid.atYear
(int year) Returns a date formed from this month-day at the specified year.int
Compares this month-day to another month-day.boolean
Is this month-day equal to the specified month-day.<T> T
get
(CalendricalRule<T> rule) Gets the value of the specified calendrical rule.Gets the chronology that this month-day uses, which is the ISO calendar system.int
Gets the day-of-month field.Gets the month-of-year field, which is an enumMonthOfYear
.int
hashCode()
A hash code for this month-day.boolean
Is this month-day after the specified month-day.boolean
Is this month-day before the specified month-day.boolean
isValidYear
(int year) Checks if the year is valid for this month-day.boolean
matchesCalendrical
(Calendrical calendrical) Checks if the month-day extracted from the calendrical matches this.static MonthDay
now()
Obtains the current month-day from the system clock in the default time-zone.static MonthDay
Obtains the current month-day from the specified clock.static MonthDay
of
(int monthOfYear, int dayOfMonth) Obtains an instance ofMonthDay
.static MonthDay
of
(Calendrical calendrical) Obtains an instance ofMonthDay
from a Calendrical.static MonthDay
of
(MonthOfYear monthOfYear, int dayOfMonth) Obtains an instance ofMonthDay
.static MonthDay
Obtains an instance ofMonthDay
from a text string such as--12-03
.static MonthDay
parse
(String text, DateTimeFormatter formatter) Obtains an instance ofMonthDay
from a text string using a specific formatter.rollDayOfMonth
(int days) Rolls the day-of-month, adding the specified number of days to a copy of thisMonthDay
.rollMonthOfYear
(int months) Rolls the month-of-year, adding the specified number of months to a copy of thisMonthDay
.static CalendricalRule<MonthDay>
rule()
Gets the rule for the month-day.toString()
Outputs this month-day as aString
, such as--12-03
.toString
(DateTimeFormatter formatter) Outputs this month-day as aString
using the formatter.with
(MonthOfYear monthOfYear) Returns a copy of thisMonthDay
with the month-of-year altered.private MonthDay
with
(MonthOfYear newMonth, int newDay) Returns a copy of this month-day with the new month and day, checking to see if a new object is in fact required.withDayOfMonth
(int dayOfMonth) Returns a copy of thisMonthDay
with the day-of-month altered.withMonthOfYear
(int monthOfYear) Returns a copy of thisMonthDay
with the month-of-year altered.
-
Field Details
-
serialVersionUID
private static final long serialVersionUIDA serialization identifier for this class.- See Also:
-
PARSER
Parser. -
month
The month-of-year, not null. -
day
private final int dayThe day-of-month.
-
-
Constructor Details
-
MonthDay
Constructor, previously validated.- Parameters:
monthOfYear
- the month-of-year to represent, validated not nulldayOfMonth
- the day-of-month to represent, validated from 1 to 29-31
-
-
Method Details
-
now
Obtains the current month-day from the system clock in the default time-zone.This will query the
system clock
in the default time-zone to obtain the current month-day.Using this method will prevent the ability to use an alternate clock for testing because the clock is hard-coded.
- Returns:
- the current month-day using the system clock, never null
-
now
Obtains the current month-day from the specified clock.This will query the specified clock to obtain the current month-day. 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 month-day, never null
-
of
Obtains an instance ofMonthDay
.The day-of-month must be valid for the month within a leap year. Hence, for February, day 29 is valid.
For example, passing in April and day 31 will throw an exception, as there can never be a 31st April in any year. Alternately, passing in 29th February is valid, as that month-day can be valid.
- Parameters:
monthOfYear
- the month-of-year to represent, not nulldayOfMonth
- the day-of-month to represent, from 1 to 31- Returns:
- the month-day, never null
- Throws:
IllegalCalendarFieldValueException
- if the value of any field is out of rangeInvalidCalendarFieldException
- if the day-of-month is invalid for the month
-
of
Obtains an instance ofMonthDay
.The day-of-month must be valid for the month within a leap year. Hence, for month 2 (February), day 29 is valid.
For example, passing in month 4 (April) and day 31 will throw an exception, as there can never be a 31st April in any year. Alternately, passing in 29th February is valid, as that month-day can be valid.
- Parameters:
monthOfYear
- the month-of-year to represent, from 1 (January) to 12 (December)dayOfMonth
- the day-of-month to represent, from 1 to 31- Returns:
- the month-day, never null
- Throws:
IllegalCalendarFieldValueException
- if the value of any field is out of rangeInvalidCalendarFieldException
- if the day-of-month is invalid for the month
-
of
Obtains an instance ofMonthDay
from a Calendrical.This method will create a MonthDay from the Calendrical by extracting the month-of-year and day-of-month fields.
- Parameters:
calendrical
- the calendrical to use, not null- Returns:
- the month-day, never null
- Throws:
UnsupportedRuleException
- if either field cannot be foundInvalidCalendarFieldException
- if the value for either field is invalid
-
parse
Obtains an instance ofMonthDay
from a text string such as--12-03
.The following formats are accepted in ASCII:
- --{monthOfYear}-{dayOfMonth}
The day-of-month has 2 digits with values from 1 to 31 appropriate to the month.
- Parameters:
text
- the text to parse such as '--12-03', not null- Returns:
- the parsed month-day, never null
- Throws:
CalendricalException
- if the text cannot be parsed
-
parse
Obtains an instance ofMonthDay
from a text string using a specific formatter.The text is parsed using the formatter, returning a month-day.
- Parameters:
text
- the text to parse, not nullformatter
- the formatter to use, not null- Returns:
- the parsed month-day, never null
- Throws:
UnsupportedOperationException
- if the formatter cannot parseCalendricalException
- if the text cannot be parsed
-
with
Returns a copy of this month-day with the new month and day, checking to see if a new object is in fact required.- Parameters:
newMonth
- the month-of-year to represent, validated not nullnewDay
- the day-of-month to represent, validated from 1 to 31- Returns:
- the month-day, never null
-
getChronology
Gets the chronology that this month-day 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 month-day 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
-
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
-
getDayOfMonth
public int getDayOfMonth()Gets the day-of-month field.This method returns the primitive
int
value for the day-of-month.- Returns:
- the day-of-month, from 1 to 31
-
with
Returns a copy of thisMonthDay
with the month-of-year altered.If the day-of-month is invalid for the specified month, the day will be adjusted to the last valid day-of-month.
This instance is immutable and unaffected by this method call.
- Parameters:
monthOfYear
- the month-of-year to set in the returned month-day, not null- Returns:
- a
MonthDay
based on this month-day with the requested month, never null
-
withMonthOfYear
Returns a copy of thisMonthDay
with the month-of-year altered.If the day-of-month is invalid for the specified month, the day will be adjusted to the last valid day-of-month.
This instance is immutable and unaffected by this method call.
- Parameters:
monthOfYear
- the month-of-year to set in the returned month-day, from 1 (January) to 12 (December)- Returns:
- a
MonthDay
based on this month-day with the requested month, never null - Throws:
IllegalCalendarFieldValueException
- if the month-of-year value is invalid
-
withDayOfMonth
Returns a copy of thisMonthDay
with the day-of-month altered.If the day-of-month is invalid for the current month, an exception will be thrown.
This instance is immutable and unaffected by this method call.
- Parameters:
dayOfMonth
- the day-of-month to set in the return month-day, from 1 to 31- Returns:
- a
MonthDay
based on this month-day with the requested day, never null - Throws:
IllegalCalendarFieldValueException
- if the day-of-month value is invalidInvalidCalendarFieldException
- if the day-of-month is invalid for the month
-
rollMonthOfYear
Rolls the month-of-year, adding the specified number of months to a copy of thisMonthDay
.This method will add the specified number of months to the month-day, rolling from December back to January if necessary.
If the day-of-month is invalid for the specified month in the result, the day will be adjusted to the last valid day-of-month.
This instance is immutable and unaffected by this method call.
- Parameters:
months
- the months to roll by, positive or negative- Returns:
- a
MonthDay
based on this month-day with the month rolled, never null
-
rollDayOfMonth
Rolls the day-of-month, adding the specified number of days to a copy of thisMonthDay
.This method will add the specified number of days to the month-day, rolling from last day-of-month to the first if necessary.
This instance is immutable and unaffected by this method call.
- Parameters:
days
- the days to roll by, positive or negative- Returns:
- a
MonthDay
based on this month-day with the day rolled, never null
-
matchesCalendrical
Checks if the month-day 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 month-day, 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(monthDay);
This implementation handles the case where this represents February 29 and the year is not a leap year by throwing an exception.
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
- Throws:
InvalidCalendarFieldException
- if the day-of-month is invalid for the year
-
adjustDate
Adjusts a date to have the value of this month-day, 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 is invalid, not null- Returns:
- the adjusted date, never null
- Throws:
InvalidCalendarFieldException
- if the day-of-month is invalid for the year
-
isValidYear
public boolean isValidYear(int year) Checks if the year is valid for this month-day.This method checks whether this month and day and the input year form a valid date.
- Parameters:
year
- the year to validate, an out of range value returns false- Returns:
- true if the year is valid for this month-day
- See Also:
-
atYear
Returns a date formed from this month-day at the specified year.This method merges
this
and the specified year to form an instance ofLocalDate
.LocalDate date = monthDay.atYear(year);
This instance is immutable and unaffected by this method call.
- Parameters:
year
- the year to use, from MIN_YEAR to MAX_YEAR- Returns:
- the local date formed from this month-day and the specified year, never null
- See Also:
-
compareTo
Compares this month-day to another month-day.- Specified by:
compareTo
in interfaceComparable<MonthDay>
- Parameters:
other
- the other month-day to compare to, not null- Returns:
- the comparator value, negative if less, positive if greater
- Throws:
NullPointerException
- ifother
is null
-
isAfter
Is this month-day after the specified month-day.- Parameters:
other
- the other month-day to compare to, not null- Returns:
- true if this is after the specified month-day
- Throws:
NullPointerException
- ifother
is null
-
isBefore
Is this month-day before the specified month-day.- Parameters:
other
- the other month-day to compare to, not null- Returns:
- true if this point is before the specified month-day
- Throws:
NullPointerException
- ifother
is null
-
equals
Is this month-day equal to the specified month-day. -
hashCode
public int hashCode()A hash code for this month-day. -
toString
Outputs this month-day as aString
, such as--12-03
.The output will be in the format
--MM-dd
: -
toString
Outputs this month-day as aString
using the formatter.- Parameters:
formatter
- the formatter to use, not null- Returns:
- the formatted month-day string, never null
- Throws:
UnsupportedOperationException
- if the formatter cannot printCalendricalPrintException
- if an error occurs during printing
-
rule
Gets the rule for the month-day.- Returns:
- the rule for the month-day, never null
-