joda-time/joda-time/2.10 : org/joda/time/DateTime.java

DateTime
http://www.joda.org/joda-time/: Date and time library to replace JDK date handling (Joda.org)
Apache 2
/*
 *  Copyright 2001-2014 Stephen Colebourne
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */
package org.joda.time;

import java.io.IOException;
import java.io.ObjectInputStream;
import java.io.ObjectOutputStream;
import java.io.Serializable;
import java.util.Locale;

import org.joda.convert.FromString;
import org.joda.time.base.BaseDateTime;
import org.joda.time.chrono.ISOChronology;
import org.joda.time.field.AbstractReadableInstantFieldProperty;
import org.joda.time.format.DateTimeFormatter;
import org.joda.time.format.ISODateTimeFormat;

DateTime is the standard implementation of an unmodifiable datetime class.

DateTime is the most widely used implementation of ReadableInstant. As with all instants, it represents an exact point on the time-line, but limited to the precision of milliseconds. A DateTime calculates its fields with respect to a time zone. 
 Internally, the class holds two pieces of data. Firstly, it holds the datetime as milliseconds from the Java epoch of 1970-01-01T00:00:00Z. Secondly, it holds a Chronology which determines how the millisecond instant value is converted into the date time fields. The default Chronology is ISOChronology which is the agreed international standard and compatible with the modern Gregorian calendar. 

Each individual field can be queried in two ways:

getHourOfDay()
hourOfDay().get()

The second technique also provides access to other useful methods on the
field:

numeric value
text value
short text value
maximum/minimum values
add/subtract
set
rounding


DateTime is thread-safe and immutable, provided that the Chronology is as well.
All standard Chronology classes supplied are thread-safe and immutable.
Author: Stephen Colebourne, Kandarp Shah, Brian S O'Neill
See Also: MutableDateTime
Since: 1.0/**
 * DateTime is the standard implementation of an unmodifiable datetime class.
 * <p>
 * <code>DateTime</code> is the most widely used implementation of
 * {@link ReadableInstant}. As with all instants, it represents an exact
 * point on the time-line, but limited to the precision of milliseconds.
 * A <code>DateTime</code> calculates its fields with respect to a
 * {@link DateTimeZone time zone}.
 * <p>
 * Internally, the class holds two pieces of data. Firstly, it holds the
 * datetime as milliseconds from the Java epoch of 1970-01-01T00:00:00Z.
 * Secondly, it holds a {@link Chronology} which determines how the
 * millisecond instant value is converted into the date time fields.
 * The default Chronology is {@link ISOChronology} which is the agreed
 * international standard and compatible with the modern Gregorian calendar.
 * <p>
 * Each individual field can be queried in two ways:
 * <ul>
 * <li><code>getHourOfDay()</code>
 * <li><code>hourOfDay().get()</code>
 * </ul>
 * The second technique also provides access to other useful methods on the
 * field:
 * <ul>
 * <li>numeric value
 * <li>text value
 * <li>short text value
 * <li>maximum/minimum values
 * <li>add/subtract
 * <li>set
 * <li>rounding
 * </ul>
 * <p>
 * DateTime is thread-safe and immutable, provided that the Chronology is as well.
 * All standard Chronology classes supplied are thread-safe and immutable.
 *
 * @author Stephen Colebourne
 * @author Kandarp Shah
 * @author Brian S O'Neill
 * @since 1.0
 * @see MutableDateTime
 */
public final class DateTime
        extends BaseDateTime
        implements ReadableDateTime, Serializable {

    Serialization lock /** Serialization lock */
    private static final long serialVersionUID = -5171125899451703815L;

    //-----------------------------------------------------------------------
    Obtains a DateTime set to the current system millisecond time using ISOChronology in the default time zone.
Returns: the current date-time, not null
Since: 2.0/**
     * Obtains a {@code DateTime} set to the current system millisecond time
     * using <code>ISOChronology</code> in the default time zone.
     * 
     * @return the current date-time, not null
     * @since 2.0
     */
    public static DateTime now() {
        return new DateTime();
    }

    Obtains a DateTime set to the current system millisecond time using ISOChronology in the specified time zone.
Params: zone –  the time zone, not null
Returns: the current date-time, not null
Since: 2.0/**
     * Obtains a {@code DateTime} set to the current system millisecond time
     * using <code>ISOChronology</code> in the specified time zone.
     *
     * @param zone  the time zone, not null
     * @return the current date-time, not null
     * @since 2.0
     */
    public static DateTime now(DateTimeZone zone) {
        if (zone == null) {
            throw new NullPointerException("Zone must not be null");
        }
        return new DateTime(zone);
    }

    Obtains a DateTime set to the current system millisecond time using the specified chronology. 
Params: chronology –  the chronology, not null
Returns: the current date-time, not null
Since: 2.0/**
     * Obtains a {@code DateTime} set to the current system millisecond time
     * using the specified chronology.
     *
     * @param chronology  the chronology, not null
     * @return the current date-time, not null
     * @since 2.0
     */
    public static DateTime now(Chronology chronology) {
        if (chronology == null) {
            throw new NullPointerException("Chronology must not be null");
        }
        return new DateTime(chronology);
    }

    //-----------------------------------------------------------------------
    Parses a DateTime from the specified string.  This uses ISODateTimeFormat.dateTimeParser().withOffsetParsed() which is different to passing a String to the constructor. 
 Sometimes this method and new DateTime(str) return different results. This can be confusing as the difference is not visible in AbstractDateTime.toString(). 
 When passed a date-time string without an offset, such as '2010-06-30T01:20', both the constructor and this method use the default time-zone. As such, DateTime.parse("2010-06-30T01:20") and new DateTime("2010-06-30T01:20")) are equal. 
 However, when this method is passed a date-time string with an offset, the offset is directly parsed and stored. As such, DateTime.parse("2010-06-30T01:20+02:00") and new DateTime("2010-06-30T01:20+02:00")) are NOT equal. The object produced via this method has a zone of DateTimeZone.forOffsetHours(2). The object produced via the constructor has a zone of DateTimeZone.getDefault(). 
Params: str –  the string to parse, not null
Since: 2.0/**
     * Parses a {@code DateTime} from the specified string.
     * <p>
     * This uses {@link ISODateTimeFormat#dateTimeParser()}{@code .withOffsetParsed()}
     * which is different to passing a {@code String} to the constructor.
     * <p>
     * Sometimes this method and {@code new DateTime(str)} return different results.
     * This can be confusing as the difference is not visible in {@link #toString()}.
     * <p>
     * When passed a date-time string without an offset, such as '2010-06-30T01:20',
     * both the constructor and this method use the default time-zone.
     * As such, {@code DateTime.parse("2010-06-30T01:20")} and
     * {@code new DateTime("2010-06-30T01:20"))} are equal.
     * <p>
     * However, when this method is passed a date-time string with an offset,
     * the offset is directly parsed and stored.
     * As such, {@code DateTime.parse("2010-06-30T01:20+02:00")} and
     * {@code new DateTime("2010-06-30T01:20+02:00"))} are NOT equal.
     * The object produced via this method has a zone of {@code DateTimeZone.forOffsetHours(2)}.
     * The object produced via the constructor has a zone of {@code DateTimeZone.getDefault()}.
     * 
     * @param str  the string to parse, not null
     * @since 2.0
     */
    @FromString
    public static DateTime parse(String str) {
        return parse(str, ISODateTimeFormat.dateTimeParser().withOffsetParsed());
    }

    Parses a DateTime from the specified string using a formatter. 
Params: str –  the string to parse, not null
formatter –  the formatter to use, not null
Since: 2.0/**
     * Parses a {@code DateTime} from the specified string using a formatter.
     * 
     * @param str  the string to parse, not null
     * @param formatter  the formatter to use, not null
     * @since 2.0
     */
    public static DateTime parse(String str, DateTimeFormatter formatter) {
        return formatter.parseDateTime(str);
    }

    //-----------------------------------------------------------------------
    Constructs an instance set to the current system millisecond time
using ISOChronology in the default time zone.
See Also: now()/**
     * Constructs an instance set to the current system millisecond time
     * using <code>ISOChronology</code> in the default time zone.
     * 
     * @see #now()
     */
    public DateTime() {
        super();
    }

    Constructs an instance set to the current system millisecond time
using ISOChronology in the specified time zone.

If the specified time zone is null, the default zone is used.
Params: zone –  the time zone, null means default zone
See Also: now(DateTimeZone)/**
     * Constructs an instance set to the current system millisecond time
     * using <code>ISOChronology</code> in the specified time zone.
     * <p>
     * If the specified time zone is null, the default zone is used.
     *
     * @param zone  the time zone, null means default zone
     * @see #now(DateTimeZone)
     */
    public DateTime(DateTimeZone zone) {
        super(zone);
    }

    Constructs an instance set to the current system millisecond time
using the specified chronology.

If the chronology is null, ISOChronology
in the default time zone is used.
Params: chronology –  the chronology, null means ISOChronology in default zone
See Also: now(Chronology)/**
     * Constructs an instance set to the current system millisecond time
     * using the specified chronology.
     * <p>
     * If the chronology is null, <code>ISOChronology</code>
     * in the default time zone is used.
     *
     * @param chronology  the chronology, null means ISOChronology in default zone
     * @see #now(Chronology)
     */
    public DateTime(Chronology chronology) {
        super(chronology);
    }

    //-----------------------------------------------------------------------
    Constructs an instance set to the milliseconds from 1970-01-01T00:00:00Z
using ISOChronology in the default time zone.
Params: instant –  the milliseconds from 1970-01-01T00:00:00Z/**
     * Constructs an instance set to the milliseconds from 1970-01-01T00:00:00Z
     * using <code>ISOChronology</code> in the default time zone.
     *
     * @param instant  the milliseconds from 1970-01-01T00:00:00Z
     */
    public DateTime(long instant) {
        super(instant);
    }

    Constructs an instance set to the milliseconds from 1970-01-01T00:00:00Z
using ISOChronology in the specified time zone.

If the specified time zone is null, the default zone is used.
Params: instant –  the milliseconds from 1970-01-01T00:00:00Z
zone –  the time zone, null means default zone/**
     * Constructs an instance set to the milliseconds from 1970-01-01T00:00:00Z
     * using <code>ISOChronology</code> in the specified time zone.
     * <p>
     * If the specified time zone is null, the default zone is used.
     *
     * @param instant  the milliseconds from 1970-01-01T00:00:00Z
     * @param zone  the time zone, null means default zone
     */
    public DateTime(long instant, DateTimeZone zone) {
        super(instant, zone);
    }

    Constructs an instance set to the milliseconds from 1970-01-01T00:00:00Z
using the specified chronology.

If the chronology is null, ISOChronology
in the default time zone is used.
Params: instant –  the milliseconds from 1970-01-01T00:00:00Z
chronology –  the chronology, null means ISOChronology in default zone/**
     * Constructs an instance set to the milliseconds from 1970-01-01T00:00:00Z
     * using the specified chronology.
     * <p>
     * If the chronology is null, <code>ISOChronology</code>
     * in the default time zone is used.
     *
     * @param instant  the milliseconds from 1970-01-01T00:00:00Z
     * @param chronology  the chronology, null means ISOChronology in default zone
     */
    public DateTime(long instant, Chronology chronology) {
        super(instant, chronology);
    }

    //-----------------------------------------------------------------------
    Constructs an instance from an Object that represents a datetime.

If the object implies a chronology (such as GregorianCalendar does),
then that chronology will be used. Otherwise, ISO default is used.
Thus if a GregorianCalendar is passed in, the chronology used will
be GJ, but if a Date is passed in the chronology will be ISO.
 The recognised object types are defined in ConverterManager and include ReadableInstant, String, Calendar and Date. The String formats are described by ISODateTimeFormat.dateTimeParser(). 
Params: instant –  the datetime object, null means now
Throws: IllegalArgumentException – if the instant is invalid/**
     * Constructs an instance from an Object that represents a datetime.
     * <p>
     * If the object implies a chronology (such as GregorianCalendar does),
     * then that chronology will be used. Otherwise, ISO default is used.
     * Thus if a GregorianCalendar is passed in, the chronology used will
     * be GJ, but if a Date is passed in the chronology will be ISO.
     * <p>
     * The recognised object types are defined in
     * {@link org.joda.time.convert.ConverterManager ConverterManager} and
     * include ReadableInstant, String, Calendar and Date.
     * The String formats are described by {@link ISODateTimeFormat#dateTimeParser()}.
     *
     * @param instant  the datetime object, null means now
     * @throws IllegalArgumentException if the instant is invalid
     */
    public DateTime(Object instant) {
        super(instant, (Chronology) null);
    }

    Constructs an instance from an Object that represents a datetime,
forcing the time zone to that specified.

If the object implies a chronology (such as GregorianCalendar does),
then that chronology will be used, but with the time zone adjusted.
Otherwise, ISO is used in the specified time zone.
If the specified time zone is null, the default zone is used.
Thus if a GregorianCalendar is passed in, the chronology used will
be GJ, but if a Date is passed in the chronology will be ISO.
 The recognised object types are defined in ConverterManager and include ReadableInstant, String, Calendar and Date. The String formats are described by ISODateTimeFormat.dateTimeParser(). 
Params: instant –  the datetime object, null means now
zone –  the time zone, null means default time zone
Throws: IllegalArgumentException – if the instant is invalid/**
     * Constructs an instance from an Object that represents a datetime,
     * forcing the time zone to that specified.
     * <p>
     * If the object implies a chronology (such as GregorianCalendar does),
     * then that chronology will be used, but with the time zone adjusted.
     * Otherwise, ISO is used in the specified time zone.
     * If the specified time zone is null, the default zone is used.
     * Thus if a GregorianCalendar is passed in, the chronology used will
     * be GJ, but if a Date is passed in the chronology will be ISO.
     * <p>
     * The recognised object types are defined in
     * {@link org.joda.time.convert.ConverterManager ConverterManager} and
     * include ReadableInstant, String, Calendar and Date.
     * The String formats are described by {@link ISODateTimeFormat#dateTimeParser()}.
     *
     * @param instant  the datetime object, null means now
     * @param zone  the time zone, null means default time zone
     * @throws IllegalArgumentException if the instant is invalid
     */
    public DateTime(Object instant, DateTimeZone zone) {
        super(instant, zone);
    }

    Constructs an instance from an Object that represents a datetime,
using the specified chronology.

If the chronology is null, ISO in the default time zone is used.
Any chronology implied by the object (such as GregorianCalendar does)
is ignored.
 The recognised object types are defined in ConverterManager and include ReadableInstant, String, Calendar and Date. The String formats are described by ISODateTimeFormat.dateTimeParser(). 
Params: instant –  the datetime object, null means now
chronology –  the chronology, null means ISO in default zone
Throws: IllegalArgumentException – if the instant is invalid/**
     * Constructs an instance from an Object that represents a datetime,
     * using the specified chronology.
     * <p>
     * If the chronology is null, ISO in the default time zone is used.
     * Any chronology implied by the object (such as GregorianCalendar does)
     * is ignored.
     * <p>
     * The recognised object types are defined in
     * {@link org.joda.time.convert.ConverterManager ConverterManager} and
     * include ReadableInstant, String, Calendar and Date.
     * The String formats are described by {@link ISODateTimeFormat#dateTimeParser()}.
     *
     * @param instant  the datetime object, null means now
     * @param chronology  the chronology, null means ISO in default zone
     * @throws IllegalArgumentException if the instant is invalid
     */
    public DateTime(Object instant, Chronology chronology) {
        super(instant, DateTimeUtils.getChronology(chronology));
    }

    //-----------------------------------------------------------------------
    Constructs an instance from datetime field values
using ISOChronology in the default time zone.
Params: year –  the year
monthOfYear –  the month of the year, from 1 to 12
dayOfMonth –  the day of the month, from 1 to 31
hourOfDay –  the hour of the day, from 0 to 23
minuteOfHour –  the minute of the hour, from 0 to 59
Since: 2.0/**
     * Constructs an instance from datetime field values
     * using <code>ISOChronology</code> in the default time zone.
     *
     * @param year  the year
     * @param monthOfYear  the month of the year, from 1 to 12
     * @param dayOfMonth  the day of the month, from 1 to 31
     * @param hourOfDay  the hour of the day, from 0 to 23
     * @param minuteOfHour  the minute of the hour, from 0 to 59
     * @since 2.0
     */
    public DateTime(
            int year,
            int monthOfYear,
            int dayOfMonth,
            int hourOfDay,
            int minuteOfHour) {
        super(year, monthOfYear, dayOfMonth, hourOfDay, minuteOfHour, 0, 0);
    }

    Constructs an instance from datetime field values
using ISOChronology in the specified time zone.

If the specified time zone is null, the default zone is used.
Params: year –  the year
monthOfYear –  the month of the year, from 1 to 12
dayOfMonth –  the day of the month, from 1 to 31
hourOfDay –  the hour of the day, from 0 to 23
minuteOfHour –  the minute of the hour, from 0 to 59
zone –  the time zone, null means default time zone
Since: 2.0/**
     * Constructs an instance from datetime field values
     * using <code>ISOChronology</code> in the specified time zone.
     * <p>
     * If the specified time zone is null, the default zone is used.
     *
     * @param year  the year
     * @param monthOfYear  the month of the year, from 1 to 12
     * @param dayOfMonth  the day of the month, from 1 to 31
     * @param hourOfDay  the hour of the day, from 0 to 23
     * @param minuteOfHour  the minute of the hour, from 0 to 59
     * @param zone  the time zone, null means default time zone
     * @since 2.0
     */
    public DateTime(
            int year,
            int monthOfYear,
            int dayOfMonth,
            int hourOfDay,
            int minuteOfHour,
            DateTimeZone zone) {
        super(year, monthOfYear, dayOfMonth,
              hourOfDay, minuteOfHour, 0, 0, zone);
    }

    Constructs an instance from datetime field values
using the specified chronology.

If the chronology is null, ISOChronology
in the default time zone is used.
Params: year –  the year, valid values defined by the chronology
monthOfYear –  the month of the year, valid values defined by the chronology
dayOfMonth –  the day of the month, valid values defined by the chronology
hourOfDay –  the hour of the day, valid values defined by the chronology
minuteOfHour –  the minute of the hour, valid values defined by the chronology
chronology –  the chronology, null means ISOChronology in default zone
Since: 2.0/**
     * Constructs an instance from datetime field values
     * using the specified chronology.
     * <p>
     * If the chronology is null, <code>ISOChronology</code>
     * in the default time zone is used.
     *
     * @param year  the year, valid values defined by the chronology
     * @param monthOfYear  the month of the year, valid values defined by the chronology
     * @param dayOfMonth  the day of the month, valid values defined by the chronology
     * @param hourOfDay  the hour of the day, valid values defined by the chronology
     * @param minuteOfHour  the minute of the hour, valid values defined by the chronology
     * @param chronology  the chronology, null means ISOChronology in default zone
     * @since 2.0
     */
    public DateTime(
            int year,
            int monthOfYear,
            int dayOfMonth,
            int hourOfDay,
            int minuteOfHour,
            Chronology chronology) {
        super(year, monthOfYear, dayOfMonth,
              hourOfDay, minuteOfHour, 0, 0, chronology);
    }

    //-----------------------------------------------------------------------
    Constructs an instance from datetime field values
using ISOChronology in the default time zone.
Params: year –  the year
monthOfYear –  the month of the year, from 1 to 12
dayOfMonth –  the day of the month, from 1 to 31
hourOfDay –  the hour of the day, from 0 to 23
minuteOfHour –  the minute of the hour, from 0 to 59
secondOfMinute –  the second of the minute, from 0 to 59
Since: 2.0/**
     * Constructs an instance from datetime field values
     * using <code>ISOChronology</code> in the default time zone.
     *
     * @param year  the year
     * @param monthOfYear  the month of the year, from 1 to 12
     * @param dayOfMonth  the day of the month, from 1 to 31
     * @param hourOfDay  the hour of the day, from 0 to 23
     * @param minuteOfHour  the minute of the hour, from 0 to 59
     * @param secondOfMinute  the second of the minute, from 0 to 59
     * @since 2.0
     */
    public DateTime(
            int year,
            int monthOfYear,
            int dayOfMonth,
            int hourOfDay,
            int minuteOfHour,
            int secondOfMinute) {
        super(year, monthOfYear, dayOfMonth, hourOfDay, minuteOfHour, secondOfMinute, 0);
    }

    Constructs an instance from datetime field values
using ISOChronology in the specified time zone.

If the specified time zone is null, the default zone is used.
Params: year –  the year
monthOfYear –  the month of the year, from 1 to 12
dayOfMonth –  the day of the month, from 1 to 31
hourOfDay –  the hour of the day, from 0 to 23
minuteOfHour –  the minute of the hour, from 0 to 59
secondOfMinute –  the second of the minute, from 0 to 59
zone –  the time zone, null means default time zone
Since: 2.0/**
     * Constructs an instance from datetime field values
     * using <code>ISOChronology</code> in the specified time zone.
     * <p>
     * If the specified time zone is null, the default zone is used.
     *
     * @param year  the year
     * @param monthOfYear  the month of the year, from 1 to 12
     * @param dayOfMonth  the day of the month, from 1 to 31
     * @param hourOfDay  the hour of the day, from 0 to 23
     * @param minuteOfHour  the minute of the hour, from 0 to 59
     * @param secondOfMinute  the second of the minute, from 0 to 59
     * @param zone  the time zone, null means default time zone
     * @since 2.0
     */
    public DateTime(
            int year,
            int monthOfYear,
            int dayOfMonth,
            int hourOfDay,
            int minuteOfHour,
            int secondOfMinute,
            DateTimeZone zone) {
        super(year, monthOfYear, dayOfMonth,
              hourOfDay, minuteOfHour, secondOfMinute, 0, zone);
    }

    Constructs an instance from datetime field values
using the specified chronology.

If the chronology is null, ISOChronology
in the default time zone is used.
Params: year –  the year, valid values defined by the chronology
monthOfYear –  the month of the year, valid values defined by the chronology
dayOfMonth –  the day of the month, valid values defined by the chronology
hourOfDay –  the hour of the day, valid values defined by the chronology
minuteOfHour –  the minute of the hour, valid values defined by the chronology
secondOfMinute –  the second of the minute, valid values defined by the chronology
chronology –  the chronology, null means ISOChronology in default zone
Since: 2.0/**
     * Constructs an instance from datetime field values
     * using the specified chronology.
     * <p>
     * If the chronology is null, <code>ISOChronology</code>
     * in the default time zone is used.
     *
     * @param year  the year, valid values defined by the chronology
     * @param monthOfYear  the month of the year, valid values defined by the chronology
     * @param dayOfMonth  the day of the month, valid values defined by the chronology
     * @param hourOfDay  the hour of the day, valid values defined by the chronology
     * @param minuteOfHour  the minute of the hour, valid values defined by the chronology
     * @param secondOfMinute  the second of the minute, valid values defined by the chronology
     * @param chronology  the chronology, null means ISOChronology in default zone
     * @since 2.0
     */
    public DateTime(
            int year,
            int monthOfYear,
            int dayOfMonth,
            int hourOfDay,
            int minuteOfHour,
            int secondOfMinute,
            Chronology chronology) {
        super(year, monthOfYear, dayOfMonth,
              hourOfDay, minuteOfHour, secondOfMinute, 0, chronology);
    }

    //-----------------------------------------------------------------------
    Constructs an instance from datetime field values
using ISOChronology in the default time zone.
Params: year –  the year
monthOfYear –  the month of the year, from 1 to 12
dayOfMonth –  the day of the month, from 1 to 31
hourOfDay –  the hour of the day, from 0 to 23
minuteOfHour –  the minute of the hour, from 0 to 59
secondOfMinute –  the second of the minute, from 0 to 59
millisOfSecond –  the millisecond of the second, from 0 to 999/**
     * Constructs an instance from datetime field values
     * using <code>ISOChronology</code> in the default time zone.
     *
     * @param year  the year
     * @param monthOfYear  the month of the year, from 1 to 12
     * @param dayOfMonth  the day of the month, from 1 to 31
     * @param hourOfDay  the hour of the day, from 0 to 23
     * @param minuteOfHour  the minute of the hour, from 0 to 59
     * @param secondOfMinute  the second of the minute, from 0 to 59
     * @param millisOfSecond  the millisecond of the second, from 0 to 999
     */
    public DateTime(
            int year,
            int monthOfYear,
            int dayOfMonth,
            int hourOfDay,
            int minuteOfHour,
            int secondOfMinute,
            int millisOfSecond) {
        super(year, monthOfYear, dayOfMonth, hourOfDay, minuteOfHour, secondOfMinute, millisOfSecond);
    }

    Constructs an instance from datetime field values
using ISOChronology in the specified time zone.

If the specified time zone is null, the default zone is used.
Params: year –  the year
monthOfYear –  the month of the year, from 1 to 12
dayOfMonth –  the day of the month, from 1 to 31
hourOfDay –  the hour of the day, from 0 to 23
minuteOfHour –  the minute of the hour, from 0 to 59
secondOfMinute –  the second of the minute, from 0 to 59
millisOfSecond –  the millisecond of the second, from 0 to 999
zone –  the time zone, null means default time zone/**
     * Constructs an instance from datetime field values
     * using <code>ISOChronology</code> in the specified time zone.
     * <p>
     * If the specified time zone is null, the default zone is used.
     *
     * @param year  the year
     * @param monthOfYear  the month of the year, from 1 to 12
     * @param dayOfMonth  the day of the month, from 1 to 31
     * @param hourOfDay  the hour of the day, from 0 to 23
     * @param minuteOfHour  the minute of the hour, from 0 to 59
     * @param secondOfMinute  the second of the minute, from 0 to 59
     * @param millisOfSecond  the millisecond of the second, from 0 to 999
     * @param zone  the time zone, null means default time zone
     */
    public DateTime(
            int year,
            int monthOfYear,
            int dayOfMonth,
            int hourOfDay,
            int minuteOfHour,
            int secondOfMinute,
            int millisOfSecond,
            DateTimeZone zone) {
        super(year, monthOfYear, dayOfMonth,
              hourOfDay, minuteOfHour, secondOfMinute, millisOfSecond, zone);
    }

    Constructs an instance from datetime field values
using the specified chronology.

If the chronology is null, ISOChronology
in the default time zone is used.
Params: year –  the year, valid values defined by the chronology
monthOfYear –  the month of the year, valid values defined by the chronology
dayOfMonth –  the day of the month, valid values defined by the chronology
hourOfDay –  the hour of the day, valid values defined by the chronology
minuteOfHour –  the minute of the hour, valid values defined by the chronology
secondOfMinute –  the second of the minute, valid values defined by the chronology
millisOfSecond –  the millisecond of the second, valid values defined by the chronology
chronology –  the chronology, null means ISOChronology in default zone/**
     * Constructs an instance from datetime field values
     * using the specified chronology.
     * <p>
     * If the chronology is null, <code>ISOChronology</code>
     * in the default time zone is used.
     *
     * @param year  the year, valid values defined by the chronology
     * @param monthOfYear  the month of the year, valid values defined by the chronology
     * @param dayOfMonth  the day of the month, valid values defined by the chronology
     * @param hourOfDay  the hour of the day, valid values defined by the chronology
     * @param minuteOfHour  the minute of the hour, valid values defined by the chronology
     * @param secondOfMinute  the second of the minute, valid values defined by the chronology
     * @param millisOfSecond  the millisecond of the second, valid values defined by the chronology
     * @param chronology  the chronology, null means ISOChronology in default zone
     */
    public DateTime(
            int year,
            int monthOfYear,
            int dayOfMonth,
            int hourOfDay,
            int minuteOfHour,
            int secondOfMinute,
            int millisOfSecond,
            Chronology chronology) {
        super(year, monthOfYear, dayOfMonth,
              hourOfDay, minuteOfHour, secondOfMinute, millisOfSecond, chronology);
    }

    //-----------------------------------------------------------------------
    Get this object as a DateTime by returning this.
Returns: this/**
     * Get this object as a DateTime by returning <code>this</code>.
     * 
     * @return <code>this</code>
     */
    public DateTime toDateTime() {
        return this;
    }

    Get this object as a DateTime using ISOChronology in the default zone,
returning this if possible.
Returns: a DateTime using the same millis/**
     * Get this object as a DateTime using ISOChronology in the default zone,
     * returning <code>this</code> if possible.
     * 
     * @return a DateTime using the same millis
     */
    public DateTime toDateTimeISO() {
        if (getChronology() == ISOChronology.getInstance()) {
            return this;
        }
        return super.toDateTimeISO();
    }

    Get this object as a DateTime, returning this if possible.
Params: zone – time zone to apply, or default if null
Returns: a DateTime using the same millis/**
     * Get this object as a DateTime, returning <code>this</code> if possible.
     * 
     * @param zone time zone to apply, or default if null
     * @return a DateTime using the same millis
     */
    public DateTime toDateTime(DateTimeZone zone) {
        zone = DateTimeUtils.getZone(zone);
        if (getZone() == zone) {
            return this;
        }
        return super.toDateTime(zone);
    }

    Get this object as a DateTime, returning this if possible.
Params: chronology – chronology to apply, or ISOChronology if null
Returns: a DateTime using the same millis/**
     * Get this object as a DateTime, returning <code>this</code> if possible.
     * 
     * @param chronology chronology to apply, or ISOChronology if null
     * @return a DateTime using the same millis
     */
    public DateTime toDateTime(Chronology chronology) {
        chronology = DateTimeUtils.getChronology(chronology);
        if (getChronology() == chronology) {
            return this;
        }
        return super.toDateTime(chronology);
    }

    //-----------------------------------------------------------------------
    Returns a copy of this datetime with different millis.

The returned object will be either be a new instance or this.
Only the millis will change, the chronology and time zone are kept.
Params: newMillis –  the new millis, from 1970-01-01T00:00:00Z
Returns: a copy of this datetime with different millis/**
     * Returns a copy of this datetime with different millis.
     * <p>
     * The returned object will be either be a new instance or <code>this</code>.
     * Only the millis will change, the chronology and time zone are kept.
     *
     * @param newMillis  the new millis, from 1970-01-01T00:00:00Z
     * @return a copy of this datetime with different millis
     */
    public DateTime withMillis(long newMillis) {
        return (newMillis == getMillis() ? this : new DateTime(newMillis, getChronology()));
    }

    Returns a copy of this datetime with a different chronology.

The returned object will be either be a new instance or this.
Only the chronology will change, the millis are kept.
Params: newChronology –  the new chronology, null means ISO default
Returns: a copy of this datetime with a different chronology/**
     * Returns a copy of this datetime with a different chronology.
     * <p>
     * The returned object will be either be a new instance or <code>this</code>.
     * Only the chronology will change, the millis are kept.
     *
     * @param newChronology  the new chronology, null means ISO default
     * @return a copy of this datetime with a different chronology
     */
    public DateTime withChronology(Chronology newChronology) {
        newChronology = DateTimeUtils.getChronology(newChronology);
        return (newChronology == getChronology() ? this : new DateTime(getMillis(), newChronology));
    }

    //-----------------------------------------------------------------------
    Returns a copy of this datetime with a different time zone, preserving the
