In support of Instant.minus(Instant)
Roger Riggs
roger.riggs at oracle.com
Fri May 3 13:39:01 UTC 2024
Hi,
I would also reinforce Stephen's early observation that the pattern for
"until" methods in java.time includes those of the XXXDate classes, with
a single Temporal parameter. Period and Duration are similar values
holding relative TemporalAmounts.
public Period until(ChronoLocalDate endDateExclusive)
In addition to Instant, the LocalTime class might also benefit from adding:
public Duration until(LocalTime endExclusive)`
The API design of java.time included an emphasis on consistent naming
across the packages.
Regards, Roger
On 5/2/24 4:01 PM, Naoto Sato wrote:
> `Temporal` interface is clear that its `minus` methods return objects
> of the same `Temporal` type, and `until` calculates the amount of time
> until another `Temporal` type. Introducing `Instant.minus` that
> returns `Duration` would be confusing to me.
>
> Naoto
>
> On 5/2/24 10:41 AM, Éamonn McManus wrote:
>> I'd say too that this makes intuitive sense based on algebra. If we
>> have:
>> /instant1/ + /duration/ = /instant2/
>> then we can subtract /duration/ from both sides:
>> /instant1 = instant2 - duration/
>> or we can subtract /instant1/ from both sides:
>> /duration = instant2 - instant1/
>>
>> There's no manipulation we can do that would cause us to try to add
>> instants together, and it's a bit surprising for the API to allow the
>> first subtraction but not the second.
>> I also think that if I see instant2.minus(instant1) it's immediately
>> obvious to me what that means, while instant1.until(instant2) seems
>> both less discoverable and less obvious.
>>
>> On Thu, 2 May 2024 at 10:29, Louis Wasserman <lowasser at google.com
>> <mailto:lowasser at google.com>> wrote:
>>
>> That doesn't follow for me at all.
>>
>> The structure formed by Instants and Durations is an affine space
>> <https://en.wikipedia.org/wiki/Affine_space#Definition>, with
>> instants the points and durations the vectors. (An affine space is
>> a vector space without a distinguished origin, which of course
>> Instants don't have.) It is 100% standard to use the minus sign for
>> the operation "point - point = vector," even when "point + point" is
>> not defined, and to use all the other standard idioms for
>> subtraction; the Wikipedia article uses "subtraction" and
>> "difference" ubiquitously.
>>
>> Personally, I'd be willing to live with a different name for the
>> operation, but consider "users keep getting it wrong" a strong
>> enough argument all by itself for a version with the swapped
>> argument order; it's not obvious to me that another API with the
>> same argument order adds enough value over Duration.between to
>> bother with.
>>
>> On Thu, May 2, 2024 at 10:04 AM Stephen Colebourne
>> <scolebourne at joda.org <mailto:scolebourne at joda.org>> wrote:
>>
>> On Thu, 2 May 2024 at 15:58, Kurt Alfred Kluever <kak at google.com
>> <mailto:kak at google.com>> wrote:
>> > instant − instant = duration // what we're discussing
>> > instant + duration = instant // satisfied by
>> instant.plus(duration)
>> > instant - duration = instant // satisfied by
>> instant.minus(duration)
>> > duration + duration = duration // satisfied by
>> duration.plus(duration)
>> > duration - duration = duration // satisfied by
>> duration.minus(duration)
>> > duration × real number = duration // satisfied by
>> duration.multipliedBy(long)
>> > duration ÷ real number = duration // satisfied by
>> duration.dividedBy(long)
>> >
>> > 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)
>>
>> But you can't have
>> instant + instant = ???
>> It doesn't make sense.
>>
>> This is at the heart of why minus isn't right in this case.
>> Stephen
>>
>>
>>
>> -- Louis Wasserman (he/they)
>>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/core-libs-dev/attachments/20240503/873fcb2b/attachment-0001.htm>
More information about the core-libs-dev
mailing list