1 /*

     2  * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Oracle designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Oracle in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

    22  * or visit www.oracle.com if you need additional information or have any

    23  * questions.

    24  */

    25 

    26 /*

    27  * This file is available under and governed by the GNU General Public

    28  * License version 2 only, as published by the Free Software Foundation.

    29  * However, the following notice accompanied the original version of this

    30  * file:

    31  *

    32  * Copyright (c) 2007-2012, Stephen Colebourne & Michael Nascimento Santos

    33  *

    34  * All rights reserved.

    35  *

    36  * Redistribution and use in source and binary forms, with or without

    37  * modification, are permitted provided that the following conditions are met:

    38  *

    39  *  * Redistributions of source code must retain the above copyright notice,

    40  *    this list of conditions and the following disclaimer.

    41  *

    42  *  * Redistributions in binary form must reproduce the above copyright notice,

    43  *    this list of conditions and the following disclaimer in the documentation

    44  *    and/or other materials provided with the distribution.

    45  *

    46  *  * Neither the name of JSR-310 nor the names of its contributors

    47  *    may be used to endorse or promote products derived from this software

    48  *    without specific prior written permission.

    49  *

    50  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS

    51  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT

    52  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR

    53  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR

    54  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,

    55  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,

    56  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR

    57  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF

    58  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING

    59  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS

    60  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

    61  */

    62 package java.time.temporal;

    63 

    64 import static java.time.temporal.ChronoField.EPOCH_DAY;

    65 import static java.time.temporal.ChronoField.INSTANT_SECONDS;

    66 import static java.time.temporal.ChronoField.NANO_OF_DAY;

    67 import static java.time.temporal.ChronoField.OFFSET_SECONDS;

    68 import static java.time.temporal.ChronoUnit.NANOS;

    69 

    70 import java.io.IOException;

    71 import java.io.InvalidObjectException;

    72 import java.io.ObjectInput;

    73 import java.io.ObjectOutput;

    74 import java.io.ObjectStreamException;

    75 import java.io.Serializable;

    76 import java.time.Clock;

    77 import java.time.DateTimeException;

    78 import java.time.DayOfWeek;

    79 import java.time.Instant;

    80 import java.time.LocalDate;

    81 import java.time.LocalDateTime;

    82 import java.time.LocalTime;

    83 import java.time.Month;

    84 import java.time.ZoneId;

    85 import java.time.ZoneOffset;

    86 import java.time.ZonedDateTime;

    87 import java.time.format.DateTimeFormatter;

    88 import java.time.format.DateTimeFormatters;

    89 import java.time.format.DateTimeParseException;

    90 import java.time.zone.ZoneRules;

    91 import java.util.Comparator;

    92 import java.util.Objects;

    93 

    94 /**

    95  * A date-time with an offset from UTC/Greenwich in the ISO-8601 calendar system,

    96  * such as {@code 2007-12-03T10:15:30+01:00}.

    97  * <p>

    98  * {@code OffsetDateTime} is an immutable representation of a date-time with an offset.

    99  * This class stores all date and time fields, to a precision of nanoseconds,

   100  * as well as the offset from UTC/Greenwich. For example, the value

   101  * "2nd October 2007 at 13:45.30.123456789 +02:00" can be stored in an {@code OffsetDateTime}.

   102  * <p>

   103  * {@code OffsetDateTime}, {@link java.time.ZonedDateTime} and {@link java.time.Instant} all store an instant

   104  * on the time-line to nanosecond precision.

   105  * {@code Instant} is the simplest, simply representing the instant.

   106  * {@code OffsetDateTime} adds to the instant the offset from UTC/Greenwich, which allows

   107  * the local date-time to be obtained.

   108  * {@code ZonedDateTime} adds full time-zone rules.

   109  * <p>

   110  * It is intended that {@code ZonedDateTime} or {@code Instant} is used to model data

   111  * in simpler applications. This class may be used when modeling date-time concepts in

   112  * more detail, or when communicating to a database or in a network protocol.

   113  *

   114  * <h3>Specification for implementors</h3>

   115  * This class is immutable and thread-safe.

   116  *

   117  * @since 1.8

   118  */

   119 public final class OffsetDateTime

   120         implements Temporal, TemporalAdjuster, Comparable<OffsetDateTime>, Serializable {

   121 

   122     /**

   123      * The minimum supported {@code OffsetDateTime}, '-999999999-01-01T00:00:00+18:00'.

   124      * This is the local date-time of midnight at the start of the minimum date

   125      * in the maximum offset (larger offsets are earlier on the time-line).

   126      * This combines {@link LocalDateTime#MIN} and {@link ZoneOffset#MAX}.

   127      * This could be used by an application as a "far past" date-time.

   128      */

   129     public static final OffsetDateTime MIN = LocalDateTime.MIN.atOffset(ZoneOffset.MAX);

   130     /**

   131      * The maximum supported {@code OffsetDateTime}, '+999999999-12-31T23:59:59.999999999-18:00'.

   132      * This is the local date-time just before midnight at the end of the maximum date

   133      * in the minimum offset (larger negative offsets are later on the time-line).

   134      * This combines {@link LocalDateTime#MAX} and {@link ZoneOffset#MIN}.

   135      * This could be used by an application as a "far future" date-time.

   136      */

   137     public static final OffsetDateTime MAX = LocalDateTime.MAX.atOffset(ZoneOffset.MIN);

   138 

   139     /**

   140      * Comparator for two {@code OffsetDateTime} instances based solely on the instant.

   141      * <p>

   142      * This method differs from the comparison in {@link #compareTo} in that it

   143      * only compares the underlying instant.

   144      *

   145      * @see #isAfter

   146      * @see #isBefore

   147      * @see #isEqual

   148      */

   149     public static final Comparator<OffsetDateTime> INSTANT_COMPARATOR = new Comparator<OffsetDateTime>() {

   150         @Override

   151         public int compare(OffsetDateTime datetime1, OffsetDateTime datetime2) {

   152             int cmp = Long.compare(datetime1.toEpochSecond(), datetime2.toEpochSecond());

   153             if (cmp == 0) {

   154                 cmp = Long.compare(datetime1.getTime().toNanoOfDay(), datetime2.getTime().toNanoOfDay());

   155             }

   156             return cmp;

   157         }

   158     };

   159 

   160     /**

   161      * Serialization version.

   162      */

   163     private static final long serialVersionUID = 2287754244819255394L;

   164 

   165     /**

   166      * The local date-time.

   167      */

   168     private final LocalDateTime dateTime;

   169     /**

   170      * The offset from UTC/Greenwich.

   171      */

   172     private final ZoneOffset offset;

   173 

   174     //-----------------------------------------------------------------------

   175     /**

   176      * Obtains the current date-time from the system clock in the default time-zone.

   177      * <p>

   178      * This will query the {@link java.time.Clock#systemDefaultZone() system clock} in the default

   179      * time-zone to obtain the current date-time.

   180      * The offset will be calculated from the time-zone in the clock.

   181      * <p>

   182      * Using this method will prevent the ability to use an alternate clock for testing

   183      * because the clock is hard-coded.

   184      *

   185      * @return the current date-time using the system clock, not null

   186      */

   187     public static OffsetDateTime now() {

   188         return now(Clock.systemDefaultZone());

   189     }

   190 

   191     /**

   192      * Obtains the current date-time from the system clock in the specified time-zone.

   193      * <p>

   194      * This will query the {@link Clock#system(java.time.ZoneId) system clock} to obtain the current date-time.

   195      * Specifying the time-zone avoids dependence on the default time-zone.

   196      * The offset will be calculated from the specified time-zone.

   197      * <p>

   198      * Using this method will prevent the ability to use an alternate clock for testing

   199      * because the clock is hard-coded.

   200      *

   201      * @param zone  the zone ID to use, not null

   202      * @return the current date-time using the system clock, not null

   203      */

   204     public static OffsetDateTime now(ZoneId zone) {

   205         return now(Clock.system(zone));

   206     }

   207 

   208     /**

   209      * Obtains the current date-time from the specified clock.

   210      * <p>

   211      * This will query the specified clock to obtain the current date-time.

   212      * The offset will be calculated from the time-zone in the clock.

   213      * <p>

   214      * Using this method allows the use of an alternate clock for testing.

   215      * The alternate clock may be introduced using {@link Clock dependency injection}.

   216      *

   217      * @param clock  the clock to use, not null

   218      * @return the current date-time, not null

   219      */

   220     public static OffsetDateTime now(Clock clock) {

   221         Objects.requireNonNull(clock, "clock");

   222         final Instant now = clock.instant();  // called once

   223         return ofInstant(now, clock.getZone().getRules().getOffset(now));

   224     }

   225 

   226     //-----------------------------------------------------------------------

   227     /**

   228      * Obtains an instance of {@code OffsetDateTime} from a date, time and offset.

   229      * <p>

   230      * This creates an offset date-time with the specified local date, time and offset.

   231      *

   232      * @param date  the local date, not null

   233      * @param time  the local time, not null

   234      * @param offset  the zone offset, not null

   235      * @return the offset date-time, not null

   236      */

   237     public static OffsetDateTime of(LocalDate date, LocalTime time, ZoneOffset offset) {

   238         LocalDateTime dt = LocalDateTime.of(date, time);

   239         return new OffsetDateTime(dt, offset);

   240     }

   241 

   242     /**

   243      * Obtains an instance of {@code OffsetDateTime} from a date-time and offset.

   244      * <p>

   245      * This creates an offset date-time with the specified local date-time and offset.

   246      *

   247      * @param dateTime  the local date-time, not null

   248      * @param offset  the zone offset, not null

   249      * @return the offset date-time, not null

   250      */

   251     public static OffsetDateTime of(LocalDateTime dateTime, ZoneOffset offset) {

   252         return new OffsetDateTime(dateTime, offset);

   253     }

   254 

   255     /**

   256      * Obtains an instance of {@code OffsetDateTime} from a {@code ZonedDateTime}.

   257      * <p>

   258      * This creates an offset date-time with the same local date-time and offset as

   259      * the zoned date-time. The result will have the same instant as the input.

   260      *

   261      * @param zonedDateTime  the zoned date-time to convert from, not null

   262      * @return the offset date-time, not null

   263      * @throws DateTimeException if the result exceeds the supported range

   264      */

   265     public static OffsetDateTime of(ZonedDateTime zonedDateTime) {

   266         Objects.requireNonNull(zonedDateTime, "zonedDateTime");

   267         return new OffsetDateTime(zonedDateTime.getDateTime(), zonedDateTime.getOffset());

   268     }

   269 

   270     //-----------------------------------------------------------------------

   271     /**

   272      * Obtains an instance of {@code OffsetDateTime} from an {@code Instant} and zone ID.

   273      * <p>

   274      * This creates an offset date-time with the same instant as that specified.

   275      * Finding the offset from UTC/Greenwich is simple as there is only one valid

   276      * offset for each instant.

   277      *

   278      * @param instant  the instant to create the date-time from, not null

   279      * @param zone  the time-zone, which may be an offset, not null

   280      * @return the offset date-time, not null

   281      * @throws DateTimeException if the result exceeds the supported range

   282      */

   283     public static OffsetDateTime ofInstant(Instant instant, ZoneId zone) {

   284         Objects.requireNonNull(instant, "instant");

   285         Objects.requireNonNull(zone, "zone");

   286         ZoneRules rules = zone.getRules();

   287         ZoneOffset offset = rules.getOffset(instant);

   288         LocalDateTime ldt = LocalDateTime.ofEpochSecond(instant.getEpochSecond(), instant.getNano(), offset);

   289         return new OffsetDateTime(ldt, offset);

   290     }

   291 

   292     //-----------------------------------------------------------------------

   293     /**

   294      * Obtains an instance of {@code OffsetDateTime} from a temporal object.

   295      * <p>

   296      * A {@code TemporalAccessor} represents some form of date and time information.

   297      * This factory converts the arbitrary temporal object to an instance of {@code OffsetDateTime}.

   298      * <p>

   299      * The conversion extracts and combines {@code LocalDateTime} and {@code ZoneOffset}.

   300      * If that fails it will try to extract and combine {@code Instant} and {@code ZoneOffset}.

   301      * <p>

   302      * This method matches the signature of the functional interface {@link TemporalQuery}

   303      * allowing it to be used in queries via method reference, {@code OffsetDateTime::from}.

   304      *

   305      * @param temporal  the temporal object to convert, not null

   306      * @return the offset date-time, not null

   307      * @throws DateTimeException if unable to convert to an {@code OffsetDateTime}

   308      */

   309     public static OffsetDateTime from(TemporalAccessor temporal) {

   310         if (temporal instanceof OffsetDateTime) {

   311             return (OffsetDateTime) temporal;

   312         }

   313         ZoneOffset offset = ZoneOffset.from(temporal);

   314         try {

   315             try {

   316                 LocalDateTime ldt = LocalDateTime.from(temporal);

   317                 return OffsetDateTime.of(ldt, offset);

   318             } catch (DateTimeException ignore) {

   319                 Instant instant = Instant.from(temporal);

   320                 return OffsetDateTime.ofInstant(instant, offset);

   321             }

   322         } catch (DateTimeException ex) {

   323             throw new DateTimeException("Unable to obtain OffsetDateTime from TemporalAccessor: " + temporal.getClass(), ex);

   324         }

   325     }

   326 

   327     //-----------------------------------------------------------------------

   328     /**

   329      * Obtains an instance of {@code OffsetDateTime} from a text string

   330      * such as {@code 2007-12-03T10:15:30+01:00}.

   331      * <p>

   332      * The string must represent a valid date-time and is parsed using

   333      * {@link java.time.format.DateTimeFormatters#isoOffsetDateTime()}.

   334      *

   335      * @param text  the text to parse such as "2007-12-03T10:15:30+01:00", not null

   336      * @return the parsed offset date-time, not null

   337      * @throws DateTimeParseException if the text cannot be parsed

   338      */

   339     public static OffsetDateTime parse(CharSequence text) {

   340         return parse(text, DateTimeFormatters.isoOffsetDateTime());

   341     }

   342 

   343     /**

   344      * Obtains an instance of {@code OffsetDateTime} from a text string using a specific formatter.

   345      * <p>

   346      * The text is parsed using the formatter, returning a date-time.

   347      *

   348      * @param text  the text to parse, not null

   349      * @param formatter  the formatter to use, not null

   350      * @return the parsed offset date-time, not null

   351      * @throws DateTimeParseException if the text cannot be parsed

   352      */

   353     public static OffsetDateTime parse(CharSequence text, DateTimeFormatter formatter) {

   354         Objects.requireNonNull(formatter, "formatter");

   355         return formatter.parse(text, OffsetDateTime::from);

   356     }

   357 

   358     //-----------------------------------------------------------------------

   359     /**

   360      * Constructor.

   361      *

   362      * @param dateTime  the local date-time, not null

   363      * @param offset  the zone offset, not null

   364      */

   365     private OffsetDateTime(LocalDateTime dateTime, ZoneOffset offset) {

   366         this.dateTime = Objects.requireNonNull(dateTime, "dateTime");

   367         this.offset = Objects.requireNonNull(offset, "offset");

   368     }

   369 

   370     /**

   371      * Returns a new date-time based on this one, returning {@code this} where possible.

   372      *

   373      * @param dateTime  the date-time to create with, not null

   374      * @param offset  the zone offset to create with, not null

   375      */

   376     private OffsetDateTime with(LocalDateTime dateTime, ZoneOffset offset) {

   377         if (this.dateTime == dateTime && this.offset.equals(offset)) {

   378             return this;

   379         }

   380         return new OffsetDateTime(dateTime, offset);

   381     }

   382 

   383     //-----------------------------------------------------------------------

   384     /**

   385      * Checks if the specified field is supported.

   386      * <p>

   387      * This checks if this date-time can be queried for the specified field.

   388      * If false, then calling the {@link #range(TemporalField) range} and

   389      * {@link #get(TemporalField) get} methods will throw an exception.

   390      * <p>

   391      * If the field is a {@link ChronoField} then the query is implemented here.

   392      * The supported fields are:

   393      * <ul>

   394      * <li>{@code NANO_OF_SECOND}

   395      * <li>{@code NANO_OF_DAY}

   396      * <li>{@code MICRO_OF_SECOND}

   397      * <li>{@code MICRO_OF_DAY}

   398      * <li>{@code MILLI_OF_SECOND}

   399      * <li>{@code MILLI_OF_DAY}

   400      * <li>{@code SECOND_OF_MINUTE}

   401      * <li>{@code SECOND_OF_DAY}

   402      * <li>{@code MINUTE_OF_HOUR}

   403      * <li>{@code MINUTE_OF_DAY}

   404      * <li>{@code HOUR_OF_AMPM}

   405      * <li>{@code CLOCK_HOUR_OF_AMPM}

   406      * <li>{@code HOUR_OF_DAY}

   407      * <li>{@code CLOCK_HOUR_OF_DAY}

   408      * <li>{@code AMPM_OF_DAY}

   409      * <li>{@code DAY_OF_WEEK}

   410      * <li>{@code ALIGNED_DAY_OF_WEEK_IN_MONTH}

   411      * <li>{@code ALIGNED_DAY_OF_WEEK_IN_YEAR}

   412      * <li>{@code DAY_OF_MONTH}

   413      * <li>{@code DAY_OF_YEAR}

   414      * <li>{@code EPOCH_DAY}

   415      * <li>{@code ALIGNED_WEEK_OF_MONTH}

   416      * <li>{@code ALIGNED_WEEK_OF_YEAR}

   417      * <li>{@code MONTH_OF_YEAR}

   418      * <li>{@code EPOCH_MONTH}

   419      * <li>{@code YEAR_OF_ERA}

   420      * <li>{@code YEAR}

   421      * <li>{@code ERA}

   422      * <li>{@code INSTANT_SECONDS}

   423      * <li>{@code OFFSET_SECONDS}

   424      * </ul>

   425      * All other {@code ChronoField} instances will return false.

   426      * <p>

   427      * If the field is not a {@code ChronoField}, then the result of this method

   428      * is obtained by invoking {@code TemporalField.doIsSupported(TemporalAccessor)}

   429      * passing {@code this} as the argument.

   430      * Whether the field is supported is determined by the field.

   431      *

   432      * @param field  the field to check, null returns false

   433      * @return true if the field is supported on this date-time, false if not

   434      */

   435     @Override

   436     public boolean isSupported(TemporalField field) {

   437         return field instanceof ChronoField || (field != null && field.doIsSupported(this));

   438     }

   439 

   440     /**

   441      * Gets the range of valid values for the specified field.

   442      * <p>

   443      * The range object expresses the minimum and maximum valid values for a field.

   444      * This date-time is used to enhance the accuracy of the returned range.

   445      * If it is not possible to return the range, because the field is not supported

   446      * or for some other reason, an exception is thrown.

   447      * <p>

   448      * If the field is a {@link ChronoField} then the query is implemented here.

   449      * The {@link #isSupported(TemporalField) supported fields} will return

   450      * appropriate range instances.

   451      * All other {@code ChronoField} instances will throw a {@code DateTimeException}.

   452      * <p>

   453      * If the field is not a {@code ChronoField}, then the result of this method

   454      * is obtained by invoking {@code TemporalField.doRange(TemporalAccessor)}

   455      * passing {@code this} as the argument.

   456      * Whether the range can be obtained is determined by the field.

   457      *

   458      * @param field  the field to query the range for, not null

   459      * @return the range of valid values for the field, not null

   460      * @throws DateTimeException if the range for the field cannot be obtained

   461      */

   462     @Override

   463     public ValueRange range(TemporalField field) {

   464         if (field instanceof ChronoField) {

   465             if (field == INSTANT_SECONDS || field == OFFSET_SECONDS) {

   466                 return field.range();

   467             }

   468             return dateTime.range(field);

   469         }

   470         return field.doRange(this);

   471     }

   472 

   473     /**

   474      * Gets the value of the specified field from this date-time as an {@code int}.

   475      * <p>

   476      * This queries this date-time for the value for the specified field.

   477      * The returned value will always be within the valid range of values for the field.

   478      * If it is not possible to return the value, because the field is not supported

   479      * or for some other reason, an exception is thrown.

   480      * <p>

   481      * If the field is a {@link ChronoField} then the query is implemented here.

   482      * The {@link #isSupported(TemporalField) supported fields} will return valid

   483      * values based on this date-time, except {@code NANO_OF_DAY}, {@code MICRO_OF_DAY},

   484      * {@code EPOCH_DAY}, {@code EPOCH_MONTH} and {@code INSTANT_SECONDS} which are too

   485      * large to fit in an {@code int} and throw a {@code DateTimeException}.

   486      * All other {@code ChronoField} instances will throw a {@code DateTimeException}.

   487      * <p>

   488      * If the field is not a {@code ChronoField}, then the result of this method

   489      * is obtained by invoking {@code TemporalField.doGet(TemporalAccessor)}

   490      * passing {@code this} as the argument. Whether the value can be obtained,

   491      * and what the value represents, is determined by the field.

   492      *

   493      * @param field  the field to get, not null

   494      * @return the value for the field

   495      * @throws DateTimeException if a value for the field cannot be obtained

   496      * @throws ArithmeticException if numeric overflow occurs

   497      */

   498     @Override

   499     public int get(TemporalField field) {

   500         if (field instanceof ChronoField) {

   501             switch ((ChronoField) field) {

   502                 case INSTANT_SECONDS: throw new DateTimeException("Field too large for an int: " + field);

   503                 case OFFSET_SECONDS: return getOffset().getTotalSeconds();

   504             }

   505             return dateTime.get(field);

   506         }

   507         return Temporal.super.get(field);

   508     }

   509 

   510     /**

   511      * Gets the value of the specified field from this date-time as a {@code long}.

   512      * <p>

   513      * This queries this date-time for the value for the specified field.

   514      * If it is not possible to return the value, because the field is not supported

   515      * or for some other reason, an exception is thrown.

   516      * <p>

   517      * If the field is a {@link ChronoField} then the query is implemented here.

   518      * The {@link #isSupported(TemporalField) supported fields} will return valid

   519      * values based on this date-time.

   520      * All other {@code ChronoField} instances will throw a {@code DateTimeException}.

   521      * <p>

   522      * If the field is not a {@code ChronoField}, then the result of this method

   523      * is obtained by invoking {@code TemporalField.doGet(TemporalAccessor)}

   524      * passing {@code this} as the argument. Whether the value can be obtained,

   525      * and what the value represents, is determined by the field.

   526      *

   527      * @param field  the field to get, not null

   528      * @return the value for the field

   529      * @throws DateTimeException if a value for the field cannot be obtained

   530      * @throws ArithmeticException if numeric overflow occurs

   531      */

   532     @Override

   533     public long getLong(TemporalField field) {

   534         if (field instanceof ChronoField) {

   535             switch ((ChronoField) field) {

   536                 case INSTANT_SECONDS: return toEpochSecond();

   537                 case OFFSET_SECONDS: return getOffset().getTotalSeconds();

   538             }

   539             return dateTime.getLong(field);

   540         }

   541         return field.doGet(this);

   542     }

   543 

   544     //-----------------------------------------------------------------------

   545     /**

   546      * Gets the zone offset, such as '+01:00'.

   547      * <p>

   548      * This is the offset of the local date-time from UTC/Greenwich.

   549      *

   550      * @return the zone offset, not null

   551      */

   552     public ZoneOffset getOffset() {

   553         return offset;

   554     }

   555 

   556     /**

   557      * Returns a copy of this {@code OffsetDateTime} with the specified offset ensuring

   558      * that the result has the same local date-time.

   559      * <p>

   560      * This method returns an object with the same {@code LocalDateTime} and the specified {@code ZoneOffset}.

   561      * No calculation is needed or performed.

   562      * For example, if this time represents {@code 2007-12-03T10:30+02:00} and the offset specified is

   563      * {@code +03:00}, then this method will return {@code 2007-12-03T10:30+03:00}.

   564      * <p>

   565      * To take into account the difference between the offsets, and adjust the time fields,

   566      * use {@link #withOffsetSameInstant}.

   567      * <p>

   568      * This instance is immutable and unaffected by this method call.

   569      *

   570      * @param offset  the zone offset to change to, not null

   571      * @return an {@code OffsetDateTime} based on this date-time with the requested offset, not null

   572      */

   573     public OffsetDateTime withOffsetSameLocal(ZoneOffset offset) {

   574         return with(dateTime, offset);

   575     }

   576 

   577     /**

   578      * Returns a copy of this {@code OffsetDateTime} with the specified offset ensuring

   579      * that the result is at the same instant.

   580      * <p>

   581      * This method returns an object with the specified {@code ZoneOffset} and a {@code LocalDateTime}

   582      * adjusted by the difference between the two offsets.

   583      * This will result in the old and new objects representing the same instant.

   584      * This is useful for finding the local time in a different offset.

   585      * For example, if this time represents {@code 2007-12-03T10:30+02:00} and the offset specified is

   586      * {@code +03:00}, then this method will return {@code 2007-12-03T11:30+03:00}.

   587      * <p>

   588      * To change the offset without adjusting the local time use {@link #withOffsetSameLocal}.

   589      * <p>

   590      * This instance is immutable and unaffected by this method call.

   591      *

   592      * @param offset  the zone offset to change to, not null

   593      * @return an {@code OffsetDateTime} based on this date-time with the requested offset, not null

   594      * @throws DateTimeException if the result exceeds the supported date range

   595      */

   596     public OffsetDateTime withOffsetSameInstant(ZoneOffset offset) {

   597         if (offset.equals(this.offset)) {

   598             return this;

   599         }

   600         int difference = offset.getTotalSeconds() - this.offset.getTotalSeconds();

   601         LocalDateTime adjusted = dateTime.plusSeconds(difference);

   602         return new OffsetDateTime(adjusted, offset);

   603     }

   604 

   605     //-----------------------------------------------------------------------

   606     /**

   607      * Gets the {@code LocalDateTime} part of this offset date-time.

   608      * <p>

   609      * This returns a {@code LocalDateTime} with the same year, month, day and time

   610      * as this date-time.

   611      *

   612      * @return the local date-time part of this date-time, not null

   613      */

   614     public LocalDateTime getDateTime() {

   615         return dateTime;

   616     }

   617 

   618     //-----------------------------------------------------------------------

   619     /**

   620      * Gets the {@code LocalDate} part of this date-time.

   621      * <p>

   622      * This returns a {@code LocalDate} with the same year, month and day

   623      * as this date-time.

   624      *

   625      * @return the date part of this date-time, not null

   626      */

   627     public LocalDate getDate() {

   628         return dateTime.getDate();

   629     }

   630 

   631     /**

   632      * Gets the year field.

   633      * <p>

   634      * This method returns the primitive {@code int} value for the year.

   635      * <p>

   636      * The year returned by this method is proleptic as per {@code get(YEAR)}.

   637      * To obtain the year-of-era, use {@code get(YEAR_OF_ERA}.

   638      *

   639      * @return the year, from MIN_YEAR to MAX_YEAR

   640      */

   641     public int getYear() {

   642         return dateTime.getYear();

   643     }

   644 

   645     /**

   646      * Gets the month-of-year field from 1 to 12.

   647      * <p>

   648      * This method returns the month as an {@code int} from 1 to 12.

   649      * Application code is frequently clearer if the enum {@link Month}

   650      * is used by calling {@link #getMonth()}.

   651      *

   652      * @return the month-of-year, from 1 to 12

   653      * @see #getMonth()

   654      */

   655     public int getMonthValue() {

   656         return dateTime.getMonthValue();

   657     }

   658 

   659     /**

   660      * Gets the month-of-year field using the {@code Month} enum.

   661      * <p>

   662      * This method returns the enum {@link Month} for the month.

   663      * This avoids confusion as to what {@code int} values mean.

   664      * If you need access to the primitive {@code int} value then the enum

   665      * provides the {@link Month#getValue() int value}.

   666      *

   667      * @return the month-of-year, not null

   668      * @see #getMonthValue()

   669      */

   670     public Month getMonth() {

   671         return dateTime.getMonth();

   672     }

   673 

   674     /**

   675      * Gets the day-of-month field.

   676      * <p>

   677      * This method returns the primitive {@code int} value for the day-of-month.

   678      *

   679      * @return the day-of-month, from 1 to 31

   680      */

   681     public int getDayOfMonth() {

   682         return dateTime.getDayOfMonth();

   683     }

   684 

   685     /**

   686      * Gets the day-of-year field.

   687      * <p>

   688      * This method returns the primitive {@code int} value for the day-of-year.

   689      *

   690      * @return the day-of-year, from 1 to 365, or 366 in a leap year

   691      */

   692     public int getDayOfYear() {

   693         return dateTime.getDayOfYear();

   694     }

   695 

   696     /**

   697      * Gets the day-of-week field, which is an enum {@code DayOfWeek}.

   698      * <p>

   699      * This method returns the enum {@link java.time.DayOfWeek} for the day-of-week.

   700      * This avoids confusion as to what {@code int} values mean.

   701      * If you need access to the primitive {@code int} value then the enum

   702      * provides the {@link java.time.DayOfWeek#getValue() int value}.

   703      * <p>

   704      * Additional information can be obtained from the {@code DayOfWeek}.

   705      * This includes textual names of the values.

   706      *

   707      * @return the day-of-week, not null

   708      */

   709     public DayOfWeek getDayOfWeek() {

   710         return dateTime.getDayOfWeek();

   711     }

   712 

   713     //-----------------------------------------------------------------------

   714     /**

   715      * Gets the {@code LocalTime} part of this date-time.

   716      * <p>

   717      * This returns a {@code LocalTime} with the same hour, minute, second and

   718      * nanosecond as this date-time.

   719      *

   720      * @return the time part of this date-time, not null

   721      */

   722     public LocalTime getTime() {

   723         return dateTime.getTime();

   724     }

   725 

   726     /**

   727      * Gets the hour-of-day field.

   728      *

   729      * @return the hour-of-day, from 0 to 23

   730      */

   731     public int getHour() {

   732         return dateTime.getHour();

   733     }

   734 

   735     /**

   736      * Gets the minute-of-hour field.

   737      *

   738      * @return the minute-of-hour, from 0 to 59

   739      */

   740     public int getMinute() {

   741         return dateTime.getMinute();

   742     }

   743 

   744     /**

   745      * Gets the second-of-minute field.

   746      *

   747      * @return the second-of-minute, from 0 to 59

   748      */

   749     public int getSecond() {

   750         return dateTime.getSecond();

   751     }

   752 

   753     /**

   754      * Gets the nano-of-second field.

   755      *

   756      * @return the nano-of-second, from 0 to 999,999,999

   757      */

   758     public int getNano() {

   759         return dateTime.getNano();

   760     }

   761 

   762     //-----------------------------------------------------------------------

   763     /**

   764      * Returns an adjusted copy of this date-time.

   765      * <p>

   766      * This returns a new {@code OffsetDateTime}, based on this one, with the date-time adjusted.

   767      * The adjustment takes place using the specified adjuster strategy object.

   768      * Read the documentation of the adjuster to understand what adjustment will be made.

   769      * <p>

   770      * A simple adjuster might simply set the one of the fields, such as the year field.

   771      * A more complex adjuster might set the date to the last day of the month.

   772      * A selection of common adjustments is provided in {@link java.time.temporal.Adjusters}.

   773      * These include finding the "last day of the month" and "next Wednesday".

   774      * Key date-time classes also implement the {@code TemporalAdjuster} interface,

   775      * such as {@link Month} and {@link java.time.temporal.MonthDay MonthDay}.

   776      * The adjuster is responsible for handling special cases, such as the varying

   777      * lengths of month and leap years.

   778      * <p>

   779      * For example this code returns a date on the last day of July:

   780      * <pre>

   781      *  import static java.time.Month.*;

   782      *  import static java.time.temporal.Adjusters.*;

   783      *

   784      *  result = offsetDateTime.with(JULY).with(lastDayOfMonth());

   785      * </pre>

   786      * <p>

   787      * The classes {@link LocalDate}, {@link LocalTime} and {@link ZoneOffset} implement

   788      * {@code TemporalAdjuster}, thus this method can be used to change the date, time or offset:

   789      * <pre>

   790      *  result = offsetDateTime.with(date);

   791      *  result = offsetDateTime.with(time);

   792      *  result = offsetDateTime.with(offset);

   793      * </pre>

   794      * <p>

   795      * The result of this method is obtained by invoking the

   796      * {@link TemporalAdjuster#adjustInto(Temporal)} method on the

   797      * specified adjuster passing {@code this} as the argument.

   798      * <p>

   799      * This instance is immutable and unaffected by this method call.

   800      *

   801      * @param adjuster the adjuster to use, not null

   802      * @return an {@code OffsetDateTime} based on {@code this} with the adjustment made, not null

   803      * @throws DateTimeException if the adjustment cannot be made

   804      * @throws ArithmeticException if numeric overflow occurs

   805      */

   806     @Override

   807     public OffsetDateTime with(TemporalAdjuster adjuster) {

   808         // optimizations

   809         if (adjuster instanceof LocalDate || adjuster instanceof LocalTime || adjuster instanceof LocalDateTime) {

   810             return with(dateTime.with(adjuster), offset);

   811         } else if (adjuster instanceof Instant) {

   812             return ofInstant((Instant) adjuster, offset);

   813         } else if (adjuster instanceof ZoneOffset) {

   814             return with(dateTime, (ZoneOffset) adjuster);

   815         } else if (adjuster instanceof OffsetDateTime) {

   816             return (OffsetDateTime) adjuster;

   817         }

   818         return (OffsetDateTime) adjuster.adjustInto(this);

   819     }

   820 

   821     /**

   822      * Returns a copy of this date-time with the specified field set to a new value.

   823      * <p>

   824      * This returns a new {@code OffsetDateTime}, based on this one, with the value

   825      * for the specified field changed.

   826      * This can be used to change any supported field, such as the year, month or day-of-month.

   827      * If it is not possible to set the value, because the field is not supported or for

   828      * some other reason, an exception is thrown.

   829      * <p>

   830      * In some cases, changing the specified field can cause the resulting date-time to become invalid,

   831      * such as changing the month from 31st January to February would make the day-of-month invalid.

   832      * In cases like this, the field is responsible for resolving the date. Typically it will choose

   833      * the previous valid date, which would be the last valid day of February in this example.

   834      * <p>

   835      * If the field is a {@link ChronoField} then the adjustment is implemented here.

   836      * <p>

   837      * The {@code INSTANT_SECONDS} field will return a date-time with the specified instant.

   838      * The offset and nano-of-second are unchanged.

   839      * If the new instant value is outside the valid range then a {@code DateTimeException} will be thrown.

   840      * <p>

   841      * The {@code OFFSET_SECONDS} field will return a date-time with the specified offset.

   842      * The local date-time is unaltered. If the new offset value is outside the valid range

   843      * then a {@code DateTimeException} will be thrown.

   844      * <p>

   845      * The other {@link #isSupported(TemporalField) supported fields} will behave as per

   846      * the matching method on {@link LocalDateTime#with(TemporalField, long) LocalDateTime}.

   847      * In this case, the offset is not part of the calculation and will be unchanged.

   848      * <p>

   849      * All other {@code ChronoField} instances will throw a {@code DateTimeException}.

   850      * <p>

   851      * If the field is not a {@code ChronoField}, then the result of this method

   852      * is obtained by invoking {@code TemporalField.doWith(Temporal, long)}

   853      * passing {@code this} as the argument. In this case, the field determines

   854      * whether and how to adjust the instant.

   855      * <p>

   856      * This instance is immutable and unaffected by this method call.

   857      *

   858      * @param field  the field to set in the result, not null

   859      * @param newValue  the new value of the field in the result

   860      * @return an {@code OffsetDateTime} based on {@code this} with the specified field set, not null

   861      * @throws DateTimeException if the field cannot be set

   862      * @throws ArithmeticException if numeric overflow occurs

   863      */

   864     @Override

   865     public OffsetDateTime with(TemporalField field, long newValue) {

   866         if (field instanceof ChronoField) {

   867             ChronoField f = (ChronoField) field;

   868             switch (f) {

   869                 case INSTANT_SECONDS: return ofInstant(Instant.ofEpochSecond(newValue, getNano()), offset);

   870                 case OFFSET_SECONDS: {

   871                     return with(dateTime, ZoneOffset.ofTotalSeconds(f.checkValidIntValue(newValue)));

   872                 }

   873             }

   874             return with(dateTime.with(field, newValue), offset);

   875         }

   876         return field.doWith(this, newValue);

   877     }

   878 

   879     //-----------------------------------------------------------------------

   880     /**

   881      * Returns a copy of this {@code OffsetDateTime} with the year altered.

   882      * The offset does not affect the calculation and will be the same in the result.

   883      * If the day-of-month is invalid for the year, it will be changed to the last valid day of the month.

   884      * <p>

   885      * This instance is immutable and unaffected by this method call.

   886      *

   887      * @param year  the year to set in the result, from MIN_YEAR to MAX_YEAR

   888      * @return an {@code OffsetDateTime} based on this date-time with the requested year, not null

   889      * @throws DateTimeException if the year value is invalid

   890      */

   891     public OffsetDateTime withYear(int year) {

   892         return with(dateTime.withYear(year), offset);

   893     }

   894 

   895     /**

   896      * Returns a copy of this {@code OffsetDateTime} with the month-of-year altered.

   897      * The offset does not affect the calculation and will be the same in the result.

   898      * If the day-of-month is invalid for the year, it will be changed to the last valid day of the month.

   899      * <p>

   900      * This instance is immutable and unaffected by this method call.

   901      *

   902      * @param month  the month-of-year to set in the result, from 1 (January) to 12 (December)

   903      * @return an {@code OffsetDateTime} based on this date-time with the requested month, not null

   904      * @throws DateTimeException if the month-of-year value is invalid

   905      */

   906     public OffsetDateTime withMonth(int month) {

   907         return with(dateTime.withMonth(month), offset);

   908     }

   909 

   910     /**

   911      * Returns a copy of this {@code OffsetDateTime} with the day-of-month altered.

   912      * If the resulting {@code OffsetDateTime} is invalid, an exception is thrown.

   913      * The offset does not affect the calculation and will be the same in the result.

   914      * <p>

   915      * This instance is immutable and unaffected by this method call.

   916      *

   917      * @param dayOfMonth  the day-of-month to set in the result, from 1 to 28-31

   918      * @return an {@code OffsetDateTime} based on this date-time with the requested day, not null

   919      * @throws DateTimeException if the day-of-month value is invalid

   920      * @throws DateTimeException if the day-of-month is invalid for the month-year

   921      */

   922     public OffsetDateTime withDayOfMonth(int dayOfMonth) {

   923         return with(dateTime.withDayOfMonth(dayOfMonth), offset);

   924     }

   925 

   926     /**

   927      * Returns a copy of this {@code OffsetDateTime} with the day-of-year altered.

   928      * If the resulting {@code OffsetDateTime} is invalid, an exception is thrown.

   929      * <p>

   930      * This instance is immutable and unaffected by this method call.

   931      *

   932      * @param dayOfYear  the day-of-year to set in the result, from 1 to 365-366

   933      * @return an {@code OffsetDateTime} based on this date with the requested day, not null

   934      * @throws DateTimeException if the day-of-year value is invalid

   935      * @throws DateTimeException if the day-of-year is invalid for the year

   936      */

   937     public OffsetDateTime withDayOfYear(int dayOfYear) {

   938         return with(dateTime.withDayOfYear(dayOfYear), offset);

   939     }

   940 

   941     //-----------------------------------------------------------------------

   942     /**

   943      * Returns a copy of this {@code OffsetDateTime} with the hour-of-day value altered.

   944      * <p>

   945      * The offset does not affect the calculation and will be the same in the result.

   946      * <p>

   947      * This instance is immutable and unaffected by this method call.

   948      *

   949      * @param hour  the hour-of-day to set in the result, from 0 to 23

   950      * @return an {@code OffsetDateTime} based on this date-time with the requested hour, not null

   951      * @throws DateTimeException if the hour value is invalid

   952      */

   953     public OffsetDateTime withHour(int hour) {

   954         return with(dateTime.withHour(hour), offset);

   955     }

   956 

   957     /**

   958      * Returns a copy of this {@code OffsetDateTime} with the minute-of-hour value altered.

   959      * <p>

   960      * The offset does not affect the calculation and will be the same in the result.

   961      * <p>

   962      * This instance is immutable and unaffected by this method call.

   963      *

   964      * @param minute  the minute-of-hour to set in the result, from 0 to 59

   965      * @return an {@code OffsetDateTime} based on this date-time with the requested minute, not null

   966      * @throws DateTimeException if the minute value is invalid

   967      */

   968     public OffsetDateTime withMinute(int minute) {

   969         return with(dateTime.withMinute(minute), offset);

   970     }

   971 

   972     /**

   973      * Returns a copy of this {@code OffsetDateTime} with the second-of-minute value altered.

   974      * <p>

   975      * The offset does not affect the calculation and will be the same in the result.

   976      * <p>

   977      * This instance is immutable and unaffected by this method call.

   978      *

   979      * @param second  the second-of-minute to set in the result, from 0 to 59

   980      * @return an {@code OffsetDateTime} based on this date-time with the requested second, not null

   981      * @throws DateTimeException if the second value is invalid

   982      */

   983     public OffsetDateTime withSecond(int second) {

   984         return with(dateTime.withSecond(second), offset);

   985     }

   986 

   987     /**

   988      * Returns a copy of this {@code OffsetDateTime} with the nano-of-second value altered.

   989      * <p>

   990      * The offset does not affect the calculation and will be the same in the result.

   991      * <p>

   992      * This instance is immutable and unaffected by this method call.

   993      *

   994      * @param nanoOfSecond  the nano-of-second to set in the result, from 0 to 999,999,999

   995      * @return an {@code OffsetDateTime} based on this date-time with the requested nanosecond, not null

   996      * @throws DateTimeException if the nanos value is invalid

   997      */

   998     public OffsetDateTime withNano(int nanoOfSecond) {

   999         return with(dateTime.withNano(nanoOfSecond), offset);

  1000     }

  1001 

  1002     //-----------------------------------------------------------------------

  1003     /**

  1004      * Returns a copy of this {@code OffsetDateTime} with the time truncated.

  1005      * <p>

  1006      * Truncation returns a copy of the original date-time with fields

  1007      * smaller than the specified unit set to zero.

  1008      * For example, truncating with the {@link ChronoUnit#MINUTES minutes} unit

  1009      * will set the second-of-minute and nano-of-second field to zero.

  1010      * <p>

  1011      * Not all units are accepted. The {@link ChronoUnit#DAYS days} unit and time

  1012      * units with an exact duration can be used, other units throw an exception.

  1013      * <p>

  1014      * The offset does not affect the calculation and will be the same in the result.

  1015      * <p>

  1016      * This instance is immutable and unaffected by this method call.

  1017      *

  1018      * @param unit  the unit to truncate to, not null

  1019      * @return an {@code OffsetDateTime} based on this date-time with the time truncated, not null

  1020      * @throws DateTimeException if unable to truncate

  1021      */

  1022     public OffsetDateTime truncatedTo(TemporalUnit unit) {

  1023         return with(dateTime.truncatedTo(unit), offset);

  1024     }

  1025 

  1026     //-----------------------------------------------------------------------

  1027     /**

  1028      * Returns a copy of this date-time with the specified period added.

  1029      * <p>

  1030      * This method returns a new date-time based on this time with the specified period added.

  1031      * The adder is typically {@link java.time.Period} but may be any other type implementing

  1032      * the {@link TemporalAdder} interface.

  1033      * The calculation is delegated to the specified adjuster, which typically calls

  1034      * back to {@link #plus(long, TemporalUnit)}.

  1035      * The offset is not part of the calculation and will be unchanged in the result.

  1036      * <p>

  1037      * This instance is immutable and unaffected by this method call.

  1038      *

  1039      * @param adder  the adder to use, not null

  1040      * @return an {@code OffsetDateTime} based on this date-time with the addition made, not null

  1041      * @throws DateTimeException if the addition cannot be made

  1042      * @throws ArithmeticException if numeric overflow occurs

  1043      */

  1044     @Override

  1045     public OffsetDateTime plus(TemporalAdder adder) {

  1046         return (OffsetDateTime) adder.addTo(this);

  1047     }

  1048 

  1049     /**

  1050      * Returns a copy of this date-time with the specified period added.

  1051      * <p>

  1052      * This method returns a new date-time based on this date-time with the specified period added.

  1053      * This can be used to add any period that is defined by a unit, for example to add years, months or days.

  1054      * The unit is responsible for the details of the calculation, including the resolution

  1055      * of any edge cases in the calculation.

  1056      * The offset is not part of the calculation and will be unchanged in the result.

  1057      * <p>

  1058      * This instance is immutable and unaffected by this method call.

  1059      *

  1060      * @param amountToAdd  the amount of the unit to add to the result, may be negative

  1061      * @param unit  the unit of the period to add, not null

  1062      * @return an {@code OffsetDateTime} based on this date-time with the specified period added, not null

  1063      * @throws DateTimeException if the unit cannot be added to this type

  1064      */

  1065     @Override

  1066     public OffsetDateTime plus(long amountToAdd, TemporalUnit unit) {

  1067         if (unit instanceof ChronoUnit) {

  1068             return with(dateTime.plus(amountToAdd, unit), offset);

  1069         }

  1070         return unit.doPlus(this, amountToAdd);

  1071     }

  1072 

  1073     //-----------------------------------------------------------------------

  1074     /**

  1075      * Returns a copy of this {@code OffsetDateTime} with the specified period in years added.

  1076      * <p>

  1077      * This method adds the specified amount to the years field in three steps:

  1078      * <ol>

  1079      * <li>Add the input years to the year field</li>

  1080      * <li>Check if the resulting date would be invalid</li>

  1081      * <li>Adjust the day-of-month to the last valid day if necessary</li>

  1082      * </ol>

  1083      * <p>

  1084      * For example, 2008-02-29 (leap year) plus one year would result in the

  1085      * invalid date 2009-02-29 (standard year). Instead of returning an invalid

  1086      * result, the last valid day of the month, 2009-02-28, is selected instead.

  1087      * <p>

  1088      * This instance is immutable and unaffected by this method call.

  1089      *

  1090      * @param years  the years to add, may be negative

  1091      * @return an {@code OffsetDateTime} based on this date-time with the years added, not null

  1092      * @throws DateTimeException if the result exceeds the supported date range

  1093      */

  1094     public OffsetDateTime plusYears(long years) {

  1095         return with(dateTime.plusYears(years), offset);

  1096     }

  1097 

  1098     /**

  1099      * Returns a copy of this {@code OffsetDateTime} with the specified period in months added.

  1100      * <p>

  1101      * This method adds the specified amount to the months field in three steps:

  1102      * <ol>

  1103      * <li>Add the input months to the month-of-year field</li>

  1104      * <li>Check if the resulting date would be invalid</li>

  1105      * <li>Adjust the day-of-month to the last valid day if necessary</li>

  1106      * </ol>

  1107      * <p>

  1108      * For example, 2007-03-31 plus one month would result in the invalid date

  1109      * 2007-04-31. Instead of returning an invalid result, the last valid day

  1110      * of the month, 2007-04-30, is selected instead.

  1111      * <p>

  1112      * This instance is immutable and unaffected by this method call.

  1113      *

  1114      * @param months  the months to add, may be negative

  1115      * @return an {@code OffsetDateTime} based on this date-time with the months added, not null

  1116      * @throws DateTimeException if the result exceeds the supported date range

  1117      */

  1118     public OffsetDateTime plusMonths(long months) {

  1119         return with(dateTime.plusMonths(months), offset);

  1120     }

  1121 

  1122     /**

  1123      * Returns a copy of this OffsetDateTime with the specified period in weeks added.

  1124      * <p>

  1125      * This method adds the specified amount in weeks to the days field incrementing

  1126      * the month and year fields as necessary to ensure the result remains valid.

  1127      * The result is only invalid if the maximum/minimum year is exceeded.

  1128      * <p>

  1129      * For example, 2008-12-31 plus one week would result in the 2009-01-07.

  1130      * <p>

  1131      * This instance is immutable and unaffected by this method call.

  1132      *

  1133      * @param weeks  the weeks to add, may be negative

  1134      * @return an {@code OffsetDateTime} based on this date-time with the weeks added, not null

  1135      * @throws DateTimeException if the result exceeds the supported date range