Class MonthDay
- java.lang.Object
-
- javax.time.calendar.MonthDay
-
- All Implemented Interfaces:
Serializable
,Comparable<MonthDay>
,Calendrical
,CalendricalMatcher
,DateAdjuster
public final class MonthDay extends Object implements Calendrical, CalendricalMatcher, DateAdjuster, Comparable<MonthDay>, Serializable
A month-day in the ISO-8601 calendar system, such as--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.
- 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 month-day, returning a new date.LocalDate
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.LocalDate
atYear(int year)
Returns a date formed from this month-day at the specified year.int
compareTo(MonthDay other)
Compares this month-day to another month-day.boolean
equals(Object other)
Is this month-day equal to the specified month-day.<T> T
get(CalendricalRule<T> rule)
Gets the value of the specified calendrical rule.ISOChronology
getChronology()
Gets the chronology that this month-day uses, which is the ISO calendar system.int
getDayOfMonth()
Gets the day-of-month field.MonthOfYear
getMonthOfYear()
Gets the month-of-year field, which is an enumMonthOfYear
.int
hashCode()
A hash code for this month-day.boolean
isAfter(MonthDay other)
Is this month-day after the specified month-day.boolean
isBefore(MonthDay other)
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
now(Clock clock)
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
parse(String text)
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.MonthDay
rollDayOfMonth(int days)
Rolls the day-of-month, adding the specified number of days to a copy of thisMonthDay
.MonthDay
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.String
toString()
Outputs this month-day as aString
, such as--12-03
.String
toString(DateTimeFormatter formatter)
Outputs this month-day as aString
using the formatter.MonthDay
with(MonthOfYear monthOfYear)
Returns a copy of thisMonthDay
with the month-of-year altered.MonthDay
withDayOfMonth(int dayOfMonth)
Returns a copy of thisMonthDay
with the day-of-month altered.MonthDay
withMonthOfYear(int monthOfYear)
Returns a copy of thisMonthDay
with the month-of-year altered.
-
-
-
Method Detail
-
now
public static MonthDay 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
public static MonthDay now(Clock clock)
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
public static MonthDay of(MonthOfYear monthOfYear, int dayOfMonth)
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
public static MonthDay of(int monthOfYear, int dayOfMonth)
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
public static MonthDay of(Calendrical calendrical)
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
public static MonthDay parse(String text)
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
public static MonthDay parse(String text, DateTimeFormatter formatter)
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
-
getChronology
public ISOChronology getChronology()
Gets the chronology that this month-day 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 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
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
-
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
public MonthDay with(MonthOfYear monthOfYear)
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
public MonthDay withMonthOfYear(int monthOfYear)
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
public MonthDay withDayOfMonth(int dayOfMonth)
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
public MonthDay rollMonthOfYear(int months)
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
public MonthDay rollDayOfMonth(int days)
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
public boolean matchesCalendrical(Calendrical calendrical)
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
public LocalDate adjustDate(LocalDate date)
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
public LocalDate 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.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:
Year.isValidMonthDay(MonthDay)
-
atYear
public LocalDate atYear(int year)
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:
Year.atMonthDay(MonthDay)
-
compareTo
public int compareTo(MonthDay other)
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
public boolean isAfter(MonthDay other)
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
public boolean isBefore(MonthDay other)
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
public boolean equals(Object other)
Is this month-day equal to the specified month-day.
-
hashCode
public int hashCode()
A hash code for this month-day.
-
toString
public String toString()
Outputs this month-day as aString
, such as--12-03
.The output will be in the format
--MM-dd
:
-
toString
public String toString(DateTimeFormatter formatter)
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
public static CalendricalRule<MonthDay> rule()
Gets the rule for the month-day.- Returns:
- the rule for the month-day, never null
-
-