8368856: Add a method that performs saturating addition of a Duration to an Instant

Reviewed-by: naoto, rriggs, scolebourne

Author: pavelrappo

src/java.base/share/classes/java/time/Instant.java

@@ -788,6 +788,32 @@ public Instant plus(TemporalAmount amountToAdd) {
         return (Instant) amountToAdd.addTo(this);
     }
 
+    /**
+     * Returns a copy of this instant with the specified duration added, with
+     * saturated semantics.
+     * <p>
+     * If the result is "earlier" than {@link Instant#MIN}, this method returns
+     * {@code MIN}. If the result is "later" than {@link Instant#MAX}, it
+     * returns {@code MAX}. Otherwise it returns {@link #plus(TemporalAmount) plus(duration)}.
+     *
+     * @apiNote This method can be used to calculate a deadline from
+     * this instant and a timeout. Unlike {@code plus(duration)},
+     * this method never throws {@link ArithmeticException} or {@link DateTimeException}
+     * due to numeric overflow or {@code Instant} range violation.
+     *
+     * @param duration the duration to add, not null
+     * @return an {@code Instant} based on this instant with the addition made, not null
+     *
+     * @since 26
+     */
+    public Instant plusSaturating(Duration duration) {
+        if (duration.isNegative()) {
+            return until(Instant.MIN).compareTo(duration) >= 0 ? Instant.MIN : plus(duration);
+        } else {
+            return until(Instant.MAX).compareTo(duration) <= 0 ? Instant.MAX : plus(duration);
+        }
+    }
+
     /**
      * Returns a copy of this instant with the specified amount added.
      * <p>

test/jdk/java/time/tck/java/time/TCKInstant.java

@@ -106,6 +106,7 @@
 import java.util.List;
 import java.util.Locale;
 
+import java.util.Optional;
 import org.testng.annotations.BeforeMethod;
 import org.testng.annotations.DataProvider;
 import org.testng.annotations.Test;
@@ -1225,6 +1226,83 @@ public void plusNanos_long_overflowTooSmall() {
         t.plusNanos(-1);
     }
 
+    @DataProvider(name = "PlusSaturating")
+    Object[][] provider_plusSaturating() {
+        return new Object[][]{
+                // 1. {edge or constant instants} x {edge or constant durations}
+                {Instant.MIN, Duration.ofSeconds(Long.MIN_VALUE, 0), Optional.of(Instant.MIN)},
+                {Instant.MIN, Duration.ofSeconds(Long.MIN_VALUE, 0), Optional.of(Instant.MIN)},
+                {Instant.MIN, Duration.ZERO, Optional.empty()},
+                {Instant.MIN, Duration.ofSeconds(Long.MAX_VALUE, 999_999_999), Optional.of(Instant.MAX)},
+                {Instant.EPOCH, Duration.ofSeconds(Long.MIN_VALUE, 0), Optional.of(Instant.MIN)},
+                {Instant.EPOCH, Duration.ZERO, Optional.empty()},
+                {Instant.EPOCH, Duration.ofSeconds(Long.MAX_VALUE, 999_999_999), Optional.of(Instant.MAX)},
+                {Instant.MAX, Duration.ofSeconds(Long.MIN_VALUE, 0), Optional.of(Instant.MIN)},
+                {Instant.MAX, Duration.ZERO, Optional.empty()},
+                {Instant.MAX, Duration.ofSeconds(Long.MAX_VALUE, 999_999_999), Optional.of(Instant.MAX)},
+                // 2. {edge or constant instants} x {normal durations}
+                {Instant.MIN, Duration.ofDays(-32), Optional.of(Instant.MIN)},
+                {Instant.MIN, Duration.ofDays(32), Optional.empty()},
+                {Instant.EPOCH, Duration.ofDays(-32), Optional.empty()},
+                {Instant.EPOCH, Duration.ofDays(32), Optional.empty()},
+                {Instant.MAX, Duration.ofDays(-32), Optional.empty()},
+                {Instant.MAX, Duration.ofDays(32), Optional.of(Instant.MAX)},
+                // 3. {normal instants with both positive and negative epoch seconds} x {edge or constant durations}
+                {Instant.parse("1950-01-01T00:00:00Z"), Duration.ofSeconds(Long.MIN_VALUE, 0), Optional.of(Instant.MIN)},
+                {Instant.parse("1950-01-01T00:00:00Z"), Duration.ZERO, Optional.empty()},
+                {Instant.parse("1950-01-01T00:00:00Z"), Duration.ofSeconds(Long.MAX_VALUE, 999_999_999), Optional.of(Instant.MAX)},
+                {Instant.parse("1990-01-01T00:00:00Z"), Duration.ofSeconds(Long.MIN_VALUE, 0), Optional.of(Instant.MIN)},
+                {Instant.parse("1990-01-01T00:00:00Z"), Duration.ZERO, Optional.empty()},
+                {Instant.parse("1990-01-01T00:00:00Z"), Duration.ofSeconds(Long.MAX_VALUE, 999_999_999), Optional.of(Instant.MAX)},
+                // 4. {normal instants with both positive and negative epoch seconds} x {normal durations}
+                {Instant.parse("1950-01-01T00:00:00Z"), Duration.ofDays(-32), Optional.empty()},
+                {Instant.parse("1950-01-01T00:00:00Z"), Duration.ofDays(32), Optional.empty()},
+                {Instant.parse("1990-01-01T00:00:00Z"), Duration.ofDays(-32), Optional.empty()},
+                {Instant.parse("1990-01-01T00:00:00Z"), Duration.ofDays(32), Optional.empty()},
+                // 5. instant boundary
+                {Instant.MIN, Duration.between(Instant.MIN, Instant.MAX), Optional.of(Instant.MAX)},
+                {Instant.EPOCH, Duration.between(Instant.EPOCH, Instant.MAX), Optional.of(Instant.MAX)},
+                {Instant.EPOCH, Duration.between(Instant.EPOCH, Instant.MIN), Optional.of(Instant.MIN)},
+                {Instant.MAX, Duration.between(Instant.MAX, Instant.MIN), Optional.of(Instant.MIN)}
+        };
+    }
+
+    @Test(dataProvider = "PlusSaturating")
+    public void plusSaturating(Instant i, Duration d, Optional<Instant> value) {
+        var actual = i.plusSaturating(d);
+        try {
+            assertEquals(actual, i.plus(d));
+            // If `value` is present, perform an additional check. It may be
+            // important to ensure that not only does the result of `plusSaturating`
+            // match that of `plus`, but that it also matches our expectation.
+            // Because if it doesn’t, then the test isn’t testing what we think
+            // it is, and needs to be fixed.
+            value.ifPresent(instant -> assertEquals(actual, instant));
+        } catch (DateTimeException /* instant overflow */
+                 | ArithmeticException /* long overflow */ e) {
+            if (value.isEmpty()) {
+                throw new AssertionError();
+            }
+            assertEquals(actual, value.get());
+        }
+    }
+
+    @DataProvider(name = "PlusSaturating_null")
+    Object[][] provider_plusSaturating_null() {
+        return new Object[][]{
+                {Instant.MIN},
+                {Instant.EPOCH},
+                {Instant.MAX},
+                // any non-random but also non-special instant
+                {Instant.parse("2025-10-13T20:47:50.369955Z")},
+        };
+    }
+
+    @Test(expectedExceptions = NullPointerException.class, dataProvider = "PlusSaturating_null")
+    public void test_plusSaturating_null(Instant i) {
+        i.plusSaturating(null);
+    }
+
     //-----------------------------------------------------------------------
     @DataProvider(name="Minus")
     Object[][] provider_minus() {