DateTime


1   /*
2    *  Copyright 2001-2006 Stephen Colebourne
3    *
4    *  Licensed under the Apache License, Version 2.0 (the "License");
5    *  you may not use this file except in compliance with the License.
6    *  You may obtain a copy of the License at
7    *
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    *
10   *  Unless required by applicable law or agreed to in writing, software
11   *  distributed under the License is distributed on an "AS IS" BASIS,
12   *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   *  See the License for the specific language governing permissions and
14   *  limitations under the License.
15   */
16  package org.joda.time;
17  
18  import java.io.IOException  ;
19  import java.io.ObjectInputStream  ;
20  import java.io.ObjectOutputStream  ;
21  import java.io.Serializable  ;
22  import java.util.Locale  ;
23  
24  import org.joda.time.base.BaseDateTime;
25  import org.joda.time.chrono.ISOChronology;
26  import org.joda.time.field.AbstractReadableInstantFieldProperty;
27  import org.joda.time.format.ISODateTimeFormat;
28  
29  /**
30   * DateTime is the standard implementation of an unmodifiable datetime class.
31   * It holds the datetime as milliseconds from the Java epoch of 1970-01-01T00:00:00Z.
32   * <p>
33   * This class uses a Chronology internally. The Chronology determines how the
34   * millisecond instant value is converted into the date time fields.
35   * The default Chronology is <code>ISOChronology</code> which is the agreed
36   * international standard and compatable with the modern Gregorian calendar.
37   *
38   * <p>Each individual field can be queried in two ways:
39   * <ul>
40   * <li><code>getHourOfDay()</code>
41   * <li><code>hourOfDay().get()</code>
42   * </ul>
43   * The second technique also provides access to other useful methods on the
44   * field:
45   * <ul>
46   * <li>numeric value
47   * <li>text value
48   * <li>short text value
49   * <li>maximum/minimum values
50   * <li>add/subtract
51   * <li>set
52   * <li>rounding
53   * </ul>
54   *
55   * <p>
56   * DateTime is thread-safe and immutable, provided that the Chronology is as well.
57   * All standard Chronology classes supplied are thread-safe and immutable.
58   *
59   * @author Stephen Colebourne
60   * @author Kandarp Shah
61   * @author Brian S O'Neill
62   * @since 1.0
63   * @see MutableDateTime
64   */
65  public final class DateTime
66          extends BaseDateTime
67          implements ReadableDateTime, Serializable   {
68  
69      /** Serialization lock */
70      private static final long serialVersionUID = -5171125899451703815L;
71  
72      //-----------------------------------------------------------------------
73      /**
74       * Constructs an instance set to the current system millisecond time
75       * using <code>ISOChronology</code> in the default time zone.
76       */
77      public DateTime() {
78          super();
79      }
80  
81      /**
82       * Constructs an instance set to the current system millisecond time
83       * using <code>ISOChronology</code> in the specified time zone.
84       * <p>
85       * If the specified time zone is null, the default zone is used.
86       *
87       * @param zone  the time zone, null means default zone
88       */
89      public DateTime(DateTimeZone zone) {
90          super(zone);
91      }
92  
93      /**
94       * Constructs an instance set to the current system millisecond time
95       * using the specified chronology.
96       * <p>
97       * If the chronology is null, <code>ISOChronology</code>
98       * in the default time zone is used.
99       *
100      * @param chronology  the chronology, null means ISOChronology in default zone
101      */
102     public DateTime(Chronology chronology) {
103         super(chronology);
104     }
105 
106     //-----------------------------------------------------------------------
107     /**
108      * Constructs an instance set to the milliseconds from 1970-01-01T00:00:00Z
109      * using <code>ISOChronology</code> in the default time zone.
110      *
111      * @param instant  the milliseconds from 1970-01-01T00:00:00Z
112      */
113     public DateTime(long instant) {
114         super(instant);
115     }
116 
117     /**
118      * Constructs an instance set to the milliseconds from 1970-01-01T00:00:00Z
119      * using <code>ISOChronology</code> in the specified time zone.
120      * <p>
121      * If the specified time zone is null, the default zone is used.
122      *
123      * @param instant  the milliseconds from 1970-01-01T00:00:00Z
124      * @param zone  the time zone, null means default zone
125      */
126     public DateTime(long instant, DateTimeZone zone) {
127         super(instant, zone);
128     }
129 
130     /**
131      * Constructs an instance set to the milliseconds from 1970-01-01T00:00:00Z
132      * using the specified chronology.
133      * <p>
134      * If the chronology is null, <code>ISOChronology</code>
135      * in the default time zone is used.
136      *
137      * @param instant  the milliseconds from 1970-01-01T00:00:00Z
138      * @param chronology  the chronology, null means ISOChronology in default zone
139      */
140     public DateTime(long instant, Chronology chronology) {
141         super(instant, chronology);
142     }
143 
144     //-----------------------------------------------------------------------
145     /**
146      * Constructs an instance from an Object that represents a datetime.
147      * <p>
148      * If the object implies a chronology (such as GregorianCalendar does),
149      * then that chronology will be used. Otherwise, ISO default is used.
150      * Thus if a GregorianCalendar is passed in, the chronology used will
151      * be GJ, but if a Date is passed in the chronology will be ISO.
152      * <p>
153      * The recognised object types are defined in
154      * {@link org.joda.time.convert.ConverterManager ConverterManager} and
155      * include ReadableInstant, String, Calendar and Date.
156      * The String formats are described by {@link ISODateTimeFormat#dateTimeParser()}.
157      *
158      * @param instant  the datetime object, null means now
159      * @throws IllegalArgumentException if the instant is invalid
160      */
161     public DateTime(Object   instant) {
162         super(instant, (Chronology) null);
163     }
164 
165     /**
166      * Constructs an instance from an Object that represents a datetime,
167      * forcing the time zone to that specified.
168      * <p>
169      * If the object implies a chronology (such as GregorianCalendar does),
170      * then that chronology will be used, but with the time zone adjusted.
171      * Otherwise, ISO is used in the specified time zone.
172      * If the specified time zone is null, the default zone is used.
173      * Thus if a GregorianCalendar is passed in, the chronology used will
174      * be GJ, but if a Date is passed in the chronology will be ISO.
175      * <p>
176      * The recognised object types are defined in
177      * {@link org.joda.time.convert.ConverterManager ConverterManager} and
178      * include ReadableInstant, String, Calendar and Date.
179      * The String formats are described by {@link ISODateTimeFormat#dateTimeParser()}.
180      *
181      * @param instant  the datetime object, null means now
182      * @param zone  the time zone, null means default time zone
183      * @throws IllegalArgumentException if the instant is invalid
184      */
185     public DateTime(Object   instant, DateTimeZone zone) {
186         super(instant, zone);
187     }
188 
189     /**
190      * Constructs an instance from an Object that represents a datetime,
191      * using the specified chronology.
192      * <p>
193      * If the chronology is null, ISO in the default time zone is used.
194      * Any chronology implied by the object (such as GregorianCalendar does)
195      * is ignored.
196      * <p>
197      * The recognised object types are defined in
198      * {@link org.joda.time.convert.ConverterManager ConverterManager} and
199      * include ReadableInstant, String, Calendar and Date.
200      * The String formats are described by {@link ISODateTimeFormat#dateTimeParser()}.
201      *
202      * @param instant  the datetime object, null means now
203      * @param chronology  the chronology, null means ISO in default zone
204      * @throws IllegalArgumentException if the instant is invalid
205      */
206     public DateTime(Object   instant, Chronology chronology) {
207         super(instant, DateTimeUtils.getChronology(chronology));
208     }
209 
210     //-----------------------------------------------------------------------
211     /**
212      * Constructs an instance from datetime field values
213      * using <code>ISOChronology</code> in the default time zone.
214      *
215      * @param year  the year
216      * @param monthOfYear  the month of the year
217      * @param dayOfMonth  the day of the month
218      * @param hourOfDay  the hour of the day
219      * @param minuteOfHour  the minute of the hour
220      * @param secondOfMinute  the second of the minute
221      * @param millisOfSecond  the millisecond of the second
222      */
223     public DateTime(
224             int year,
225             int monthOfYear,
226             int dayOfMonth,
227             int hourOfDay,
228             int minuteOfHour,
229             int secondOfMinute,
230             int millisOfSecond) {
231         super(year, monthOfYear, dayOfMonth, hourOfDay, minuteOfHour, secondOfMinute, millisOfSecond);
232     }
233 
234     /**
235      * Constructs an instance from datetime field values
236      * using <code>ISOChronology</code> in the specified time zone.
237      * <p>
238      * If the specified time zone is null, the default zone is used.
239      *
240      * @param year  the year
241      * @param monthOfYear  the month of the year
242      * @param dayOfMonth  the day of the month
243      * @param hourOfDay  the hour of the day
244      * @param minuteOfHour  the minute of the hour
245      * @param secondOfMinute  the second of the minute
246      * @param millisOfSecond  the millisecond of the second
247      * @param zone  the time zone, null means default time zone
248      */
249     public DateTime(
250             int year,
251             int monthOfYear,
252             int dayOfMonth,
253             int hourOfDay,
254             int minuteOfHour,
255             int secondOfMinute,
256             int millisOfSecond,
257             DateTimeZone zone) {
258         super(year, monthOfYear, dayOfMonth,
259               hourOfDay, minuteOfHour, secondOfMinute, millisOfSecond, zone);
260     }
261 
262     /**
263      * Constructs an instance from datetime field values
264      * using the specified chronology.
265      * <p>
266      * If the chronology is null, <code>ISOChronology</code>
267      * in the default time zone is used.
268      *
269      * @param year  the year
270      * @param monthOfYear  the month of the year
271      * @param dayOfMonth  the day of the month
272      * @param hourOfDay  the hour of the day
273      * @param minuteOfHour  the minute of the hour
274      * @param secondOfMinute  the second of the minute
275      * @param millisOfSecond  the millisecond of the second
276      * @param chronology  the chronology, null means ISOChronology in default zone
277      */
278     public DateTime(
279             int year,
280             int monthOfYear,
281             int dayOfMonth,
282             int hourOfDay,
283             int minuteOfHour,
284             int secondOfMinute,
285             int millisOfSecond,
286             Chronology chronology) {
287         super(year, monthOfYear, dayOfMonth,
288               hourOfDay, minuteOfHour, secondOfMinute, millisOfSecond, chronology);
289     }
290 
291     //-----------------------------------------------------------------------
292     /**
293      * Get this object as a DateTime by returning <code>this</code>.
294      * 
295      * @return <code>this</code>
296      */
297     public DateTime toDateTime() {
298         return this;
299     }
300 
301     /**
302      * Get this object as a DateTime using ISOChronology in the default zone,
303      * returning <code>this</code> if possible.
304      * 
305      * @return a DateTime using the same millis
306      */
307     public DateTime toDateTimeISO() {
308         if (getChronology() == ISOChronology.getInstance()) {
309             return this;
310         }
311         return super.toDateTimeISO();
312     }
313 
314     /**
315      * Get this object as a DateTime, returning <code>this</code> if possible.
316      * 
317      * @param zone time zone to apply, or default if null
318      * @return a DateTime using the same millis
319      */
320     public DateTime toDateTime(DateTimeZone zone) {
321         zone = DateTimeUtils.getZone(zone);
322         if (getZone() == zone) {
323             return this;
324         }
325         return super.toDateTime(zone);
326     }
327 
328     /**
329      * Get this object as a DateTime, returning <code>this</code> if possible.
330      * 
331      * @param chronology chronology to apply, or ISOChronology if null
332      * @return a DateTime using the same millis
333      */
334     public DateTime toDateTime(Chronology chronology) {
335         chronology = DateTimeUtils.getChronology(chronology);
336         if (getChronology() == chronology) {
337             return this;
338         }
339         return super.toDateTime(chronology);
340     }
341 
342     //-----------------------------------------------------------------------
343     /**
344      * Returns a copy of this datetime with different millis.
345      * <p>
346      * The returned object will be either be a new instance or <code>this</code>.
347      * Only the millis will change, the chronology and time zone are kept.
348      *
349      * @param newMillis  the new millis, from 1970-01-01T00:00:00Z
350      * @return a copy of this datetime with different millis
351      */
352     public DateTime withMillis(long newMillis) {
353         return (newMillis == getMillis() ? this : new DateTime(newMillis, getChronology()));
354     }
355 
356     /**
357      * Returns a copy of this datetime with a different chronology.
358      * <p>
359      * The returned object will be either be a new instance or <code>this</code>.
360      * Only the chronology will change, the millis are kept.
361      *
362      * @param newChronology  the new chronology, null means ISO default
363      * @return a copy of this datetime with a different chronology
364      */
365     public DateTime withChronology(Chronology newChronology) {
366         newChronology = DateTimeUtils.getChronology(newChronology);
367         return (newChronology == getChronology() ? this : new DateTime(getMillis(), newChronology));
368     }
369 
370     //-----------------------------------------------------------------------
371     /**
372      * Returns a copy of this datetime with a different time zone, preserving the
373      * millisecond instant.
374      * <p>
375      * This method is useful for finding the local time in another timezone.
376      * For example, if this instant holds 12:30 in Europe/London, the result
377      * from this method with Europe/Paris would be 13:30.
378      * <p>
379      * The returned object will be a new instance of the same implementation type.
380      * This method changes the time zone, and does not change the
381      * millisecond instant, with the effect that the field values usually change.
382      * The returned object will be either be a new instance or <code>this</code>.
383      *
384      * @param newZone  the new time zone
385      * @return a copy of this datetime with a different time zone
386      * @see #withZoneRetainFields
387      */
388     public DateTime withZone(DateTimeZone newZone) {
389         return withChronology(getChronology().withZone(newZone));
390     }
391 
392     /**
393      * Returns a copy of this datetime with a different time zone, preserving the
394      * field values.
395      * <p>
396      * This method is useful for finding the millisecond time in another timezone.
397      * For example, if this instant holds 12:30 in Europe/London (ie. 12:30Z),
398      * the result from this method with Europe/Paris would be 12:30 (ie. 11:30Z).
399      * <p>
400      * The returned object will be a new instance of the same implementation type.
401      * This method changes the time zone and the millisecond instant to keep
402      * the field values the same.
403      * The returned object will be either be a new instance or <code>this</code>.
404      *
405      * @param newZone  the new time zone, null means default
406      * @return a copy of this datetime with a different time zone
407      * @see #withZone
408      */
409     public DateTime withZoneRetainFields(DateTimeZone newZone) {
410         newZone = DateTimeUtils.getZone(newZone);
411         DateTimeZone originalZone = DateTimeUtils.getZone(getZone());
412         if (newZone == originalZone) {
413             return this;
414         }
415         
416         long millis = originalZone.getMillisKeepLocal(newZone, getMillis());
417         return new DateTime(millis, getChronology().withZone(newZone));
418     }
419 
420     //-----------------------------------------------------------------------
421     /**
422      * Returns a copy of this datetime with the specified date, retaining the time fields.
423      * <p>
424      * If the date is already the date passed in, then <code>this</code> is returned.
425      * <p>
426      * To set a single field use the properties, for example:
427      * <pre>
428      * DateTime set = monthOfYear().setCopy(6);
429      * </pre>
430      *
431      * @param year  the new year value
432      * @param monthOfYear  the new monthOfYear value
433      * @param dayOfMonth  the new dayOfMonth value
434      * @return a copy of this datetime with a different date
435      * @throws IllegalArgumentException if any value if invalid
436      */
437     public DateTime withDate(int year, int monthOfYear, int dayOfMonth) {
438         Chronology chrono = getChronology();
439         long instant = getMillis();
440         instant = chrono.year().set(instant, year);
441         instant = chrono.monthOfYear().set(instant, monthOfYear);
442         instant = chrono.dayOfMonth().set(instant, dayOfMonth);
443         return withMillis(instant);
444     }
445 
446     /**
447      * Returns a copy of this datetime with the specified time, retaining the date fields.
448      * <p>
449      * If the time is already the time passed in, then <code>this</code> is returned.
450      * <p>
451      * To set a single field use the properties, for example:
452      * <pre>
453      * DateTime set = dt.hourOfDay().setCopy(6);
454      * </pre>
455      *
456      * @param hourOfDay  the hour of the day
457      * @param minuteOfHour  the minute of the hour
458      * @param secondOfMinute  the second of the minute
459      * @param millisOfSecond  the millisecond of the second
460      * @return a copy of this datetime with a different time
461      * @throws IllegalArgumentException if any value if invalid
462      */
463     public DateTime withTime(int hourOfDay, int minuteOfHour, int secondOfMinute, int millisOfSecond) {
464         Chronology chrono = getChronology();
465         long instant = getMillis();
466         instant = chrono.hourOfDay().set(instant, hourOfDay);
467         instant = chrono.minuteOfHour().set(instant, minuteOfHour);
468         instant = chrono.secondOfMinute().set(instant, secondOfMinute);
469         instant = chrono.millisOfSecond().set(instant, millisOfSecond);
470         return withMillis(instant);
471     }
472 
473     //-----------------------------------------------------------------------
474     /**
475      * Returns a copy of this datetime with the partial set of fields replacing those
476      * from this instance.
477      * <p>
478      * For example, if the partial is a <code>TimeOfDay</code> then the time fields
479      * would be changed in the returned instance.
480      * If the partial is null, then <code>this</code> is returned.
481      *
482      * @param partial  the partial set of fields to apply to this datetime, null ignored
483      * @return a copy of this datetime with a different set of fields
484      * @throws IllegalArgumentException if any value is invalid
485      */
486     public DateTime withFields(ReadablePartial partial) {
487         if (partial == null) {
488             return this;
489         }
490         return withMillis(getChronology().set(partial, getMillis()));
491     }
492 
493     /**
494      * Returns a copy of this datetime with the specified field set to a new value.
495      * <p>
496      * For example, if the field type is <code>hourOfDay</code> then the hour of day
497      * field would be changed in the returned instance.
498      * If the field type is null, then <code>this</code> is returned.
499      * <p>
500      * These three lines are equivalent:
501      * <pre>
502      * DateTime updated = dt.withField(DateTimeFieldType.dayOfMonth(), 6);
503      * DateTime updated = dt.dayOfMonth().setCopy(6);
504      * DateTime updated = dt.property(DateTimeFieldType.dayOfMonth()).setCopy(6);
505      * </pre>
506      *
507      * @param fieldType  the field type to set, not null
508      * @param value  the value to set
509      * @return a copy of this datetime with the field set
510      * @throws IllegalArgumentException if the value is null or invalid
511      */
512     public DateTime withField(DateTimeFieldType fieldType, int value) {
513         if (fieldType == null) {
514             throw new IllegalArgumentException  ("Field must not be null");
515         }
516         long instant = fieldType.getField(getChronology()).set(getMillis(), value);
517         return withMillis(instant);
518     }
519 
520     /**
521      * Returns a copy of this datetime with the value of the specified field increased.
522      * <p>
523      * If the addition is zero or the field is null, then <code>this</code> is returned.
524      * <p>
525      * These three lines are equivalent:
526      * <pre>
527      * DateTime added = dt.withFieldAdded(DurationFieldType.years(), 6);
528      * DateTime added = dt.plusYears(6);
529      * DateTime added = dt.plus(Period.years(6));
530      * </pre>
531      * 
532      * @param fieldType  the field type to add to, not null
533      * @param amount  the amount to add
534      * @return a copy of this datetime with the field updated
535      * @throws IllegalArgumentException if the value is null or invalid
536      * @throws ArithmeticException if the new datetime exceeds the capacity of a long
537      */
538     public DateTime withFieldAdded(DurationFieldType fieldType, int amount) {
539         if (fieldType == null) {
540             throw new IllegalArgumentException  ("Field must not be null");
541         }
542         if (amount == 0) {
543             return this;
544         }
545         long instant = fieldType.getField(getChronology()).add(getMillis(), amount);
546         return withMillis(instant);
547     }
548 
549     //-----------------------------------------------------------------------
550     /**
551      * Returns a copy of this datetime with the specified duration added.
552      * <p>
553      * If the addition is zero, then <code>this</code> is returned.
554      * 
555      * @param durationToAdd  the duration to add to this one
556      * @param scalar  the amount of times to add, such as -1 to subtract once
557      * @return a copy of this datetime with the duration added
558      * @throws ArithmeticException if the new datetime exceeds the capacity of a long
559      */
560     public DateTime withDurationAdded(long durationToAdd, int scalar) {
561         if (durationToAdd == 0 || scalar == 0) {
562             return this;
563         }
564         long instant = getChronology().add(getMillis(), durationToAdd, scalar);
565         return withMillis(instant);
566     }
567 
568     /**
569      * Returns a copy of this datetime with the specified duration added.
570      * <p>
571      * If the addition is zero, then <code>this</code> is returned.
572      * 
573      * @param durationToAdd  the duration to add to this one, null means zero
574      * @param scalar  the amount of times to add, such as -1 to subtract once
575      * @return a copy of this datetime with the duration added
576      * @throws ArithmeticException if the new datetime exceeds the capacity of a long
577      */
578     public DateTime withDurationAdded(ReadableDuration durationToAdd, int scalar) {
579         if (durationToAdd == null || scalar == 0) {
580             return this;
581         }
582         return withDurationAdded(durationToAdd.getMillis(), scalar);
583     }
584 
585     /**
586      * Returns a copy of this datetime with the specified period added.
587      * <p>
588      * If the addition is zero, then <code>this</code> is returned.
589      * <p>
590      * This method is typically used to add multiple copies of complex
591      * period instances. Adding one field is best achieved using methods
592      * like {@link #withFieldAdded(DurationFieldType, int)}
593      * or {@link #plusYears(int)}.
594      * 
595      * @param period  the period to add to this one, null means zero
596      * @param scalar  the amount of times to add, such as -1 to subtract once
597      * @return a copy of this datetime with the period added
598      * @throws ArithmeticException if the new datetime exceeds the capacity of a long
599      */
600     public DateTime withPeriodAdded(ReadablePeriod period, int scalar) {
601         if (period == null || scalar == 0) {
602             return this;
603         }
604         long instant = getChronology().add(period, getMillis(), scalar);
605         return withMillis(instant);
606     }
607 
608     //-----------------------------------------------------------------------
609     /**
610      * Returns a copy of this datetime with the specified duration added.
611      * <p>
612      * If the amount is zero or null, then <code>this</code> is returned.
613      * 
614      * @param duration  the duration, in millis, to add to this one
615      * @return a copy of this datetime with the duration added
616      * @throws ArithmeticException if the new datetime exceeds the capacity of a long
617      */
618     public DateTime plus(long duration) {
619         return withDurationAdded(duration, 1);
620     }
621 
622     /**
623      * Returns a copy of this datetime with the specified duration added.
624      * <p>
625      * If the amount is zero or null, then <code>this</code> is returned.
626      * 
627      * @param duration  the duration to add to this one, null means zero
628      * @return a copy of this datetime with the duration added
629      * @throws ArithmeticException if the new datetime exceeds the capacity of a long
630      */
631     public DateTime plus(ReadableDuration duration) {
632         return withDurationAdded(duration, 1);
633     }
634 
635     /**
636      * Returns a copy of this datetime with the specified period added.
637      * <p>
638      * If the amount is zero or null, then <code>this</code> is returned.
639      * <p>
640      * This method is typically used to add complex period instances.
641      * Adding one field is best achieved using methods
642      * like {@link #plusYears(int)}.
643      * 
644      * @param period  the duration to add to this one, null means zero
645      * @return a copy of this datetime with the period added
646      * @throws ArithmeticException if the new datetime exceeds the capacity of a long
647      */
648     public DateTime plus(ReadablePeriod period) {
649         return withPeriodAdded(period, 1);
650     }
651 
652     //-----------------------------------------------------------------------
653     /**
654      * Returns a copy of this datetime plus the specified number of years.
655      * <p>
656      * This datetime instance is immutable and unaffected by this method call.
657      * <p>
658      * The following three lines are identical in effect:
659      * <pre>
660      * DateTime added = dt.plusYears(6);
661      * DateTime added = dt.plus(Period.years(6));
662      * DateTime added = dt.withFieldAdded(DurationFieldType.years(), 6);
663      * </pre>
664      *
665      * @param years  the amount of years to add, may be negative
666      * @return the new datetime plus the increased years
667      * @since 1.1
668      */
669     public DateTime plusYears(int years) {
670         if (years == 0) {
671             return this;
672         }
673         long instant = getChronology().years().add(getMillis(), years);
674         return withMillis(instant);
675     }
676 
677     /**
678      * Returns a copy of this datetime plus the specified number of months.
679      * <p>
680      * This datetime instance is immutable and unaffected by this method call.
681      * <p>
682      * The following three lines are identical in effect:
683      * <pre>
684      * DateTime added = dt.plusMonths(6);
685      * DateTime added = dt.plus(Period.months(6));
686      * DateTime added = dt.withFieldAdded(DurationFieldType.months(), 6);
687      * </pre>
688      *
689      * @param months  the amount of months to add, may be negative
690      * @return the new datetime plus the increased months
691      * @since 1.1
692      */
693     public DateTime plusMonths(int months) {
694         if (months == 0) {
695             return this;
696         }
697         long instant = getChronology().months().add(getMillis(), months);
698         return withMillis(instant);
699     }
700 
701     /**
702      * Returns a copy of this datetime plus the specified number of weeks.
703      * <p>
704      * This datetime instance is immutable and unaffected by this method call.
705      * <p>
706      * The following three lines are identical in effect:
707      * <pre>
708      * DateTime added = dt.plusWeeks(6);
709      * DateTime added = dt.plus(Period.weeks(6));
710      * DateTime added = dt.withFieldAdded(DurationFieldType.weeks(), 6);
711      * </pre>
712      *
713      * @param weeks  the amount of weeks to add, may be negative
714      * @return the new datetime plus the increased weeks
715      * @since 1.1
716      */
717     public DateTime plusWeeks(int weeks) {
718         if (weeks == 0) {
719             return this;
720         }
721         long instant = getChronology().weeks().add(getMillis(), weeks);
722         return withMillis(instant);
723     }
724 
725     /**
726      * Returns a copy of this datetime plus the specified number of days.
727      * <p>
728      * This datetime instance is immutable and unaffected by this method call.
729      * <p>
730      * The following three lines are identical in effect:
731      * <pre>
732      * DateTime added = dt.plusDays(6);
733      * DateTime added = dt.plus(Period.days(6));
734      * DateTime added = dt.withFieldAdded(DurationFieldType.days(), 6);
735      * </pre>
736      *
737      * @param days  the amount of days to add, may be negative
738      * @return the new datetime plus the increased days
739      * @since 1.1
740      */
741     public DateTime plusDays(int days) {
742         if (days == 0) {
743             return this;
744         }
745         long instant = getChronology().days().add(getMillis(), days);
746         return withMillis(instant);
747     }
748 
749     /**
750      * Returns a copy of this datetime plus the specified number of hours.
751      * <p>
752      * This datetime instance is immutable and unaffected by this method call.
753      * <p>
754      * The following three lines are identical in effect:
755      * <pre>
756      * DateTime added = dt.plusHours(6);
757      * DateTime added = dt.plus(Period.hours(6));
758      * DateTime added = dt.withFieldAdded(DurationFieldType.hours(), 6);
759      * </pre>
760      *
761      * @param hours  the amount of hours to add, may be negative
762      * @return the new datetime plus the increased hours
763      * @since 1.1
764      */
765     public DateTime plusHours(int hours) {
766         if (hours == 0) {
767             return this;
768         }
769         long instant = getChronology().hours().add(getMillis(), hours);
770         return withMillis(instant);
771     }
772 
773     /**
774      * Returns a copy of this datetime plus the specified number of minutes.
775      * <p>
776      * This datetime instance is immutable and unaffected by this method call.
777      * <p>
778      * The following three lines are identical in effect:
779      * <pre>
780      * DateTime added = dt.plusMinutes(6);
781      * DateTime added = dt.plus(Period.minutes(6));
782      * DateTime added = dt.withFieldAdded(DurationFieldType.minutes(), 6);
783      * </pre>
784      *
785      * @param minutes  the amount of minutes to add, may be negative
786      * @return the new datetime plus the increased minutes
787      * @since 1.1
788      */
789     public DateTime plusMinutes(int minutes) {
790         if (minutes == 0) {
791             return this;
792         }
793         long instant = getChronology().minutes().add(getMillis(), minutes);
794         return withMillis(instant);
795     }
796 
797     /**
798      * Returns a copy of this datetime plus the specified number of seconds.
799      * <p>
800      * This datetime instance is immutable and unaffected by this method call.
801      * <p>
802      * The following three lines are identical in effect:
803      * <pre>
804      * DateTime added = dt.plusSeconds(6);
805      * DateTime added = dt.plus(Period.seconds(6));
806      * DateTime added = dt.withFieldAdded(DurationFieldType.seconds(), 6);
807      * </pre>
808      *
809      * @param seconds  the amount of seconds to add, may be negative
810      * @return the new datetime plus the increased seconds
811      * @since 1.1
812      */
813     public DateTime plusSeconds(int seconds) {
814         if (seconds == 0) {
815             return this;
816         }
817         long instant = getChronology().seconds().add(getMillis(), seconds);
818         return withMillis(instant);
819     }
820 
821     /**
822      * Returns a copy of this datetime plus the specified number of millis.
823      * <p>
824      * This datetime instance is immutable and unaffected by this method call.
825      * <p>
826      * The following three lines are identical in effect:
827      * <pre>
828      * DateTime added = dt.plusMillis(6);
829      * DateTime added = dt.plus(Period.millis(6));
830      * DateTime added = dt.withFieldAdded(DurationFieldType.millis(), 6);
831      * </pre>
832      *
833      * @param millis  the amount of millis to add, may be negative
834      * @return the new datetime plus the increased millis
835      * @since 1.1
836      */
837     public DateTime plusMillis(int millis) {
838         if (millis == 0) {
839             return this;
840         }
841         long instant = getChronology().millis().add(getMillis(), millis);
842         return withMillis(instant);
843     }
844 
845     //-----------------------------------------------------------------------
846     /**
847      * Returns a copy of this datetime with the specified duration taken away.
848      * <p>
849      * If the amount is zero or null, then <code>this</code> is returned.
850      * 
851      * @param duration  the duration, in millis, to reduce this instant by
852      * @return a copy of this datetime with the duration taken away
853      * @throws ArithmeticException if the new datetime exceeds the capacity of a long
854      */
855     public DateTime minus(long duration) {
856         return withDurationAdded(duration, -1);
857     }
858 
859     /**
860      * Returns a copy of this datetime with the specified duration taken away.
861      * <p>
862      * If the amount is zero or null, then <code>this</code> is returned.
863      * 
864      * @param duration  the duration to reduce this instant by
865      * @return a copy of this datetime with the duration taken away
866      * @throws ArithmeticException if the new datetime exceeds the capacity of a long
867      */
868     public DateTime minus(ReadableDuration duration) {
869         return withDurationAdded(duration, -1);
870     }
871 
872     /**
873      * Returns a copy of this datetime with the specified period taken away.
874      * <p>
875      * If the amount is zero or null, then <code>this</code> is returned.
876      * <p>
877      * This method is typically used to subtract complex period instances.
878      * Subtracting one field is best achieved using methods
879      * like {@link #minusYears(int)}.
880      * 
881      * @param period  the period to reduce this instant by
882      * @return a copy of this datetime with the period taken away
883      * @throws ArithmeticException if the new datetime exceeds the capacity of a long
884      */
885     public DateTime minus(ReadablePeriod period) {
886         return withPeriodAdded(period, -1);
887     }
888 
889     //-----------------------------------------------------------------------
890     /**
891      * Returns a copy of this datetime minus the specified number of years.
892      * <p>
893      * This datetime instance is immutable and unaffected by this method call.
894      * <p>
895      * The following three lines are identical in effect:
896      * <pre>
897      * DateTime subtracted = dt.minusYears(6);
898      * DateTime subtracted = dt.minus(Period.years(6));
899      * DateTime subtracted = dt.withFieldAdded(DurationFieldType.years(), -6);
900      * </pre>
901      *
902      * @param years  the amount of years to subtract, may be negative
903      * @return the new datetime minus the increased years
904      * @since 1.1
905      */
906     public DateTime minusYears(int years) {
907         if (years == 0) {
908             return this;
909         }
910         long instant = getChronology().years().subtract(getMillis(), years);
911         return withMillis(instant);
912     }
913 
914     /**
915      * Returns a copy of this datetime minus the specified number of months.
916      * <p>
917      * This datetime instance is immutable and unaffected by this method call.
918      * <p>
919      * The following three lines are identical in effect:
920      * <pre>
921      * DateTime subtracted = dt.minusMonths(6);
922      * DateTime subtracted = dt.minus(Period.months(6));
923      * DateTime subtracted = dt.withFieldAdded(DurationFieldType.months(), -6);
924      * </pre>
925      *
926      * @param months  the amount of months to subtract, may be negative
927      * @return the new datetime minus the increased months
928      * @since 1.1
929      */
930     public DateTime minusMonths(int months) {
931         if (months == 0) {
932             return this;
933         }
934         long instant = getChronology().months().subtract(getMillis(), months);
935         return withMillis(instant);
936     }
937 
938     /**
939      * Returns a copy of this datetime minus the specified number of weeks.
940      * <p>
941      * This datetime instance is immutable and unaffected by this method call.
942      * <p>
943      * The following three lines are identical in effect:
944      * <pre>
945      * DateTime subtracted = dt.minusWeeks(6);
946      * DateTime subtracted = dt.minus(Period.weeks(6));
947      * DateTime subtracted = dt.withFieldAdded(DurationFieldType.weeks(), -6);
948      * </pre>
949      *
950      * @param weeks  the amount of weeks to subtract, may be negative
951      * @return the new datetime minus the increased weeks
952      * @since 1.1
953      */
954     public DateTime minusWeeks(int weeks) {
955         if (weeks == 0) {
956             return this;
957         }
958         long instant = getChronology().weeks().subtract(getMillis(), weeks);
959         return withMillis(instant);
960     }
961 
962     /**
963      * Returns a copy of this datetime minus the specified number of days.
964      * <p>
965      * This datetime instance is immutable and unaffected by this method call.
966      * <p>
967      * The following three lines are identical in effect:
968      * <pre>
969      * DateTime subtracted = dt.minusDays(6);
970      * DateTime subtracted = dt.minus(Period.days(6));
971      * DateTime subtracted = dt.withFieldAdded(DurationFieldType.days(), -6);
972      * </pre>
973      *
974      * @param days  the amount of days to subtract, may be negative
975      * @return the new datetime minus the increased days
976      * @since 1.1
977      */
978     public DateTime minusDays(int days) {
979         if (days == 0) {
980             return this;
981         }
982         long instant = getChronology().days().subtract(getMillis(), days);
983         return withMillis(instant);
984     }
985 
986     /**
987      * Returns a copy of this datetime minus the specified number of hours.
988      * <p>
989      * This datetime instance is immutable and unaffected by this method call.
990      * <p>
991      * The following three lines are identical in effect:
992      * <pre>
993      * DateTime subtracted = dt.minusHours(6);
994      * DateTime subtracted = dt.minus(Period.hours(6));
995      * DateTime subtracted = dt.withFieldAdded(DurationFieldType.hours(), -6);
996      * </pre>
997      *
998      * @param hours  the amount of hours to subtract, may be negative
999      * @return the new datetime minus the increased hours
1000     * @since 1.1
1001     */
1002    public DateTime minusHours(int hours) {
1003        if (hours == 0) {
1004            return this;
1005        }
1006        long instant = getChronology().hours().subtract(getMillis(), hours);
1007        return withMillis(instant);
1008    }
1009
1010    /**
1011     * Returns a copy of this datetime minus the specified number of minutes.
1012     * <p>
1013     * This datetime instance is immutable and unaffected by this method call.
1014     * <p>
1015     * The following three lines are identical in effect:
1016     * <pre>
1017     * DateTime subtracted = dt.minusMinutes(6);
1018     * DateTime subtracted = dt.minus(Period.minutes(6));
1019     * DateTime subtracted = dt.withFieldAdded(DurationFieldType.minutes(), -6);
1020     * </pre>
1021     *
1022     * @param minutes  the amount of minutes to subtract, may be negative
1023     * @return the new datetime minus the increased minutes
1024     * @since 1.1
1025     */
1026    public DateTime minusMinutes(int minutes) {
1027        if (minutes == 0) {
1028            return this;
1029        }
1030        long instant = getChronology().minutes().subtract(getMillis(), minutes);
1031        return withMillis(instant);
1032    }
1033
1034    /**
1035     * Returns a copy of this datetime minus the specified number of seconds.
1036     * <p>
1037     * This datetime instance is immutable and unaffected by this method call.
1038     * <p>
1039     * The following three lines are identical in effect:
1040     * <pre>
1041     * DateTime subtracted = dt.minusSeconds(6);
1042     * DateTime subtracted = dt.minus(Period.seconds(6));
1043     * DateTime subtracted = dt.withFieldAdded(DurationFieldType.seconds(), -6);
1044     * </pre>
1045     *
1046     * @param seconds  the amount of seconds to subtract, may be negative
1047     * @return the new datetime minus the increased seconds
1048     * @since 1.1
1049     */
1050    public DateTime minusSeconds(int seconds) {
1051        if (seconds == 0) {
1052            return this;
1053        }
1054        long instant = getChronology().seconds().subtract(getMillis(), seconds);
1055        return withMillis(instant);
1056    }
1057
1058    /**
1059     * Returns a copy of this datetime minus the specified number of millis.
1060     * <p>
1061     * This datetime instance is immutable and unaffected by this method call.
1062     * <p>
1063     * The following three lines are identical in effect:
1064     * <pre>
1065     * DateTime subtracted = dt.minusMillis(6);
1066     * DateTime subtracted = dt.minus(Period.millis(6));
1067     * DateTime subtracted = dt.withFieldAdded(DurationFieldType.millis(), -6);
1068     * </pre>
1069     *
1070     * @param millis  the amount of millis to subtract, may be negative
1071     * @return the new datetime minus the increased millis
1072     * @since 1.1
1073     */
1074    public DateTime minusMillis(int millis) {
1075        if (millis == 0) {
1076            return this;
1077        }
1078        long instant = getChronology().millis().subtract(getMillis(), millis);
1079        return withMillis(instant);
1080    }
1081
1082    //-----------------------------------------------------------------------
1083    /**
1084     * Gets the property object for the specified type, which contains many useful methods.
1085     *
1086     * @param type  the field type to get the chronology for
1087     * @return the property object
1088     * @throws IllegalArgumentException if the field is null or unsupported
1089     */
1090    public Property property(DateTimeFieldType type) {
1091        if (type == null) {
1092            throw new IllegalArgumentException  ("The DateTimeFieldType must not be null");
1093        }
1094        DateTimeField field = type.getField(getChronology());
1095        if (field.isSupported() == false) {
1096            throw new IllegalArgumentException  ("Field '" + type + "' is not supported");
1097        }
1098        return new Property(this, field);
1099    }
1100
1101    //-----------------------------------------------------------------------
1102    /**
1103     * Converts this object to a <code>DateMidnight</code> using the
1104     * same millis and chronology.
1105     * 
1106     * @return a DateMidnight using the same millis and chronology
1107     */
1108    public DateMidnight toDateMidnight() {
1109        return new DateMidnight(getMillis(), getChronology());
1110    }
1111
1112    /**
1113     * Converts this object to a <code>YearMonthDay</code> using the
1114     * same millis and chronology.
1115     * 
1116     * @return a YearMonthDay using the same millis and chronology
1117     */
1118    public YearMonthDay toYearMonthDay() {
1119        return new YearMonthDay(getMillis(), getChronology());
1120    }
1121
1122    /**
1123     * Converts this object to a <code>TimeOfDay</code> using the
1124     * same millis and chronology.
1125     * 
1126     * @return a TimeOfDay using the same millis and chronology
1127     */
1128    public TimeOfDay toTimeOfDay() {
1129        return new TimeOfDay(getMillis(), getChronology());
1130    }
1131
1132    /**
1133     * Converts this object to a <code>LocalDateTime</code> with
1134     * the same datetime and chronology.
1135     *
1136     * @return a LocalDateTime with the same datetime and chronology
1137     * @since 1.3
1138     */
1139    public LocalDateTime toLocalDateTime() {
1140        return new LocalDateTime(getMillis(), getChronology());
1141    }
1142
1143    /**
1144     * Converts this object to a <code>LocalDate</code> with the
1145     * same date and chronology.
1146     *
1147     * @return a LocalDate with the same date and chronology
1148     * @since 1.3
1149     */
1150    public LocalDate toLocalDate() {
1151        return new LocalDate(getMillis(), getChronology());
1152    }
1153
1154    /**
1155     * Converts this object to a <code>LocalTime</code> with the
1156     * same time and chronology.
1157     *
1158     * @return a LocalTime with the same time and chronology
1159     * @since 1.3
1160     */
1161    public LocalTime toLocalTime() {
1162        return new LocalTime(getMillis(), getChronology());
1163    }
1164
1165    //-----------------------------------------------------------------------
1166    /**
1167     * Returns a copy of this datetime with the era field updated.
1168     * <p>
1169     * DateTime is immutable, so there are no set methods.
1170     * Instead, this method returns a new instance with the value of
1171     * era changed.
1172     *
1173     * @param era  the era to set
1174     * @return a copy of this object with the field set
1175     * @throws IllegalArgumentException if the value is invalid
1176     * @since 1.3
1177     */
1178    public DateTime withEra(int era) {
1179        return withMillis(getChronology().era().set(getMillis(), era));
1180    }
1181
1182    /**
1183     * Returns a copy of this datetime with the century of era field updated.
1184     * <p>
1185     * DateTime is immutable, so there are no set methods.
1186     * Instead, this method returns a new instance with the value of
1187     * century of era changed.
1188     *
1189     * @param centuryOfEra  the centurey of era to set
1190     * @return a copy of this object with the field set
1191     * @throws IllegalArgumentException if the value is invalid
1192     * @since 1.3
1193     */
1194    public DateTime withCenturyOfEra(int centuryOfEra) {
1195        return withMillis(getChronology().centuryOfEra().set(getMillis(), centuryOfEra));
1196    }
1197
1198    /**
1199     * Returns a copy of this datetime with the year of era field updated.
1200     * <p>
1201     * DateTime is immutable, so there are no set methods.
1202     * Instead, this method returns a new instance with the value of
1203     * year of era changed.
1204     *
1205     * @param yearOfEra  the year of era to set
1206     * @return a copy of this object with the field set
1207     * @throws IllegalArgumentException if the value is invalid
1208     * @since 1.3
1209     */
1210    public DateTime withYearOfEra(int yearOfEra) {
1211        return withMillis(getChronology().yearOfEra().set(getMillis(), yearOfEra));
1212    }
1213
1214    /**
1215     * Returns a copy of this datetime with the year of century field updated.
1216     * <p>
1217     * DateTime is immutable, so there are no set methods.
1218     * Instead, this method returns a new instance with the value of
1219     * year of century changed.
1220     *
1221     * @param yearOfCentury  the year of century to set
1222     * @return a copy of this object with the field set
1223     * @throws IllegalArgumentException if the value is invalid
1224     * @since 1.3
1225     */
1226    public DateTime withYearOfCentury(int yearOfCentury) {
1227        return withMillis(getChronology().yearOfCentury().set(getMillis(), yearOfCentury));
1228    }
1229
1230    /**
1231     * Returns a copy of this datetime with the year field updated.
1232     * <p>
1233     * DateTime is immutable, so there are no set methods.
1234     * Instead, this method returns a new instance with the value of
1235     * year changed.
1236     *
1237     * @param year  the year to set
1238     * @return a copy of this object with the field set
1239     * @throws IllegalArgumentException if the value is invalid
1240     * @since 1.3
1241     */
1242    public DateTime withYear(int year) {
1243        return withMillis(getChronology().year().set(getMillis(), year));
1244    }
1245
1246    /**
1247     * Returns a copy of this datetime with the weekyear field updated.
1248     * <p>
1249     * DateTime is immutable, so there are no set methods.
1250     * Instead, this method returns a new instance with the value of
1251     * weekyear changed.
1252     *
1253     * @param weekyear  the weekyear to set
1254     * @return a copy of this object with the field set
1255     * @throws IllegalArgumentException if the value is invalid
1256     * @since 1.3
1257     */
1258    public DateTime withWeekyear(int weekyear) {
1259        return withMillis(getChronology().weekyear().set(getMillis(), weekyear));
1260    }
1261
1262    /**
1263     * Returns a copy of this datetime with the month of year field updated.
1264     * <p>
1265     * DateTime is immutable, so there are no set methods.
1266     * Instead, this method returns a new instance with the value of
1267     * month of year changed.
1268     *
1269     * @param monthOfYear  the month of year to set
1270     * @return a copy of this object with the field set
1271     * @throws IllegalArgumentException if the value is invalid
1272     * @since 1.3
1273     */
1274    public DateTime withMonthOfYear(int monthOfYear) {
1275        return withMillis(getChronology().monthOfYear().set(getMillis(), monthOfYear));
1276    }
1277
1278    /**
1279     * Returns a copy of this datetime with the week of weekyear field updated.
1280     * <p>
1281     * DateTime is immutable, so there are no set methods.
1282     * Instead, this method returns a new instance with the value of
1283     * week of weekyear changed.
1284     *
1285     * @param weekOfWeekyear  the week of weekyear to set
1286     * @return a copy of this object with the field set
1287     * @throws IllegalArgumentException if the value is invalid
1288     * @since 1.3
1289     */
1290    public DateTime withWeekOfWeekyear(int weekOfWeekyear) {
1291        return withMillis(getChronology().weekOfWeekyear().set(getMillis(), weekOfWeekyear));
1292    }
1293
1294    /**
1295     * Returns a copy of this datetime with the day of year field updated.
1296     * <p>
1297     * DateTime is immutable, so there are no set methods.
1298     * Instead, this method returns a new instance with the value of
1299     * day of year changed.
1300     *
1301     * @param dayOfYear  the day of year to set
1302     * @return a copy of this object with the field set
1303     * @throws IllegalArgumentException if the value is invalid
1304     * @since 1.3
1305     */
1306    public DateTime withDayOfYear(int dayOfYear) {
1307        return withMillis(getChronology().dayOfYear().set(getMillis(), dayOfYear));
1308    }
1309
1310    /**
1311     * Returns a copy of this datetime with the day of month field updated.
1312     * <p>
1313     * DateTime is immutable, so there are no set methods.
1314     * Instead, this method returns a new instance with the value of
1315     * day of month changed.
1316     *
1317     * @param dayOfMonth  the day of month to set
1318     * @return a copy of this object with the field set
1319     * @throws IllegalArgumentException if the value is invalid
1320     * @since 1.3
1321     */
1322    public DateTime withDayOfMonth(int dayOfMonth) {
1323        return withMillis(getChronology().dayOfMonth().set(getMillis(), dayOfMonth));
1324    }
1325
1326    /**
1327     * Returns a copy of this datetime with the day of week field updated.
1328     * <p>
1329     * DateTime is immutable, so there are no set methods.
1330     * Instead, this method returns a new instance with the value of
1331     * day of week changed.
1332     *
1333     * @param dayOfWeek  the day of week to set
1334     * @return a copy of this object with the field set
1335     * @throws IllegalArgumentException if the value is invalid
1336     * @since 1.3
1337     */
1338    public DateTime withDayOfWeek(int dayOfWeek) {
1339        return withMillis(getChronology().dayOfWeek().set(getMillis(), dayOfWeek));
1340    }
1341
1342    //-----------------------------------------------------------------------
1343    /**
1344     * Returns a copy of this datetime with the hour of day field updated.
1345     * <p>
1346     * DateTime is immutable, so there are no set methods.
1347     * Instead, this method returns a new instance with the value of
1348     * hour of day changed.
1349     *
1350     * @param hour  the hour of day to set
1351     * @return a copy of this object with the field set
1352     * @throws IllegalArgumentException if the value is invalid
1353     * @since 1.3
1354     */
1355    public DateTime withHourOfDay(int hour) {
1356        return withMillis(getChronology().hourOfDay().set(getMillis(), hour));
1357    }
1358
1359    /**
1360     * Returns a copy of this datetime with the minute of hour updated.
1361     * <p>
1362     * DateTime is immutable, so there are no set methods.
1363     * Instead, this method returns a new instance with the value of
1364     * minute of hour changed.
1365     *
1366     * @param minute  the minute of hour to set
1367     * @return a copy of this object with the field set
1368     * @throws IllegalArgumentException if the value is invalid
1369     * @since 1.3
1370     */
1371    public DateTime withMinuteOfHour(int minute) {
1372        return withMillis(getChronology().minuteOfHour().set(getMillis(), minute));
1373    }
1374
1375    /**
1376     * Returns a copy of this datetime with the second of minute field updated.
1377     * <p>
1378     * DateTime is immutable, so there are no set methods.
1379     * Instead, this method returns a new instance with the value of
1380     * second of minute changed.
1381     *
1382     * @param second  the second of minute to set
1383     * @return a copy of this object with the field set
1384     * @throws IllegalArgumentException if the value is invalid
1385     * @since 1.3
1386     */
1387    public DateTime withSecondOfMinute(int second) {
1388        return withMillis(getChronology().secondOfMinute().set(getMillis(), second));
1389    }
1390
1391    /**
1392     * Returns a copy of this datetime with the millis of second field updated.
1393     * <p>
1394     * DateTime is immutable, so there are no set methods.
1395     * Instead, this method returns a new instance with the value of
1396     * millis of second changed.
1397     *
1398     * @param millis  the millis of second to set
1399     * @return a copy of this object with the field set
1400     * @throws IllegalArgumentException if the value is invalid
1401     * @since 1.3
1402     */
1403    public DateTime withMillisOfSecond(int millis) {
1404        return withMillis(getChronology().millisOfSecond().set(getMillis(), millis));
1405    }
1406
1407    /**
1408     * Returns a copy of this datetime with the millis of day field updated.
1409     * <p>
1410     * DateTime is immutable, so there are no set methods.
1411     * Instead, this method returns a new instance with the value of
1412     * millis of day changed.
1413     *
1414     * @param millis  the millis of day to set
1415     * @return a copy of this object with the field set
1416     * @throws IllegalArgumentException if the value is invalid
1417     * @since 1.3
1418     */
1419    public DateTime withMillisOfDay(int millis) {
1420        return withMillis(getChronology().millisOfDay().set(getMillis(), millis));
1421    }
1422
1423    // Date properties
1424    //-----------------------------------------------------------------------
1425    /**
1426     * Get the era property which provides access to advanced functionality.
1427     * 
1428     * @return the era property
1429     */
1430    public Property era() {
1431        return new Property(this, getChronology().era());
1432    }
1433
1434    /**
1435     * Get the century of era property which provides access to advanced functionality.
1436     * 
1437     * @return the year of era property
1438     */
1439    public Property centuryOfEra() {
1440        return new Property(this, getChronology().centuryOfEra());
1441    }
1442
1443    /**
1444     * Get the year of century property which provides access to advanced functionality.
1445     * 
1446     * @return the year of era property
1447     */
1448    public Property yearOfCentury() {
1449        return new Property(this, getChronology().yearOfCentury());
1450    }
1451
1452    /**
1453     * Get the year of era property which provides access to advanced functionality.
1454     * 
1455     * @return the year of era property
1456     */
1457    public Property yearOfEra() {
1458        return new Property(this, getChronology().yearOfEra());
1459    }
1460
1461    /**
1462     * Get the year property which provides access to advanced functionality.
1463     * 
1464     * @return the year property
1465     */
1466    public Property year() {
1467        return new Property(this, getChronology().year());
1468    }
1469
1470    /**
1471     * Get the year of a week based year property which provides access to advanced functionality.
1472     * 
1473     * @return the year of a week based year property
1474     */
1475    public Property weekyear() {
1476        return new Property(this, getChronology().weekyear());
1477    }
1478
1479    /**
1480     * Get the month of year property which provides access to advanced functionality.
1481     * 
1482     * @return the month of year property
1483     */
1484    public Property monthOfYear() {
1485        return new Property(this, getChronology().monthOfYear());
1486    }
1487
1488    /**
1489     * Get the week of a week based year property which provides access to advanced functionality.
1490     * 
1491     * @return the week of a week based year property
1492     */
1493    public Property weekOfWeekyear() {
1494        return new Property(this, getChronology().weekOfWeekyear());
1495    }
1496
1497    /**
1498     * Get the day of year property which provides access to advanced functionality.
1499     * 
1500     * @return the day of year property
1501     */
1502    public Property dayOfYear() {
1503        return new Property(this, getChronology().dayOfYear());
1504    }
1505
1506    /**
1507     * Get the day of month property which provides access to advanced functionality.
1508     * 
1509     * @return the day of month property
1510     */
1511    public Property dayOfMonth() {
1512        return new Property(this, getChronology().dayOfMonth());
1513    }
1514
1515    /**
1516     * Get the day of week property which provides access to advanced functionality.
1517     * 
1518     * @return the day of week property
1519     */
1520    public Property dayOfWeek() {
1521        return new Property(this, getChronology().dayOfWeek());
1522    }
1523
1524    // Time properties
1525    //-----------------------------------------------------------------------
1526    /**
1527     * Get the hour of day field property which provides access to advanced functionality.
1528     * 
1529     * @return the hour of day property
1530     */
1531    public Property hourOfDay() {
1532        return new Property(this, getChronology().hourOfDay());
1533    }
1534
1535    /**
1536     * Get the minute of day property which provides access to advanced functionality.
1537     * 
1538     * @return the minute of day property
1539     */
1540    public Property minuteOfDay() {
1541        return new Property(this, getChronology().minuteOfDay());
1542    }
1543
1544    /**
1545     * Get the minute of hour field property which provides access to advanced functionality.
1546     * 
1547     * @return the minute of hour property
1548     */
1549    public Property minuteOfHour() {
1550        return new Property(this, getChronology().minuteOfHour());
1551    }
1552
1553    /**
1554     * Get the second of day property which provides access to advanced functionality.
1555     * 
1556     * @return the second of day property
1557     */
1558    public Property secondOfDay() {
1559        return new Property(this, getChronology().secondOfDay());
1560    }
1561
1562    /**
1563     * Get the second of minute field property which provides access to advanced functionality.
1564     * 
1565     * @return the second of minute property
1566     */
1567    public Property secondOfMinute() {
1568        return new Property(this, getChronology().secondOfMinute());
1569    }
1570
1571    /**
1572     * Get the millis of day property which provides access to advanced functionality.
1573     * 
1574     * @return the millis of day property
1575     */
1576    public Property millisOfDay() {
1577        return new Property(this, getChronology().millisOfDay());
1578    }
1579
1580    /**
1581     * Get the millis of second property which provides access to advanced functionality.
1582     * 
1583     * @return the millis of second property
1584     */
1585    public Property millisOfSecond() {
1586        return new Property(this, getChronology().millisOfSecond());
1587    }
1588
1589    //-----------------------------------------------------------------------
1590    /**
1591     * DateTime.Property binds a DateTime to a DateTimeField allowing powerful
1592     * datetime functionality to be easily accessed.
1593     * <p>
1594     * The simplest use of this class is as an alternative get method, here used to
1595     * get the year '1972' (as an int) and the month 'December' (as a String).
1596     * <pre>
1597     * DateTime dt = new DateTime(1972, 12, 3, 0, 0, 0, 0);
1598     * int year = dt.year().get();
1599     * String monthStr = dt.month().getAsText();
1600     * </pre>
1601     * <p>
1602     * Methods are also provided that allow date modification. These return new instances
1603     * of DateTime - they do not modify the original. The example below yields two
1604     * independent immutable date objects 20 years apart.
1605     * <pre>
1606     * DateTime dt = new DateTime(1972, 12, 3, 0, 0, 0, 0);
1607     * DateTime dt20 = dt.year().addToCopy(20);
1608     * </pre>
1609     * Serious modification of dates (ie. more than just changing one or two fields)
1610     * should use the {@link org.joda.time.MutableDateTime MutableDateTime} class.
1611     * <p>
1612     * DateTime.Propery itself is thread-safe and immutable, as well as the
1613     * DateTime being operated on.
1614     *
1615     * @author Stephen Colebourne
1616     * @author Brian S O'Neill
1617     * @since 1.0
1618     */
1619    public static final class Property extends AbstractReadableInstantFieldProperty {
1620        
1621        /** Serialization version */
1622        private static final long serialVersionUID = -6983323811635733510L;
1623        
1624        /** The instant this property is working against */
1625        private DateTime iInstant;
1626        /** The field this property is working against */
1627        private DateTimeField iField;
1628        
1629        /**
1630         * Constructor.
1631         * 
1632         * @param instant  the instant to set
1633         * @param field  the field to use
1634         */
1635        Property(DateTime instant, DateTimeField field) {
1636            super();
1637            iInstant = instant;
1638            iField = field;
1639        }
1640        
1641        /**
1642         * Writes the property in a safe serialization format.
1643         */
1644        private void writeObject(ObjectOutputStream   oos) throws IOException   {
1645            oos.writeObject(iInstant);
1646            oos.writeObject(iField.getType());
1647        }
1648
1649        /**
1650         * Reads the property from a safe serialization format.
1651         */
1652        private void readObject(ObjectInputStream   oos) throws IOException  , ClassNotFoundException   {
1653            iInstant = (DateTime) oos.readObject();
1654            DateTimeFieldType type = (DateTimeFieldType) oos.readObject();
1655            iField = type.getField(iInstant.getChronology());
1656        }
1657
1658        //-----------------------------------------------------------------------
1659        /**
1660         * Gets the field being used.
1661         * 
1662         * @return the field
1663         */
1664        public DateTimeField getField() {
1665            return iField;
1666        }
1667        
1668        /**
1669         * Gets the milliseconds of the datetime that this property is linked to.
1670         * 
1671         * @return the milliseconds
1672         */
1673        protected long getMillis() {
1674            return iInstant.getMillis();
1675        }
1676        
1677        /**
1678         * Gets the chronology of the datetime that this property is linked to.
1679         * 
1680         * @return the chronology
1681         * @since 1.4
1682         */
1683        protected Chronology getChronology() {
1684            return iInstant.getChronology();
1685        }
1686        
1687        /**
1688         * Gets the datetime being used.
1689         * 
1690         * @return the datetime
1691         */
1692        public DateTime getDateTime() {
1693            return iInstant;
1694        }
1695        
1696        //-----------------------------------------------------------------------
1697        /**
1698         * Adds to this field in a copy of this DateTime.
1699         * <p>
1700         * The DateTime attached to this property is unchanged by this call.
1701         * This operation is faster than converting a DateTime to a MutableDateTime
1702         * and back again when setting one field. When setting multiple fields,
1703         * it is generally quicker to make the conversion to MutableDateTime.
1704         * 
1705         * @param value  the value to add to the field in the copy
1706         * @return a copy of the DateTime with the field value changed
1707         * @throws IllegalArgumentException if the value isn't valid
1708         */
1709        public DateTime addToCopy(int value) {
1710            return iInstant.withMillis(iField.add(iInstant.getMillis(), value));
1711        }
1712        
1713        /**
1714         * Adds to this field in a copy of this DateTime.
1715         * <p>
1716         * The DateTime attached to this property is unchanged by this call.
1717         * This operation is faster than converting a DateTime to a MutableDateTime
1718         * and back again when setting one field. When setting multiple fields,
1719         * it is generally quicker to make the conversion to MutableDateTime.
1720         * 
1721         * @param value  the value to add to the field in the copy
1722         * @return a copy of the DateTime with the field value changed
1723         * @throws IllegalArgumentException if the value isn't valid
1724         */
1725        public DateTime addToCopy(long value) {
1726            return iInstant.withMillis(iField.add(iInstant.getMillis(), value));
1727        }
1728        
1729        /**
1730         * Adds to this field, possibly wrapped, in a copy of this DateTime.
1731         * A wrapped operation only changes this field.
1732         * Thus 31st January addWrapField one day goes to the 1st January.
1733         * <p>
1734         * The DateTime attached to this property is unchanged by this call.
1735         * This operation is faster than converting a DateTime to a MutableDateTime
1736         * and back again when setting one field. When setting multiple fields,
1737         * it is generally quicker to make the conversion to MutableDateTime.
1738         * 
1739         * @param value  the value to add to the field in the copy
1740         * @return a copy of the DateTime with the field value changed
1741         * @throws IllegalArgumentException if the value isn't valid
1742         */
1743        public DateTime addWrapFieldToCopy(int value) {
1744            return iInstant.withMillis(iField.addWrapField(iInstant.getMillis(), value));
1745        }
1746        
1747        //-----------------------------------------------------------------------
1748        /**
1749         * Sets this field in a copy of the DateTime.
1750         * <p>
1751         * The DateTime attached to this property is unchanged by this call.
1752         * This operation is faster than converting a DateTime to a MutableDateTime
1753         * and back again when setting one field. When setting multiple fields,
1754         * it is generally quicker to make the conversion to MutableDateTime.
1755         * 
1756         * @param value  the value to set the field in the copy to
1757         * @return a copy of the DateTime with the field value changed
1758         * @throws IllegalArgumentException if the value isn't valid
1759         */
1760        public DateTime setCopy(int value) {
1761            return iInstant.withMillis(iField.set(iInstant.getMillis(), value));
1762        }
1763        
1764        /**
1765         * Sets this field in a copy of the DateTime to a parsed text value.
1766         * <p>
1767         * The DateTime attached to this property is unchanged by this call.
1768         * This operation is faster than converting a DateTime to a MutableDateTime
1769         * and back again when setting one field. When setting multiple fields,
1770         * it is generally quicker to make the conversion to MutableDateTime.
1771         * 
1772         * @param text  the text value to set
1773         * @param locale  optional locale to use for selecting a text symbol
1774         * @return a copy of the DateTime with the field value changed
1775         * @throws IllegalArgumentException if the text value isn't valid
1776         */
1777        public DateTime setCopy(String   text, Locale   locale) {
1778            return iInstant.withMillis(iField.set(iInstant.getMillis(), text, locale));
1779        }
1780        
1781        /**
1782         * Sets this field in a copy of the DateTime to a parsed text value.
1783         * <p>
1784         * The DateTime attached to this property is unchanged by this call.
1785         * This operation is faster than converting a DateTime to a MutableDateTime
1786         * and back again when setting one field. When setting multiple fields,
1787         * it is generally quicker to make the conversion to MutableDateTime.
1788         * 
1789         * @param text  the text value to set
1790         * @return a copy of the DateTime with the field value changed
1791         * @throws IllegalArgumentException if the text value isn't valid
1792         */
1793        public DateTime setCopy(String   text) {
1794            return setCopy(text, null);
1795        }
1796        
1797        //-----------------------------------------------------------------------
1798        /**
1799         * Returns a new DateTime with this field set to the maximum value
1800         * for this field.
1801         * <p>
1802         * This operation is useful for obtaining a DateTime on the last day
1803         * of the month, as month lengths vary.
1804         * <pre>
1805         * DateTime lastDayOfMonth = dt.dayOfMonth().withMaximumValue();
1806         * </pre>
1807         * <p>
1808         * The DateTime attached to this property is unchanged by this call.
1809         *
1810         * @return a copy of the DateTime with this field set to its maximum
1811         * @since 1.2
1812         */
1813        public DateTime withMaximumValue() {
1814            return setCopy(getMaximumValue());
1815        }
1816        
1817        /**
1818         * Returns a new DateTime with this field set to the minimum value
1819         * for this field.
1820         * <p>
1821         * The DateTime attached to this property is unchanged by this call.
1822         *
1823         * @return a copy of the DateTime with this field set to its minimum
1824         * @since 1.2
1825         */
1826        public DateTime withMinimumValue() {
1827            return setCopy(getMinimumValue());
1828        }
1829        
1830        //-----------------------------------------------------------------------
1831        /**
1832         * Rounds to the lowest whole unit of this field on a copy of this DateTime.
1833         *
1834         * @return a copy of the DateTime with the field value changed
1835         */
1836        public DateTime roundFloorCopy() {
1837            return iInstant.withMillis(iField.roundFloor(iInstant.getMillis()));
1838        }
1839        
1840        /**
1841         * Rounds to the highest whole unit of this field on a copy of this DateTime.
1842         *
1843         * @return a copy of the DateTime with the field value changed
1844         */
1845        public DateTime roundCeilingCopy() {
1846            return iInstant.withMillis(iField.roundCeiling(iInstant.getMillis()));
1847        }
1848        
1849        /**
1850         * Rounds to the nearest whole unit of this field on a copy of this DateTime,
1851         * favoring the floor if halfway.
1852         *
1853         * @return a copy of the DateTime with the field value changed
1854         */
1855        public DateTime roundHalfFloorCopy() {
1856            return iInstant.withMillis(iField.roundHalfFloor(iInstant.getMillis()));
1857        }
1858        
1859        /**
1860         * Rounds to the nearest whole unit of this field on a copy of this DateTime,
1861         * favoring the ceiling if halfway.
1862         *
1863         * @return a copy of the DateTime with the field value changed
1864         */
1865        public DateTime roundHalfCeilingCopy() {
1866            return iInstant.withMillis(iField.roundHalfCeiling(iInstant.getMillis()));
1867        }
1868        
1869        /**
1870         * Rounds to the nearest whole unit of this field on a copy of this
1871         * DateTime.  If halfway, the ceiling is favored over the floor only if
1872         * it makes this field's value even.
1873         *
1874         * @return a copy of the DateTime with the field value changed
1875         */
1876        public DateTime roundHalfEvenCopy() {
1877            return iInstant.withMillis(iField.roundHalfEven(iInstant.getMillis()));
1878        }
1879    }
1880
1881}
1882
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags