-
Notifications
You must be signed in to change notification settings - Fork 155
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add "kinds of durations" section to Duration
docs
#639
Conversation
Codecov Report
@@ Coverage Diff @@
## main #639 +/- ##
==========================================
+ Coverage 97.82% 97.84% +0.02%
==========================================
Files 16 16
Lines 3727 3765 +38
Branches 637 638 +1
==========================================
+ Hits 3646 3684 +38
Misses 79 79
Partials 2 2
Continue to review full report at Codecov.
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks!
Thinking about Temporal's strong typing approach, the words "There are two kinds of durations" seem to indicate to me that we really should have two duration types, and coincidentally that ties in with today's comment on Duration.compare: #608 (comment)
I'm OK with merging this anyway, though, and thinking about splitting Duration into two types in another issue (much as I dislike the idea of adding more types...) Any thoughts from others?
Yep, I agree that this inconsistency is surprising given how strict the rest of Temporal is about avoiding ambiguity.
Yeah, this PR was both a way to help initial users and as a not-so-subtle hint that documentation may not be enough to solve this problem. ;-) At a high level, there are three possible solutions:
I've drafted a write-up of 10-ish total variations on these three basic approaches, each with its own pros and cons. It's kinda long. What's the best venue to discuss? The discussion currently seems spread across a few GH issues, none of which are exactly focused on the core "Durations can mean two things" problem. |
Co-authored-by: Philip Chimento <[email protected]>
Ugh, I was reminded today that there's really a third kind of Duration: an RFC-5545 (iCalendar) duration, where the date portion is a "date/time" duration but the time portion is an "absolute" duration. Even outside of the iCalendar standard, AFAIK this is a common pattern. For example, moment.js uses it, at least when adding/subtracting single units because it tends to match most users' expectations: that short time intervals (e.g. 15-minute event reminder time) are calculated in absolute time, while longer durations (e.g. 2-day event) are calculated in a way that keeps local times unchanged when adding/subtracting durations. Anyway, tomorrow I'll take a second look at this docs content in this PR and see if there's an obvious way to communicate how to work with this third kind of duration without overcomplicating things too much. |
Is that really a third kind of Duration? It seems to me even in a "nominal" duration, the hours/minutes/seconds are still "accurate"? |
Yep, it's different, although only in a narrow case: when you want the time portion of a duration to measure clock time not absolute time. Here's an example: // "fall back" DST transition in America/Los_Angeles
fallBack = Temporal.Absolute.from('2020-11-01T09:00Z')
fallBack.minus({hours:1}).toString()
// => "2020-11-01T08:00Z"
fallBack.inTimeZone('America/Los_Angeles').minus({hours:1}).inTimeZone('America/Los_Angeles').toString()
// => "2020-11-01T07:00Z" If we decided that the case of "clock time durations" wasn't important to support (FWIW, clock time durations aren't supported in Java nor .NET, and seem relatively uncommon in real-world use cases-- so this may not be as crazy as it sounds) then we could simply specify that all Temporal durations' time portion was exact/absolute, and the only difference in meaning between the kinds is the meaning of the date portion. Was that what you were suggesting? If yes, that'd imply that we'd have to do one or both of the following:
Also, if a time-only (or date/time) duration meant only absolute time, then |
I decided to delay updates to these docs until I finished the JSDoc and implementation of RFC5545 duration handling in the ZonedAbsolute prototype's |
The information in this PR seems to be outdated in light of LocalDateTime — should we close it or try to revise it? |
Closing as I think this is no longer relevant as mentioned in #639 (comment) |
Per the discussion in #559,
Duration
is challenging to make DST-safe because (unlikeDateTime
vs.Absolute
), there's no way to know that the duration in a particularDuration
instance represents an "absolute" duration or a "date/time" duration.This PR adds a new section in the summary of the
Duration
documentation that:Temporal.Absolute
methods.