millisecond instant.

This method is useful for finding the local time in another timezone.
For example, if this instant holds 12:30 in Europe/London, the result
from this method with Europe/Paris would be 13:30.

The returned object will be a new instance of the same implementation type.
This method changes the time zone, and does not change the
millisecond instant, with the effect that the field values usually change.
The returned object will be either be a new instance or this.
Params: newZone –  the new time zone
See Also: withZoneRetainFields
Returns: a copy of this datetime with a different time zone/**
     * Returns a copy of this datetime with a different time zone, preserving the
     * millisecond instant.
     * <p>
     * This method is useful for finding the local time in another timezone.
     * For example, if this instant holds 12:30 in Europe/London, the result
     * from this method with Europe/Paris would be 13:30.
     * <p>
     * The returned object will be a new instance of the same implementation type.
     * This method changes the time zone, and does not change the
     * millisecond instant, with the effect that the field values usually change.
     * The returned object will be either be a new instance or <code>this</code>.
     *
     * @param newZone  the new time zone
     * @return a copy of this datetime with a different time zone
     * @see #withZoneRetainFields
     */
    public DateTime withZone(DateTimeZone newZone) {
        return withChronology(getChronology().withZone(newZone));
    }

    Returns a copy of this datetime with a different time zone, preserving the
field values.

This method is useful for finding the millisecond time in another timezone.
For example, if this instant holds 12:30 in Europe/London (ie. 12:30Z),
the result from this method with Europe/Paris would be 12:30 (ie. 11:30Z).

The returned object will be a new instance of the same implementation type.
This method changes the time zone and the millisecond instant to keep
the field values the same.
The returned object will be either be a new instance or this.
Params: newZone –  the new time zone, null means default
See Also: withZone
Returns: a copy of this datetime with a different time zone/**
     * Returns a copy of this datetime with a different time zone, preserving the
     * field values.
     * <p>
     * This method is useful for finding the millisecond time in another timezone.
     * For example, if this instant holds 12:30 in Europe/London (ie. 12:30Z),
     * the result from this method with Europe/Paris would be 12:30 (ie. 11:30Z).
     * <p>
     * The returned object will be a new instance of the same implementation type.
     * This method changes the time zone and the millisecond instant to keep
     * the field values the same.
     * The returned object will be either be a new instance or <code>this</code>.
     *
     * @param newZone  the new time zone, null means default
     * @return a copy of this datetime with a different time zone
     * @see #withZone
     */
    public DateTime withZoneRetainFields(DateTimeZone newZone) {
        newZone = DateTimeUtils.getZone(newZone);
        DateTimeZone originalZone = DateTimeUtils.getZone(getZone());
        if (newZone == originalZone) {
            return this;
        }
        
        long millis = originalZone.getMillisKeepLocal(newZone, getMillis());
        return new DateTime(millis, getChronology().withZone(newZone));
    }

    Returns a copy of this ZonedDateTime changing the zone offset to the earlier
of the two valid offsets at a local time-line overlap.

This method only has any effect when the local time-line overlaps, such as at
an autumn daylight savings cutover. In this scenario, there are two valid offsets
for the local date-time. Calling this method will return a date-time with the
earlier of the two selected.

If this method is called when it is not an overlap, this is returned.

This instance is immutable and unaffected by this method call.
Returns: a copy of this datetime with the earliest valid offset for the local datetime/**
     * Returns a copy of this ZonedDateTime changing the zone offset to the earlier
     * of the two valid offsets at a local time-line overlap.
     * <p>
     * This method only has any effect when the local time-line overlaps, such as at
     * an autumn daylight savings cutover. In this scenario, there are two valid offsets
     * for the local date-time. Calling this method will return a date-time with the
     * earlier of the two selected.
     * <p>
     * If this method is called when it is not an overlap, this is returned.
     * <p>
     * This instance is immutable and unaffected by this method call.
     *
     * @return a copy of this datetime with the earliest valid offset for the local datetime
     */
    public DateTime withEarlierOffsetAtOverlap() {
        long newMillis = getZone().adjustOffset(getMillis(), false);
        return withMillis(newMillis);
    }

    Returns a copy of this ZonedDateTime changing the zone offset to the later
of the two valid offsets at a local time-line overlap.

This method only has any effect when the local time-line overlaps, such as at
an autumn daylight savings cutover. In this scenario, there are two valid offsets
for the local date-time. Calling this method will return a date-time with the
later of the two selected.

If this method is called when it is not an overlap, this is returned.

This instance is immutable and unaffected by this method call.
Returns: a copy of this datetime with the latest valid offset for the local datetime/**
     * Returns a copy of this ZonedDateTime changing the zone offset to the later
     * of the two valid offsets at a local time-line overlap.
     * <p>
     * This method only has any effect when the local time-line overlaps, such as at
     * an autumn daylight savings cutover. In this scenario, there are two valid offsets
     * for the local date-time. Calling this method will return a date-time with the
     * later of the two selected.
     * <p>
     * If this method is called when it is not an overlap, this is returned.
     * <p>
     * This instance is immutable and unaffected by this method call.
     *
     * @return a copy of this datetime with the latest valid offset for the local datetime
     */
    public DateTime withLaterOffsetAtOverlap() {
        long newMillis = getZone().adjustOffset(getMillis(), true);
        return withMillis(newMillis);
    }

    //-----------------------------------------------------------------------
    Returns a copy of this datetime with the specified date, retaining the time fields.

If the date is already the date passed in, then this is returned.

To set a single field use the properties, for example:
DateTime set = monthOfYear().setCopy(6);


If the time is invalid on the new date due to the time-zone, the time will be adjusted.

This instance is immutable and unaffected by this method call.
Params: year –  the new year value
monthOfYear –  the new monthOfYear value
dayOfMonth –  the new dayOfMonth value
Throws: IllegalArgumentException – if any value if invalid
Returns: a copy of this datetime with a different date/**
     * Returns a copy of this datetime with the specified date, retaining the time fields.
     * <p>
     * If the date is already the date passed in, then <code>this</code> is returned.
     * <p>
     * To set a single field use the properties, for example:
     * <pre>
     * DateTime set = monthOfYear().setCopy(6);
     * </pre>
     * <p>
     * If the time is invalid on the new date due to the time-zone, the time will be adjusted.
     * <p>
     * This instance is immutable and unaffected by this method call.
     *
     * @param year  the new year value
     * @param monthOfYear  the new monthOfYear value
     * @param dayOfMonth  the new dayOfMonth value
     * @return a copy of this datetime with a different date
     * @throws IllegalArgumentException if any value if invalid
     */
    public DateTime withDate(int year, int monthOfYear, int dayOfMonth) {
        Chronology chrono = getChronology();
        long localInstant = chrono.withUTC().getDateTimeMillis(year, monthOfYear, dayOfMonth, getMillisOfDay());
        return withMillis(chrono.getZone().convertLocalToUTC(localInstant, false, getMillis()));
    }

    Returns a copy of this datetime with the specified date, retaining the time fields.

If the time is invalid on the new date due to the time-zone, the time will be adjusted.

This instance is immutable and unaffected by this method call.
Params: date –  the local date
Throws: IllegalArgumentException – if the time-of-day is invalid for the date
NullPointerException – if the date is null
Returns: a copy of this datetime with a different date/**
     * Returns a copy of this datetime with the specified date, retaining the time fields.
     * <p>
     * If the time is invalid on the new date due to the time-zone, the time will be adjusted.
     * <p>
     * This instance is immutable and unaffected by this method call.
     *
     * @param date  the local date
     * @return a copy of this datetime with a different date
     * @throws IllegalArgumentException if the time-of-day is invalid for the date
     * @throws NullPointerException if the date is null
     */
    public DateTime withDate(LocalDate date) {
        return withDate(
            date.getYear(), date.getMonthOfYear(), date.getDayOfMonth());
    }

    Returns a copy of this datetime with the specified time, retaining the date fields.

If the time is already the time passed in, then this is returned.

To set a single field use the properties, for example:
DateTime set = dt.hourOfDay().setCopy(6);


If the new time is invalid due to the time-zone, the time will be adjusted.

This instance is immutable and unaffected by this method call.
Params: hourOfDay –  the hour of the day
minuteOfHour –  the minute of the hour
secondOfMinute –  the second of the minute
millisOfSecond –  the millisecond of the second
Throws: IllegalArgumentException – if any value if invalid
Returns: a copy of this datetime with a different time/**
     * Returns a copy of this datetime with the specified time, retaining the date fields.
     * <p>
     * If the time is already the time passed in, then <code>this</code> is returned.
     * <p>
     * To set a single field use the properties, for example:
     * <pre>
     * DateTime set = dt.hourOfDay().setCopy(6);
     * </pre>
     * <p>
     * If the new time is invalid due to the time-zone, the time will be adjusted.
     * <p>
     * This instance is immutable and unaffected by this method call.
     *
     * @param hourOfDay  the hour of the day
     * @param minuteOfHour  the minute of the hour
     * @param secondOfMinute  the second of the minute
     * @param millisOfSecond  the millisecond of the second
     * @return a copy of this datetime with a different time
     * @throws IllegalArgumentException if any value if invalid
     */
    public DateTime withTime(int hourOfDay, int minuteOfHour, int secondOfMinute, int millisOfSecond) {
        Chronology chrono = getChronology();
        long localInstant = chrono.withUTC().getDateTimeMillis(
            getYear(), getMonthOfYear(), getDayOfMonth(), hourOfDay, minuteOfHour, secondOfMinute, millisOfSecond);
        return withMillis(chrono.getZone().convertLocalToUTC(localInstant, false, getMillis()));
    }

    Returns a copy of this datetime with the specified time, retaining the date fields.

If the new time is invalid due to the time-zone, the time will be adjusted.

This instance is immutable and unaffected by this method call.
Params: time –  the local time
Throws: IllegalArgumentException – if the time-of-day is invalid for the date
NullPointerException – if the time is null
Returns: a copy of this datetime with a different time/**
     * Returns a copy of this datetime with the specified time, retaining the date fields.
     * <p>
     * If the new time is invalid due to the time-zone, the time will be adjusted.
     * <p>
     * This instance is immutable and unaffected by this method call.
     *
     * @param time  the local time
     * @return a copy of this datetime with a different time
     * @throws IllegalArgumentException if the time-of-day is invalid for the date
     * @throws NullPointerException if the time is null
     */
    public DateTime withTime(LocalTime time) {
        return withTime(
            time.getHourOfDay(), time.getMinuteOfHour(), time.getSecondOfMinute(), time.getMillisOfSecond());
    }

    Returns a copy of this datetime with the time set to the start of the day.

The time will normally be midnight, as that is the earliest time on
any given day. However, in some time zones when Daylight Savings Time
starts, there is no midnight because time jumps from 11:59 to 01:00.
This method handles that situation by returning 01:00 on that date.

This instance is immutable and unaffected by this method call.
Returns: a copy of this datetime with the time set to the start of the day, not null/**
     * Returns a copy of this datetime with the time set to the start of the day.
     * <p>
     * The time will normally be midnight, as that is the earliest time on
     * any given day. However, in some time zones when Daylight Savings Time
     * starts, there is no midnight because time jumps from 11:59 to 01:00.
     * This method handles that situation by returning 01:00 on that date.
     * <p>
     * This instance is immutable and unaffected by this method call.
     *
     * @return a copy of this datetime with the time set to the start of the day, not null
     */
    public DateTime withTimeAtStartOfDay() {
        return toLocalDate().toDateTimeAtStartOfDay(getZone());
    }

    //-----------------------------------------------------------------------
    Returns a copy of this datetime with the partial set of fields replacing those
from this instance.

For example, if the partial is a TimeOfDay then the time fields
would be changed in the returned instance.
If the partial is null, then this is returned.
Params: partial –  the partial set of fields to apply to this datetime, null ignored
Throws: IllegalArgumentException – if any value is invalid
Returns: a copy of this datetime with a different set of fields/**
     * Returns a copy of this datetime with the partial set of fields replacing those
     * from this instance.
     * <p>
     * For example, if the partial is a <code>TimeOfDay</code> then the time fields
     * would be changed in the returned instance.
     * If the partial is null, then <code>this</code> is returned.
     *
     * @param partial  the partial set of fields to apply to this datetime, null ignored
     * @return a copy of this datetime with a different set of fields
     * @throws IllegalArgumentException if any value is invalid
     */
    public DateTime withFields(ReadablePartial partial) {
        if (partial == null) {
            return this;
        }
        return withMillis(getChronology().set(partial, getMillis()));
    }

    Returns a copy of this datetime with the specified field set to a new value.

For example, if the field type is hourOfDay then the hour of day
field would be changed in the returned instance.
If the field type is null, then this is returned.

These three lines are equivalent:
DateTime updated = dt.withField(DateTimeFieldType.dayOfMonth(), 6);
DateTime updated = dt.dayOfMonth().setCopy(6);
DateTime updated = dt.property(DateTimeFieldType.dayOfMonth()).setCopy(6);

Params: fieldType –  the field type to set, not null
value –  the value to set
Throws: IllegalArgumentException – if the value is null or invalid
Returns: a copy of this datetime with the field set/**
     * Returns a copy of this datetime with the specified field set to a new value.
     * <p>
     * For example, if the field type is <code>hourOfDay</code> then the hour of day
     * field would be changed in the returned instance.
     * If the field type is null, then <code>this</code> is returned.
     * <p>
     * These three lines are equivalent:
     * <pre>
     * DateTime updated = dt.withField(DateTimeFieldType.dayOfMonth(), 6);
     * DateTime updated = dt.dayOfMonth().setCopy(6);
     * DateTime updated = dt.property(DateTimeFieldType.dayOfMonth()).setCopy(6);
     * </pre>
     *
     * @param fieldType  the field type to set, not null
     * @param value  the value to set
     * @return a copy of this datetime with the field set
     * @throws IllegalArgumentException if the value is null or invalid
     */
    public DateTime withField(DateTimeFieldType fieldType, int value) {
        if (fieldType == null) {
            throw new IllegalArgumentException("Field must not be null");
        }
        long instant = fieldType.getField(getChronology()).set(getMillis(), value);
        return withMillis(instant);
    }

    Returns a copy of this datetime with the value of the specified field increased.

If the addition is zero or the field is null, then this is returned.

These three lines are equivalent:
DateTime added = dt.withFieldAdded(DurationFieldType.years(), 6);
DateTime added = dt.plusYears(6);
DateTime added = dt.plus(Period.years(6));

Params: fieldType –  the field type to add to, not null
amount –  the amount to add
Throws: IllegalArgumentException – if the value is null or invalid
ArithmeticException – if the new datetime exceeds the capacity of a long
Returns: a copy of this datetime with the field updated/**
     * Returns a copy of this datetime with the value of the specified field increased.
     * <p>
     * If the addition is zero or the field is null, then <code>this</code> is returned.
     * <p>
     * These three lines are equivalent:
     * <pre>
     * DateTime added = dt.withFieldAdded(DurationFieldType.years(), 6);
     * DateTime added = dt.plusYears(6);
     * DateTime added = dt.plus(Period.years(6));
     * </pre>
     * 
     * @param fieldType  the field type to add to, not null
     * @param amount  the amount to add
     * @return a copy of this datetime with the field updated
     * @throws IllegalArgumentException if the value is null or invalid
     * @throws ArithmeticException if the new datetime exceeds the capacity of a long
     */
    public DateTime withFieldAdded(DurationFieldType fieldType, int amount) {
        if (fieldType == null) {
            throw new IllegalArgumentException("Field must not be null");
        }
        if (amount == 0) {
            return this;
        }
        long instant = fieldType.getField(getChronology()).add(getMillis(), amount);
        return withMillis(instant);
    }

    //-----------------------------------------------------------------------
    Returns a copy of this datetime with the specified duration added.

