YearMonthDay is an immutable partial supporting the year, monthOfYear
and dayOfMonth fields.
NOTE: This class only supports the three fields listed above. Thus, you
cannot query the dayOfWeek or centuryOfEra fields for example.
The new
LocalDate
class removes this restriction.
Calculations on YearMonthDay are performed using a
Chronology
.
This chronology is set to be in the UTC time zone for all calculations.
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()
YearMonthDay is thread-safe and immutable, provided that the Chronology is as well.
All standard Chronology classes supplied are thread-safe and immutable.
YearMonthDay
public YearMonthDay()
Constructs a YearMonthDay with the current date, 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 timezone (by switching to UTC).
YearMonthDay
public YearMonthDay(Object instant)
instant
- the datetime object, null means now
YearMonthDay
public YearMonthDay(Object instant,
Chronology chronology)
Constructs a YearMonthDay from an Object that represents a 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.dateOptionalTimeParser()
.
The constructor uses the time zone of the chronology specified.
Once the constructor is complete, all further calculations are performed
without reference to a timezone (by switching to UTC).
The specified chronology overrides that of the object.
NOTE: Prior to v1.3 the string format was described by
ISODateTimeFormat.dateTimeParser()
. Time only strings are now rejected.
instant
- the datetime object, null means nowchronology
- the chronology, null means ISO default
YearMonthDay
public YearMonthDay(int year,
int monthOfYear,
int dayOfMonth)
Constructs a YearMonthDay with specified time field values
using
ISOChronology
in the default zone.
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 timezone (by switching to UTC).
year
- the yearmonthOfYear
- the month of the yeardayOfMonth
- the day of the month
YearMonthDay
public YearMonthDay(int year,
int monthOfYear,
int dayOfMonth,
Chronology chronology)
Constructs a YearMonthDay with specified time field values.
The constructor uses the time zone of the chronology specified.
Once the constructor is complete, all further calculations are performed
without reference to a timezone (by switching to UTC).
year
- the yearmonthOfYear
- the month of the yeardayOfMonth
- the day of the monthchronology
- the chronology, null means ISOChronology in the default zone
YearMonthDay
public YearMonthDay(long instant)
Constructs a YearMonthDay 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 timezone (by switching to UTC).
instant
- the milliseconds from 1970-01-01T00:00:00Z
YearMonthDay
public YearMonthDay(long instant,
Chronology chronology)
Constructs a YearMonthDay 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 timezone (by switching to UTC).
instant
- the milliseconds from 1970-01-01T00:00:00Zchronology
- the chronology, null means ISOChronology in the default zone
YearMonthDay
public YearMonthDay(Chronology chronology)
Constructs a YearMonthDay with the current date, 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 timezone (by switching to UTC).
chronology
- the chronology, null means ISOChronology in the default zone
YearMonthDay
public YearMonthDay(DateTimeZone zone)
Constructs a YearMonthDay with the current date, using ISOChronology in
the specified zone to extract the fields.
The constructor uses the specified time zone to obtain the current date.
Once the constructor is complete, all further calculations
are performed without reference to a timezone (by switching to UTC).
zone
- the zone to use, null means default zone
dayOfMonth
public YearMonthDay.Property dayOfMonth()
Get the day of month field property which provides access to advanced functionality.
- the day of month property
fromCalendarFields
public static YearMonthDay fromCalendarFields(Calendar calendar)
Constructs a YearMonthDay 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 YearMonthDay.
This is useful if you have been using the Calendar as a local date,
ignoing the zone.
This factory method ignores the type of the calendar and always
creates a YearMonthDay 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 from
fromDateFields
public static YearMonthDay fromDateFields(Date date)
Constructs a YearMonthDay 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 YearMonthDay.
This is useful if you have been using the Date as a local date,
ignoing the zone.
This factory method always creates a YearMonthDay with ISO chronology.
date
- the Date to extract fields from
getDayOfMonth
public int getDayOfMonth()
Get the day of month field value.
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.
- getField in interface AbstractPartial
index
- the index to retrievechrono
- the chronology to use
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, Day
- getFieldTypes in interface AbstractPartial
- the array of field types (cloned), largest to smallest
getMonthOfYear
public int getMonthOfYear()
Get the month of year field value.
getYear
public int getYear()
Get the year field value.
minus
public YearMonthDay minus(ReadablePeriod period)
Returns a copy of this date 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)
.
period
- the period to reduce this instant by
- a copy of this instance with the period taken away
minusDays
public YearMonthDay minusDays(int days)
Returns a copy of this date minus the specified number of days.
This datetime instance is immutable and unaffected by this method call.
The following three lines are identical in effect:
YearMonthDay subtracted = dt.minusDays(6);
YearMonthDay subtracted = dt.minus(Period.days(6));
YearMonthDay subtracted = dt.withFieldAdded(DurationFieldType.days(), -6);
days
- the amount of days to subtract, may be negative
- the new datetime minus the increased days
minusMonths
public YearMonthDay minusMonths(int months)
Returns a copy of this date minus the specified number of months.
This datetime instance is immutable and unaffected by this method call.
The following three lines are identical in effect:
YearMonthDay subtracted = dt.minusMonths(6);
YearMonthDay subtracted = dt.minus(Period.months(6));
YearMonthDay subtracted = dt.withFieldAdded(DurationFieldType.months(), -6);
months
- the amount of months to subtract, may be negative
- the new datetime minus the increased months
minusYears
public YearMonthDay minusYears(int years)
Returns a copy of this date minus the specified number of years.
This datetime instance is immutable and unaffected by this method call.
The following three lines are identical in effect:
YearMonthDay subtracted = dt.minusYears(6);
YearMonthDay subtracted = dt.minus(Period.years(6));
YearMonthDay subtracted = dt.withFieldAdded(DurationFieldType.years(), -6);
years
- the amount of years to subtract, may be negative
- the new datetime minus the increased years
monthOfYear
public YearMonthDay.Property monthOfYear()
Get the month of year field property which provides access to advanced functionality.
- the month of year property
plus
public YearMonthDay plus(ReadablePeriod period)
Returns a copy of this date 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)
.
period
- the duration to add to this one, null means zero
- a copy of this instance with the period added
plusDays
public YearMonthDay plusDays(int days)
Returns a copy of this date plus the specified number of days.
This date instance is immutable and unaffected by this method call.
The following three lines are identical in effect:
YearMonthDay added = dt.plusDays(6);
YearMonthDay added = dt.plus(Period.days(6));
YearMonthDay added = dt.withFieldAdded(DurationFieldType.days(), 6);
days
- the amount of days to add, may be negative
- the new date plus the increased days
plusMonths
public YearMonthDay plusMonths(int months)
Returns a copy of this date plus the specified number of months.
This date instance is immutable and unaffected by this method call.
The following three lines are identical in effect:
YearMonthDay added = dt.plusMonths(6);
YearMonthDay added = dt.plus(Period.months(6));
YearMonthDay added = dt.withFieldAdded(DurationFieldType.months(), 6);
months
- the amount of months to add, may be negative
- the new date plus the increased months
plusYears
public YearMonthDay plusYears(int years)
Returns a copy of this date plus the specified number of years.
This date instance is immutable and unaffected by this method call.
The following three lines are identical in effect:
YearMonthDay added = dt.plusYears(6);
YearMonthDay added = dt.plus(Period.years(6));
YearMonthDay added = dt.withFieldAdded(DurationFieldType.years(), 6);
years
- the amount of years to add, may be negative
- the new date plus the increased years
property
public YearMonthDay.Property property(DateTimeFieldType type)
Gets the property object for the specified type, which contains
many useful methods.
type
- the field type to get the property for
size
public int size()
Gets the number of fields in this partial.
- size in interface ReadablePartial
toDateMidnight
public DateMidnight toDateMidnight()
Converts this object to a DateMidnight in the default time zone.
- the DateMidnight instance in the default zone
toDateMidnight
public DateMidnight toDateMidnight(DateTimeZone zone)
Converts this object to a DateMidnight.
zone
- the zone to get the DateMidnight in, null means default
- the DateMidnight instance
toDateTime
public DateTime toDateTime(TimeOfDay time)
Converts this object to a DateTime using a TimeOfDay to fill in the
missing fields and using the default time zone.
This instance is immutable and unaffected by this method call.
The resulting chronology is determined by the chronology of this
YearMonthDay plus the time zone.
The chronology of the time is ignored - only the field values are used.
time
- the time of day to use, null means current time
toDateTime
public DateTime toDateTime(TimeOfDay time,
DateTimeZone zone)
Converts this object to a DateTime using a TimeOfDay to fill in the
missing fields.
This instance is immutable and unaffected by this method call.
The resulting chronology is determined by the chronology of this
YearMonthDay plus the time zone.
The chronology of the time is ignored - only the field values are used.
time
- the time of day to use, null means current timezone
- the zone to get the DateTime in, null means default
toDateTimeAtCurrentTime
public DateTime toDateTimeAtCurrentTime()
Converts this partial to a full datetime using the default time zone
setting the date fields from this instance and the time fields from
the current time.
- this date as a datetime with the time as the current time
toDateTimeAtCurrentTime
public DateTime toDateTimeAtCurrentTime(DateTimeZone zone)
Converts this partial to a full datetime using the specified time zone
setting the date fields from this instance and the time fields from
the current time.
This method uses the chronology from this instance plus the time zone
specified.
zone
- the zone to use, null means default
- this date as a datetime with the time as the current time
toDateTimeAtMidnight
public DateTime toDateTimeAtMidnight()
Converts this YearMonthDay to a full datetime at midnight using the
default time zone.
- this date as a datetime at midnight
toDateTimeAtMidnight
public DateTime toDateTimeAtMidnight(DateTimeZone zone)
Converts this YearMonthDay to a full datetime at midnight using the
specified time zone.
This method uses the chronology from this instance plus the time zone
specified.
zone
- the zone to use, null means default
- this date as a datetime at midnight
toInterval
public Interval toInterval()
Converts this object to an Interval representing the whole day
in the default time zone.
toInterval
public Interval toInterval(DateTimeZone zone)
Converts this object to an Interval representing the whole day.
zone
- the zone to get the Interval in, null means default
toLocalDate
public LocalDate toLocalDate()
Converts this object to a LocalDate with the same date and chronology.
- a LocalDate with the same date and chronology
toString
public String toString()
Output the date in the ISO8601 format YYYY-MM-DD.
- toString in interface ReadablePartial
withChronologyRetainFields
public YearMonthDay withChronologyRetainFields(Chronology newChronology)
Returns a copy of this date 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 YearMonthDay
operates without a time zone.
newChronology
- the new chronology, null means ISO
- a copy of this datetime with a different chronology
withDayOfMonth
public YearMonthDay withDayOfMonth(int dayOfMonth)
Returns a copy of this date with the day of month field updated.
YearMonthDay is immutable, so there are no set methods.
Instead, this method returns a new instance with the value of
day of month changed.
dayOfMonth
- the day of month to set
- a copy of this object with the field set
withField
public YearMonthDay withField(DateTimeFieldType fieldType,
int value)
Returns a copy of this date 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:
YearMonthDay updated = ymd.withField(DateTimeFieldType.dayOfMonth(), 6);
YearMonthDay updated = ymd.dayOfMonth().setCopy(6);
YearMonthDay updated = ymd.property(DateTimeFieldType.dayOfMonth()).setCopy(6);
fieldType
- the field type to set, not nullvalue
- the value to set
- a copy of this instance with the field set
withFieldAdded
public YearMonthDay withFieldAdded(DurationFieldType fieldType,
int amount)
Returns a copy of this date with the value of the specified field increased.
If the addition is zero, then
this
is returned.
These three lines are equivalent:
YearMonthDay added = ymd.withFieldAdded(DurationFieldType.days(), 6);
YearMonthDay added = ymd.plusDays(6);
YearMonthDay added = ymd.dayOfMonth().addToCopy(6);
fieldType
- the field type to add to, not nullamount
- the amount to add
- a copy of this instance with the field updated
withMonthOfYear
public YearMonthDay withMonthOfYear(int monthOfYear)
Returns a copy of this date with the month of year field updated.
YearMonthDay 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 set
- a copy of this object with the field set
withPeriodAdded
public YearMonthDay withPeriodAdded(ReadablePeriod period,
int scalar)
Returns a copy of this date 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)
.
period
- the period to add to this one, null means zeroscalar
- the amount of times to add, such as -1 to subtract once
- a copy of this instance with the period added
withYear
public YearMonthDay withYear(int year)
Returns a copy of this date with the year field updated.
YearMonthDay is immutable, so there are no set methods.
Instead, this method returns a new instance with the value of
year changed.
- a copy of this object with the field set
year
public YearMonthDay.Property year()
Get the year field property which provides access to advanced functionality.