org.joda.time
Class YearMonth

java.lang.Object
  extended by org.joda.time.base.AbstractPartial
      extended by org.joda.time.base.BasePartial
          extended by org.joda.time.YearMonth
All Implemented Interfaces:
Serializable, Comparable<ReadablePartial>, ReadablePartial

public final class YearMonth
extends BasePartial
implements ReadablePartial, Serializable

YearMonth is an immutable partial supporting the year and monthOfYear fields.

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:

The second technique also provides access to other useful methods on the field:

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:
Serialized Form

Nested Class Summary
static class YearMonth.Property
          The property class for YearMonth.
 
Field Summary
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 Summary
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(Object instant)
          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.
 
Method Summary
static YearMonth fromCalendarFields(Calendar calendar)
          Constructs a YearMonth from a java.util.Calendar using exactly the same field values avoiding any time zone effects.
static YearMonth fromDateFields(Date date)
          Constructs a YearMonth from a java.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.
 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(String str)
          Parses a YearMonth from the specified string.
static YearMonth parse(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.
 String toString()
          Output the year-month in ISO8601 format (yyyy-MM).
 String toString(String pattern)
          Output the year-month using the specified format pattern.
 String toString(String pattern, 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.
 
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 org.joda.time.ReadablePartial
equals, get, getChronology, getField, getValue, hashCode, isSupported, toDateTime
 
Methods inherited from interface java.lang.Comparable
compareTo
 

Field Detail

YEAR

public static final int YEAR
The index of the year field in the field array

See Also:
Constant Field Values

MONTH_OF_YEAR

public static final int MONTH_OF_YEAR
The index of the monthOfYear field in the field array

See Also:
Constant Field Values
Constructor Detail

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:
now()

YearMonth

public YearMonth(DateTimeZone zone)
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:
now(DateTimeZone)

YearMonth

public YearMonth(Chronology chronology)
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:
now(Chronology)

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

public YearMonth(long instant,
                 Chronology chronology)
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:00Z
chronology - the chronology, null means ISOChronology in the default zone

YearMonth

public YearMonth(Object instant)
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 by ISODateTimeFormat.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

public YearMonth(Object instant,
                 Chronology chronology)
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 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.

Parameters:
instant - the date-time object, null means now
chronology - 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 using 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).

Parameters:
year - the year
monthOfYear - the month of the year

YearMonth

public 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.

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 year
monthOfYear - the month of the year
chronology - the chronology, null means ISOChronology in the default zone
Method Detail

now

public static YearMonth now()
Obtains a YearMonth set to the current system millisecond time using ISOChronology in the default time zone. The resulting object does not use the zone.

Returns:
the current year-month, not null
Since:
2.0

now

public static YearMonth now(DateTimeZone zone)
Obtains a YearMonth set to the current system millisecond time using ISOChronology 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

public static YearMonth now(Chronology chronology)
Obtains a YearMonth 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

public static YearMonth parse(String str)
Parses a YearMonth from the specified string.

This uses ISODateTimeFormat.localDateParser().

Parameters:
str - the string to parse, not null
Since:
2.0

parse

public static YearMonth parse(String str,
                              DateTimeFormatter formatter)
Parses a YearMonth from the specified string using a formatter.

Parameters:
str - the string to parse, not null
formatter - the formatter to use, not null
Since:
2.0

fromCalendarFields

public static YearMonth fromCalendarFields(Calendar calendar)
Constructs a YearMonth from a 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.

Parameters:
calendar - the Calendar to extract fields from
Returns:
the created YearMonth, never null
Throws:
IllegalArgumentException - if the calendar is null
IllegalArgumentException - if the year or month is invalid for the ISO chronology

fromDateFields

public static YearMonth fromDateFields(Date date)
Constructs a YearMonth from a 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.

Parameters:
date - the Date to extract fields from
Returns:
the created YearMonth, never null
Throws:
IllegalArgumentException - if the calendar is null
IllegalArgumentException - 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 interface ReadablePartial
Returns:
the field count, two

getField

protected DateTimeField getField(int index,
                                 Chronology chrono)
Gets the field for a specific index in the chronology specified.

This method must not use any instance variables.

Specified by:
getField in class AbstractPartial
Parameters:
index - the index to retrieve
chrono - the chronology to use
Returns:
the field, never null

getFieldType

public DateTimeFieldType getFieldType(int index)
Gets the field type at the specified index.

Specified by:
getFieldType in interface ReadablePartial
Overrides:
getFieldType in class AbstractPartial
Parameters:
index - the index to retrieve
Returns:
the field at the specified index, never null
Throws:
IndexOutOfBoundsException - if the index is invalid

getFieldTypes

public DateTimeFieldType[] 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 class AbstractPartial
Returns:
the array of field types (cloned), largest to smallest, never null

withChronologyRetainFields

public YearMonth withChronologyRetainFields(Chronology newChronology)
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

public YearMonth withField(DateTimeFieldType fieldType,
                           int value)
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 null
value - 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

public YearMonth withFieldAdded(DurationFieldType fieldType,
                                int amount)
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 null
amount - the amount to add
Returns:
a copy of this instance with the field updated, never null
Throws:
IllegalArgumentException - if the value is null or invalid
ArithmeticException - if the new date-time exceeds the capacity

withPeriodAdded

public YearMonth withPeriodAdded(ReadablePeriod period,
                                 int scalar)
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) or plusYears(int).

Parameters:
period - the period to add to this one, null means zero
scalar - 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

public YearMonth plus(ReadablePeriod period)
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

public YearMonth plusYears(int years)
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

public YearMonth plusMonths(int months)
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

public YearMonth minus(ReadablePeriod period)
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

public YearMonth minusYears(int years)
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

public YearMonth minusMonths(int months)
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

public LocalDate toLocalDate(int dayOfMonth)
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

public Interval 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

public Interval toInterval(DateTimeZone zone)
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

public YearMonth withYear(int year)
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

public YearMonth withMonthOfYear(int monthOfYear)
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

public YearMonth.Property property(DateTimeFieldType type)
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

public YearMonth.Property year()
Get the year field property which provides access to advanced functionality.

Returns:
the year property

monthOfYear

public YearMonth.Property monthOfYear()
Get the month of year field property which provides access to advanced functionality.

Returns:
the month of year property

toString

public String toString()
Output the year-month in ISO8601 format (yyyy-MM).

Specified by:
toString in interface ReadablePartial
Overrides:
toString in class Object
Returns:
ISO8601 time formatted string.

toString

public String toString(String pattern)
Output the year-month using the specified format pattern.

Overrides:
toString in class BasePartial
Parameters:
pattern - the pattern specification, null means use toString
See Also:
DateTimeFormat

toString

public String toString(String pattern,
                       Locale locale)
                throws IllegalArgumentException
Output the year-month using the specified format pattern.

Overrides:
toString in class BasePartial
Parameters:
pattern - the pattern specification, null means use toString
locale - Locale to use, null means default
Throws:
IllegalArgumentException
See Also:
DateTimeFormat


Copyright © 2002-2012 Joda.org. All Rights Reserved.