From 9ed4c945d938b6900ae485c70b60d2c8e6ee4847 Mon Sep 17 00:00:00 2001 From: Kiel Gillard Date: Tue, 28 Nov 2023 18:55:46 +1100 Subject: [PATCH 1/5] Proposal WIP --- Proposals/0002-date-interval-differences.md | 90 +++++++++++++++++++++ 1 file changed, 90 insertions(+) create mode 100644 Proposals/0002-date-interval-differences.md diff --git a/Proposals/0002-date-interval-differences.md b/Proposals/0002-date-interval-differences.md new file mode 100644 index 000000000..9c7bd1797 --- /dev/null +++ b/Proposals/0002-date-interval-differences.md @@ -0,0 +1,90 @@ +# Date Interval Differences + +* Proposal: [FOU-0002](0002-date-interval-differences.md) +* Authors: [Kiel Gillard](https://github.com/kielgillard) +* Review Manager: TBD +* Status: **Awaiting review** +* Implementation: [apple/swift-foundation#330](https://github.com/apple/swift-foundation/pull/330) +* Review: ([pitch](https://forums.swift.org/...)) + +When filling out this template, you should delete or replace all of the text except for the section headers and the header fields above. For example, you should delete everything from this paragraph down to the Introduction section below. + +As a proposal author, you should fill out all of the header fields except `Review Manager`. The review manager will set that field and change several others as part of initiating the review. Delete any header fields marked *if applicable* that are not applicable to your proposal. + +When sharing a link to the proposal while it is still a PR, be sure to share a live link to the proposal, not an exact commit, so that readers will always see the latest version when you make changes. On GitHub, you can find this link by browsing the PR branch: from the PR page, click the "username wants to merge ... from username:my-branch-name" link and find the proposal file in that branch. + +`Status` should reflect the current implementation status while the proposal is still a PR. The proposal cannot be reviewed until an implementation is available, but early readers should see the correct status. + +`Bug` should be used when this proposal is fixing a bug with significant discussion in the bug report. It is not necessary to link bugs that do not contain significant discussion or that merely duplicate discussion linked somewhere else. Do not link bugs from private bug trackers. + +`Implementation` should link to the PR(s) implementing the feature. If the proposal has not been implemented yet, or if it simply codifies existing behavior, just say that. If the implementation has already been committed to the main branch (as an experimental feature), say that and specify the experimental feature flag. If the implementation is spread across multiple PRs, just link to the most important ones. + +`Previous Proposal` should be used when there is a specific line of succession between this proposal and another proposal. For example, this proposal might have been removed from a previous proposal so that it can be reviewed separately, or this proposal might supersede a previous proposal in some way that was felt to exceed the scope of a "revision". Include text briefly explaining the relationship, such as "Supersedes SE-1234" or "Extracted from SE-01234". If possible, link to a post explaining the relationship, such as a review decision that asked for part of the proposal to be split off. Otherwise, you can just link to the previous proposal. + +`Previous Revision` should be added after a major substantive revision of a proposal that has undergone review. It links to the previously reviewed revision. It is not necessary to add or update this field after minor editorial changes. + +`Review` is a history of all discussion threads about this proposal, in chronological order. Use these standardized link names: `pitch` `review` `revision` `acceptance` `rejection`. If there are multiple such threads, spell the ordinal out: `first pitch` `second review` etc. + +## Introduction + +A short description of what the feature is. Try to keep it to a single-paragraph "elevator pitch" so the reader understands what problem this proposal is addressing. + +Add small but convenient, quality-assured methods on `DateInterval` to compute time and date intervals between date intervals to extend and complement existing comparison and intersection APIs. + +## Motivation + +Describe the problems that this proposal seeks to address. If the problem is that some common pattern is currently hard to express, show how one can currently get a similar effect and describe its drawbacks. If it's completely new functionality that cannot be emulated, motivate why this new functionality would help Swift developers create better Swift code. + +`DateInterval` could offer more API helping developers working with ranges of absolute moments in time. For example, a developer might be building a logbook, employment time planner or implementing a time based feature in a less specialised app. In a more complex case, the 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 measuring the time between them or by some moment. `DateInterval` would be an intuitive type to begin such an implementation with but developers would quickly hit a limit with its available interface and become responsible for implementing their logic and maintain its quality. + +## Proposed solution + +Describe your solution to the problem. Provide examples and describe how they work. Show how your solution is better than current workarounds: is it cleaner, safer, or more efficient? + +This section doesn't have to be comprehensive. Focus on the most important parts of the proposal and make arguments about why the proposal is better than the status quo. + +I would like to suggest 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. + +Should a developer find themselves needing to compute values, these additions should feel intuitive because they bear a family resemblance to existing `Date` APIs. They extend the existing intersection APIs by signalling if two intervals intersect for a moment at opposing ends. They complement the comparison API by providing the past or future time between intervals. Effort has been put into expressively describing the computations — promoting readability — especially when developers may be tempted to settle for terse expressions. With the quality of these APIs assured, their convenience saving developers the cognitive load implementing, naming, testing and maintaining these computations, I would suggest these small but not-so-commonly needed additions would delight developers. + +## Detailed design + +Describe the design of the solution in detail. Show the full API and its documentation comments detailing what it does. The detail in this section should be sufficient for someone who is *not* one of the authors to be able to reasonably implement the feature. + +## Source compatibility + +Describe the impact of this proposal on source compatibility. As a general rule, all else being equal, Swift code that worked in previous releases of the tools should work in new releases. That means both that it should continue to build and that it should continue to behave dynamically the same as it did before. + +Consider the impact on existing clients. If clients provide a similar API, will type-checking find the right one? If the feature overloads an existing API, is it problematic that existing users of that API might start resolving to the new API? + +## Implications on adoption + +The compatibility sections above are focused on the direct impact of the proposal on existing code. In this section, describe issues that intentional adopters of the proposal should be aware of. + +Consider the impact on library adopters of those features. Can adopting this feature in a library break source or ABI compatibility for users of the library? If a library adopts the feature, can it be *un*-adopted later without breaking source compatibility? Will package authors be able to selectively adopt this feature depending on the tools version available, or will it require bumping the minimum tools version required by the package? + +If there are no concerns to raise in this section, leave it in with text like "This feature can be freely adopted and un-adopted in source code with no deployment constraints and without affecting source compatibility." + +## Future directions + +Describe any interesting proposals that could build on this proposal in the future. This is especially important when these future directions inform the design of the proposal. + +The rest of the proposal should generally not talk about future directions except by referring to this section. It is important not to confuse reviewers about what is covered by this specific proposal. If there's a larger vision that needs to be explained in order to understand this proposal, consider starting a discussion thread on the forums to capture your broader thoughts. + +Avoid making affirmative statements in this section, such as "we will" or even "we should". Describe the proposals neutrally as possibilities to be considered in the future. + +Consider whether any of these future directions should really just be part of the current proposal. It's important to make focused, self-contained proposals that can be incrementally implemented and reviewed, but it's also good when proposals feel "complete" rather than leaving significant gaps in their design. + +## Alternatives considered + +Describe alternative approaches to addressing the same problem. This is an important part of most proposal documents. Reviewers are often familiar with other approaches prior to review and may have reasons to prefer them. This section is your first opportunity to try to convince them that your approach is the right one, and even if you don't fully succeed, you can help set the terms of the conversation and make the review a much more productive exchange of ideas. + +You should be fair about other proposals, but you do not have to be neutral; after all, you are specifically proposing something else. Describe any advantages these alternatives might have, but also be sure to explain the disadvantages that led you to prefer the approach in this proposal. + +You should update this section during the pitch phase to discuss any particularly interesting alternatives raised by the community. You do not need to list every idea raised during the pitch, just the ones you think raise points that are worth discussing. Of course, if you decide the alternative is more compelling than what's in the current proposal, you should change the main proposal; be sure to then discuss your previous proposal in this section and explain why the new idea is better. + +## Acknowledgments + +If significant changes or improvements suggested by members of the community were incorporated into the proposal as it developed, take a moment here to thank them for their contributions. Swift evolution is a collaborative process, and everyone's input should receive recognition! + +Generally, you should not acknowledge anyone who is listed as a co-author or as the review manager. From 66abfc82e60cab0de786507663598c4b28b847cd Mon Sep 17 00:00:00 2001 From: Kiel Gillard Date: Tue, 28 Nov 2023 19:24:47 +1100 Subject: [PATCH 2/5] more words --- Proposals/0002-date-interval-differences.md | 32 +++------------------ 1 file changed, 4 insertions(+), 28 deletions(-) diff --git a/Proposals/0002-date-interval-differences.md b/Proposals/0002-date-interval-differences.md index 9c7bd1797..0324a1322 100644 --- a/Proposals/0002-date-interval-differences.md +++ b/Proposals/0002-date-interval-differences.md @@ -7,45 +7,21 @@ * Implementation: [apple/swift-foundation#330](https://github.com/apple/swift-foundation/pull/330) * Review: ([pitch](https://forums.swift.org/...)) -When filling out this template, you should delete or replace all of the text except for the section headers and the header fields above. For example, you should delete everything from this paragraph down to the Introduction section below. - -As a proposal author, you should fill out all of the header fields except `Review Manager`. The review manager will set that field and change several others as part of initiating the review. Delete any header fields marked *if applicable* that are not applicable to your proposal. - -When sharing a link to the proposal while it is still a PR, be sure to share a live link to the proposal, not an exact commit, so that readers will always see the latest version when you make changes. On GitHub, you can find this link by browsing the PR branch: from the PR page, click the "username wants to merge ... from username:my-branch-name" link and find the proposal file in that branch. - -`Status` should reflect the current implementation status while the proposal is still a PR. The proposal cannot be reviewed until an implementation is available, but early readers should see the correct status. - -`Bug` should be used when this proposal is fixing a bug with significant discussion in the bug report. It is not necessary to link bugs that do not contain significant discussion or that merely duplicate discussion linked somewhere else. Do not link bugs from private bug trackers. - -`Implementation` should link to the PR(s) implementing the feature. If the proposal has not been implemented yet, or if it simply codifies existing behavior, just say that. If the implementation has already been committed to the main branch (as an experimental feature), say that and specify the experimental feature flag. If the implementation is spread across multiple PRs, just link to the most important ones. - -`Previous Proposal` should be used when there is a specific line of succession between this proposal and another proposal. For example, this proposal might have been removed from a previous proposal so that it can be reviewed separately, or this proposal might supersede a previous proposal in some way that was felt to exceed the scope of a "revision". Include text briefly explaining the relationship, such as "Supersedes SE-1234" or "Extracted from SE-01234". If possible, link to a post explaining the relationship, such as a review decision that asked for part of the proposal to be split off. Otherwise, you can just link to the previous proposal. - -`Previous Revision` should be added after a major substantive revision of a proposal that has undergone review. It links to the previously reviewed revision. It is not necessary to add or update this field after minor editorial changes. - -`Review` is a history of all discussion threads about this proposal, in chronological order. Use these standardized link names: `pitch` `review` `revision` `acceptance` `rejection`. If there are multiple such threads, spell the ordinal out: `first pitch` `second review` etc. - ## Introduction -A short description of what the feature is. Try to keep it to a single-paragraph "elevator pitch" so the reader understands what problem this proposal is addressing. - -Add small but convenient, quality-assured methods on `DateInterval` to compute time and date intervals between date intervals to extend and complement existing comparison and intersection APIs. +Add small but convenient, quality-assured methods on `DateInterval` for computing time and date intervals between other date intervals. ## Motivation -Describe the problems that this proposal seeks to address. If the problem is that some common pattern is currently hard to express, show how one can currently get a similar effect and describe its drawbacks. If it's completely new functionality that cannot be emulated, motivate why this new functionality would help Swift developers create better Swift code. +`DateInterval` could offer more APIs to help developers work with ranges of absolute moments in time. For example, a developer might be building a logbook, employment time planner or implementing a time based feature in a less specialised app. In a more complex case, the 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. -`DateInterval` could offer more API helping developers working with ranges of absolute moments in time. For example, a developer might be building a logbook, employment time planner or implementing a time based feature in a less specialised app. In a more complex case, the 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 measuring the time between them or by some moment. `DateInterval` would be an intuitive type to begin such an implementation with but developers would quickly hit a limit with its available interface and become responsible for implementing their logic and maintain its quality. +`DateInterval` would be an intuitive type to begin such an implementation with. However, developers would quickly hit a limit with its out-of-the-box utility and become responsible for proving a quality implementation. Further, the precedent set by other Foundation types forms our intuitions about what utility we should expect of it. ## Proposed solution -Describe your solution to the problem. Provide examples and describe how they work. Show how your solution is better than current workarounds: is it cleaner, safer, or more efficient? - -This section doesn't have to be comprehensive. Focus on the most important parts of the proposal and make arguments about why the proposal is better than the status quo. - I would like to suggest 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. -Should a developer find themselves needing to compute values, these additions should feel intuitive because they bear a family resemblance to existing `Date` APIs. They extend the existing intersection APIs by signalling if two intervals intersect for a moment at opposing ends. They complement the comparison API by providing the past or future time between intervals. Effort has been put into expressively describing the computations — promoting readability — especially when developers may be tempted to settle for terse expressions. With the quality of these APIs assured, their convenience saving developers the cognitive load implementing, naming, testing and maintaining these computations, I would suggest these small but not-so-commonly needed additions would delight developers. +Should a developer find themselves needing to compute these values, the suggested additions should feel intuitive because they bear a family resemblance to existing `Date` APIs. 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 relative to another in the past or the future, the comparison offering is enriched. Effort has been put into expressively describing the computations — promoting 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 but not-so-commonly needed additions that match our intuitions about using Foundation; I would suggest these additions are delightful. ## Detailed design From 35bb7643f6423306d6b6e5030cca43fc6c664cbf Mon Sep 17 00:00:00 2001 From: Kiel Gillard Date: Wed, 29 Nov 2023 11:05:15 +1100 Subject: [PATCH 3/5] rewording, expand on detailed design --- Proposals/0002-date-interval-differences.md | 28 +++++++++++++++++---- 1 file changed, 23 insertions(+), 5 deletions(-) diff --git a/Proposals/0002-date-interval-differences.md b/Proposals/0002-date-interval-differences.md index 0324a1322..e3911e9e1 100644 --- a/Proposals/0002-date-interval-differences.md +++ b/Proposals/0002-date-interval-differences.md @@ -13,19 +13,37 @@ Add small but convenient, quality-assured methods on `DateInterval` for computin ## Motivation -`DateInterval` could offer more APIs to help developers work with ranges of absolute moments in time. For example, a developer might be building a logbook, employment time planner or implementing a time based feature in a less specialised app. In a more complex case, the 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. +`DateInterval` could offer more APIs to help developers work with ranges of absolute moments in time. For example, a developer might be building a logbook, 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, perhaps the duration between some moment and either the start or end of an interval should be displayed. -`DateInterval` would be an intuitive type to begin such an implementation with. However, developers would quickly hit a limit with its out-of-the-box utility and become responsible for proving a quality implementation. Further, the precedent set by other Foundation types forms our intuitions about what utility we should expect of it. +`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 an implementation. Further, the precedent set by other Foundation types have shaped our intuitions about what utility we could expect of it. ## Proposed solution -I would like to suggest 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. +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. -Should a developer find themselves needing to compute these values, the suggested additions should feel intuitive because they bear a family resemblance to existing `Date` APIs. 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 relative to another in the past or the future, the comparison offering is enriched. Effort has been put into expressively describing the computations — promoting 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 but not-so-commonly needed additions that match our intuitions about using Foundation; I would suggest these additions are delightful. +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 -Describe the design of the solution in detail. Show the full API and its documentation comments detailing what it does. The detail in this section should be sufficient for someone who is *not* one of the authors to be able to reasonably implement the feature. +Consider two date intervals `A` and `B` demarcating moments on this first timeline: +``` +1. |--A--| <-- time interval --> |--B--| +``` +For the `timeIntervalSince(_:)` APIs, the time interval of `B` since `A` will be zero or positive because `B` demarcates a range of moments later than the range of moments demarcated by `A`. The time interval of `A` since `B` will be zero or negative because the range of moments the range of moments demarcated by `A` are earlier than those demarcated by `B`. + +For the `dateIntervalSince(_:)` APIs, the date interval of `B` since `A` will be the same as the date interval of `A` since `B` because `DateInterval` is designed to represent positive intervals only. The time between the earliest end and latest start becomes the duration and the earliest end becomes the start of the resulting `DateInterval`. + +Consider two date intervals `C` and `D` demarcating moments on a second timeline: +``` +2. |--C--|--D--| +``` +The time or date intervals since `C` and `D` and vice-versa are zero because `C` ends where `D` begins. With this, developers can test that two date intervals form an unbroken, continuous range of moments. + +Finally, consider two thoroughly intersecting date intervals demarcating these moments on a third timeline: +``` +3. |--|—-—-|--| +``` +In this case, the time or date intervals since either interval does not exist and the APIs shall return `nil`. ## Source compatibility From ab1dee34ff9d7b3040233c4b4a45906091007546 Mon Sep 17 00:00:00 2001 From: Kiel Gillard Date: Wed, 29 Nov 2023 12:18:24 +1100 Subject: [PATCH 4/5] fleshing out more sections --- Proposals/0002-date-interval-differences.md | 40 ++++++--------------- 1 file changed, 11 insertions(+), 29 deletions(-) diff --git a/Proposals/0002-date-interval-differences.md b/Proposals/0002-date-interval-differences.md index e3911e9e1..e0783080e 100644 --- a/Proposals/0002-date-interval-differences.md +++ b/Proposals/0002-date-interval-differences.md @@ -13,9 +13,9 @@ Add small but convenient, quality-assured methods on `DateInterval` for computin ## Motivation -`DateInterval` could offer more APIs to help developers work with ranges of absolute moments in time. For example, a developer might be building a logbook, 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, perhaps the duration between some moment and either the start or end of an interval should be displayed. +`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 an implementation. Further, the precedent set by other Foundation types have shaped our intuitions about what utility we could expect of it. +`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. ## Proposed solution @@ -25,7 +25,7 @@ Should a developer find themselves needing to compute these values, the proposed ## Detailed design -Consider two date intervals `A` and `B` demarcating moments on this first timeline: +Consider two date intervals `A` and `B` demarcating ascending moments on this first timeline: ``` 1. |--A--| <-- time interval --> |--B--| ``` @@ -33,52 +33,34 @@ For the `timeIntervalSince(_:)` APIs, the time interval of `B` since `A` will be For the `dateIntervalSince(_:)` APIs, the date interval of `B` since `A` will be the same as the date interval of `A` since `B` because `DateInterval` is designed to represent positive intervals only. The time between the earliest end and latest start becomes the duration and the earliest end becomes the start of the resulting `DateInterval`. -Consider two date intervals `C` and `D` demarcating moments on a second timeline: +Next, consider two date intervals `C` and `D` demarcating moments on a second timeline: ``` 2. |--C--|--D--| ``` -The time or date intervals since `C` and `D` and vice-versa are zero because `C` ends where `D` begins. With this, developers can test that two date intervals form an unbroken, continuous range of moments. +The time or date intervals since `C` and `D` and vice-versa are zero because `C` ends when `D` begins. With this, developers can test that two date intervals form a seamless, continuous range of moments. Finally, consider two thoroughly intersecting date intervals demarcating these moments on a third timeline: ``` 3. |--|—-—-|--| ``` -In this case, the time or date intervals since either interval does not exist and the APIs shall return `nil`. +In this case, the time or date intervals since either date interval does not exist, so the APIs shall return `nil`. ## Source compatibility -Describe the impact of this proposal on source compatibility. As a general rule, all else being equal, Swift code that worked in previous releases of the tools should work in new releases. That means both that it should continue to build and that it should continue to behave dynamically the same as it did before. - -Consider the impact on existing clients. If clients provide a similar API, will type-checking find the right one? If the feature overloads an existing API, is it problematic that existing users of that API might start resolving to the new API? +The proposed changes are additive and no significant impact on existing code is expected. ## Implications on adoption -The compatibility sections above are focused on the direct impact of the proposal on existing code. In this section, describe issues that intentional adopters of the proposal should be aware of. - -Consider the impact on library adopters of those features. Can adopting this feature in a library break source or ABI compatibility for users of the library? If a library adopts the feature, can it be *un*-adopted later without breaking source compatibility? Will package authors be able to selectively adopt this feature depending on the tools version available, or will it require bumping the minimum tools version required by the package? - -If there are no concerns to raise in this section, leave it in with text like "This feature can be freely adopted and un-adopted in source code with no deployment constraints and without affecting source compatibility." +These additions can be freely adopted and un-adopted in source code with no deployment constraints and without affecting source compatibility. ## Future directions -Describe any interesting proposals that could build on this proposal in the future. This is especially important when these future directions inform the design of the proposal. - -The rest of the proposal should generally not talk about future directions except by referring to this section. It is important not to confuse reviewers about what is covered by this specific proposal. If there's a larger vision that needs to be explained in order to understand this proposal, consider starting a discussion thread on the forums to capture your broader thoughts. - -Avoid making affirmative statements in this section, such as "we will" or even "we should". Describe the proposals neutrally as possibilities to be considered in the future. - -Consider whether any of these future directions should really just be part of the current proposal. It's important to make focused, self-contained proposals that can be incrementally implemented and reviewed, but it's also good when proposals feel "complete" rather than leaving significant gaps in their design. +`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. ## Alternatives considered -Describe alternative approaches to addressing the same problem. This is an important part of most proposal documents. Reviewers are often familiar with other approaches prior to review and may have reasons to prefer them. This section is your first opportunity to try to convince them that your approach is the right one, and even if you don't fully succeed, you can help set the terms of the conversation and make the review a much more productive exchange of ideas. - -You should be fair about other proposals, but you do not have to be neutral; after all, you are specifically proposing something else. Describe any advantages these alternatives might have, but also be sure to explain the disadvantages that led you to prefer the approach in this proposal. +An alternative could be to “do nothing”. A motivation for this could be that the additions are “too small”. One problem with this is it would be too permissive, applicable to many existing APIs and discouraging new ones. For example, developers can subtract two time intervals easily enough, so `Date.timeIntervalSince(_:)` is (so the argument permits) regrettable. Another problem with this motivation is that it misses the other merits of readability, convenience etc. -You should update this section during the pitch phase to discuss any particularly interesting alternatives raised by the community. You do not need to list every idea raised during the pitch, just the ones you think raise points that are worth discussing. Of course, if you decide the alternative is more compelling than what's in the current proposal, you should change the main proposal; be sure to then discuss your previous proposal in this section and explain why the new idea is better. +Another motivation for “doing nothing” could be that it does not seem to solve some “third party date interval redundancy epidemic” within the broader community. One problem with this could be “survivorship bias”: do we really know the computations these additions provide are not solving a more common pain point for developers? Another problem would be that such a high bar for inclusion discourages the community from contributing their small conveniences that in sum make Foundation as a whole convenient, freeing developers to focus on building features rather than algorithms. ## Acknowledgments - -If significant changes or improvements suggested by members of the community were incorporated into the proposal as it developed, take a moment here to thank them for their contributions. Swift evolution is a collaborative process, and everyone's input should receive recognition! - -Generally, you should not acknowledge anyone who is listed as a co-author or as the review manager. From 814d2b1d89087cabd29d252891587c98ae2b2d65 Mon Sep 17 00:00:00 2001 From: Kiel Gillard Date: Wed, 29 Nov 2023 12:22:52 +1100 Subject: [PATCH 5/5] help Foundation become convenient --- Proposals/0002-date-interval-differences.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Proposals/0002-date-interval-differences.md b/Proposals/0002-date-interval-differences.md index e0783080e..920fadce0 100644 --- a/Proposals/0002-date-interval-differences.md +++ b/Proposals/0002-date-interval-differences.md @@ -61,6 +61,6 @@ These additions can be freely adopted and un-adopted in source code with no depl An alternative could be to “do nothing”. A motivation for this could be that the additions are “too small”. One problem with this is it would be too permissive, applicable to many existing APIs and discouraging new ones. For example, developers can subtract two time intervals easily enough, so `Date.timeIntervalSince(_:)` is (so the argument permits) regrettable. Another problem with this motivation is that it misses the other merits of readability, convenience etc. -Another motivation for “doing nothing” could be that it does not seem to solve some “third party date interval redundancy epidemic” within the broader community. One problem with this could be “survivorship bias”: do we really know the computations these additions provide are not solving a more common pain point for developers? Another problem would be that such a high bar for inclusion discourages the community from contributing their small conveniences that in sum make Foundation as a whole convenient, freeing developers to focus on building features rather than algorithms. +Another motivation for “doing nothing” could be that it does not seem to solve some “third party date interval redundancy epidemic” within the broader community. One problem with this could be “survivorship bias”: do we really know the computations these additions provide are not solving a more common pain point for developers? Another problem would be that such a high bar for inclusion discourages the community from contributing their small conveniences that in sum help make Foundation as a whole convenient, freeing developers to focus on building features rather than algorithms. ## Acknowledgments