Update Time implementation (#288)

Author: Kyle-Ye

Sources/OpenSwiftUICore/Data/Time.swift

@@ -7,92 +7,178 @@
 
 #if canImport(QuartzCore)
 public import QuartzCore
+#else
+public import Foundation
 #endif
 
+/// A type that represents a time value in seconds.
+///
+/// Use `Time` to represent durations or time intervals within the OpenSwiftUI framework.
+/// The structure provides various operators and methods for time-related calculations.
+///
+/// Example:
+/// 
+///     let duration = Time(seconds: 2.5)
+///     let delay = Time.systemUptime + 1.0
+/// 
 @_spi(ForOpenSwiftUIOnly)
 public struct Time: Equatable, Hashable, Comparable {
+    /// The time value in seconds.
     public var seconds: Double
+
+    /// Creates a time value from the specified number of seconds.
+    /// - Parameter seconds: The number of seconds.
     public init(seconds: Double) {
         self.seconds = seconds
     }
+
+    /// Creates a time value initialized to zero seconds.
     public init() {
         self.seconds = .zero
     }
+
+    /// A time value of zero seconds.
     public static let zero: Time = Time(seconds: .zero)
-    public static let infinity: Time = Time(seconds: .infinity)
 
-    #if canImport(QuartzCore)
+    /// A time value representing infinity.
+    public static let infinity: Time = Time(seconds: .infinity)
+    
+    /// The current system uptime as a `Time` value.
+    ///
+    /// This property provides the time since system boot using platform-specific
+    /// implementation.
     @inlinable
     public static var systemUptime: Time {
+        // NOTE: ProcessInfo.systemUptime is a general API available on all platforms via Foundation.
+        // The implementation result of ProcessInfo().systemUptime and CACurrentMediaTime() is the same on Darwin platforms.
+        // Both of them is using `mach_absolute_time` under the hood for Darwin platforms.
+        // On non-Darwin platforms, `CACurrentMediaTime` is not available. But `ProcessInfo.systemUptime` is available.
+        #if canImport(QuartzCore)
         Time(seconds: CACurrentMediaTime())
+        #else
+        Time(seconds: ProcessInfo.processInfo.systemUptime)
+        #endif
     }
-    #endif
 
+    /// Returns the negation of the specified time value.
+    /// - Parameter lhs: A time value.
+    /// - Returns: A time value that is the negation of the input.
     @inlinable
-    prefix public static func - (lhs: Time) -> Time {
+    public static prefix func - (lhs: Time) -> Time {
         Time(seconds: -lhs.seconds)
     }
-
+    
+    /// Adds a time value and a number of seconds.
+    /// - Parameters:
+    ///   - lhs: A time value.
+    ///   - rhs: The number of seconds to add.
+    /// - Returns: A new time value representing the sum.
     @inlinable
     public static func + (lhs: Time, rhs: Double) -> Time {
         Time(seconds: lhs.seconds + rhs)
     }
 
+    /// Adds a number of seconds to a time value.
+    /// - Parameters:
+    ///   - lhs: The number of seconds to add.
+    ///   - rhs: A time value.
+    /// - Returns: A new time value representing the sum.
     @inlinable
     public static func + (lhs: Double, rhs: Time) -> Time {
         rhs + lhs
     }
 
+    /// Subtracts a number of seconds from a time value.
+    /// - Parameters:
+    ///   - lhs: A time value.
+    ///   - rhs: The number of seconds to subtract.
+    /// - Returns: A new time value representing the difference.
     @inlinable
     public static func - (lhs: Time, rhs: Double) -> Time {
         Time(seconds: lhs.seconds - rhs)
     }
 
+    /// Calculates the time difference between two time values.
+    /// - Parameters:
+    ///   - lhs: The first time value.
+    ///   - rhs: The second time value.
+    /// - Returns: The difference in seconds between the two time values.
     @inlinable
     public static func - (lhs: Time, rhs: Time) -> Double {
         lhs.seconds - rhs.seconds
     }
-    
+
+    /// Multiplies a time value by a scalar.
+    /// - Parameters:
+    ///   - lhs: A time value.
+    ///   - rhs: The scalar to multiply by.
+    /// - Returns: A new time value representing the product.
     @inlinable
     public static func * (lhs: Time, rhs: Double) -> Time {
         Time(seconds: lhs.seconds * rhs)
     }
-    
+
+    /// Divides a time value by a scalar.
+    /// - Parameters:
+    ///   - lhs: A time value.
+    ///   - rhs: The scalar to divide by.
+    /// - Returns: A new time value representing the quotient.
     @inlinable
     public static func / (lhs: Time, rhs: Double) -> Time {
         return Time(seconds: lhs.seconds / rhs)
     }
-    
+
+    /// Adds a number of seconds to a time value, storing the result in the left-hand operand.
+    /// - Parameters:
+    ///   - lhs: The time value to modify.
+    ///   - rhs: The number of seconds to add.
     @inlinable
     public static func += (lhs: inout Time, rhs: Double) {
         lhs = lhs + rhs
     }
 
+    /// Subtracts a number of seconds from a time value, storing the result in the left-hand operand.
+    /// - Parameters:
+    ///   - lhs: The time value to modify.
+    ///   - rhs: The number of seconds to subtract.
     @inlinable
     public static func -= (lhs: inout Time, rhs: Double) {
         lhs = lhs - rhs
     }
 
+    /// Multiplies a time value by a scalar, storing the result in the left-hand operand.
+    /// - Parameters:
+    ///   - lhs: The time value to modify.
+    ///   - rhs: The scalar to multiply by.
     @inlinable
     public static func *= (lhs: inout Time, rhs: Double) {
         lhs = lhs * rhs
     }
-    
+
+    /// Divides a time value by a scalar, storing the result in the left-hand operand.
+    /// - Parameters:
+    ///   - lhs: The time value to modify.
+    ///   - rhs: The scalar to divide by.
     @inlinable
     public static func /= (lhs: inout Time, rhs: Double) {
         lhs = lhs / rhs
     }
 
+    /// Returns a Boolean value indicating whether the first time value is less than the second.
+    /// - Parameters:
+    ///   - lhs: A time value to compare.
+    ///   - rhs: Another time value to compare.
+    /// - Returns: `true` if the first value is less than the second value; otherwise, `false`.
     @inlinable
     public static func < (lhs: Time, rhs: Time) -> Bool {
         lhs.seconds < rhs.seconds
     }
-    
+
     @inlinable
     public static func == (a: Time, b: Time) -> Bool {
         a.seconds == b.seconds
     }
-    
+
     @inlinable
     public func hash(into hasher: inout Hasher) {
         hasher.combine(seconds)

Tests/OpenSwiftUICoreTests/Data/TimeTests.swift

@@ -0,0 +1,123 @@
+//
+//  TimeTests.swift
+//  OpenSwiftUICoreTests
+
+@_spi(ForOpenSwiftUIOnly)
+import OpenSwiftUICore
+import Testing
+import Numerics
+
+struct TimeTests {
+    @Test
+    func initialization() {
+        let time1 = Time(seconds: 10)
+        #expect(time1.seconds.isApproximatelyEqual(to: 10))
+
+        let time2 = Time()
+        #expect(time2.seconds.isApproximatelyEqual(to: 0))
+
+        #expect(Time.zero.seconds.isApproximatelyEqual(to: 0))
+        #expect(Time.infinity.seconds == Double.infinity)
+    }
+
+    @Test
+    func systemUptime() {
+        let uptime = Time.systemUptime
+        #expect(uptime.seconds > 0)
+    }
+
+    @Test
+    func negation() {
+        let time = Time(seconds: 5)
+        let negated = -time
+        #expect(negated.seconds.isApproximatelyEqual(to: -5))
+    }
+
+    @Test
+    func addition() {
+        let time = Time(seconds: 5)
+        let result1 = time + 3
+        #expect(result1.seconds.isApproximatelyEqual(to: 8))
+
+        let result2 = 3 + time
+        #expect(result2.seconds.isApproximatelyEqual(to: 8))
+
+        var time2 = Time(seconds: 5)
+        time2 += 3
+        #expect(time2.seconds.isApproximatelyEqual(to: 8))
+    }
+
+    @Test
+    func subtraction() {
+        let time = Time(seconds: 5)
+        let result1 = time - 3
+        #expect(result1.seconds.isApproximatelyEqual(to: 2))
+
+        let time2 = Time(seconds: 8)
+        let diff = time2 - time
+        #expect(diff.isApproximatelyEqual(to: 3))
+
+        var time3 = Time(seconds: 5)
+        time3 -= 3
+        #expect(time3.seconds.isApproximatelyEqual(to: 2))
+    }
+
+    @Test
+    func multiplication() {
+        let time = Time(seconds: 5)
+        let result = time * 3
+        #expect(result.seconds.isApproximatelyEqual(to: 15))
+
+        var time2 = Time(seconds: 5)
+        time2 *= 3
+        #expect(time2.seconds.isApproximatelyEqual(to: 15))
+    }
+
+    @Test
+    func division() {
+        let time = Time(seconds: 15)
+        let result = time / 3
+        #expect(result.seconds.isApproximatelyEqual(to: 5))
+
+        var time2 = Time(seconds: 15)
+        time2 /= 3
+        #expect(time2.seconds.isApproximatelyEqual(to: 5))
+    }
+
+    @Test
+    func comparison() {
+        let time1 = Time(seconds: 5)
+        let time2 = Time(seconds: 10)
+        let time3 = Time(seconds: 5)
+
+        #expect(time1 < time2)
+        #expect(time1 <= time2)
+        #expect(time2 > time1)
+        #expect(time2 >= time1)
+        #expect(time1 == time3)
+        #expect(time1 != time2)
+    }
+
+    @Test
+    func hashable() {
+        let time1 = Time(seconds: 5)
+        let time2 = Time(seconds: 5)
+        let time3 = Time(seconds: 10)
+
+        var set = Set<Time>()
+        set.insert(time1)
+        set.insert(time2)
+        set.insert(time3)
+
+        #expect(set.count == 2)
+    }
+
+    @Test
+    func sendable() {
+        let time = Time(seconds: 5)
+        Task {
+            let copiedTime = time
+            #expect(copiedTime.seconds.isApproximatelyEqual(to: 5))
+        }
+    }
+}