100 * This class stores all time fields, to a precision of nanoseconds, |
100 * This class stores all time fields, to a precision of nanoseconds, |
101 * as well as a zone offset. |
101 * as well as a zone offset. |
102 * For example, the value "13:45.30.123456789+02:00" can be stored |
102 * For example, the value "13:45.30.123456789+02:00" can be stored |
103 * in an {@code OffsetTime}. |
103 * in an {@code OffsetTime}. |
104 * |
104 * |
105 * <h3>Specification for implementors</h3> |
105 * @implSpec |
106 * This class is immutable and thread-safe. |
106 * This class is immutable and thread-safe. |
107 * |
107 * |
108 * @since 1.8 |
108 * @since 1.8 |
109 */ |
109 */ |
110 public final class OffsetTime |
110 public final class OffsetTime |
1075 .with(NANO_OF_DAY, time.toNanoOfDay()) |
1075 .with(NANO_OF_DAY, time.toNanoOfDay()) |
1076 .with(OFFSET_SECONDS, offset.getTotalSeconds()); |
1076 .with(OFFSET_SECONDS, offset.getTotalSeconds()); |
1077 } |
1077 } |
1078 |
1078 |
1079 /** |
1079 /** |
1080 * Calculates the period between this time and another time in |
1080 * Calculates the amount of time until another time in terms of the specified unit. |
1081 * terms of the specified unit. |
1081 * <p> |
1082 * <p> |
1082 * This calculates the amount of time between two {@code OffsetTime} |
1083 * This calculates the period between two times in terms of a single unit. |
1083 * objects in terms of a single {@code TemporalUnit}. |
1084 * The start and end points are {@code this} and the specified time. |
1084 * The start and end points are {@code this} and the specified time. |
1085 * The result will be negative if the end is before the start. |
1085 * The result will be negative if the end is before the start. |
1086 * For example, the period in hours between two times can be calculated |
1086 * For example, the period in hours between two times can be calculated |
1087 * using {@code startTime.periodUntil(endTime, HOURS)}. |
1087 * using {@code startTime.periodUntil(endTime, HOURS)}. |
1088 * <p> |
1088 * <p> |
1116 * the second argument. |
1116 * the second argument. |
1117 * <p> |
1117 * <p> |
1118 * This instance is immutable and unaffected by this method call. |
1118 * This instance is immutable and unaffected by this method call. |
1119 * |
1119 * |
1120 * @param endTime the end time, which must be an {@code OffsetTime}, not null |
1120 * @param endTime the end time, which must be an {@code OffsetTime}, not null |
1121 * @param unit the unit to measure the period in, not null |
1121 * @param unit the unit to measure the amount in, not null |
1122 * @return the amount of the period between this time and the end time |
1122 * @return the amount of time between this time and the end time |
1123 * @throws DateTimeException if the period cannot be calculated |
1123 * @throws DateTimeException if the amount cannot be calculated |
1124 * @throws UnsupportedTemporalTypeException if the unit is not supported |
1124 * @throws UnsupportedTemporalTypeException if the unit is not supported |
1125 * @throws ArithmeticException if numeric overflow occurs |
1125 * @throws ArithmeticException if numeric overflow occurs |
1126 */ |
1126 */ |
1127 @Override |
1127 @Override |
1128 public long periodUntil(Temporal endTime, TemporalUnit unit) { |
1128 public long periodUntil(Temporal endTime, TemporalUnit unit) { |
1129 if (endTime instanceof OffsetTime == false) { |
1129 if (endTime instanceof OffsetTime == false) { |
1130 Objects.requireNonNull(endTime, "endTime"); |
1130 Objects.requireNonNull(endTime, "endTime"); |
1131 throw new DateTimeException("Unable to calculate period between objects of two different types"); |
1131 throw new DateTimeException("Unable to calculate amount as objects are of two different types"); |
1132 } |
1132 } |
1133 if (unit instanceof ChronoUnit) { |
1133 if (unit instanceof ChronoUnit) { |
1134 OffsetTime end = (OffsetTime) endTime; |
1134 OffsetTime end = (OffsetTime) endTime; |
1135 long nanosUntil = end.toEpochNano() - toEpochNano(); // no overflow |
1135 long nanosUntil = end.toEpochNano() - toEpochNano(); // no overflow |
1136 switch ((ChronoUnit) unit) { |
1136 switch ((ChronoUnit) unit) { |