Clarification to TimeUnit.convert(Duration)

[Chen Liang]

Hi Pavel,

I don't think specifying the enum constants is particularly meaningful - maybe future constants also have overflowing operations. Wording like "conversion methods on Duration" instead of just toNanos/toMillis would be more helpful though.

Chen
________________________________
From: concurrency-discuss <concurrency-discuss-retn at openjdk.org> on behalf of Pavel Rappo <pavel.rappo at gmail.com>
Sent: Monday, October 13, 2025 10:11 AM
To: concurrency-discuss at openjdk.org <concurrency-discuss at openjdk.org>
Subject: Re: Clarification to TimeUnit.convert(Duration)

ping

On Fri, Oct 3, 2025 at 9:54 PM Pavel Rappo <pavel.rappo at gmail.com> wrote:
>
> TimeUnit.covert(Duration)'s receiver is an enum constant. Different
> constants result in different converstions. So, it's a bit vague to
> contrast "this method" to a specific conversion (in this case,
> nanoseconds). Would this small clarification benefit the reader? If
> so, I could create a PR.
>
> diff --git a/src/java.base/share/classes/java/util/concurrent/TimeUnit.java
> b/src/java.base/share/classes/java/util/concurrent/TimeUnit.java
> index d116fb9b22b..6135461cf48 100644
> --- a/src/java.base/share/classes/java/util/concurrent/TimeUnit.java
> +++ b/src/java.base/share/classes/java/util/concurrent/TimeUnit.java
> @@ -203,8 +203,11 @@ public long convert(long sourceDuration, TimeUnit
> sourceUnit) {
>       * is equivalent to {@code n} (in the absence of overflow).
>       *
>       * @apiNote
> -     * This method differs from {@link Duration#toNanos()} in that it
> -     * does not throw {@link ArithmeticException} on numeric overflow.
> +     * {@link #NANOSECONDS}{@code .convert(Duration)} and
> +     * {@link #MILLISECONDS}{@code .convert(Duration)} differ from
> +     * {@link Duration#toNanos()} and {@link Duration#toMillis()} respectively
> +     * in that they do not throw {@link ArithmeticException} on numeric
> +     * overflow.
>       *
>       * @param duration the time duration
>       * @return the converted duration in this unit,
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/concurrency-discuss/attachments/20251014/66a665e3/attachment-0001.htm>