org.joda.time
Class MonthDay

java.lang.Object
  org.joda.time.base.AbstractPartial
      org.joda.time.base.BasePartial
          org.joda.time.MonthDay

All Implemented Interfaces:

Serializable, Comparable<ReadablePartial>, ReadablePartial

public final class MonthDay
extends BasePartial
implements ReadablePartial, Serializable

MonthDay is an immutable partial supporting the monthOfYear and dayOfMonth 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 MonthDay 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 birthday without the year (to avoid storing the age of the person). This class can be used as the gMonthDay type in XML Schema.

Each individual field can be queried in two ways:

• getMonthOfYear()
• monthOfYear().get()

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

• 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()

MonthDay 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:

Chris Pheby

See Also:

Serialized Form

Nested Class Summary

static class

MonthDay.Property The property class for MonthDay.

Field Summary

static int	DAY_OF_MONTH The index of the day field in the field array
static int	MONTH_OF_YEAR The index of the monthOfYear field in the field array

Constructor Summary

MonthDay()
Constructs a MonthDay with the current monthOfYear, using ISOChronology in the default zone to extract the fields.

MonthDay(Chronology chronology)
Constructs a MonthDay with the current month-day, using the specified chronology and zone to extract the fields.

MonthDay(DateTimeZone zone)
Constructs a MonthDay with the current month-day, using ISOChronology in the specified zone to extract the fields.

MonthDay(int monthOfYear, int dayOfMonth)
Constructs a MonthDay with specified year and month using ISOChronology.

MonthDay(int monthOfYear, int dayOfMonth, Chronology chronology)
Constructs an instance set to the specified monthOfYear and dayOfMonth using the specified chronology, whose zone is ignored.

MonthDay(long instant)
Constructs a MonthDay extracting the partial fields from the specified milliseconds using the ISOChronology in the default zone.

MonthDay(long instant, Chronology chronology)
Constructs a MonthDay extracting the partial fields from the specified milliseconds using the chronology provided.

MonthDay(Object instant)
Constructs a MonthDay from an Object that represents some form of time.

MonthDay(Object instant, Chronology chronology)
Constructs a MonthDay from an Object that represents some form of time, using the specified chronology.

Method Summary

MonthDay.Property	dayOfMonth() Get the day of month field property which provides access to advanced functionality.
static MonthDay	fromCalendarFields(Calendar calendar) Constructs a MonthDay from a java.util.Calendar using exactly the same field values avoiding any time zone effects.
static MonthDay	fromDateFields(Date date) Constructs a MonthDay from a java.util.Date using exactly the same field values avoiding any time zone effects.
int	getDayOfMonth() Get the day of month field value.
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.
MonthDay	minus(ReadablePeriod period) Returns a copy of this month-day with the specified period taken away.
MonthDay	minusDays(int days) Returns a copy of this month-day minus the specified number of months.
MonthDay	minusMonths(int months) Returns a copy of this month-day minus the specified number of months.
MonthDay.Property	monthOfYear() Get the month of year field property which provides access to advanced functionality.
static MonthDay	now() Obtains a MonthDay set to the current system millisecond time using ISOChronology in the default time zone.
static MonthDay	now(Chronology chronology) Obtains a MonthDay set to the current system millisecond time using the specified chronology.
static MonthDay	now(DateTimeZone zone) Obtains a MonthDay set to the current system millisecond time using ISOChronology in the specified time zone.
static MonthDay	parse(String str) Parses a MonthDay from the specified string.
static MonthDay	parse(String str, DateTimeFormatter formatter) Parses a MonthDay from the specified string using a formatter.
MonthDay	plus(ReadablePeriod period) Returns a copy of this month-day with the specified period added.
MonthDay	plusDays(int days) Returns a copy of this month-day plus the specified number of days.
MonthDay	plusMonths(int months) Returns a copy of this month-day plus the specified number of months.
MonthDay.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.
LocalDate	toLocalDate(int year) Converts this object to a LocalDate with the same month-day and chronology.
String	toString() Output the month-day in ISO8601 format (--MM-dd).
String	toString(String pattern) Output the month-day using the specified format pattern.
String	toString(String pattern, Locale locale) Output the month-day using the specified format pattern.
MonthDay	withChronologyRetainFields(Chronology newChronology) Returns a copy of this month-day with the specified chronology.
MonthDay	withDayOfMonth(int dayOfMonth) Returns a copy of this month-day with the day of month field updated.
MonthDay	withField(DateTimeFieldType fieldType, int value) Returns a copy of this month-day with the specified field set to a new value.
MonthDay	withFieldAdded(DurationFieldType fieldType, int amount) Returns a copy of this month-day with the value of the specified field increased.
MonthDay	withMonthOfYear(int monthOfYear) Returns a copy of this month-day with the month of year field updated.
MonthDay	withPeriodAdded(ReadablePeriod period, int scalar) Returns a copy of this month-day with the specified period added.

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

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

