Introducing Timer.record(_ duration:), closes #114

Sources/Metrics/Metrics.swift

@@ -74,3 +74,39 @@ extension Timer {
         }
     }
 }
+
+#if swift(>=5.7)
+
+public enum TimerError: Error {
+    case durationToIntOverflow
+}
+
+extension Timer {
+    /// Convenience for recording a duration based on ``Duration``.
+    ///
+    /// `Duration` will be converted to an `Int64` number of nanoseconds, and then recorded with nanosecond precision.
+    ///
+    /// - Parameters:
+    ///     - duration: The `Duration` to record.
+    ///
+    /// - Throws: `TimerError.durationToIntOverflow` if conversion from `Duration` to `Int64` of Nanoseconds overflowed.
+    @available(macOS 13, iOS 16, tvOS 15, watchOS 8, *)
+    @inlinable
+    public func record(_ duration: Duration) throws {
+        // `Duration` doesn't have a nice way to convert it nanoseconds or seconds,
+        // so we'll do the multiplication manually.
+        // Nanoseconds are the smallest unit Timer can track, so we'll record in that.
+        let (seconds, overflow) = duration.components.seconds.multipliedReportingOverflow(by: 1_000_000_000)
+        guard !overflow else {
+            throw TimerError.durationToIntOverflow
+        }
+
+        let (nanoseconds, attosecondsOverflow) = seconds.addingReportingOverflow(duration.components.attoseconds / 1_000_000_000)
+        guard !attosecondsOverflow else {
+            throw TimerError.durationToIntOverflow
+        }
+
+        self.recordNanoseconds(nanoseconds)
+    }
+}
+#endif

Tests/MetricsTests/MetricsTests+XCTest.swift

@@ -29,6 +29,7 @@ extension MetricsExtensionsTests {
             ("testTimerWithTimeInterval", testTimerWithTimeInterval),
             ("testTimerWithDispatchTime", testTimerWithDispatchTime),
             ("testTimerWithDispatchTimeInterval", testTimerWithDispatchTimeInterval),
+            ("testTimerDuration", testTimerDuration),
             ("testTimerUnits", testTimerUnits),
             ("testPreferDisplayUnit", testPreferDisplayUnit),
         ]

Tests/MetricsTests/MetricsTests.swift

@@ -96,6 +96,35 @@ class MetricsExtensionsTests: XCTestCase {
         XCTAssertEqual(metrics.timers.count, 1, "timer should have been stored")
     }
 
+    func testTimerDuration() throws {
+        // Wrapping only the insides of the test case so that the generated
+        // tests on Linux in MetricsTests+XCTest don't complain that the func does not exist.
+        #if swift(>=5.7)
+        guard #available(iOS 16, macOS 13, tvOS 15, watchOS 8, *) else {
+            return
+        }
+
+        let metrics = TestMetrics()
+        MetricsSystem.bootstrapInternal(metrics)
+
+        let name = "timer-\(UUID().uuidString)"
+        let timer = Timer(label: name)
+
+        let duration = Duration(secondsComponent: 3, attosecondsComponent: 123_000_000_000_000_000)
+        let durationInNanoseconds = duration.components.seconds * 1_000_000_000 + duration.components.attoseconds / 1_000_000_000
+
+        XCTAssertNoThrow(try timer.record(duration))
+
+        let testTimer = try metrics.expectTimer(timer)
+        XCTAssertEqual(testTimer.values.count, 1, "expected number of entries to match")
+        XCTAssertEqual(testTimer.values.first, durationInNanoseconds, "expected value to match")
+        XCTAssertEqual(metrics.timers.count, 1, "timer should have been stored")
+
+        let overflowDuration = Duration(secondsComponent: 10_000_000_000, attosecondsComponent: 123)
+        XCTAssertThrowsError(try timer.record(overflowDuration))
+        #endif
+    }
+
     func testTimerUnits() throws {
         let metrics = TestMetrics()
         MetricsSystem.bootstrapInternal(metrics)

scripts/soundness.sh

@@ -64,6 +64,12 @@ fi
 printf "\033[0;32mokay.\033[0m\n"
 
 printf "=> Checking format... "
+
+if [[ ! -x $(which swiftformat) ]]; then
+    printf "\033[0;31mswiftformat not found!\033[0m\n"
+    exit 1
+fi
+
 FIRST_OUT="$(git status --porcelain)"
 swiftformat . > /dev/null 2>&1
 SECOND_OUT="$(git status --porcelain)"