java/time/Instant.java

192  * This includes {@code Instant}, {@code LocalDate}, {@code LocalTime}, {@code OffsetDateTime},
199  * {@code Instant} may have unpredictable results and should be avoided.
207 public final class Instant
208         implements Temporal, TemporalAdjuster, Comparable<Instant>, Serializable {
213     public static final Instant EPOCH = new Instant(0, 0);
223      * The minimum supported {@code Instant}, '-1000000000-01-01T00:00Z'.
232     public static final Instant MIN = Instant.ofEpochSecond(MIN_SECOND, 0);
234      * The maximum supported {@code Instant}, '1000000000-12-31T23:59:59.999999999Z'.
243     public static final Instant MAX = Instant.ofEpochSecond(MAX_SECOND, 999_999_999);
272     public static Instant now() {
287     public static Instant now(Clock clock) {
294      * Obtains an instance of {@code Instant} using seconds from the
303     public static Instant ofEpochSecond(long epochSecond) {
308      * Obtains an instance of {@code Instant} using seconds from the
316      *  Instant.ofEpochSecond(3, 1);
317      *  Instant.ofEpochSecond(4, -999_999_999);
318      *  Instant.ofEpochSecond(2, 1000_000_001);
327     public static Instant ofEpochSecond(long epochSecond, long nanoAdjustment) {
334      * Obtains an instance of {@code Instant} using milliseconds from the
343     public static Instant ofEpochMilli(long epochMilli) {
351      * Obtains an instance of {@code Instant} from a temporal object.
355      * which this factory converts to an instance of {@code Instant}.
361      * allowing it to be used as a query via method reference, {@code Instant::from}.
365      * @throws DateTimeException if unable to convert to an {@code Instant}
367     public static Instant from(TemporalAccessor temporal) {
368         if (temporal instanceof Instant) {
369             return (Instant) temporal;
375             return Instant.ofEpochSecond(instantSecs, nanoOfSecond);
377             throw new DateTimeException("Unable to obtain Instant from TemporalAccessor: " +
384      * Obtains an instance of {@code Instant} from a text string such as
394     public static Instant parse(final CharSequence text) {
395         return DateTimeFormatter.ISO_INSTANT.parse(text, Instant::from);
400      * Obtains an instance of {@code Instant} using seconds and nanoseconds.
406     private static Instant create(long seconds, int nanoOfSecond) {
411             throw new DateTimeException("Instant exceeds minimum or maximum instant");
413         return new Instant(seconds, nanoOfSecond);
417      * Constructs an instance of {@code Instant} using seconds from the epoch of
423     private Instant(long epochSecond, int nanos) {
638      * This returns an {@code Instant}, based on this one, with the instant adjusted.
649      * @return an {@code Instant} based on {@code this} with the adjustment made, not null
654     public Instant with(TemporalAdjuster adjuster) {
655         return (Instant) adjuster.adjustInto(this);
661      * This returns an {@code Instant}, based on this one, with the value
670      *  Returns an {@code Instant} with the specified nano-of-second.
673      *  Returns an {@code Instant} with the nano-of-second replaced by the specified
676      *  Returns an {@code Instant} with the nano-of-second replaced by the specified
679      *  Returns an {@code Instant} with the specified epoch-second.
697      * @return an {@code Instant} based on {@code this} with the specified field set, not null
703     public Instant with(TemporalField field, long newValue) {
726      * Returns a copy of this {@code Instant} truncated to the specified unit.
743      * @return an {@code Instant} based on this instant with the time truncated, not null
747     public Instant truncatedTo(TemporalUnit unit) {
768      * This returns an {@code Instant}, based on this one, with the specified amount added.
781      * @return an {@code Instant} based on this instant with the addition made, not null
786     public Instant plus(TemporalAmount amountToAdd) {
787         return (Instant) amountToAdd.addTo(this);
793      * This returns an {@code Instant}, based on this one, with the amount
801      *  Returns an {@code Instant} with the specified number of nanoseconds added.
804      *  Returns an {@code Instant} with the specified number of microseconds added.
808      *  Returns an {@code Instant} with the specified number of milliseconds added.
812      *  Returns an {@code Instant} with the specified number of seconds added.
815      *  Returns an {@code Instant} with the specified number of minutes added.
819      *  Returns an {@code Instant} with the specified number of hours added.
823      *  Returns an {@code Instant} with the specified number of half-days added.
827      *  Returns an {@code Instant} with the specified number of days added.
843      * @return an {@code Instant} based on this instant with the specified amount added, not null
849     public Instant plus(long amountToAdd, TemporalUnit unit) {
873      * @return an {@code Instant} based on this instant with the specified seconds added, not null
877     public Instant plusSeconds(long secondsToAdd) {
887      * @return an {@code Instant} based on this instant with the specified milliseconds added, not null
891     public Instant plusMillis(long millisToAdd) {
901      * @return an {@code Instant} based on this instant with the specified nanoseconds added, not null
905     public Instant plusNanos(long nanosToAdd) {
916      * @return an {@code Instant} based on this instant with the specified seconds added, not null
920     private Instant plus(long secondsToAdd, long nanosToAdd) {
935      * This returns an {@code Instant}, based on this one, with the specified amount subtracted.
948      * @return an {@code Instant} based on this instant with the subtraction made, not null
953     public Instant minus(TemporalAmount amountToSubtract) {
954         return (Instant) amountToSubtract.subtractFrom(this);
960      * This returns an {@code Instant}, based on this one, with the amount
971      * @return an {@code Instant} based on this instant with the specified amount subtracted, not null
977     public Instant minus(long amountToSubtract, TemporalUnit unit) {
988      * @return an {@code Instant} based on this instant with the specified seconds subtracted, not null
992     public Instant minusSeconds(long secondsToSubtract) {
1005      * @return an {@code Instant} based on this instant with the specified milliseconds subtracted, not null
1009     public Instant minusMillis(long millisToSubtract) {
1022      * @return an {@code Instant} based on this instant with the specified nanoseconds subtracted, not null
1026     public Instant minusNanos(long nanosToSubtract) {
1100      * This calculates the amount of time between two {@code Instant}
1107      * {@code Instant} using {@link #from(TemporalAccessor)}.
1133      * @param endExclusive  the end date, exclusive, which is converted to an {@code Instant}, not null
1137      *  temporal cannot be converted to an {@code Instant}
1143         Instant end = Instant.from(endExclusive);
1161     private long nanosUntil(Instant end) {
1167     private long secondsUntil(Instant end) {
1187      * {@link OffsetDateTime#ofInstant(Instant, ZoneId) OffsetDateTime.ofInstant(this, offset)}.
1205      * {@link ZonedDateTime#ofInstant(Instant, ZoneId) ZonedDateTime.ofInstant(this, zone)}.
1253     public int compareTo(Instant otherInstant) {
1270     public boolean isAfter(Instant otherInstant) {
1283     public boolean isBefore(Instant otherInstant) {
1301         if (otherInstant instanceof Instant) {
1302             Instant other = (Instant) otherInstant;
1338      *  out.writeByte(2);  // identifies an Instant
1364     static Instant readExternal(DataInput in) throws IOException {
1367         return Instant.ofEpochSecond(seconds, nanos);