If the addition is zero, then this is returned.
Params: durationToAdd –  the duration to add to this one
scalar –  the amount of times to add, such as -1 to subtract once
Throws: ArithmeticException – if the new datetime exceeds the capacity of a long
Returns: a copy of this datetime with the duration added/**
     * Returns a copy of this datetime with the specified duration added.
     * <p>
     * If the addition is zero, then <code>this</code> is returned.
     * 
     * @param durationToAdd  the duration to add to this one
     * @param scalar  the amount of times to add, such as -1 to subtract once
     * @return a copy of this datetime with the duration added
     * @throws ArithmeticException if the new datetime exceeds the capacity of a long
     */
    public DateTime withDurationAdded(long durationToAdd, int scalar) {
        if (durationToAdd == 0 || scalar == 0) {
            return this;
        }
        long instant = getChronology().add(getMillis(), durationToAdd, scalar);
        return withMillis(instant);
    }

    Returns a copy of this datetime with the specified duration added.

If the addition is zero, then this is returned.
Params: durationToAdd –  the duration to add to this one, null means zero
scalar –  the amount of times to add, such as -1 to subtract once
Throws: ArithmeticException – if the new datetime exceeds the capacity of a long
Returns: a copy of this datetime with the duration added/**
     * Returns a copy of this datetime with the specified duration added.
     * <p>
     * If the addition is zero, then <code>this</code> is returned.
     * 
     * @param durationToAdd  the duration to add to this one, null means zero
     * @param scalar  the amount of times to add, such as -1 to subtract once
     * @return a copy of this datetime with the duration added
     * @throws ArithmeticException if the new datetime exceeds the capacity of a long
     */
    public DateTime withDurationAdded(ReadableDuration durationToAdd, int scalar) {
        if (durationToAdd == null || scalar == 0) {
            return this;
        }
        return withDurationAdded(durationToAdd.getMillis(), scalar);
    }

    Returns a copy of this datetime with the specified period added.

If the addition is zero, then this is returned.
 This method is typically used to add multiple copies of complex period instances. Adding one field is best achieved using methods like withFieldAdded(DurationFieldType, int) or plusYears(int). 
Params: period –  the period to add to this one, null means zero
scalar –  the amount of times to add, such as -1 to subtract once
Throws: ArithmeticException – if the new datetime exceeds the capacity of a long
Returns: a copy of this datetime with the period added/**
     * Returns a copy of this datetime with the specified period added.
     * <p>
     * If the addition is zero, then <code>this</code> is returned.
     * <p>
     * This method is typically used to add multiple copies of complex
     * period instances. Adding one field is best achieved using methods
     * like {@link #withFieldAdded(DurationFieldType, int)}
     * or {@link #plusYears(int)}.
     * 
     * @param period  the period to add to this one, null means zero
     * @param scalar  the amount of times to add, such as -1 to subtract once
     * @return a copy of this datetime with the period added
     * @throws ArithmeticException if the new datetime exceeds the capacity of a long
     */
    public DateTime withPeriodAdded(ReadablePeriod period, int scalar) {
        if (period == null || scalar == 0) {
            return this;
        }
        long instant = getChronology().add(period, getMillis(), scalar);
        return withMillis(instant);
    }

    //-----------------------------------------------------------------------
    Returns a copy of this datetime with the specified duration added.

If the amount is zero or null, then this is returned.
This datetime instance is immutable and unaffected by this method call.
Params: duration –  the duration, in millis, to add to this one
Throws: ArithmeticException – if the new datetime exceeds the capacity of a long
Returns: a copy of this datetime with the duration added/**
     * Returns a copy of this datetime with the specified duration added.
     * <p>
     * If the amount is zero or null, then <code>this</code> is returned.
     * This datetime instance is immutable and unaffected by this method call.
     * 
     * @param duration  the duration, in millis, to add to this one
     * @return a copy of this datetime with the duration added
     * @throws ArithmeticException if the new datetime exceeds the capacity of a long
     */
    public DateTime plus(long duration) {
        return withDurationAdded(duration, 1);
    }

    Returns a copy of this datetime with the specified duration added.

If the amount is zero or null, then this is returned.
This datetime instance is immutable and unaffected by this method call.
Params: duration –  the duration to add to this one, null means zero
Throws: ArithmeticException – if the new datetime exceeds the capacity of a long
Returns: a copy of this datetime with the duration added/**
     * Returns a copy of this datetime with the specified duration added.
     * <p>
     * If the amount is zero or null, then <code>this</code> is returned.
     * This datetime instance is immutable and unaffected by this method call.
     * 
     * @param duration  the duration to add to this one, null means zero
     * @return a copy of this datetime with the duration added
     * @throws ArithmeticException if the new datetime exceeds the capacity of a long
     */
    public DateTime plus(ReadableDuration duration) {
        return withDurationAdded(duration, 1);
    }

    Returns a copy of this datetime with the specified period added.

This method will add each element of the period one by one, from largest
to smallest, adjusting the datetime to be accurate between each.

Thus, adding a period of one month and one day to 2007-03-31 will
work as follows:
First add one month and adjust, resulting in 2007-04-30
Then add one day and adjust, resulting in 2007-05-01.
 This method is typically used to add complex period instances. Adding one field is best achieved using methods like plusYears(int). 

If the amount is zero or null, then this is returned.
This datetime instance is immutable and unaffected by this method call.
Params: period –  the duration to add to this one, null means zero
Throws: ArithmeticException – if the new datetime exceeds the capacity of a long
Returns: a copy of this datetime with the period added/**
     * Returns a copy of this datetime with the specified period added.
     * <p>
     * This method will add each element of the period one by one, from largest
     * to smallest, adjusting the datetime to be accurate between each.
     * <p>
     * Thus, adding a period of one month and one day to 2007-03-31 will
     * work as follows:
     * First add one month and adjust, resulting in 2007-04-30
     * Then add one day and adjust, resulting in 2007-05-01.
     * <p>
     * This method is typically used to add complex period instances.
     * Adding one field is best achieved using methods
     * like {@link #plusYears(int)}.
     * <p>
     * If the amount is zero or null, then <code>this</code> is returned.
     * This datetime instance is immutable and unaffected by this method call.
     * 
     * @param period  the duration to add to this one, null means zero
     * @return a copy of this datetime with the period added
     * @throws ArithmeticException if the new datetime exceeds the capacity of a long
     */
    public DateTime plus(ReadablePeriod period) {
        return withPeriodAdded(period, 1);
    }

    //-----------------------------------------------------------------------
    Returns a copy of this datetime plus the specified number of years.

The calculation will do its best to only change the year field
retaining the same month of year.
However, in certain circumstances, it may be necessary to alter
smaller fields. For example, 2008-02-29 plus one year cannot result
in 2009-02-29, so the day of month is adjusted to 2009-02-28.

The following three lines are identical in effect:
DateTime added = dt.plusYears(6);
DateTime added = dt.plus(Period.years(6));
DateTime added = dt.withFieldAdded(DurationFieldType.years(), 6);


This datetime instance is immutable and unaffected by this method call.
Params: years –  the amount of years to add, may be negative
Returns: the new datetime plus the increased years
Since: 1.1/**
     * Returns a copy of this datetime plus the specified number of years.
     * <p>
     * The calculation will do its best to only change the year field
     * retaining the same month of year.
     * However, in certain circumstances, it may be necessary to alter
     * smaller fields. For example, 2008-02-29 plus one year cannot result
     * in 2009-02-29, so the day of month is adjusted to 2009-02-28.
     * <p>
     * The following three lines are identical in effect:
     * <pre>
     * DateTime added = dt.plusYears(6);
     * DateTime added = dt.plus(Period.years(6));
     * DateTime added = dt.withFieldAdded(DurationFieldType.years(), 6);
     * </pre>
     * <p>
     * This datetime instance is immutable and unaffected by this method call.
     *
     * @param years  the amount of years to add, may be negative
     * @return the new datetime plus the increased years
     * @since 1.1
     */
    public DateTime plusYears(int years) {
        if (years == 0) {
            return this;
        }
        long instant = getChronology().years().add(getMillis(), years);
        return withMillis(instant);
    }

    Returns a copy of this datetime plus the specified number of months.

The calculation will do its best to only change the month field
retaining the same day of month.
However, in certain circumstances, it may be necessary to alter
smaller fields. For example, 2007-03-31 plus one month cannot result
in 2007-04-31, so the day of month is adjusted to 2007-04-30.

The following three lines are identical in effect:
DateTime added = dt.plusMonths(6);
DateTime added = dt.plus(Period.months(6));
DateTime added = dt.withFieldAdded(DurationFieldType.months(), 6);


This datetime instance is immutable and unaffected by this method call.
Params: months –  the amount of months to add, may be negative
Returns: the new datetime plus the increased months
Since: 1.1/**
     * Returns a copy of this datetime plus the specified number of months.
     * <p>
     * The calculation will do its best to only change the month field
     * retaining the same day of month.
     * However, in certain circumstances, it may be necessary to alter
     * smaller fields. For example, 2007-03-31 plus one month cannot result
     * in 2007-04-31, so the day of month is adjusted to 2007-04-30.
     * <p>
     * The following three lines are identical in effect:
     * <pre>
     * DateTime added = dt.plusMonths(6);
     * DateTime added = dt.plus(Period.months(6));
     * DateTime added = dt.withFieldAdded(DurationFieldType.months(), 6);
     * </pre>
     * <p>
     * This datetime instance is immutable and unaffected by this method call.
     *
     * @param months  the amount of months to add, may be negative
     * @return the new datetime plus the increased months
     * @since 1.1
     */
    public DateTime plusMonths(int months) {
        if (months == 0) {
            return this;
        }
        long instant = getChronology().months().add(getMillis(), months);
        return withMillis(instant);
    }

    Returns a copy of this datetime plus the specified number of weeks.

The calculation operates as if it were adding the equivalent in days.

The following three lines are identical in effect:
DateTime added = dt.plusWeeks(6);
DateTime added = dt.plus(Period.weeks(6));
DateTime added = dt.withFieldAdded(DurationFieldType.weeks(), 6);


This datetime instance is immutable and unaffected by this method call.
Params: weeks –  the amount of weeks to add, may be negative
Returns: the new datetime plus the increased weeks
Since: 1.1/**
     * Returns a copy of this datetime plus the specified number of weeks.
     * <p>
     * The calculation operates as if it were adding the equivalent in days.
     * <p>
     * The following three lines are identical in effect:
     * <pre>
     * DateTime added = dt.plusWeeks(6);
     * DateTime added = dt.plus(Period.weeks(6));
     * DateTime added = dt.withFieldAdded(DurationFieldType.weeks(), 6);
     * </pre>
     * <p>
     * This datetime instance is immutable and unaffected by this method call.
     *
     * @param weeks  the amount of weeks to add, may be negative
     * @return the new datetime plus the increased weeks
     * @since 1.1
     */
    public DateTime plusWeeks(int weeks) {
        if (weeks == 0) {
            return this;
        }
        long instant = getChronology().weeks().add(getMillis(), weeks);
        return withMillis(instant);
    }

    Returns a copy of this datetime plus the specified number of days.

The calculation will do its best to only change the day field
retaining the same time of day.
However, in certain circumstances, typically daylight savings cutover,
it may be necessary to alter the time fields.

In spring an hour is typically removed. If adding one day results in
the time being within the cutover then the time is adjusted to be
within summer time. For example, if the cutover is from 01:59 to 03:00
and the result of this method would have been 02:30, then the result
will be adjusted to 03:30.

The following three lines are identical in effect:
DateTime added = dt.plusDays(6);
DateTime added = dt.plus(Period.days(6));
DateTime added = dt.withFieldAdded(DurationFieldType.days(), 6);


This datetime instance is immutable and unaffected by this method call.
Params: days –  the amount of days to add, may be negative
Returns: the new datetime plus the increased days
Since: 1.1/**
     * Returns a copy of this datetime plus the specified number of days.
     * <p>
     * The calculation will do its best to only change the day field
     * retaining the same time of day.
     * However, in certain circumstances, typically daylight savings cutover,
     * it may be necessary to alter the time fields.
     * <p>
     * In spring an hour is typically removed. If adding one day results in
     * the time being within the cutover then the time is adjusted to be
     * within summer time. For example, if the cutover is from 01:59 to 03:00
     * and the result of this method would have been 02:30, then the result
     * will be adjusted to 03:30.
     * <p>
     * The following three lines are identical in effect:
     * <pre>
     * DateTime added = dt.plusDays(6);
     * DateTime added = dt.plus(Period.days(6));
     * DateTime added = dt.withFieldAdded(DurationFieldType.days(), 6);
     * </pre>
     * <p>
     * This datetime instance is immutable and unaffected by this method call.
     *
     * @param days  the amount of days to add, may be negative
     * @return the new datetime plus the increased days
     * @since 1.1
     */
    public DateTime plusDays(int days) {
        if (days == 0) {
            return this;
        }
        long instant = getChronology().days().add(getMillis(), days);
        return withMillis(instant);
    }

    Returns a copy of this datetime plus the specified number of hours.

The calculation will add a duration equivalent to the number of hours
expressed in milliseconds.

For example, if a spring daylight savings cutover is from 01:59 to 03:00
then adding one hour to 01:30 will result in 03:30. This is a duration
of one hour later, even though the hour field value changed from 1 to 3.

The following three lines are identical in effect:
DateTime added = dt.plusHours(6);
DateTime added = dt.plus(Period.hours(6));
DateTime added = dt.withFieldAdded(DurationFieldType.hours(), 6);


This datetime instance is immutable and unaffected by this method call.
Params: hours –  the amount of hours to add, may be negative
Returns: the new datetime plus the increased hours
Since: 1.1/**
     * Returns a copy of this datetime plus the specified number of hours.
     * <p>
     * The calculation will add a duration equivalent to the number of hours
     * expressed in milliseconds.
     * <p>
     * For example, if a spring daylight savings cutover is from 01:59 to 03:00
     * then adding one hour to 01:30 will result in 03:30. This is a duration
     * of one hour later, even though the hour field value changed from 1 to 3.
     * <p>
     * The following three lines are identical in effect:
     * <pre>
     * DateTime added = dt.plusHours(6);
     * DateTime added = dt.plus(Period.hours(6));
     * DateTime added = dt.withFieldAdded(DurationFieldType.hours(), 6);
     * </pre>
     * <p>
     * This datetime instance is immutable and unaffected by this method call.
     *
     * @param hours  the amount of hours to add, may be negative
     * @return the new datetime plus the increased hours
     * @since 1.1
     */
    public DateTime plusHours(int hours) {
        if (hours == 0) {
            return this;
        }
        long instant = getChronology().hours().add(getMillis(), hours);
        return withMillis(instant);
    }

    Returns a copy of this datetime plus the specified number of minutes.

The calculation will add a duration equivalent to the number of minutes
expressed in milliseconds.

The following three lines are identical in effect:
DateTime added = dt.plusMinutes(6);
DateTime added = dt.plus(Period.minutes(6));
DateTime added = dt.withFieldAdded(DurationFieldType.minutes(), 6);