DAY_OF_MONTH

public static final int DAY_OF_MONTH

The index of the day field in the field array

See Also:

Constant Field Values

Constructor Detail

MonthDay

public MonthDay()

Constructs a MonthDay with the current monthOfYear, 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()

MonthDay

public MonthDay(DateTimeZone zone)

Constructs a MonthDay with the current month-day, using ISOChronology in the specified zone to extract the fields.

The constructor uses the specified time zone to obtain the current month-day. 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)

MonthDay

public MonthDay(Chronology chronology)

Constructs a MonthDay with the current month-day, 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)

MonthDay

public MonthDay(long instant)

Constructs a MonthDay 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

MonthDay

public MonthDay(long instant,
                Chronology chronology)

Constructs a MonthDay 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

MonthDay

public MonthDay(Object instant)

Constructs a MonthDay 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

MonthDay

public MonthDay(Object instant,
                Chronology chronology)

Constructs a MonthDay 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

MonthDay

public MonthDay(int monthOfYear,
                int dayOfMonth)

Constructs a MonthDay 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:

monthOfYear - the month of the year

dayOfMonth - the day of the month

MonthDay

public MonthDay(int monthOfYear,
                int dayOfMonth,
                Chronology chronology)

Constructs an instance set to the specified monthOfYear and dayOfMonth 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:

monthOfYear - the month of the year

dayOfMonth - the day of the month

chronology - the chronology, null means ISOChronology in the default zone

Method Detail

now

public static MonthDay now()

Obtains a MonthDay 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 month-day, not null

Since:

2.0

now

public static MonthDay now(DateTimeZone zone)

Obtains a MonthDay 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 month-day, not null

Since:

2.0

now

public static MonthDay now(Chronology chronology)

Obtains a MonthDay 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 month-day, not null

Since:

2.0

parse

public static MonthDay parse(String str)

Parses a MonthDay from the specified string.

This uses ISODateTimeFormat.localDateParser() or the format --MM-dd.

Parameters:

str - the string to parse, not null

Since:

2.0

parse

public static MonthDay parse(String str,
                             DateTimeFormatter formatter)

Parses a MonthDay 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 MonthDay fromCalendarFields(Calendar calendar)

Constructs a MonthDay 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 MonthDay.

This factory method ignores the type of the calendar and always creates a MonthDay 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 MonthDay, never null

Throws:

IllegalArgumentException - if the calendar is null

IllegalArgumentException - if the monthOfYear or dayOfMonth is invalid for the ISO chronology

fromDateFields

public static MonthDay fromDateFields(Date date)

Constructs a MonthDay 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 MonthDay.

This factory method always creates a MonthDay with ISO chronology.

Parameters:

date - the Date to extract fields from

Returns:

the created MonthDay, never null

Throws:

IllegalArgumentException - if the calendar is null

IllegalArgumentException - if the monthOfYear or dayOfMonth 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 MonthOfYear and DayOfMonth. 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, Month, Day.

Overrides:

getFieldTypes in class AbstractPartial

Returns:

the array of field types (cloned), largest to smallest, never null

withChronologyRetainFields

public MonthDay withChronologyRetainFields(Chronology newChronology)

Returns a copy of this month-day 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 MonthDay operates without a time zone.

Parameters:

newChronology - the new chronology, null means ISO

Returns:

a copy of this month-day with a different chronology, never null

Throws:

IllegalArgumentException - if the values are invalid for the new chronology

withField

public MonthDay withField(DateTimeFieldType fieldType,
                          int value)

Returns a copy of this month-day with the specified field set to a new value.

For example, if the field type is dayOfMonth then the day would be changed in the returned instance.

These three lines are equivalent:

 MonthDay updated = md.withField(DateTimeFieldType.dayOfMonth(), 6);
 MonthDay updated = md.dayOfMonth().setCopy(6);
 MonthDay updated = md.property(DateTimeFieldType.dayOfMonth()).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 MonthDay withFieldAdded(DurationFieldType fieldType,
                               int amount)

Returns a copy of this month-day with the value of the specified field increased.

