Proposal for DateInterval time and date interval difference APIs
#331
Conversation
|
@iCharlesHu @itingliu Hello! Could you please give me some feedback on this proposal? Anything you think should be changed before I share it with the community? |
|
Thank you @kielgillard for the proposal. Some quick process notes - let's number this The template includes a place to put the Swift forum links. So let's go ahead and start that conversation up and point people here for the complete text. |
|
|
||
| Should a developer find themselves needing to compute these values, the proposed additions should feel intuitive because they bear a family resemblance to existing `Date` APIs (e.g.: `timeIntervalSince(_:)`). These additions build on and complement existing intersection and comparision APIs. By easily indicating if two intervals intersect for a moment at opposing ends, developers can more easily determine special cases of intersection. By indicating if one interval is exclusively relative to another in the past or the future, the comparison offering is enriched. The names for these computations are expressive, promoting clarity and readability, especially when developers may be tempted to settle for terse expressions. With the quality of these APIs assured; the convenience saving developers the cognitive load implementing, naming, testing and maintaining these computations and; the presence of these small additions that congeal with intuitions about Foundation types; I would propose these additions are delightful. | ||
|
|
||
| ## Detailed design |
There was a problem hiding this comment.
We usually spell out all the changes in this section. See https://github.com/apple/swift-foundation/pull/321/files for an example.
There was a problem hiding this comment.
Please include the complete source code (declaration only, no implementation needed) and header comments in this section
|
|
||
| `DateInterval` could offer more APIs to help developers work with ranges of absolute moments in time. For example, a developer might be building a log book, shift planner, time tracker or implementing a time based feature in a less specialised app. In the more complex cases, an app may require users to enter start and end times for particular activities, arrange them in a particular sequence with some acceptable gap between (e.g. work here for 2 hours, work there for 1.5 hours and rest for 10 minutes with at most five minutes between, no overlaps, etc). This app would need to validate the intervals formed by the dates entered by at least: checking the intersections of intervals, measuring how much those intervals intersect by and/or by measuring the time between them. In the case of a simpler feature, displaying the time until or since an event, with different formatting or app behaviour on either side (e.g. a library book due/overdue). | ||
|
|
||
| `DateInterval` would be an intuitive type to begin such implementations with. However, developers would quickly hit a limit with its out-of-the-box utility and become responsible for providing what is missing. Further, the precedent set by other Foundation types have shaped our intuitions about what utility we could expect of it. |
There was a problem hiding this comment.
I think having a concrete example of what developers currently need to do here with a comparison of what they'll be able to do with the addition API would help the story.
|
|
||
| ## Proposed solution | ||
|
|
||
| I would like to propose a set of small but delightful, quality-assured additions to `DateInterval` for computing the time or date interval between two, potentially non-intersecting date intervals: `timeIntervalSince(_:)`, `dateIntervalSince(_:)`. I would propose two overloads for these APIs: one taking `DateInterval` values and another taking `Date` values. |
There was a problem hiding this comment.
Same comment here -- it's useful to show an example for the proposed API in code
|
|
||
| Should a developer find themselves needing to compute these values, the proposed additions should feel intuitive because they bear a family resemblance to existing `Date` APIs (e.g.: `timeIntervalSince(_:)`). These additions build on and complement existing intersection and comparision APIs. By easily indicating if two intervals intersect for a moment at opposing ends, developers can more easily determine special cases of intersection. By indicating if one interval is exclusively relative to another in the past or the future, the comparison offering is enriched. The names for these computations are expressive, promoting clarity and readability, especially when developers may be tempted to settle for terse expressions. With the quality of these APIs assured; the convenience saving developers the cognitive load implementing, naming, testing and maintaining these computations and; the presence of these small additions that congeal with intuitions about Foundation types; I would propose these additions are delightful. | ||
|
|
||
| ## Detailed design |
There was a problem hiding this comment.
Please include the complete source code (declaration only, no implementation needed) and header comments in this section
|
|
||
| ## Future directions | ||
|
|
||
| `DateInterval` could gain more API inspired by operations in set theory. I would expect these proposed additions can be subsumed and compatible with such a direction. |
There was a problem hiding this comment.
It'd be useful if you can give a few concrete examples of these. But if they're not clearly related to this proposal I'd recommend leaving them out from this proposal
iCharlesHu
added
API Change
See #330 for the implementation.