This datetime instance is immutable and unaffected by this method call.
Params: minutes –  the amount of minutes to add, may be negative
Returns: the new datetime plus the increased minutes
Since: 1.1/**
     * Returns a copy of this datetime plus the specified number of minutes.
     * <p>
     * The calculation will add a duration equivalent to the number of minutes
     * expressed in milliseconds.
     * <p>
     * The following three lines are identical in effect:
     * <pre>
     * DateTime added = dt.plusMinutes(6);
     * DateTime added = dt.plus(Period.minutes(6));
     * DateTime added = dt.withFieldAdded(DurationFieldType.minutes(), 6);
     * </pre>
     * <p>
     * This datetime instance is immutable and unaffected by this method call.
     *
     * @param minutes  the amount of minutes to add, may be negative
     * @return the new datetime plus the increased minutes
     * @since 1.1
     */
    public DateTime plusMinutes(int minutes) {
        if (minutes == 0) {
            return this;
        }
        long instant = getChronology().minutes().add(getMillis(), minutes);
        return withMillis(instant);
    }

    Returns a copy of this datetime plus the specified number of seconds.

The calculation will add a duration equivalent to the number of seconds
expressed in milliseconds.

The following three lines are identical in effect:
DateTime added = dt.plusSeconds(6);
DateTime added = dt.plus(Period.seconds(6));
DateTime added = dt.withFieldAdded(DurationFieldType.seconds(), 6);


This datetime instance is immutable and unaffected by this method call.
Params: seconds –  the amount of seconds to add, may be negative
Returns: the new datetime plus the increased seconds
Since: 1.1/**
     * Returns a copy of this datetime plus the specified number of seconds.
     * <p>
     * The calculation will add a duration equivalent to the number of seconds
     * expressed in milliseconds.
     * <p>
     * The following three lines are identical in effect:
     * <pre>
     * DateTime added = dt.plusSeconds(6);
     * DateTime added = dt.plus(Period.seconds(6));
     * DateTime added = dt.withFieldAdded(DurationFieldType.seconds(), 6);
     * </pre>
     * <p>
     * This datetime instance is immutable and unaffected by this method call.
     *
     * @param seconds  the amount of seconds to add, may be negative
     * @return the new datetime plus the increased seconds
     * @since 1.1
     */
    public DateTime plusSeconds(int seconds) {
        if (seconds == 0) {
            return this;
        }
        long instant = getChronology().seconds().add(getMillis(), seconds);
        return withMillis(instant);
    }

    Returns a copy of this datetime plus the specified number of millis.

The calculation will add a duration equivalent to the number of milliseconds.

The following three lines are identical in effect:
DateTime added = dt.plusMillis(6);
DateTime added = dt.plus(Period.millis(6));
DateTime added = dt.withFieldAdded(DurationFieldType.millis(), 6);


This datetime instance is immutable and unaffected by this method call.
Params: millis –  the amount of millis to add, may be negative
Returns: the new datetime plus the increased millis
Since: 1.1/**
     * Returns a copy of this datetime plus the specified number of millis.
     * <p>
     * The calculation will add a duration equivalent to the number of milliseconds.
     * <p>
     * The following three lines are identical in effect:
     * <pre>
     * DateTime added = dt.plusMillis(6);
     * DateTime added = dt.plus(Period.millis(6));
     * DateTime added = dt.withFieldAdded(DurationFieldType.millis(), 6);
     * </pre>
     * <p>
     * This datetime instance is immutable and unaffected by this method call.
     *
     * @param millis  the amount of millis to add, may be negative
     * @return the new datetime plus the increased millis
     * @since 1.1
     */
    public DateTime plusMillis(int millis) {
        if (millis == 0) {
            return this;
        }
        long instant = getChronology().millis().add(getMillis(), millis);
        return withMillis(instant);
    }

    //-----------------------------------------------------------------------
    Returns a copy of this datetime with the specified duration taken away.

If the amount is zero or null, then this is returned.
This datetime instance is immutable and unaffected by this method call.
Params: duration –  the duration, in millis, to reduce this instant by
Throws: ArithmeticException – if the new datetime exceeds the capacity of a long
Returns: a copy of this datetime with the duration taken away/**
     * Returns a copy of this datetime with the specified duration taken away.
     * <p>
     * If the amount is zero or null, then <code>this</code> is returned.
     * This datetime instance is immutable and unaffected by this method call.
     * 
     * @param duration  the duration, in millis, to reduce this instant by
     * @return a copy of this datetime with the duration taken away
     * @throws ArithmeticException if the new datetime exceeds the capacity of a long
     */
    public DateTime minus(long duration) {
        return withDurationAdded(duration, -1);
    }

    Returns a copy of this datetime with the specified duration taken away.

If the amount is zero or null, then this is returned.
This datetime instance is immutable and unaffected by this method call.
Params: duration –  the duration to reduce this instant by
Throws: ArithmeticException – if the new datetime exceeds the capacity of a long
Returns: a copy of this datetime with the duration taken away/**
     * Returns a copy of this datetime with the specified duration taken away.
     * <p>
     * If the amount is zero or null, then <code>this</code> is returned.
     * This datetime instance is immutable and unaffected by this method call.
     * 
     * @param duration  the duration to reduce this instant by
     * @return a copy of this datetime with the duration taken away
     * @throws ArithmeticException if the new datetime exceeds the capacity of a long
     */
    public DateTime minus(ReadableDuration duration) {
        return withDurationAdded(duration, -1);
    }

    Returns a copy of this datetime with the specified period taken away.

This method will subtract each element of the period one by one, from
largest to smallest, adjusting the datetime to be accurate between each.

Thus, subtracting a period of one month and one day from 2007-05-31 will
work as follows:
First subtract one month and adjust, resulting in 2007-04-30
Then subtract one day and adjust, resulting in 2007-04-29.
Note that the day has been adjusted by two.
 This method is typically used to subtract complex period instances. Subtracting one field is best achieved using methods like minusYears(int). 

If the amount is zero or null, then this is returned.
This datetime instance is immutable and unaffected by this method call.
Params: period –  the period to reduce this instant by
Throws: ArithmeticException – if the new datetime exceeds the capacity of a long
Returns: a copy of this datetime with the period taken away/**
     * Returns a copy of this datetime with the specified period taken away.
     * <p>
     * This method will subtract each element of the period one by one, from
     * largest to smallest, adjusting the datetime to be accurate between each.
     * <p>
     * Thus, subtracting a period of one month and one day from 2007-05-31 will
     * work as follows:
     * First subtract one month and adjust, resulting in 2007-04-30
     * Then subtract one day and adjust, resulting in 2007-04-29.
     * Note that the day has been adjusted by two.
     * <p>
     * This method is typically used to subtract complex period instances.
     * Subtracting one field is best achieved using methods
     * like {@link #minusYears(int)}.
     * <p>
     * If the amount is zero or null, then <code>this</code> is returned.
     * This datetime instance is immutable and unaffected by this method call.
     * 
     * @param period  the period to reduce this instant by
     * @return a copy of this datetime with the period taken away
     * @throws ArithmeticException if the new datetime exceeds the capacity of a long
     */
    public DateTime minus(ReadablePeriod period) {
        return withPeriodAdded(period, -1);
    }

    //-----------------------------------------------------------------------
    Returns a copy of this datetime minus the specified number of years.

The calculation will do its best to only change the year field
retaining the same month of year.
However, in certain circumstances, it may be necessary to alter
smaller fields. For example, 2008-02-29 minus one year cannot result
in 2007-02-29, so the day of month is adjusted to 2007-02-28.

The following three lines are identical in effect:
DateTime subtracted = dt.minusYears(6);
DateTime subtracted = dt.minus(Period.years(6));
DateTime subtracted = dt.withFieldAdded(DurationFieldType.years(), -6);


This datetime instance is immutable and unaffected by this method call.
Params: years –  the amount of years to subtract, may be negative
Returns: the new datetime minus the increased years
Since: 1.1/**
     * Returns a copy of this datetime minus the specified number of years.
     * <p>
     * The calculation will do its best to only change the year field
     * retaining the same month of year.
     * However, in certain circumstances, it may be necessary to alter
     * smaller fields. For example, 2008-02-29 minus one year cannot result
     * in 2007-02-29, so the day of month is adjusted to 2007-02-28.
     * <p>
     * The following three lines are identical in effect:
     * <pre>
     * DateTime subtracted = dt.minusYears(6);
     * DateTime subtracted = dt.minus(Period.years(6));
     * DateTime subtracted = dt.withFieldAdded(DurationFieldType.years(), -6);
     * </pre>
     * <p>
     * This datetime instance is immutable and unaffected by this method call.
     *
     * @param years  the amount of years to subtract, may be negative
     * @return the new datetime minus the increased years
     * @since 1.1
     */
    public DateTime minusYears(int years) {
        if (years == 0) {
            return this;
        }
        long instant = getChronology().years().subtract(getMillis(), years);
        return withMillis(instant);
    }

    Returns a copy of this datetime minus the specified number of months.

The calculation will do its best to only change the month field
retaining the same day of month.
However, in certain circumstances, it may be necessary to alter
smaller fields. For example, 2007-05-31 minus one month cannot result
in 2007-04-31, so the day of month is adjusted to 2007-04-30.

The following three lines are identical in effect:
DateTime subtracted = dt.minusMonths(6);
DateTime subtracted = dt.minus(Period.months(6));
DateTime subtracted = dt.withFieldAdded(DurationFieldType.months(), -6);


This datetime instance is immutable and unaffected by this method call.
Params: months –  the amount of months to subtract, may be negative
Returns: the new datetime minus the increased months
Since: 1.1/**
     * Returns a copy of this datetime minus the specified number of months.
     * <p>
     * The calculation will do its best to only change the month field
     * retaining the same day of month.
     * However, in certain circumstances, it may be necessary to alter
     * smaller fields. For example, 2007-05-31 minus one month cannot result
     * in 2007-04-31, so the day of month is adjusted to 2007-04-30.
     * <p>
     * The following three lines are identical in effect:
     * <pre>
     * DateTime subtracted = dt.minusMonths(6);
     * DateTime subtracted = dt.minus(Period.months(6));
     * DateTime subtracted = dt.withFieldAdded(DurationFieldType.months(), -6);
     * </pre>
     * <p>
     * This datetime instance is immutable and unaffected by this method call.
     *
     * @param months  the amount of months to subtract, may be negative
     * @return the new datetime minus the increased months
     * @since 1.1
     */
    public DateTime minusMonths(int months) {
        if (months == 0) {
            return this;
        }
        long instant = getChronology().months().subtract(getMillis(), months);
        return withMillis(instant);
    }

    Returns a copy of this datetime minus the specified number of weeks.

The calculation operates as if it were subtracting the equivalent in days.

The following three lines are identical in effect:
DateTime subtracted = dt.minusWeeks(6);
DateTime subtracted = dt.minus(Period.weeks(6));
DateTime subtracted = dt.withFieldAdded(DurationFieldType.weeks(), -6);


This datetime instance is immutable and unaffected by this method call.
Params: weeks –  the amount of weeks to subtract, may be negative
Returns: the new datetime minus the increased weeks
Since: 1.1/**
     * Returns a copy of this datetime minus the specified number of weeks.
     * <p>
     * The calculation operates as if it were subtracting the equivalent in days.
     * <p>
     * The following three lines are identical in effect:
     * <pre>
     * DateTime subtracted = dt.minusWeeks(6);
     * DateTime subtracted = dt.minus(Period.weeks(6));
     * DateTime subtracted = dt.withFieldAdded(DurationFieldType.weeks(), -6);
     * </pre>
     * <p>
     * This datetime instance is immutable and unaffected by this method call.
     *
     * @param weeks  the amount of weeks to subtract, may be negative
     * @return the new datetime minus the increased weeks
     * @since 1.1
     */
    public DateTime minusWeeks(int weeks) {
        if (weeks == 0) {
            return this;
        }
        long instant = getChronology().weeks().subtract(getMillis(), weeks);
        return withMillis(instant);
    }

    Returns a copy of this datetime minus the specified number of days.

The calculation will do its best to only change the day field
retaining the same time of day.
However, in certain circumstances, typically daylight savings cutover,
it may be necessary to alter the time fields.

In spring an hour is typically removed. If subtracting one day results
in the time being within the cutover then the time is adjusted to be
within summer time. For example, if the cutover is from 01:59 to 03:00
and the result of this method would have been 02:30, then the result
will be adjusted to 03:30.

The following three lines are identical in effect:
DateTime subtracted = dt.minusDays(6);
DateTime subtracted = dt.minus(Period.days(6));
DateTime subtracted = dt.withFieldAdded(DurationFieldType.days(), -6);


This datetime instance is immutable and unaffected by this method call.
Params: days –  the amount of days to subtract, may be negative
Returns: the new datetime minus the increased days
Since: 1.1/**
     * Returns a copy of this datetime minus the specified number of days.
     * <p>
     * The calculation will do its best to only change the day field
     * retaining the same time of day.
     * However, in certain circumstances, typically daylight savings cutover,
     * it may be necessary to alter the time fields.
     * <p>
     * In spring an hour is typically removed. If subtracting one day results
     * in the time being within the cutover then the time is adjusted to be
     * within summer time. For example, if the cutover is from 01:59 to 03:00
     * and the result of this method would have been 02:30, then the result
     * will be adjusted to 03:30.
     * <p>
     * The following three lines are identical in effect:
     * <pre>
     * DateTime subtracted = dt.minusDays(6);
     * DateTime subtracted = dt.minus(Period.days(6));
     * DateTime subtracted = dt.withFieldAdded(DurationFieldType.days(), -6);
     * </pre>
     * <p>
     * This datetime instance is immutable and unaffected by this method call.
     *
     * @param days  the amount of days to subtract, may be negative
     * @return the new datetime minus the increased days
     * @since 1.1
     */
    public DateTime minusDays(int days) {
        if (days == 0) {
            return this;
        }
        long instant = getChronology().days().subtract(getMillis(), days);
        return withMillis(instant);
    }

    Returns a copy of this datetime minus the specified number of hours.

The calculation will subtract a duration equivalent to the number of
hours expressed in milliseconds.

For example, if a spring daylight savings cutover is from 01:59 to 03:00
then subtracting one hour from 03:30 will result in 01:30. This is a
duration of one hour earlier, even though the hour field value changed
from 3 to 1.

The following three lines are identical in effect:
DateTime subtracted = dt.minusHours(6);
DateTime subtracted = dt.minus(Period.hours(6));
DateTime subtracted = dt.withFieldAdded(DurationFieldType.hours(), -6);


This datetime instance is immutable and unaffected by this method call.
Params: hours –  the amount of hours to subtract, may be negative
Returns: the new datetime minus the increased hours
Since: 1.1/**
     * Returns a copy of this datetime minus the specified number of hours.
     * <p>
     * The calculation will subtract a duration equivalent to the number of
     * hours expressed in milliseconds.
     * <p>
     * For example, if a spring daylight savings cutover is from 01:59 to 03:00
     * then subtracting one hour from 03:30 will result in 01:30. This is a
     * duration of one hour earlier, even though the hour field value changed
     * from 3 to 1.
     * <p>
     * The following three lines are identical in effect:
     * <pre>
     * DateTime subtracted = dt.minusHours(6);
     * DateTime subtracted = dt.minus(Period.hours(6));
     * DateTime subtracted = dt.withFieldAdded(DurationFieldType.hours(), -6);
     * </pre>
     * <p>
     * This datetime instance is immutable and unaffected by this method call.
     *
     * @param hours  the amount of hours to subtract, may be negative
     * @return the new datetime minus the increased hours
     * @since 1.1
     */
    public DateTime minusHours(int hours) {
        if (hours == 0) {
            return this;
        }
        long instant = getChronology().hours().subtract(getMillis(), hours);
        return withMillis(instant);
    }

    Returns a copy of this datetime minus the specified number of minutes.

