Class YearMonth
- All Implemented Interfaces:
Serializable
,Comparable<ReadablePartial>
,ReadablePartial
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()
- numeric value -
monthOfYear().get()
- text value -
monthOfYear().getAsText()
- short text value -
monthOfYear().getAsShortText()
- maximum/minimum values -
monthOfYear().getMaximumValue()
- add/subtract -
monthOfYear().addToCopy()
- set -
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.
- Since:
- 2.0
- Author:
- Stephen Colebourne
- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic class
The property class forYearMonth
. -
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final int
The index of the monthOfYear field in the field arraystatic final int
The index of the year field in the field array -
Constructor Summary
ConstructorsConstructorDescriptionConstructs a YearMonth with the current year-month, using ISOChronology in the default zone to extract the fields.YearMonth
(int year, int monthOfYear) Constructs a YearMonth with specified year and month usingISOChronology
.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.Constructs a YearMonth from an Object that represents some form of time.YearMonth
(Object instant, Chronology chronology) Constructs a YearMonth from an Object that represents some form of time, using the specified chronology.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. -
Method Summary
Modifier and TypeMethodDescriptionstatic YearMonth
fromCalendarFields
(Calendar calendar) Constructs a YearMonth from ajava.util.Calendar
using exactly the same field values avoiding any time zone effects.static YearMonth
fromDateFields
(Date date) Constructs a YearMonth from ajava.util.Date
using exactly the same field values avoiding any time zone effects.protected DateTimeField
getField
(int index, Chronology chrono) Gets the field for a specific index in the chronology specified.getFieldType
(int index) Gets the field type at the specified index.Gets an array of the field type of each of the fields that this partial supports.int
Get the month of year field value.int
getYear()
Get the year field value.minus
(ReadablePeriod period) Returns a copy of this year-month with the specified period taken away.minusMonths
(int months) Returns a copy of this year-month minus the specified number of months.minusYears
(int years) Returns a copy of this year-month minus the specified number of years.Get the month of year field property which provides access to advanced functionality.static YearMonth
now()
Obtains aYearMonth
set to the current system millisecond time usingISOChronology
in the default time zone.static YearMonth
now
(Chronology chronology) Obtains aYearMonth
set to the current system millisecond time using the specified chronology.static YearMonth
now
(DateTimeZone zone) Obtains aYearMonth
set to the current system millisecond time usingISOChronology
in the specified time zone.static YearMonth
Parses aYearMonth
from the specified string.static YearMonth
parse
(String str, DateTimeFormatter formatter) Parses aYearMonth
from the specified string using a formatter.plus
(ReadablePeriod period) Returns a copy of this year-month with the specified period added.plusMonths
(int months) Returns a copy of this year-month plus the specified number of months.plusYears
(int years) Returns a copy of this year-month plus the specified number of years.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.Converts this object to an Interval representing the whole month.toInterval
(DateTimeZone zone) Converts this object to an Interval representing the whole month.toLocalDate
(int dayOfMonth) Converts this object to a LocalDate with the same year-month and chronology.toString()
Output the year-month in ISO8601 format (yyyy-MM).Output the year-month using the specified format pattern.Output the year-month using the specified format pattern.withChronologyRetainFields
(Chronology newChronology) Returns a copy of this year-month with the specified chronology.withField
(DateTimeFieldType fieldType, int value) Returns a copy of this year-month with the specified field set to a new value.withFieldAdded
(DurationFieldType fieldType, int amount) Returns a copy of this year-month with the value of the specified field increased.withMonthOfYear
(int monthOfYear) Returns a copy of this year-month with the month of year field updated.withPeriodAdded
(ReadablePeriod period, int scalar) Returns a copy of this year-month with the specified period added.withYear
(int year) Returns a copy of this year-month with the year field updated.year()
Get the year field property which provides access to advanced functionality.Methods inherited from class org.joda.time.base.BasePartial
getChronology, getValue, getValues, setValue, setValues
Methods inherited from class org.joda.time.base.AbstractPartial
compareTo, equals, get, getField, getFields, hashCode, indexOf, indexOf, indexOfSupported, indexOfSupported, isAfter, isBefore, isEqual, isSupported, toDateTime, toString
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
Methods inherited from interface java.lang.Comparable
compareTo
Methods inherited from interface org.joda.time.ReadablePartial
equals, get, getChronology, getField, getValue, hashCode, isSupported, toDateTime
-
Field Details
-
YEAR
public static final int YEARThe index of the year field in the field array- See Also:
-
MONTH_OF_YEAR
public static final int MONTH_OF_YEARThe index of the monthOfYear field in the field array- See Also:
-
-
Constructor Details
-
YearMonth
public YearMonth()Constructs a YearMonth with the current year-month, using ISOChronology in the default zone to extract the fields.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).
- See Also:
-
YearMonth
Constructs a YearMonth with the current year-month, using ISOChronology in the specified zone to extract the fields.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).
- Parameters:
zone
- the zone to use, null means default zone- See Also:
-
YearMonth
Constructs a YearMonth with the current year-month, using the specified chronology and zone to extract the fields.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).
- Parameters:
chronology
- the chronology, null means ISOChronology in the default zone- See Also:
-
YearMonth
public YearMonth(long instant) Constructs a YearMonth extracting the partial fields from the specified milliseconds using the ISOChronology in the default zone.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).
- Parameters:
instant
- the milliseconds from 1970-01-01T00:00:00Z
-
YearMonth
Constructs a YearMonth extracting the partial fields from the specified milliseconds using the chronology provided.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).
- Parameters:
instant
- the milliseconds from 1970-01-01T00:00:00Zchronology
- the chronology, null means ISOChronology in the default zone
-
YearMonth
Constructs a YearMonth from an Object that represents some form of time.The recognised object types are defined in
ConverterManager
and include ReadableInstant, String, Calendar and Date. The String formats are described byISODateTimeFormat.localDateParser()
.The chronology used will be derived from the object, defaulting to ISO.
- Parameters:
instant
- the date-time object, null means now- Throws:
IllegalArgumentException
- if the instant is invalid
-
YearMonth
Constructs a YearMonth from an Object that represents some form of time, using the specified chronology.The recognised object types are defined in
ConverterManager
and include ReadableInstant, String, Calendar and Date. The String formats are described byISODateTimeFormat.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.
- Parameters:
instant
- the date-time object, null means nowchronology
- the chronology, null means ISO default- Throws:
IllegalArgumentException
- if the instant is invalid
-
YearMonth
public YearMonth(int year, int monthOfYear) Constructs a YearMonth with specified year and month usingISOChronology
.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).
- Parameters:
year
- the yearmonthOfYear
- the month of the year
-
YearMonth
Constructs an instance set to the specified year and month using the specified chronology, whose zone is ignored.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).
- Parameters:
year
- the yearmonthOfYear
- the month of the yearchronology
- the chronology, null means ISOChronology in the default zone
-
-
Method Details
-
now
Obtains aYearMonth
set to the current system millisecond time usingISOChronology
in the default time zone. The resulting object does not use the zone.- Returns:
- the current year-month, not null
- Since:
- 2.0
-
now
Obtains aYearMonth
set to the current system millisecond time usingISOChronology
in the specified time zone. The resulting object does not use the zone.- Parameters:
zone
- the time zone, not null- Returns:
- the current year-month, not null
- Since:
- 2.0
-
now
Obtains aYearMonth
set to the current system millisecond time using the specified chronology. The resulting object does not use the zone.- Parameters:
chronology
- the chronology, not null- Returns:
- the current year-month, not null
- Since:
- 2.0
-
parse
Parses aYearMonth
from the specified string.This uses
ISODateTimeFormat.localDateParser()
.- Parameters:
str
- the string to parse, not null- Since:
- 2.0
-
parse
Parses aYearMonth
from the specified string using a formatter.- Parameters:
str
- the string to parse, not nullformatter
- the formatter to use, not null- Since:
- 2.0
-
fromCalendarFields
Constructs a YearMonth from ajava.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.- Parameters:
calendar
- the Calendar to extract fields from- Returns:
- the created YearMonth, never null
- Throws:
IllegalArgumentException
- if the calendar is nullIllegalArgumentException
- if the year or month is invalid for the ISO chronology
-
fromDateFields
Constructs a YearMonth from ajava.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.
- Parameters:
date
- the Date to extract fields from- Returns:
- the created YearMonth, never null
- Throws:
IllegalArgumentException
- if the calendar is nullIllegalArgumentException
- if the year or month is invalid for the ISO chronology
-
size
public int size()Gets the number of fields in this partial, which is two. The supported fields are Year and MonthOfYear. Note that only these fields may be queried.- Specified by:
size
in interfaceReadablePartial
- Returns:
- the field count, two
-
getField
Gets the field for a specific index in the chronology specified.This method must not use any instance variables.
- Specified by:
getField
in classAbstractPartial
- Parameters:
index
- the index to retrievechrono
- the chronology to use- Returns:
- the field, never null
-
getFieldType
Gets the field type at the specified index.- Specified by:
getFieldType
in interfaceReadablePartial
- Overrides:
getFieldType
in classAbstractPartial
- Parameters:
index
- the index to retrieve- Returns:
- the field at the specified index, never null
- Throws:
IndexOutOfBoundsException
- if the index is invalid
-
getFieldTypes
Gets an array of the field type of each of the fields that this partial supports.The fields are returned largest to smallest, Year, Month.
- Overrides:
getFieldTypes
in classAbstractPartial
- Returns:
- the array of field types (cloned), largest to smallest, never null
-
withChronologyRetainFields
Returns a copy of this year-month with the specified chronology. This instance is immutable and unaffected by this method call.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.
- Parameters:
newChronology
- the new chronology, null means ISO- Returns:
- a copy of this year-month with a different chronology, never null
- Throws:
IllegalArgumentException
- if the values are invalid for the new chronology
-
withField
Returns a copy of this year-month with the specified field set to a new 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);
- Parameters:
fieldType
- the field type to set, not nullvalue
- the value to set- Returns:
- a copy of this instance with the field set, never null
- Throws:
IllegalArgumentException
- if the value is null or invalid
-
withFieldAdded
Returns a copy of this year-month with the value of the specified field increased.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);
- Parameters:
fieldType
- the field type to add to, not nullamount
- the amount to add- Returns:
- a copy of this instance with the field updated, never null
- Throws:
IllegalArgumentException
- if the value is null or invalidArithmeticException
- if the new date-time exceeds the capacity
-
withPeriodAdded
Returns a copy of this year-month with the specified period added.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)
orplusYears(int)
.- Parameters:
period
- the period to add to this one, null means zeroscalar
- the amount of times to add, such as -1 to subtract once- Returns:
- a copy of this instance with the period added, never null
- Throws:
ArithmeticException
- if the new date-time exceeds the capacity
-
plus
Returns a copy of this year-month with the specified period added.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)
.- Parameters:
period
- the duration to add to this one, null means zero- Returns:
- a copy of this instance with the period added, never null
- Throws:
ArithmeticException
- if the new year-month exceeds the capacity
-
plusYears
Returns a copy of this year-month plus the specified number of 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);
- Parameters:
years
- the amount of years to add, may be negative- Returns:
- the new year-month plus the increased years, never null
-
plusMonths
Returns a copy of this year-month plus the specified number of 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);
- Parameters:
months
- the amount of months to add, may be negative- Returns:
- the new year-month plus the increased months, never null
-
minus
Returns a copy of this year-month with the specified period taken away.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)
.- Parameters:
period
- the period to reduce this instant by- Returns:
- a copy of this instance with the period taken away, never null
- Throws:
ArithmeticException
- if the new year-month exceeds the capacity
-
minusYears
Returns a copy of this year-month minus the specified number of 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);
- Parameters:
years
- the amount of years to subtract, may be negative- Returns:
- the new year-month minus the increased years, never null
-
minusMonths
Returns a copy of this year-month minus the specified number of 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);
- Parameters:
months
- the amount of months to subtract, may be negative- Returns:
- the new year-month minus the increased months, never null
-
toLocalDate
Converts this object to a LocalDate with the same year-month and chronology.- Parameters:
dayOfMonth
- the day of month to use, valid for chronology, such as 1-31 for ISO- Returns:
- a LocalDate with the same year-month and chronology, never null
-
toInterval
Converts this object to an Interval representing the whole month.The interval will use the chronology of the year-month in the default zone.
This instance is immutable and unaffected by this method call.
- Returns:
- an interval over the month, never null
-
toInterval
Converts this object to an Interval representing the whole month.The interval will use the chronology of the year-month in the specified zone.
This instance is immutable and unaffected by this method call.
- Parameters:
zone
- the zone to get the Interval in, null means default- Returns:
- an interval over the month, never null
-
getYear
public int getYear()Get the year field value.- Returns:
- the year
-
getMonthOfYear
public int getMonthOfYear()Get the month of year field value.- Returns:
- the month of year
-
withYear
Returns a copy of this year-month with the year field updated.YearMonth is immutable, so there are no set methods. Instead, this method returns a new instance with the value of year changed.
- Parameters:
year
- the year to set- Returns:
- a copy of this object with the field set, never null
- Throws:
IllegalArgumentException
- if the value is invalid
-
withMonthOfYear
Returns a copy of this year-month with the month of year field updated.YearMonth is immutable, so there are no set methods. Instead, this method returns a new instance with the value of month of year changed.
- Parameters:
monthOfYear
- the month of year to set- Returns:
- a copy of this object with the field set, never null
- Throws:
IllegalArgumentException
- if the value is invalid
-
property
Gets the property object for the specified type, which contains many useful methods.- Parameters:
type
- the field type to get the property for- Returns:
- the property object
- Throws:
IllegalArgumentException
- if the field is null or unsupported
-
year
Get the year field property which provides access to advanced functionality.- Returns:
- the year property
-
monthOfYear
Get the month of year field property which provides access to advanced functionality.- Returns:
- the month of year property
-
toString
Output the year-month in ISO8601 format (yyyy-MM).- Specified by:
toString
in interfaceReadablePartial
- Overrides:
toString
in classObject
- Returns:
- ISO8601 time formatted string.
-
toString
Output the year-month using the specified format pattern.- Overrides:
toString
in classBasePartial
- Parameters:
pattern
- the pattern specification, null means usetoString
- See Also:
-
toString
Output the year-month using the specified format pattern.- Overrides:
toString
in classBasePartial
- Parameters:
pattern
- the pattern specification, null means usetoString
locale
- Locale to use, null means default- Throws:
IllegalArgumentException
- See Also:
-