* LocalDateTime implements the {@link ReadablePartial} interface. * To do this, certain methods focus on key fields Year, MonthOfYear, * DayOfYear and MillisOfDay. * However, all fields may in fact be queried. *
* Internally, LocalDateTime uses a single millisecond-based value to * represent the local datetime. This value is only used internally and * is not exposed to applications. *
* Calculations on LocalDateTime are performed using a {@link Chronology}. * This chronology will be set internally to be in the UTC time zone * for all calculations. * *
Each individual field can be queried in two ways: *
getHourOfDay()
* hourOfDay().get()
*
* LocalDateTime is thread-safe and immutable, provided that the Chronology is as well.
* All standard Chronology classes supplied are thread-safe and immutable.
*
* @author Stephen Colebourne
* @since 1.3
*/
public final class LocalDateTime
extends BaseLocal
implements ReadablePartial, Serializable {
/** Serialization lock */
private static final long serialVersionUID = -268716875315837168L;
/** The index of the year field in the field array */
private static final int YEAR = 0;
/** The index of the monthOfYear field in the field array */
private static final int MONTH_OF_YEAR = 1;
/** The index of the dayOfMonth field in the field array */
private static final int DAY_OF_MONTH = 2;
/** The index of the millis field in the field array */
private static final int MILLIS_OF_DAY = 3;
/** The local millis from 1970-01-01T00:00:00 */
private final long iLocalMillis;
/** The chronology to use in UTC */
private final Chronology iChronology;
//-----------------------------------------------------------------------
/**
* Obtains a {@code LocalDateTime} set to the current system millisecond time
* using ISOChronology in the default time zone.
* The resulting object does not use the zone.
*
* @return the current date, not null
* @since 2.0
*/
public static LocalDateTime now() {
return new LocalDateTime();
}
/**
* Obtains a {@code LocalDateTime} set to the current system millisecond time
* using ISOChronology in the specified time zone.
* The resulting object does not use the zone.
*
* @param zone the time zone, not null
* @return the current date, not null
* @since 2.0
*/
public static LocalDateTime now(DateTimeZone zone) {
if (zone == null) {
throw new NullPointerException("Zone must not be null");
}
return new LocalDateTime(zone);
}
/**
* Obtains a {@code LocalDateTime} set to the current system millisecond time
* using the specified chronology.
* The resulting object does not use the zone.
*
* @param chronology the chronology, not null
* @return the current date, not null
* @since 2.0
*/
public static LocalDateTime now(Chronology chronology) {
if (chronology == null) {
throw new NullPointerException("Chronology must not be null");
}
return new LocalDateTime(chronology);
}
//-----------------------------------------------------------------------
/**
* Parses a {@code LocalDateTime} from the specified string.
*
* This uses {@link ISODateTimeFormat#localDateOptionalTimeParser()}.
*
* @param str the string to parse, not null
* @since 2.0
*/
@FromString
public static LocalDateTime parse(String str) {
return parse(str, ISODateTimeFormat.localDateOptionalTimeParser());
}
/**
* Parses a {@code LocalDateTime} from the specified string using a formatter.
*
* @param str the string to parse, not null
* @param formatter the formatter to use, not null
* @since 2.0
*/
public static LocalDateTime parse(String str, DateTimeFormatter formatter) {
return formatter.parseLocalDateTime(str);
}
//-----------------------------------------------------------------------
/**
* Constructs a LocalDateTime from a java.util.Calendar
* using exactly the same field values.
*
* Each field is queried from the Calendar and assigned to the LocalDateTime. * This is useful if you have been using the Calendar as a local date, * ignoring the zone. *
* One advantage of this method is that this method is unaffected if the * version of the time zone data differs between the JDK and Joda-Time. * That is because the local field values are transferred, calculated using * the JDK time zone data and without using the Joda-Time time zone data. *
* This factory method ignores the type of the calendar and always
* creates a LocalDateTime with ISO chronology. It is expected that you
* will only pass in instances of GregorianCalendar however
* this is not validated.
*
* @param calendar the Calendar to extract fields from
* @return the created LocalDateTime
* @throws IllegalArgumentException if the calendar is null
* @throws IllegalArgumentException if the date is invalid for the ISO chronology
*/
public static LocalDateTime fromCalendarFields(Calendar calendar) {
if (calendar == null) {
throw new IllegalArgumentException("The calendar must not be null");
}
return new LocalDateTime(
calendar.get(Calendar.YEAR),
calendar.get(Calendar.MONTH) + 1,
calendar.get(Calendar.DAY_OF_MONTH),
calendar.get(Calendar.HOUR_OF_DAY),
calendar.get(Calendar.MINUTE),
calendar.get(Calendar.SECOND),
calendar.get(Calendar.MILLISECOND)
);
}
/**
* Constructs a LocalDateTime from a java.util.Date
* using exactly the same field values.
*
* Each field is queried from the Date and assigned to the LocalDateTime. * This is useful if you have been using the Date as a local date, * ignoring the zone. *
* One advantage of this method is that this method is unaffected if the * version of the time zone data differs between the JDK and Joda-Time. * That is because the local field values are transferred, calculated using * the JDK time zone data and without using the Joda-Time time zone data. *
* This factory method always creates a LocalDateTime with ISO chronology. * * @param date the Date to extract fields from * @return the created LocalDateTime * @throws IllegalArgumentException if the calendar is null * @throws IllegalArgumentException if the date is invalid for the ISO chronology */ @SuppressWarnings("deprecation") public static LocalDateTime fromDateFields(Date date) { if (date == null) { throw new IllegalArgumentException("The date must not be null"); } return new LocalDateTime( date.getYear() + 1900, date.getMonth() + 1, date.getDate(), date.getHours(), date.getMinutes(), date.getSeconds(), (int) (date.getTime() % 1000) ); } //----------------------------------------------------------------------- /** * Constructs an instance set to the current local time evaluated using * ISO chronology in the default zone. *
* Once the constructor is completed, the zone is no longer used. * * @see #now() */ public LocalDateTime() { this(DateTimeUtils.currentTimeMillis(), ISOChronology.getInstance()); } /** * Constructs an instance set to the current local time evaluated using * ISO chronology in the specified zone. *
* If the specified time zone is null, the default zone is used. * Once the constructor is completed, the zone is no longer used. * * @param zone the time zone, null means default zone * @see #now(DateTimeZone) */ public LocalDateTime(DateTimeZone zone) { this(DateTimeUtils.currentTimeMillis(), ISOChronology.getInstance(zone)); } /** * Constructs an instance set to the current local time evaluated using * specified chronology. *
* If the chronology is null, ISO chronology in the default time zone is used. * Once the constructor is completed, the zone is no longer used. * * @param chronology the chronology, null means ISOChronology in default zone * @see #now(Chronology) */ public LocalDateTime(Chronology chronology) { this(DateTimeUtils.currentTimeMillis(), chronology); } //----------------------------------------------------------------------- /** * Constructs an instance set to the local time defined by the specified * instant evaluated using ISO chronology in the default zone. *
* Once the constructor is completed, the zone is no longer used. * * @param instant the milliseconds from 1970-01-01T00:00:00Z */ public LocalDateTime(long instant) { this(instant, ISOChronology.getInstance()); } /** * Constructs an instance set to the local time defined by the specified * instant evaluated using ISO chronology in the specified zone. *
* If the specified time zone is null, the default zone is used. * Once the constructor is completed, the zone is no longer used. * * @param instant the milliseconds from 1970-01-01T00:00:00Z * @param zone the time zone, null means default zone */ public LocalDateTime(long instant, DateTimeZone zone) { this(instant, ISOChronology.getInstance(zone)); } /** * Constructs an instance set to the local time defined by the specified * instant evaluated using the specified chronology. *
* If the chronology is null, ISO chronology in the default zone is used. * Once the constructor is completed, the zone is no longer used. * * @param instant the milliseconds from 1970-01-01T00:00:00Z * @param chronology the chronology, null means ISOChronology in default zone */ public LocalDateTime(long instant, Chronology chronology) { chronology = DateTimeUtils.getChronology(chronology); long localMillis = chronology.getZone().getMillisKeepLocal(DateTimeZone.UTC, instant); iLocalMillis = localMillis; iChronology = chronology.withUTC(); } //----------------------------------------------------------------------- /** * Constructs an instance from an Object that represents a datetime. *
* If the object contains no chronology, ISOChronology is used.
* If the object contains no time zone, the default zone is used.
* Once the constructor is completed, the zone is no longer used.
*
* The recognised object types are defined in * {@link org.joda.time.convert.ConverterManager ConverterManager} and * include ReadablePartial, ReadableInstant, String, Calendar and Date. * The String formats are described by {@link ISODateTimeFormat#localDateOptionalTimeParser()}. * The default String converter ignores the zone and only parses the field values. * * @param instant the datetime object * @throws IllegalArgumentException if the instant is invalid */ public LocalDateTime(Object instant) { this(instant, (Chronology) null); } /** * Constructs an instance from an Object that represents a datetime, * forcing the time zone to that specified. *
* If the object contains no chronology, ISOChronology is used.
* If the specified time zone is null, the default zone is used.
* Once the constructor is completed, the zone is no longer used.
*
* The recognised object types are defined in * {@link org.joda.time.convert.ConverterManager ConverterManager} and * include ReadablePartial, ReadableInstant, String, Calendar and Date. * The String formats are described by {@link ISODateTimeFormat#localDateOptionalTimeParser()}. * The default String converter ignores the zone and only parses the field values. * * @param instant the datetime object * @param zone the time zone * @throws IllegalArgumentException if the instant is invalid */ public LocalDateTime(Object instant, DateTimeZone zone) { PartialConverter converter = ConverterManager.getInstance().getPartialConverter(instant); Chronology chronology = converter.getChronology(instant, zone); chronology = DateTimeUtils.getChronology(chronology); iChronology = chronology.withUTC(); int[] values = converter.getPartialValues(this, instant, chronology, ISODateTimeFormat.localDateOptionalTimeParser()); iLocalMillis = iChronology.getDateTimeMillis(values[0], values[1], values[2], values[3]); } /** * Constructs an instance from an Object that represents a datetime, * using the specified chronology. *
* If the chronology is null, ISO in the default time zone is used. * Once the constructor is completed, the zone is no longer used. *
* The recognised object types are defined in
* {@link org.joda.time.convert.ConverterManager ConverterManager} and
* include ReadablePartial, ReadableInstant, String, Calendar and Date.
* The String formats are described by {@link ISODateTimeFormat#localDateOptionalTimeParser()}.
* The default String converter ignores the zone and only parses the field values.
*
* @param instant the datetime object
* @param chronology the chronology
* @throws IllegalArgumentException if the instant is invalid
*/
public LocalDateTime(Object instant, Chronology chronology) {
PartialConverter converter = ConverterManager.getInstance().getPartialConverter(instant);
chronology = converter.getChronology(instant, chronology);
chronology = DateTimeUtils.getChronology(chronology);
iChronology = chronology.withUTC();
int[] values = converter.getPartialValues(this, instant, chronology, ISODateTimeFormat.localDateOptionalTimeParser());
iLocalMillis = iChronology.getDateTimeMillis(values[0], values[1], values[2], values[3]);
}
//-----------------------------------------------------------------------
/**
* Constructs an instance set to the specified date and time
* using ISOChronology.
*
* @param year the year
* @param monthOfYear the month of the year
* @param dayOfMonth the day of the month
* @param hourOfDay the hour of the day
* @param minuteOfHour the minute of the hour
*/
public LocalDateTime(
int year,
int monthOfYear,
int dayOfMonth,
int hourOfDay,
int minuteOfHour) {
this(year, monthOfYear, dayOfMonth, hourOfDay,
minuteOfHour, 0, 0, ISOChronology.getInstanceUTC());
}
/**
* Constructs an instance set to the specified date and time
* using ISOChronology.
*
* @param year the year
* @param monthOfYear the month of the year
* @param dayOfMonth the day of the month
* @param hourOfDay the hour of the day
* @param minuteOfHour the minute of the hour
* @param secondOfMinute the second of the minute
*/
public LocalDateTime(
int year,
int monthOfYear,
int dayOfMonth,
int hourOfDay,
int minuteOfHour,
int secondOfMinute) {
this(year, monthOfYear, dayOfMonth, hourOfDay,
minuteOfHour, secondOfMinute, 0, ISOChronology.getInstanceUTC());
}
/**
* Constructs an instance set to the specified date and time
* using ISOChronology.
*
* @param year the year
* @param monthOfYear the month of the year
* @param dayOfMonth the day of the month
* @param hourOfDay the hour of the day
* @param minuteOfHour the minute of the hour
* @param secondOfMinute the second of the minute
* @param millisOfSecond the millisecond of the second
*/
public LocalDateTime(
int year,
int monthOfYear,
int dayOfMonth,
int hourOfDay,
int minuteOfHour,
int secondOfMinute,
int millisOfSecond) {
this(year, monthOfYear, dayOfMonth, hourOfDay,
minuteOfHour, secondOfMinute, millisOfSecond, ISOChronology.getInstanceUTC());
}
/**
* Constructs an instance set to the specified date and time
* using the specified chronology, whose zone is ignored.
*
* If the chronology is null, ISOChronology is used.
*
* @param year the year
* @param monthOfYear the month of the year
* @param dayOfMonth the day of the month
* @param hourOfDay the hour of the day
* @param minuteOfHour the minute of the hour
* @param secondOfMinute the second of the minute
* @param millisOfSecond the millisecond of the second
* @param chronology the chronology, null means ISOChronology in default zone
*/
public LocalDateTime(
int year,
int monthOfYear,
int dayOfMonth,
int hourOfDay,
int minuteOfHour,
int secondOfMinute,
int millisOfSecond,
Chronology chronology) {
super();
chronology = DateTimeUtils.getChronology(chronology).withUTC();
long instant = chronology.getDateTimeMillis(year, monthOfYear, dayOfMonth,
hourOfDay, minuteOfHour, secondOfMinute, millisOfSecond);
iChronology = chronology;
iLocalMillis = instant;
}
/**
* Handle broken serialization from other tools.
* @return the resolved object, not null
*/
private Object readResolve() {
if (iChronology == null) {
return new LocalDateTime(iLocalMillis, ISOChronology.getInstanceUTC());
}
if (DateTimeZone.UTC.equals(iChronology.getZone()) == false) {
return new LocalDateTime(iLocalMillis, iChronology.withUTC());
}
return this;
}
//-----------------------------------------------------------------------
/**
* Gets the number of fields in this partial, which is four.
* The supported fields are Year, MonthOfDay, DayOfMonth and MillisOfDay.
*
* @return the field count, four
*/
public int size() {
return 4;
}
/**
* Gets the field for a specific index in the chronology specified.
*
* This method must not use any instance variables. * * @param index the index to retrieve * @param chrono the chronology to use * @return the field */ protected DateTimeField getField(int index, Chronology chrono) { switch (index) { case YEAR: return chrono.year(); case MONTH_OF_YEAR: return chrono.monthOfYear(); case DAY_OF_MONTH: return chrono.dayOfMonth(); case MILLIS_OF_DAY: return chrono.millisOfDay(); default: throw new IndexOutOfBoundsException("Invalid index: " + index); } } /** * Gets the value of the field at the specifed index. *
* This method is required to support the ReadablePartial
* interface. The supported fields are Year, MonthOfDay, DayOfMonth and MillisOfDay.
*
* @param index the index, zero to two
* @return the value
* @throws IndexOutOfBoundsException if the index is invalid
*/
public int getValue(int index) {
switch (index) {
case YEAR:
return getChronology().year().get(getLocalMillis());
case MONTH_OF_YEAR:
return getChronology().monthOfYear().get(getLocalMillis());
case DAY_OF_MONTH:
return getChronology().dayOfMonth().get(getLocalMillis());
case MILLIS_OF_DAY:
return getChronology().millisOfDay().get(getLocalMillis());
default:
throw new IndexOutOfBoundsException("Invalid index: " + index);
}
}
//-----------------------------------------------------------------------
/**
* Get the value of one of the fields of a datetime.
*
* This method gets the value of the specified field. * For example: *
* DateTime dt = new DateTime();
* int year = dt.get(DateTimeFieldType.year());
*
*
* @param type a field type, usually obtained from DateTimeFieldType, not null
* @return the value of that field
* @throws IllegalArgumentException if the field type is null
*/
public int get(DateTimeFieldType type) {
if (type == null) {
throw new IllegalArgumentException("The DateTimeFieldType must not be null");
}
return type.getField(getChronology()).get(getLocalMillis());
}
/**
* Checks if the field type specified is supported by this
* local datetime and chronology.
* This can be used to avoid exceptions in {@link #get(DateTimeFieldType)}.
*
* @param type a field type, usually obtained from DateTimeFieldType
* @return true if the field type is supported
*/
public boolean isSupported(DateTimeFieldType type) {
if (type == null) {
return false;
}
return type.getField(getChronology()).isSupported();
}
/**
* Checks if the duration type specified is supported by this
* local datetime and chronology.
*
* @param type a duration type, usually obtained from DurationFieldType
* @return true if the field type is supported
*/
public boolean isSupported(DurationFieldType type) {
if (type == null) {
return false;
}
return type.getField(getChronology()).isSupported();
}
//-----------------------------------------------------------------------
/**
* Gets the milliseconds of the datetime instant from the Java epoch
* of 1970-01-01T00:00:00 (not fixed to any specific time zone).
*
* @return the number of milliseconds since 1970-01-01T00:00:00
* @since 1.5 (previously private)
*/
protected long getLocalMillis() {
return iLocalMillis;
}
/**
* Gets the chronology of the datetime.
*
* @return the Chronology that the datetime is using
*/
public Chronology getChronology() {
return iChronology;
}
//-----------------------------------------------------------------------
/**
* Compares this ReadablePartial with another returning true if the chronology,
* field types and values are equal.
*
* @param partial an object to check against
* @return true if fields and values are equal
*/
public boolean equals(Object partial) {
// override to perform faster
if (this == partial) {
return true;
}
if (partial instanceof LocalDateTime) {
LocalDateTime other = (LocalDateTime) partial;
if (iChronology.equals(other.iChronology)) {
return iLocalMillis == other.iLocalMillis;
}
}
return super.equals(partial);
}
/**
* Compares this partial with another returning an integer
* indicating the order.
* * The fields are compared in order, from largest to smallest. * The first field that is non-equal is used to determine the result. *
* The specified object must be a partial instance whose field types * match those of this partial. * * @param partial an object to check against * @return negative if this is less, zero if equal, positive if greater * @throws ClassCastException if the partial is the wrong class * or if it has field types that don't match * @throws NullPointerException if the partial is null */ public int compareTo(ReadablePartial partial) { // override to perform faster if (this == partial) { return 0; } if (partial instanceof LocalDateTime) { LocalDateTime other = (LocalDateTime) partial; if (iChronology.equals(other.iChronology)) { return (iLocalMillis < other.iLocalMillis ? -1 : (iLocalMillis == other.iLocalMillis ? 0 : 1)); } } return super.compareTo(partial); } //----------------------------------------------------------------------- /** * Converts this object to a DateTime using the default zone. *
* This method will throw an exception if the datetime that would be
* created does not exist when the time zone is taken into account.
*
* @return this
*/
public DateTime toDateTime() {
return toDateTime((DateTimeZone) null);
}
/**
* Converts this object to a DateTime using the specified zone.
*
* This method will throw an exception if the datetime that would be
* created does not exist when the time zone is taken into account.
*
* @param zone time zone to apply, or default if null
* @return a DateTime using the same millis
*/
public DateTime toDateTime(DateTimeZone zone) {
zone = DateTimeUtils.getZone(zone);
Chronology chrono = iChronology.withZone(zone);
return new DateTime(
getYear(), getMonthOfYear(), getDayOfMonth(),
getHourOfDay(), getMinuteOfHour(),
getSecondOfMinute(), getMillisOfSecond(), chrono);
}
//-----------------------------------------------------------------------
/**
* Converts this object to a LocalDate with the same date and chronology.
*
* @return a LocalDate with the same date and chronology
*/
public LocalDate toLocalDate() {
return new LocalDate(getLocalMillis(), getChronology());
}
/**
* Converts this object to a LocalTime with the same time and chronology.
*
* @return a LocalTime with the same time and chronology
*/
public LocalTime toLocalTime() {
return new LocalTime(getLocalMillis(), getChronology());
}
//-----------------------------------------------------------------------
/**
* Get the date time as a java.util.Date.
*
* The Date object created has exactly the same fields as this
* date-time, except when the time would be invalid due to a daylight savings
* gap. In that case, the time will be set to the earliest valid time after the gap.
*
* In the case of a daylight savings overlap, the earlier instant is selected. *
* Converting to a JDK Date is full of complications as the JDK Date constructor * doesn't behave as you might expect around DST transitions. This method works * by taking a first guess and then adjusting. This also handles the situation * where the JDK time zone data differs from the Joda-Time time zone data. * * @return a Date initialised with this date-time, never null * @since 2.0 */ @SuppressWarnings("deprecation") public Date toDate() { int dom = getDayOfMonth(); Date date = new Date(getYear() - 1900, getMonthOfYear() - 1, dom, getHourOfDay(), getMinuteOfHour(), getSecondOfMinute()); date.setTime(date.getTime() + getMillisOfSecond()); LocalDateTime check = LocalDateTime.fromDateFields(date); if (check.isBefore(this)) { // DST gap // move forward in units of one minute until equal/after while (check.isBefore(this)) { date.setTime(date.getTime() + 60000); check = LocalDateTime.fromDateFields(date); } // move back in units of one second until date wrong while (check.isBefore(this) == false) { date.setTime(date.getTime() - 1000); check = LocalDateTime.fromDateFields(date); } date.setTime(date.getTime() + 1000); } else if (check.equals(this)) { // check for DST overlap Date earlier = new Date(date.getTime() - TimeZone.getDefault().getDSTSavings()); check = LocalDateTime.fromDateFields(earlier); if (check.equals(this)) { date = earlier; } } return date; } //----------------------------------------------------------------------- /** * Returns a copy of this datetime with different local millis. *
* The returned object will be a new instance of the same type.
* Only the millis will change, the chronology is kept.
* The returned object will be either be a new instance or this.
*
* @param newMillis the new millis, from 1970-01-01T00:00:00
* @return a copy of this datetime with different millis
*/
LocalDateTime withLocalMillis(long newMillis) {
return (newMillis == getLocalMillis() ? this : new LocalDateTime(newMillis, getChronology()));
}
//-----------------------------------------------------------------------
/**
* Returns a copy of this datetime with the specified date,
* retaining the time fields.
*
* If the date is already the date passed in, then this is returned.
*
* To set a single field use the properties, for example: *
* DateTime set = dt.monthOfYear().setCopy(6);
*
*
* @param year the new year value
* @param monthOfYear the new monthOfYear value
* @param dayOfMonth the new dayOfMonth value
* @return a copy of this datetime with a different date
* @throws IllegalArgumentException if any value if invalid
*/
public LocalDateTime withDate(int year, int monthOfYear, int dayOfMonth) {
Chronology chrono = getChronology();
long instant = getLocalMillis();
instant = chrono.year().set(instant, year);
instant = chrono.monthOfYear().set(instant, monthOfYear);
instant = chrono.dayOfMonth().set(instant, dayOfMonth);
return withLocalMillis(instant);
}
/**
* Returns a copy of this datetime with the specified time,
* retaining the date fields.
*
* If the time is already the time passed in, then this is returned.
*
* To set a single field use the properties, for example: *
* LocalDateTime set = dt.hourOfDay().setCopy(6);
*
*
* @param hourOfDay the hour of the day
* @param minuteOfHour the minute of the hour
* @param secondOfMinute the second of the minute
* @param millisOfSecond the millisecond of the second
* @return a copy of this datetime with a different time
* @throws IllegalArgumentException if any value if invalid
*/
public LocalDateTime withTime(int hourOfDay, int minuteOfHour, int secondOfMinute, int millisOfSecond) {
Chronology chrono = getChronology();
long instant = getLocalMillis();
instant = chrono.hourOfDay().set(instant, hourOfDay);
instant = chrono.minuteOfHour().set(instant, minuteOfHour);
instant = chrono.secondOfMinute().set(instant, secondOfMinute);
instant = chrono.millisOfSecond().set(instant, millisOfSecond);
return withLocalMillis(instant);
}
//-----------------------------------------------------------------------
/**
* Returns a copy of this datetime with the partial set of fields
* replacing those from this instance.
*
* For example, if the partial is a TimeOfDay then the time fields
* would be changed in the returned instance.
* If the partial is null, then this is returned.
*
* @param partial the partial set of fields to apply to this datetime, null ignored
* @return a copy of this datetime with a different set of fields
* @throws IllegalArgumentException if any value is invalid
*/
public LocalDateTime withFields(ReadablePartial partial) {
if (partial == null) {
return this;
}
return withLocalMillis(getChronology().set(partial, getLocalMillis()));
}
/**
* Returns a copy of this datetime with the specified field set to a new value.
*
* For example, if the field type is hourOfDay then the hour of day
* field would be changed in the returned instance.
* If the field type is null, then this is returned.
*
* These three lines are equivalent: *
* LocalDateTime updated = dt.withField(DateTimeFieldType.dayOfMonth(), 6);
* LocalDateTime updated = dt.dayOfMonth().setCopy(6);
* LocalDateTime updated = dt.property(DateTimeFieldType.dayOfMonth()).setCopy(6);
*
*
* @param fieldType the field type to set, not null
* @param value the value to set
* @return a copy of this datetime with the field set
* @throws IllegalArgumentException if the value is null or invalid
*/
public LocalDateTime withField(DateTimeFieldType fieldType, int value) {
if (fieldType == null) {
throw new IllegalArgumentException("Field must not be null");
}
long instant = fieldType.getField(getChronology()).set(getLocalMillis(), value);
return withLocalMillis(instant);
}
/**
* Returns a copy of this datetime with the value of the specified
* field increased.
*
* If the addition is zero or the field is null, then this is returned.
*
* These three lines are equivalent: *
* LocalDateTime added = dt.withFieldAdded(DurationFieldType.years(), 6);
* LocalDateTime added = dt.plusYears(6);
* LocalDateTime added = dt.plus(Period.years(6));
*
*
* @param fieldType the field type to add to, not null
* @param amount the amount to add
* @return a copy of this datetime with the field updated
* @throws IllegalArgumentException if the value is null or invalid
* @throws ArithmeticException if the result exceeds the internal capacity
*/
public LocalDateTime withFieldAdded(DurationFieldType fieldType, int amount) {
if (fieldType == null) {
throw new IllegalArgumentException("Field must not be null");
}
if (amount == 0) {
return this;
}
long instant = fieldType.getField(getChronology()).add(getLocalMillis(), amount);
return withLocalMillis(instant);
}
//-----------------------------------------------------------------------
/**
* Returns a copy of this datetime with the specified duration added.
*
* If the addition is zero, then this is returned.
*
* @param durationToAdd the duration to add to this one, null means zero
* @param scalar the amount of times to add, such as -1 to subtract once
* @return a copy of this datetime with the duration added
* @throws ArithmeticException if the result exceeds the internal capacity
*/
public LocalDateTime withDurationAdded(ReadableDuration durationToAdd, int scalar) {
if (durationToAdd == null || scalar == 0) {
return this;
}
long instant = getChronology().add(getLocalMillis(), durationToAdd.getMillis(), scalar);
return withLocalMillis(instant);
}
/**
* Returns a copy of this datetime with the specified period added.
*
* If the addition is zero, then this is returned.
*
* This method is typically used to add multiple copies of complex * period instances. Adding one field is best achieved using methods * like {@link #withFieldAdded(DurationFieldType, int)} * or {@link #plusYears(int)}. * * @param period the period to add to this one, null means zero * @param scalar the amount of times to add, such as -1 to subtract once * @return a copy of this datetime with the period added * @throws ArithmeticException if the result exceeds the internal capacity */ public LocalDateTime withPeriodAdded(ReadablePeriod period, int scalar) { if (period == null || scalar == 0) { return this; } long instant = getChronology().add(period, getLocalMillis(), scalar); return withLocalMillis(instant); } //----------------------------------------------------------------------- /** * Returns a copy of this datetime with the specified duration added. *
* If the amount is zero or null, then this is returned.
*
* @param duration the duration to add to this one, null means zero
* @return a copy of this datetime with the duration added
* @throws ArithmeticException if the result exceeds the internal capacity
*/
public LocalDateTime plus(ReadableDuration duration) {
return withDurationAdded(duration, 1);
}
/**
* Returns a copy of this datetime 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 {@link #plusYears(int)}. * * @param period the period to add to this one, null means zero * @return a copy of this datetime with the period added * @throws ArithmeticException if the result exceeds the internal capacity */ public LocalDateTime plus(ReadablePeriod period) { return withPeriodAdded(period, 1); } //----------------------------------------------------------------------- /** * Returns a copy of this datetime plus the specified number of years. *
* This LocalDateTime instance is immutable and unaffected by this method call. *
* The following three lines are identical in effect: *
* LocalDateTime added = dt.plusYears(6);
* LocalDateTime added = dt.plus(Period.years(6));
* LocalDateTime added = dt.withFieldAdded(DurationFieldType.years(), 6);
*
*
* @param years the amount of years to add, may be negative
* @return the new LocalDateTime plus the increased years
*/
public LocalDateTime plusYears(int years) {
if (years == 0) {
return this;
}
long instant = getChronology().years().add(getLocalMillis(), years);
return withLocalMillis(instant);
}
/**
* Returns a copy of this datetime plus the specified number of months.
* * This LocalDateTime instance is immutable and unaffected by this method call. *
* The following three lines are identical in effect: *
* LocalDateTime added = dt.plusMonths(6);
* LocalDateTime added = dt.plus(Period.months(6));
* LocalDateTime added = dt.withFieldAdded(DurationFieldType.months(), 6);
*
*
* @param months the amount of months to add, may be negative
* @return the new LocalDateTime plus the increased months
*/
public LocalDateTime plusMonths(int months) {
if (months == 0) {
return this;
}
long instant = getChronology().months().add(getLocalMillis(), months);
return withLocalMillis(instant);
}
/**
* Returns a copy of this datetime plus the specified number of weeks.
* * This LocalDateTime instance is immutable and unaffected by this method call. *
* The following three lines are identical in effect: *
* LocalDateTime added = dt.plusWeeks(6);
* LocalDateTime added = dt.plus(Period.weeks(6));
* LocalDateTime added = dt.withFieldAdded(DurationFieldType.weeks(), 6);
*
*
* @param weeks the amount of weeks to add, may be negative
* @return the new LocalDateTime plus the increased weeks
*/
public LocalDateTime plusWeeks(int weeks) {
if (weeks == 0) {
return this;
}
long instant = getChronology().weeks().add(getLocalMillis(), weeks);
return withLocalMillis(instant);
}
/**
* Returns a copy of this datetime plus the specified number of days.
* * This LocalDateTime instance is immutable and unaffected by this method call. *
* The following three lines are identical in effect: *
* LocalDateTime added = dt.plusDays(6);
* LocalDateTime added = dt.plus(Period.days(6));
* LocalDateTime added = dt.withFieldAdded(DurationFieldType.days(), 6);
*
*
* @param days the amount of days to add, may be negative
* @return the new LocalDateTime plus the increased days
*/
public LocalDateTime plusDays(int days) {
if (days == 0) {
return this;
}
long instant = getChronology().days().add(getLocalMillis(), days);
return withLocalMillis(instant);
}
//-----------------------------------------------------------------------
/**
* Returns a copy of this datetime plus the specified number of hours.
* * This LocalDateTime instance is immutable and unaffected by this method call. *
* The following three lines are identical in effect: *
* LocalDateTime added = dt.plusHours(6);
* LocalDateTime added = dt.plus(Period.hours(6));
* LocalDateTime added = dt.withFieldAdded(DurationFieldType.hours(), 6);
*
*
* @param hours the amount of hours to add, may be negative
* @return the new LocalDateTime plus the increased hours
*/
public LocalDateTime plusHours(int hours) {
if (hours == 0) {
return this;
}
long instant = getChronology().hours().add(getLocalMillis(), hours);
return withLocalMillis(instant);
}
/**
* Returns a copy of this datetime plus the specified number of minutes.
* * This LocalDateTime instance is immutable and unaffected by this method call. *
* The following three lines are identical in effect: *
* LocalDateTime added = dt.plusMinutes(6);
* LocalDateTime added = dt.plus(Period.minutes(6));
* LocalDateTime added = dt.withFieldAdded(DurationFieldType.minutes(), 6);
*
*
* @param minutes the amount of minutes to add, may be negative
* @return the new LocalDateTime plus the increased minutes
*/
public LocalDateTime plusMinutes(int minutes) {
if (minutes == 0) {
return this;
}
long instant = getChronology().minutes().add(getLocalMillis(), minutes);
return withLocalMillis(instant);
}
/**
* Returns a copy of this datetime plus the specified number of seconds.
* * This LocalDateTime instance is immutable and unaffected by this method call. *
* The following three lines are identical in effect: *
* LocalDateTime added = dt.plusSeconds(6);
* LocalDateTime added = dt.plus(Period.seconds(6));
* LocalDateTime added = dt.withFieldAdded(DurationFieldType.seconds(), 6);
*
*
* @param seconds the amount of seconds to add, may be negative
* @return the new LocalDateTime plus the increased seconds
*/
public LocalDateTime plusSeconds(int seconds) {
if (seconds == 0) {
return this;
}
long instant = getChronology().seconds().add(getLocalMillis(), seconds);
return withLocalMillis(instant);
}
/**
* Returns a copy of this datetime plus the specified number of millis.
* * This LocalDateTime instance is immutable and unaffected by this method call. *
* The following three lines are identical in effect: *
* LocalDateTime added = dt.plusMillis(6);
* LocalDateTime added = dt.plus(Period.millis(6));
* LocalDateTime added = dt.withFieldAdded(DurationFieldType.millis(), 6);
*
*
* @param millis the amount of millis to add, may be negative
* @return the new LocalDateTime plus the increased millis
*/
public LocalDateTime plusMillis(int millis) {
if (millis == 0) {
return this;
}
long instant = getChronology().millis().add(getLocalMillis(), millis);
return withLocalMillis(instant);
}
//-----------------------------------------------------------------------
/**
* Returns a copy of this datetime with the specified duration taken away.
*
* If the amount is zero or null, then this is returned.
*
* @param duration the duration to reduce this instant by
* @return a copy of this datetime with the duration taken away
* @throws ArithmeticException if the result exceeds the internal capacity
*/
public LocalDateTime minus(ReadableDuration duration) {
return withDurationAdded(duration, -1);
}
/**
* Returns a copy of this datetime 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 {@link #minusYears(int)}. * * @param period the period to reduce this instant by * @return a copy of this datetime with the period taken away * @throws ArithmeticException if the result exceeds the internal capacity */ public LocalDateTime minus(ReadablePeriod period) { return withPeriodAdded(period, -1); } //----------------------------------------------------------------------- /** * Returns a copy of this datetime minus the specified number of years. *
* This LocalDateTime instance is immutable and unaffected by this method call. *
* The following three lines are identical in effect: *
* LocalDateTime subtracted = dt.minusYears(6);
* LocalDateTime subtracted = dt.minus(Period.years(6));
* LocalDateTime subtracted = dt.withFieldAdded(DurationFieldType.years(), -6);
*
*
* @param years the amount of years to subtract, may be negative
* @return the new LocalDateTime minus the increased years
*/
public LocalDateTime minusYears(int years) {
if (years == 0) {
return this;
}
long instant = getChronology().years().subtract(getLocalMillis(), years);
return withLocalMillis(instant);
}
/**
* Returns a copy of this datetime minus the specified number of months.
* * This LocalDateTime instance is immutable and unaffected by this method call. *
* The following three lines are identical in effect: *
* LocalDateTime subtracted = dt.minusMonths(6);
* LocalDateTime subtracted = dt.minus(Period.months(6));
* LocalDateTime subtracted = dt.withFieldAdded(DurationFieldType.months(), -6);
*
*
* @param months the amount of months to subtract, may be negative
* @return the new LocalDateTime minus the increased months
*/
public LocalDateTime minusMonths(int months) {
if (months == 0) {
return this;
}
long instant = getChronology().months().subtract(getLocalMillis(), months);
return withLocalMillis(instant);
}
/**
* Returns a copy of this datetime minus the specified number of weeks.
* * This LocalDateTime instance is immutable and unaffected by this method call. *
* The following three lines are identical in effect: *
* LocalDateTime subtracted = dt.minusWeeks(6);
* LocalDateTime subtracted = dt.minus(Period.weeks(6));
* LocalDateTime subtracted = dt.withFieldAdded(DurationFieldType.weeks(), -6);
*
*
* @param weeks the amount of weeks to subtract, may be negative
* @return the new LocalDateTime minus the increased weeks
*/
public LocalDateTime minusWeeks(int weeks) {
if (weeks == 0) {
return this;
}
long instant = getChronology().weeks().subtract(getLocalMillis(), weeks);
return withLocalMillis(instant);
}
/**
* Returns a copy of this datetime minus the specified number of days.
* * This LocalDateTime instance is immutable and unaffected by this method call. *
* The following three lines are identical in effect: *
* LocalDateTime subtracted = dt.minusDays(6);
* LocalDateTime subtracted = dt.minus(Period.days(6));
* LocalDateTime subtracted = dt.withFieldAdded(DurationFieldType.days(), -6);
*
*
* @param days the amount of days to subtract, may be negative
* @return the new LocalDateTime minus the increased days
*/
public LocalDateTime minusDays(int days) {
if (days == 0) {
return this;
}
long instant = getChronology().days().subtract(getLocalMillis(), days);
return withLocalMillis(instant);
}
//-----------------------------------------------------------------------
/**
* Returns a copy of this datetime minus the specified number of hours.
* * This LocalDateTime instance is immutable and unaffected by this method call. *
* The following three lines are identical in effect: *
* LocalDateTime subtracted = dt.minusHours(6);
* LocalDateTime subtracted = dt.minus(Period.hours(6));
* LocalDateTime subtracted = dt.withFieldAdded(DurationFieldType.hours(), -6);
*
*
* @param hours the amount of hours to subtract, may be negative
* @return the new LocalDateTime minus the increased hours
*/
public LocalDateTime minusHours(int hours) {
if (hours == 0) {
return this;
}
long instant = getChronology().hours().subtract(getLocalMillis(), hours);
return withLocalMillis(instant);
}
/**
* Returns a copy of this datetime minus the specified number of minutes.
* * This LocalDateTime instance is immutable and unaffected by this method call. *
* The following three lines are identical in effect: *
* LocalDateTime subtracted = dt.minusMinutes(6);
* LocalDateTime subtracted = dt.minus(Period.minutes(6));
* LocalDateTime subtracted = dt.withFieldAdded(DurationFieldType.minutes(), -6);
*
*
* @param minutes the amount of minutes to subtract, may be negative
* @return the new LocalDateTime minus the increased minutes
*/
public LocalDateTime minusMinutes(int minutes) {
if (minutes == 0) {
return this;
}
long instant = getChronology().minutes().subtract(getLocalMillis(), minutes);
return withLocalMillis(instant);
}
/**
* Returns a copy of this datetime minus the specified number of seconds.
* * This LocalDateTime instance is immutable and unaffected by this method call. *
* The following three lines are identical in effect: *
* LocalDateTime subtracted = dt.minusSeconds(6);
* LocalDateTime subtracted = dt.minus(Period.seconds(6));
* LocalDateTime subtracted = dt.withFieldAdded(DurationFieldType.seconds(), -6);
*
*
* @param seconds the amount of seconds to subtract, may be negative
* @return the new LocalDateTime minus the increased seconds
*/
public LocalDateTime minusSeconds(int seconds) {
if (seconds == 0) {
return this;
}
long instant = getChronology().seconds().subtract(getLocalMillis(), seconds);
return withLocalMillis(instant);
}
/**
* Returns a copy of this datetime minus the specified number of millis.
* * This LocalDateTime instance is immutable and unaffected by this method call. *
* The following three lines are identical in effect: *
* LocalDateTime subtracted = dt.minusMillis(6);
* LocalDateTime subtracted = dt.minus(Period.millis(6));
* LocalDateTime subtracted = dt.withFieldAdded(DurationFieldType.millis(), -6);
*
*
* @param millis the amount of millis to subtract, may be negative
* @return the new LocalDateTime minus the increased millis
*/
public LocalDateTime minusMillis(int millis) {
if (millis == 0) {
return this;
}
long instant = getChronology().millis().subtract(getLocalMillis(), millis);
return withLocalMillis(instant);
}
//-----------------------------------------------------------------------
/**
* Gets the property object for the specified type, which contains many
* useful methods.
*
* @param fieldType the field type to get the chronology for
* @return the property object
* @throws IllegalArgumentException if the field is null or unsupported
*/
public Property property(DateTimeFieldType fieldType) {
if (fieldType == null) {
throw new IllegalArgumentException("The DateTimeFieldType must not be null");
}
if (isSupported(fieldType) == false) {
throw new IllegalArgumentException("Field '" + fieldType + "' is not supported");
}
return new Property(this, fieldType.getField(getChronology()));
}
//-----------------------------------------------------------------------
/**
* Get the era field value.
*
* @return the era
*/
public int getEra() {
return getChronology().era().get(getLocalMillis());
}
/**
* Get the year of era field value.
*
* @return the year of era
*/
public int getCenturyOfEra() {
return getChronology().centuryOfEra().get(getLocalMillis());
}
/**
* Get the year of era field value.
*
* @return the year of era
*/
public int getYearOfEra() {
return getChronology().yearOfEra().get(getLocalMillis());
}
/**
* Get the year of century field value.
*
* @return the year of century
*/
public int getYearOfCentury() {
return getChronology().yearOfCentury().get(getLocalMillis());
}
/**
* Get the year field value.
*
* @return the year
*/
public int getYear() {
return getChronology().year().get(getLocalMillis());
}
/**
* Get the weekyear field value.
* * The weekyear is the year that matches with the weekOfWeekyear field. * In the standard ISO8601 week algorithm, the first week of the year * is that in which at least 4 days are in the year. As a result of this * definition, day 1 of the first week may be in the previous year. * The weekyear allows you to query the effective year for that day. * * @return the weekyear */ public int getWeekyear() { return getChronology().weekyear().get(getLocalMillis()); } /** * Get the month of year field value. * * @return the month of year */ public int getMonthOfYear() { return getChronology().monthOfYear().get(getLocalMillis()); } /** * Get the week of weekyear field value. *
* This field is associated with the "weekyear" via {@link #getWeekyear()}. * In the standard ISO8601 week algorithm, the first week of the year * is that in which at least 4 days are in the year. As a result of this * definition, day 1 of the first week may be in the previous year. * * @return the week of a week based year */ public int getWeekOfWeekyear() { return getChronology().weekOfWeekyear().get(getLocalMillis()); } /** * Get the day of year field value. * * @return the day of year */ public int getDayOfYear() { return getChronology().dayOfYear().get(getLocalMillis()); } /** * Get the day of month field value. *
* The values for the day of month are defined in {@link org.joda.time.DateTimeConstants}. * * @return the day of month */ public int getDayOfMonth() { return getChronology().dayOfMonth().get(getLocalMillis()); } /** * Get the day of week field value. *
* The values for the day of week are defined in {@link org.joda.time.DateTimeConstants}. * * @return the day of week */ public int getDayOfWeek() { return getChronology().dayOfWeek().get(getLocalMillis()); } //----------------------------------------------------------------------- /** * Get the hour of day field value. * * @return the hour of day */ public int getHourOfDay() { return getChronology().hourOfDay().get(getLocalMillis()); } /** * Get the minute of hour field value. * * @return the minute of hour */ public int getMinuteOfHour() { return getChronology().minuteOfHour().get(getLocalMillis()); } /** * Get the second of minute field value. * * @return the second of minute */ public int getSecondOfMinute() { return getChronology().secondOfMinute().get(getLocalMillis()); } /** * Get the millis of second field value. * * @return the millis of second */ public int getMillisOfSecond() { return getChronology().millisOfSecond().get(getLocalMillis()); } /** * Get the millis of day field value. * * @return the millis of day */ public int getMillisOfDay() { return getChronology().millisOfDay().get(getLocalMillis()); } //----------------------------------------------------------------------- /** * Returns a copy of this datetime with the era field updated. *
* LocalDateTime is immutable, so there are no set methods. * Instead, this method returns a new instance with the value of * era changed. * * @param era the era to set * @return a copy of this object with the field set * @throws IllegalArgumentException if the value is invalid */ public LocalDateTime withEra(int era) { return withLocalMillis(getChronology().era().set(getLocalMillis(), era)); } /** * Returns a copy of this datetime with the century of era field updated. *
* LocalDateTime is immutable, so there are no set methods. * Instead, this method returns a new instance with the value of * century of era changed. * * @param centuryOfEra the centurey of era to set * @return a copy of this object with the field set * @throws IllegalArgumentException if the value is invalid */ public LocalDateTime withCenturyOfEra(int centuryOfEra) { return withLocalMillis(getChronology().centuryOfEra().set(getLocalMillis(), centuryOfEra)); } /** * Returns a copy of this datetime with the year of era field updated. *
* LocalDateTime is immutable, so there are no set methods. * Instead, this method returns a new instance with the value of * year of era changed. * * @param yearOfEra the year of era to set * @return a copy of this object with the field set * @throws IllegalArgumentException if the value is invalid */ public LocalDateTime withYearOfEra(int yearOfEra) { return withLocalMillis(getChronology().yearOfEra().set(getLocalMillis(), yearOfEra)); } /** * Returns a copy of this datetime with the year of century field updated. *
* LocalDateTime is immutable, so there are no set methods. * Instead, this method returns a new instance with the value of * year of century changed. * * @param yearOfCentury the year of century to set * @return a copy of this object with the field set * @throws IllegalArgumentException if the value is invalid */ public LocalDateTime withYearOfCentury(int yearOfCentury) { return withLocalMillis(getChronology().yearOfCentury().set(getLocalMillis(), yearOfCentury)); } /** * Returns a copy of this datetime with the year field updated. *
* LocalDateTime is immutable, so there are no set methods. * Instead, this method returns a new instance with the value of * year changed. * * @param year the year to set * @return a copy of this object with the field set * @throws IllegalArgumentException if the value is invalid */ public LocalDateTime withYear(int year) { return withLocalMillis(getChronology().year().set(getLocalMillis(), year)); } /** * Returns a copy of this datetime with the weekyear field updated. *
* The weekyear is the year that matches with the weekOfWeekyear field. * In the standard ISO8601 week algorithm, the first week of the year * is that in which at least 4 days are in the year. As a result of this * definition, day 1 of the first week may be in the previous year. * The weekyear allows you to query the effective year for that day. *
* LocalDateTime is immutable, so there are no set methods. * Instead, this method returns a new instance with the value of * weekyear changed. * * @param weekyear the weekyear to set * @return a copy of this object with the field set * @throws IllegalArgumentException if the value is invalid */ public LocalDateTime withWeekyear(int weekyear) { return withLocalMillis(getChronology().weekyear().set(getLocalMillis(), weekyear)); } /** * Returns a copy of this datetime with the month of year field updated. *
* LocalDateTime is immutable, so there are no set methods. * Instead, this method returns a new instance with the value of * month of year changed. * * @param monthOfYear the month of year to set * @return a copy of this object with the field set * @throws IllegalArgumentException if the value is invalid */ public LocalDateTime withMonthOfYear(int monthOfYear) { return withLocalMillis(getChronology().monthOfYear().set(getLocalMillis(), monthOfYear)); } /** * Returns a copy of this datetime with the week of weekyear field updated. *
* This field is associated with the "weekyear" via {@link #withWeekyear(int)}. * In the standard ISO8601 week algorithm, the first week of the year * is that in which at least 4 days are in the year. As a result of this * definition, day 1 of the first week may be in the previous year. *
* LocalDateTime is immutable, so there are no set methods. * Instead, this method returns a new instance with the value of * week of weekyear changed. * * @param weekOfWeekyear the week of weekyear to set * @return a copy of this object with the field set * @throws IllegalArgumentException if the value is invalid */ public LocalDateTime withWeekOfWeekyear(int weekOfWeekyear) { return withLocalMillis(getChronology().weekOfWeekyear().set(getLocalMillis(), weekOfWeekyear)); } /** * Returns a copy of this datetime with the day of year field updated. *
* LocalDateTime is immutable, so there are no set methods. * Instead, this method returns a new instance with the value of * day of year changed. * * @param dayOfYear the day of year to set * @return a copy of this object with the field set * @throws IllegalArgumentException if the value is invalid */ public LocalDateTime withDayOfYear(int dayOfYear) { return withLocalMillis(getChronology().dayOfYear().set(getLocalMillis(), dayOfYear)); } /** * Returns a copy of this datetime with the day of month field updated. *
* LocalDateTime is immutable, so there are no set methods. * Instead, this method returns a new instance with the value of * day of month changed. * * @param dayOfMonth the day of month to set * @return a copy of this object with the field set * @throws IllegalArgumentException if the value is invalid */ public LocalDateTime withDayOfMonth(int dayOfMonth) { return withLocalMillis(getChronology().dayOfMonth().set(getLocalMillis(), dayOfMonth)); } /** * Returns a copy of this datetime with the day of week field updated. *
* LocalDateTime is immutable, so there are no set methods. * Instead, this method returns a new instance with the value of * day of week changed. * * @param dayOfWeek the day of week to set * @return a copy of this object with the field set * @throws IllegalArgumentException if the value is invalid */ public LocalDateTime withDayOfWeek(int dayOfWeek) { return withLocalMillis(getChronology().dayOfWeek().set(getLocalMillis(), dayOfWeek)); } //----------------------------------------------------------------------- /** * Returns a copy of this datetime with the hour of day field updated. *
* LocalDateTime is immutable, so there are no set methods. * Instead, this method returns a new instance with the value of * hour of day changed. * * @param hour the hour of day to set * @return a copy of this object with the field set * @throws IllegalArgumentException if the value is invalid */ public LocalDateTime withHourOfDay(int hour) { return withLocalMillis(getChronology().hourOfDay().set(getLocalMillis(), hour)); } /** * Returns a copy of this datetime with the minute of hour field updated. *
* LocalDateTime is immutable, so there are no set methods. * Instead, this method returns a new instance with the value of * minute of hour changed. * * @param minute the minute of hour to set * @return a copy of this object with the field set * @throws IllegalArgumentException if the value is invalid */ public LocalDateTime withMinuteOfHour(int minute) { return withLocalMillis(getChronology().minuteOfHour().set(getLocalMillis(), minute)); } /** * Returns a copy of this datetime with the second of minute field updated. *
* LocalDateTime is immutable, so there are no set methods. * Instead, this method returns a new instance with the value of * second of minute changed. * * @param second the second of minute to set * @return a copy of this object with the field set * @throws IllegalArgumentException if the value is invalid */ public LocalDateTime withSecondOfMinute(int second) { return withLocalMillis(getChronology().secondOfMinute().set(getLocalMillis(), second)); } /** * Returns a copy of this datetime with the millis of second field updated. *
* LocalDateTime is immutable, so there are no set methods. * Instead, this method returns a new instance with the value of * millis of second changed. * * @param millis the millis of second to set * @return a copy of this object with the field set * @throws IllegalArgumentException if the value is invalid */ public LocalDateTime withMillisOfSecond(int millis) { return withLocalMillis(getChronology().millisOfSecond().set(getLocalMillis(), millis)); } /** * Returns a copy of this datetime with the millis of day field updated. *
* LocalDateTime is immutable, so there are no set methods.
* Instead, this method returns a new instance with the value of
* millis of day changed.
*
* @param millis the millis of day to set
* @return a copy of this object with the field set
* @throws IllegalArgumentException if the value is invalid
*/
public LocalDateTime withMillisOfDay(int millis) {
return withLocalMillis(getChronology().millisOfDay().set(getLocalMillis(), millis));
}
//-----------------------------------------------------------------------
/**
* Get the era property which provides access to advanced functionality.
*
* @return the era property
*/
public Property era() {
return new Property(this, getChronology().era());
}
/**
* Get the century of era property which provides access to advanced functionality.
*
* @return the year of era property
*/
public Property centuryOfEra() {
return new Property(this, getChronology().centuryOfEra());
}
/**
* Get the year of century property which provides access to advanced functionality.
*
* @return the year of era property
*/
public Property yearOfCentury() {
return new Property(this, getChronology().yearOfCentury());
}
/**
* Get the year of era property which provides access to advanced functionality.
*
* @return the year of era property
*/
public Property yearOfEra() {
return new Property(this, getChronology().yearOfEra());
}
/**
* Get the year property which provides access to advanced functionality.
*
* @return the year property
*/
public Property year() {
return new Property(this, getChronology().year());
}
/**
* Get the weekyear property which provides access to advanced functionality.
*
* @return the weekyear property
*/
public Property weekyear() {
return new Property(this, getChronology().weekyear());
}
/**
* Get the month of year property which provides access to advanced functionality.
*
* @return the month of year property
*/
public Property monthOfYear() {
return new Property(this, getChronology().monthOfYear());
}
/**
* Get the week of a week based year property which provides access to advanced functionality.
*
* @return the week of a week based year property
*/
public Property weekOfWeekyear() {
return new Property(this, getChronology().weekOfWeekyear());
}
/**
* Get the day of year property which provides access to advanced functionality.
*
* @return the day of year property
*/
public Property dayOfYear() {
return new Property(this, getChronology().dayOfYear());
}
/**
* Get the day of month property which provides access to advanced functionality.
*
* @return the day of month property
*/
public Property dayOfMonth() {
return new Property(this, getChronology().dayOfMonth());
}
/**
* Get the day of week property which provides access to advanced functionality.
*
* @return the day of week property
*/
public Property dayOfWeek() {
return new Property(this, getChronology().dayOfWeek());
}
//-----------------------------------------------------------------------
/**
* Get the hour of day field property which provides access to advanced functionality.
*
* @return the hour of day property
*/
public Property hourOfDay() {
return new Property(this, getChronology().hourOfDay());
}
/**
* Get the minute of hour field property which provides access to advanced functionality.
*
* @return the minute of hour property
*/
public Property minuteOfHour() {
return new Property(this, getChronology().minuteOfHour());
}
/**
* Get the second of minute field property which provides access to advanced functionality.
*
* @return the second of minute property
*/
public Property secondOfMinute() {
return new Property(this, getChronology().secondOfMinute());
}
/**
* Get the millis of second property which provides access to advanced functionality.
*
* @return the millis of second property
*/
public Property millisOfSecond() {
return new Property(this, getChronology().millisOfSecond());
}
/**
* Get the millis of day property which provides access to advanced functionality.
*
* @return the millis of day property
*/
public Property millisOfDay() {
return new Property(this, getChronology().millisOfDay());
}
//-----------------------------------------------------------------------
/**
* Output the date time in ISO8601 format (yyyy-MM-ddTHH:mm:ss.SSS).
*
* @return ISO8601 time formatted string.
*/
@ToString
public String toString() {
return ISODateTimeFormat.dateTime().print(this);
}
/**
* Output the date using the specified format pattern.
*
* @param pattern the pattern specification, null means use toString
* @see org.joda.time.format.DateTimeFormat
*/
public String toString(String pattern) {
if (pattern == null) {
return toString();
}
return DateTimeFormat.forPattern(pattern).print(this);
}
/**
* Output the date using the specified format pattern.
*
* @param pattern the pattern specification, null means use toString
* @param locale Locale to use, null means default
* @see org.joda.time.format.DateTimeFormat
*/
public String toString(String pattern, Locale locale) throws IllegalArgumentException {
if (pattern == null) {
return toString();
}
return DateTimeFormat.forPattern(pattern).withLocale(locale).print(this);
}
//-----------------------------------------------------------------------
/**
* LocalDateTime.Property binds a LocalDateTime to a DateTimeField allowing
* powerful datetime functionality to be easily accessed.
*
* The simplest use of this class is as an alternative get method, here used to * get the year '1972' (as an int) and the month 'December' (as a String). *
* LocalDateTime dt = new LocalDateTime(1972, 12, 3, 0, 0);
* int year = dt.year().get();
* String monthStr = dt.month().getAsText();
*
* * Methods are also provided that allow date modification. These return * new instances of LocalDateTime - they do not modify the original. * The example below yields two independent immutable date objects * 20 years apart. *
* LocalDateTime dt = new LocalDateTime(1972, 12, 3, 0, 0);
* LocalDateTime dt1920 = dt.year().setCopy(1920);
*
* * LocalDateTime.Property itself is thread-safe and immutable, as well as the * LocalDateTime being operated on. * * @author Stephen Colebourne * @author Brian S O'Neill * @since 1.3 */ public static final class Property extends AbstractReadableInstantFieldProperty { /** Serialization version */ private static final long serialVersionUID = -358138762846288L; /** The instant this property is working against */ private transient LocalDateTime iInstant; /** The field this property is working against */ private transient DateTimeField iField; /** * Constructor. * * @param instant the instant to set * @param field the field to use */ Property(LocalDateTime instant, DateTimeField field) { super(); iInstant = instant; iField = field; } /** * Writes the property in a safe serialization format. */ private void writeObject(ObjectOutputStream oos) throws IOException { oos.writeObject(iInstant); oos.writeObject(iField.getType()); } /** * Reads the property from a safe serialization format. */ private void readObject(ObjectInputStream oos) throws IOException, ClassNotFoundException { iInstant = (LocalDateTime) oos.readObject(); DateTimeFieldType type = (DateTimeFieldType) oos.readObject(); iField = type.getField(iInstant.getChronology()); } //----------------------------------------------------------------------- /** * Gets the field being used. * * @return the field */ public DateTimeField getField() { return iField; } /** * Gets the milliseconds of the datetime that this property is linked to. * * @return the milliseconds */ protected long getMillis() { return iInstant.getLocalMillis(); } /** * Gets the chronology of the datetime that this property is linked to. * * @return the chronology * @since 1.4 */ protected Chronology getChronology() { return iInstant.getChronology(); } /** * Gets the LocalDateTime object linked to this property. * * @return the linked LocalDateTime */ public LocalDateTime getLocalDateTime() { return iInstant; } //----------------------------------------------------------------------- /** * Adds to this field in a copy of this LocalDateTime. *
* The LocalDateTime attached to this property is unchanged by this call. * * @param value the value to add to the field in the copy * @return a copy of the LocalDateTime with the field value changed * @throws IllegalArgumentException if the value isn't valid */ public LocalDateTime addToCopy(int value) { return iInstant.withLocalMillis(iField.add(iInstant.getLocalMillis(), value)); } /** * Adds to this field in a copy of this LocalDateTime. *
* The LocalDateTime attached to this property is unchanged by this call. * * @param value the value to add to the field in the copy * @return a copy of the LocalDateTime with the field value changed * @throws IllegalArgumentException if the value isn't valid */ public LocalDateTime addToCopy(long value) { return iInstant.withLocalMillis(iField.add(iInstant.getLocalMillis(), value)); } /** * Adds to this field, possibly wrapped, in a copy of this LocalDateTime. * A field wrapped operation only changes this field. * Thus 31st January addWrapField one day goes to the 1st January. *
* The LocalDateTime attached to this property is unchanged by this call. * * @param value the value to add to the field in the copy * @return a copy of the LocalDateTime with the field value changed * @throws IllegalArgumentException if the value isn't valid */ public LocalDateTime addWrapFieldToCopy(int value) { return iInstant.withLocalMillis(iField.addWrapField(iInstant.getLocalMillis(), value)); } //----------------------------------------------------------------------- /** * Sets this field in a copy of the LocalDateTime. *
* The LocalDateTime attached to this property is unchanged by this call. * * @param value the value to set the field in the copy to * @return a copy of the LocalDateTime with the field value changed * @throws IllegalArgumentException if the value isn't valid */ public LocalDateTime setCopy(int value) { return iInstant.withLocalMillis(iField.set(iInstant.getLocalMillis(), value)); } /** * Sets this field in a copy of the LocalDateTime to a parsed text value. *
* The LocalDateTime attached to this property is unchanged by this call. * * @param text the text value to set * @param locale optional locale to use for selecting a text symbol * @return a copy of the LocalDateTime with the field value changed * @throws IllegalArgumentException if the text value isn't valid */ public LocalDateTime setCopy(String text, Locale locale) { return iInstant.withLocalMillis(iField.set(iInstant.getLocalMillis(), text, locale)); } /** * Sets this field in a copy of the LocalDateTime to a parsed text value. *
* The LocalDateTime attached to this property is unchanged by this call. * * @param text the text value to set * @return a copy of the LocalDateTime with the field value changed * @throws IllegalArgumentException if the text value isn't valid */ public LocalDateTime setCopy(String text) { return setCopy(text, null); } //----------------------------------------------------------------------- /** * Returns a new LocalDateTime with this field set to the maximum value * for this field. *
* This operation is useful for obtaining a LocalDateTime on the last day * of the month, as month lengths vary. *
* LocalDateTime lastDayOfMonth = dt.dayOfMonth().withMaximumValue();
*
* * The LocalDateTime attached to this property is unchanged by this call. * * @return a copy of the LocalDateTime with this field set to its maximum */ public LocalDateTime withMaximumValue() { return setCopy(getMaximumValue()); } /** * Returns a new LocalDateTime with this field set to the minimum value * for this field. *
* The LocalDateTime attached to this property is unchanged by this call. * * @return a copy of the LocalDateTime with this field set to its minimum */ public LocalDateTime withMinimumValue() { return setCopy(getMinimumValue()); } //----------------------------------------------------------------------- /** * Rounds to the lowest whole unit of this field on a copy of this * LocalDateTime. *
* For example, rounding floor on the hourOfDay field of a LocalDateTime * where the time is 10:30 would result in new LocalDateTime with the * time of 10:00. * * @return a copy of the LocalDateTime with the field value changed */ public LocalDateTime roundFloorCopy() { return iInstant.withLocalMillis(iField.roundFloor(iInstant.getLocalMillis())); } /** * Rounds to the highest whole unit of this field on a copy of this * LocalDateTime. *
* For example, rounding floor on the hourOfDay field of a LocalDateTime * where the time is 10:30 would result in new LocalDateTime with the * time of 11:00. * * @return a copy of the LocalDateTime with the field value changed */ public LocalDateTime roundCeilingCopy() { return iInstant.withLocalMillis(iField.roundCeiling(iInstant.getLocalMillis())); } /** * Rounds to the nearest whole unit of this field on a copy of this * LocalDateTime, favoring the floor if halfway. * * @return a copy of the LocalDateTime with the field value changed */ public LocalDateTime roundHalfFloorCopy() { return iInstant.withLocalMillis(iField.roundHalfFloor(iInstant.getLocalMillis())); } /** * Rounds to the nearest whole unit of this field on a copy of this * LocalDateTime, favoring the ceiling if halfway. * * @return a copy of the LocalDateTime with the field value changed */ public LocalDateTime roundHalfCeilingCopy() { return iInstant.withLocalMillis(iField.roundHalfCeiling(iInstant.getLocalMillis())); } /** * Rounds to the nearest whole unit of this field on a copy of this * LocalDateTime. If halfway, the ceiling is favored over the floor * only if it makes this field's value even. * * @return a copy of the LocalDateTime with the field value changed */ public LocalDateTime roundHalfEvenCopy() { return iInstant.withLocalMillis(iField.roundHalfEven(iInstant.getLocalMillis())); } } }