The calculation will subtract a duration equivalent to the number of
minutes expressed in milliseconds.

The following three lines are identical in effect:
DateTime subtracted = dt.minusMinutes(6);
DateTime subtracted = dt.minus(Period.minutes(6));
DateTime subtracted = dt.withFieldAdded(DurationFieldType.minutes(), -6);


This datetime instance is immutable and unaffected by this method call.
Params: minutes –  the amount of minutes to subtract, may be negative
Returns: the new datetime minus the increased minutes
Since: 1.1/**
     * Returns a copy of this datetime minus the specified number of minutes.
     * <p>
     * The calculation will subtract a duration equivalent to the number of
     * minutes expressed in milliseconds.
     * <p>
     * The following three lines are identical in effect:
     * <pre>
     * DateTime subtracted = dt.minusMinutes(6);
     * DateTime subtracted = dt.minus(Period.minutes(6));
     * DateTime subtracted = dt.withFieldAdded(DurationFieldType.minutes(), -6);
     * </pre>
     * <p>
     * This datetime instance is immutable and unaffected by this method call.
     *
     * @param minutes  the amount of minutes to subtract, may be negative
     * @return the new datetime minus the increased minutes
     * @since 1.1
     */
    public DateTime minusMinutes(int minutes) {
        if (minutes == 0) {
            return this;
        }
        long instant = getChronology().minutes().subtract(getMillis(), minutes);
        return withMillis(instant);
    }

    Returns a copy of this datetime minus the specified number of seconds.

The calculation will subtract a duration equivalent to the number of
seconds expressed in milliseconds.

The following three lines are identical in effect:
DateTime subtracted = dt.minusSeconds(6);
DateTime subtracted = dt.minus(Period.seconds(6));
DateTime subtracted = dt.withFieldAdded(DurationFieldType.seconds(), -6);


This datetime instance is immutable and unaffected by this method call.
Params: seconds –  the amount of seconds to subtract, may be negative
Returns: the new datetime minus the increased seconds
Since: 1.1/**
     * Returns a copy of this datetime minus the specified number of seconds.
     * <p>
     * The calculation will subtract a duration equivalent to the number of
     * seconds expressed in milliseconds.
     * <p>
     * The following three lines are identical in effect:
     * <pre>
     * DateTime subtracted = dt.minusSeconds(6);
     * DateTime subtracted = dt.minus(Period.seconds(6));
     * DateTime subtracted = dt.withFieldAdded(DurationFieldType.seconds(), -6);
     * </pre>
     * <p>
     * This datetime instance is immutable and unaffected by this method call.
     *
     * @param seconds  the amount of seconds to subtract, may be negative
     * @return the new datetime minus the increased seconds
     * @since 1.1
     */
    public DateTime minusSeconds(int seconds) {
        if (seconds == 0) {
            return this;
        }
        long instant = getChronology().seconds().subtract(getMillis(), seconds);
        return withMillis(instant);
    }

    Returns a copy of this datetime minus the specified number of millis.

The calculation will subtract a duration equivalent to the number of
milliseconds.

The following three lines are identical in effect:
DateTime subtracted = dt.minusMillis(6);
DateTime subtracted = dt.minus(Period.millis(6));
DateTime subtracted = dt.withFieldAdded(DurationFieldType.millis(), -6);


This datetime instance is immutable and unaffected by this method call.
Params: millis –  the amount of millis to subtract, may be negative
Returns: the new datetime minus the increased millis
Since: 1.1/**
     * Returns a copy of this datetime minus the specified number of millis.
     * <p>
     * The calculation will subtract a duration equivalent to the number of
     * milliseconds.
     * <p>
     * The following three lines are identical in effect:
     * <pre>
     * DateTime subtracted = dt.minusMillis(6);
     * DateTime subtracted = dt.minus(Period.millis(6));
     * DateTime subtracted = dt.withFieldAdded(DurationFieldType.millis(), -6);
     * </pre>
     * <p>
     * This datetime instance is immutable and unaffected by this method call.
     *
     * @param millis  the amount of millis to subtract, may be negative
     * @return the new datetime minus the increased millis
     * @since 1.1
     */
    public DateTime minusMillis(int millis) {
        if (millis == 0) {
            return this;
        }
        long instant = getChronology().millis().subtract(getMillis(), millis);
        return withMillis(instant);
    }

    //-----------------------------------------------------------------------
    Gets the property object for the specified type, which contains many useful methods.
Params: type –  the field type to get the chronology for
Throws: IllegalArgumentException – if the field is null or unsupported
Returns: the property object/**
     * Gets the property object for the specified type, which contains many useful methods.
     *
     * @param type  the field type to get the chronology for
     * @return the property object
     * @throws IllegalArgumentException if the field is null or unsupported
     */
    public Property property(DateTimeFieldType type) {
        if (type == null) {
            throw new IllegalArgumentException("The DateTimeFieldType must not be null");
        }
        DateTimeField field = type.getField(getChronology());
        if (field.isSupported() == false) {
            throw new IllegalArgumentException("Field '" + type + "' is not supported");
        }
        return new Property(this, field);
    }

    //-----------------------------------------------------------------------
    Converts this object to a DateMidnight using the
same millis and chronology.
Returns: a DateMidnight using the same millis and chronology
Deprecated: DateMidnight is deprecated/**
     * Converts this object to a <code>DateMidnight</code> using the
     * same millis and chronology.
     * 
     * @return a DateMidnight using the same millis and chronology
     * @deprecated DateMidnight is deprecated
     */
    @Deprecated
    public DateMidnight toDateMidnight() {
        return new DateMidnight(getMillis(), getChronology());
    }

    Converts this object to a YearMonthDay using the
same millis and chronology.
Returns: a YearMonthDay using the same millis and chronology
Deprecated: Use LocalDate instead of YearMonthDay/**
     * Converts this object to a <code>YearMonthDay</code> using the
     * same millis and chronology.
     * 
     * @return a YearMonthDay using the same millis and chronology
     * @deprecated Use LocalDate instead of YearMonthDay
     */
    @Deprecated
    public YearMonthDay toYearMonthDay() {
        return new YearMonthDay(getMillis(), getChronology());
    }

    Converts this object to a TimeOfDay using the
same millis and chronology.
Returns: a TimeOfDay using the same millis and chronology
Deprecated: Use LocalTime instead of TimeOfDay/**
     * Converts this object to a <code>TimeOfDay</code> using the
     * same millis and chronology.
     * 
     * @return a TimeOfDay using the same millis and chronology
     * @deprecated Use LocalTime instead of TimeOfDay
     */
    @Deprecated
    public TimeOfDay toTimeOfDay() {
        return new TimeOfDay(getMillis(), getChronology());
    }

    Converts this object to a LocalDateTime with
the same datetime and chronology.
Returns: a LocalDateTime with the same datetime and chronology
Since: 1.3/**
     * Converts this object to a <code>LocalDateTime</code> with
     * the same datetime and chronology.
     *
     * @return a LocalDateTime with the same datetime and chronology
     * @since 1.3
     */
    public LocalDateTime toLocalDateTime() {
        return new LocalDateTime(getMillis(), getChronology());
    }

    Converts this object to a LocalDate with the
same date and chronology.
Returns: a LocalDate with the same date and chronology
Since: 1.3/**
     * Converts this object to a <code>LocalDate</code> with the
     * same date and chronology.
     *
     * @return a LocalDate with the same date and chronology
     * @since 1.3
     */
    public LocalDate toLocalDate() {
        return new LocalDate(getMillis(), getChronology());
    }

    Converts this object to a LocalTime with the
same time and chronology.
Returns: a LocalTime with the same time and chronology
Since: 1.3/**
     * Converts this object to a <code>LocalTime</code> with the
     * same time and chronology.
     *
     * @return a LocalTime with the same time and chronology
     * @since 1.3
     */
    public LocalTime toLocalTime() {
        return new LocalTime(getMillis(), getChronology());
    }

    //-----------------------------------------------------------------------
    Returns a copy of this datetime with the era field updated.

DateTime is immutable, so there are no set methods.
Instead, this method returns a new instance with the value of
era changed.
Params: era –  the era to set
Throws: IllegalArgumentException – if the value is invalid
Returns: a copy of this object with the field set
Since: 1.3/**
     * Returns a copy of this datetime with the era field updated.
     * <p>
     * DateTime is immutable, so there are no set methods.
     * Instead, this method returns a new instance with the value of
     * era changed.
     *
     * @param era  the era to set
     * @return a copy of this object with the field set
     * @throws IllegalArgumentException if the value is invalid
     * @since 1.3
     */
    public DateTime withEra(int era) {
        return withMillis(getChronology().era().set(getMillis(), era));
    }

    Returns a copy of this datetime with the century of era field updated.

DateTime is immutable, so there are no set methods.
Instead, this method returns a new instance with the value of
century of era changed.
Params: centuryOfEra –  the century of era to set
Throws: IllegalArgumentException – if the value is invalid
Returns: a copy of this object with the field set
Since: 1.3/**
     * Returns a copy of this datetime with the century of era field updated.
     * <p>
     * DateTime is immutable, so there are no set methods.
     * Instead, this method returns a new instance with the value of
     * century of era changed.
     *
     * @param centuryOfEra  the century of era to set
     * @return a copy of this object with the field set
     * @throws IllegalArgumentException if the value is invalid
     * @since 1.3
     */
    public DateTime withCenturyOfEra(int centuryOfEra) {
        return withMillis(getChronology().centuryOfEra().set(getMillis(), centuryOfEra));
    }

    Returns a copy of this datetime with the year of era field updated.

DateTime is immutable, so there are no set methods.
Instead, this method returns a new instance with the value of
year of era changed.
Params: yearOfEra –  the year of era to set
Throws: IllegalArgumentException – if the value is invalid
Returns: a copy of this object with the field set
Since: 1.3/**
     * Returns a copy of this datetime with the year of era field updated.
     * <p>
     * DateTime is immutable, so there are no set methods.
     * Instead, this method returns a new instance with the value of
     * year of era changed.
     *
     * @param yearOfEra  the year of era to set
     * @return a copy of this object with the field set
     * @throws IllegalArgumentException if the value is invalid
     * @since 1.3
     */
    public DateTime withYearOfEra(int yearOfEra) {
        return withMillis(getChronology().yearOfEra().set(getMillis(), yearOfEra));
    }

    Returns a copy of this datetime with the year of century field updated.

DateTime is immutable, so there are no set methods.
Instead, this method returns a new instance with the value of
year of century changed.
Params: yearOfCentury –  the year of century to set
Throws: IllegalArgumentException – if the value is invalid
Returns: a copy of this object with the field set
Since: 1.3/**
     * Returns a copy of this datetime with the year of century field updated.
     * <p>
     * DateTime is immutable, so there are no set methods.
     * Instead, this method returns a new instance with the value of
     * year of century changed.
     *
     * @param yearOfCentury  the year of century to set
     * @return a copy of this object with the field set
     * @throws IllegalArgumentException if the value is invalid
     * @since 1.3
     */
    public DateTime withYearOfCentury(int yearOfCentury) {
        return withMillis(getChronology().yearOfCentury().set(getMillis(), yearOfCentury));
    }

    Returns a copy of this datetime with the year field updated.

DateTime is immutable, so there are no set methods.
Instead, this method returns a new instance with the value of
year changed.
Params: year –  the year to set
Throws: IllegalArgumentException – if the value is invalid
Returns: a copy of this object with the field set
Since: 1.3/**
     * Returns a copy of this datetime with the year field updated.
     * <p>
     * DateTime is immutable, so there are no set methods.
     * Instead, this method returns a new instance with the value of
     * year changed.
     *
     * @param year  the year to set
     * @return a copy of this object with the field set
     * @throws IllegalArgumentException if the value is invalid
     * @since 1.3
     */
    public DateTime withYear(int year) {
        return withMillis(getChronology().year().set(getMillis(), year));
    }

    Returns a copy of this datetime with the weekyear field updated.

The weekyear is the year that matches with the weekOfWeekyear field.
In the standard ISO8601 week algorithm, the first week of the year
is that in which at least 4 days are in the year. As a result of this
definition, day 1 of the first week may be in the previous year.
The weekyear allows you to query the effective year for that day.

DateTime is immutable, so there are no set methods.
Instead, this method returns a new instance with the value of
weekyear changed.
Params: weekyear –  the weekyear to set
Throws: IllegalArgumentException – if the value is invalid
Returns: a copy of this object with the field set
Since: 1.3/**
     * Returns a copy of this datetime with the weekyear field updated.
     * <p>
     * The weekyear is the year that matches with the weekOfWeekyear field.
     * In the standard ISO8601 week algorithm, the first week of the year
     * is that in which at least 4 days are in the year. As a result of this
     * definition, day 1 of the first week may be in the previous year.
     * The weekyear allows you to query the effective year for that day.
     * <p>
     * DateTime is immutable, so there are no set methods.
     * Instead, this method returns a new instance with the value of
     * weekyear changed.
     *
     * @param weekyear  the weekyear to set
     * @return a copy of this object with the field set
     * @throws IllegalArgumentException if the value is invalid
     * @since 1.3
     */
    public DateTime withWeekyear(int weekyear) {
        return withMillis(getChronology().weekyear().set(getMillis(), weekyear));
    }

    Returns a copy of this datetime with the month of year field updated.

DateTime is immutable, so there are no set methods.
Instead, this method returns a new instance with the value of
month of year changed.
Params: monthOfYear –  the month of year to set
Throws: IllegalArgumentException – if the value is invalid
Returns: a copy of this object with the field set
Since: 1.3/**
     * Returns a copy of this datetime with the month of year field updated.
     * <p>
     * DateTime is immutable, so there are no set methods.
     * Instead, this method returns a new instance with the value of
     * month of year changed.
     *
     * @param monthOfYear  the month of year to set
     * @return a copy of this object with the field set
     * @throws IllegalArgumentException if the value is invalid
     * @since 1.3
     */
    public DateTime withMonthOfYear(int monthOfYear) {
        return withMillis(getChronology().monthOfYear().set(getMillis(), monthOfYear));
    }

    Returns a copy of this datetime with the week of weekyear field updated.
 This field is associated with the "weekyear" via withWeekyear(int). In the standard ISO8601 week algorithm, the first week of the year is that in which at least 4 days are in the year. As a result of this definition, day 1 of the first week may be in the previous year. 

DateTime is immutable, so there are no set methods.
Instead, this method returns a new instance with the value of
week of weekyear changed.
Params: weekOfWeekyear –  the week of weekyear to set
Throws: IllegalArgumentException – if the value is invalid
Returns: a copy of this object with the field set
Since: 1.3/**
     * Returns a copy of this datetime with the week of weekyear field updated.
     * <p>
     * This field is associated with the "weekyear" via {@link #withWeekyear(int)}.
     * In the standard ISO8601 week algorithm, the first week of the year
     * is that in which at least 4 days are in the year. As a result of this
     * definition, day 1 of the first week may be in the previous year.
     * <p>
     * DateTime is immutable, so there are no set methods.
     * Instead, this method returns a new instance with the value of
     * week of weekyear changed.
     *
     * @param weekOfWeekyear  the week of weekyear to set
     * @return a copy of this object with the field set
     * @throws IllegalArgumentException if the value is invalid
     * @since 1.3
     */
    public DateTime withWeekOfWeekyear(int weekOfWeekyear) {
        return withMillis(getChronology().weekOfWeekyear().set(getMillis(), weekOfWeekyear));
    }

    Returns a copy of this datetime with the day of year field updated.

