RFR: 8368856: Add methods for saturating Duration arithmetic to Instant [v7]

[Roger Riggs]

On Wed, 8 Oct 2025 19:00:44 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> src/java.base/share/classes/java/time/Instant.java line 1011:
>> 
>>> 1009:         }
>>> 1010:     }
>>> 1011: 
>> 
>> Omit minusSaturating, I think subtraction is much less common and even more so to exceed the negative range.
>> The caller can negate their argument and use plus if that's needed.
>
>> Omit minusSaturating, I think subtraction is much less common and even more so to exceed the negative range.
>> The caller can negate their argument and use plus if that's needed.
> 
> On the one hand, I also don't think we need `minusSaturating` as far as the typical use case is concerned. On the other hand, negating durations is a tricky business. Although, it's not a real use case, negating the minimum duration will cause `ArithmeticException`:
> 
> 
> jshell> Duration.ofSeconds(Long.MIN_VALUE, 0).negated()
> |  Exception java.lang.ArithmeticException: Exceeds capacity of Duration: 9223372036854775808000000000
> |        at Duration.create (Duration.java:1056)
> |        at Duration.multipliedBy (Duration.java:995)
> |        at Duration.negated (Duration.java:1074)
> |        at (#2:1)
> 
> 
> So one cannot implement `i.minusSaturaring(Duration.ofSeconds(Long.MIN_VALUE, 0))` as `i.plusSaturating(Duration.ofSeconds(Long.MIN_VALUE, 0).negated())`.

We're defining the values of MIN and MAX and they *could* be defined to be the negation of the other.
The defined use case is a sentinels and the exact value is less significant.
It just a different kind of oddity compared to twos-complement numbers that have their own asymmetry.

-------------

PR Review Comment: https://git.openjdk.org/jdk/pull/27549#discussion_r2414774950