src/share/classes/java/time/OffsetTime.java

Print this page




  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


 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.


 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.


 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();


 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.


 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.


 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);


 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 


1244      * <li>{@code HH:mmXXXXX}</li>
1245      * <li>{@code HH:mm:ssXXXXX}</li>
1246      * <li>{@code HH:mm:ss.SSSXXXXX}</li>
1247      * <li>{@code HH:mm:ss.SSSSSSXXXXX}</li>
1248      * <li>{@code HH:mm:ss.SSSSSSSSSXXXXX}</li>
1249      * </ul><p>
1250      * The format used will be the shortest that outputs the full value of
1251      * the time where the omitted parts are implied to be zero.
1252      *
1253      * @return a string representation of this time, not null
1254      */
1255     @Override
1256     public String toString() {
1257         return time.toString() + offset.toString();
1258     }
1259 
1260     /**
1261      * Outputs this time as a {@code String} using the formatter.
1262      * <p>
1263      * This time will be passed to the formatter
1264      * {@link DateTimeFormatter#print(TemporalAccessor) print method}.
1265      *
1266      * @param formatter  the formatter to use, not null
1267      * @return the formatted time string, not null
1268      * @throws DateTimeException if an error occurs during printing
1269      */
1270     public String toString(DateTimeFormatter formatter) {
1271         Objects.requireNonNull(formatter, "formatter");
1272         return formatter.print(this);
1273     }
1274 
1275     // -----------------------------------------------------------------------
1276     /**
1277      * Writes the object using a
1278      * <a href="../../../serialized-form.html#java.time.temporal.Ser">dedicated serialized form</a>.
1279      * <pre>
1280      *  out.writeByte(2);  // identifies this as a OffsetDateTime
1281      *  out.writeObject(time);
1282      *  out.writeObject(offset);
1283      * </pre>
1284      *
1285      * @return the instance of {@code Ser}, not null
1286      */
1287     private Object writeReplace() {
1288         return new Ser(Ser.OFFSET_TIME_TYPE, this);
1289     }
1290 
1291     /**
1292      * Defend against malicious streams.
1293      * @return never
1294      * @throws InvalidObjectException always
1295      */
1296     private Object readResolve() throws ObjectStreamException {
1297         throw new InvalidObjectException("Deserialization via serialization delegate");
1298     }
1299 
1300     void writeExternal(ObjectOutput out) throws IOException {


  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


 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.


 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.


 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();


 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.


 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.


 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);


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 


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 {