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.NANO_OF_DAY;

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

    66 import static java.time.temporal.ChronoLocalDateTimeImpl.NANOS_PER_HOUR;

    67 import static java.time.temporal.ChronoLocalDateTimeImpl.NANOS_PER_MINUTE;

    68 import static java.time.temporal.ChronoLocalDateTimeImpl.NANOS_PER_SECOND;

    69 import static java.time.temporal.ChronoLocalDateTimeImpl.SECONDS_PER_DAY;

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

    71 

    72 import java.io.IOException;

    73 import java.io.InvalidObjectException;

    74 import java.io.ObjectInput;

    75 import java.io.ObjectOutput;

    76 import java.io.ObjectStreamException;

    77 import java.io.Serializable;

    78 import java.time.Clock;

    79 import java.time.DateTimeException;

    80 import java.time.Instant;

    81 import java.time.LocalDate;

    82 import java.time.LocalTime;

    83 import java.time.ZoneId;

    84 import java.time.ZoneOffset;

    85 import java.time.format.DateTimeFormatter;

    86 import java.time.format.DateTimeFormatters;

    87 import java.time.format.DateTimeParseException;

    88 import java.time.zone.ZoneRules;

    89 import java.util.Objects;

    90 

    91 /**

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

    93  * such as {@code 10:15:30+01:00}.

    94  * <p>

    95  * {@code OffsetTime} is an immutable date-time object that represents a time, often

    96  * viewed as hour-minute-second-offset.

    97  * This class stores all time fields, to a precision of nanoseconds,

    98  * as well as a zone offset.

    99  * For example, the value "13:45.30.123456789+02:00" can be stored

   100  * in an {@code OffsetTime}.

   101  *

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

   103  * This class is immutable and thread-safe.

   104  *

   105  * @since 1.8

   106  */

   107 public final class OffsetTime

   108         implements Temporal, TemporalAdjuster, Comparable<OffsetTime>, Serializable {

   109 

   110     /**

   111      * The minimum supported {@code OffsetTime}, '00:00:00+18:00'.

   112      * This is the time of midnight at the start of the day in the maximum offset

   113      * (larger offsets are earlier on the time-line).

   114      * This combines {@link LocalTime#MIN} and {@link ZoneOffset#MAX}.

   115      * This could be used by an application as a "far past" date.

   116      */

   117     public static final OffsetTime MIN = LocalTime.MIN.atOffset(ZoneOffset.MAX);

   118     /**

   119      * The maximum supported {@code OffsetTime}, '23:59:59.999999999-18:00'.

   120      * This is the time just before midnight at the end of the day in the minimum offset

   121      * (larger negative offsets are later on the time-line).

   122      * This combines {@link LocalTime#MAX} and {@link ZoneOffset#MIN}.

   123      * This could be used by an application as a "far future" date.

   124      */

   125     public static final OffsetTime MAX = LocalTime.MAX.atOffset(ZoneOffset.MIN);

   126 

   127     /**

   128      * Serialization version.

   129      */

   130     private static final long serialVersionUID = 7264499704384272492L;

   131 

   132     /**

   133      * The local date-time.

   134      */

   135     private final LocalTime time;

   136     /**

   137      * The offset from UTC/Greenwich.

   138      */

   139     private final ZoneOffset offset;

   140 

   141     //-----------------------------------------------------------------------

   142     /**

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

   144      * <p>

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

   146      * time-zone to obtain the current time.

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

   148      * <p>

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

   150      * because the clock is hard-coded.

   151      *

   152      * @return the current time using the system clock, not null

   153      */

   154     public static OffsetTime now() {

   155         return now(Clock.systemDefaultZone());

   156     }

   157 

   158     /**

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

   160      * <p>

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

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

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

   164      * <p>

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

   166      * because the clock is hard-coded.

   167      *

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

   169      * @return the current time using the system clock, not null

   170      */

   171     public static OffsetTime now(ZoneId zone) {

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

   173     }

   174 

   175     /**

   176      * Obtains the current time from the specified clock.

   177      * <p>

   178      * This will query the specified clock to obtain the current time.

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

   180      * <p>

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

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

   183      *

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

   185      * @return the current time, not null

   186      */

   187     public static OffsetTime now(Clock clock) {

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

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

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

   191     }

   192 

   193     //-----------------------------------------------------------------------

   194     /**

   195      * Obtains an instance of {@code OffsetTime} from a local time and an offset.

   196      *

   197      * @param time  the local time, not null

   198      * @param offset  the zone offset, not null

   199      * @return the offset time, not null

   200      */

   201     public static OffsetTime of(LocalTime time, ZoneOffset offset) {

   202         return new OffsetTime(time, offset);

   203     }

   204 

   205     //-----------------------------------------------------------------------

   206     /**

   207      * Obtains an instance of {@code OffsetTime} from an {@code Instant} and zone ID.

   208      * <p>

   209      * This creates an offset time with the same instant as that specified.

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

   211      * offset for each instant.

   212      * <p>

   213      * The date component of the instant is dropped during the conversion.

   214      * This means that the conversion can never fail due to the instant being

   215      * out of the valid range of dates.

   216      *

   217      * @param instant  the instant to create the time from, not null

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

   219      * @return the offset time, not null

   220      */

   221     public static OffsetTime ofInstant(Instant instant, ZoneId zone) {

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

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

   224         ZoneRules rules = zone.getRules();

   225         ZoneOffset offset = rules.getOffset(instant);

   226         long secsOfDay = instant.getEpochSecond() % SECONDS_PER_DAY;

   227         secsOfDay = (secsOfDay + offset.getTotalSeconds()) % SECONDS_PER_DAY;

   228         if (secsOfDay < 0) {

   229             secsOfDay += SECONDS_PER_DAY;

   230         }

   231         LocalTime time = LocalTime.ofSecondOfDay(secsOfDay, instant.getNano());

   232         return new OffsetTime(time, offset);

   233     }

   234 

   235     //-----------------------------------------------------------------------

   236     /**

   237      * Obtains an instance of {@code OffsetTime} from a temporal object.

   238      * <p>

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

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

   241      * <p>

   242      * The conversion extracts and combines {@code LocalTime} and {@code ZoneOffset}.

   243      * <p>

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

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

   246      *

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

   248      * @return the offset time, not null

   249      * @throws DateTimeException if unable to convert to an {@code OffsetTime}

   250      */

   251     public static OffsetTime from(TemporalAccessor temporal) {

   252         if (temporal instanceof OffsetTime) {

   253             return (OffsetTime) temporal;

   254         }

   255         try {

   256             LocalTime time = LocalTime.from(temporal);

   257             ZoneOffset offset = ZoneOffset.from(temporal);

   258             return new OffsetTime(time, offset);

   259         } catch (DateTimeException ex) {

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

   261         }

   262     }

   263 

   264     //-----------------------------------------------------------------------

   265     /**

   266      * Obtains an instance of {@code OffsetTime} from a text string such as {@code 10:15:30+01:00}.

   267      * <p>

   268      * The string must represent a valid time and is parsed using

   269      * {@link java.time.format.DateTimeFormatters#isoOffsetTime()}.

   270      *

   271      * @param text  the text to parse such as "10:15:30+01:00", not null

   272      * @return the parsed local time, not null

   273      * @throws DateTimeParseException if the text cannot be parsed

   274      */

   275     public static OffsetTime parse(CharSequence text) {

   276         return parse(text, DateTimeFormatters.isoOffsetTime());

   277     }

   278 

   279     /**

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

   281      * <p>

   282      * The text is parsed using the formatter, returning a time.

   283      *

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

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

   286      * @return the parsed offset time, not null

   287      * @throws DateTimeParseException if the text cannot be parsed

   288      */

   289     public static OffsetTime parse(CharSequence text, DateTimeFormatter formatter) {

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

   291         return formatter.parse(text, OffsetTime::from);

   292     }

   293 

   294     //-----------------------------------------------------------------------

   295     /**

   296      * Constructor.

   297      *

   298      * @param time  the local time, not null

   299      * @param offset  the zone offset, not null

   300      */

   301     private OffsetTime(LocalTime time, ZoneOffset offset) {

   302         this.time = Objects.requireNonNull(time, "time");

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

   304     }

   305 

   306     /**

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

   308      *

   309      * @param time  the time to create with, not null

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

   311      */

   312     private OffsetTime with(LocalTime time, ZoneOffset offset) {

   313         if (this.time == time && this.offset.equals(offset)) {

   314             return this;

   315         }

   316         return new OffsetTime(time, offset);

   317     }

   318 

   319     //-----------------------------------------------------------------------

   320     /**

   321      * Checks if the specified field is supported.

   322      * <p>

   323      * This checks if this time can be queried for the specified field.

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

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

   326      * <p>

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

   328      * The supported fields are:

   329      * <ul>

   330      * <li>{@code NANO_OF_SECOND}

   331      * <li>{@code NANO_OF_DAY}

   332      * <li>{@code MICRO_OF_SECOND}

   333      * <li>{@code MICRO_OF_DAY}

   334      * <li>{@code MILLI_OF_SECOND}

   335      * <li>{@code MILLI_OF_DAY}

   336      * <li>{@code SECOND_OF_MINUTE}

   337      * <li>{@code SECOND_OF_DAY}

   338      * <li>{@code MINUTE_OF_HOUR}

   339      * <li>{@code MINUTE_OF_DAY}

   340      * <li>{@code HOUR_OF_AMPM}

   341      * <li>{@code CLOCK_HOUR_OF_AMPM}

   342      * <li>{@code HOUR_OF_DAY}

   343      * <li>{@code CLOCK_HOUR_OF_DAY}

   344      * <li>{@code AMPM_OF_DAY}

   345      * <li>{@code OFFSET_SECONDS}

   346      * </ul>

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

   348      * <p>

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

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

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

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

   353      *

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

   355      * @return true if the field is supported on this time, false if not

   356      */

   357     @Override

   358     public boolean isSupported(TemporalField field) {

   359         if (field instanceof ChronoField) {

   360             return ((ChronoField) field).isTimeField() || field == OFFSET_SECONDS;

   361         }

   362         return field != null && field.doIsSupported(this);

   363     }

   364 

   365     /**

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

   367      * <p>

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

   369      * This time is used to enhance the accuracy of the returned range.

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

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

   372      * <p>

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

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

   375      * appropriate range instances.

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

   377      * <p>

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

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

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

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

   382      *

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

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

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

   386      */

   387     @Override

   388     public ValueRange range(TemporalField field) {

   389         if (field instanceof ChronoField) {

   390             if (field == OFFSET_SECONDS) {

   391                 return field.range();

   392             }

   393             return time.range(field);

   394         }

   395         return field.doRange(this);

   396     }

   397 

   398     /**

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

   400      * <p>

   401      * This queries this time for the value for the specified field.

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

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

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

   405      * <p>

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

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

   408      * values based on this time, except {@code NANO_OF_DAY} and {@code MICRO_OF_DAY}

   409      * which are too large to fit in an {@code int} and throw a {@code DateTimeException}.

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

   411      * <p>

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

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

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

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

   416      *

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

   418      * @return the value for the field

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

   420      * @throws ArithmeticException if numeric overflow occurs

   421      */

   422     @Override  // override for Javadoc

   423     public int get(TemporalField field) {

   424         return Temporal.super.get(field);

   425     }

   426 

   427     /**

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

   429      * <p>

   430      * This queries this time for the value for the specified field.

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

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

   433      * <p>

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

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

   436      * values based on this time.

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

   438      * <p>

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

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

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

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

   443      *

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

   445      * @return the value for the field

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

   447      * @throws ArithmeticException if numeric overflow occurs

   448      */

   449     @Override

   450     public long getLong(TemporalField field) {

   451         if (field instanceof ChronoField) {

   452             if (field == OFFSET_SECONDS) {

   453                 return getOffset().getTotalSeconds();

   454             }

   455             return time.getLong(field);

   456         }

   457         return field.doGet(this);

   458     }

   459 

   460     //-----------------------------------------------------------------------

   461     /**

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

   463      * <p>

   464      * This is the offset of the local time from UTC/Greenwich.

   465      *

   466      * @return the zone offset, not null

   467      */

   468     public ZoneOffset getOffset() {

   469         return offset;

   470     }

   471 

   472     /**

   473      * Returns a copy of this {@code OffsetTime} with the specified offset ensuring

   474      * that the result has the same local time.

   475      * <p>

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

   477      * No calculation is needed or performed.

   478      * For example, if this time represents {@code 10:30+02:00} and the offset specified is

   479      * {@code +03:00}, then this method will return {@code 10:30+03:00}.

   480      * <p>

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

   482      * use {@link #withOffsetSameInstant}.

   483      * <p>

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

   485      *

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

   487      * @return an {@code OffsetTime} based on this time with the requested offset, not null

   488      */

   489     public OffsetTime withOffsetSameLocal(ZoneOffset offset) {

   490         return offset != null && offset.equals(this.offset) ? this : new OffsetTime(time, offset);

   491     }

   492 

   493     /**

   494      * Returns a copy of this {@code OffsetTime} with the specified offset ensuring

   495      * that the result is at the same instant on an implied day.

   496      * <p>

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

   498      * adjusted by the difference between the two offsets.

   499      * This will result in the old and new objects representing the same instant an an implied day.

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

   501      * For example, if this time represents {@code 10:30+02:00} and the offset specified is

   502      * {@code +03:00}, then this method will return {@code 11:30+03:00}.

   503      * <p>

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

   505      * <p>

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

   507      *

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

   509      * @return an {@code OffsetTime} based on this time with the requested offset, not null

   510      */

   511     public OffsetTime withOffsetSameInstant(ZoneOffset offset) {

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

   513             return this;

   514         }

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

   516         LocalTime adjusted = time.plusSeconds(difference);

   517         return new OffsetTime(adjusted, offset);

   518     }

   519 

   520     //-----------------------------------------------------------------------

   521     /**

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

   523      * <p>

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

   525      * nanosecond as this date-time.

   526      *

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

   528      */

   529     public LocalTime getTime() {

   530         return time;

   531     }

   532 

   533     //-----------------------------------------------------------------------

   534     /**

   535      * Gets the hour-of-day field.

   536      *

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

   538      */

   539     public int getHour() {

   540         return time.getHour();

   541     }

   542 

   543     /**

   544      * Gets the minute-of-hour field.

   545      *

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

   547      */

   548     public int getMinute() {

   549         return time.getMinute();

   550     }

   551 

   552     /**

   553      * Gets the second-of-minute field.

   554      *

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

   556      */

   557     public int getSecond() {

   558         return time.getSecond();

   559     }

   560 

   561     /**

   562      * Gets the nano-of-second field.

   563      *

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

   565      */

   566     public int getNano() {

   567         return time.getNano();

   568     }

   569 

   570     //-----------------------------------------------------------------------

   571     /**

   572      * Returns an adjusted copy of this time.

   573      * <p>

   574      * This returns a new {@code OffsetTime}, based on this one, with the time adjusted.

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

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

   577      * <p>

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

   579      * A more complex adjuster might set the time to the last hour of the day.

   580      * <p>

   581      * The classes {@link LocalTime} and {@link ZoneOffset} implement {@code TemporalAdjuster},

   582      * thus this method can be used to change the time or offset:

   583      * <pre>

   584      *  result = offsetTime.with(time);

   585      *  result = offsetTime.with(offset);

   586      * </pre>

   587      * <p>

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

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

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

   591      * <p>

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

   593      *

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

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

   596      * @throws DateTimeException if the adjustment cannot be made

   597      * @throws ArithmeticException if numeric overflow occurs

   598      */

   599     @Override

   600     public OffsetTime with(TemporalAdjuster adjuster) {

   601         // optimizations

   602         if (adjuster instanceof LocalTime) {

   603             return with((LocalTime) adjuster, offset);

   604         } else if (adjuster instanceof ZoneOffset) {

   605             return with(time, (ZoneOffset) adjuster);

   606         } else if (adjuster instanceof OffsetTime) {

   607             return (OffsetTime) adjuster;

   608         }

   609         return (OffsetTime) adjuster.adjustInto(this);

   610     }

   611 

   612     /**

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

   614      * <p>

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

   616      * for the specified field changed.

   617      * This can be used to change any supported field, such as the hour, minute or second.

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

   619      * some other reason, an exception is thrown.

   620      * <p>

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

   622      * <p>

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

   624      * The local time is unaltered. If the new offset value is outside the valid range

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

   626      * <p>

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

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

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

   630      * <p>

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

   632      * <p>

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

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

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

   636      * whether and how to adjust the instant.

   637      * <p>

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

   639      *

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

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

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

   643      * @throws DateTimeException if the field cannot be set

   644      * @throws ArithmeticException if numeric overflow occurs

   645      */

   646     @Override

   647     public OffsetTime with(TemporalField field, long newValue) {

   648         if (field instanceof ChronoField) {

   649             if (field == OFFSET_SECONDS) {

   650                 ChronoField f = (ChronoField) field;

   651                 return with(time, ZoneOffset.ofTotalSeconds(f.checkValidIntValue(newValue)));

   652             }

   653             return with(time.with(field, newValue), offset);

   654         }

   655         return field.doWith(this, newValue);

   656     }

   657 

   658     //-----------------------------------------------------------------------

   659     /**

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

   661      * <p>

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

   663      * <p>

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

   665      *

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

   667      * @return an {@code OffsetTime} based on this time with the requested hour, not null

   668      * @throws DateTimeException if the hour value is invalid

   669      */

   670     public OffsetTime withHour(int hour) {

   671         return with(time.withHour(hour), offset);

   672     }

   673 

   674     /**

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

   676      * <p>

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

   678      * <p>

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

   680      *

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

   682      * @return an {@code OffsetTime} based on this time with the requested minute, not null

   683      * @throws DateTimeException if the minute value is invalid

   684      */

   685     public OffsetTime withMinute(int minute) {

   686         return with(time.withMinute(minute), offset);

   687     }

   688 

   689     /**

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

   691      * <p>

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

   693      * <p>

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

   695      *

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

   697      * @return an {@code OffsetTime} based on this time with the requested second, not null

   698      * @throws DateTimeException if the second value is invalid

   699      */

   700     public OffsetTime withSecond(int second) {

   701         return with(time.withSecond(second), offset);

   702     }

   703 

   704     /**

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

   706      * <p>

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

   708      * <p>

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

   710      *

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

   712      * @return an {@code OffsetTime} based on this time with the requested nanosecond, not null

   713      * @throws DateTimeException if the nanos value is invalid

   714      */

   715     public OffsetTime withNano(int nanoOfSecond) {

   716         return with(time.withNano(nanoOfSecond), offset);

   717     }

   718 

   719     //-----------------------------------------------------------------------

   720     /**

   721      * Returns a copy of this {@code OffsetTime} with the time truncated.

   722      * <p>

   723      * Truncation returns a copy of the original time with fields

   724      * smaller than the specified unit set to zero.

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

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

   727      * <p>

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

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

   730      * <p>

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

   732      * <p>

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

   734      *

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

   736      * @return an {@code OffsetTime} based on this time with the time truncated, not null

   737      * @throws DateTimeException if unable to truncate

   738      */

   739     public OffsetTime truncatedTo(TemporalUnit unit) {

   740         return with(time.truncatedTo(unit), offset);

   741     }

   742 

   743     //-----------------------------------------------------------------------

   744     /**

   745      * Returns a copy of this date with the specified period added.

   746      * <p>

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

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

   749      * the {@link TemporalAdder} interface.

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

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

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

   753      * <p>

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

   755      *

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

   757      * @return an {@code OffsetTime} based on this time with the addition made, not null

   758      * @throws DateTimeException if the addition cannot be made

   759      * @throws ArithmeticException if numeric overflow occurs

   760      */

   761     @Override

   762     public OffsetTime plus(TemporalAdder adder) {

   763         return (OffsetTime) adder.addTo(this);

   764     }

   765 

   766     /**

   767      * Returns a copy of this time with the specified period added.

   768      * <p>

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

   770      * This can be used to add any period that is defined by a unit, for example to add hours, minutes or seconds.

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

   772      * of any edge cases in the calculation.

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

   774      * <p>

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

   776      *

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

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

   779      * @return an {@code OffsetTime} based on this time with the specified period added, not null

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

   781      */

   782     @Override

   783     public OffsetTime plus(long amountToAdd, TemporalUnit unit) {

   784         if (unit instanceof ChronoUnit) {

   785             return with(time.plus(amountToAdd, unit), offset);

   786         }

   787         return unit.doPlus(this, amountToAdd);

   788     }

   789 

   790     //-----------------------------------------------------------------------

   791     /**

   792      * Returns a copy of this {@code OffsetTime} with the specified period in hours added.

   793      * <p>

   794      * This adds the specified number of hours to this time, returning a new time.

   795      * The calculation wraps around midnight.

   796      * <p>

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

   798      *

   799      * @param hours  the hours to add, may be negative

   800      * @return an {@code OffsetTime} based on this time with the hours added, not null

   801      */

   802     public OffsetTime plusHours(long hours) {

   803         return with(time.plusHours(hours), offset);

   804     }

   805 

   806     /**

   807      * Returns a copy of this {@code OffsetTime} with the specified period in minutes added.

   808      * <p>

   809      * This adds the specified number of minutes to this time, returning a new time.

   810      * The calculation wraps around midnight.

   811      * <p>

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

   813      *

   814      * @param minutes  the minutes to add, may be negative

   815      * @return an {@code OffsetTime} based on this time with the minutes added, not null

   816      */

   817     public OffsetTime plusMinutes(long minutes) {

   818         return with(time.plusMinutes(minutes), offset);

   819     }

   820 

   821     /**

   822      * Returns a copy of this {@code OffsetTime} with the specified period in seconds added.

   823      * <p>

   824      * This adds the specified number of seconds to this time, returning a new time.

   825      * The calculation wraps around midnight.

   826      * <p>

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

   828      *

   829      * @param seconds  the seconds to add, may be negative

   830      * @return an {@code OffsetTime} based on this time with the seconds added, not null

   831      */

   832     public OffsetTime plusSeconds(long seconds) {

   833         return with(time.plusSeconds(seconds), offset);

   834     }

   835 

   836     /**

   837      * Returns a copy of this {@code OffsetTime} with the specified period in nanoseconds added.

   838      * <p>

   839      * This adds the specified number of nanoseconds to this time, returning a new time.

   840      * The calculation wraps around midnight.

   841      * <p>

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

   843      *

   844      * @param nanos  the nanos to add, may be negative

   845      * @return an {@code OffsetTime} based on this time with the nanoseconds added, not null

   846      */

   847     public OffsetTime plusNanos(long nanos) {

   848         return with(time.plusNanos(nanos), offset);

   849     }

   850 

   851     //-----------------------------------------------------------------------

   852     /**

   853      * Returns a copy of this time with the specified period subtracted.

   854      * <p>

   855      * This method returns a new time based on this time with the specified period subtracted.

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

   857      * the {@link TemporalSubtractor} interface.

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

   859      * back to {@link #minus(long, TemporalUnit)}.

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

   861      * <p>

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

   863      *

   864      * @param subtractor  the subtractor to use, not null

   865      * @return an {@code OffsetTime} based on this time with the subtraction made, not null

   866      * @throws DateTimeException if the subtraction cannot be made

   867      * @throws ArithmeticException if numeric overflow occurs

   868      */

   869     @Override

   870     public OffsetTime minus(TemporalSubtractor subtractor) {

   871         return (OffsetTime) subtractor.subtractFrom(this);

   872     }

   873 

   874     /**

   875      * Returns a copy of this time with the specified period subtracted.

   876      * <p>

   877      * This method returns a new time based on this time with the specified period subtracted.

   878      * This can be used to subtract any period that is defined by a unit, for example to subtract hours, minutes or seconds.

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

   880      * of any edge cases in the calculation.

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

   882      * <p>

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

   884      *

   885      * @param amountToSubtract  the amount of the unit to subtract from the result, may be negative

   886      * @param unit  the unit of the period to subtract, not null

   887      * @return an {@code OffsetTime} based on this time with the specified period subtracted, not null

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

   889      */

   890     @Override

   891     public OffsetTime minus(long amountToSubtract, TemporalUnit unit) {

   892         return (amountToSubtract == Long.MIN_VALUE ? plus(Long.MAX_VALUE, unit).plus(1, unit) : plus(-amountToSubtract, unit));

   893     }

   894 

   895     //-----------------------------------------------------------------------

   896     /**

   897      * Returns a copy of this {@code OffsetTime} with the specified period in hours subtracted.

   898      * <p>

   899      * This subtracts the specified number of hours from this time, returning a new time.

   900      * The calculation wraps around midnight.

   901      * <p>

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

   903      *

   904      * @param hours  the hours to subtract, may be negative

   905      * @return an {@code OffsetTime} based on this time with the hours subtracted, not null

   906      */

   907     public OffsetTime minusHours(long hours) {

   908         return with(time.minusHours(hours), offset);

   909     }

   910 

   911     /**

   912      * Returns a copy of this {@code OffsetTime} with the specified period in minutes subtracted.

   913      * <p>

   914      * This subtracts the specified number of minutes from this time, returning a new time.

   915      * The calculation wraps around midnight.

   916      * <p>

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

   918      *

   919      * @param minutes  the minutes to subtract, may be negative

   920      * @return an {@code OffsetTime} based on this time with the minutes subtracted, not null

   921      */

   922     public OffsetTime minusMinutes(long minutes) {

   923         return with(time.minusMinutes(minutes), offset);

   924     }

   925 

   926     /**

   927      * Returns a copy of this {@code OffsetTime} with the specified period in seconds subtracted.

   928      * <p>

   929      * This subtracts the specified number of seconds from this time, returning a new time.

   930      * The calculation wraps around midnight.

   931      * <p>

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

   933      *

   934      * @param seconds  the seconds to subtract, may be negative

   935      * @return an {@code OffsetTime} based on this time with the seconds subtracted, not null

   936      */

   937     public OffsetTime minusSeconds(long seconds) {

   938         return with(time.minusSeconds(seconds), offset);

   939     }

   940 

   941     /**

   942      * Returns a copy of this {@code OffsetTime} with the specified period in nanoseconds subtracted.

   943      * <p>

   944      * This subtracts the specified number of nanoseconds from this time, returning a new time.

   945      * The calculation wraps around midnight.

   946      * <p>

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

   948      *

   949      * @param nanos  the nanos to subtract, may be negative

   950      * @return an {@code OffsetTime} based on this time with the nanoseconds subtracted, not null

   951      */

   952     public OffsetTime minusNanos(long nanos) {

   953         return with(time.minusNanos(nanos), offset);

   954     }

   955 

   956     //-----------------------------------------------------------------------

   957     /**

   958      * Queries this time using the specified query.

   959      * <p>

   960      * This queries this time using the specified query strategy object.

   961      * The {@code TemporalQuery} object defines the logic to be used to

   962      * obtain the result. Read the documentation of the query to understand

   963      * what the result of this method will be.

   964      * <p>

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

   966      * {@link TemporalQuery#queryFrom(TemporalAccessor)} method on the

   967      * specified query passing {@code this} as the argument.

   968      *

   969      * @param <R> the type of the result

   970      * @param query  the query to invoke, not null

   971      * @return the query result, null may be returned (defined by the query)

   972      * @throws DateTimeException if unable to query (defined by the query)

   973      * @throws ArithmeticException if numeric overflow occurs (defined by the query)

   974      */

   975     @SuppressWarnings("unchecked")

   976     @Override

   977     public <R> R query(TemporalQuery<R> query) {

   978         if (query == Queries.precision()) {

   979             return (R) NANOS;

   980         } else if (query == Queries.offset() || query == Queries.zone()) {

   981             return (R) getOffset();

   982         }

   983         return Temporal.super.query(query);

   984     }

   985 

   986     /**

   987      * Adjusts the specified temporal object to have the same offset and time

   988      * as this object.

   989      * <p>

   990      * This returns a temporal object of the same observable type as the input

   991      * with the offset and time changed to be the same as this.

   992      * <p>

   993      * The adjustment is equivalent to using {@link Temporal#with(TemporalField, long)}

   994      * twice, passing {@link ChronoField#OFFSET_SECONDS} and

   995      * {@link ChronoField#NANO_OF_DAY} as the fields.

   996      * <p>

   997      * In most cases, it is clearer to reverse the calling pattern by using

   998      * {@link Temporal#with(TemporalAdjuster)}:

   999      * <pre>

  1000      *   // these two lines are equivalent, but the second approach is recommended

  1001      *   temporal = thisOffsetTime.adjustInto(temporal);

  1002      *   temporal = temporal.with(thisOffsetTime);

  1003      * </pre>

  1004      * <p>

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

  1006      *

  1007      * @param temporal  the target object to be adjusted, not null

  1008      * @return the adjusted object, not null

  1009      * @throws DateTimeException if unable to make the adjustment

  1010      * @throws ArithmeticException if numeric overflow occurs

  1011      */

  1012     @Override

  1013     public Temporal adjustInto(Temporal temporal) {

  1014         return temporal

  1015                 .with(OFFSET_SECONDS, getOffset().getTotalSeconds())

  1016                 .with(NANO_OF_DAY, time.toNanoOfDay());

  1017     }

  1018 

  1019     /**

  1020      * Calculates the period between this time and another time in

  1021      * terms of the specified unit.

  1022      * <p>

  1023      * This calculates the period between two times in terms of a single unit.

  1024      * The start and end points are {@code this} and the specified time.

  1025      * The result will be negative if the end is before the start.

  1026      * For example, the period in hours between two times can be calculated

  1027      * using {@code startTime.periodUntil(endTime, HOURS)}.

  1028      * <p>

  1029      * The {@code Temporal} passed to this method must be an {@code OffsetTime}.

  1030      * If the offset differs between the two times, then the specified

  1031      * end time is normalized to have the same offset as this time.

  1032      * <p>

  1033      * The calculation returns a whole number, representing the number of

  1034      * complete units between the two times.

  1035      * For example, the period in hours between 11:30Z and 13:29Z will only

  1036      * be one hour as it is one minute short of two hours.

  1037      * <p>

  1038      * This method operates in association with {@link TemporalUnit#between}.

  1039      * The result of this method is a {@code long} representing the amount of

  1040      * the specified unit. By contrast, the result of {@code between} is an

  1041      * object that can be used directly in addition/subtraction:

  1042      * <pre>

  1043      *   long period = start.periodUntil(end, HOURS);   // this method

  1044      *   dateTime.plus(HOURS.between(start, end));      // use in plus/minus

  1045      * </pre>

  1046      * <p>

  1047      * The calculation is implemented in this method for {@link ChronoUnit}.

  1048      * The units {@code NANOS}, {@code MICROS}, {@code MILLIS}, {@code SECONDS},

  1049      * {@code MINUTES}, {@code HOURS} and {@code HALF_DAYS} are supported.

  1050      * Other {@code ChronoUnit} values will throw an exception.

  1051      * <p>

  1052      * If the unit is not a {@code ChronoUnit}, then the result of this method

  1053      * is obtained by invoking {@code TemporalUnit.between(Temporal, Temporal)}

  1054      * passing {@code this} as the first argument and the input temporal as

  1055      * the second argument.

  1056      * <p>

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

  1058      *

  1059      * @param endTime  the end time, which must be an {@code OffsetTime}, not null

  1060      * @param unit  the unit to measure the period in, not null

  1061      * @return the amount of the period between this time and the end time

  1062      * @throws DateTimeException if the period cannot be calculated

  1063      * @throws ArithmeticException if numeric overflow occurs

  1064      */

  1065     @Override

  1066     public long periodUntil(Temporal endTime, TemporalUnit unit) {

  1067         if (endTime instanceof OffsetTime == false) {

  1068             Objects.requireNonNull(endTime, "endTime");

  1069             throw new DateTimeException("Unable to calculate period between objects of two different types");

  1070         }

  1071         if (unit instanceof ChronoUnit) {

  1072             OffsetTime end = (OffsetTime) endTime;

  1073             long nanosUntil = end.toEpochNano() - toEpochNano();  // no overflow

  1074             switch ((ChronoUnit) unit) {

  1075                 case NANOS: return nanosUntil;

  1076                 case MICROS: return nanosUntil / 1000;

  1077                 case MILLIS: return nanosUntil / 1000_000;

  1078                 case SECONDS: return nanosUntil / NANOS_PER_SECOND;

  1079                 case MINUTES: return nanosUntil / NANOS_PER_MINUTE;

  1080                 case HOURS: return nanosUntil / NANOS_PER_HOUR;

  1081                 case HALF_DAYS: return nanosUntil / (12 * NANOS_PER_HOUR);

  1082             }

  1083             throw new DateTimeException("Unsupported unit: " + unit.getName());

  1084         }

  1085         return unit.between(this, endTime).getAmount();

  1086     }

  1087 

  1088     //-----------------------------------------------------------------------

  1089     /**

  1090      * Returns an offset date-time formed from this time at the specified date.

  1091      * <p>

  1092      * This combines this time with the specified date to form an {@code OffsetDateTime}.

  1093      * All possible combinations of date and time are valid.

  1094      * <p>

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

  1096      *

  1097      * @param date  the date to combine with, not null

  1098      * @return the offset date-time formed from this time and the specified date, not null

  1099      */

  1100     public OffsetDateTime atDate(LocalDate date) {

  1101         return OffsetDateTime.of(date, time, offset);

  1102     }

  1103 

  1104     //-----------------------------------------------------------------------

  1105     /**

  1106      * Converts this time to epoch nanos based on 1970-01-01Z.

  1107      *

  1108      * @return the epoch nanos value

  1109      */

  1110     private long toEpochNano() {

  1111         long nod = time.toNanoOfDay();

  1112         long offsetNanos = offset.getTotalSeconds() * NANOS_PER_SECOND;

  1113         return nod - offsetNanos;

  1114     }

  1115 

  1116     //-----------------------------------------------------------------------

  1117     /**

  1118      * Compares this {@code OffsetTime} to another time.

  1119      * <p>

  1120      * The comparison is based first on the UTC equivalent instant, then on the local time.

  1121      * It is "consistent with equals", as defined by {@link Comparable}.

  1122      * <p>

  1123      * For example, the following is the comparator order:

  1124      * <ol>

  1125      * <li>{@code 10:30+01:00}</li>

  1126      * <li>{@code 11:00+01:00}</li>

  1127      * <li>{@code 12:00+02:00}</li>

  1128      * <li>{@code 11:30+01:00}</li>

  1129      * <li>{@code 12:00+01:00}</li>

  1130      * <li>{@code 12:30+01:00}</li>

  1131      * </ol>

  1132      * Values #2 and #3 represent the same instant on the time-line.

  1133      * When two values represent the same instant, the local time is compared

  1134      * to distinguish them. This step is needed to make the ordering

  1135      * consistent with {@code equals()}.