<div dir="ltr">Hi all,<br><br>Thanks for filing JDK-8331202 (<a href="https://bugs.openjdk.org/browse/JDK-8331202">https://bugs.openjdk.org/browse/JDK-8331202</a>).<br><br>I think this proposal is definitely a step in the right direction. The Instant instance method is much more discoverable than the Duration static method. I also think there's a much lower chance of users accidentally swapping the arguments.<br><br>However, I still have concerns about the method name (and thus indirectly the ordering of the arguments). Users are very accustomed to performing this calculation with primitives as (end - start). This is a basic, common, familiar way of thinking about this operation (especially with primitives), and it's a good idea to lean into that familiarity. I understand there's some precedent for until() (thanks for pointing this out, Stephen!), but I think it requires too much "mental gymnastics" to translate from conceptual model to Actual Code.<br><br>Kevin Bourillion has written a great programming guide called "How to Think About Time" (internal to Google for now, but we hope to publish it sometime later this year). One section enumerates the available math operations for the time types:<br><ul><li>instant − instant = duration // what we're discussing</li><li>instant + duration = instant // satisfied by instant.plus(duration)</li><li>instant - duration = instant // satisfied by instant.minus(duration)</li><li>duration + duration = duration // satisfied by duration.plus(duration)</li><li>duration - duration = duration // satisfied by duration.minus(duration)</li><li>duration × real number = duration // satisfied by duration.multipliedBy(long)</li><li>duration ÷ real number = duration // satisfied by duration.dividedBy(long)</li></ul>All but the first operation have very clear translations from conceptual model to code. I'm hoping we can achieve the same clarity for instant - instant by using the obvious name: instant.minus(instant)<br><br>Thanks!<br><br>-Kurt Alfred Kluever<br></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Fri, Apr 26, 2024 at 11:07 AM Roger Riggs <<a href="mailto:roger.riggs@oracle.com">roger.riggs@oracle.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><u></u>

  
  <div>
    A constructive API enhancement.<br>
    Created  <a href="https://bugs.openjdk.org/browse/JDK-8331202" id="m_3041524162104441306key-val" rel="5128047" target="_blank">JDK-8331202</a> Support for duration between
    Instants<br>
    <br>
    Regards, Roger<br>
    <br>
    <div>On 4/25/24 4:53 PM, Stephen Colebourne
      wrote:<br>
    </div>
    <blockquote type="cite">
      <pre>java.time.* already has the `until(ChronoLocalDate)` method on
LocalDate. It would be reasonable to add a similar method to various
other classes. This potentially gives you

 Duration dur = start.until(end)

I'm wary of adding the opposite (given until() is already there). I'm
particularly wary of using minus() as the verb for the opposite as
minus() means something different in other parts of the API (minus()
is used to subtract a TemporalAmounrt, not a Temporal).

Stephen


On Thu, 25 Apr 2024 at 19:57, Kurt Alfred Kluever <a href="mailto:kak@google.com" target="_blank"><kak@google.com></a> wrote:
</pre>
      <blockquote type="cite">
        <pre>Hi core-libs-dev,

The java.time API already supports subtracting two Instants (end - start) via Duration.between(Temporal, Temporal), but we've found the parameter ordering (which requires a bit of "mental gymnastics") and API location to be a bit unnatural.

Parameter Ordering

We very often see folks write code like this: Duration elapsed = Duration.ofMillis(end.toEpochMilli() - start.toEpochMilli());

This closely matches the mental model of what they're trying to accomplish, but it is longer (and more complex) than it needs to be, it drops sub-millisecond precision, and it requires decomposing the java.time types (which we strongly discourage). If you want to "simplify" the above statement, you must remember to swap the argument order: Duration elapsed = Duration.between(start, end);

Many of us find representing (end - start) as between(start, end) to be confusing.

API Location

We do not believe Duration is the most obvious place to find this method; if you want a way to subtract two Instant values, an instance method on Instant is a more obvious place to look. Pushing what could be an instance method to a static utility method feels unnatural.

JDK-8276624 (<a href="https://bugs.openjdk.org/browse/JDK-8276624" target="_blank">https://bugs.openjdk.org/browse/JDK-8276624</a>) proposes to add Temporal.minus(Temporal) as a default method (which would effectively accomplish the same thing), but we do not recommend implementing that proposal as specified. A default method on Temporal would require runtime exceptions to be thrown from other Temporal types like LocalDate or Year. It would also allow oddities like instant.minus(year) to compile (but presumably throw at runtime). Conceptually, this API would not make sense for certain types (e.g., LocalDate — the difference between two LocalDates is a Period, not a Duration).

Instead, we recommend adding a new instance method: instant.minus(instant) (which returns a Duration), and possibly also adding localDate.minus(localDate) (which returns a Period). However note that we've seen a lot of confusion using the Period API (but that's a separate discussion).

While we generally don't like having 2 public APIs that accomplish the same thing, in this case we feel the discoverability and simplicity of the new API(s) outweighs the cost of an additional public API.

Please consider this a +1 from our team to add instant.minus(instant).

Regards,

-Kurt Alfred Kluever (<a href="mailto:kak@google.com" target="_blank">kak@google.com</a>)
(on behalf of Google's Java and Kotlin Ecosystem Team, aka the Guava team)
</pre>
      </blockquote>
    </blockquote>
    <br>
  </div>

</blockquote></div><br clear="all"><div><br></div><span class="gmail_signature_prefix">-- </span><br><div dir="ltr" class="gmail_signature"><font face="sans-serif"><span style="line-height:19px">kak</span></font></div>