If the addition is zero, then this is returned.

These three lines are equivalent:

 MonthDay added = md.withFieldAdded(DurationFieldType.days(), 6);
 MonthDay added = md.plusDays(6);
 MonthDay added = md.dayOfMonth().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 MonthDay withPeriodAdded(ReadablePeriod period,
                                int scalar)

Returns a copy of this month-day 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 plusMonths(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 MonthDay plus(ReadablePeriod period)

Returns a copy of this month-day 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 plusMonths(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 month-day exceeds the capacity

plusMonths

public MonthDay plusMonths(int months)

Returns a copy of this month-day plus the specified number of months.

This month-day instance is immutable and unaffected by this method call. The month will wrap at the end of the year from December to January. The day will be adjusted to the last valid value if necessary.

The following three lines are identical in effect:

 MonthDay added = md.plusMonths(6);
 MonthDay added = md.plus(Period.months(6));
 MonthDay added = md.withFieldAdded(DurationFieldType.months(), 6);
 

Parameters:

months - the amount of months to add, may be negative

Returns:

the new month-day plus the increased months, never null

plusDays

public MonthDay plusDays(int days)

Returns a copy of this month-day plus the specified number of days.

This month-day instance is immutable and unaffected by this method call. The month will wrap at the end of the year from December to January.

The following three lines are identical in effect:

 MonthDay added = md.plusDays(6);
 MonthDay added = md.plus(Period.days(6));
 MonthDay added = md.withFieldAdded(DurationFieldType.days(), 6);
 

Parameters:

days - the amount of days to add, may be negative

Returns:

the new month-day plus the increased days, never null

minus

public MonthDay minus(ReadablePeriod period)

Returns a copy of this month-day 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 minusMonths(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 month-day exceeds the capacity

minusMonths

public MonthDay minusMonths(int months)

Returns a copy of this month-day minus the specified number of months.

This MonthDay instance is immutable and unaffected by this method call. The month will wrap at the end of the year from January to December. The day will be adjusted to the last valid value if necessary.

The following three lines are identical in effect:

 MonthDay subtracted = md.minusMonths(6);
 MonthDay subtracted = md.minus(Period.months(6));
 MonthDay subtracted = md.withFieldAdded(DurationFieldType.months(), -6);
 

Parameters:

months - the amount of months to subtract, may be negative

Returns:

the new month-day minus the increased months, never null

minusDays

public MonthDay minusDays(int days)

Returns a copy of this month-day minus the specified number of months.

This month-day instance is immutable and unaffected by this method call. The month will wrap at the end of the year from January to December.

The following three lines are identical in effect:

 MonthDay subtracted = md.minusDays(6);
 MonthDay subtracted = md.minus(Period.days(6));
 MonthDay subtracted = md.withFieldAdded(DurationFieldType.days(), -6);
 

Parameters:

days - the amount of days to subtract, may be negative

Returns:

the new month-day minus the increased days, never null

toLocalDate

public LocalDate toLocalDate(int year)

Converts this object to a LocalDate with the same month-day and chronology.

Parameters:

year - the year to use, valid for chronology

Returns:

a LocalDate with the same month-day and chronology, never null

getMonthOfYear

public int getMonthOfYear()

Get the month of year field value.

Returns:

the month of year

getDayOfMonth

public int getDayOfMonth()

Get the day of month field value.

Returns:

the day of month

withMonthOfYear

public MonthDay withMonthOfYear(int monthOfYear)

Returns a copy of this month-day with the month of year field updated.

MonthDay 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

withDayOfMonth

public MonthDay withDayOfMonth(int dayOfMonth)

Returns a copy of this month-day with the day of month field updated.

MonthDay is immutable, so there are no set methods. Instead, this method returns a new instance with the value of day of month changed.

Parameters:

dayOfMonth - the day of month to set

Returns:

a copy of this object with the field set, never null

Throws:

IllegalArgumentException - if the value is invalid

property

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

monthOfYear

public MonthDay.Property monthOfYear()

Get the month of year field property which provides access to advanced functionality.

Returns:

the month of year property

dayOfMonth

public MonthDay.Property dayOfMonth()

Get the day of month field property which provides access to advanced functionality.

Returns:

the day of month property

toString

public String toString()

Output the month-day in ISO8601 format (--MM-dd).

Specified by:

toString in interface ReadablePartial

Overrides:

toString in class Object

Returns:

ISO8601 time formatted string.

toString

public String toString(String pattern)

Output the month-day 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 month-day 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