294 * Obtains an instance of {@code Instant} using seconds from the
295 * epoch of 1970-01-01T00:00:00Z.
296 * <p>
297 * The nanosecond field is set to zero.
298 *
299 * @param epochSecond the number of seconds from 1970-01-01T00:00:00Z
300 * @return an instant, not null
301 * @throws DateTimeException if the instant exceeds the maximum or minimum instant
302 */
303 public static Instant ofEpochSecond(long epochSecond) {
304 return create(epochSecond, 0);
305 }
306
307 /**
308 * Obtains an instance of {@code Instant} using seconds from the
309 * epoch of 1970-01-01T00:00:00Z and nanosecond fraction of second.
310 * <p>
311 * This method allows an arbitrary number of nanoseconds to be passed in.
312 * The factory will alter the values of the second and nanosecond in order
313 * to ensure that the stored nanosecond is in the range 0 to 999,999,999.
314 * For example, the following will result in the exactly the same instant:
315 * <pre>
316 * Instant.ofEpochSecond(3, 1);
317 * Instant.ofEpochSecond(4, -999_999_999);
318 * Instant.ofEpochSecond(2, 1000_000_001);
319 * </pre>
320 *
321 * @param epochSecond the number of seconds from 1970-01-01T00:00:00Z
322 * @param nanoAdjustment the nanosecond adjustment to the number of seconds, positive or negative
323 * @return an instant, not null
324 * @throws DateTimeException if the instant exceeds the maximum or minimum instant
325 * @throws ArithmeticException if numeric overflow occurs
326 */
327 public static Instant ofEpochSecond(long epochSecond, long nanoAdjustment) {
328 long secs = Math.addExact(epochSecond, Math.floorDiv(nanoAdjustment, NANOS_PER_SECOND));
329 int nos = (int)Math.floorMod(nanoAdjustment, NANOS_PER_SECOND);
330 return create(secs, nos);
331 }
332
333 /**
334 * Obtains an instance of {@code Instant} using milliseconds from the
740 * This instance is immutable and unaffected by this method call.
741 *
742 * @param unit the unit to truncate to, not null
743 * @return an {@code Instant} based on this instant with the time truncated, not null
744 * @throws DateTimeException if the unit is invalid for truncation
745 * @throws UnsupportedTemporalTypeException if the unit is not supported
746 */
747 public Instant truncatedTo(TemporalUnit unit) {
748 if (unit == ChronoUnit.NANOS) {
749 return this;
750 }
751 Duration unitDur = unit.getDuration();
752 if (unitDur.getSeconds() > LocalTime.SECONDS_PER_DAY) {
753 throw new UnsupportedTemporalTypeException("Unit is too large to be used for truncation");
754 }
755 long dur = unitDur.toNanos();
756 if ((LocalTime.NANOS_PER_DAY % dur) != 0) {
757 throw new UnsupportedTemporalTypeException("Unit must divide into a standard day without remainder");
758 }
759 long nod = (seconds % LocalTime.SECONDS_PER_DAY) * LocalTime.NANOS_PER_SECOND + nanos;
760 long result = Math.floorDiv(nod, dur) * dur ;
761 return plusNanos(result - nod);
762 }
763
764 //-----------------------------------------------------------------------
765 /**
766 * Returns a copy of this instant with the specified amount added.
767 * <p>
768 * This returns an {@code Instant}, based on this one, with the specified amount added.
769 * The amount is typically {@link Duration} but may be any other type implementing
770 * the {@link TemporalAmount} interface.
771 * <p>
772 * The calculation is delegated to the amount object by calling
773 * {@link TemporalAmount#addTo(Temporal)}. The amount implementation is free
774 * to implement the addition in any way it wishes, however it typically
775 * calls back to {@link #plus(long, TemporalUnit)}. Consult the documentation
776 * of the amount implementation to determine if it can be successfully added.
777 * <p>
778 * This instance is immutable and unaffected by this method call.
779 *
780 * @param amountToAdd the amount to add, not null
|
294 * Obtains an instance of {@code Instant} using seconds from the
295 * epoch of 1970-01-01T00:00:00Z.
296 * <p>
297 * The nanosecond field is set to zero.
298 *
299 * @param epochSecond the number of seconds from 1970-01-01T00:00:00Z
300 * @return an instant, not null
301 * @throws DateTimeException if the instant exceeds the maximum or minimum instant
302 */
303 public static Instant ofEpochSecond(long epochSecond) {
304 return create(epochSecond, 0);
305 }
306
307 /**
308 * Obtains an instance of {@code Instant} using seconds from the
309 * epoch of 1970-01-01T00:00:00Z and nanosecond fraction of second.
310 * <p>
311 * This method allows an arbitrary number of nanoseconds to be passed in.
312 * The factory will alter the values of the second and nanosecond in order
313 * to ensure that the stored nanosecond is in the range 0 to 999,999,999.
314 * For example, the following will result in exactly the same instant:
315 * <pre>
316 * Instant.ofEpochSecond(3, 1);
317 * Instant.ofEpochSecond(4, -999_999_999);
318 * Instant.ofEpochSecond(2, 1000_000_001);
319 * </pre>
320 *
321 * @param epochSecond the number of seconds from 1970-01-01T00:00:00Z
322 * @param nanoAdjustment the nanosecond adjustment to the number of seconds, positive or negative
323 * @return an instant, not null
324 * @throws DateTimeException if the instant exceeds the maximum or minimum instant
325 * @throws ArithmeticException if numeric overflow occurs
326 */
327 public static Instant ofEpochSecond(long epochSecond, long nanoAdjustment) {
328 long secs = Math.addExact(epochSecond, Math.floorDiv(nanoAdjustment, NANOS_PER_SECOND));
329 int nos = (int)Math.floorMod(nanoAdjustment, NANOS_PER_SECOND);
330 return create(secs, nos);
331 }
332
333 /**
334 * Obtains an instance of {@code Instant} using milliseconds from the
740 * This instance is immutable and unaffected by this method call.
741 *
742 * @param unit the unit to truncate to, not null
743 * @return an {@code Instant} based on this instant with the time truncated, not null
744 * @throws DateTimeException if the unit is invalid for truncation
745 * @throws UnsupportedTemporalTypeException if the unit is not supported
746 */
747 public Instant truncatedTo(TemporalUnit unit) {
748 if (unit == ChronoUnit.NANOS) {
749 return this;
750 }
751 Duration unitDur = unit.getDuration();
752 if (unitDur.getSeconds() > LocalTime.SECONDS_PER_DAY) {
753 throw new UnsupportedTemporalTypeException("Unit is too large to be used for truncation");
754 }
755 long dur = unitDur.toNanos();
756 if ((LocalTime.NANOS_PER_DAY % dur) != 0) {
757 throw new UnsupportedTemporalTypeException("Unit must divide into a standard day without remainder");
758 }
759 long nod = (seconds % LocalTime.SECONDS_PER_DAY) * LocalTime.NANOS_PER_SECOND + nanos;
760 long result = Math.floorDiv(nod, dur) * dur;
761 return plusNanos(result - nod);
762 }
763
764 //-----------------------------------------------------------------------
765 /**
766 * Returns a copy of this instant with the specified amount added.
767 * <p>
768 * This returns an {@code Instant}, based on this one, with the specified amount added.
769 * The amount is typically {@link Duration} but may be any other type implementing
770 * the {@link TemporalAmount} interface.
771 * <p>
772 * The calculation is delegated to the amount object by calling
773 * {@link TemporalAmount#addTo(Temporal)}. The amount implementation is free
774 * to implement the addition in any way it wishes, however it typically
775 * calls back to {@link #plus(long, TemporalUnit)}. Consult the documentation
776 * of the amount implementation to determine if it can be successfully added.
777 * <p>
778 * This instance is immutable and unaffected by this method call.
779 *
780 * @param amountToAdd the amount to add, not null
|