public final class YearMonth extends BasePartial implements ReadablePartial, java.io.Serializable
NOTE: This class only supports the two fields listed above. It is impossible to query any other fields, such as dayOfWeek or centuryOfEra.
Calculations on YearMonth are performed using a Chronology
.
This chronology is set to be in the UTC time zone for all calculations.
One use case for this class is to store a credit card expiry date, as that only references the year and month. This class can be used as the gYearMonth type in XML Schema.
Each individual field can be queried in two ways:
getMonthOfYear()
monthOfYear().get()
monthOfYear().get()
monthOfYear().getAsText()
monthOfYear().getAsShortText()
monthOfYear().getMaximumValue()
monthOfYear().addToCopy()
monthOfYear().setCopy()
YearMonth is thread-safe and immutable, provided that the Chronology is as well. All standard Chronology classes supplied are thread-safe and immutable.
Modifier and Type | Class and Description |
---|---|
static class |
YearMonth.Property
The property class for
YearMonth . |
Modifier and Type | Field and Description |
---|---|
static int |
MONTH_OF_YEAR
The index of the monthOfYear field in the field array
|
static int |
YEAR
The index of the year field in the field array
|
Constructor and Description |
---|
YearMonth()
Constructs a YearMonth with the current year-month, using ISOChronology in
the default zone to extract the fields.
|
YearMonth(Chronology chronology)
Constructs a YearMonth with the current year-month, using the specified chronology
and zone to extract the fields.
|
YearMonth(DateTimeZone zone)
Constructs a YearMonth with the current year-month, using ISOChronology in
the specified zone to extract the fields.
|
YearMonth(int year,
int monthOfYear)
Constructs a YearMonth with specified year and month
using
ISOChronology . |
YearMonth(int year,
int monthOfYear,
Chronology chronology)
Constructs an instance set to the specified year and month
using the specified chronology, whose zone is ignored.
|
YearMonth(long instant)
Constructs a YearMonth extracting the partial fields from the specified
milliseconds using the ISOChronology in the default zone.
|
YearMonth(long instant,
Chronology chronology)
Constructs a YearMonth extracting the partial fields from the specified
milliseconds using the chronology provided.
|
YearMonth(java.lang.Object instant)
Constructs a YearMonth from an Object that represents some form of time.
|
YearMonth(java.lang.Object instant,
Chronology chronology)
Constructs a YearMonth from an Object that represents some form of time,
using the specified chronology.
|
Modifier and Type | Method and Description |
---|---|
static YearMonth |
fromCalendarFields(java.util.Calendar calendar)
Constructs a YearMonth from a
java.util.Calendar
using exactly the same field values avoiding any time zone effects. |
static YearMonth |
fromDateFields(java.util.Date date)
Constructs a YearMonth from a
java.util.Date
using exactly the same field values avoiding any time zone effects. |
DateTimeFieldType |
getFieldType(int index)
Gets the field type at the specified index.
|
DateTimeFieldType[] |
getFieldTypes()
Gets an array of the field type of each of the fields that this partial supports.
|
int |
getMonthOfYear()
Get the month of year field value.
|
int |
getYear()
Get the year field value.
|
YearMonth |
minus(ReadablePeriod period)
Returns a copy of this year-month with the specified period taken away.
|
YearMonth |
minusMonths(int months)
Returns a copy of this year-month minus the specified number of months.
|
YearMonth |
minusYears(int years)
Returns a copy of this year-month minus the specified number of years.
|
YearMonth.Property |
monthOfYear()
Get the month of year field property which provides access to advanced functionality.
|
static YearMonth |
now()
Obtains a
YearMonth set to the current system millisecond time
using ISOChronology in the default time zone. |
static YearMonth |
now(Chronology chronology)
Obtains a
YearMonth set to the current system millisecond time
using the specified chronology. |
static YearMonth |
now(DateTimeZone zone)
Obtains a
YearMonth set to the current system millisecond time
using ISOChronology in the specified time zone. |
static YearMonth |
parse(java.lang.String str)
Parses a
YearMonth from the specified string. |
static YearMonth |
parse(java.lang.String str,
DateTimeFormatter formatter)
Parses a
YearMonth from the specified string using a formatter. |
YearMonth |
plus(ReadablePeriod period)
Returns a copy of this year-month with the specified period added.
|
YearMonth |
plusMonths(int months)
Returns a copy of this year-month plus the specified number of months.
|
YearMonth |
plusYears(int years)
Returns a copy of this year-month plus the specified number of years.
|
YearMonth.Property |
property(DateTimeFieldType type)
Gets the property object for the specified type, which contains
many useful methods.
|
int |
size()
Gets the number of fields in this partial, which is two.
|
Interval |
toInterval()
Converts this object to an Interval representing the whole month.
|
Interval |
toInterval(DateTimeZone zone)
Converts this object to an Interval representing the whole month.
|
LocalDate |
toLocalDate(int dayOfMonth)
Converts this object to a LocalDate with the same year-month and chronology.
|
java.lang.String |
toString()
Output the year-month in ISO8601 format (yyyy-MM).
|
java.lang.String |
toString(java.lang.String pattern)
Output the year-month using the specified format pattern.
|
java.lang.String |
toString(java.lang.String pattern,
java.util.Locale locale)
Output the year-month using the specified format pattern.
|
YearMonth |
withChronologyRetainFields(Chronology newChronology)
Returns a copy of this year-month with the specified chronology.
|
YearMonth |
withField(DateTimeFieldType fieldType,
int value)
Returns a copy of this year-month with the specified field set to a new value.
|
YearMonth |
withFieldAdded(DurationFieldType fieldType,
int amount)
Returns a copy of this year-month with the value of the specified field increased.
|
YearMonth |
withMonthOfYear(int monthOfYear)
Returns a copy of this year-month with the month of year field updated.
|
YearMonth |
withPeriodAdded(ReadablePeriod period,
int scalar)
Returns a copy of this year-month with the specified period added.
|
YearMonth |
withYear(int year)
Returns a copy of this year-month with the year field updated.
|
YearMonth.Property |
year()
Get the year field property which provides access to advanced functionality.
|
getChronology, getValue, getValues
compareTo, equals, get, getField, getFields, hashCode, indexOf, isAfter, isBefore, isEqual, isSupported, toDateTime, toString
equals, get, getChronology, getField, getValue, hashCode, isSupported, toDateTime
public static final int YEAR
public static final int MONTH_OF_YEAR
public YearMonth()
The constructor uses the default time zone, resulting in the local time being initialised. Once the constructor is complete, all further calculations are performed without reference to a time-zone (by switching to UTC).
now()
public YearMonth(DateTimeZone zone)
The constructor uses the specified time zone to obtain the current year-month. Once the constructor is complete, all further calculations are performed without reference to a time-zone (by switching to UTC).
zone
- the zone to use, null means default zonenow(DateTimeZone)
public YearMonth(Chronology chronology)
The constructor uses the time zone of the chronology specified. Once the constructor is complete, all further calculations are performed without reference to a time-zone (by switching to UTC).
chronology
- the chronology, null means ISOChronology in the default zonenow(Chronology)
public YearMonth(long instant)
The constructor uses the default time zone, resulting in the local time being initialised. Once the constructor is complete, all further calculations are performed without reference to a time-zone (by switching to UTC).
instant
- the milliseconds from 1970-01-01T00:00:00Zpublic YearMonth(long instant, Chronology chronology)
The constructor uses the time zone of the chronology specified. Once the constructor is complete, all further calculations are performed without reference to a time-zone (by switching to UTC).
instant
- the milliseconds from 1970-01-01T00:00:00Zchronology
- the chronology, null means ISOChronology in the default zonepublic YearMonth(java.lang.Object instant)
The recognised object types are defined in
ConverterManager
and
include ReadableInstant, String, Calendar and Date.
The String formats are described by ISODateTimeFormat.localDateParser()
.
The chronology used will be derived from the object, defaulting to ISO.
instant
- the date-time object, null means nowjava.lang.IllegalArgumentException
- if the instant is invalidpublic YearMonth(java.lang.Object instant, Chronology chronology)
The recognised object types are defined in
ConverterManager
and
include ReadableInstant, String, Calendar and Date.
The String formats are described by ISODateTimeFormat.localDateParser()
.
The constructor uses the time zone of the chronology specified. Once the constructor is complete, all further calculations are performed without reference to a time-zone (by switching to UTC). The specified chronology overrides that of the object.
instant
- the date-time object, null means nowchronology
- the chronology, null means ISO defaultjava.lang.IllegalArgumentException
- if the instant is invalidpublic YearMonth(int year, int monthOfYear)
ISOChronology
.
The constructor uses the no time zone initialising the fields as provided. Once the constructor is complete, all further calculations are performed without reference to a time-zone (by switching to UTC).
year
- the yearmonthOfYear
- the month of the yearpublic YearMonth(int year, int monthOfYear, Chronology chronology)
If the chronology is null, ISOChronology
is used.
The constructor uses the time zone of the chronology specified. Once the constructor is complete, all further calculations are performed without reference to a time-zone (by switching to UTC).
year
- the yearmonthOfYear
- the month of the yearchronology
- the chronology, null means ISOChronology in the default zonepublic static YearMonth now()
YearMonth
set to the current system millisecond time
using ISOChronology
in the default time zone.
The resulting object does not use the zone.public static YearMonth now(DateTimeZone zone)
YearMonth
set to the current system millisecond time
using ISOChronology
in the specified time zone.
The resulting object does not use the zone.zone
- the time zone, not nullpublic static YearMonth now(Chronology chronology)
YearMonth
set to the current system millisecond time
using the specified chronology.
The resulting object does not use the zone.chronology
- the chronology, not nullpublic static YearMonth parse(java.lang.String str)
YearMonth
from the specified string.
This uses ISODateTimeFormat.localDateParser()
.
str
- the string to parse, not nullpublic static YearMonth parse(java.lang.String str, DateTimeFormatter formatter)
YearMonth
from the specified string using a formatter.str
- the string to parse, not nullformatter
- the formatter to use, not nullpublic static YearMonth fromCalendarFields(java.util.Calendar calendar)
java.util.Calendar
using exactly the same field values avoiding any time zone effects.
Each field is queried from the Calendar and assigned to the YearMonth.
This factory method ignores the type of the calendar and always
creates a YearMonth with ISO chronology. It is expected that you
will only pass in instances of GregorianCalendar
however
this is not validated.
calendar
- the Calendar to extract fields fromjava.lang.IllegalArgumentException
- if the calendar is nulljava.lang.IllegalArgumentException
- if the year or month is invalid for the ISO chronologypublic static YearMonth fromDateFields(java.util.Date date)
java.util.Date
using exactly the same field values avoiding any time zone effects.
Each field is queried from the Date and assigned to the YearMonth.
This factory method always creates a YearMonth with ISO chronology.
date
- the Date to extract fields fromjava.lang.IllegalArgumentException
- if the calendar is nulljava.lang.IllegalArgumentException
- if the year or month is invalid for the ISO chronologypublic int size()
size
in interface ReadablePartial
public DateTimeFieldType getFieldType(int index)
getFieldType
in interface ReadablePartial
getFieldType
in class AbstractPartial
index
- the index to retrievejava.lang.IndexOutOfBoundsException
- if the index is invalidpublic DateTimeFieldType[] getFieldTypes()
The fields are returned largest to smallest, Year, Month.
getFieldTypes
in class AbstractPartial
public YearMonth withChronologyRetainFields(Chronology newChronology)
This method retains the values of the fields, thus the result will typically refer to a different instant.
The time zone of the specified chronology is ignored, as YearMonth operates without a time zone.
newChronology
- the new chronology, null means ISOjava.lang.IllegalArgumentException
- if the values are invalid for the new chronologypublic YearMonth withField(DateTimeFieldType fieldType, int value)
For example, if the field type is monthOfYear
then the month
would be changed in the returned instance.
These three lines are equivalent:
YearMonth updated = ym.withField(DateTimeFieldType.monthOfYear(), 6); YearMonth updated = ym.monthOfYear().setCopy(6); YearMonth updated = ym.property(DateTimeFieldType.monthOfYear()).setCopy(6);
fieldType
- the field type to set, not nullvalue
- the value to setjava.lang.IllegalArgumentException
- if the value is null or invalidpublic YearMonth withFieldAdded(DurationFieldType fieldType, int amount)
If the addition is zero, then this
is returned.
These three lines are equivalent:
YearMonth added = ym.withFieldAdded(DurationFieldType.months(), 6); YearMonth added = ym.plusMonths(6); YearMonth added = ym.monthOfYear().addToCopy(6);
fieldType
- the field type to add to, not nullamount
- the amount to addjava.lang.IllegalArgumentException
- if the value is null or invalidjava.lang.ArithmeticException
- if the new date-time exceeds the capacitypublic YearMonth withPeriodAdded(ReadablePeriod period, int scalar)
If the addition is zero, then this
is returned.
Fields in the period that aren't present in the partial are ignored.
This method is typically used to add multiple copies of complex
period instances. Adding one field is best achieved using methods
like withFieldAdded(DurationFieldType, int)
or plusYears(int)
.
period
- the period to add to this one, null means zeroscalar
- the amount of times to add, such as -1 to subtract oncejava.lang.ArithmeticException
- if the new date-time exceeds the capacitypublic YearMonth plus(ReadablePeriod period)
If the amount is zero or null, then this
is returned.
This method is typically used to add complex period instances.
Adding one field is best achieved using methods
like plusYears(int)
.
period
- the duration to add to this one, null means zerojava.lang.ArithmeticException
- if the new year-month exceeds the capacitypublic YearMonth plusYears(int years)
This year-month instance is immutable and unaffected by this method call.
The following three lines are identical in effect:
YearMonth added = ym.plusYears(6); YearMonth added = ym.plus(Period.years(6)); YearMonth added = ym.withFieldAdded(DurationFieldType.years(), 6);
years
- the amount of years to add, may be negativepublic YearMonth plusMonths(int months)
This year-month instance is immutable and unaffected by this method call.
The following three lines are identical in effect:
YearMonth added = ym.plusMonths(6); YearMonth added = ym.plus(Period.months(6)); YearMonth added = ym.withFieldAdded(DurationFieldType.months(), 6);
months
- the amount of months to add, may be negativepublic YearMonth minus(ReadablePeriod period)
If the amount is zero or null, then this
is returned.
This method is typically used to subtract complex period instances.
Subtracting one field is best achieved using methods
like minusYears(int)
.
period
- the period to reduce this instant byjava.lang.ArithmeticException
- if the new year-month exceeds the capacitypublic YearMonth minusYears(int years)
This year-month instance is immutable and unaffected by this method call.
The following three lines are identical in effect:
YearMonth subtracted = ym.minusYears(6); YearMonth subtracted = ym.minus(Period.years(6)); YearMonth subtracted = ym.withFieldAdded(DurationFieldType.years(), -6);
years
- the amount of years to subtract, may be negativepublic YearMonth minusMonths(int months)
This year-month instance is immutable and unaffected by this method call.
The following three lines are identical in effect:
YearMonth subtracted = ym.minusMonths(6); YearMonth subtracted = ym.minus(Period.months(6)); YearMonth subtracted = ym.withFieldAdded(DurationFieldType.months(), -6);
months
- the amount of months to subtract, may be negativepublic LocalDate toLocalDate(int dayOfMonth)
dayOfMonth
- the day of month to use, valid for chronology, such as 1-31 for ISOpublic Interval toInterval()
The interval will use the chronology of the year-month in the default zone.
This instance is immutable and unaffected by this method call.
public Interval toInterval(DateTimeZone zone)
The interval will use the chronology of the year-month in the specified zone.
This instance is immutable and unaffected by this method call.
zone
- the zone to get the Interval in, null means defaultpublic int getYear()
public int getMonthOfYear()
public YearMonth withYear(int year)
YearMonth is immutable, so there are no set methods. Instead, this method returns a new instance with the value of year changed.
year
- the year to setjava.lang.IllegalArgumentException
- if the value is invalidpublic YearMonth withMonthOfYear(int monthOfYear)
YearMonth is immutable, so there are no set methods. Instead, this method returns a new instance with the value of month of year changed.
monthOfYear
- the month of year to setjava.lang.IllegalArgumentException
- if the value is invalidpublic YearMonth.Property property(DateTimeFieldType type)
type
- the field type to get the property forjava.lang.IllegalArgumentException
- if the field is null or unsupportedpublic YearMonth.Property year()
public YearMonth.Property monthOfYear()
public java.lang.String toString()
toString
in interface ReadablePartial
toString
in class java.lang.Object
public java.lang.String toString(java.lang.String pattern)
toString
in class BasePartial
pattern
- the pattern specification, null means use toString
DateTimeFormat
public java.lang.String toString(java.lang.String pattern, java.util.Locale locale) throws java.lang.IllegalArgumentException
toString
in class BasePartial
pattern
- the pattern specification, null means use toString
locale
- Locale to use, null means defaultjava.lang.IllegalArgumentException
DateTimeFormat
"Copyright © 2010 - 2020 Adobe Systems Incorporated. All Rights Reserved"