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.field.AbstractReadableInstantFieldProperty;
0026: import org.joda.time.format.ISODateTimeFormat;
0027:
0028: /**
0029: * DateMidnight defines a date where the time component is fixed at midnight.
0030: * The class uses a time zone, thus midnight is local unless a UTC time zone is used.
0031: * <p>
0032: * It is important to emphasise that this class represents the time of midnight on
0033: * any given day.
0034: * Note that midnight is defined as 00:00, which is at the very start of a day.
0035: * <p>
0036: * This class does not represent a day, but the millisecond instant at midnight.
0037: * If you need a class that represents the whole day, then an {@link Interval} or
0038: * a {@link LocalDate} may be more suitable.
0039: * <p>
0040: * This class uses a Chronology internally. The Chronology determines how the
0041: * millisecond instant value is converted into the date time fields.
0042: * The default Chronology is <code>ISOChronology</code> which is the agreed
0043: * international standard and compatable with the modern Gregorian calendar.
0044: *
0045: * <p>Each individual field can be queried in two ways:
0046: * <ul>
0047: * <li><code>getDayOfMonth()</code>
0048: * <li><code>dayOfMonth().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: *
0062: * <p>
0063: * DateMidnight is thread-safe and immutable, provided that the Chronology is as well.
0064: * All standard Chronology classes supplied are thread-safe and immutable.
0065: *
0066: * @author Stephen Colebourne
0067: * @since 1.0
0068: */
0069: public final class DateMidnight extends BaseDateTime implements
0070: ReadableDateTime, Serializable {
0071:
0072: /** Serialization lock */
0073: private static final long serialVersionUID = 156371964018738L;
0074:
0075: // Constructors
0076: //-----------------------------------------------------------------------
0077: /**
0078: * Constructs an instance set to the current system millisecond time
0079: * using <code>ISOChronology</code> in the default time zone.
0080: * The constructed object will have a local time of midnight.
0081: */
0082: public DateMidnight() {
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: * The constructed object will have a local time of midnight.
0090: * <p>
0091: * If the specified time zone is null, the default zone is used.
0092: *
0093: * @param zone the time zone, null means default zone
0094: */
0095: public DateMidnight(DateTimeZone zone) {
0096: super (zone);
0097: }
0098:
0099: /**
0100: * Constructs an instance set to the current system millisecond time
0101: * using the specified chronology.
0102: * The constructed object will have a local time of midnight.
0103: * <p>
0104: * If the chronology is null, <code>ISOChronology</code>
0105: * in the default time zone is used.
0106: *
0107: * @param chronology the chronology, null means ISOChronology in default zone
0108: */
0109: public DateMidnight(Chronology chronology) {
0110: super (chronology);
0111: }
0112:
0113: //-----------------------------------------------------------------------
0114: /**
0115: * Constructs an instance set to the milliseconds from 1970-01-01T00:00:00Z
0116: * using <code>ISOChronology</code> in the default time zone.
0117: * The constructed object will have a local time of midnight.
0118: *
0119: * @param instant the milliseconds from 1970-01-01T00:00:00Z
0120: */
0121: public DateMidnight(long instant) {
0122: super (instant);
0123: }
0124:
0125: /**
0126: * Constructs an instance set to the milliseconds from 1970-01-01T00:00:00Z
0127: * using <code>ISOChronology</code> in the specified time zone.
0128: * The constructed object will have a local time of midnight.
0129: * <p>
0130: * If the specified time zone is null, the default zone is used.
0131: *
0132: * @param instant the milliseconds from 1970-01-01T00:00:00Z
0133: * @param zone the time zone, null means default zone
0134: */
0135: public DateMidnight(long instant, DateTimeZone zone) {
0136: super (instant, zone);
0137: }
0138:
0139: /**
0140: * Constructs an instance set to the milliseconds from 1970-01-01T00:00:00Z
0141: * using the specified chronology.
0142: * The constructed object will have a local time of midnight.
0143: * <p>
0144: * If the chronology is null, <code>ISOChronology</code>
0145: * in the default time zone is used.
0146: *
0147: * @param instant the milliseconds from 1970-01-01T00:00:00Z
0148: * @param chronology the chronology, null means ISOChronology in default zone
0149: */
0150: public DateMidnight(long instant, Chronology chronology) {
0151: super (instant, chronology);
0152: }
0153:
0154: //-----------------------------------------------------------------------
0155: /**
0156: * Constructs an instance from an Object that represents a datetime.
0157: * The constructed object will have a local time of midnight.
0158: * <p>
0159: * If the object implies a chronology (such as GregorianCalendar does),
0160: * then that chronology will be used. Otherwise, ISO default is used.
0161: * Thus if a GregorianCalendar is passed in, the chronology used will
0162: * be GJ, but if a Date is passed in the chronology will be ISO.
0163: * <p>
0164: * The recognised object types are defined in
0165: * {@link org.joda.time.convert.ConverterManager ConverterManager} and
0166: * include ReadableInstant, String, Calendar and Date.
0167: * The String formats are described by {@link ISODateTimeFormat#dateTimeParser()}.
0168: *
0169: * @param instant the datetime object, null means now
0170: * @throws IllegalArgumentException if the instant is invalid
0171: */
0172: public DateMidnight(Object instant) {
0173: super (instant, (Chronology) null);
0174: }
0175:
0176: /**
0177: * Constructs an instance from an Object that represents a datetime,
0178: * forcing the time zone to that specified.
0179: * The constructed object will have a local time of midnight.
0180: * <p>
0181: * If the object implies a chronology (such as GregorianCalendar does),
0182: * then that chronology will be used, but with the time zone adjusted.
0183: * Otherwise, ISO is used in the specified time zone.
0184: * If the specified time zone is null, the default zone is used.
0185: * Thus if a GregorianCalendar is passed in, the chronology used will
0186: * be GJ, but if a Date is passed in the chronology will be ISO.
0187: * <p>
0188: * The recognised object types are defined in
0189: * {@link org.joda.time.convert.ConverterManager ConverterManager} and
0190: * include ReadableInstant, String, Calendar and Date.
0191: * The String formats are described by {@link ISODateTimeFormat#dateTimeParser()}.
0192: *
0193: * @param instant the datetime object, null means now
0194: * @param zone the time zone, null means default time zone
0195: * @throws IllegalArgumentException if the instant is invalid
0196: */
0197: public DateMidnight(Object instant, DateTimeZone zone) {
0198: super (instant, zone);
0199: }
0200:
0201: /**
0202: * Constructs an instance from an Object that represents a datetime,
0203: * using the specified chronology.
0204: * The constructed object will have a local time of midnight.
0205: * <p>
0206: * If the chronology is null, ISO in the default time zone is used.
0207: * Any chronology implied by the object (such as GregorianCalendar does)
0208: * is ignored.
0209: * <p>
0210: * The recognised object types are defined in
0211: * {@link org.joda.time.convert.ConverterManager ConverterManager} and
0212: * include ReadableInstant, String, Calendar and Date.
0213: * The String formats are described by {@link ISODateTimeFormat#dateTimeParser()}.
0214: *
0215: * @param instant the datetime object, null means now
0216: * @param chronology the chronology, null means ISOChronology in default zone
0217: * @throws IllegalArgumentException if the instant is invalid
0218: */
0219: public DateMidnight(Object instant, Chronology chronology) {
0220: super (instant, DateTimeUtils.getChronology(chronology));
0221: }
0222:
0223: //-----------------------------------------------------------------------
0224: /**
0225: * Constructs an instance from datetime field values
0226: * using <code>ISOChronology</code> in the default time zone.
0227: * The constructed object will have a local time of midnight.
0228: *
0229: * @param year the year
0230: * @param monthOfYear the month of the year
0231: * @param dayOfMonth the day of the month
0232: */
0233: public DateMidnight(int year, int monthOfYear, int dayOfMonth) {
0234: super (year, monthOfYear, dayOfMonth, 0, 0, 0, 0);
0235: }
0236:
0237: /**
0238: * Constructs an instance from datetime field values
0239: * using <code>ISOChronology</code> in the specified time zone.
0240: * The constructed object will have a local time of midnight.
0241: * <p>
0242: * If the specified time zone is null, the default zone is used.
0243: *
0244: * @param year the year
0245: * @param monthOfYear the month of the year
0246: * @param dayOfMonth the day of the month
0247: * @param zone the time zone, null means default time zone
0248: */
0249: public DateMidnight(int year, int monthOfYear, int dayOfMonth,
0250: DateTimeZone zone) {
0251: super (year, monthOfYear, dayOfMonth, 0, 0, 0, 0, zone);
0252: }
0253:
0254: /**
0255: * Constructs an instance from datetime field values
0256: * using the specified chronology.
0257: * The constructed object will have a local time of midnight.
0258: * <p>
0259: * If the chronology is null, <code>ISOChronology</code>
0260: * in the default time zone is used.
0261: *
0262: * @param year the year
0263: * @param monthOfYear the month of the year
0264: * @param dayOfMonth the day of the month
0265: * @param chronology the chronology, null means ISOChronology in default zone
0266: */
0267: public DateMidnight(int year, int monthOfYear, int dayOfMonth,
0268: Chronology chronology) {
0269: super (year, monthOfYear, dayOfMonth, 0, 0, 0, 0, chronology);
0270: }
0271:
0272: /**
0273: * Rounds the specified instant to midnight.
0274: *
0275: * @param instant the milliseconds from 1970-01-01T00:00:00Z to round
0276: * @param chronology the chronology to use, not null
0277: * @return the updated instant, rounded to midnight
0278: */
0279: protected long checkInstant(long instant, Chronology chronology) {
0280: return chronology.dayOfMonth().roundFloor(instant);
0281: }
0282:
0283: //-----------------------------------------------------------------------
0284: /**
0285: * Returns a copy of this date with a different millisecond instant.
0286: * The returned object will have a local time of midnight.
0287: * <p>
0288: * Only the millis will change, the chronology and time zone are kept.
0289: * The returned object will be either be a new instance or <code>this</code>.
0290: *
0291: * @param newMillis the new millis, from 1970-01-01T00:00:00Z
0292: * @return a copy of this instant with different millis
0293: */
0294: public DateMidnight withMillis(long newMillis) {
0295: Chronology chrono = getChronology();
0296: newMillis = checkInstant(newMillis, chrono);
0297: return (newMillis == getMillis() ? this : new DateMidnight(
0298: newMillis, chrono));
0299: }
0300:
0301: /**
0302: * Returns a copy of this date with a different chronology, potentially
0303: * changing the day in unexpected ways.
0304: * <p>
0305: * This method creates a new DateMidnight using the midnight millisecond value
0306: * and the new chronology. If the same or similar chronology is specified, but
0307: * with a different time zone, the day may change. This occurs because the new
0308: * DateMidnight rounds down the millisecond value to get to midnight, and the
0309: * time zone change may result in a rounding down to a different day.
0310: * <p>
0311: * For example, changing time zone from London (+00:00) to Paris (+01:00) will
0312: * retain the same day, but changing from Paris to London will change the day.
0313: * (When its midnight in London its the same day in Paris, but when its midnight
0314: * in Paris its still the previous day in London)
0315: * <p>
0316: * To avoid these unusual effects, use {@link #withZoneRetainFields(DateTimeZone)}
0317: * to change time zones.
0318: *
0319: * @param newChronology the new chronology
0320: * @return a copy of this instant with a different chronology
0321: */
0322: public DateMidnight withChronology(Chronology newChronology) {
0323: return (newChronology == getChronology() ? this
0324: : new DateMidnight(getMillis(), newChronology));
0325: }
0326:
0327: /**
0328: * Returns a copy of this date with a different time zone, preserving the day
0329: * The returned object will have a local time of midnight in the new zone on
0330: * the same day as the original instant.
0331: *
0332: * @param newZone the new time zone, null means default
0333: * @return a copy of this instant with a different time zone
0334: */
0335: public DateMidnight withZoneRetainFields(DateTimeZone newZone) {
0336: newZone = DateTimeUtils.getZone(newZone);
0337: DateTimeZone originalZone = DateTimeUtils.getZone(getZone());
0338: if (newZone == originalZone) {
0339: return this ;
0340: }
0341:
0342: long millis = originalZone.getMillisKeepLocal(newZone,
0343: getMillis());
0344: return new DateMidnight(millis, getChronology().withZone(
0345: newZone));
0346: }
0347:
0348: //-----------------------------------------------------------------------
0349: /**
0350: * Returns a copy of this date with the partial set of fields replacing those
0351: * from this instance.
0352: * <p>
0353: * For example, if the partial is a <code>LocalDate</code> then the date fields
0354: * would be changed in the returned instance.
0355: * If the partial is null, then <code>this</code> is returned.
0356: *
0357: * @param partial the partial set of fields to apply to this datetime, null ignored
0358: * @return a copy of this datetime with a different set of fields
0359: * @throws IllegalArgumentException if any value is invalid
0360: */
0361: public DateMidnight withFields(ReadablePartial partial) {
0362: if (partial == null) {
0363: return this ;
0364: }
0365: return withMillis(getChronology().set(partial, getMillis()));
0366: }
0367:
0368: /**
0369: * Returns a copy of this date with the specified field set to a new value.
0370: * <p>
0371: * For example, if the field type is <code>dayOfMonth</code> then the day of month
0372: * field would be changed in the returned instance.
0373: * If the field type is null, then <code>this</code> is returned.
0374: * <p>
0375: * These three lines are equivalent:
0376: * <pre>
0377: * DateTime updated = dt.withField(DateTimeFieldType.dayOfMonth(), 6);
0378: * DateTime updated = dt.dayOfMonth().setCopy(6);
0379: * DateTime updated = dt.property(DateTimeFieldType.dayOfMonth()).setCopy(6);
0380: * </pre>
0381: *
0382: * @param fieldType the field type to set, not null
0383: * @param value the value to set
0384: * @return a copy of this datetime with the field set
0385: * @throws IllegalArgumentException if the value is null or invalid
0386: */
0387: public DateMidnight withField(DateTimeFieldType fieldType, int value) {
0388: if (fieldType == null) {
0389: throw new IllegalArgumentException("Field must not be null");
0390: }
0391: long instant = fieldType.getField(getChronology()).set(
0392: getMillis(), value);
0393: return withMillis(instant);
0394: }
0395:
0396: /**
0397: * Returns a copy of this date with the value of the specified field increased.
0398: * <p>
0399: * If the addition is zero or the field is null, then <code>this</code> is returned.
0400: * <p>
0401: * These three lines are equivalent:
0402: * <pre>
0403: * DateMidnight added = dt.withFieldAdded(DateTimeFieldType.year(), 6);
0404: * DateMidnight added = dt.plusYears(6);
0405: * DateMidnight added = dt.year().addToCopy(6);
0406: * </pre>
0407: *
0408: * @param fieldType the field type to add to, not null
0409: * @param amount the amount to add
0410: * @return a copy of this datetime with the field updated
0411: * @throws IllegalArgumentException if the value is null or invalid
0412: * @throws ArithmeticException if the new datetime exceeds the capacity of a long
0413: */
0414: public DateMidnight withFieldAdded(DurationFieldType fieldType,
0415: int amount) {
0416: if (fieldType == null) {
0417: throw new IllegalArgumentException("Field must not be null");
0418: }
0419: if (amount == 0) {
0420: return this ;
0421: }
0422: long instant = fieldType.getField(getChronology()).add(
0423: getMillis(), amount);
0424: return withMillis(instant);
0425: }
0426:
0427: //-----------------------------------------------------------------------
0428: /**
0429: * Returns a copy of this date with the specified duration added.
0430: * <p>
0431: * If the addition is zero, then <code>this</code> is returned.
0432: *
0433: * @param durationToAdd the duration to add to this one
0434: * @param scalar the amount of times to add, such as -1 to subtract once
0435: * @return a copy of this datetime with the duration added
0436: * @throws ArithmeticException if the new datetime exceeds the capacity of a long
0437: */
0438: public DateMidnight withDurationAdded(long durationToAdd, int scalar) {
0439: if (durationToAdd == 0 || scalar == 0) {
0440: return this ;
0441: }
0442: long instant = getChronology().add(getMillis(), durationToAdd,
0443: scalar);
0444: return withMillis(instant);
0445: }
0446:
0447: /**
0448: * Returns a copy of this date with the specified duration added.
0449: * <p>
0450: * If the addition is zero, then <code>this</code> is returned.
0451: *
0452: * @param durationToAdd the duration to add to this one, null means zero
0453: * @param scalar the amount of times to add, such as -1 to subtract once
0454: * @return a copy of this datetime with the duration added
0455: * @throws ArithmeticException if the new datetime exceeds the capacity of a long
0456: */
0457: public DateMidnight withDurationAdded(
0458: ReadableDuration durationToAdd, int scalar) {
0459: if (durationToAdd == null || scalar == 0) {
0460: return this ;
0461: }
0462: return withDurationAdded(durationToAdd.getMillis(), scalar);
0463: }
0464:
0465: /**
0466: * Returns a copy of this date with the specified period added.
0467: * <p>
0468: * If the addition is zero, then <code>this</code> is returned.
0469: * <p>
0470: * This method is typically used to add multiple copies of complex
0471: * period instances. Adding one field is best achieved using methods
0472: * like {@link #withFieldAdded(DurationFieldType, int)}
0473: * or {@link #plusYears(int)}.
0474: *
0475: * @param period the period to add to this one, null means zero
0476: * @param scalar the amount of times to add, such as -1 to subtract once
0477: * @return a copy of this datetime with the period added
0478: * @throws ArithmeticException if the new datetime exceeds the capacity of a long
0479: */
0480: public DateMidnight withPeriodAdded(ReadablePeriod period,
0481: int scalar) {
0482: if (period == null || scalar == 0) {
0483: return this ;
0484: }
0485: long instant = getChronology().add(period, getMillis(), scalar);
0486: return withMillis(instant);
0487: }
0488:
0489: //-----------------------------------------------------------------------
0490: /**
0491: * Returns a copy of this date with the specified duration added.
0492: * <p>
0493: * If the amount is zero, then <code>this</code> is returned.
0494: *
0495: * @param duration the duration, in millis, to add to this one
0496: * @return a copy of this datetime with the duration added
0497: * @throws ArithmeticException if the new datetime exceeds the capacity of a long
0498: */
0499: public DateMidnight plus(long duration) {
0500: return withDurationAdded(duration, 1);
0501: }
0502:
0503: /**
0504: * Returns a copy of this date with the specified duration added.
0505: * <p>
0506: * If the amount is zero or null, then <code>this</code> is returned.
0507: *
0508: * @param duration the duration to add to this one, null means zero
0509: * @return a copy of this datetime with the duration added
0510: * @throws ArithmeticException if the new datetime exceeds the capacity of a long
0511: */
0512: public DateMidnight plus(ReadableDuration duration) {
0513: return withDurationAdded(duration, 1);
0514: }
0515:
0516: /**
0517: * Returns a copy of this date with the specified period added.
0518: * <p>
0519: * If the amount is zero or null, then <code>this</code> is returned.
0520: * <p>
0521: * This method is typically used to add complex period instances.
0522: * Adding one field is best achieved using methods
0523: * like {@link #plusYears(int)}.
0524: *
0525: * @param period the duration to add to this one, null means zero
0526: * @return a copy of this datetime with the period added
0527: * @throws ArithmeticException if the new datetime exceeds the capacity of a long
0528: */
0529: public DateMidnight plus(ReadablePeriod period) {
0530: return withPeriodAdded(period, 1);
0531: }
0532:
0533: //-----------------------------------------------------------------------
0534: /**
0535: * Returns a copy of this date plus the specified number of years.
0536: * <p>
0537: * This datetime instance is immutable and unaffected by this method call.
0538: * <p>
0539: * The following three lines are identical in effect:
0540: * <pre>
0541: * DateMidnight added = dt.plusYears(6);
0542: * DateMidnight added = dt.plus(Period.years(6));
0543: * DateMidnight added = dt.withFieldAdded(DurationFieldType.years(), 6);
0544: * </pre>
0545: *
0546: * @param years the amount of years to add, may be negative
0547: * @return the new datetime plus the increased years
0548: * @since 1.1
0549: */
0550: public DateMidnight plusYears(int years) {
0551: if (years == 0) {
0552: return this ;
0553: }
0554: long instant = getChronology().years().add(getMillis(), years);
0555: return withMillis(instant);
0556: }
0557:
0558: /**
0559: * Returns a copy of this date plus the specified number of months.
0560: * <p>
0561: * This datetime instance is immutable and unaffected by this method call.
0562: * <p>
0563: * The following three lines are identical in effect:
0564: * <pre>
0565: * DateMidnight added = dt.plusMonths(6);
0566: * DateMidnight added = dt.plus(Period.months(6));
0567: * DateMidnight added = dt.withFieldAdded(DurationFieldType.months(), 6);
0568: * </pre>
0569: *
0570: * @param months the amount of months to add, may be negative
0571: * @return the new datetime plus the increased months
0572: * @since 1.1
0573: */
0574: public DateMidnight plusMonths(int months) {
0575: if (months == 0) {
0576: return this ;
0577: }
0578: long instant = getChronology().months()
0579: .add(getMillis(), months);
0580: return withMillis(instant);
0581: }
0582:
0583: /**
0584: * Returns a copy of this date plus the specified number of weeks.
0585: * <p>
0586: * This datetime instance is immutable and unaffected by this method call.
0587: * <p>
0588: * The following three lines are identical in effect:
0589: * <pre>
0590: * DateMidnight added = dt.plusWeeks(6);
0591: * DateMidnight added = dt.plus(Period.weeks(6));
0592: * DateMidnight added = dt.withFieldAdded(DurationFieldType.weeks(), 6);
0593: * </pre>
0594: *
0595: * @param weeks the amount of weeks to add, may be negative
0596: * @return the new datetime plus the increased weeks
0597: * @since 1.1
0598: */
0599: public DateMidnight plusWeeks(int weeks) {
0600: if (weeks == 0) {
0601: return this ;
0602: }
0603: long instant = getChronology().weeks().add(getMillis(), weeks);
0604: return withMillis(instant);
0605: }
0606:
0607: /**
0608: * Returns a copy of this date plus the specified number of days.
0609: * <p>
0610: * This datetime instance is immutable and unaffected by this method call.
0611: * <p>
0612: * The following three lines are identical in effect:
0613: * <pre>
0614: * DateMidnight added = dt.plusDays(6);
0615: * DateMidnight added = dt.plus(Period.days(6));
0616: * DateMidnight added = dt.withFieldAdded(DurationFieldType.days(), 6);
0617: * </pre>
0618: *
0619: * @param days the amount of days to add, may be negative
0620: * @return the new datetime plus the increased days
0621: * @since 1.1
0622: */
0623: public DateMidnight plusDays(int days) {
0624: if (days == 0) {
0625: return this ;
0626: }
0627: long instant = getChronology().days().add(getMillis(), days);
0628: return withMillis(instant);
0629: }
0630:
0631: //-----------------------------------------------------------------------
0632: /**
0633: * Returns a copy of this date with the specified duration taken away.
0634: * <p>
0635: * If the amount is zero or null, then <code>this</code> is returned.
0636: *
0637: * @param duration the duration, in millis, to reduce this instant by
0638: * @return a copy of this datetime with the duration taken away
0639: * @throws ArithmeticException if the new datetime exceeds the capacity of a long
0640: */
0641: public DateMidnight minus(long duration) {
0642: return withDurationAdded(duration, -1);
0643: }
0644:
0645: /**
0646: * Returns a copy of this date with the specified duration taken away.
0647: * <p>
0648: * If the amount is zero or null, then <code>this</code> is returned.
0649: *
0650: * @param duration the duration to reduce this instant by
0651: * @return a copy of this datetime with the duration taken away
0652: * @throws ArithmeticException if the new datetime exceeds the capacity of a long
0653: */
0654: public DateMidnight minus(ReadableDuration duration) {
0655: return withDurationAdded(duration, -1);
0656: }
0657:
0658: /**
0659: * Returns a copy of this date with the specified period taken away.
0660: * <p>
0661: * If the amount is zero or null, then <code>this</code> is returned.
0662: * <p>
0663: * This method is typically used to subtract complex period instances.
0664: * Subtracting one field is best achieved using methods
0665: * like {@link #minusYears(int)}.
0666: *
0667: * @param period the period to reduce this instant by
0668: * @return a copy of this datetime with the period taken away
0669: * @throws ArithmeticException if the new datetime exceeds the capacity of a long
0670: */
0671: public DateMidnight minus(ReadablePeriod period) {
0672: return withPeriodAdded(period, -1);
0673: }
0674:
0675: //-----------------------------------------------------------------------
0676: /**
0677: * Returns a copy of this date minus the specified number of years.
0678: * <p>
0679: * This datetime instance is immutable and unaffected by this method call.
0680: * <p>
0681: * The following three lines are identical in effect:
0682: * <pre>
0683: * DateTime subtracted = dt.minusYears(6);
0684: * DateTime subtracted = dt.minus(Period.years(6));
0685: * DateTime subtracted = dt.withFieldAdded(DurationFieldType.years(), -6);
0686: * </pre>
0687: *
0688: * @param years the amount of years to subtract, may be negative
0689: * @return the new datetime minus the increased years
0690: * @since 1.1
0691: */
0692: public DateMidnight minusYears(int years) {
0693: if (years == 0) {
0694: return this ;
0695: }
0696: long instant = getChronology().years().subtract(getMillis(),
0697: years);
0698: return withMillis(instant);
0699: }
0700:
0701: /**
0702: * Returns a copy of this date minus the specified number of months.
0703: * <p>
0704: * This datetime instance is immutable and unaffected by this method call.
0705: * <p>
0706: * The following three lines are identical in effect:
0707: * <pre>
0708: * DateMidnight subtracted = dt.minusMonths(6);
0709: * DateMidnight subtracted = dt.minus(Period.months(6));
0710: * DateMidnight subtracted = dt.withFieldAdded(DurationFieldType.months(), -6);
0711: * </pre>
0712: *
0713: * @param months the amount of months to subtract, may be negative
0714: * @return the new datetime minus the increased months
0715: * @since 1.1
0716: */
0717: public DateMidnight minusMonths(int months) {
0718: if (months == 0) {
0719: return this ;
0720: }
0721: long instant = getChronology().months().subtract(getMillis(),
0722: months);
0723: return withMillis(instant);
0724: }
0725:
0726: /**
0727: * Returns a copy of this date minus the specified number of weeks.
0728: * <p>
0729: * This datetime instance is immutable and unaffected by this method call.
0730: * <p>
0731: * The following three lines are identical in effect:
0732: * <pre>
0733: * DateMidnight subtracted = dt.minusWeeks(6);
0734: * DateMidnight subtracted = dt.minus(Period.weeks(6));
0735: * DateMidnight subtracted = dt.withFieldAdded(DurationFieldType.weeks(), -6);
0736: * </pre>
0737: *
0738: * @param weeks the amount of weeks to subtract, may be negative
0739: * @return the new datetime minus the increased weeks
0740: * @since 1.1
0741: */
0742: public DateMidnight minusWeeks(int weeks) {
0743: if (weeks == 0) {
0744: return this ;
0745: }
0746: long instant = getChronology().weeks().subtract(getMillis(),
0747: weeks);
0748: return withMillis(instant);
0749: }
0750:
0751: /**
0752: * Returns a copy of this date minus the specified number of days.
0753: * <p>
0754: * This datetime instance is immutable and unaffected by this method call.
0755: * <p>
0756: * The following three lines are identical in effect:
0757: * <pre>
0758: * DateMidnight subtracted = dt.minusDays(6);
0759: * DateMidnight subtracted = dt.minus(Period.days(6));
0760: * DateMidnight subtracted = dt.withFieldAdded(DurationFieldType.days(), -6);
0761: * </pre>
0762: *
0763: * @param days the amount of days to subtract, may be negative
0764: * @return the new datetime minus the increased days
0765: * @since 1.1
0766: */
0767: public DateMidnight minusDays(int days) {
0768: if (days == 0) {
0769: return this ;
0770: }
0771: long instant = getChronology().days().subtract(getMillis(),
0772: days);
0773: return withMillis(instant);
0774: }
0775:
0776: //-----------------------------------------------------------------------
0777: /**
0778: * Gets the property object for the specified type, which contains many useful methods.
0779: *
0780: * @param type the field type to get the chronology for
0781: * @return the property object
0782: * @throws IllegalArgumentException if the field is null or unsupported
0783: */
0784: public Property property(DateTimeFieldType type) {
0785: if (type == null) {
0786: throw new IllegalArgumentException(
0787: "The DateTimeFieldType must not be null");
0788: }
0789: DateTimeField field = type.getField(getChronology());
0790: if (field.isSupported() == false) {
0791: throw new IllegalArgumentException("Field '" + type
0792: + "' is not supported");
0793: }
0794: return new Property(this , field);
0795: }
0796:
0797: //-----------------------------------------------------------------------
0798: /**
0799: * Converts this object to a <code>YearMonthDay</code> using the
0800: * same date and chronology.
0801: *
0802: * @return a YearMonthDay using the same millis and chronology
0803: * @deprecated Use LocalDate instead of YearMonthDay
0804: */
0805: public YearMonthDay toYearMonthDay() {
0806: return new YearMonthDay(getMillis(), getChronology());
0807: }
0808:
0809: /**
0810: * Converts this object to a <code>LocalDate</code> with the
0811: * same date and chronology.
0812: *
0813: * @return a LocalDate with the same date and chronology
0814: * @since 1.3
0815: */
0816: public LocalDate toLocalDate() {
0817: return new LocalDate(getMillis(), getChronology());
0818: }
0819:
0820: /**
0821: * Converts this object to an <code>Interval</code> encompassing
0822: * the whole of this day.
0823: * <p>
0824: * The interval starts at midnight 00:00 and ends at 00:00 the following day,
0825: * (which is not included in the interval, as intervals are half-open).
0826: *
0827: * @return an interval over the day
0828: */
0829: public Interval toInterval() {
0830: Chronology chrono = getChronology();
0831: long start = getMillis();
0832: long end = DurationFieldType.days().getField(chrono).add(start,
0833: 1);
0834: return new Interval(start, end, chrono);
0835: }
0836:
0837: //-----------------------------------------------------------------------
0838: /**
0839: * Returns a copy of this date with the era field updated.
0840: * <p>
0841: * DateMidnight is immutable, so there are no set methods.
0842: * Instead, this method returns a new instance with the value of
0843: * era changed.
0844: *
0845: * @param era the era to set
0846: * @return a copy of this object with the field set
0847: * @throws IllegalArgumentException if the value is invalid
0848: * @since 1.3
0849: */
0850: public DateMidnight withEra(int era) {
0851: return withMillis(getChronology().era().set(getMillis(), era));
0852: }
0853:
0854: /**
0855: * Returns a copy of this date with the century of era field updated.
0856: * <p>
0857: * DateMidnight is immutable, so there are no set methods.
0858: * Instead, this method returns a new instance with the value of
0859: * century of era changed.
0860: *
0861: * @param centuryOfEra the centurey of era to set
0862: * @return a copy of this object with the field set
0863: * @throws IllegalArgumentException if the value is invalid
0864: * @since 1.3
0865: */
0866: public DateMidnight withCenturyOfEra(int centuryOfEra) {
0867: return withMillis(getChronology().centuryOfEra().set(
0868: getMillis(), centuryOfEra));
0869: }
0870:
0871: /**
0872: * Returns a copy of this date with the year of era field updated.
0873: * <p>
0874: * DateMidnight is immutable, so there are no set methods.
0875: * Instead, this method returns a new instance with the value of
0876: * year of era changed.
0877: *
0878: * @param yearOfEra the year of era to set
0879: * @return a copy of this object with the field set
0880: * @throws IllegalArgumentException if the value is invalid
0881: * @since 1.3
0882: */
0883: public DateMidnight withYearOfEra(int yearOfEra) {
0884: return withMillis(getChronology().yearOfEra().set(getMillis(),
0885: yearOfEra));
0886: }
0887:
0888: /**
0889: * Returns a copy of this date with the year of century field updated.
0890: * <p>
0891: * DateMidnight is immutable, so there are no set methods.
0892: * Instead, this method returns a new instance with the value of
0893: * year of century changed.
0894: *
0895: * @param yearOfCentury the year of century to set
0896: * @return a copy of this object with the field set
0897: * @throws IllegalArgumentException if the value is invalid
0898: * @since 1.3
0899: */
0900: public DateMidnight withYearOfCentury(int yearOfCentury) {
0901: return withMillis(getChronology().yearOfCentury().set(
0902: getMillis(), yearOfCentury));
0903: }
0904:
0905: /**
0906: * Returns a copy of this date with the year field updated.
0907: * <p>
0908: * DateMidnight is immutable, so there are no set methods.
0909: * Instead, this method returns a new instance with the value of
0910: * year changed.
0911: *
0912: * @param year the year to set
0913: * @return a copy of this object with the field set
0914: * @throws IllegalArgumentException if the value is invalid
0915: * @since 1.3
0916: */
0917: public DateMidnight withYear(int year) {
0918: return withMillis(getChronology().year().set(getMillis(), year));
0919: }
0920:
0921: /**
0922: * Returns a copy of this date with the weekyear field updated.
0923: * <p>
0924: * DateMidnight is immutable, so there are no set methods.
0925: * Instead, this method returns a new instance with the value of
0926: * weekyear changed.
0927: *
0928: * @param weekyear the weekyear to set
0929: * @return a copy of this object with the field set
0930: * @throws IllegalArgumentException if the value is invalid
0931: * @since 1.3
0932: */
0933: public DateMidnight withWeekyear(int weekyear) {
0934: return withMillis(getChronology().weekyear().set(getMillis(),
0935: weekyear));
0936: }
0937:
0938: /**
0939: * Returns a copy of this date with the month of year field updated.
0940: * <p>
0941: * DateMidnight is immutable, so there are no set methods.
0942: * Instead, this method returns a new instance with the value of
0943: * month of year changed.
0944: *
0945: * @param monthOfYear the month of year to set
0946: * @return a copy of this object with the field set
0947: * @throws IllegalArgumentException if the value is invalid
0948: * @since 1.3
0949: */
0950: public DateMidnight withMonthOfYear(int monthOfYear) {
0951: return withMillis(getChronology().monthOfYear().set(
0952: getMillis(), monthOfYear));
0953: }
0954:
0955: /**
0956: * Returns a copy of this date with the week of weekyear field updated.
0957: * <p>
0958: * DateMidnight is immutable, so there are no set methods.
0959: * Instead, this method returns a new instance with the value of
0960: * week of weekyear changed.
0961: *
0962: * @param weekOfWeekyear the week of weekyear to set
0963: * @return a copy of this object with the field set
0964: * @throws IllegalArgumentException if the value is invalid
0965: * @since 1.3
0966: */
0967: public DateMidnight withWeekOfWeekyear(int weekOfWeekyear) {
0968: return withMillis(getChronology().weekOfWeekyear().set(
0969: getMillis(), weekOfWeekyear));
0970: }
0971:
0972: /**
0973: * Returns a copy of this date with the day of year field updated.
0974: * <p>
0975: * DateMidnight is immutable, so there are no set methods.
0976: * Instead, this method returns a new instance with the value of
0977: * day of year changed.
0978: *
0979: * @param dayOfYear the day of year to set
0980: * @return a copy of this object with the field set
0981: * @throws IllegalArgumentException if the value is invalid
0982: * @since 1.3
0983: */
0984: public DateMidnight withDayOfYear(int dayOfYear) {
0985: return withMillis(getChronology().dayOfYear().set(getMillis(),
0986: dayOfYear));
0987: }
0988:
0989: /**
0990: * Returns a copy of this date with the day of month field updated.
0991: * <p>
0992: * DateMidnight is immutable, so there are no set methods.
0993: * Instead, this method returns a new instance with the value of
0994: * day of month changed.
0995: *
0996: * @param dayOfMonth the day of month to set
0997: * @return a copy of this object with the field set
0998: * @throws IllegalArgumentException if the value is invalid
0999: * @since 1.3
1000: */
1001: public DateMidnight withDayOfMonth(int dayOfMonth) {
1002: return withMillis(getChronology().dayOfMonth().set(getMillis(),
1003: dayOfMonth));
1004: }
1005:
1006: /**
1007: * Returns a copy of this date with the day of week field updated.
1008: * <p>
1009: * DateMidnight is immutable, so there are no set methods.
1010: * Instead, this method returns a new instance with the value of
1011: * day of week changed.
1012: *
1013: * @param dayOfWeek the day of week to set
1014: * @return a copy of this object with the field set
1015: * @throws IllegalArgumentException if the value is invalid
1016: * @since 1.3
1017: */
1018: public DateMidnight withDayOfWeek(int dayOfWeek) {
1019: return withMillis(getChronology().dayOfWeek().set(getMillis(),
1020: dayOfWeek));
1021: }
1022:
1023: // Date properties
1024: //-----------------------------------------------------------------------
1025: /**
1026: * Get the era property which provides access to advanced functionality.
1027: *
1028: * @return the era property
1029: */
1030: public Property era() {
1031: return new Property(this , getChronology().era());
1032: }
1033:
1034: /**
1035: * Get the century of era property which provides access to advanced functionality.
1036: *
1037: * @return the year of era property
1038: */
1039: public Property centuryOfEra() {
1040: return new Property(this , getChronology().centuryOfEra());
1041: }
1042:
1043: /**
1044: * Get the year of century property which provides access to advanced functionality.
1045: *
1046: * @return the year of era property
1047: */
1048: public Property yearOfCentury() {
1049: return new Property(this , getChronology().yearOfCentury());
1050: }
1051:
1052: /**
1053: * Get the year of era property which provides access to advanced functionality.
1054: *
1055: * @return the year of era property
1056: */
1057: public Property yearOfEra() {
1058: return new Property(this , getChronology().yearOfEra());
1059: }
1060:
1061: /**
1062: * Get the year property which provides access to advanced functionality.
1063: *
1064: * @return the year property
1065: */
1066: public Property year() {
1067: return new Property(this , getChronology().year());
1068: }
1069:
1070: /**
1071: * Get the year of a week based year property which provides access to advanced functionality.
1072: *
1073: * @return the year of a week based year property
1074: */
1075: public Property weekyear() {
1076: return new Property(this , getChronology().weekyear());
1077: }
1078:
1079: /**
1080: * Get the month of year property which provides access to advanced functionality.
1081: *
1082: * @return the month of year property
1083: */
1084: public Property monthOfYear() {
1085: return new Property(this , getChronology().monthOfYear());
1086: }
1087:
1088: /**
1089: * Get the week of a week based year property which provides access to advanced functionality.
1090: *
1091: * @return the week of a week based year property
1092: */
1093: public Property weekOfWeekyear() {
1094: return new Property(this , getChronology().weekOfWeekyear());
1095: }
1096:
1097: /**
1098: * Get the day of year property which provides access to advanced functionality.
1099: *
1100: * @return the day of year property
1101: */
1102: public Property dayOfYear() {
1103: return new Property(this , getChronology().dayOfYear());
1104: }
1105:
1106: /**
1107: * Get the day of month property which provides access to advanced functionality.
1108: *
1109: * @return the day of month property
1110: */
1111: public Property dayOfMonth() {
1112: return new Property(this , getChronology().dayOfMonth());
1113: }
1114:
1115: /**
1116: * Get the day of week property which provides access to advanced functionality.
1117: *
1118: * @return the day of week property
1119: */
1120: public Property dayOfWeek() {
1121: return new Property(this , getChronology().dayOfWeek());
1122: }
1123:
1124: //-----------------------------------------------------------------------
1125: /**
1126: * DateMidnight.Property binds a DateMidnight to a DateTimeField allowing powerful
1127: * datetime functionality to be easily accessed.
1128: * <p>
1129: * The simplest use of this class is as an alternative get method, here used to
1130: * get the year '1972' (as an int) and the month 'December' (as a String).
1131: * <pre>
1132: * DateMidnight dt = new DateMidnight(1972, 12, 3);
1133: * int year = dt.year().get();
1134: * String monthStr = dt.monthOfYear().getAsText();
1135: * </pre>
1136: * <p>
1137: * Methods are also provided that allow date modification. These return new instances
1138: * of DateMidnight - they do not modify the original. The example below yields two
1139: * independent immutable date objects 20 years apart.
1140: * <pre>
1141: * DateMidnight dt = new DateMidnight(1972, 12, 3);
1142: * DateMidnight dt20 = dt.year().addToCopy(20);
1143: * </pre>
1144: * Serious modification of dates (ie. more than just changing one or two fields)
1145: * should use the {@link org.joda.time.MutableDateTime MutableDateTime} class.
1146: * <p>
1147: * DateMidnight.Property itself is thread-safe and immutable.
1148: *
1149: * @author Stephen Colebourne
1150: * @author Brian S O'Neill
1151: * @since 1.0
1152: */
1153: public static final class Property extends
1154: AbstractReadableInstantFieldProperty {
1155:
1156: /** Serialization lock */
1157: private static final long serialVersionUID = 257629620L;
1158:
1159: /** The instant this property is working against */
1160: private DateMidnight iInstant;
1161: /** The field this property is working against */
1162: private DateTimeField iField;
1163:
1164: /**
1165: * Constructor.
1166: *
1167: * @param instant the instant to set
1168: * @param field the field to use
1169: */
1170: Property(DateMidnight instant, DateTimeField field) {
1171: super ();
1172: iInstant = instant;
1173: iField = field;
1174: }
1175:
1176: /**
1177: * Writes the property in a safe serialization format.
1178: */
1179: private void writeObject(ObjectOutputStream oos)
1180: throws IOException {
1181: oos.writeObject(iInstant);
1182: oos.writeObject(iField.getType());
1183: }
1184:
1185: /**
1186: * Reads the property from a safe serialization format.
1187: */
1188: private void readObject(ObjectInputStream oos)
1189: throws IOException, ClassNotFoundException {
1190: iInstant = (DateMidnight) oos.readObject();
1191: DateTimeFieldType type = (DateTimeFieldType) oos
1192: .readObject();
1193: iField = type.getField(iInstant.getChronology());
1194: }
1195:
1196: //-----------------------------------------------------------------------
1197: /**
1198: * Gets the field being used.
1199: *
1200: * @return the field
1201: */
1202: public DateTimeField getField() {
1203: return iField;
1204: }
1205:
1206: /**
1207: * Gets the milliseconds of the datetime that this property is linked to.
1208: *
1209: * @return the milliseconds
1210: */
1211: protected long getMillis() {
1212: return iInstant.getMillis();
1213: }
1214:
1215: /**
1216: * Gets the chronology of the datetime that this property is linked to.
1217: *
1218: * @return the chronology
1219: * @since 1.4
1220: */
1221: protected Chronology getChronology() {
1222: return iInstant.getChronology();
1223: }
1224:
1225: /**
1226: * Gets the datetime being used.
1227: *
1228: * @return the datetime
1229: */
1230: public DateMidnight getDateMidnight() {
1231: return iInstant;
1232: }
1233:
1234: //-----------------------------------------------------------------------
1235: /**
1236: * Adds to this field in a copy of this DateMidnight.
1237: * <p>
1238: * The DateMidnight attached to this property is unchanged by this call.
1239: * This operation is faster than converting a DateMidnight to a MutableDateTime
1240: * and back again when setting one field. When setting multiple fields,
1241: * it is generally quicker to make the conversion to MutableDateTime.
1242: *
1243: * @param value the value to add to the field in the copy
1244: * @return a copy of the DateMidnight with the field value changed
1245: * @throws IllegalArgumentException if the value isn't valid
1246: */
1247: public DateMidnight addToCopy(int value) {
1248: return iInstant.withMillis(iField.add(iInstant.getMillis(),
1249: value));
1250: }
1251:
1252: /**
1253: * Adds to this field in a copy of this DateMidnight.
1254: * <p>
1255: * The DateMidnight attached to this property is unchanged by this call.
1256: * This operation is faster than converting a DateMidnight to a MutableDateTime
1257: * and back again when setting one field. When setting multiple fields,
1258: * it is generally quicker to make the conversion to MutableDateTime.
1259: *
1260: * @param value the value to add to the field in the copy
1261: * @return a copy of the DateMidnight with the field value changed
1262: * @throws IllegalArgumentException if the value isn't valid
1263: */
1264: public DateMidnight addToCopy(long value) {
1265: return iInstant.withMillis(iField.add(iInstant.getMillis(),
1266: value));
1267: }
1268:
1269: /**
1270: * Adds to this field, possibly wrapped, in a copy of this DateMidnight.
1271: * A wrapped operation only changes this field.
1272: * Thus 31st January addWrapField one day goes to the 1st January.
1273: * <p>
1274: * The DateMidnight attached to this property is unchanged by this call.
1275: * This operation is faster than converting a DateMidnight to a MutableDateTime
1276: * and back again when setting one field. When setting multiple fields,
1277: * it is generally quicker to make the conversion to MutableDateTime.
1278: *
1279: * @param value the value to add to the field in the copy
1280: * @return a copy of the DateMidnight with the field value changed
1281: * @throws IllegalArgumentException if the value isn't valid
1282: */
1283: public DateMidnight addWrapFieldToCopy(int value) {
1284: return iInstant.withMillis(iField.addWrapField(iInstant
1285: .getMillis(), value));
1286: }
1287:
1288: //-----------------------------------------------------------------------
1289: /**
1290: * Sets this field in a copy of the DateMidnight.
1291: * <p>
1292: * The DateMidnight attached to this property is unchanged by this call.
1293: * This operation is faster than converting a DateMidnight to a MutableDateTime
1294: * and back again when setting one field. When setting multiple fields,
1295: * it is generally quicker to make the conversion to MutableDateTime.
1296: *
1297: * @param value the value to set the field in the copy to
1298: * @return a copy of the DateMidnight with the field value changed
1299: * @throws IllegalArgumentException if the value isn't valid
1300: */
1301: public DateMidnight setCopy(int value) {
1302: return iInstant.withMillis(iField.set(iInstant.getMillis(),
1303: value));
1304: }
1305:
1306: /**
1307: * Sets this field in a copy of the DateMidnight to a parsed text value.
1308: * <p>
1309: * The DateMidnight attached to this property is unchanged by this call.
1310: * This operation is faster than converting a DateMidnight to a MutableDateTime
1311: * and back again when setting one field. When setting multiple fields,
1312: * it is generally quicker to make the conversion to MutableDateTime.
1313: *
1314: * @param text the text value to set
1315: * @param locale optional locale to use for selecting a text symbol
1316: * @return a copy of the DateMidnight with the field value changed
1317: * @throws IllegalArgumentException if the text value isn't valid
1318: */
1319: public DateMidnight setCopy(String text, Locale locale) {
1320: return iInstant.withMillis(iField.set(iInstant.getMillis(),
1321: text, locale));
1322: }
1323:
1324: /**
1325: * Sets this field in a copy of the DateMidnight to a parsed text value.
1326: * <p>
1327: * The DateMidnight attached to this property is unchanged by this call.
1328: * This operation is faster than converting a DateMidnight to a MutableDateTime
1329: * and back again when setting one field. When setting multiple fields,
1330: * it is generally quicker to make the conversion to MutableDateTime.
1331: *
1332: * @param text the text value to set
1333: * @return a copy of the DateMidnight with the field value changed
1334: * @throws IllegalArgumentException if the text value isn't valid
1335: */
1336: public DateMidnight setCopy(String text) {
1337: return setCopy(text, null);
1338: }
1339:
1340: //-----------------------------------------------------------------------
1341: /**
1342: * Returns a new DateMidnight with this field set to the maximum value
1343: * for this field.
1344: * <p>
1345: * This operation is useful for obtaining a DateTime on the last day
1346: * of the month, as month lengths vary.
1347: * <pre>
1348: * DateMidnight lastDayOfMonth = dt.dayOfMonth().withMaximumValue();
1349: * </pre>
1350: * <p>
1351: * The DateMidnight attached to this property is unchanged by this call.
1352: *
1353: * @return a copy of the DateMidnight with this field set to its maximum
1354: * @since 1.2
1355: */
1356: public DateMidnight withMaximumValue() {
1357: return setCopy(getMaximumValue());
1358: }
1359:
1360: /**
1361: * Returns a new DateMidnight with this field set to the minimum value
1362: * for this field.
1363: * <p>
1364: * The DateMidnight attached to this property is unchanged by this call.
1365: *
1366: * @return a copy of the DateMidnight with this field set to its minimum
1367: * @since 1.2
1368: */
1369: public DateMidnight withMinimumValue() {
1370: return setCopy(getMinimumValue());
1371: }
1372:
1373: //-----------------------------------------------------------------------
1374: /**
1375: * Rounds to the lowest whole unit of this field on a copy of this DateMidnight.
1376: *
1377: * @return a copy of the DateMidnight with the field value changed
1378: */
1379: public DateMidnight roundFloorCopy() {
1380: return iInstant.withMillis(iField.roundFloor(iInstant
1381: .getMillis()));
1382: }
1383:
1384: /**
1385: * Rounds to the highest whole unit of this field on a copy of this DateMidnight.
1386: *
1387: * @return a copy of the DateMidnight with the field value changed
1388: */
1389: public DateMidnight roundCeilingCopy() {
1390: return iInstant.withMillis(iField.roundCeiling(iInstant
1391: .getMillis()));
1392: }
1393:
1394: /**
1395: * Rounds to the nearest whole unit of this field on a copy of this DateMidnight,
1396: * favoring the floor if halfway.
1397: *
1398: * @return a copy of the DateMidnight with the field value changed
1399: */
1400: public DateMidnight roundHalfFloorCopy() {
1401: return iInstant.withMillis(iField.roundHalfFloor(iInstant
1402: .getMillis()));
1403: }
1404:
1405: /**
1406: * Rounds to the nearest whole unit of this field on a copy of this DateMidnight,
1407: * favoring the ceiling if halfway.
1408: *
1409: * @return a copy of the DateMidnight with the field value changed
1410: */
1411: public DateMidnight roundHalfCeilingCopy() {
1412: return iInstant.withMillis(iField.roundHalfCeiling(iInstant
1413: .getMillis()));
1414: }
1415:
1416: /**
1417: * Rounds to the nearest whole unit of this field on a copy of this DateMidnight.
1418: * If halfway, the ceiling is favored over the floor only if it makes this field's value even.
1419: *
1420: * @return a copy of the DateMidnight with the field value changed
1421: */
1422: public DateMidnight roundHalfEvenCopy() {
1423: return iInstant.withMillis(iField.roundHalfEven(iInstant
1424: .getMillis()));
1425: }
1426:
1427: }
1428: }
|