Double-double Date (#1533)

Adapts Date to use a double-Double representation (the underlying representation is the sum of two double-precision values, giving about 106 bits of precision).

Previously Date was backed by a single Double measuring time since Jan 1 2001 in seconds. Because Double's precision is non-uniform, this means that times within a hundred days of the epoch are represented with approximately nanosecond precision, but as you get farther away from that date the precision decreases. For times close to today, it has been reduced to about 100ns.

The obvious thing would be to adopt an integer-based representation similar to C's timespec (32b nanoseconds, 64b seconds) or Swift's Duration (128b attoseconds). These representations suffer from a few difficulties:

- Existing API on Date takes and produces TimeInterval (aka Double). Making Date use an integer representation internally would mean that existing users of the public API would suddently start getting different results for computations that were previously exact; even though we could add new API, and the overall system would be more precise, this would be a surprisingly subtle change for users to navigate.

- We have been told that some software interprets the raw bytes of Date as a Double for the purposes of fast serialization. These packages formally violate Foundation's API boundaries, but that doesn't help users of those packages who would abruptly be broken by switching to an integer representation.

Using DoubleDouble instead navigates these problems fairly elegantly.

- Because DoubleDouble is still a floating-point type, it still suffers from non-uniform precision. However, because DoubleDouble is so fantastically precise, it can represent dates out to ±2.5 quadrillion years at ~nanosecond or better precision, so in practice this won't be much of an issue.

- Existing API on Date will produce exactly the same result as it did previously in cases where those results were exact, minimizing surprises. In cases where the existing API was not exact, it will produce much more accurate results, even if users do not adopt new API, because its internal calculations are now more precise.

- Software that (incorrectly) interprets the raw bytes of Date as a Double will get at least as accurate of a value as it did previously (and often a more accurate value).

DateInterval gets the same treatment, so that it can benefit from more accurate internal computations as well. Follow-on work may adapt/add-to Date's API to make it easier to specify Dates with high precision.

Author: stephentyrone

Sources/FoundationEssentials/CMakeLists.txt

@@ -21,6 +21,7 @@ add_library(FoundationEssentials
     ComparisonResult.swift
     Date.swift
     DateInterval.swift
+    DoubleDouble.swift
     FoundationEssentials.swift
     IndexPath.swift
     LockedState.swift

Sources/FoundationEssentials/Calendar/Calendar_Gregorian.swift

@@ -1448,30 +1448,39 @@ internal final class _CalendarGregorian: _CalendarProtocol, @unchecked Sendable
     }
 
     func dateInterval(of component: Calendar.Component, for date: Date) -> DateInterval? {
-        let time = date.timeIntervalSinceReferenceDate
+        let approximateTime = date._time.head
         var effectiveUnit = component
         switch effectiveUnit {
         case .calendar, .timeZone, .isLeapMonth, .isRepeatedDay:
             return nil
         case .era:
-            if time < -63113904000.0 {
+            if approximateTime < -63113904000.0 {
                 return DateInterval(start: Date(timeIntervalSinceReferenceDate: -63113904000.0 - inf_ti), duration: inf_ti)
             } else {
                 return DateInterval(start: Date(timeIntervalSinceReferenceDate: -63113904000.0), duration: inf_ti)
             }
 
         case .hour:
-            let ti = Double(timeZone.secondsFromGMT(for: date))
-            var fixedTime = time + ti // compute local time
-            fixedTime = floor(fixedTime / 3600.0) * 3600.0
-            fixedTime = fixedTime - ti // compute GMT
-            return DateInterval(start: Date(timeIntervalSinceReferenceDate: fixedTime), duration: 3600.0)
+            // Local hours may not be aligned to GMT hours, so we have to apply
+            // the time zone adjustment before rounding down, then unapply it.
+            let offset = Double(timeZone.secondsFromGMT(for: date))
+            let start = ((date._time + offset)/3600).floor() * 3600 - offset
+            return DateInterval(
+                start: Date(start),
+                duration: 3600
+            )
         case .minute:
-            return DateInterval(start: Date(timeIntervalSinceReferenceDate: floor(time / 60.0) * 60.0), duration: 60.0)
+            return DateInterval(
+                start: Date((date._time/60).floor() * 60),
+                duration: 60
+            )
         case .second:
-            return DateInterval(start: Date(timeIntervalSinceReferenceDate: floor(time)), duration: 1.0)
+            return DateInterval(start: Date(date._time.floor()), duration: 1)
         case .nanosecond:
-            return DateInterval(start: Date(timeIntervalSinceReferenceDate: floor(time * 1.0e+9) * 1.0e-9), duration: 1.0e-9)
+            return DateInterval(
+                start: Date((date._time*1e9).floor() / 1e9),
+                duration: 1e-9
+            )
         case .year, .yearForWeekOfYear, .quarter, .month, .day, .dayOfYear, .weekOfMonth, .weekOfYear:
             // Continue to below
             break

Sources/FoundationEssentials/Calendar/Calendar_Recurrence.swift

@@ -93,8 +93,8 @@ extension Calendar {
             /// value is used as a lower bound for ``nextBaseRecurrenceDate()``.
             let rangeLowerBound: Date?
 
-            /// The start date's nanoseconds component
-            let startDateNanoseconds: TimeInterval
+            /// The start date's fractional seconds component
+            let fractionalSeconds: TimeInterval
 
             /// How many occurrences have been found so far
             var resultsFound = 0
@@ -131,7 +131,10 @@ extension Calendar {
                 }
                 self.recurrence = recurrence
 
-                self.start = start
+                // round start down to whole seconds, set aside fraction.
+                let wholeSeconds = start._time.floor()
+                fractionalSeconds = (start._time - wholeSeconds).head
+                self.start = Date(wholeSeconds)
                 self.range = range
 
                 let frequency = recurrence.frequency
@@ -233,9 +236,7 @@ extension Calendar {
                     case .monthly:  [.second, .minute, .hour, .day]
                     case .yearly:   [.second, .minute, .hour, .day, .month, .isLeapMonth]
                 }
-                var componentsForEnumerating = recurrence.calendar._dateComponents(components, from: start) 
-                
-                startDateNanoseconds = start.timeIntervalSinceReferenceDate.truncatingRemainder(dividingBy: 1)
+                var componentsForEnumerating = recurrence.calendar._dateComponents(components, from: start)
 
                 let expansionChangesDay = dayOfYearAction == .expand || dayOfMonthAction == .expand || weekAction == .expand || weekdayAction == .expand
                 let expansionChangesMonth = dayOfYearAction == .expand || monthAction == .expand || weekAction == .expand
@@ -427,11 +428,11 @@ extension Calendar {
                     recurrence._limitTimeComponent(.second, dates: &dates, anchor: anchor)
                 }
 
-                if startDateNanoseconds > 0 {
+                if fractionalSeconds != 0 {
                     // `_dates(startingAfter:)` above returns whole-second dates,
                     // so we need to restore the nanoseconds value present in the original start date.
                     for idx in dates.indices {
-                        dates[idx] += startDateNanoseconds
+                        dates[idx] += fractionalSeconds
                     }
                 }
                 dates = dates.filter { $0 >= self.start }

Sources/FoundationEssentials/Date.swift

@@ -34,12 +34,64 @@ public typealias TimeInterval = Double
  A `Date` is independent of a particular calendar or time zone. To represent a `Date` to a user, you must interpret it in the context of a `Calendar`.
 */
 @available(macOS 10.10, iOS 8.0, watchOS 2.0, tvOS 9.0, *)
-public struct Date : Comparable, Hashable, Equatable, Sendable {
-
-    internal var _time : TimeInterval
+public struct Date: Comparable, Hashable, Equatable, Sendable {
+    /* Date is internally represented as a sum of two Doubles.
+    
+     Previously Date was backed by a single Double measuring time since
+     Jan 1 2001 in seconds. Because Double's precision is non-uniform, this
+     means that times within a hundred days of the epoch are represented
+     with approximately nanosecond precision, but as you get farther away
+     from that date the precision decreases. For times close to the time
+     at which this comment was written, accuracy has been reduced to about
+     100ns.
+     
+     The obvious thing would be to adopt an integer-based representation
+     similar to C's timespec (32b nanoseconds, 64b seconds) or Swift's
+     Duration (128b attoseconds). These representations suffer from a few
+     difficulties:
+     
+     - Existing API on Date takes and produces `TimeInterval` (aka Double).
+       Making Date use an integer representation internally would mean that
+       existing users of the public API would suddently start getting
+       different results for computations that were previously exact; even
+       though we could add new API, and the overall system would be more
+       precise, this would be a surprisingly subtle change for users to
+       navigate.
+     
+     - We have been told that some software interprets the raw bytes of Date
+       as a Double for the purposes of fast serialization. These packages
+       formally violate Foundation's API boundaries, but that doesn't help
+       users of those packages who would abruptly be broken by switching to
+       an integer representation.
+     
+     Using DoubleDouble instead navigates these problems fairly elegantly.
+     
+     - Because DoubleDouble is still a floating-point type, it still suffers
+       from non-uniform precision. However, because DoubleDouble is so
+       fantastically precise, it can represent dates out to ±2.5 quadrillion
+       years at ~nanosecond or better precision, so in practice this won't
+       be much of an issue.
+     
+     - Existing API on Date will produce exactly the same result as it did
+       previously in cases where those results were exact, minimizing
+       surprises. In cases where the existing API was not exact, it will
+       produce much more accurate results, even if users do not adopt new
+       API, because its internal calculations are now more precise.
+     
+     - Software that (incorrectly) interprets the raw bytes of Date as a
+       Double will get at least as accurate of a value as it did previously
+       (and often a more accurate value).                                     */
+    internal var _time: DoubleDouble
+    
+    internal init(_ time: DoubleDouble) {
+        self._time = time
+    }
+}
 
+@available(macOS 10.10, iOS 8.0, watchOS 2.0, tvOS 9.0, *)
+extension Date {
     /// The number of seconds from 1 January 1970 to the reference date, 1 January 2001.
-    public static let timeIntervalBetween1970AndReferenceDate : TimeInterval = 978307200.0
+    public static let timeIntervalBetween1970AndReferenceDate: TimeInterval = 978307200.0
 
     /// The number of seconds from 1 January 1601 to the reference date, 1 January 2001.
     internal static let timeIntervalBetween1601AndReferenceDate: TimeInterval = 12622780800.0
@@ -51,17 +103,23 @@ public struct Date : Comparable, Hashable, Equatable, Sendable {
 
     /// Returns a `Date` initialized to the current date and time.
     public init() {
-        _time = Self.getCurrentAbsoluteTime()
+        _time = .init(uncheckedHead: Self.getCurrentAbsoluteTime(), tail: 0)
     }
 
     /// Returns a `Date` initialized relative to the current date and time by a given number of seconds.
     public init(timeIntervalSinceNow: TimeInterval) {
-        self.init(timeIntervalSinceReferenceDate: timeIntervalSinceNow + Self.getCurrentAbsoluteTime())
+        self.init(.sum(
+            Self.getCurrentAbsoluteTime(),
+            timeIntervalSinceNow
+        ))
     }
 
     /// Returns a `Date` initialized relative to 00:00:00 UTC on 1 January 1970 by a given number of seconds.
     public init(timeIntervalSince1970: TimeInterval) {
-        self.init(timeIntervalSinceReferenceDate: timeIntervalSince1970 - Date.timeIntervalBetween1970AndReferenceDate)
+        self.init(.sum(
+            timeIntervalSince1970,
+            -Date.timeIntervalBetween1970AndReferenceDate
+        ))
     }
 
     /**
@@ -71,12 +129,12 @@ public struct Date : Comparable, Hashable, Equatable, Sendable {
     - Parameter date: The reference date.
     */
     public init(timeInterval: TimeInterval, since date: Date) {
-        self.init(timeIntervalSinceReferenceDate: date.timeIntervalSinceReferenceDate + timeInterval)
+        self.init(date._time + timeInterval)
     }
 
     /// Returns a `Date` initialized relative to 00:00:00 UTC on 1 January 2001 by a given number of seconds.
     public init(timeIntervalSinceReferenceDate ti: TimeInterval) {
-        _time = ti
+        _time = .init(uncheckedHead: ti, tail: 0)
     }
 
     /**
@@ -85,7 +143,7 @@ public struct Date : Comparable, Hashable, Equatable, Sendable {
     This property's value is negative if the date object is earlier than the system's absolute reference date (00:00:00 UTC on 1 January 2001).
     */
     public var timeIntervalSinceReferenceDate: TimeInterval {
-        return _time
+        return _time.head
     }
 
     /**
@@ -100,7 +158,7 @@ public struct Date : Comparable, Hashable, Equatable, Sendable {
     - SeeAlso: `timeIntervalSinceReferenceDate`
     */
     public func timeIntervalSince(_ date: Date) -> TimeInterval {
-        return self.timeIntervalSinceReferenceDate - date.timeIntervalSinceReferenceDate
+        return (self._time - date._time).head
     }
 
     /**
@@ -173,9 +231,9 @@ public struct Date : Comparable, Hashable, Equatable, Sendable {
 
     /// Compare two `Date` values.
     public func compare(_ other: Date) -> ComparisonResult {
-        if _time < other.timeIntervalSinceReferenceDate {
+        if _time < other._time {
             return .orderedAscending
-        } else if _time > other.timeIntervalSinceReferenceDate {
+        } else if _time > other._time {
             return .orderedDescending
         } else {
             return .orderedSame
@@ -184,27 +242,27 @@ public struct Date : Comparable, Hashable, Equatable, Sendable {
 
     /// Returns true if the two `Date` values represent the same point in time.
     public static func ==(lhs: Date, rhs: Date) -> Bool {
-        return lhs.timeIntervalSinceReferenceDate == rhs.timeIntervalSinceReferenceDate
+        return lhs._time == rhs._time
     }
 
     /// Returns true if the left hand `Date` is earlier in time than the right hand `Date`.
     public static func <(lhs: Date, rhs: Date) -> Bool {
-        return lhs.timeIntervalSinceReferenceDate < rhs.timeIntervalSinceReferenceDate
+        return lhs._time < rhs._time
     }
 
     /// Returns true if the left hand `Date` is later in time than the right hand `Date`.
     public static func >(lhs: Date, rhs: Date) -> Bool {
-        return lhs.timeIntervalSinceReferenceDate > rhs.timeIntervalSinceReferenceDate
+        return lhs._time > rhs._time
     }
 
     /// Returns a `Date` with a specified amount of time added to it.
     public static func +(lhs: Date, rhs: TimeInterval) -> Date {
-        return Date(timeIntervalSinceReferenceDate: lhs.timeIntervalSinceReferenceDate + rhs)
+        return Date(lhs._time + rhs)
     }
 
     /// Returns a `Date` with a specified amount of time subtracted from it.
     public static func -(lhs: Date, rhs: TimeInterval) -> Date {
-        return Date(timeIntervalSinceReferenceDate: lhs.timeIntervalSinceReferenceDate - rhs)
+        return Date(lhs._time - rhs)
     }
 
     /// Add a `TimeInterval` to a `Date`.
@@ -220,7 +278,6 @@ public struct Date : Comparable, Hashable, Equatable, Sendable {
     public static func -=(lhs: inout Date, rhs: TimeInterval) {
         lhs = lhs - rhs
     }
-
 }
 
 @available(macOS 10.10, iOS 8.0, watchOS 2.0, tvOS 9.0, *)

Sources/FoundationEssentials/DateInterval.swift

@@ -12,38 +12,45 @@
 
 /// DateInterval represents a closed date interval in the form of [startDate, endDate].  It is possible for the start and end dates to be the same with a duration of 0.  DateInterval does not support reverse intervals i.e. intervals where the duration is less than 0 and the end date occurs earlier in time than the start date.
 @available(macOS 10.12, iOS 10.0, watchOS 3.0, tvOS 10.0, *)
-public struct DateInterval : Comparable, Hashable, Codable, Sendable {
+public struct DateInterval: Comparable, Hashable, Codable, Sendable {
 
     /// The start date.
-    public var start : Date
+    public var start: Date
+    
+    /// Underlying storage for `duration`
+    internal var _duration: DoubleDouble
 
     /// The end date.
     ///
     /// - precondition: `end >= start`
-    public var end : Date {
+    public var end: Date {
         get {
-            return start + duration
+            return Date(start._time + _duration)
         }
         set {
             precondition(newValue >= start, "Reverse intervals are not allowed")
-            duration = newValue.timeIntervalSinceReferenceDate - start.timeIntervalSinceReferenceDate
+            _duration = (newValue._time - start._time)
         }
     }
-
-    /// The duration.
+    
+    /// The duration
     ///
     /// - precondition: `duration >= 0`
-    public var duration : TimeInterval {
-        willSet {
+    public var duration: TimeInterval {
+        get {
+            _duration.head
+        }
+        set {
             precondition(newValue >= 0, "Negative durations are not allowed")
+            _duration = DoubleDouble(uncheckedHead: newValue, tail: 0)
         }
     }
 
     /// Initializes a `DateInterval` with start and end dates set to the current date and the duration set to `0`.
     public init() {
         let d = Date()
         start = d
-        duration = 0
+        _duration = .zero
     }
 
     /// Initialize a `DateInterval` with the specified start and end date.
@@ -52,7 +59,7 @@ public struct DateInterval : Comparable, Hashable, Codable, Sendable {
     public init(start: Date, end: Date) {
         precondition(end >= start, "Reverse intervals are not allowed")
         self.start = start
-        duration = end.timeIntervalSince(start)
+        _duration = end._time - start._time
     }
 
     /// Initialize a `DateInterval` with the specified start date and duration.
@@ -61,7 +68,7 @@ public struct DateInterval : Comparable, Hashable, Codable, Sendable {
     public init(start: Date, duration: TimeInterval) {
         precondition(duration >= 0, "Negative durations are not allowed")
         self.start = start
-        self.duration = duration
+        _duration = DoubleDouble(uncheckedHead: duration, tail: 0)
     }
 
     /**
@@ -162,6 +169,24 @@ public struct DateInterval : Comparable, Hashable, Codable, Sendable {
     public static func <(lhs: DateInterval, rhs: DateInterval) -> Bool {
         return lhs.compare(rhs) == .orderedAscending
     }
+    
+    enum CodingKeys: String, CodingKey {
+        case start = "start"
+        case duration = "duration"
+    }
+    
+    public init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        let start = try container.decode(Date.self, forKey: .start)
+        let duration = try container.decode(TimeInterval.self, forKey: .duration)
+        self.init(start: start, duration: duration)
+    }
+    
+    public func encode(to encoder: Encoder) throws {
+        var container = encoder.container(keyedBy: CodingKeys.self)
+        try container.encode(start, forKey: .start)
+        try container.encode(duration, forKey: .duration)
+    }
 }
 
 @available(macOS 10.12, iOS 10.0, watchOS 3.0, tvOS 10.0, *)