Convenience methods for computing intervals between `DateInterval`s.

[kielgillard]

Note for wanderers

The understanding of this issue evolved since its creation. I've started working on a proposal at #331. The current implementation can now be found at #330.

---

Original comment

I was reviewing some code today that checked two date intervals, say A and B, were arranged like this on a timeline:

----|---A---|---B---|----

These intervals intersect, but it would be nice to easily check how they intersect; if they "touch" at their boundaries; if the intervals are "beside" each other. This resulted in the following implementation:

func isBeside(_ other: DateInterval) -> Bool {
   self.start == other.end || self.end == other.start
}

Naming aside*, how viable would this such a contribution be as an incredibly tiny but nice convenience method on DateInterval?

It seems it would have to go through evolution which, as the tiniest of conveniences, would be practically embarrassing. While I think it would be delightful to have this quality assured convenience available when you realise you need it, I do not have any data that demands its presence in Foundation, either. I did no more than a search of GitHub for Swift or Objective-C code for date intervals, dates and times. There's seems to be no obvious or compelling third party redundancy to solve. Is this a dead end? What can I do next?

* pun not intended.

EDIT: Having thought a bit more about the name, I would say "beside" and "sidedness" is a bad choice / metaphor because it ignores that these kinds of intervals do in fact intersect, it just they intersect at the very first and last moments. An alternative could be isContinuous.

[kielgillard]

I was compelled by the edit of my comment above and updated the referenced PR to replace the notion of "sidedness" with a notion of "continuity".

[kielgillard]

I thought more about a motivation for it and I am considering something more useful.

A user might have a logbook, employment or time planner app that requires them to enter the start and end time of particular activities in a particular sequence with some acceptable gap between (e.g. work 30 minutes here, do 30 minutes there and take a 10 minute break, at most five minutes between segments). The app has to check both the intersections of intervals and the measure of time between them.

The current intersection API can only get you so far with this (it can compute intervals of intersections) but it would be good to know the time interval between two date intervals to know if the intersection is at the boundary (they share opposing start/end times) or if there was no intersection at all.

After putting this into words, I see a more useful API here: a difference API for computing a TimeInterval (or DateInterval!) between two DateInterval values:

a.   |-----|
           |<--compute this interval-->|
b.                                     |-----|

let timeBetweenBA = b.timeIntervalSince(a) // positive time interval
let timeBetweenAB = a.timeIntervalSince(b) // negative time interval

let datesBetweenBA = b.dateIntervalSince(a) // (a.end, b.start)
let datesBetweenAB = a.dateIntervalSince(b) // the same: (a.end, b.start)

And in this case:

c.   |--------|
d.         |-----|

let timeBetweenCD = c.timeIntervalSince(d) // nil (there is no "between")
let datesBetweenAB = d.dateIntervalSince(d) // nil (there is no "between")

[kielgillard]

Again, please let me know if I'm wasting my time doing this.

[kielgillard]

I have pushed new changes to the PR, adding timeInterval(to:) and dateInterval(to:) methods on DateInterval that allow developers to compute differences between date intervals (if any difference exists). Unit tests included.

These methods give developers out-of-the-box, quality assured convenience methods to implement features that might need to check how date intervals might intersect or what the difference between them might be (if any difference exists).

I have updated the names of this issue and the PR to better communicate the proposed changes and functionality.

I keenly await further feedback before I invest more time in this.

[kielgillard]

I've started working on a proposal at #331. The current implementation can now be found at #330.