0001: /*
0002: * Copyright 2001-2006 Stephen Colebourne
0003: *
0004: * Licensed under the Apache License, Version 2.0 (the "License");
0005: * you may not use this file except in compliance with the License.
0006: * You may obtain a copy of the License at
0007: *
0008: * http://www.apache.org/licenses/LICENSE-2.0
0009: *
0010: * Unless required by applicable law or agreed to in writing, software
0011: * distributed under the License is distributed on an "AS IS" BASIS,
0012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
0013: * See the License for the specific language governing permissions and
0014: * limitations under the License.
0015: */
0016: package org.joda.time;
0017:
0018: import java.io.IOException;
0019: import java.io.ObjectInputStream;
0020: import java.io.ObjectOutputStream;
0021: import java.io.Serializable;
0022: import java.util.Locale;
0023:
0024: import org.joda.time.base.BaseDateTime;
0025: import org.joda.time.chrono.ISOChronology;
0026: import org.joda.time.field.AbstractReadableInstantFieldProperty;
0027: import org.joda.time.format.ISODateTimeFormat;
0028:
0029: /**
0030: * DateTime is the standard implementation of an unmodifiable datetime class.
0031: * <p>
0032: * <code>DateTime</code> is the most widely used implementation of
0033: * {@link ReadableInstant}. As with all instants, it represents an exact
0034: * point on the time-line, but limited to the precision of milliseconds.
0035: * A <code>DateTime</code> calculates its fields with respect to a
0036: * {@link DateTimeZone time zone}.
0037: * <p>
0038: * Internally, the class holds two pieces of data. Firstly, it holds the
0039: * datetime as milliseconds from the Java epoch of 1970-01-01T00:00:00Z.
0040: * Secondly, it holds a {@link Chronology} which determines how the
0041: * millisecond instant value is converted into the date time fields.
0042: * The default Chronology is {@link ISOChronology} which is the agreed
0043: * international standard and compatible with the modern Gregorian calendar.
0044: * <p>
0045: * Each individual field can be queried in two ways:
0046: * <ul>
0047: * <li><code>getHourOfDay()</code>
0048: * <li><code>hourOfDay().get()</code>
0049: * </ul>
0050: * The second technique also provides access to other useful methods on the
0051: * field:
0052: * <ul>
0053: * <li>numeric value
0054: * <li>text value
0055: * <li>short text value
0056: * <li>maximum/minimum values
0057: * <li>add/subtract
0058: * <li>set
0059: * <li>rounding
0060: * </ul>
0061: * <p>
0062: * DateTime is thread-safe and immutable, provided that the Chronology is as well.
0063: * All standard Chronology classes supplied are thread-safe and immutable.
0064: *
0065: * @author Stephen Colebourne
0066: * @author Kandarp Shah
0067: * @author Brian S O'Neill
0068: * @since 1.0
0069: * @see MutableDateTime
0070: */
0071: public final class DateTime extends BaseDateTime implements
0072: ReadableDateTime, Serializable {
0073:
0074: /** Serialization lock */
0075: private static final long serialVersionUID = -5171125899451703815L;
0076:
0077: //-----------------------------------------------------------------------
0078: /**
0079: * Constructs an instance set to the current system millisecond time
0080: * using <code>ISOChronology</code> in the default time zone.
0081: */
0082: public DateTime() {
0083: super ();
0084: }
0085:
0086: /**
0087: * Constructs an instance set to the current system millisecond time
0088: * using <code>ISOChronology</code> in the specified time zone.
0089: * <p>
0090: * If the specified time zone is null, the default zone is used.
0091: *
0092: * @param zone the time zone, null means default zone
0093: */
0094: public DateTime(DateTimeZone zone) {
0095: super (zone);
0096: }
0097:
0098: /**
0099: * Constructs an instance set to the current system millisecond time
0100: * using the specified chronology.
0101: * <p>
0102: * If the chronology is null, <code>ISOChronology</code>
0103: * in the default time zone is used.
0104: *
0105: * @param chronology the chronology, null means ISOChronology in default zone
0106: */
0107: public DateTime(Chronology chronology) {
0108: super (chronology);
0109: }
0110:
0111: //-----------------------------------------------------------------------
0112: /**
0113: * Constructs an instance set to the milliseconds from 1970-01-01T00:00:00Z
0114: * using <code>ISOChronology</code> in the default time zone.
0115: *
0116: * @param instant the milliseconds from 1970-01-01T00:00:00Z
0117: */
0118: public DateTime(long instant) {
0119: super (instant);
0120: }
0121:
0122: /**
0123: * Constructs an instance set to the milliseconds from 1970-01-01T00:00:00Z
0124: * using <code>ISOChronology</code> in the specified time zone.
0125: * <p>
0126: * If the specified time zone is null, the default zone is used.
0127: *
0128: * @param instant the milliseconds from 1970-01-01T00:00:00Z
0129: * @param zone the time zone, null means default zone
0130: */
0131: public DateTime(long instant, DateTimeZone zone) {
0132: super (instant, zone);
0133: }
0134:
0135: /**
0136: * Constructs an instance set to the milliseconds from 1970-01-01T00:00:00Z
0137: * using the specified chronology.
0138: * <p>
0139: * If the chronology is null, <code>ISOChronology</code>
0140: * in the default time zone is used.
0141: *
0142: * @param instant the milliseconds from 1970-01-01T00:00:00Z
0143: * @param chronology the chronology, null means ISOChronology in default zone
0144: */
0145: public DateTime(long instant, Chronology chronology) {
0146: super (instant, chronology);
0147: }
0148:
0149: //-----------------------------------------------------------------------
0150: /**
0151: * Constructs an instance from an Object that represents a datetime.
0152: * <p>
0153: * If the object implies a chronology (such as GregorianCalendar does),
0154: * then that chronology will be used. Otherwise, ISO default is used.
0155: * Thus if a GregorianCalendar is passed in, the chronology used will
0156: * be GJ, but if a Date is passed in the chronology will be ISO.
0157: * <p>
0158: * The recognised object types are defined in
0159: * {@link org.joda.time.convert.ConverterManager ConverterManager} and
0160: * include ReadableInstant, String, Calendar and Date.
0161: * The String formats are described by {@link ISODateTimeFormat#dateTimeParser()}.
0162: *
0163: * @param instant the datetime object, null means now
0164: * @throws IllegalArgumentException if the instant is invalid
0165: */
0166: public DateTime(Object instant) {
0167: super (instant, (Chronology) null);
0168: }
0169:
0170: /**
0171: * Constructs an instance from an Object that represents a datetime,
0172: * forcing the time zone to that specified.
0173: * <p>
0174: * If the object implies a chronology (such as GregorianCalendar does),
0175: * then that chronology will be used, but with the time zone adjusted.
0176: * Otherwise, ISO is used in the specified time zone.
0177: * If the specified time zone is null, the default zone is used.
0178: * Thus if a GregorianCalendar is passed in, the chronology used will
0179: * be GJ, but if a Date is passed in the chronology will be ISO.
0180: * <p>
0181: * The recognised object types are defined in
0182: * {@link org.joda.time.convert.ConverterManager ConverterManager} and
0183: * include ReadableInstant, String, Calendar and Date.
0184: * The String formats are described by {@link ISODateTimeFormat#dateTimeParser()}.
0185: *
0186: * @param instant the datetime object, null means now
0187: * @param zone the time zone, null means default time zone
0188: * @throws IllegalArgumentException if the instant is invalid
0189: */
0190: public DateTime(Object instant, DateTimeZone zone) {
0191: super (instant, zone);
0192: }
0193:
0194: /**
0195: * Constructs an instance from an Object that represents a datetime,
0196: * using the specified chronology.
0197: * <p>
0198: * If the chronology is null, ISO in the default time zone is used.
0199: * Any chronology implied by the object (such as GregorianCalendar does)
0200: * is ignored.
0201: * <p>
0202: * The recognised object types are defined in
0203: * {@link org.joda.time.convert.ConverterManager ConverterManager} and
0204: * include ReadableInstant, String, Calendar and Date.
0205: * The String formats are described by {@link ISODateTimeFormat#dateTimeParser()}.
0206: *
0207: * @param instant the datetime object, null means now
0208: * @param chronology the chronology, null means ISO in default zone
0209: * @throws IllegalArgumentException if the instant is invalid
0210: */
0211: public DateTime(Object instant, Chronology chronology) {
0212: super (instant, DateTimeUtils.getChronology(chronology));
0213: }
0214:
0215: //-----------------------------------------------------------------------
0216: /**
0217: * Constructs an instance from datetime field values
0218: * using <code>ISOChronology</code> in the default time zone.
0219: *
0220: * @param year the year
0221: * @param monthOfYear the month of the year
0222: * @param dayOfMonth the day of the month
0223: * @param hourOfDay the hour of the day
0224: * @param minuteOfHour the minute of the hour
0225: * @param secondOfMinute the second of the minute
0226: * @param millisOfSecond the millisecond of the second
0227: */
0228: public DateTime(int year, int monthOfYear, int dayOfMonth,
0229: int hourOfDay, int minuteOfHour, int secondOfMinute,
0230: int millisOfSecond) {
0231: super (year, monthOfYear, dayOfMonth, hourOfDay, minuteOfHour,
0232: secondOfMinute, millisOfSecond);
0233: }
0234:
0235: /**
0236: * Constructs an instance from datetime field values
0237: * using <code>ISOChronology</code> in the specified time zone.
0238: * <p>
0239: * If the specified time zone is null, the default zone is used.
0240: *
0241: * @param year the year
0242: * @param monthOfYear the month of the year
0243: * @param dayOfMonth the day of the month
0244: * @param hourOfDay the hour of the day
0245: * @param minuteOfHour the minute of the hour
0246: * @param secondOfMinute the second of the minute
0247: * @param millisOfSecond the millisecond of the second
0248: * @param zone the time zone, null means default time zone
0249: */
0250: public DateTime(int year, int monthOfYear, int dayOfMonth,
0251: int hourOfDay, int minuteOfHour, int secondOfMinute,
0252: int millisOfSecond, DateTimeZone zone) {
0253: super (year, monthOfYear, dayOfMonth, hourOfDay, minuteOfHour,
0254: secondOfMinute, millisOfSecond, zone);
0255: }
0256:
0257: /**
0258: * Constructs an instance from datetime field values
0259: * using the specified chronology.
0260: * <p>
0261: * If the chronology is null, <code>ISOChronology</code>
0262: * in the default time zone is used.
0263: *
0264: * @param year the year
0265: * @param monthOfYear the month of the year
0266: * @param dayOfMonth the day of the month
0267: * @param hourOfDay the hour of the day
0268: * @param minuteOfHour the minute of the hour
0269: * @param secondOfMinute the second of the minute
0270: * @param millisOfSecond the millisecond of the second
0271: * @param chronology the chronology, null means ISOChronology in default zone
0272: */
0273: public DateTime(int year, int monthOfYear, int dayOfMonth,
0274: int hourOfDay, int minuteOfHour, int secondOfMinute,
0275: int millisOfSecond, Chronology chronology) {
0276: super (year, monthOfYear, dayOfMonth, hourOfDay, minuteOfHour,
0277: secondOfMinute, millisOfSecond, chronology);
0278: }
0279:
0280: //-----------------------------------------------------------------------
0281: /**
0282: * Get this object as a DateTime by returning <code>this</code>.
0283: *
0284: * @return <code>this</code>
0285: */
0286: public DateTime toDateTime() {
0287: return this ;
0288: }
0289:
0290: /**
0291: * Get this object as a DateTime using ISOChronology in the default zone,
0292: * returning <code>this</code> if possible.
0293: *
0294: * @return a DateTime using the same millis
0295: */
0296: public DateTime toDateTimeISO() {
0297: if (getChronology() == ISOChronology.getInstance()) {
0298: return this ;
0299: }
0300: return super .toDateTimeISO();
0301: }
0302:
0303: /**
0304: * Get this object as a DateTime, returning <code>this</code> if possible.
0305: *
0306: * @param zone time zone to apply, or default if null
0307: * @return a DateTime using the same millis
0308: */
0309: public DateTime toDateTime(DateTimeZone zone) {
0310: zone = DateTimeUtils.getZone(zone);
0311: if (getZone() == zone) {
0312: return this ;
0313: }
0314: return super .toDateTime(zone);
0315: }
0316:
0317: /**
0318: * Get this object as a DateTime, returning <code>this</code> if possible.
0319: *
0320: * @param chronology chronology to apply, or ISOChronology if null
0321: * @return a DateTime using the same millis
0322: */
0323: public DateTime toDateTime(Chronology chronology) {
0324: chronology = DateTimeUtils.getChronology(chronology);
0325: if (getChronology() == chronology) {
0326: return this ;
0327: }
0328: return super .toDateTime(chronology);
0329: }
0330:
0331: //-----------------------------------------------------------------------
0332: /**
0333: * Returns a copy of this datetime with different millis.
0334: * <p>
0335: * The returned object will be either be a new instance or <code>this</code>.
0336: * Only the millis will change, the chronology and time zone are kept.
0337: *
0338: * @param newMillis the new millis, from 1970-01-01T00:00:00Z
0339: * @return a copy of this datetime with different millis
0340: */
0341: public DateTime withMillis(long newMillis) {
0342: return (newMillis == getMillis() ? this : new DateTime(
0343: newMillis, getChronology()));
0344: }
0345:
0346: /**
0347: * Returns a copy of this datetime with a different chronology.
0348: * <p>
0349: * The returned object will be either be a new instance or <code>this</code>.
0350: * Only the chronology will change, the millis are kept.
0351: *
0352: * @param newChronology the new chronology, null means ISO default
0353: * @return a copy of this datetime with a different chronology
0354: */
0355: public DateTime withChronology(Chronology newChronology) {
0356: newChronology = DateTimeUtils.getChronology(newChronology);
0357: return (newChronology == getChronology() ? this : new DateTime(
0358: getMillis(), newChronology));
0359: }
0360:
0361: //-----------------------------------------------------------------------
0362: /**
0363: * Returns a copy of this datetime with a different time zone, preserving the
0364: * millisecond instant.
0365: * <p>
0366: * This method is useful for finding the local time in another timezone.
0367: * For example, if this instant holds 12:30 in Europe/London, the result
0368: * from this method with Europe/Paris would be 13:30.
0369: * <p>
0370: * The returned object will be a new instance of the same implementation type.
0371: * This method changes the time zone, and does not change the
0372: * millisecond instant, with the effect that the field values usually change.
0373: * The returned object will be either be a new instance or <code>this</code>.
0374: *
0375: * @param newZone the new time zone
0376: * @return a copy of this datetime with a different time zone
0377: * @see #withZoneRetainFields
0378: */
0379: public DateTime withZone(DateTimeZone newZone) {
0380: return withChronology(getChronology().withZone(newZone));
0381: }
0382:
0383: /**
0384: * Returns a copy of this datetime with a different time zone, preserving the
0385: * field values.
0386: * <p>
0387: * This method is useful for finding the millisecond time in another timezone.
0388: * For example, if this instant holds 12:30 in Europe/London (ie. 12:30Z),
0389: * the result from this method with Europe/Paris would be 12:30 (ie. 11:30Z).
0390: * <p>
0391: * The returned object will be a new instance of the same implementation type.
0392: * This method changes the time zone and the millisecond instant to keep
0393: * the field values the same.
0394: * The returned object will be either be a new instance or <code>this</code>.
0395: *
0396: * @param newZone the new time zone, null means default
0397: * @return a copy of this datetime with a different time zone
0398: * @see #withZone
0399: */
0400: public DateTime withZoneRetainFields(DateTimeZone newZone) {
0401: newZone = DateTimeUtils.getZone(newZone);
0402: DateTimeZone originalZone = DateTimeUtils.getZone(getZone());
0403: if (newZone == originalZone) {
0404: return this ;
0405: }
0406:
0407: long millis = originalZone.getMillisKeepLocal(newZone,
0408: getMillis());
0409: return new DateTime(millis, getChronology().withZone(newZone));
0410: }
0411:
0412: //-----------------------------------------------------------------------
0413: /**
0414: * Returns a copy of this datetime with the specified date, retaining the time fields.
0415: * <p>
0416: * If the date is already the date passed in, then <code>this</code> is returned.
0417: * <p>
0418: * To set a single field use the properties, for example:
0419: * <pre>
0420: * DateTime set = monthOfYear().setCopy(6);
0421: * </pre>
0422: *
0423: * @param year the new year value
0424: * @param monthOfYear the new monthOfYear value
0425: * @param dayOfMonth the new dayOfMonth value
0426: * @return a copy of this datetime with a different date
0427: * @throws IllegalArgumentException if any value if invalid
0428: */
0429: public DateTime withDate(int year, int monthOfYear, int dayOfMonth) {
0430: Chronology chrono = getChronology();
0431: long instant = getMillis();
0432: instant = chrono.year().set(instant, year);
0433: instant = chrono.monthOfYear().set(instant, monthOfYear);
0434: instant = chrono.dayOfMonth().set(instant, dayOfMonth);
0435: return withMillis(instant);
0436: }
0437:
0438: /**
0439: * Returns a copy of this datetime with the specified time, retaining the date fields.
0440: * <p>
0441: * If the time is already the time passed in, then <code>this</code> is returned.
0442: * <p>
0443: * To set a single field use the properties, for example:
0444: * <pre>
0445: * DateTime set = dt.hourOfDay().setCopy(6);
0446: * </pre>
0447: *
0448: * @param hourOfDay the hour of the day
0449: * @param minuteOfHour the minute of the hour
0450: * @param secondOfMinute the second of the minute
0451: * @param millisOfSecond the millisecond of the second
0452: * @return a copy of this datetime with a different time
0453: * @throws IllegalArgumentException if any value if invalid
0454: */
0455: public DateTime withTime(int hourOfDay, int minuteOfHour,
0456: int secondOfMinute, int millisOfSecond) {
0457: Chronology chrono = getChronology();
0458: long instant = getMillis();
0459: instant = chrono.hourOfDay().set(instant, hourOfDay);
0460: instant = chrono.minuteOfHour().set(instant, minuteOfHour);
0461: instant = chrono.secondOfMinute().set(instant, secondOfMinute);
0462: instant = chrono.millisOfSecond().set(instant, millisOfSecond);
0463: return withMillis(instant);
0464: }
0465:
0466: //-----------------------------------------------------------------------
0467: /**
0468: * Returns a copy of this datetime with the partial set of fields replacing those
0469: * from this instance.
0470: * <p>
0471: * For example, if the partial is a <code>TimeOfDay</code> then the time fields
0472: * would be changed in the returned instance.
0473: * If the partial is null, then <code>this</code> is returned.
0474: *
0475: * @param partial the partial set of fields to apply to this datetime, null ignored
0476: * @return a copy of this datetime with a different set of fields
0477: * @throws IllegalArgumentException if any value is invalid
0478: */
0479: public DateTime withFields(ReadablePartial partial) {
0480: if (partial == null) {
0481: return this ;
0482: }
0483: return withMillis(getChronology().set(partial, getMillis()));
0484: }
0485:
0486: /**
0487: * Returns a copy of this datetime with the specified field set to a new value.
0488: * <p>
0489: * For example, if the field type is <code>hourOfDay</code> then the hour of day
0490: * field would be changed in the returned instance.
0491: * If the field type is null, then <code>this</code> is returned.
0492: * <p>
0493: * These three lines are equivalent:
0494: * <pre>
0495: * DateTime updated = dt.withField(DateTimeFieldType.dayOfMonth(), 6);
0496: * DateTime updated = dt.dayOfMonth().setCopy(6);
0497: * DateTime updated = dt.property(DateTimeFieldType.dayOfMonth()).setCopy(6);
0498: * </pre>
0499: *
0500: * @param fieldType the field type to set, not null
0501: * @param value the value to set
0502: * @return a copy of this datetime with the field set
0503: * @throws IllegalArgumentException if the value is null or invalid
0504: */
0505: public DateTime withField(DateTimeFieldType fieldType, int value) {
0506: if (fieldType == null) {
0507: throw new IllegalArgumentException("Field must not be null");
0508: }
0509: long instant = fieldType.getField(getChronology()).set(
0510: getMillis(), value);
0511: return withMillis(instant);
0512: }
0513:
0514: /**
0515: * Returns a copy of this datetime with the value of the specified field increased.
0516: * <p>
0517: * If the addition is zero or the field is null, then <code>this</code> is returned.
0518: * <p>
0519: * These three lines are equivalent:
0520: * <pre>
0521: * DateTime added = dt.withFieldAdded(DurationFieldType.years(), 6);
0522: * DateTime added = dt.plusYears(6);
0523: * DateTime added = dt.plus(Period.years(6));
0524: * </pre>
0525: *
0526: * @param fieldType the field type to add to, not null
0527: * @param amount the amount to add
0528: * @return a copy of this datetime with the field updated
0529: * @throws IllegalArgumentException if the value is null or invalid
0530: * @throws ArithmeticException if the new datetime exceeds the capacity of a long
0531: */
0532: public DateTime withFieldAdded(DurationFieldType fieldType,
0533: int amount) {
0534: if (fieldType == null) {
0535: throw new IllegalArgumentException("Field must not be null");
0536: }
0537: if (amount == 0) {
0538: return this ;
0539: }
0540: long instant = fieldType.getField(getChronology()).add(
0541: getMillis(), amount);
0542: return withMillis(instant);
0543: }
0544:
0545: //-----------------------------------------------------------------------
0546: /**
0547: * Returns a copy of this datetime with the specified duration added.
0548: * <p>
0549: * If the addition is zero, then <code>this</code> is returned.
0550: *
0551: * @param durationToAdd the duration to add to this one
0552: * @param scalar the amount of times to add, such as -1 to subtract once
0553: * @return a copy of this datetime with the duration added
0554: * @throws ArithmeticException if the new datetime exceeds the capacity of a long
0555: */
0556: public DateTime withDurationAdded(long durationToAdd, int scalar) {
0557: if (durationToAdd == 0 || scalar == 0) {
0558: return this ;
0559: }
0560: long instant = getChronology().add(getMillis(), durationToAdd,
0561: scalar);
0562: return withMillis(instant);
0563: }
0564:
0565: /**
0566: * Returns a copy of this datetime with the specified duration added.
0567: * <p>
0568: * If the addition is zero, then <code>this</code> is returned.
0569: *
0570: * @param durationToAdd the duration to add to this one, null means zero
0571: * @param scalar the amount of times to add, such as -1 to subtract once
0572: * @return a copy of this datetime with the duration added
0573: * @throws ArithmeticException if the new datetime exceeds the capacity of a long
0574: */
0575: public DateTime withDurationAdded(ReadableDuration durationToAdd,
0576: int scalar) {
0577: if (durationToAdd == null || scalar == 0) {
0578: return this ;
0579: }
0580: return withDurationAdded(durationToAdd.getMillis(), scalar);
0581: }
0582:
0583: /**
0584: * Returns a copy of this datetime with the specified period added.
0585: * <p>
0586: * If the addition is zero, then <code>this</code> is returned.
0587: * <p>
0588: * This method is typically used to add multiple copies of complex
0589: * period instances. Adding one field is best achieved using methods
0590: * like {@link #withFieldAdded(DurationFieldType, int)}
0591: * or {@link #plusYears(int)}.
0592: *
0593: * @param period the period to add to this one, null means zero
0594: * @param scalar the amount of times to add, such as -1 to subtract once
0595: * @return a copy of this datetime with the period added
0596: * @throws ArithmeticException if the new datetime exceeds the capacity of a long
0597: */
0598: public DateTime withPeriodAdded(ReadablePeriod period, int scalar) {
0599: if (period == null || scalar == 0) {
0600: return this ;
0601: }
0602: long instant = getChronology().add(period, getMillis(), scalar);
0603: return withMillis(instant);
0604: }
0605:
0606: //-----------------------------------------------------------------------
0607: /**
0608: * Returns a copy of this datetime with the specified duration added.
0609: * <p>
0610: * If the amount is zero or null, then <code>this</code> is returned.
0611: * This datetime instance is immutable and unaffected by this method call.
0612: *
0613: * @param duration the duration, in millis, to add to this one
0614: * @return a copy of this datetime with the duration added
0615: * @throws ArithmeticException if the new datetime exceeds the capacity of a long
0616: */
0617: public DateTime plus(long duration) {
0618: return withDurationAdded(duration, 1);
0619: }
0620:
0621: /**
0622: * Returns a copy of this datetime with the specified duration added.
0623: * <p>
0624: * If the amount is zero or null, then <code>this</code> is returned.
0625: * This datetime instance is immutable and unaffected by this method call.
0626: *
0627: * @param duration the duration to add to this one, null means zero
0628: * @return a copy of this datetime with the duration added
0629: * @throws ArithmeticException if the new datetime exceeds the capacity of a long
0630: */
0631: public DateTime plus(ReadableDuration duration) {
0632: return withDurationAdded(duration, 1);
0633: }
0634:
0635: /**
0636: * Returns a copy of this datetime with the specified period added.
0637: * <p>
0638: * This method will add each element of the period one by one, from largest
0639: * to smallest, adjusting the datetime to be accurate between each.
0640: * <p>
0641: * Thus, adding a period of one month and one day to 2007-03-31 will
0642: * work as follows:
0643: * First add one month and adjust, resulting in 2007-04-30
0644: * Then add one day and adjust, resulting in 2007-05-01.
0645: * <p>
0646: * This method is typically used to add complex period instances.
0647: * Adding one field is best achieved using methods
0648: * like {@link #plusYears(int)}.
0649: * <p>
0650: * If the amount is zero or null, then <code>this</code> is returned.
0651: * This datetime instance is immutable and unaffected by this method call.
0652: *
0653: * @param period the duration to add to this one, null means zero
0654: * @return a copy of this datetime with the period added
0655: * @throws ArithmeticException if the new datetime exceeds the capacity of a long
0656: */
0657: public DateTime plus(ReadablePeriod period) {
0658: return withPeriodAdded(period, 1);
0659: }
0660:
0661: //-----------------------------------------------------------------------
0662: /**
0663: * Returns a copy of this datetime plus the specified number of years.
0664: * <p>
0665: * The calculation will do its best to only change the year field
0666: * retaining the same month of year.
0667: * However, in certain circumstances, it may be necessary to alter
0668: * smaller fields. For example, 2008-02-29 plus one year cannot result
0669: * in 2009-02-29, so the day of month is adjusted to 2009-02-28.
0670: * <p>
0671: * The following three lines are identical in effect:
0672: * <pre>
0673: * DateTime added = dt.plusYears(6);
0674: * DateTime added = dt.plus(Period.years(6));
0675: * DateTime added = dt.withFieldAdded(DurationFieldType.years(), 6);
0676: * </pre>
0677: * <p>
0678: * This datetime instance is immutable and unaffected by this method call.
0679: *
0680: * @param years the amount of years to add, may be negative
0681: * @return the new datetime plus the increased years
0682: * @since 1.1
0683: */
0684: public DateTime plusYears(int years) {
0685: if (years == 0) {
0686: return this ;
0687: }
0688: long instant = getChronology().years().add(getMillis(), years);
0689: return withMillis(instant);
0690: }
0691:
0692: /**
0693: * Returns a copy of this datetime plus the specified number of months.
0694: * <p>
0695: * The calculation will do its best to only change the month field
0696: * retaining the same day of month.
0697: * However, in certain circumstances, it may be necessary to alter
0698: * smaller fields. For example, 2007-03-31 plus one month cannot result
0699: * in 2007-04-31, so the day of month is adjusted to 2007-04-30.
0700: * <p>
0701: * The following three lines are identical in effect:
0702: * <pre>
0703: * DateTime added = dt.plusMonths(6);
0704: * DateTime added = dt.plus(Period.months(6));
0705: * DateTime added = dt.withFieldAdded(DurationFieldType.months(), 6);
0706: * </pre>
0707: * <p>
0708: * This datetime instance is immutable and unaffected by this method call.
0709: *
0710: * @param months the amount of months to add, may be negative
0711: * @return the new datetime plus the increased months
0712: * @since 1.1
0713: */
0714: public DateTime plusMonths(int months) {
0715: if (months == 0) {
0716: return this ;
0717: }
0718: long instant = getChronology().months()
0719: .add(getMillis(), months);
0720: return withMillis(instant);
0721: }
0722:
0723: /**
0724: * Returns a copy of this datetime plus the specified number of weeks.
0725: * <p>
0726: * The calculation operates as if it were adding the equivalent in days.
0727: * <p>
0728: * The following three lines are identical in effect:
0729: * <pre>
0730: * DateTime added = dt.plusWeeks(6);
0731: * DateTime added = dt.plus(Period.weeks(6));
0732: * DateTime added = dt.withFieldAdded(DurationFieldType.weeks(), 6);
0733: * </pre>
0734: * <p>
0735: * This datetime instance is immutable and unaffected by this method call.
0736: *
0737: * @param weeks the amount of weeks to add, may be negative
0738: * @return the new datetime plus the increased weeks
0739: * @since 1.1
0740: */
0741: public DateTime plusWeeks(int weeks) {
0742: if (weeks == 0) {
0743: return this ;
0744: }
0745: long instant = getChronology().weeks().add(getMillis(), weeks);
0746: return withMillis(instant);
0747: }
0748:
0749: /**
0750: * Returns a copy of this datetime plus the specified number of days.
0751: * <p>
0752: * The calculation will do its best to only change the day field
0753: * retaining the same time of day.
0754: * However, in certain circumstances, typically daylight savings cutover,
0755: * it may be necessary to alter the time fields.
0756: * <p>
0757: * In spring an hour is typically removed. If adding one day results in
0758: * the time being within the cutover then the time is adjusted to be
0759: * within summer time. For example, if the cutover is from 01:59 to 03:00
0760: * and the result of this method would have been 02:30, then the result
0761: * will be adjusted to 03:30.
0762: * <p>
0763: * The following three lines are identical in effect:
0764: * <pre>
0765: * DateTime added = dt.plusDays(6);
0766: * DateTime added = dt.plus(Period.days(6));
0767: * DateTime added = dt.withFieldAdded(DurationFieldType.days(), 6);
0768: * </pre>
0769: * <p>
0770: * This datetime instance is immutable and unaffected by this method call.
0771: *
0772: * @param days the amount of days to add, may be negative
0773: * @return the new datetime plus the increased days
0774: * @since 1.1
0775: */
0776: public DateTime plusDays(int days) {
0777: if (days == 0) {
0778: return this ;
0779: }
0780: long instant = getChronology().days().add(getMillis(), days);
0781: return withMillis(instant);
0782: }
0783:
0784: /**
0785: * Returns a copy of this datetime plus the specified number of hours.
0786: * <p>
0787: * The calculation will add a duration equivalent to the number of hours
0788: * expressed in milliseconds.
0789: * <p>
0790: * For example, if a spring daylight savings cutover is from 01:59 to 03:00
0791: * then adding one hour to 01:30 will result in 03:30. This is a duration
0792: * of one hour later, even though the hour field value changed from 1 to 3.
0793: * <p>
0794: * The following three lines are identical in effect:
0795: * <pre>
0796: * DateTime added = dt.plusHours(6);
0797: * DateTime added = dt.plus(Period.hours(6));
0798: * DateTime added = dt.withFieldAdded(DurationFieldType.hours(), 6);
0799: * </pre>
0800: * <p>
0801: * This datetime instance is immutable and unaffected by this method call.
0802: *
0803: * @param hours the amount of hours to add, may be negative
0804: * @return the new datetime plus the increased hours
0805: * @since 1.1
0806: */
0807: public DateTime plusHours(int hours) {
0808: if (hours == 0) {
0809: return this ;
0810: }
0811: long instant = getChronology().hours().add(getMillis(), hours);
0812: return withMillis(instant);
0813: }
0814:
0815: /**
0816: * Returns a copy of this datetime plus the specified number of minutes.
0817: * <p>
0818: * The calculation will add a duration equivalent to the number of minutes
0819: * expressed in milliseconds.
0820: * <p>
0821: * The following three lines are identical in effect:
0822: * <pre>
0823: * DateTime added = dt.plusMinutes(6);
0824: * DateTime added = dt.plus(Period.minutes(6));
0825: * DateTime added = dt.withFieldAdded(DurationFieldType.minutes(), 6);
0826: * </pre>
0827: * <p>
0828: * This datetime instance is immutable and unaffected by this method call.
0829: *
0830: * @param minutes the amount of minutes to add, may be negative
0831: * @return the new datetime plus the increased minutes
0832: * @since 1.1
0833: */
0834: public DateTime plusMinutes(int minutes) {
0835: if (minutes == 0) {
0836: return this ;
0837: }
0838: long instant = getChronology().minutes().add(getMillis(),
0839: minutes);
0840: return withMillis(instant);
0841: }
0842:
0843: /**
0844: * Returns a copy of this datetime plus the specified number of seconds.
0845: * <p>
0846: * The calculation will add a duration equivalent to the number of seconds
0847: * expressed in milliseconds.
0848: * <p>
0849: * The following three lines are identical in effect:
0850: * <pre>
0851: * DateTime added = dt.plusSeconds(6);
0852: * DateTime added = dt.plus(Period.seconds(6));
0853: * DateTime added = dt.withFieldAdded(DurationFieldType.seconds(), 6);
0854: * </pre>
0855: * <p>
0856: * This datetime instance is immutable and unaffected by this method call.
0857: *
0858: * @param seconds the amount of seconds to add, may be negative
0859: * @return the new datetime plus the increased seconds
0860: * @since 1.1
0861: */
0862: public DateTime plusSeconds(int seconds) {
0863: if (seconds == 0) {
0864: return this ;
0865: }
0866: long instant = getChronology().seconds().add(getMillis(),
0867: seconds);
0868: return withMillis(instant);
0869: }
0870:
0871: /**
0872: * Returns a copy of this datetime plus the specified number of millis.
0873: * <p>
0874: * The calculation will add a duration equivalent to the number of milliseconds.
0875: * <p>
0876: * The following three lines are identical in effect:
0877: * <pre>
0878: * DateTime added = dt.plusMillis(6);
0879: * DateTime added = dt.plus(Period.millis(6));
0880: * DateTime added = dt.withFieldAdded(DurationFieldType.millis(), 6);
0881: * </pre>
0882: * <p>
0883: * This datetime instance is immutable and unaffected by this method call.
0884: *
0885: * @param millis the amount of millis to add, may be negative
0886: * @return the new datetime plus the increased millis
0887: * @since 1.1
0888: */
0889: public DateTime plusMillis(int millis) {
0890: if (millis == 0) {
0891: return this ;
0892: }
0893: long instant = getChronology().millis()
0894: .add(getMillis(), millis);
0895: return withMillis(instant);
0896: }
0897:
0898: //-----------------------------------------------------------------------
0899: /**
0900: * Returns a copy of this datetime with the specified duration taken away.
0901: * <p>
0902: * If the amount is zero or null, then <code>this</code> is returned.
0903: * This datetime instance is immutable and unaffected by this method call.
0904: *
0905: * @param duration the duration, in millis, to reduce this instant by
0906: * @return a copy of this datetime with the duration taken away
0907: * @throws ArithmeticException if the new datetime exceeds the capacity of a long
0908: */
0909: public DateTime minus(long duration) {
0910: return withDurationAdded(duration, -1);
0911: }
0912:
0913: /**
0914: * Returns a copy of this datetime with the specified duration taken away.
0915: * <p>
0916: * If the amount is zero or null, then <code>this</code> is returned.
0917: * This datetime instance is immutable and unaffected by this method call.
0918: *
0919: * @param duration the duration to reduce this instant by
0920: * @return a copy of this datetime with the duration taken away
0921: * @throws ArithmeticException if the new datetime exceeds the capacity of a long
0922: */
0923: public DateTime minus(ReadableDuration duration) {
0924: return withDurationAdded(duration, -1);
0925: }
0926:
0927: /**
0928: * Returns a copy of this datetime with the specified period taken away.
0929: * <p>
0930: * This method will subtract each element of the period one by one, from
0931: * largest to smallest, adjusting the datetime to be accurate between each.
0932: * <p>
0933: * Thus, subtracting a period of one month and one day from 2007-05-31 will
0934: * work as follows:
0935: * First subtract one month and adjust, resulting in 2007-04-30
0936: * Then subtract one day and adjust, resulting in 2007-04-29.
0937: * Note that the day has been adjusted by two.
0938: * <p>
0939: * This method is typically used to subtract complex period instances.
0940: * Subtracting one field is best achieved using methods
0941: * like {@link #minusYears(int)}.
0942: * <p>
0943: * If the amount is zero or null, then <code>this</code> is returned.
0944: * This datetime instance is immutable and unaffected by this method call.
0945: *
0946: * @param period the period to reduce this instant by
0947: * @return a copy of this datetime with the period taken away
0948: * @throws ArithmeticException if the new datetime exceeds the capacity of a long
0949: */
0950: public DateTime minus(ReadablePeriod period) {
0951: return withPeriodAdded(period, -1);
0952: }
0953:
0954: //-----------------------------------------------------------------------
0955: /**
0956: * Returns a copy of this datetime minus the specified number of years.
0957: * <p>
0958: * The calculation will do its best to only change the year field
0959: * retaining the same month of year.
0960: * However, in certain circumstances, it may be necessary to alter
0961: * smaller fields. For example, 2008-02-29 minus one year cannot result
0962: * in 2007-02-29, so the day of month is adjusted to 2007-02-28.
0963: * <p>
0964: * The following three lines are identical in effect:
0965: * <pre>
0966: * DateTime subtracted = dt.minusYears(6);
0967: * DateTime subtracted = dt.minus(Period.years(6));
0968: * DateTime subtracted = dt.withFieldAdded(DurationFieldType.years(), -6);
0969: * </pre>
0970: * <p>
0971: * This datetime instance is immutable and unaffected by this method call.
0972: *
0973: * @param years the amount of years to subtract, may be negative
0974: * @return the new datetime minus the increased years
0975: * @since 1.1
0976: */
0977: public DateTime minusYears(int years) {
0978: if (years == 0) {
0979: return this ;
0980: }
0981: long instant = getChronology().years().subtract(getMillis(),
0982: years);
0983: return withMillis(instant);
0984: }
0985:
0986: /**
0987: * Returns a copy of this datetime minus the specified number of months.
0988: * <p>
0989: * The calculation will do its best to only change the month field
0990: * retaining the same day of month.
0991: * However, in certain circumstances, it may be necessary to alter
0992: * smaller fields. For example, 2007-05-31 minus one month cannot result
0993: * in 2007-04-31, so the day of month is adjusted to 2007-04-30.
0994: * <p>
0995: * The following three lines are identical in effect:
0996: * <pre>
0997: * DateTime subtracted = dt.minusMonths(6);
0998: * DateTime subtracted = dt.minus(Period.months(6));
0999: * DateTime subtracted = dt.withFieldAdded(DurationFieldType.months(), -6);
1000: * </pre>
1001: * <p>
1002: * This datetime instance is immutable and unaffected by this method call.
1003: *
1004: * @param months the amount of months to subtract, may be negative
1005: * @return the new datetime minus the increased months
1006: * @since 1.1
1007: */
1008: public DateTime minusMonths(int months) {
1009: if (months == 0) {
1010: return this ;
1011: }
1012: long instant = getChronology().months().subtract(getMillis(),
1013: months);
1014: return withMillis(instant);
1015: }
1016:
1017: /**
1018: * Returns a copy of this datetime minus the specified number of weeks.
1019: * <p>
1020: * The calculation operates as if it were subtracting the equivalent in days.
1021: * <p>
1022: * The following three lines are identical in effect:
1023: * <pre>
1024: * DateTime subtracted = dt.minusWeeks(6);
1025: * DateTime subtracted = dt.minus(Period.weeks(6));
1026: * DateTime subtracted = dt.withFieldAdded(DurationFieldType.weeks(), -6);
1027: * </pre>
1028: * <p>
1029: * This datetime instance is immutable and unaffected by this method call.
1030: *
1031: * @param weeks the amount of weeks to subtract, may be negative
1032: * @return the new datetime minus the increased weeks
1033: * @since 1.1
1034: */
1035: public DateTime minusWeeks(int weeks) {
1036: if (weeks == 0) {
1037: return this ;
1038: }
1039: long instant = getChronology().weeks().subtract(getMillis(),
1040: weeks);
1041: return withMillis(instant);
1042: }
1043:
1044: /**
1045: * Returns a copy of this datetime minus the specified number of days.
1046: * <p>
1047: * The calculation will do its best to only change the day field
1048: * retaining the same time of day.
1049: * However, in certain circumstances, typically daylight savings cutover,
1050: * it may be necessary to alter the time fields.
1051: * <p>
1052: * In spring an hour is typically removed. If subtracting one day results
1053: * in the time being within the cutover then the time is adjusted to be
1054: * within summer time. For example, if the cutover is from 01:59 to 03:00
1055: * and the result of this method would have been 02:30, then the result
1056: * will be adjusted to 03:30.
1057: * <p>
1058: * The following three lines are identical in effect:
1059: * <pre>
1060: * DateTime subtracted = dt.minusDays(6);
1061: * DateTime subtracted = dt.minus(Period.days(6));
1062: * DateTime subtracted = dt.withFieldAdded(DurationFieldType.days(), -6);
1063: * </pre>
1064: * <p>
1065: * This datetime instance is immutable and unaffected by this method call.
1066: *
1067: * @param days the amount of days to subtract, may be negative
1068: * @return the new datetime minus the increased days
1069: * @since 1.1
1070: */
1071: public DateTime minusDays(int days) {
1072: if (days == 0) {
1073: return this ;
1074: }
1075: long instant = getChronology().days().subtract(getMillis(),
1076: days);
1077: return withMillis(instant);
1078: }
1079:
1080: /**
1081: * Returns a copy of this datetime minus the specified number of hours.
1082: * <p>
1083: * The calculation will subtract a duration equivalent to the number of
1084: * hours expressed in milliseconds.
1085: * <p>
1086: * For example, if a spring daylight savings cutover is from 01:59 to 03:00
1087: * then subtracting one hour from 03:30 will result in 01:30. This is a
1088: * duration of one hour earlier, even though the hour field value changed
1089: * from 3 to 1.
1090: * <p>
1091: * The following three lines are identical in effect:
1092: * <pre>
1093: * DateTime subtracted = dt.minusHours(6);
1094: * DateTime subtracted = dt.minus(Period.hours(6));
1095: * DateTime subtracted = dt.withFieldAdded(DurationFieldType.hours(), -6);
1096: * </pre>
1097: * <p>
1098: * This datetime instance is immutable and unaffected by this method call.
1099: *
1100: * @param hours the amount of hours to subtract, may be negative
1101: * @return the new datetime minus the increased hours
1102: * @since 1.1
1103: */
1104: public DateTime minusHours(int hours) {
1105: if (hours == 0) {
1106: return this ;
1107: }
1108: long instant = getChronology().hours().subtract(getMillis(),
1109: hours);
1110: return withMillis(instant);
1111: }
1112:
1113: /**
1114: * Returns a copy of this datetime minus the specified number of minutes.
1115: * <p>
1116: * The calculation will subtract a duration equivalent to the number of
1117: * minutes expressed in milliseconds.
1118: * <p>
1119: * The following three lines are identical in effect:
1120: * <pre>
1121: * DateTime subtracted = dt.minusMinutes(6);
1122: * DateTime subtracted = dt.minus(Period.minutes(6));
1123: * DateTime subtracted = dt.withFieldAdded(DurationFieldType.minutes(), -6);
1124: * </pre>
1125: * <p>
1126: * This datetime instance is immutable and unaffected by this method call.
1127: *
1128: * @param minutes the amount of minutes to subtract, may be negative
1129: * @return the new datetime minus the increased minutes
1130: * @since 1.1
1131: */
1132: public DateTime minusMinutes(int minutes) {
1133: if (minutes == 0) {
1134: return this ;
1135: }
1136: long instant = getChronology().minutes().subtract(getMillis(),
1137: minutes);
1138: return withMillis(instant);
1139: }
1140:
1141: /**
1142: * Returns a copy of this datetime minus the specified number of seconds.
1143: * <p>
1144: * The calculation will subtract a duration equivalent to the number of
1145: * seconds expressed in milliseconds.
1146: * <p>
1147: * The following three lines are identical in effect:
1148: * <pre>
1149: * DateTime subtracted = dt.minusSeconds(6);
1150: * DateTime subtracted = dt.minus(Period.seconds(6));
1151: * DateTime subtracted = dt.withFieldAdded(DurationFieldType.seconds(), -6);
1152: * </pre>
1153: * <p>
1154: * This datetime instance is immutable and unaffected by this method call.
1155: *
1156: * @param seconds the amount of seconds to subtract, may be negative
1157: * @return the new datetime minus the increased seconds
1158: * @since 1.1
1159: */
1160: public DateTime minusSeconds(int seconds) {
1161: if (seconds == 0) {
1162: return this ;
1163: }
1164: long instant = getChronology().seconds().subtract(getMillis(),
1165: seconds);
1166: return withMillis(instant);
1167: }
1168:
1169: /**
1170: * Returns a copy of this datetime minus the specified number of millis.
1171: * <p>
1172: * The calculation will subtract a duration equivalent to the number of
1173: * milliseconds.
1174: * <p>
1175: * The following three lines are identical in effect:
1176: * <pre>
1177: * DateTime subtracted = dt.minusMillis(6);
1178: * DateTime subtracted = dt.minus(Period.millis(6));
1179: * DateTime subtracted = dt.withFieldAdded(DurationFieldType.millis(), -6);
1180: * </pre>
1181: * <p>
1182: * This datetime instance is immutable and unaffected by this method call.
1183: *
1184: * @param millis the amount of millis to subtract, may be negative
1185: * @return the new datetime minus the increased millis
1186: * @since 1.1
1187: */
1188: public DateTime minusMillis(int millis) {
1189: if (millis == 0) {
1190: return this ;
1191: }
1192: long instant = getChronology().millis().subtract(getMillis(),
1193: millis);
1194: return withMillis(instant);
1195: }
1196:
1197: //-----------------------------------------------------------------------
1198: /**
1199: * Gets the property object for the specified type, which contains many useful methods.
1200: *
1201: * @param type the field type to get the chronology for
1202: * @return the property object
1203: * @throws IllegalArgumentException if the field is null or unsupported
1204: */
1205: public Property property(DateTimeFieldType type) {
1206: if (type == null) {
1207: throw new IllegalArgumentException(
1208: "The DateTimeFieldType must not be null");
1209: }
1210: DateTimeField field = type.getField(getChronology());
1211: if (field.isSupported() == false) {
1212: throw new IllegalArgumentException("Field '" + type
1213: + "' is not supported");
1214: }
1215: return new Property(this , field);
1216: }
1217:
1218: //-----------------------------------------------------------------------
1219: /**
1220: * Converts this object to a <code>DateMidnight</code> using the
1221: * same millis and chronology.
1222: *
1223: * @return a DateMidnight using the same millis and chronology
1224: */
1225: public DateMidnight toDateMidnight() {
1226: return new DateMidnight(getMillis(), getChronology());
1227: }
1228:
1229: /**
1230: * Converts this object to a <code>YearMonthDay</code> using the
1231: * same millis and chronology.
1232: *
1233: * @return a YearMonthDay using the same millis and chronology
1234: * @deprecated Use LocalDate instead of YearMonthDay
1235: */
1236: public YearMonthDay toYearMonthDay() {
1237: return new YearMonthDay(getMillis(), getChronology());
1238: }
1239:
1240: /**
1241: * Converts this object to a <code>TimeOfDay</code> using the
1242: * same millis and chronology.
1243: *
1244: * @return a TimeOfDay using the same millis and chronology
1245: * @deprecated Use LocalTime instead of TimeOfDay
1246: */
1247: public TimeOfDay toTimeOfDay() {
1248: return new TimeOfDay(getMillis(), getChronology());
1249: }
1250:
1251: /**
1252: * Converts this object to a <code>LocalDateTime</code> with
1253: * the same datetime and chronology.
1254: *
1255: * @return a LocalDateTime with the same datetime and chronology
1256: * @since 1.3
1257: */
1258: public LocalDateTime toLocalDateTime() {
1259: return new LocalDateTime(getMillis(), getChronology());
1260: }
1261:
1262: /**
1263: * Converts this object to a <code>LocalDate</code> with the
1264: * same date and chronology.
1265: *
1266: * @return a LocalDate with the same date and chronology
1267: * @since 1.3
1268: */
1269: public LocalDate toLocalDate() {
1270: return new LocalDate(getMillis(), getChronology());
1271: }
1272:
1273: /**
1274: * Converts this object to a <code>LocalTime</code> with the
1275: * same time and chronology.
1276: *
1277: * @return a LocalTime with the same time and chronology
1278: * @since 1.3
1279: */
1280: public LocalTime toLocalTime() {
1281: return new LocalTime(getMillis(), getChronology());
1282: }
1283:
1284: //-----------------------------------------------------------------------
1285: /**
1286: * Returns a copy of this datetime with the era field updated.
1287: * <p>
1288: * DateTime is immutable, so there are no set methods.
1289: * Instead, this method returns a new instance with the value of
1290: * era changed.
1291: *
1292: * @param era the era to set
1293: * @return a copy of this object with the field set
1294: * @throws IllegalArgumentException if the value is invalid
1295: * @since 1.3
1296: */
1297: public DateTime withEra(int era) {
1298: return withMillis(getChronology().era().set(getMillis(), era));
1299: }
1300:
1301: /**
1302: * Returns a copy of this datetime with the century of era field updated.
1303: * <p>
1304: * DateTime is immutable, so there are no set methods.
1305: * Instead, this method returns a new instance with the value of
1306: * century of era changed.
1307: *
1308: * @param centuryOfEra the centurey of era to set
1309: * @return a copy of this object with the field set
1310: * @throws IllegalArgumentException if the value is invalid
1311: * @since 1.3
1312: */
1313: public DateTime withCenturyOfEra(int centuryOfEra) {
1314: return withMillis(getChronology().centuryOfEra().set(
1315: getMillis(), centuryOfEra));
1316: }
1317:
1318: /**
1319: * Returns a copy of this datetime with the year of era field updated.
1320: * <p>
1321: * DateTime is immutable, so there are no set methods.
1322: * Instead, this method returns a new instance with the value of
1323: * year of era changed.
1324: *
1325: * @param yearOfEra the year of era to set
1326: * @return a copy of this object with the field set
1327: * @throws IllegalArgumentException if the value is invalid
1328: * @since 1.3
1329: */
1330: public DateTime withYearOfEra(int yearOfEra) {
1331: return withMillis(getChronology().yearOfEra().set(getMillis(),
1332: yearOfEra));
1333: }
1334:
1335: /**
1336: * Returns a copy of this datetime with the year of century field updated.
1337: * <p>
1338: * DateTime is immutable, so there are no set methods.
1339: * Instead, this method returns a new instance with the value of
1340: * year of century changed.
1341: *
1342: * @param yearOfCentury the year of century to set
1343: * @return a copy of this object with the field set
1344: * @throws IllegalArgumentException if the value is invalid
1345: * @since 1.3
1346: */
1347: public DateTime withYearOfCentury(int yearOfCentury) {
1348: return withMillis(getChronology().yearOfCentury().set(
1349: getMillis(), yearOfCentury));
1350: }
1351:
1352: /**
1353: * Returns a copy of this datetime with the year field updated.
1354: * <p>
1355: * DateTime is immutable, so there are no set methods.
1356: * Instead, this method returns a new instance with the value of
1357: * year changed.
1358: *
1359: * @param year the year to set
1360: * @return a copy of this object with the field set
1361: * @throws IllegalArgumentException if the value is invalid
1362: * @since 1.3
1363: */
1364: public DateTime withYear(int year) {
1365: return withMillis(getChronology().year().set(getMillis(), year));
1366: }
1367:
1368: /**
1369: * Returns a copy of this datetime with the weekyear field updated.
1370: * <p>
1371: * DateTime is immutable, so there are no set methods.
1372: * Instead, this method returns a new instance with the value of
1373: * weekyear changed.
1374: *
1375: * @param weekyear the weekyear to set
1376: * @return a copy of this object with the field set
1377: * @throws IllegalArgumentException if the value is invalid
1378: * @since 1.3
1379: */
1380: public DateTime withWeekyear(int weekyear) {
1381: return withMillis(getChronology().weekyear().set(getMillis(),
1382: weekyear));
1383: }
1384:
1385: /**
1386: * Returns a copy of this datetime with the month of year field updated.
1387: * <p>
1388: * DateTime is immutable, so there are no set methods.
1389: * Instead, this method returns a new instance with the value of
1390: * month of year changed.
1391: *
1392: * @param monthOfYear the month of year to set
1393: * @return a copy of this object with the field set
1394: * @throws IllegalArgumentException if the value is invalid
1395: * @since 1.3
1396: */
1397: public DateTime withMonthOfYear(int monthOfYear) {
1398: return withMillis(getChronology().monthOfYear().set(
1399: getMillis(), monthOfYear));
1400: }
1401:
1402: /**
1403: * Returns a copy of this datetime with the week of weekyear field updated.
1404: * <p>
1405: * DateTime is immutable, so there are no set methods.
1406: * Instead, this method returns a new instance with the value of
1407: * week of weekyear changed.
1408: *
1409: * @param weekOfWeekyear the week of weekyear to set
1410: * @return a copy of this object with the field set
1411: * @throws IllegalArgumentException if the value is invalid
1412: * @since 1.3
1413: */
1414: public DateTime withWeekOfWeekyear(int weekOfWeekyear) {
1415: return withMillis(getChronology().weekOfWeekyear().set(
1416: getMillis(), weekOfWeekyear));
1417: }
1418:
1419: /**
1420: * Returns a copy of this datetime with the day of year field updated.
1421: * <p>
1422: * DateTime is immutable, so there are no set methods.
1423: * Instead, this method returns a new instance with the value of
1424: * day of year changed.
1425: *
1426: * @param dayOfYear the day of year to set
1427: * @return a copy of this object with the field set
1428: * @throws IllegalArgumentException if the value is invalid
1429: * @since 1.3
1430: */
1431: public DateTime withDayOfYear(int dayOfYear) {
1432: return withMillis(getChronology().dayOfYear().set(getMillis(),
1433: dayOfYear));
1434: }
1435:
1436: /**
1437: * Returns a copy of this datetime with the day of month field updated.
1438: * <p>
1439: * DateTime is immutable, so there are no set methods.
1440: * Instead, this method returns a new instance with the value of
1441: * day of month changed.
1442: *
1443: * @param dayOfMonth the day of month to set
1444: * @return a copy of this object with the field set
1445: * @throws IllegalArgumentException if the value is invalid
1446: * @since 1.3
1447: */
1448: public DateTime withDayOfMonth(int dayOfMonth) {
1449: return withMillis(getChronology().dayOfMonth().set(getMillis(),
1450: dayOfMonth));
1451: }
1452:
1453: /**
1454: * Returns a copy of this datetime with the day of week field updated.
1455: * <p>
1456: * DateTime is immutable, so there are no set methods.
1457: * Instead, this method returns a new instance with the value of
1458: * day of week changed.
1459: *
1460: * @param dayOfWeek the day of week to set
1461: * @return a copy of this object with the field set
1462: * @throws IllegalArgumentException if the value is invalid
1463: * @since 1.3
1464: */
1465: public DateTime withDayOfWeek(int dayOfWeek) {
1466: return withMillis(getChronology().dayOfWeek().set(getMillis(),
1467: dayOfWeek));
1468: }
1469:
1470: //-----------------------------------------------------------------------
1471: /**
1472: * Returns a copy of this datetime with the hour of day field updated.
1473: * <p>
1474: * DateTime is immutable, so there are no set methods.
1475: * Instead, this method returns a new instance with the value of
1476: * hour of day changed.
1477: *
1478: * @param hour the hour of day to set
1479: * @return a copy of this object with the field set
1480: * @throws IllegalArgumentException if the value is invalid
1481: * @since 1.3
1482: */
1483: public DateTime withHourOfDay(int hour) {
1484: return withMillis(getChronology().hourOfDay().set(getMillis(),
1485: hour));
1486: }
1487:
1488: /**
1489: * Returns a copy of this datetime with the minute of hour updated.
1490: * <p>
1491: * DateTime is immutable, so there are no set methods.
1492: * Instead, this method returns a new instance with the value of
1493: * minute of hour changed.
1494: *
1495: * @param minute the minute of hour to set
1496: * @return a copy of this object with the field set
1497: * @throws IllegalArgumentException if the value is invalid
1498: * @since 1.3
1499: */
1500: public DateTime withMinuteOfHour(int minute) {
1501: return withMillis(getChronology().minuteOfHour().set(
1502: getMillis(), minute));
1503: }
1504:
1505: /**
1506: * Returns a copy of this datetime with the second of minute field updated.
1507: * <p>
1508: * DateTime is immutable, so there are no set methods.
1509: * Instead, this method returns a new instance with the value of
1510: * second of minute changed.
1511: *
1512: * @param second the second of minute to set
1513: * @return a copy of this object with the field set
1514: * @throws IllegalArgumentException if the value is invalid
1515: * @since 1.3
1516: */
1517: public DateTime withSecondOfMinute(int second) {
1518: return withMillis(getChronology().secondOfMinute().set(
1519: getMillis(), second));
1520: }
1521:
1522: /**
1523: * Returns a copy of this datetime with the millis of second field updated.
1524: * <p>
1525: * DateTime is immutable, so there are no set methods.
1526: * Instead, this method returns a new instance with the value of
1527: * millis of second changed.
1528: *
1529: * @param millis the millis of second to set
1530: * @return a copy of this object with the field set
1531: * @throws IllegalArgumentException if the value is invalid
1532: * @since 1.3
1533: */
1534: public DateTime withMillisOfSecond(int millis) {
1535: return withMillis(getChronology().millisOfSecond().set(
1536: getMillis(), millis));
1537: }
1538:
1539: /**
1540: * Returns a copy of this datetime with the millis of day field updated.
1541: * <p>
1542: * DateTime is immutable, so there are no set methods.
1543: * Instead, this method returns a new instance with the value of
1544: * millis of day changed.
1545: *
1546: * @param millis the millis of day to set
1547: * @return a copy of this object with the field set
1548: * @throws IllegalArgumentException if the value is invalid
1549: * @since 1.3
1550: */
1551: public DateTime withMillisOfDay(int millis) {
1552: return withMillis(getChronology().millisOfDay().set(
1553: getMillis(), millis));
1554: }
1555:
1556: // Date properties
1557: //-----------------------------------------------------------------------
1558: /**
1559: * Get the era property which provides access to advanced functionality.
1560: *
1561: * @return the era property
1562: */
1563: public Property era() {
1564: return new Property(this , getChronology().era());
1565: }
1566:
1567: /**
1568: * Get the century of era property which provides access to advanced functionality.
1569: *
1570: * @return the year of era property
1571: */
1572: public Property centuryOfEra() {
1573: return new Property(this , getChronology().centuryOfEra());
1574: }
1575:
1576: /**
1577: * Get the year of century property which provides access to advanced functionality.
1578: *
1579: * @return the year of era property
1580: */
1581: public Property yearOfCentury() {
1582: return new Property(this , getChronology().yearOfCentury());
1583: }
1584:
1585: /**
1586: * Get the year of era property which provides access to advanced functionality.
1587: *
1588: * @return the year of era property
1589: */
1590: public Property yearOfEra() {
1591: return new Property(this , getChronology().yearOfEra());
1592: }
1593:
1594: /**
1595: * Get the year property which provides access to advanced functionality.
1596: *
1597: * @return the year property
1598: */
1599: public Property year() {
1600: return new Property(this , getChronology().year());
1601: }
1602:
1603: /**
1604: * Get the year of a week based year property which provides access to advanced functionality.
1605: *
1606: * @return the year of a week based year property
1607: */
1608: public Property weekyear() {
1609: return new Property(this , getChronology().weekyear());
1610: }
1611:
1612: /**
1613: * Get the month of year property which provides access to advanced functionality.
1614: *
1615: * @return the month of year property
1616: */
1617: public Property monthOfYear() {
1618: return new Property(this , getChronology().monthOfYear());
1619: }
1620:
1621: /**
1622: * Get the week of a week based year property which provides access to advanced functionality.
1623: *
1624: * @return the week of a week based year property
1625: */
1626: public Property weekOfWeekyear() {
1627: return new Property(this , getChronology().weekOfWeekyear());
1628: }
1629:
1630: /**
1631: * Get the day of year property which provides access to advanced functionality.
1632: *
1633: * @return the day of year property
1634: */
1635: public Property dayOfYear() {
1636: return new Property(this , getChronology().dayOfYear());
1637: }
1638:
1639: /**
1640: * Get the day of month property which provides access to advanced functionality.
1641: *
1642: * @return the day of month property
1643: */
1644: public Property dayOfMonth() {
1645: return new Property(this , getChronology().dayOfMonth());
1646: }
1647:
1648: /**
1649: * Get the day of week property which provides access to advanced functionality.
1650: *
1651: * @return the day of week property
1652: */
1653: public Property dayOfWeek() {
1654: return new Property(this , getChronology().dayOfWeek());
1655: }
1656:
1657: // Time properties
1658: //-----------------------------------------------------------------------
1659: /**
1660: * Get the hour of day field property which provides access to advanced functionality.
1661: *
1662: * @return the hour of day property
1663: */
1664: public Property hourOfDay() {
1665: return new Property(this , getChronology().hourOfDay());
1666: }
1667:
1668: /**
1669: * Get the minute of day property which provides access to advanced functionality.
1670: *
1671: * @return the minute of day property
1672: */
1673: public Property minuteOfDay() {
1674: return new Property(this , getChronology().minuteOfDay());
1675: }
1676:
1677: /**
1678: * Get the minute of hour field property which provides access to advanced functionality.
1679: *
1680: * @return the minute of hour property
1681: */
1682: public Property minuteOfHour() {
1683: return new Property(this , getChronology().minuteOfHour());
1684: }
1685:
1686: /**
1687: * Get the second of day property which provides access to advanced functionality.
1688: *
1689: * @return the second of day property
1690: */
1691: public Property secondOfDay() {
1692: return new Property(this , getChronology().secondOfDay());
1693: }
1694:
1695: /**
1696: * Get the second of minute field property which provides access to advanced functionality.
1697: *
1698: * @return the second of minute property
1699: */
1700: public Property secondOfMinute() {
1701: return new Property(this , getChronology().secondOfMinute());
1702: }
1703:
1704: /**
1705: * Get the millis of day property which provides access to advanced functionality.
1706: *
1707: * @return the millis of day property
1708: */
1709: public Property millisOfDay() {
1710: return new Property(this , getChronology().millisOfDay());
1711: }
1712:
1713: /**
1714: * Get the millis of second property which provides access to advanced functionality.
1715: *
1716: * @return the millis of second property
1717: */
1718: public Property millisOfSecond() {
1719: return new Property(this , getChronology().millisOfSecond());
1720: }
1721:
1722: //-----------------------------------------------------------------------
1723: /**
1724: * DateTime.Property binds a DateTime to a DateTimeField allowing powerful
1725: * datetime functionality to be easily accessed.
1726: * <p>
1727: * The simplest use of this class is as an alternative get method, here used to
1728: * get the year '1972' (as an int) and the month 'December' (as a String).
1729: * <pre>
1730: * DateTime dt = new DateTime(1972, 12, 3, 0, 0, 0, 0);
1731: * int year = dt.year().get();
1732: * String monthStr = dt.month().getAsText();
1733: * </pre>
1734: * <p>
1735: * Methods are also provided that allow date modification. These return new instances
1736: * of DateTime - they do not modify the original. The example below yields two
1737: * independent immutable date objects 20 years apart.
1738: * <pre>
1739: * DateTime dt = new DateTime(1972, 12, 3, 0, 0, 0, 0);
1740: * DateTime dt20 = dt.year().addToCopy(20);
1741: * </pre>
1742: * Serious modification of dates (ie. more than just changing one or two fields)
1743: * should use the {@link org.joda.time.MutableDateTime MutableDateTime} class.
1744: * <p>
1745: * DateTime.Propery itself is thread-safe and immutable, as well as the
1746: * DateTime being operated on.
1747: *
1748: * @author Stephen Colebourne
1749: * @author Brian S O'Neill
1750: * @since 1.0
1751: */
1752: public static final class Property extends
1753: AbstractReadableInstantFieldProperty {
1754:
1755: /** Serialization version */
1756: private static final long serialVersionUID = -6983323811635733510L;
1757:
1758: /** The instant this property is working against */
1759: private DateTime iInstant;
1760: /** The field this property is working against */
1761: private DateTimeField iField;
1762:
1763: /**
1764: * Constructor.
1765: *
1766: * @param instant the instant to set
1767: * @param field the field to use
1768: */
1769: Property(DateTime instant, DateTimeField field) {
1770: super ();
1771: iInstant = instant;
1772: iField = field;
1773: }
1774:
1775: /**
1776: * Writes the property in a safe serialization format.
1777: */
1778: private void writeObject(ObjectOutputStream oos)
1779: throws IOException {
1780: oos.writeObject(iInstant);
1781: oos.writeObject(iField.getType());
1782: }
1783:
1784: /**
1785: * Reads the property from a safe serialization format.
1786: */
1787: private void readObject(ObjectInputStream oos)
1788: throws IOException, ClassNotFoundException {
1789: iInstant = (DateTime) oos.readObject();
1790: DateTimeFieldType type = (DateTimeFieldType) oos
1791: .readObject();
1792: iField = type.getField(iInstant.getChronology());
1793: }
1794:
1795: //-----------------------------------------------------------------------
1796: /**
1797: * Gets the field being used.
1798: *
1799: * @return the field
1800: */
1801: public DateTimeField getField() {
1802: return iField;
1803: }
1804:
1805: /**
1806: * Gets the milliseconds of the datetime that this property is linked to.
1807: *
1808: * @return the milliseconds
1809: */
1810: protected long getMillis() {
1811: return iInstant.getMillis();
1812: }
1813:
1814: /**
1815: * Gets the chronology of the datetime that this property is linked to.
1816: *
1817: * @return the chronology
1818: * @since 1.4
1819: */
1820: protected Chronology getChronology() {
1821: return iInstant.getChronology();
1822: }
1823:
1824: /**
1825: * Gets the datetime being used.
1826: *
1827: * @return the datetime
1828: */
1829: public DateTime getDateTime() {
1830: return iInstant;
1831: }
1832:
1833: //-----------------------------------------------------------------------
1834: /**
1835: * Adds to this field in a copy of this DateTime.
1836: * <p>
1837: * The DateTime attached to this property is unchanged by this call.
1838: * This operation is faster than converting a DateTime to a MutableDateTime
1839: * and back again when setting one field. When setting multiple fields,
1840: * it is generally quicker to make the conversion to MutableDateTime.
1841: *
1842: * @param value the value to add to the field in the copy
1843: * @return a copy of the DateTime with the field value changed
1844: * @throws IllegalArgumentException if the value isn't valid
1845: */
1846: public DateTime addToCopy(int value) {
1847: return iInstant.withMillis(iField.add(iInstant.getMillis(),
1848: value));
1849: }
1850:
1851: /**
1852: * Adds to this field in a copy of this DateTime.
1853: * <p>
1854: * The DateTime attached to this property is unchanged by this call.
1855: * This operation is faster than converting a DateTime to a MutableDateTime
1856: * and back again when setting one field. When setting multiple fields,
1857: * it is generally quicker to make the conversion to MutableDateTime.
1858: *
1859: * @param value the value to add to the field in the copy
1860: * @return a copy of the DateTime with the field value changed
1861: * @throws IllegalArgumentException if the value isn't valid
1862: */
1863: public DateTime addToCopy(long value) {
1864: return iInstant.withMillis(iField.add(iInstant.getMillis(),
1865: value));
1866: }
1867:
1868: /**
1869: * Adds to this field, possibly wrapped, in a copy of this DateTime.
1870: * A wrapped operation only changes this field.
1871: * Thus 31st January addWrapField one day goes to the 1st January.
1872: * <p>
1873: * The DateTime attached to this property is unchanged by this call.
1874: * This operation is faster than converting a DateTime to a MutableDateTime
1875: * and back again when setting one field. When setting multiple fields,
1876: * it is generally quicker to make the conversion to MutableDateTime.
1877: *
1878: * @param value the value to add to the field in the copy
1879: * @return a copy of the DateTime with the field value changed
1880: * @throws IllegalArgumentException if the value isn't valid
1881: */
1882: public DateTime addWrapFieldToCopy(int value) {
1883: return iInstant.withMillis(iField.addWrapField(iInstant
1884: .getMillis(), value));
1885: }
1886:
1887: //-----------------------------------------------------------------------
1888: /**
1889: * Sets this field in a copy of the DateTime.
1890: * <p>
1891: * The DateTime attached to this property is unchanged by this call.
1892: * This operation is faster than converting a DateTime to a MutableDateTime
1893: * and back again when setting one field. When setting multiple fields,
1894: * it is generally quicker to make the conversion to MutableDateTime.
1895: *
1896: * @param value the value to set the field in the copy to
1897: * @return a copy of the DateTime with the field value changed
1898: * @throws IllegalArgumentException if the value isn't valid
1899: */
1900: public DateTime setCopy(int value) {
1901: return iInstant.withMillis(iField.set(iInstant.getMillis(),
1902: value));
1903: }
1904:
1905: /**
1906: * Sets this field in a copy of the DateTime to a parsed text value.
1907: * <p>
1908: * The DateTime attached to this property is unchanged by this call.
1909: * This operation is faster than converting a DateTime to a MutableDateTime
1910: * and back again when setting one field. When setting multiple fields,
1911: * it is generally quicker to make the conversion to MutableDateTime.
1912: *
1913: * @param text the text value to set
1914: * @param locale optional locale to use for selecting a text symbol
1915: * @return a copy of the DateTime with the field value changed
1916: * @throws IllegalArgumentException if the text value isn't valid
1917: */
1918: public DateTime setCopy(String text, Locale locale) {
1919: return iInstant.withMillis(iField.set(iInstant.getMillis(),
1920: text, locale));
1921: }
1922:
1923: /**
1924: * Sets this field in a copy of the DateTime to a parsed text value.
1925: * <p>
1926: * The DateTime attached to this property is unchanged by this call.
1927: * This operation is faster than converting a DateTime to a MutableDateTime
1928: * and back again when setting one field. When setting multiple fields,
1929: * it is generally quicker to make the conversion to MutableDateTime.
1930: *
1931: * @param text the text value to set
1932: * @return a copy of the DateTime with the field value changed
1933: * @throws IllegalArgumentException if the text value isn't valid
1934: */
1935: public DateTime setCopy(String text) {
1936: return setCopy(text, null);
1937: }
1938:
1939: //-----------------------------------------------------------------------
1940: /**
1941: * Returns a new DateTime with this field set to the maximum value
1942: * for this field.
1943: * <p>
1944: * This operation is useful for obtaining a DateTime on the last day
1945: * of the month, as month lengths vary.
1946: * <pre>
1947: * DateTime lastDayOfMonth = dt.dayOfMonth().withMaximumValue();
1948: * </pre>
1949: * <p>
1950: * The DateTime attached to this property is unchanged by this call.
1951: *
1952: * @return a copy of the DateTime with this field set to its maximum
1953: * @since 1.2
1954: */
1955: public DateTime withMaximumValue() {
1956: return setCopy(getMaximumValue());
1957: }
1958:
1959: /**
1960: * Returns a new DateTime with this field set to the minimum value
1961: * for this field.
1962: * <p>
1963: * The DateTime attached to this property is unchanged by this call.
1964: *
1965: * @return a copy of the DateTime with this field set to its minimum
1966: * @since 1.2
1967: */
1968: public DateTime withMinimumValue() {
1969: return setCopy(getMinimumValue());
1970: }
1971:
1972: //-----------------------------------------------------------------------
1973: /**
1974: * Rounds to the lowest whole unit of this field on a copy of this DateTime.
1975: *
1976: * @return a copy of the DateTime with the field value changed
1977: */
1978: public DateTime roundFloorCopy() {
1979: return iInstant.withMillis(iField.roundFloor(iInstant
1980: .getMillis()));
1981: }
1982:
1983: /**
1984: * Rounds to the highest whole unit of this field on a copy of this DateTime.
1985: *
1986: * @return a copy of the DateTime with the field value changed
1987: */
1988: public DateTime roundCeilingCopy() {
1989: return iInstant.withMillis(iField.roundCeiling(iInstant
1990: .getMillis()));
1991: }
1992:
1993: /**
1994: * Rounds to the nearest whole unit of this field on a copy of this DateTime,
1995: * favoring the floor if halfway.
1996: *
1997: * @return a copy of the DateTime with the field value changed
1998: */
1999: public DateTime roundHalfFloorCopy() {
2000: return iInstant.withMillis(iField.roundHalfFloor(iInstant
2001: .getMillis()));
2002: }
2003:
2004: /**
2005: * Rounds to the nearest whole unit of this field on a copy of this DateTime,
2006: * favoring the ceiling if halfway.
2007: *
2008: * @return a copy of the DateTime with the field value changed
2009: */
2010: public DateTime roundHalfCeilingCopy() {
2011: return iInstant.withMillis(iField.roundHalfCeiling(iInstant
2012: .getMillis()));
2013: }
2014:
2015: /**
2016: * Rounds to the nearest whole unit of this field on a copy of this
2017: * DateTime. If halfway, the ceiling is favored over the floor only if
2018: * it makes this field's value even.
2019: *
2020: * @return a copy of the DateTime with the field value changed
2021: */
2022: public DateTime roundHalfEvenCopy() {
2023: return iInstant.withMillis(iField.roundHalfEven(iInstant
2024: .getMillis()));
2025: }
2026: }
2027:
2028: }
|