DateTime is immutable, so there are no set methods.
Instead, this method returns a new instance with the value of
day of year changed.
Params: dayOfYear –  the day of year to set
Throws: IllegalArgumentException – if the value is invalid
Returns: a copy of this object with the field set
Since: 1.3/**
     * Returns a copy of this datetime with the day of year field updated.
     * <p>
     * DateTime is immutable, so there are no set methods.
     * Instead, this method returns a new instance with the value of
     * day of year changed.
     *
     * @param dayOfYear  the day of year to set
     * @return a copy of this object with the field set
     * @throws IllegalArgumentException if the value is invalid
     * @since 1.3
     */
    public DateTime withDayOfYear(int dayOfYear) {
        return withMillis(getChronology().dayOfYear().set(getMillis(), dayOfYear));
    }

    Returns a copy of this datetime with the day of month field updated.

DateTime is immutable, so there are no set methods.
Instead, this method returns a new instance with the value of
day of month changed.
Params: dayOfMonth –  the day of month to set
Throws: IllegalArgumentException – if the value is invalid
Returns: a copy of this object with the field set
Since: 1.3/**
     * Returns a copy of this datetime with the day of month field updated.
     * <p>
     * DateTime is immutable, so there are no set methods.
     * Instead, this method returns a new instance with the value of
     * day of month changed.
     *
     * @param dayOfMonth  the day of month to set
     * @return a copy of this object with the field set
     * @throws IllegalArgumentException if the value is invalid
     * @since 1.3
     */
    public DateTime withDayOfMonth(int dayOfMonth) {
        return withMillis(getChronology().dayOfMonth().set(getMillis(), dayOfMonth));
    }

    Returns a copy of this datetime with the day of week field updated.

DateTime is immutable, so there are no set methods.
Instead, this method returns a new instance with the value of
day of week changed.
Params: dayOfWeek –  the day of week to set
Throws: IllegalArgumentException – if the value is invalid
Returns: a copy of this object with the field set
Since: 1.3/**
     * Returns a copy of this datetime with the day of week field updated.
     * <p>
     * DateTime is immutable, so there are no set methods.
     * Instead, this method returns a new instance with the value of
     * day of week changed.
     *
     * @param dayOfWeek  the day of week to set
     * @return a copy of this object with the field set
     * @throws IllegalArgumentException if the value is invalid
     * @since 1.3
     */
    public DateTime withDayOfWeek(int dayOfWeek) {
        return withMillis(getChronology().dayOfWeek().set(getMillis(), dayOfWeek));
    }

    //-----------------------------------------------------------------------
    Returns a copy of this datetime with the hour of day field updated.

DateTime is immutable, so there are no set methods.
Instead, this method returns a new instance with the value of
hour of day changed.
Params: hour –  the hour of day to set
Throws: IllegalArgumentException – if the value is invalid
Returns: a copy of this object with the field set
Since: 1.3/**
     * Returns a copy of this datetime with the hour of day field updated.
     * <p>
     * DateTime is immutable, so there are no set methods.
     * Instead, this method returns a new instance with the value of
     * hour of day changed.
     *
     * @param hour  the hour of day to set
     * @return a copy of this object with the field set
     * @throws IllegalArgumentException if the value is invalid
     * @since 1.3
     */
    public DateTime withHourOfDay(int hour) {
        return withMillis(getChronology().hourOfDay().set(getMillis(), hour));
    }

    Returns a copy of this datetime with the minute of hour updated.

DateTime is immutable, so there are no set methods.
Instead, this method returns a new instance with the value of
minute of hour changed.
Params: minute –  the minute of hour to set
Throws: IllegalArgumentException – if the value is invalid
Returns: a copy of this object with the field set
Since: 1.3/**
     * Returns a copy of this datetime with the minute of hour updated.
     * <p>
     * DateTime is immutable, so there are no set methods.
     * Instead, this method returns a new instance with the value of
     * minute of hour changed.
     *
     * @param minute  the minute of hour to set
     * @return a copy of this object with the field set
     * @throws IllegalArgumentException if the value is invalid
     * @since 1.3
     */
    public DateTime withMinuteOfHour(int minute) {
        return withMillis(getChronology().minuteOfHour().set(getMillis(), minute));
    }

    Returns a copy of this datetime with the second of minute field updated.

DateTime is immutable, so there are no set methods.
Instead, this method returns a new instance with the value of
second of minute changed.
Params: second –  the second of minute to set
Throws: IllegalArgumentException – if the value is invalid
Returns: a copy of this object with the field set
Since: 1.3/**
     * Returns a copy of this datetime with the second of minute field updated.
     * <p>
     * DateTime is immutable, so there are no set methods.
     * Instead, this method returns a new instance with the value of
     * second of minute changed.
     *
     * @param second  the second of minute to set
     * @return a copy of this object with the field set
     * @throws IllegalArgumentException if the value is invalid
     * @since 1.3
     */
    public DateTime withSecondOfMinute(int second) {
        return withMillis(getChronology().secondOfMinute().set(getMillis(), second));
    }

    Returns a copy of this datetime with the millis of second field updated.

DateTime is immutable, so there are no set methods.
Instead, this method returns a new instance with the value of
millis of second changed.
Params: millis –  the millis of second to set
Throws: IllegalArgumentException – if the value is invalid
Returns: a copy of this object with the field set
Since: 1.3/**
     * Returns a copy of this datetime with the millis of second field updated.
     * <p>
     * DateTime is immutable, so there are no set methods.
     * Instead, this method returns a new instance with the value of
     * millis of second changed.
     *
     * @param millis  the millis of second to set
     * @return a copy of this object with the field set
     * @throws IllegalArgumentException if the value is invalid
     * @since 1.3
     */
    public DateTime withMillisOfSecond(int millis) {
        return withMillis(getChronology().millisOfSecond().set(getMillis(), millis));
    }

    Returns a copy of this datetime with the millis of day field updated.

DateTime is immutable, so there are no set methods.
Instead, this method returns a new instance with the value of
millis of day changed.
Params: millis –  the millis of day to set
Throws: IllegalArgumentException – if the value is invalid
Returns: a copy of this object with the field set
Since: 1.3/**
     * Returns a copy of this datetime with the millis of day field updated.
     * <p>
     * DateTime is immutable, so there are no set methods.
     * Instead, this method returns a new instance with the value of
     * millis of day changed.
     *
     * @param millis  the millis of day to set
     * @return a copy of this object with the field set
     * @throws IllegalArgumentException if the value is invalid
     * @since 1.3
     */
    public DateTime withMillisOfDay(int millis) {
        return withMillis(getChronology().millisOfDay().set(getMillis(), millis));
    }

    // Date properties
    //-----------------------------------------------------------------------
    Get the era property which provides access to advanced functionality.
Returns: the era property/**
     * Get the era property which provides access to advanced functionality.
     * 
     * @return the era property
     */
    public Property era() {
        return new Property(this, getChronology().era());
    }

    Get the century of era property which provides access to advanced functionality.
Returns: the year of era property/**
     * Get the century of era property which provides access to advanced functionality.
     * 
     * @return the year of era property
     */
    public Property centuryOfEra() {
        return new Property(this, getChronology().centuryOfEra());
    }

    Get the year of century property which provides access to advanced functionality.
Returns: the year of era property/**
     * Get the year of century property which provides access to advanced functionality.
     * 
     * @return the year of era property
     */
    public Property yearOfCentury() {
        return new Property(this, getChronology().yearOfCentury());
    }

    Get the year of era property which provides access to advanced functionality.
Returns: the year of era property/**
     * Get the year of era property which provides access to advanced functionality.
     * 
     * @return the year of era property
     */
    public Property yearOfEra() {
        return new Property(this, getChronology().yearOfEra());
    }

    Get the year property which provides access to advanced functionality.
Returns: the year property/**
     * Get the year property which provides access to advanced functionality.
     * 
     * @return the year property
     */
    public Property year() {
        return new Property(this, getChronology().year());
    }

    Get the year of a week based year property which provides access to advanced functionality.
Returns: the year of a week based year property/**
     * Get the year of a week based year property which provides access to advanced functionality.
     * 
     * @return the year of a week based year property
     */
    public Property weekyear() {
        return new Property(this, getChronology().weekyear());
    }

    Get the month of year property which provides access to advanced functionality.
Returns: the month of year property/**
     * Get the month of year property which provides access to advanced functionality.
     * 
     * @return the month of year property
     */
    public Property monthOfYear() {
        return new Property(this, getChronology().monthOfYear());
    }

    Get the week of a week based year property which provides access to advanced functionality.
Returns: the week of a week based year property/**
     * Get the week of a week based year property which provides access to advanced functionality.
     * 
     * @return the week of a week based year property
     */
    public Property weekOfWeekyear() {
        return new Property(this, getChronology().weekOfWeekyear());
    }

    Get the day of year property which provides access to advanced functionality.
Returns: the day of year property/**
     * Get the day of year property which provides access to advanced functionality.
     * 
     * @return the day of year property
     */
    public Property dayOfYear() {
        return new Property(this, getChronology().dayOfYear());
    }

    Get the day of month property which provides access to advanced functionality.
Returns: the day of month property/**
     * Get the day of month property which provides access to advanced functionality.
     * 
     * @return the day of month property
     */
    public Property dayOfMonth() {
        return new Property(this, getChronology().dayOfMonth());
    }

    Get the day of week property which provides access to advanced functionality.
Returns: the day of week property/**
     * Get the day of week property which provides access to advanced functionality.
     * 
     * @return the day of week property
     */
    public Property dayOfWeek() {
        return new Property(this, getChronology().dayOfWeek());
    }

    // Time properties
    //-----------------------------------------------------------------------
    Get the hour of day field property which provides access to advanced functionality.
Returns: the hour of day property/**
     * Get the hour of day field property which provides access to advanced functionality.
     * 
     * @return the hour of day property
     */
    public Property hourOfDay() {
        return new Property(this, getChronology().hourOfDay());
    }

    Get the minute of day property which provides access to advanced functionality.
Returns: the minute of day property/**
     * Get the minute of day property which provides access to advanced functionality.
     * 
     * @return the minute of day property
     */
    public Property minuteOfDay() {
        return new Property(this, getChronology().minuteOfDay());
    }

    Get the minute of hour field property which provides access to advanced functionality.
Returns: the minute of hour property/**
     * Get the minute of hour field property which provides access to advanced functionality.
     * 
     * @return the minute of hour property
     */
    public Property minuteOfHour() {
        return new Property(this, getChronology().minuteOfHour());
    }

    Get the second of day property which provides access to advanced functionality.
Returns: the second of day property/**
     * Get the second of day property which provides access to advanced functionality.
     * 
     * @return the second of day property
     */
    public Property secondOfDay() {
        return new Property(this, getChronology().secondOfDay());
    }

    Get the second of minute field property which provides access to advanced functionality.
Returns: the second of minute property/**
     * Get the second of minute field property which provides access to advanced functionality.
     * 
     * @return the second of minute property
     */
    public Property secondOfMinute() {
        return new Property(this, getChronology().secondOfMinute());
    }

    Get the millis of day property which provides access to advanced functionality.
Returns: the millis of day property/**
     * Get the millis of day property which provides access to advanced functionality.
     * 
     * @return the millis of day property
     */
    public Property millisOfDay() {
        return new Property(this, getChronology().millisOfDay());
    }

    Get the millis of second property which provides access to advanced functionality.
Returns: the millis of second property/**
     * Get the millis of second property which provides access to advanced functionality.
     * 
     * @return the millis of second property
     */
    public Property millisOfSecond() {
        return new Property(this, getChronology().millisOfSecond());
    }

    //-----------------------------------------------------------------------
    DateTime.Property binds a DateTime to a DateTimeField allowing powerful
datetime functionality to be easily accessed.

The simplest use of this class is as an alternative get method, here used to
get the year '1972' (as an int) and the month 'December' (as a String).
DateTime dt = new DateTime(1972, 12, 3, 0, 0, 0, 0);
int year = dt.year().get();
String monthStr = dt.month().getAsText();


Methods are also provided that allow date modification. These return new instances
of DateTime - they do not modify the original. The example below yields two
independent immutable date objects 20 years apart.
DateTime dt = new DateTime(1972, 12, 3, 0, 0, 0, 0);
DateTime dt20 = dt.year().addToCopy(20);
 Serious modification of dates (ie. more than just changing one or two fields) should use the MutableDateTime class. 
