Comparing Instants
The methods isBefore() and isAfter() can be used to determine if one instant is before or after the other on the timeline, respectively.
// instA is 1970-01-01T00:00:00.000000500Z
// instB is 1949-03-01T12:30:15Z
// instC is -1949-03-01T12:30:15Z
out.println(instA.isBefore(instB)); // false
out.println(instA.isAfter(instC)); // true
The Instant class also overrides the equals() method and the hashCode() method of the Object class, and implements the Comparable<Instant> interface. Instants can readily be used in collections. The code below illustrates comparing instants.
out.println(instA.equals(instB)); // false
out.println(instA.equals(instC)); // false
List<Instant> list = Arrays.asList(instA, instB, instC);
Collections.sort(list); // Natural order: position on the timeline.
// [-1949-03-01T12:30:15Z, 1949-03-01T12:30:15Z, 1970-01-01T00:00:00.000000500Z]
boolean isBefore(Instant other)
boolean isAfter(Instant other)
Determine whether this Instant is before or after the other instant on the timeline, respectively.
boolean equals(Object other)
Determines whether this Instant is equal to the other instant, based on the timeline position of the instants.
int hashCode()
Returns a hash code for this Instant.
int compareTo(Instant other)
Compares this Instant with the other instant, based on the timeline position of the instants.
Creating Modified Copies of Instants
The Instant class provides the with(field, newValue) method that returns a copy of this instant with either the epoch-second or the nano-of-second set to a new value, while the other one is unchanged.
Instant with(TemporalField field, long newValue)
Returns a copy of this instant where either the epoch-second or the nano-of-second is set to the specified value. The value of the other is retained.
This method only supports the following ChronoField constants: NANO_OF_SECOND, MICRO_OF_SECOND, MILLI_OF_SECOND, and INSTANT_SECONDS (p. 1046). For the first three fields, the nano-of-second is replaced by appropriately converting the specified value, and the epoch-second will be unchanged in the copy returned by the method. For the INSTANT_SECONDS field, the epoch-second will be replaced and the nanosecond will be unchanged in the copy returned by the method. Valid values that can be specified with these constants are [0–999999999], [0–999999], [0–999], and a long, respectively.
This method throws a DateTimeException if the field cannot be set, an Unsupported-TemporalTypeException if the field is not supported, and an ArithmeticException if number overflow occurs.
In the code below, the three instants i1, i2, and i3 will have the nano-of-second set to 5,000,000,000 nanoseconds using the with() method, but the epoch-second will not be changed.
Instant i0, i1, i2, i3;
i0 = Instant.now();
out.println(i0); // 2021-02-28T08:43:35.864Z
i1 = i0.with(ChronoField.NANO_OF_SECOND, 500_000_000);// 500000000 ns.
i2 = i0.with(ChronoField.MICRO_OF_SECOND, 500_000); // 500000×1000 ns.
i3 = i0.with(ChronoField.MILLI_OF_SECOND, 500); // 500×1000000 ns.
out.println(i1); // 2021-02-28T08:43:35.500Z
out.println(i1.equals(i2)); // true
out.println(i1.equals(i3)); // true
In the code below, oneInstant has the nano-of-second set to 500,000,000 nanoseconds and the epoch-second set to 1 day after the epoch.
Instant oneInstant = Instant.now()
.with(ChronoField.MILLI_OF_SECOND, 500)
.with(ChronoField.INSTANT_SECONDS, 24L*60*60);
out.println(oneInstant); // 1970-01-02T00:00:00.500Z