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

[Pavel Rappo]

On Tue, 7 Oct 2025 20:14:07 GMT, Stephen Colebourne <scolebourne at openjdk.org> wrote:

> Have any users been asking for these methods, or is it just a case of we think they might be useful?
>

I cannot recall if people specifically asked for those. But from the prior discussion on the mailing list, it seemed that it's what the users do themselves when they handle extreme durations.

These methods are error-prone. And although I think there's value in providing them, if you think it's overkill, we can always settle for capturing them as _examples_ in documentation comments instead.
 
> It is definitely a bit weird that the saturating methods take a `Duration`, while the non-saturating ones take `TemporalAmount`, but I don't think there is a lot that can be done about that.

Should they be required in the future, more generic methods that take `TemporalAmount` can be added to `Temporal`. In the case of `Instant`, they will be harmless overloads.

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

PR Comment: https://git.openjdk.org/jdk/pull/27549#issuecomment-3378645437