DateTime.Propery itself is thread-safe and immutable, as well as the
DateTime being operated on.
Author: Stephen Colebourne, Brian S O'Neill
Since: 1.0/**
     * DateTime.Property binds a DateTime to a DateTimeField allowing powerful
     * datetime functionality to be easily accessed.
     * <p>
     * The simplest use of this class is as an alternative get method, here used to
     * get the year '1972' (as an int) and the month 'December' (as a String).
     * <pre>
     * DateTime dt = new DateTime(1972, 12, 3, 0, 0, 0, 0);
     * int year = dt.year().get();
     * String monthStr = dt.month().getAsText();
     * </pre>
     * <p>
     * Methods are also provided that allow date modification. These return new instances
     * of DateTime - they do not modify the original. The example below yields two
     * independent immutable date objects 20 years apart.
     * <pre>
     * DateTime dt = new DateTime(1972, 12, 3, 0, 0, 0, 0);
     * DateTime dt20 = dt.year().addToCopy(20);
     * </pre>
     * Serious modification of dates (ie. more than just changing one or two fields)
     * should use the {@link org.joda.time.MutableDateTime MutableDateTime} class.
     * <p>
     * DateTime.Propery itself is thread-safe and immutable, as well as the
     * DateTime being operated on.
     *
     * @author Stephen Colebourne
     * @author Brian S O'Neill
     * @since 1.0
     */
    public static final class Property extends AbstractReadableInstantFieldProperty {
        
        Serialization version /** Serialization version */
        private static final long serialVersionUID = -6983323811635733510L;
        
        The instant this property is working against /** The instant this property is working against */
        private DateTime iInstant;
        The field this property is working against /** The field this property is working against */
        private DateTimeField iField;
        
        Constructor.
Params: instant –  the instant to set
field –  the field to use/**
         * Constructor.
         * 
         * @param instant  the instant to set
         * @param field  the field to use
         */
        Property(DateTime instant, DateTimeField field) {
            super();
            iInstant = instant;
            iField = field;
        }
        
        Writes the property in a safe serialization format.
/**
         * Writes the property in a safe serialization format.
         */
        private void writeObject(ObjectOutputStream oos) throws IOException {
            oos.writeObject(iInstant);
            oos.writeObject(iField.getType());
        }

        Reads the property from a safe serialization format.
/**
         * Reads the property from a safe serialization format.
         */
        private void readObject(ObjectInputStream oos) throws IOException, ClassNotFoundException {
            iInstant = (DateTime) oos.readObject();
            DateTimeFieldType type = (DateTimeFieldType) oos.readObject();
            iField = type.getField(iInstant.getChronology());
        }

        //-----------------------------------------------------------------------
        Gets the field being used.
Returns: the field/**
         * Gets the field being used.
         * 
         * @return the field
         */
        public DateTimeField getField() {
            return iField;
        }
        
        Gets the milliseconds of the datetime that this property is linked to.
Returns: the milliseconds/**
         * Gets the milliseconds of the datetime that this property is linked to.
         * 
         * @return the milliseconds
         */
        protected long getMillis() {
            return iInstant.getMillis();
        }
        
        Gets the chronology of the datetime that this property is linked to.
Returns: the chronology
Since: 1.4/**
         * Gets the chronology of the datetime that this property is linked to.
         * 
         * @return the chronology
         * @since 1.4
         */
        protected Chronology getChronology() {
            return iInstant.getChronology();
        }
        
        Gets the datetime being used.
Returns: the datetime/**
         * Gets the datetime being used.
         * 
         * @return the datetime
         */
        public DateTime getDateTime() {
            return iInstant;
        }
        
        //-----------------------------------------------------------------------
        Adds to this field in a copy of this DateTime.

The DateTime attached to this property is unchanged by this call.
This operation is faster than converting a DateTime to a MutableDateTime
and back again when setting one field. When setting multiple fields,
it is generally quicker to make the conversion to MutableDateTime.
Params: value –  the value to add to the field in the copy
Throws: IllegalArgumentException – if the value isn't valid
Returns: a copy of the DateTime with the field value changed/**
         * Adds to this field in a copy of this DateTime.
         * <p>
         * The DateTime attached to this property is unchanged by this call.
         * This operation is faster than converting a DateTime to a MutableDateTime
         * and back again when setting one field. When setting multiple fields,
         * it is generally quicker to make the conversion to MutableDateTime.
         * 
         * @param value  the value to add to the field in the copy
         * @return a copy of the DateTime with the field value changed
         * @throws IllegalArgumentException if the value isn't valid
         */
        public DateTime addToCopy(int value) {
            return iInstant.withMillis(iField.add(iInstant.getMillis(), value));
        }
        
        Adds to this field in a copy of this DateTime.

The DateTime attached to this property is unchanged by this call.
This operation is faster than converting a DateTime to a MutableDateTime
and back again when setting one field. When setting multiple fields,
it is generally quicker to make the conversion to MutableDateTime.
Params: value –  the value to add to the field in the copy
Throws: IllegalArgumentException – if the value isn't valid
Returns: a copy of the DateTime with the field value changed/**
         * Adds to this field in a copy of this DateTime.
         * <p>
         * The DateTime attached to this property is unchanged by this call.
         * This operation is faster than converting a DateTime to a MutableDateTime
         * and back again when setting one field. When setting multiple fields,
         * it is generally quicker to make the conversion to MutableDateTime.
         * 
         * @param value  the value to add to the field in the copy
         * @return a copy of the DateTime with the field value changed
         * @throws IllegalArgumentException if the value isn't valid
         */
        public DateTime addToCopy(long value) {
            return iInstant.withMillis(iField.add(iInstant.getMillis(), value));
        }
        
        Adds to this field, possibly wrapped, in a copy of this DateTime.
A wrapped operation only changes this field.
Thus 31st January addWrapField one day goes to the 1st January.

The DateTime attached to this property is unchanged by this call.
This operation is faster than converting a DateTime to a MutableDateTime
and back again when setting one field. When setting multiple fields,
it is generally quicker to make the conversion to MutableDateTime.
Params: value –  the value to add to the field in the copy
Throws: IllegalArgumentException – if the value isn't valid
Returns: a copy of the DateTime with the field value changed/**
         * Adds to this field, possibly wrapped, in a copy of this DateTime.
         * A wrapped operation only changes this field.
         * Thus 31st January addWrapField one day goes to the 1st January.
         * <p>
         * The DateTime attached to this property is unchanged by this call.
         * This operation is faster than converting a DateTime to a MutableDateTime
         * and back again when setting one field. When setting multiple fields,
         * it is generally quicker to make the conversion to MutableDateTime.
         * 
         * @param value  the value to add to the field in the copy
         * @return a copy of the DateTime with the field value changed
         * @throws IllegalArgumentException if the value isn't valid
         */
        public DateTime addWrapFieldToCopy(int value) {
            return iInstant.withMillis(iField.addWrapField(iInstant.getMillis(), value));
        }
        
        //-----------------------------------------------------------------------
        Sets this field in a copy of the DateTime.

The DateTime attached to this property is unchanged by this call.
This operation is faster than converting a DateTime to a MutableDateTime
and back again when setting one field. When setting multiple fields,
it is generally quicker to make the conversion to MutableDateTime.
Params: value –  the value to set the field in the copy to
Throws: IllegalArgumentException – if the value isn't valid
Returns: a copy of the DateTime with the field value changed/**
         * Sets this field in a copy of the DateTime.
         * <p>
         * The DateTime attached to this property is unchanged by this call.
         * This operation is faster than converting a DateTime to a MutableDateTime
         * and back again when setting one field. When setting multiple fields,
         * it is generally quicker to make the conversion to MutableDateTime.
         * 
         * @param value  the value to set the field in the copy to
         * @return a copy of the DateTime with the field value changed
         * @throws IllegalArgumentException if the value isn't valid
         */
        public DateTime setCopy(int value) {
            return iInstant.withMillis(iField.set(iInstant.getMillis(), value));
        }
        
        Sets this field in a copy of the DateTime to a parsed text value.

The DateTime attached to this property is unchanged by this call.
This operation is faster than converting a DateTime to a MutableDateTime
and back again when setting one field. When setting multiple fields,
it is generally quicker to make the conversion to MutableDateTime.
Params: text –  the text value to set
locale –  optional locale to use for selecting a text symbol
Throws: IllegalArgumentException – if the text value isn't valid
Returns: a copy of the DateTime with the field value changed/**
         * Sets this field in a copy of the DateTime to a parsed text value.
         * <p>
         * The DateTime attached to this property is unchanged by this call.
         * This operation is faster than converting a DateTime to a MutableDateTime
         * and back again when setting one field. When setting multiple fields,
         * it is generally quicker to make the conversion to MutableDateTime.
         * 
         * @param text  the text value to set
         * @param locale  optional locale to use for selecting a text symbol
         * @return a copy of the DateTime with the field value changed
         * @throws IllegalArgumentException if the text value isn't valid
         */
        public DateTime setCopy(String text, Locale locale) {
            return iInstant.withMillis(iField.set(iInstant.getMillis(), text, locale));
        }
        
        Sets this field in a copy of the DateTime to a parsed text value.

The DateTime attached to this property is unchanged by this call.
This operation is faster than converting a DateTime to a MutableDateTime
and back again when setting one field. When setting multiple fields,
it is generally quicker to make the conversion to MutableDateTime.
Params: text –  the text value to set
Throws: IllegalArgumentException – if the text value isn't valid
Returns: a copy of the DateTime with the field value changed/**
         * Sets this field in a copy of the DateTime to a parsed text value.
         * <p>
         * The DateTime attached to this property is unchanged by this call.
         * This operation is faster than converting a DateTime to a MutableDateTime
         * and back again when setting one field. When setting multiple fields,
         * it is generally quicker to make the conversion to MutableDateTime.
         * 
         * @param text  the text value to set
         * @return a copy of the DateTime with the field value changed
         * @throws IllegalArgumentException if the text value isn't valid
         */
        public DateTime setCopy(String text) {
            return setCopy(text, null);
        }
        
        //-----------------------------------------------------------------------
        Returns a new DateTime with this field set to the maximum value
for this field.

This operation is useful for obtaining a DateTime on the last day
of the month, as month lengths vary.
DateTime lastDayOfMonth = dt.dayOfMonth().withMaximumValue();

 Where possible, the offset from UTC will be retained, thus applications may need to call DateTime.withLaterOffsetAtOverlap() on the result to force the later time during a DST overlap if desired. 

From v2.2, this method handles a daylight savings time gap, setting the
time to the last instant before the gap.

The DateTime attached to this property is unchanged by this call.
Returns: a copy of the DateTime with this field set to its maximum
Since: 1.2/**
         * Returns a new DateTime with this field set to the maximum value
         * for this field.
         * <p>
         * This operation is useful for obtaining a DateTime on the last day
         * of the month, as month lengths vary.
         * <pre>
         * DateTime lastDayOfMonth = dt.dayOfMonth().withMaximumValue();
         * </pre>
         * <p>
         * Where possible, the offset from UTC will be retained, thus applications
         * may need to call {@link DateTime#withLaterOffsetAtOverlap()} on the result
         * to force the later time during a DST overlap if desired.
         * <p>
         * From v2.2, this method handles a daylight savings time gap, setting the
         * time to the last instant before the gap.
         * <p>
         * The DateTime attached to this property is unchanged by this call.
         *
         * @return a copy of the DateTime with this field set to its maximum
         * @since 1.2
         */
        public DateTime withMaximumValue() {
            try {
                return setCopy(getMaximumValue());
            } catch (RuntimeException ex) {
                if (IllegalInstantException.isIllegalInstant(ex)) {
                    // adding MILLIS_PER_DAY is not perfect, but will work in almost all situations
                    long beforeGap = getChronology().getZone().previousTransition(getMillis() + DateTimeConstants.MILLIS_PER_DAY);
                    return new DateTime(beforeGap, getChronology());
                }
                throw ex;
            }
        }
        
        Returns a new DateTime with this field set to the minimum value
for this field.
 Where possible, the offset from UTC will be retained, thus applications may need to call DateTime.withEarlierOffsetAtOverlap() on the result to force the earlier time during a DST overlap if desired. 

From v2.2, this method handles a daylight savings time gap, setting the
time to the first instant after the gap.

The DateTime attached to this property is unchanged by this call.
Returns: a copy of the DateTime with this field set to its minimum
Since: 1.2/**
         * Returns a new DateTime with this field set to the minimum value
         * for this field.
         * <p>
         * Where possible, the offset from UTC will be retained, thus applications
         * may need to call {@link DateTime#withEarlierOffsetAtOverlap()} on the result
         * to force the earlier time during a DST overlap if desired.
         * <p>
         * From v2.2, this method handles a daylight savings time gap, setting the
         * time to the first instant after the gap.
         * <p>
         * The DateTime attached to this property is unchanged by this call.
         *
         * @return a copy of the DateTime with this field set to its minimum
         * @since 1.2
         */
        public DateTime withMinimumValue() {
            try {
                return setCopy(getMinimumValue());
            } catch (RuntimeException ex) {
                if (IllegalInstantException.isIllegalInstant(ex)) {
                    // subtracting MILLIS_PER_DAY is not perfect, but will work in almost all situations
                    long afterGap = getChronology().getZone().nextTransition(getMillis() - DateTimeConstants.MILLIS_PER_DAY);
                    return new DateTime(afterGap, getChronology());
                }
                throw ex;
            }
        }
        
        //-----------------------------------------------------------------------
        Rounds to the lowest whole unit of this field on a copy of this DateTime.
Returns: a copy of the DateTime with the field value changed/**
         * Rounds to the lowest whole unit of this field on a copy of this DateTime.
         *
         * @return a copy of the DateTime with the field value changed
         */
        public DateTime roundFloorCopy() {
            return iInstant.withMillis(iField.roundFloor(iInstant.getMillis()));
        }
        
        Rounds to the highest whole unit of this field on a copy of this DateTime.
Returns: a copy of the DateTime with the field value changed/**
         * Rounds to the highest whole unit of this field on a copy of this DateTime.
         *
         * @return a copy of the DateTime with the field value changed
         */
        public DateTime roundCeilingCopy() {
            return iInstant.withMillis(iField.roundCeiling(iInstant.getMillis()));
        }
        
        Rounds to the nearest whole unit of this field on a copy of this DateTime,
favoring the floor if halfway.
Returns: a copy of the DateTime with the field value changed/**
         * Rounds to the nearest whole unit of this field on a copy of this DateTime,
         * favoring the floor if halfway.
         *
         * @return a copy of the DateTime with the field value changed
         */
        public DateTime roundHalfFloorCopy() {
            return iInstant.withMillis(iField.roundHalfFloor(iInstant.getMillis()));
        }
        
        Rounds to the nearest whole unit of this field on a copy of this DateTime,
favoring the ceiling if halfway.
Returns: a copy of the DateTime with the field value changed/**
         * Rounds to the nearest whole unit of this field on a copy of this DateTime,
         * favoring the ceiling if halfway.
         *
         * @return a copy of the DateTime with the field value changed
         */
        public DateTime roundHalfCeilingCopy() {
            return iInstant.withMillis(iField.roundHalfCeiling(iInstant.getMillis()));
        }
        
        Rounds to the nearest whole unit of this field on a copy of this
DateTime.  If halfway, the ceiling is favored over the floor only if
it makes this field's value even.
Returns: a copy of the DateTime with the field value changed/**
         * Rounds to the nearest whole unit of this field on a copy of this
         * DateTime.  If halfway, the ceiling is favored over the floor only if
         * it makes this field's value even.
         *
         * @return a copy of the DateTime with the field value changed
         */
        public DateTime roundHalfEvenCopy() {
            return iInstant.withMillis(iField.roundHalfEven(iInstant.getMillis()));
        }
    }

}
Author:	Stephen Colebourne, Kandarp Shah, Brian S O'Neill
See Also:	MutableDateTime
Since:	1.0
Params:	zone – the time zone, not null
Returns:	the current date-time, not null
Since:	2.0
Params:	chronology – the chronology, not null
Returns:	the current date-time, not null
Since:	2.0
Params:	str – the string to parse, not null formatter – the formatter to use, not null
Since:	2.0
Params:	zone – the time zone, null means default zone
See Also:	now(DateTimeZone)
Params:	chronology – the chronology, null means ISOChronology in default zone
See Also:	now(Chronology)
Params:	instant – the datetime object, null means now
Throws:	IllegalArgumentException – if the instant is invalid
Params:	year – the year monthOfYear – the month of the year, from 1 to 12 dayOfMonth – the day of the month, from 1 to 31 hourOfDay – the hour of the day, from 0 to 23 minuteOfHour – the minute of the hour, from 0 to 59
Since:	2.0
Params:	zone – time zone to apply, or default if null
Returns:	a DateTime using the same millis
Params:	chronology – chronology to apply, or ISOChronology if null
Returns:	a DateTime using the same millis
Params:	newMillis – the new millis, from 1970-01-01T00:00:00Z
Returns:	a copy of this datetime with different millis
Params:	newChronology – the new chronology, null means ISO default
Returns:	a copy of this datetime with a different chronology
Params:	newZone – the new time zone
See Also:	withZoneRetainFields
Returns:	a copy of this datetime with a different time zone
Params:	newZone – the new time zone, null means default
See Also:	withZone
Returns:	a copy of this datetime with a different time zone
Params:	year – the new year value monthOfYear – the new monthOfYear value dayOfMonth – the new dayOfMonth value
Throws:	IllegalArgumentException – if any value if invalid
Returns:	a copy of this datetime with a different date
Params:	date – the local date
Throws:	IllegalArgumentException – if the time-of-day is invalid for the date NullPointerException – if the date is null
Returns:	a copy of this datetime with a different date
Params:	hourOfDay – the hour of the day minuteOfHour – the minute of the hour secondOfMinute – the second of the minute millisOfSecond – the millisecond of the second
Throws:	IllegalArgumentException – if any value if invalid
Returns:	a copy of this datetime with a different time
Params:	time – the local time
Throws:	IllegalArgumentException – if the time-of-day is invalid for the date NullPointerException – if the time is null
Returns:	a copy of this datetime with a different time
Params:	partial – the partial set of fields to apply to this datetime, null ignored
Throws:	IllegalArgumentException – if any value is invalid
Returns:	a copy of this datetime with a different set of fields
Params:	fieldType – the field type to set, not null value – the value to set
Throws:	IllegalArgumentException – if the value is null or invalid
Returns:	a copy of this datetime with the field set
/

joda-time/ joda-time/ 2.10/ org/joda/time/DateTime.java
