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;
  63 
  64 import static java.time.LocalTime.NANOS_PER_HOUR;
  65 import static java.time.LocalTime.NANOS_PER_MINUTE;
  66 import static java.time.LocalTime.NANOS_PER_SECOND;
  67 import static java.time.LocalTime.SECONDS_PER_DAY;
  68 import static java.time.temporal.ChronoField.NANO_OF_DAY;
  69 import static java.time.temporal.ChronoField.OFFSET_SECONDS;
  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.format.DateTimeFormatter;
  79 import java.time.format.DateTimeParseException;
  80 import java.time.temporal.ChronoField;
  81 import java.time.temporal.ChronoUnit;
  82 import java.time.temporal.Queries;
  83 import java.time.temporal.Temporal;
  84 import java.time.temporal.TemporalAccessor;
  85 import java.time.temporal.TemporalAdjuster;
  86 import java.time.temporal.TemporalAmount;
  87 import java.time.temporal.TemporalField;
  88 import java.time.temporal.TemporalQuery;
  89 import java.time.temporal.TemporalUnit;
  90 import java.time.temporal.ValueRange;
  91 import java.time.zone.ZoneRules;
  92 import java.util.Objects;
  93 
  94 /**
  95  * A time with an offset from UTC/Greenwich in the ISO-8601 calendar system,
  96  * such as {@code 10:15:30+01:00}.
  97  * <p>
  98  * {@code OffsetTime} is an immutable date-time object that represents a time, often
  99  * viewed as hour-minute-second-offset.
 100  * This class stores all time fields, to a precision of nanoseconds,
 101  * as well as a zone offset.
 102  * For example, the value "13:45.30.123456789+02:00" can be stored
 103  * in an {@code OffsetTime}.
 104  *
 105  * <h3>Specification for implementors</h3>
 106  * This class is immutable and thread-safe.
 107  *
 108  * @since 1.8
 109  */
 110 public final class OffsetTime
 111         implements Temporal, TemporalAdjuster, Comparable<OffsetTime>, Serializable {
 112 
 113     /**
 114      * The minimum supported {@code OffsetTime}, '00:00:00+18:00'.
 115      * This is the time of midnight at the start of the day in the maximum offset
 116      * (larger offsets are earlier on the time-line).
 117      * This combines {@link LocalTime#MIN} and {@link ZoneOffset#MAX}.
 118      * This could be used by an application as a "far past" date.
 119      */
 120     public static final OffsetTime MIN = LocalTime.MIN.atOffset(ZoneOffset.MAX);
 121     /**
 122      * The maximum supported {@code OffsetTime}, '23:59:59.999999999-18:00'.
 123      * This is the time just before midnight at the end of the day in the minimum offset
 124      * (larger negative offsets are later on the time-line).
 125      * This combines {@link LocalTime#MAX} and {@link ZoneOffset#MIN}.
 126      * This could be used by an application as a "far future" date.
 127      */
 128     public static final OffsetTime MAX = LocalTime.MAX.atOffset(ZoneOffset.MIN);
 129 
 130     /**
 131      * Serialization version.
 132      */
 133     private static final long serialVersionUID = 7264499704384272492L;
 134 
 135     /**
 136      * The local date-time.
 137      */
 138     private final LocalTime time;
 139     /**
 140      * The offset from UTC/Greenwich.
 141      */
 142     private final ZoneOffset offset;
 143 
 144     //-----------------------------------------------------------------------
 145     /**
 146      * Obtains the current time from the system clock in the default time-zone.
 147      * <p>
 148      * This will query the {@link java.time.Clock#systemDefaultZone() system clock} in the default
 149      * time-zone to obtain the current time.
 150      * The offset will be calculated from the time-zone in the clock.
 151      * <p>
 152      * Using this method will prevent the ability to use an alternate clock for testing
 153      * because the clock is hard-coded.
 154      *
 155      * @return the current time using the system clock, not null
 156      */
 157     public static OffsetTime now() {
 158         return now(Clock.systemDefaultZone());
 159     }
 160 
 161     /**
 162      * Obtains the current time from the system clock in the specified time-zone.
 163      * <p>
 164      * This will query the {@link Clock#system(java.time.ZoneId) system clock} to obtain the current time.
 165      * Specifying the time-zone avoids dependence on the default time-zone.
 166      * The offset will be calculated from the specified time-zone.
 167      * <p>
 168      * Using this method will prevent the ability to use an alternate clock for testing
 169      * because the clock is hard-coded.
 170      *
 171      * @param zone  the zone ID to use, not null
 172      * @return the current time using the system clock, not null
 173      */
 174     public static OffsetTime now(ZoneId zone) {
 175         return now(Clock.system(zone));
 176     }
 177 
 178     /**
 179      * Obtains the current time from the specified clock.
 180      * <p>
 181      * This will query the specified clock to obtain the current time.
 182      * The offset will be calculated from the time-zone in the clock.
 183      * <p>
 184      * Using this method allows the use of an alternate clock for testing.
 185      * The alternate clock may be introduced using {@link Clock dependency injection}.
 186      *
 187      * @param clock  the clock to use, not null
 188      * @return the current time, not null
 189      */
 190     public static OffsetTime now(Clock clock) {
 191         Objects.requireNonNull(clock, "clock");
 192         final Instant now = clock.instant();  // called once
 193         return ofInstant(now, clock.getZone().getRules().getOffset(now));
 194     }
 195 
 196     //-----------------------------------------------------------------------
 197     /**
 198      * Obtains an instance of {@code OffsetTime} from a local time and an offset.
 199      *
 200      * @param time  the local time, not null
 201      * @param offset  the zone offset, not null
 202      * @return the offset time, not null
 203      */
 204     public static OffsetTime of(LocalTime time, ZoneOffset offset) {
 205         return new OffsetTime(time, offset);
 206     }
 207 
 208     /**
 209      * Obtains an instance of {@code OffsetTime} from an hour, minute, second and nanosecond.
 210      * <p>
 211      * This creates an offset time with the four specified fields.
 212      * <p>
 213      * This method exists primarily for writing test cases.
 214      * Non test-code will typically use other methods to create an offset time.
 215      * {@code LocalTime} has two additional convenience variants of the
 216      * equivalent factory method taking fewer arguments.
 217      * They are not provided here to reduce the footprint of the API.
 218      *
 219      * @param hour  the hour-of-day to represent, from 0 to 23
 220      * @param minute  the minute-of-hour to represent, from 0 to 59
 221      * @param second  the second-of-minute to represent, from 0 to 59
 222      * @param nanoOfSecond  the nano-of-second to represent, from 0 to 999,999,999
 223      * @param offset  the zone offset, not null
 224      * @return the offset time, not null
 225      * @throws DateTimeException if the value of any field is out of range
 226      */
 227     public static OffsetTime of(int hour, int minute, int second, int nanoOfSecond, ZoneOffset offset) {
 228         return new OffsetTime(LocalTime.of(hour, minute, second, nanoOfSecond), offset);
 229     }
 230 
 231     //-----------------------------------------------------------------------
 232     /**
 233      * Obtains an instance of {@code OffsetTime} from an {@code Instant} and zone ID.
 234      * <p>
 235      * This creates an offset time with the same instant as that specified.
 236      * Finding the offset from UTC/Greenwich is simple as there is only one valid
 237      * offset for each instant.
 238      * <p>
 239      * The date component of the instant is dropped during the conversion.
 240      * This means that the conversion can never fail due to the instant being
 241      * out of the valid range of dates.
 242      *
 243      * @param instant  the instant to create the time from, not null
 244      * @param zone  the time-zone, which may be an offset, not null
 245      * @return the offset time, not null
 246      */
 247     public static OffsetTime ofInstant(Instant instant, ZoneId zone) {
 248         Objects.requireNonNull(instant, "instant");
 249         Objects.requireNonNull(zone, "zone");
 250         ZoneRules rules = zone.getRules();
 251         ZoneOffset offset = rules.getOffset(instant);
 252         long localSecond = instant.getEpochSecond() + offset.getTotalSeconds();  // overflow caught later
 253         int secsOfDay = (int) Math.floorMod(localSecond, SECONDS_PER_DAY);
 254         LocalTime time = LocalTime.ofNanoOfDay(secsOfDay * NANOS_PER_SECOND + instant.getNano());
 255         return new OffsetTime(time, offset);
 256     }
 257 
 258     //-----------------------------------------------------------------------
 259     /**
 260      * Obtains an instance of {@code OffsetTime} from a temporal object.
 261      * <p>
 262      * This obtains an offset time based on the specified temporal.
 263      * A {@code TemporalAccessor} represents an arbitrary set of date and time information,
 264      * which this factory converts to an instance of {@code OffsetTime}.
 265      * <p>
 266      * The conversion extracts and combines the {@code ZoneOffset} and the
 267      * {@code LocalTime} from the temporal object.
 268      * Implementations are permitted to perform optimizations such as accessing
 269      * those fields that are equivalent to the relevant objects.
 270      * <p>
 271      * This method matches the signature of the functional interface {@link TemporalQuery}
 272      * allowing it to be used in queries via method reference, {@code OffsetTime::from}.
 273      *
 274      * @param temporal  the temporal object to convert, not null
 275      * @return the offset time, not null
 276      * @throws DateTimeException if unable to convert to an {@code OffsetTime}
 277      */
 278     public static OffsetTime from(TemporalAccessor temporal) {
 279         if (temporal instanceof OffsetTime) {
 280             return (OffsetTime) temporal;
 281         }
 282         try {
 283             LocalTime time = LocalTime.from(temporal);
 284             ZoneOffset offset = ZoneOffset.from(temporal);
 285             return new OffsetTime(time, offset);
 286         } catch (DateTimeException ex) {
 287             throw new DateTimeException("Unable to obtain OffsetTime from TemporalAccessor: " + temporal.getClass(), ex);
 288         }
 289     }
 290 
 291     //-----------------------------------------------------------------------
 292     /**
 293      * Obtains an instance of {@code OffsetTime} from a text string such as {@code 10:15:30+01:00}.
 294      * <p>
 295      * The string must represent a valid time and is parsed using
 296      * {@link java.time.format.DateTimeFormatter#ISO_OFFSET_TIME}.
 297      *
 298      * @param text  the text to parse such as "10:15:30+01:00", not null
 299      * @return the parsed local time, not null
 300      * @throws DateTimeParseException if the text cannot be parsed
 301      */
 302     public static OffsetTime parse(CharSequence text) {
 303         return parse(text, DateTimeFormatter.ISO_OFFSET_TIME);
 304     }
 305 
 306     /**
 307      * Obtains an instance of {@code OffsetTime} from a text string using a specific formatter.
 308      * <p>
 309      * The text is parsed using the formatter, returning a time.
 310      *
 311      * @param text  the text to parse, not null
 312      * @param formatter  the formatter to use, not null
 313      * @return the parsed offset time, not null
 314      * @throws DateTimeParseException if the text cannot be parsed
 315      */
 316     public static OffsetTime parse(CharSequence text, DateTimeFormatter formatter) {
 317         Objects.requireNonNull(formatter, "formatter");
 318         return formatter.parse(text, OffsetTime::from);
 319     }
 320 
 321     //-----------------------------------------------------------------------
 322     /**
 323      * Constructor.
 324      *
 325      * @param time  the local time, not null
 326      * @param offset  the zone offset, not null
 327      */
 328     private OffsetTime(LocalTime time, ZoneOffset offset) {
 329         this.time = Objects.requireNonNull(time, "time");
 330         this.offset = Objects.requireNonNull(offset, "offset");
 331     }
 332 
 333     /**
 334      * Returns a new time based on this one, returning {@code this} where possible.
 335      *
 336      * @param time  the time to create with, not null
 337      * @param offset  the zone offset to create with, not null
 338      */
 339     private OffsetTime with(LocalTime time, ZoneOffset offset) {
 340         if (this.time == time && this.offset.equals(offset)) {
 341             return this;
 342         }
 343         return new OffsetTime(time, offset);
 344     }
 345 
 346     //-----------------------------------------------------------------------
 347     /**
 348      * Checks if the specified field is supported.
 349      * <p>
 350      * This checks if this time can be queried for the specified field.
 351      * If false, then calling the {@link #range(TemporalField) range} and
 352      * {@link #get(TemporalField) get} methods will throw an exception.
 353      * <p>
 354      * If the field is a {@link ChronoField} then the query is implemented here.
 355      * The supported fields are:
 356      * <ul>
 357      * <li>{@code NANO_OF_SECOND}
 358      * <li>{@code NANO_OF_DAY}
 359      * <li>{@code MICRO_OF_SECOND}
 360      * <li>{@code MICRO_OF_DAY}
 361      * <li>{@code MILLI_OF_SECOND}
 362      * <li>{@code MILLI_OF_DAY}
 363      * <li>{@code SECOND_OF_MINUTE}
 364      * <li>{@code SECOND_OF_DAY}
 365      * <li>{@code MINUTE_OF_HOUR}
 366      * <li>{@code MINUTE_OF_DAY}
 367      * <li>{@code HOUR_OF_AMPM}
 368      * <li>{@code CLOCK_HOUR_OF_AMPM}
 369      * <li>{@code HOUR_OF_DAY}
 370      * <li>{@code CLOCK_HOUR_OF_DAY}
 371      * <li>{@code AMPM_OF_DAY}
 372      * <li>{@code OFFSET_SECONDS}
 373      * </ul>
 374      * All other {@code ChronoField} instances will return false.
 375      * <p>
 376      * If the field is not a {@code ChronoField}, then the result of this method
 377      * is obtained by invoking {@code TemporalField.isSupportedBy(TemporalAccessor)}
 378      * passing {@code this} as the argument.
 379      * Whether the field is supported is determined by the field.
 380      *
 381      * @param field  the field to check, null returns false
 382      * @return true if the field is supported on this time, false if not
 383      */
 384     @Override
 385     public boolean isSupported(TemporalField field) {
 386         if (field instanceof ChronoField) {
 387             return ((ChronoField) field).isTimeField() || field == OFFSET_SECONDS;
 388         }
 389         return field != null && field.isSupportedBy(this);
 390     }
 391 
 392     /**
 393      * Gets the range of valid values for the specified field.
 394      * <p>
 395      * The range object expresses the minimum and maximum valid values for a field.
 396      * This time is used to enhance the accuracy of the returned range.
 397      * If it is not possible to return the range, because the field is not supported
 398      * or for some other reason, an exception is thrown.
 399      * <p>
 400      * If the field is a {@link ChronoField} then the query is implemented here.
 401      * The {@link #isSupported(TemporalField) supported fields} will return
 402      * appropriate range instances.
 403      * All other {@code ChronoField} instances will throw a {@code DateTimeException}.
 404      * <p>
 405      * If the field is not a {@code ChronoField}, then the result of this method
 406      * is obtained by invoking {@code TemporalField.rangeRefinedBy(TemporalAccessor)}
 407      * passing {@code this} as the argument.
 408      * Whether the range can be obtained is determined by the field.
 409      *
 410      * @param field  the field to query the range for, not null
 411      * @return the range of valid values for the field, not null
 412      * @throws DateTimeException if the range for the field cannot be obtained
 413      */
 414     @Override
 415     public ValueRange range(TemporalField field) {
 416         if (field instanceof ChronoField) {
 417             if (field == OFFSET_SECONDS) {
 418                 return field.range();
 419             }
 420             return time.range(field);
 421         }
 422         return field.rangeRefinedBy(this);
 423     }
 424 
 425     /**
 426      * Gets the value of the specified field from this time as an {@code int}.
 427      * <p>
 428      * This queries this time for the value for the specified field.
 429      * The returned value will always be within the valid range of values for the field.
 430      * If it is not possible to return the value, because the field is not supported
 431      * or for some other reason, an exception is thrown.
 432      * <p>
 433      * If the field is a {@link ChronoField} then the query is implemented here.
 434      * The {@link #isSupported(TemporalField) supported fields} will return valid
 435      * values based on this time, except {@code NANO_OF_DAY} and {@code MICRO_OF_DAY}
 436      * which are too large to fit in an {@code int} and throw a {@code DateTimeException}.
 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.getFrom(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  // override for Javadoc
 450     public int get(TemporalField field) {
 451         return Temporal.super.get(field);
 452     }
 453 
 454     /**
 455      * Gets the value of the specified field from this time as a {@code long}.
 456      * <p>
 457      * This queries this time for the value for the specified field.
 458      * If it is not possible to return the value, because the field is not supported
 459      * or for some other reason, an exception is thrown.
 460      * <p>
 461      * If the field is a {@link ChronoField} then the query is implemented here.
 462      * The {@link #isSupported(TemporalField) supported fields} will return valid
 463      * values based on this time.
 464      * All other {@code ChronoField} instances will throw a {@code DateTimeException}.
 465      * <p>
 466      * If the field is not a {@code ChronoField}, then the result of this method
 467      * is obtained by invoking {@code TemporalField.getFrom(TemporalAccessor)}
 468      * passing {@code this} as the argument. Whether the value can be obtained,
 469      * and what the value represents, is determined by the field.
 470      *
 471      * @param field  the field to get, not null
 472      * @return the value for the field
 473      * @throws DateTimeException if a value for the field cannot be obtained
 474      * @throws ArithmeticException if numeric overflow occurs
 475      */
 476     @Override
 477     public long getLong(TemporalField field) {
 478         if (field instanceof ChronoField) {
 479             if (field == OFFSET_SECONDS) {
 480                 return offset.getTotalSeconds();
 481             }
 482             return time.getLong(field);
 483         }
 484         return field.getFrom(this);
 485     }
 486 
 487     //-----------------------------------------------------------------------
 488     /**
 489      * Gets the zone offset, such as '+01:00'.
 490      * <p>
 491      * This is the offset of the local time from UTC/Greenwich.
 492      *
 493      * @return the zone offset, not null
 494      */
 495     public ZoneOffset getOffset() {
 496         return offset;
 497     }
 498 
 499     /**
 500      * Returns a copy of this {@code OffsetTime} with the specified offset ensuring
 501      * that the result has the same local time.
 502      * <p>
 503      * This method returns an object with the same {@code LocalTime} and the specified {@code ZoneOffset}.
 504      * No calculation is needed or performed.
 505      * For example, if this time represents {@code 10:30+02:00} and the offset specified is
 506      * {@code +03:00}, then this method will return {@code 10:30+03:00}.
 507      * <p>
 508      * To take into account the difference between the offsets, and adjust the time fields,
 509      * use {@link #withOffsetSameInstant}.
 510      * <p>
 511      * This instance is immutable and unaffected by this method call.
 512      *
 513      * @param offset  the zone offset to change to, not null
 514      * @return an {@code OffsetTime} based on this time with the requested offset, not null
 515      */
 516     public OffsetTime withOffsetSameLocal(ZoneOffset offset) {
 517         return offset != null && offset.equals(this.offset) ? this : new OffsetTime(time, offset);
 518     }
 519 
 520     /**
 521      * Returns a copy of this {@code OffsetTime} with the specified offset ensuring
 522      * that the result is at the same instant on an implied day.
 523      * <p>
 524      * This method returns an object with the specified {@code ZoneOffset} and a {@code LocalTime}
 525      * adjusted by the difference between the two offsets.
 526      * This will result in the old and new objects representing the same instant an an implied day.
 527      * This is useful for finding the local time in a different offset.
 528      * For example, if this time represents {@code 10:30+02:00} and the offset specified is
 529      * {@code +03:00}, then this method will return {@code 11:30+03:00}.
 530      * <p>
 531      * To change the offset without adjusting the local time use {@link #withOffsetSameLocal}.
 532      * <p>
 533      * This instance is immutable and unaffected by this method call.
 534      *
 535      * @param offset  the zone offset to change to, not null
 536      * @return an {@code OffsetTime} based on this time with the requested offset, not null
 537      */
 538     public OffsetTime withOffsetSameInstant(ZoneOffset offset) {
 539         if (offset.equals(this.offset)) {
 540             return this;
 541         }
 542         int difference = offset.getTotalSeconds() - this.offset.getTotalSeconds();
 543         LocalTime adjusted = time.plusSeconds(difference);
 544         return new OffsetTime(adjusted, offset);
 545     }
 546 
 547     //-----------------------------------------------------------------------
 548     /**
 549      * Gets the {@code LocalTime} part of this date-time.
 550      * <p>
 551      * This returns a {@code LocalTime} with the same hour, minute, second and
 552      * nanosecond as this date-time.
 553      *
 554      * @return the time part of this date-time, not null
 555      */
 556     public LocalTime toLocalTime() {
 557         return time;
 558     }
 559 
 560     //-----------------------------------------------------------------------
 561     /**
 562      * Gets the hour-of-day field.
 563      *
 564      * @return the hour-of-day, from 0 to 23
 565      */
 566     public int getHour() {
 567         return time.getHour();
 568     }
 569 
 570     /**
 571      * Gets the minute-of-hour field.
 572      *
 573      * @return the minute-of-hour, from 0 to 59
 574      */
 575     public int getMinute() {
 576         return time.getMinute();
 577     }
 578 
 579     /**
 580      * Gets the second-of-minute field.
 581      *
 582      * @return the second-of-minute, from 0 to 59
 583      */
 584     public int getSecond() {
 585         return time.getSecond();
 586     }
 587 
 588     /**
 589      * Gets the nano-of-second field.
 590      *
 591      * @return the nano-of-second, from 0 to 999,999,999
 592      */
 593     public int getNano() {
 594         return time.getNano();
 595     }
 596 
 597     //-----------------------------------------------------------------------
 598     /**
 599      * Returns an adjusted copy of this time.
 600      * <p>
 601      * This returns an {@code OffsetTime}, based on this one, with the time adjusted.
 602      * The adjustment takes place using the specified adjuster strategy object.
 603      * Read the documentation of the adjuster to understand what adjustment will be made.
 604      * <p>
 605      * A simple adjuster might simply set the one of the fields, such as the hour field.
 606      * A more complex adjuster might set the time to the last hour of the day.
 607      * <p>
 608      * The classes {@link LocalTime} and {@link ZoneOffset} implement {@code TemporalAdjuster},
 609      * thus this method can be used to change the time or offset:
 610      * <pre>
 611      *  result = offsetTime.with(time);
 612      *  result = offsetTime.with(offset);
 613      * </pre>
 614      * <p>
 615      * The result of this method is obtained by invoking the
 616      * {@link TemporalAdjuster#adjustInto(Temporal)} method on the
 617      * specified adjuster passing {@code this} as the argument.
 618      * <p>
 619      * This instance is immutable and unaffected by this method call.
 620      *
 621      * @param adjuster the adjuster to use, not null
 622      * @return an {@code OffsetTime} based on {@code this} with the adjustment made, not null
 623      * @throws DateTimeException if the adjustment cannot be made
 624      * @throws ArithmeticException if numeric overflow occurs
 625      */
 626     @Override
 627     public OffsetTime with(TemporalAdjuster adjuster) {
 628         // optimizations
 629         if (adjuster instanceof LocalTime) {
 630             return with((LocalTime) adjuster, offset);
 631         } else if (adjuster instanceof ZoneOffset) {
 632             return with(time, (ZoneOffset) adjuster);
 633         } else if (adjuster instanceof OffsetTime) {
 634             return (OffsetTime) adjuster;
 635         }
 636         return (OffsetTime) adjuster.adjustInto(this);
 637     }
 638 
 639     /**
 640      * Returns a copy of this time with the specified field set to a new value.
 641      * <p>
 642      * This returns an {@code OffsetTime}, based on this one, with the value
 643      * for the specified field changed.
 644      * This can be used to change any supported field, such as the hour, minute or second.
 645      * If it is not possible to set the value, because the field is not supported or for
 646      * some other reason, an exception is thrown.
 647      * <p>
 648      * If the field is a {@link ChronoField} then the adjustment is implemented here.
 649      * <p>
 650      * The {@code OFFSET_SECONDS} field will return a time with the specified offset.
 651      * The local time is unaltered. If the new offset value is outside the valid range
 652      * then a {@code DateTimeException} will be thrown.
 653      * <p>
 654      * The other {@link #isSupported(TemporalField) supported fields} will behave as per
 655      * the matching method on {@link LocalTime#with(TemporalField, long)} LocalTime}.
 656      * In this case, the offset is not part of the calculation and will be unchanged.
 657      * <p>
 658      * All other {@code ChronoField} instances will throw a {@code DateTimeException}.
 659      * <p>
 660      * If the field is not a {@code ChronoField}, then the result of this method
 661      * is obtained by invoking {@code TemporalField.adjustInto(Temporal, long)}
 662      * passing {@code this} as the argument. In this case, the field determines
 663      * whether and how to adjust the instant.
 664      * <p>
 665      * This instance is immutable and unaffected by this method call.
 666      *
 667      * @param field  the field to set in the result, not null
 668      * @param newValue  the new value of the field in the result
 669      * @return an {@code OffsetTime} based on {@code this} with the specified field set, not null
 670      * @throws DateTimeException if the field cannot be set
 671      * @throws ArithmeticException if numeric overflow occurs
 672      */
 673     @Override
 674     public OffsetTime with(TemporalField field, long newValue) {
 675         if (field instanceof ChronoField) {
 676             if (field == OFFSET_SECONDS) {
 677                 ChronoField f = (ChronoField) field;
 678                 return with(time, ZoneOffset.ofTotalSeconds(f.checkValidIntValue(newValue)));
 679             }
 680             return with(time.with(field, newValue), offset);
 681         }
 682         return field.adjustInto(this, newValue);
 683     }
 684 
 685     //-----------------------------------------------------------------------
 686     /**
 687      * Returns a copy of this {@code OffsetTime} with the hour-of-day value altered.
 688      * <p>
 689      * The offset does not affect the calculation and will be the same in the result.
 690      * <p>
 691      * This instance is immutable and unaffected by this method call.
 692      *
 693      * @param hour  the hour-of-day to set in the result, from 0 to 23
 694      * @return an {@code OffsetTime} based on this time with the requested hour, not null
 695      * @throws DateTimeException if the hour value is invalid
 696      */
 697     public OffsetTime withHour(int hour) {
 698         return with(time.withHour(hour), offset);
 699     }
 700 
 701     /**
 702      * Returns a copy of this {@code OffsetTime} with the minute-of-hour value altered.
 703      * <p>
 704      * The offset does not affect the calculation and will be the same in the result.
 705      * <p>
 706      * This instance is immutable and unaffected by this method call.
 707      *
 708      * @param minute  the minute-of-hour to set in the result, from 0 to 59
 709      * @return an {@code OffsetTime} based on this time with the requested minute, not null
 710      * @throws DateTimeException if the minute value is invalid
 711      */
 712     public OffsetTime withMinute(int minute) {
 713         return with(time.withMinute(minute), offset);
 714     }
 715 
 716     /**
 717      * Returns a copy of this {@code OffsetTime} with the second-of-minute value altered.
 718      * <p>
 719      * The offset does not affect the calculation and will be the same in the result.
 720      * <p>
 721      * This instance is immutable and unaffected by this method call.
 722      *
 723      * @param second  the second-of-minute to set in the result, from 0 to 59
 724      * @return an {@code OffsetTime} based on this time with the requested second, not null
 725      * @throws DateTimeException if the second value is invalid
 726      */
 727     public OffsetTime withSecond(int second) {
 728         return with(time.withSecond(second), offset);
 729     }
 730 
 731     /**
 732      * Returns a copy of this {@code OffsetTime} with the nano-of-second value altered.
 733      * <p>
 734      * The offset does not affect the calculation and will be the same in the result.
 735      * <p>
 736      * This instance is immutable and unaffected by this method call.
 737      *
 738      * @param nanoOfSecond  the nano-of-second to set in the result, from 0 to 999,999,999
 739      * @return an {@code OffsetTime} based on this time with the requested nanosecond, not null
 740      * @throws DateTimeException if the nanos value is invalid
 741      */
 742     public OffsetTime withNano(int nanoOfSecond) {
 743         return with(time.withNano(nanoOfSecond), offset);
 744     }
 745 
 746     //-----------------------------------------------------------------------
 747     /**
 748      * Returns a copy of this {@code OffsetTime} with the time truncated.
 749      * <p>
 750      * Truncation returns a copy of the original time with fields
 751      * smaller than the specified unit set to zero.
 752      * For example, truncating with the {@link ChronoUnit#MINUTES minutes} unit
 753      * will set the second-of-minute and nano-of-second field to zero.
 754      * <p>
 755      * The unit must have a {@linkplain TemporalUnit#getDuration() duration}
 756      * that divides into the length of a standard day without remainder.
 757      * This includes all supplied time units on {@link ChronoUnit} and
 758      * {@link ChronoUnit#DAYS DAYS}. Other units throw an exception.
 759      * <p>
 760      * The offset does not affect the calculation and will be the same in the result.
 761      * <p>
 762      * This instance is immutable and unaffected by this method call.
 763      *
 764      * @param unit  the unit to truncate to, not null
 765      * @return an {@code OffsetTime} based on this time with the time truncated, not null
 766      * @throws DateTimeException if unable to truncate
 767      */
 768     public OffsetTime truncatedTo(TemporalUnit unit) {
 769         return with(time.truncatedTo(unit), offset);
 770     }
 771 
 772     //-----------------------------------------------------------------------
 773     /**
 774      * Returns a copy of this time with the specified amount added.
 775      * <p>
 776      * This returns an {@code OffsetTime}, based on this one, with the specified amount added.
 777      * The amount is typically {@link Duration} but may be any other type implementing
 778      * the {@link TemporalAmount} interface.
 779      * <p>
 780      * The calculation is delegated to the amount object by calling
 781      * {@link TemporalAmount#addTo(Temporal)}. The amount implementation is free
 782      * to implement the addition in any way it wishes, however it typically
 783      * calls back to {@link #plus(long, TemporalUnit)}. Consult the documentation
 784      * of the amount implementation to determine if it can be successfully added.
 785      * <p>
 786      * This instance is immutable and unaffected by this method call.
 787      *
 788      * @param amountToAdd  the amount to add, not null
 789      * @return an {@code OffsetTime} based on this time with the addition made, not null
 790      * @throws DateTimeException if the addition cannot be made
 791      * @throws ArithmeticException if numeric overflow occurs
 792      */
 793     @Override
 794     public OffsetTime plus(TemporalAmount amountToAdd) {
 795         return (OffsetTime) amountToAdd.addTo(this);
 796     }
 797 
 798     /**
 799      * Returns a copy of this time with the specified amount added.
 800      * <p>
 801      * This returns an {@code OffsetTime}, based on this one, with the amount
 802      * in terms of the unit added. If it is not possible to add the amount, because the
 803      * unit is not supported or for some other reason, an exception is thrown.
 804      * <p>
 805      * If the field is a {@link ChronoUnit} then the addition is implemented by
 806      * {@link LocalTime#plus(long, TemporalUnit)}.
 807      * The offset is not part of the calculation and will be unchanged in the result.
 808      * <p>
 809      * If the field is not a {@code ChronoUnit}, then the result of this method
 810      * is obtained by invoking {@code TemporalUnit.addTo(Temporal, long)}
 811      * passing {@code this} as the argument. In this case, the unit determines
 812      * whether and how to perform the addition.
 813      * <p>
 814      * This instance is immutable and unaffected by this method call.
 815      *
 816      * @param amountToAdd  the amount of the unit to add to the result, may be negative
 817      * @param unit  the unit of the amount to add, not null
 818      * @return an {@code OffsetTime} based on this time with the specified amount added, not null
 819      * @throws DateTimeException if the addition cannot be made
 820      * @throws ArithmeticException if numeric overflow occurs
 821      */
 822     @Override
 823     public OffsetTime plus(long amountToAdd, TemporalUnit unit) {
 824         if (unit instanceof ChronoUnit) {
 825             return with(time.plus(amountToAdd, unit), offset);
 826         }
 827         return unit.addTo(this, amountToAdd);
 828     }
 829 
 830     //-----------------------------------------------------------------------
 831     /**
 832      * Returns a copy of this {@code OffsetTime} with the specified period in hours added.
 833      * <p>
 834      * This adds the specified number of hours to this time, returning a new time.
 835      * The calculation wraps around midnight.
 836      * <p>
 837      * This instance is immutable and unaffected by this method call.
 838      *
 839      * @param hours  the hours to add, may be negative
 840      * @return an {@code OffsetTime} based on this time with the hours added, not null
 841      */
 842     public OffsetTime plusHours(long hours) {
 843         return with(time.plusHours(hours), offset);
 844     }
 845 
 846     /**
 847      * Returns a copy of this {@code OffsetTime} with the specified period in minutes added.
 848      * <p>
 849      * This adds the specified number of minutes to this time, returning a new time.
 850      * The calculation wraps around midnight.
 851      * <p>
 852      * This instance is immutable and unaffected by this method call.
 853      *
 854      * @param minutes  the minutes to add, may be negative
 855      * @return an {@code OffsetTime} based on this time with the minutes added, not null
 856      */
 857     public OffsetTime plusMinutes(long minutes) {
 858         return with(time.plusMinutes(minutes), offset);
 859     }
 860 
 861     /**
 862      * Returns a copy of this {@code OffsetTime} with the specified period in seconds added.
 863      * <p>
 864      * This adds the specified number of seconds to this time, returning a new time.
 865      * The calculation wraps around midnight.
 866      * <p>
 867      * This instance is immutable and unaffected by this method call.
 868      *
 869      * @param seconds  the seconds to add, may be negative
 870      * @return an {@code OffsetTime} based on this time with the seconds added, not null
 871      */
 872     public OffsetTime plusSeconds(long seconds) {
 873         return with(time.plusSeconds(seconds), offset);
 874     }
 875 
 876     /**
 877      * Returns a copy of this {@code OffsetTime} with the specified period in nanoseconds added.
 878      * <p>
 879      * This adds the specified number of nanoseconds to this time, returning a new time.
 880      * The calculation wraps around midnight.
 881      * <p>
 882      * This instance is immutable and unaffected by this method call.
 883      *
 884      * @param nanos  the nanos to add, may be negative
 885      * @return an {@code OffsetTime} based on this time with the nanoseconds added, not null
 886      */
 887     public OffsetTime plusNanos(long nanos) {
 888         return with(time.plusNanos(nanos), offset);
 889     }
 890 
 891     //-----------------------------------------------------------------------
 892     /**
 893      * Returns a copy of this time with the specified amount subtracted.
 894      * <p>
 895      * This returns an {@code OffsetTime}, based on this one, with the specified amount subtracted.
 896      * The amount is typically {@link Duration} but may be any other type implementing
 897      * the {@link TemporalAmount} interface.
 898      * <p>
 899      * The calculation is delegated to the amount object by calling
 900      * {@link TemporalAmount#subtractFrom(Temporal)}. The amount implementation is free
 901      * to implement the subtraction in any way it wishes, however it typically
 902      * calls back to {@link #minus(long, TemporalUnit)}. Consult the documentation
 903      * of the amount implementation to determine if it can be successfully subtracted.
 904      * <p>
 905      * This instance is immutable and unaffected by this method call.
 906      *
 907      * @param amountToSubtract  the amount to subtract, not null
 908      * @return an {@code OffsetTime} based on this time with the subtraction made, not null
 909      * @throws DateTimeException if the subtraction cannot be made
 910      * @throws ArithmeticException if numeric overflow occurs
 911      */
 912     @Override
 913     public OffsetTime minus(TemporalAmount amountToSubtract) {
 914         return (OffsetTime) amountToSubtract.subtractFrom(this);
 915     }
 916 
 917     /**
 918      * Returns a copy of this time with the specified amount subtracted.
 919      * <p>
 920      * This returns an {@code OffsetTime}, based on this one, with the amount
 921      * in terms of the unit subtracted. If it is not possible to subtract the amount,
 922      * because the unit is not supported or for some other reason, an exception is thrown.
 923      * <p>
 924      * This method is equivalent to {@link #plus(long, TemporalUnit)} with the amount negated.
 925      * See that method for a full description of how addition, and thus subtraction, works.
 926      * <p>
 927      * This instance is immutable and unaffected by this method call.
 928      *
 929      * @param amountToSubtract  the amount of the unit to subtract from the result, may be negative
 930      * @param unit  the unit of the amount to subtract, not null
 931      * @return an {@code OffsetTime} based on this time with the specified amount subtracted, not null
 932      * @throws DateTimeException if the subtraction cannot be made
 933      * @throws ArithmeticException if numeric overflow occurs
 934      */
 935     @Override
 936     public OffsetTime minus(long amountToSubtract, TemporalUnit unit) {
 937         return (amountToSubtract == Long.MIN_VALUE ? plus(Long.MAX_VALUE, unit).plus(1, unit) : plus(-amountToSubtract, unit));
 938     }
 939 
 940     //-----------------------------------------------------------------------
 941     /**
 942      * Returns a copy of this {@code OffsetTime} with the specified period in hours subtracted.
 943      * <p>
 944      * This subtracts the specified number of hours 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 hours  the hours to subtract, may be negative
 950      * @return an {@code OffsetTime} based on this time with the hours subtracted, not null
 951      */
 952     public OffsetTime minusHours(long hours) {
 953         return with(time.minusHours(hours), offset);
 954     }
 955 
 956     /**
 957      * Returns a copy of this {@code OffsetTime} with the specified period in minutes subtracted.
 958      * <p>
 959      * This subtracts the specified number of minutes from this time, returning a new time.
 960      * The calculation wraps around midnight.
 961      * <p>
 962      * This instance is immutable and unaffected by this method call.
 963      *
 964      * @param minutes  the minutes to subtract, may be negative
 965      * @return an {@code OffsetTime} based on this time with the minutes subtracted, not null
 966      */
 967     public OffsetTime minusMinutes(long minutes) {
 968         return with(time.minusMinutes(minutes), offset);
 969     }
 970 
 971     /**
 972      * Returns a copy of this {@code OffsetTime} with the specified period in seconds subtracted.
 973      * <p>
 974      * This subtracts the specified number of seconds from this time, returning a new time.
 975      * The calculation wraps around midnight.
 976      * <p>
 977      * This instance is immutable and unaffected by this method call.
 978      *
 979      * @param seconds  the seconds to subtract, may be negative
 980      * @return an {@code OffsetTime} based on this time with the seconds subtracted, not null
 981      */
 982     public OffsetTime minusSeconds(long seconds) {
 983         return with(time.minusSeconds(seconds), offset);
 984     }
 985 
 986     /**
 987      * Returns a copy of this {@code OffsetTime} with the specified period in nanoseconds subtracted.
 988      * <p>
 989      * This subtracts the specified number of nanoseconds from this time, returning a new time.
 990      * The calculation wraps around midnight.
 991      * <p>
 992      * This instance is immutable and unaffected by this method call.
 993      *
 994      * @param nanos  the nanos to subtract, may be negative
 995      * @return an {@code OffsetTime} based on this time with the nanoseconds subtracted, not null
 996      */
 997     public OffsetTime minusNanos(long nanos) {
 998         return with(time.minusNanos(nanos), offset);
 999     }
1000 
1001     //-----------------------------------------------------------------------
1002     /**
1003      * Queries this time using the specified query.
1004      * <p>
1005      * This queries this time using the specified query strategy object.
1006      * The {@code TemporalQuery} object defines the logic to be used to
1007      * obtain the result. Read the documentation of the query to understand
1008      * what the result of this method will be.
1009      * <p>
1010      * The result of this method is obtained by invoking the
1011      * {@link TemporalQuery#queryFrom(TemporalAccessor)} method on the
1012      * specified query passing {@code this} as the argument.
1013      *
1014      * @param <R> the type of the result
1015      * @param query  the query to invoke, not null
1016      * @return the query result, null may be returned (defined by the query)
1017      * @throws DateTimeException if unable to query (defined by the query)
1018      * @throws ArithmeticException if numeric overflow occurs (defined by the query)
1019      */
1020     @SuppressWarnings("unchecked")
1021     @Override
1022     public <R> R query(TemporalQuery<R> query) {
1023         if (query == Queries.offset() || query == Queries.zone()) {
1024             return (R) offset;
1025         } else if (query == Queries.zoneId() | query == Queries.chronology() || query == Queries.localDate()) {
1026             return null;
1027         } else if (query == Queries.localTime()) {
1028             return (R) time;
1029         } else if (query == Queries.precision()) {
1030             return (R) NANOS;
1031         }
1032         // inline TemporalAccessor.super.query(query) as an optimization
1033         // non-JDK classes are not permitted to make this optimization
1034         return query.queryFrom(this);
1035     }
1036 
1037     /**
1038      * Adjusts the specified temporal object to have the same offset and time
1039      * as this object.
1040      * <p>
1041      * This returns a temporal object of the same observable type as the input
1042      * with the offset and time changed to be the same as this.
1043      * <p>
1044      * The adjustment is equivalent to using {@link Temporal#with(TemporalField, long)}
1045      * twice, passing {@link ChronoField#OFFSET_SECONDS} and
1046      * {@link ChronoField#NANO_OF_DAY} as the fields.
1047      * <p>
1048      * In most cases, it is clearer to reverse the calling pattern by using
1049      * {@link Temporal#with(TemporalAdjuster)}:
1050      * <pre>
1051      *   // these two lines are equivalent, but the second approach is recommended
1052      *   temporal = thisOffsetTime.adjustInto(temporal);
1053      *   temporal = temporal.with(thisOffsetTime);
1054      * </pre>
1055      * <p>
1056      * This instance is immutable and unaffected by this method call.
1057      *
1058      * @param temporal  the target object to be adjusted, not null
1059      * @return the adjusted object, not null
1060      * @throws DateTimeException if unable to make the adjustment
1061      * @throws ArithmeticException if numeric overflow occurs
1062      */
1063     @Override
1064     public Temporal adjustInto(Temporal temporal) {
1065         return temporal
1066                 .with(OFFSET_SECONDS, offset.getTotalSeconds())
1067                 .with(NANO_OF_DAY, time.toNanoOfDay());
1068     }
1069 
1070     /**
1071      * Calculates the period between this time and another time in
1072      * terms of the specified unit.
1073      * <p>
1074      * This calculates the period between two times in terms of a single unit.
1075      * The start and end points are {@code this} and the specified time.
1076      * The result will be negative if the end is before the start.
1077      * For example, the period in hours between two times can be calculated
1078      * using {@code startTime.periodUntil(endTime, HOURS)}.
1079      * <p>
1080      * The {@code Temporal} passed to this method must be an {@code OffsetTime}.
1081      * If the offset differs between the two times, then the specified
1082      * end time is normalized to have the same offset as this time.
1083      * <p>
1084      * The calculation returns a whole number, representing the number of
1085      * complete units between the two times.
1086      * For example, the period in hours between 11:30Z and 13:29Z will only
1087      * be one hour as it is one minute short of two hours.
1088      * <p>
1089      * There are two equivalent ways of using this method.
1090      * The first is to invoke this method.
1091      * The second is to use {@link TemporalUnit#between(Temporal, Temporal)}:
1092      * <pre>
1093      *   // these two lines are equivalent
1094      *   amount = start.periodUntil(end, MINUTES);
1095      *   amount = MINUTES.between(start, end);
1096      * </pre>
1097      * The choice should be made based on which makes the code more readable.
1098      * <p>
1099      * The calculation is implemented in this method for {@link ChronoUnit}.
1100      * The units {@code NANOS}, {@code MICROS}, {@code MILLIS}, {@code SECONDS},
1101      * {@code MINUTES}, {@code HOURS} and {@code HALF_DAYS} are supported.
1102      * Other {@code ChronoUnit} values will throw an exception.
1103      * <p>
1104      * If the unit is not a {@code ChronoUnit}, then the result of this method
1105      * is obtained by invoking {@code TemporalUnit.between(Temporal, Temporal)}
1106      * passing {@code this} as the first argument and the input temporal as
1107      * the second argument.
1108      * <p>
1109      * This instance is immutable and unaffected by this method call.
1110      *
1111      * @param endTime  the end time, which must be an {@code OffsetTime}, not null
1112      * @param unit  the unit to measure the period in, not null
1113      * @return the amount of the period between this time and the end time
1114      * @throws DateTimeException if the period cannot be calculated
1115      * @throws ArithmeticException if numeric overflow occurs
1116      */
1117     @Override
1118     public long periodUntil(Temporal endTime, TemporalUnit unit) {
1119         if (endTime instanceof OffsetTime == false) {
1120             Objects.requireNonNull(endTime, "endTime");
1121             throw new DateTimeException("Unable to calculate period between objects of two different types");
1122         }
1123         if (unit instanceof ChronoUnit) {
1124             OffsetTime end = (OffsetTime) endTime;
1125             long nanosUntil = end.toEpochNano() - toEpochNano();  // no overflow
1126             switch ((ChronoUnit) unit) {
1127                 case NANOS: return nanosUntil;
1128                 case MICROS: return nanosUntil / 1000;
1129                 case MILLIS: return nanosUntil / 1000_000;
1130                 case SECONDS: return nanosUntil / NANOS_PER_SECOND;
1131                 case MINUTES: return nanosUntil / NANOS_PER_MINUTE;
1132                 case HOURS: return nanosUntil / NANOS_PER_HOUR;
1133                 case HALF_DAYS: return nanosUntil / (12 * NANOS_PER_HOUR);
1134             }
1135             throw new DateTimeException("Unsupported unit: " + unit.getName());
1136         }
1137         return unit.between(this, endTime);
1138     }
1139 
1140     //-----------------------------------------------------------------------
1141     /**
1142      * Combines this date with a time to create an {@code OffsetDateTime}.
1143      * <p>
1144      * This returns an {@code OffsetDateTime} formed from this time and the specified date.
1145      * All possible combinations of date and time are valid.
1146      *
1147      * @param date  the date to combine with, not null
1148      * @return the offset date-time formed from this time and the specified date, not null
1149      */
1150     public OffsetDateTime atDate(LocalDate date) {
1151         return OffsetDateTime.of(date, time, offset);
1152     }
1153 
1154     //-----------------------------------------------------------------------
1155     /**
1156      * Converts this time to epoch nanos based on 1970-01-01Z.
1157      *
1158      * @return the epoch nanos value
1159      */
1160     private long toEpochNano() {
1161         long nod = time.toNanoOfDay();
1162         long offsetNanos = offset.getTotalSeconds() * NANOS_PER_SECOND;
1163         return nod - offsetNanos;
1164     }
1165 
1166     //-----------------------------------------------------------------------
1167     /**
1168      * Compares this {@code OffsetTime} to another time.
1169      * <p>
1170      * The comparison is based first on the UTC equivalent instant, then on the local time.
1171      * It is "consistent with equals", as defined by {@link Comparable}.
1172      * <p>
1173      * For example, the following is the comparator order:
1174      * <ol>
1175      * <li>{@code 10:30+01:00}</li>
1176      * <li>{@code 11:00+01:00}</li>
1177      * <li>{@code 12:00+02:00}</li>
1178      * <li>{@code 11:30+01:00}</li>
1179      * <li>{@code 12:00+01:00}</li>
1180      * <li>{@code 12:30+01:00}</li>
1181      * </ol>
1182      * Values #2 and #3 represent the same instant on the time-line.
1183      * When two values represent the same instant, the local time is compared
1184      * to distinguish them. This step is needed to make the ordering
1185      * consistent with {@code equals()}.
1186      * <p>
1187      * To compare the underlying local time of two {@code TemporalAccessor} instances,
1188      * use {@link ChronoField#NANO_OF_DAY} as a comparator.
1189      *
1190      * @param other  the other time to compare to, not null
1191      * @return the comparator value, negative if less, positive if greater
1192      * @throws NullPointerException if {@code other} is null
1193      */
1194     @Override
1195     public int compareTo(OffsetTime other) {
1196         if (offset.equals(other.offset)) {
1197             return time.compareTo(other.time);
1198         }
1199         int compare = Long.compare(toEpochNano(), other.toEpochNano());
1200         if (compare == 0) {
1201             compare = time.compareTo(other.time);
1202         }
1203         return compare;
1204     }
1205 
1206     //-----------------------------------------------------------------------
1207     /**
1208      * Checks if the instant of this {@code OffsetTime} is after that of the
1209      * specified time applying both times to a common date.
1210      * <p>
1211      * This method differs from the comparison in {@link #compareTo} in that it
1212      * only compares the instant of the time. This is equivalent to converting both
1213      * times to an instant using the same date and comparing the instants.
1214      *
1215      * @param other  the other time to compare to, not null
1216      * @return true if this is after the instant of the specified time
1217      */
1218     public boolean isAfter(OffsetTime other) {
1219         return toEpochNano() > other.toEpochNano();
1220     }
1221 
1222     /**
1223      * Checks if the instant of this {@code OffsetTime} is before that of the
1224      * specified time applying both times to a common date.
1225      * <p>
1226      * This method differs from the comparison in {@link #compareTo} in that it
1227      * only compares the instant of the time. This is equivalent to converting both
1228      * times to an instant using the same date and comparing the instants.
1229      *
1230      * @param other  the other time to compare to, not null
1231      * @return true if this is before the instant of the specified time
1232      */
1233     public boolean isBefore(OffsetTime other) {
1234         return toEpochNano() < other.toEpochNano();
1235     }
1236 
1237     /**
1238      * Checks if the instant of this {@code OffsetTime} is equal to that of the
1239      * specified time applying both times to a common date.
1240      * <p>
1241      * This method differs from the comparison in {@link #compareTo} and {@link #equals}
1242      * in that it only compares the instant of the time. This is equivalent to converting both
1243      * times to an instant using the same date and comparing the instants.
1244      *
1245      * @param other  the other time to compare to, not null
1246      * @return true if this is equal to the instant of the specified time
1247      */
1248     public boolean isEqual(OffsetTime other) {
1249         return toEpochNano() == other.toEpochNano();
1250     }
1251 
1252     //-----------------------------------------------------------------------
1253     /**
1254      * Checks if this time is equal to another time.
1255      * <p>
1256      * The comparison is based on the local-time and the offset.
1257      * To compare for the same instant on the time-line, use {@link #isEqual(OffsetTime)}.
1258      * <p>
1259      * Only objects of type {@code OffsetTime} are compared, other types return false.
1260      * To compare the underlying local time of two {@code TemporalAccessor} instances,
1261      * use {@link ChronoField#NANO_OF_DAY} as a comparator.
1262      *
1263      * @param obj  the object to check, null returns false
1264      * @return true if this is equal to the other time
1265      */
1266     @Override
1267     public boolean equals(Object obj) {
1268         if (this == obj) {
1269             return true;
1270         }
1271         if (obj instanceof OffsetTime) {
1272             OffsetTime other = (OffsetTime) obj;
1273             return time.equals(other.time) && offset.equals(other.offset);
1274         }
1275         return false;
1276     }
1277 
1278     /**
1279      * A hash code for this time.
1280      *
1281      * @return a suitable hash code
1282      */
1283     @Override
1284     public int hashCode() {
1285         return time.hashCode() ^ offset.hashCode();
1286     }
1287 
1288     //-----------------------------------------------------------------------
1289     /**
1290      * Outputs this time as a {@code String}, such as {@code 10:15:30+01:00}.
1291      * <p>
1292      * The output will be one of the following ISO-8601 formats:
1293      * <p><ul>
1294      * <li>{@code HH:mmXXXXX}</li>
1295      * <li>{@code HH:mm:ssXXXXX}</li>
1296      * <li>{@code HH:mm:ss.SSSXXXXX}</li>
1297      * <li>{@code HH:mm:ss.SSSSSSXXXXX}</li>
1298      * <li>{@code HH:mm:ss.SSSSSSSSSXXXXX}</li>
1299      * </ul><p>
1300      * The format used will be the shortest that outputs the full value of
1301      * the time where the omitted parts are implied to be zero.
1302      *
1303      * @return a string representation of this time, not null
1304      */
1305     @Override
1306     public String toString() {
1307         return time.toString() + offset.toString();
1308     }
1309 
1310     /**
1311      * Outputs this time as a {@code String} using the formatter.
1312      * <p>
1313      * This time will be passed to the formatter
1314      * {@link DateTimeFormatter#format(TemporalAccessor) format method}.
1315      *
1316      * @param formatter  the formatter to use, not null
1317      * @return the formatted time string, not null
1318      * @throws DateTimeException if an error occurs during printing
1319      */
1320     public String toString(DateTimeFormatter formatter) {
1321         Objects.requireNonNull(formatter, "formatter");
1322         return formatter.format(this);
1323     }
1324 
1325     // -----------------------------------------------------------------------
1326     /**
1327      * Writes the object using a
1328      * <a href="../../../serialized-form.html#java.time.temporal.Ser">dedicated serialized form</a>.
1329      * <pre>
1330      *  out.writeByte(9);  // identifies this as a OffsetDateTime
1331      *  out.writeObject(time);
1332      *  out.writeObject(offset);
1333      * </pre>
1334      *
1335      * @return the instance of {@code Ser}, not null
1336      */
1337     private Object writeReplace() {
1338         return new Ser(Ser.OFFSET_TIME_TYPE, this);
1339     }
1340 
1341     /**
1342      * Defend against malicious streams.
1343      * @return never
1344      * @throws InvalidObjectException always
1345      */
1346     private Object readResolve() throws ObjectStreamException {
1347         throw new InvalidObjectException("Deserialization via serialization delegate");
1348     }
1349 
1350     void writeExternal(ObjectOutput out) throws IOException {
1351         out.writeObject(time);
1352         out.writeObject(offset);
1353     }
1354 
1355     static OffsetTime readExternal(ObjectInput in) throws IOException, ClassNotFoundException {
1356         LocalTime time = (LocalTime) in.readObject();
1357         ZoneOffset offset = (ZoneOffset) in.readObject();
1358         return OffsetTime.of(time, offset);
1359     }
1360 
1361 }