Add comment explaining rationale for DoubleDouble storage on Date

Also add some other documentation comments on the internal DoubleDouble type and rename init(head:tail:) to init(uncheckedHead:tail:) to better document that its precondition is not enforced in Release builds

Author: stephentyrone

Sources/FoundationEssentials/Date.swift

@@ -34,16 +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 {
-
+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
+        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
@@ -55,7 +103,7 @@ public struct Date : Comparable, Hashable, Equatable, Sendable {
 
     /// Returns a `Date` initialized to the current date and time.
     public init() {
-        _time = .init(head: Self.getCurrentAbsoluteTime(), tail: 0)
+        _time = .init(uncheckedHead: Self.getCurrentAbsoluteTime(), tail: 0)
     }
 
     /// Returns a `Date` initialized relative to the current date and time by a given number of seconds.
@@ -86,7 +134,7 @@ public struct Date : Comparable, Hashable, Equatable, Sendable {
 
     /// 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 = .init(head: ti, tail: 0)
+        _time = .init(uncheckedHead: ti, tail: 0)
     }
 
     /**

Sources/FoundationEssentials/DateInterval.swift

@@ -42,7 +42,7 @@ public struct DateInterval: Comparable, Hashable, Codable, Sendable {
         }
         set {
             precondition(newValue >= 0, "Negative durations are not allowed")
-            _duration = DoubleDouble(head: newValue, tail: 0)
+            _duration = DoubleDouble(uncheckedHead: newValue, tail: 0)
         }
     }
 
@@ -68,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
-        _duration = DoubleDouble(head: duration, tail: 0)
+        _duration = DoubleDouble(uncheckedHead: duration, tail: 0)
     }
 
     /**

Sources/FoundationEssentials/DoubleDouble.swift

@@ -10,42 +10,85 @@
 //
 //===----------------------------------------------------------------------===//
 
+/// A numeric type that uses two Double values as its representation, providing
+/// about 106 bits of precision with the same exponent range as Double.
+///
+/// This type conforms to AdditiveArithmetic, Hashable and Comparable, but does
+/// not conform to FloatingPoint or Numeric; it implements only the API surface
+/// that is necessary to serve as an internal implementation detail of Date.
 internal struct DoubleDouble {
 
     private let storage: (Double, Double)
 
+    /// A double-double value constructed by specifying the head and tail.
+    ///
+    /// This is an unchecked operation because it does not enforce the
+    /// invariant that head + tail == head in release builds, which is
+    /// necessary for subsequent arithmetic operations to behave correctly.
     @_transparent
-    init(head: Double, tail: Double) {
+    init(uncheckedHead head: Double, tail: Double) {
+        assert(!head.isFinite || head + tail == head)
         storage = (head, tail)
     }
 
+    /// The high-order Double.
+    ///
+    /// This property does not have a setter because `head` should pretty much
+    /// never be set independently of `tail`, so as to maintain the invariant
+    /// that `head + tail == head`. You can use `init(uncheckedHead:tail:)`
+    /// to directly construct DoubleDouble values, which will enforce the
+    /// invariant in debug builds.
     @_transparent
     var head: Double { storage.0 }
 
+    /// The low-order Double.
+    ///
+    /// This property does not have a setter because `tail` should pretty much
+    /// never be set independently of `head`, so as to maintain the invariant
+    /// that `head + tail == head`. You can use `init(uncheckedHead:tail:)`
+    /// to directly construct DoubleDouble values, which will enforce the
+    /// invariant in debug builds.
     @_transparent
     var tail: Double { storage.1 }
 
+    /// `a + b` represented as a normalized DoubleDouble.
+    ///
+    /// Computed via the [2Sum algorithm](https://en.wikipedia.org/wiki/2Sum).
     @inlinable
     static func sum(_ a: Double, _ b: Double) -> DoubleDouble {
         let head = a + b
         let x = head - b
         let y = head - x
         let tail = (a - x) + (b - y)
-        return DoubleDouble(head: head, tail: tail)
+        return DoubleDouble(uncheckedHead: head, tail: tail)
     }
 
+    /// `a + b` represented as a normalized DoubleDouble.
+    ///
+    /// Computed via the [Fast2Sum algorithm](https://en.wikipedia.org/wiki/2Sum).
+    ///
+    /// - Precondition:
+    /// `large` and `small` must be such that `sum(large:small:)`
+    /// produces the same result as `sum(_:_:)` would. A sufficient condition
+    /// is that `|large| >= |small|`, but this is not necessary, so we do not
+    /// enforce it via an assert. Instead this function asserts that the result
+    /// is the same as that produced by `sum(_:_:)` in Debug builds. This is
+    /// unchecked in Release.
     @inlinable
     static func sum(large a: Double, small b: Double) -> DoubleDouble {
         let head = a + b
         let tail = a - head + b
-        return DoubleDouble(head: head, tail: tail)
+        let result = DoubleDouble(uncheckedHead: head, tail: tail)
+        assert(!head.isFinite || result == sum(a, b))
+        return result
     }
 
+    /// `a * b` represented as a normalized DoubleDouble.
     @inlinable
     static func product(_ a: Double, _ b: Double) -> DoubleDouble {
         let head = a * b
         let tail = (-head).addingProduct(a, b)
-        return DoubleDouble(head: head, tail: tail)
+        return DoubleDouble(uncheckedHead: head, tail: tail)
     }
 }
 
@@ -72,7 +115,7 @@ extension DoubleDouble: Hashable {
 extension DoubleDouble: AdditiveArithmetic {
     @inlinable
     static var zero: DoubleDouble {
-        Self(head: 0, tail: 0)
+        Self(uncheckedHead: 0, tail: 0)
     }
 
     @inlinable
@@ -83,6 +126,8 @@ extension DoubleDouble: AdditiveArithmetic {
         return sum(large: first.head, small: first.tail + tails.tail)
     }
 
+    /// Equivalent to `a + DoubleDouble(uncheckedHead: b, tail: 0)` but
+    /// computed more efficiently.
     @inlinable
     static func +(a: DoubleDouble, b: Double) -> DoubleDouble {
         let heads = sum(a.head, b)
@@ -92,14 +137,16 @@ extension DoubleDouble: AdditiveArithmetic {
 
     @inlinable
     prefix static func -(a: DoubleDouble) -> DoubleDouble {
-        DoubleDouble(head: -a.head, tail: -a.tail)
+        DoubleDouble(uncheckedHead: -a.head, tail: -a.tail)
     }
 
     @inlinable
     static func -(a: DoubleDouble, b: DoubleDouble) -> DoubleDouble {
         a + (-b)
     }
 
+    /// Equivalent to `a - DoubleDouble(uncheckedHead: b, tail: 0)` but
+    /// computed more efficiently.
     @inlinable
     static func -(a: DoubleDouble, b: Double) -> DoubleDouble {
         a + (-b)
@@ -111,7 +158,7 @@ extension DoubleDouble {
     static func *(a: DoubleDouble, b: Double) -> DoubleDouble {
         let tmp = product(a.head, b)
         return DoubleDouble(
-            head: tmp.head,
+            uncheckedHead: tmp.head,
             tail: tmp.tail.addingProduct(a.tail, b)
         )
     }
@@ -120,17 +167,20 @@ extension DoubleDouble {
     static func /(a: DoubleDouble, b: Double) -> DoubleDouble {
         let head = a.head/b
         let residual = a.head.addingProduct(-head, b) + a.tail
-        return DoubleDouble(head: head, tail: residual/b)
+        return .sum(large: head, small: residual/b)
     }
 }
 
 extension DoubleDouble {
+    // This value rounded down to an integer.
     @inlinable
     func floor() -> DoubleDouble {
         let approx = head.rounded(.down)
+        // If head was already an integer, round tail down and renormalize.
         if approx == head {
             return .sum(large: head, small: tail.rounded(.down))
         }
-        return DoubleDouble(head: approx, tail: 0)
+        // Head was not an integer; we can simply discard tail.
+        return DoubleDouble(uncheckedHead: approx, tail: 0)
     }
 }