davedelong/time

This system is a Swift library for handling complex calendrical and temporal data, providing robust types for instants, durations, and fixed calendar components. It enables precise time arithmetic, interval relationship analysis, and flexible formatting or parsing of dates across different regions and locales. The library also supports real-time clock simulations with customizable scaling and strike notifications, ensuring cross-platform stability and type-safe operations.

Users can now determine the temporal relationship between two \Fixed\ values or ranges using the new \Relation\ enum, which implements Allen's Interval Algebra. This includes 13 distinct relationship types (such as \before\, \after\, \overlaps\, \contains\, \during\, \meets\, etc.) and convenience methods like \isBefore\, \isAfter\, \contains\, \isDuring\, and \overlaps\ on the \Fixed\ type, along with range-based relation checks.

Sources/Time/10-Relations · high confidence

Users can now create a \Fixed\ time value by parsing a string against a raw format template and a specific region. This new initializer accepts a string (e.g., "2024-01-30"), a format string (e.g., "y-MM-dd"), and a \Region\, using a \DateFormatter\ to convert the input. If parsing fails, it throws a \TimeError.cannotParseString\ error, providing the original string, format, and region for debugging.

Sources/Time/9-Parsing · high confidence

The \Fixed\ type now includes a suite of methods to round time values to specific boundaries (such as nearest hour, day, month, or year) and supports custom rounding directions (forward, backward, or nearest). This allows users to easily snap time instances to whole multiples of larger time units, with specific handling for era boundaries.

Sources/Time/11-Rounding · high confidence

The formatting API for \Fixed\ values has been significantly expanded to support granular, template-driven composition of date and time strings. Users can now format specific calendar components (such as era, year, month, day, weekday, hour, minute, second, and nanosecond) individually or in various combinations using the new \Template\ types and \FixedFormatStyle\ presets (full, long, medium, short). This allows for precise control over output, including support for standalone month/weekday names, day periods (AM/PM), and time zones, while also introducing a \format(raw:strict:)\ method for hard-coded format strings like ISO8601 with optional strict validation.

Sources/Time/8-Formatting · high confidence

The \Fixed\ type (representing specific calendar units like days, months, or years) has been expanded with new capabilities. It now conforms to \Codable\, allowing fixed values to be serialized to and deserialized from JSON, with backward compatibility for older formats. A new \ConversionBehavior\ enum enables converting a fixed value to a different region or calendar, either by preserving the original time range (e.g., converting 2 PM LA to Rome) or by preserving the calendar components (e.g., keeping the same day/month/year numbers). Additionally, new properties and methods allow navigating between granularities (e.g., getting all hours in a day) and performing safe adjustments, while Linux-specific thread-safety workarounds have been added to mitigate issues with Foundation's \NSCalendar\.

Sources/Time/4-Fixed Values · high confidence

The library now includes a new \RegionalClock\ protocol and implementation suite in the \Sources/Time/3-RegionalClock\ module, allowing users to access current calendar values (such as year, month, day, and hour) within a specific \Region\. This update adds the ability to create custom clocks that can be offset by a time interval or scaled to run faster or slower than real time, as well as a \ClockStrikes\ feature that emits notifications at specific intervals or times using \AsyncSequence\ or Combine publishers.

Sources/Time/3-RegionalClock · high confidence

This change introduces the \TimeDifference\ type and associated extensions for the \Fixed\ type, enabling users to compute calendrical differences between fixed time values (e.g., \Fixed\<Day\>\) using the \-\ operator or \difference(to:)\ method. It adds specific methods like \differenceInWholeYears\, \differenceInWholeMonths\, etc., to calculate differences in whole units of a specific granularity. Additionally, it defines invalid addition/subtraction operations (e.g., adding months to a year) as unavailable, preventing nonsensical calendrical arithmetic at compile time.

Sources/Time/5-Differences · high confidence

This change introduces three new foundational types for the Time library. \SISeconds\ provides a high-precision duration representation backed by Swift's \Duration\ type, supporting arithmetic operations and precise serialization. \Epoch\ defines temporal reference points (such as Unix and Reference epochs) from which time intervals are calculated. \Instant\ represents a specific point in time relative to an \Epoch\, offering methods for conversion between epochs, arithmetic operations, and interoperability with Foundation's \Date\. These types collectively replace previous implementations to provide a more robust and semantically clear API for time handling.

Sources/Time/1-Core Types · high confidence

The Examples app now provides a tabbed interface featuring three distinct demonstrations: a Calendar view for selecting days with configurable week consistency, a Clocks view that displays real-time updates and allows switching between various calendars, time zones, and locales, and a Calculator view that computes time differences between two selected moments using whole or cumulative units.

Examples · high confidence

The library now provides two new sequence types for iterating through time values. BoundaryAlignedSequence automatically resets to a calendar boundary (such as the top of the hour) when a stride crosses it, ensuring that iterations like 13-minute steps snap back to clean boundaries rather than drifting. FixedSequence allows users to generate infinite, conditional, or ranged sequences of fixed time values with a specified stride, supporting both open and closed ranges for precise iteration control.

Sources/Time/7-Sequences · high confidence

This change introduces the foundational types for the calendar subsystem. The new \Region\ struct encapsulates a user's calendrical preferences (calendar, time zone, and locale) and provides static instances for current, POSIX, and autoupdating configurations, while ensuring values are snapshotted to avoid unexpected updates. A new \TimeError\ type defines specific failure reasons for calendrical operations, such as missing units, invalid components, or format string errors. Additionally, the \Units.swift\ file establishes the \Unit\ protocol and specific enum types (e.g., \Second\, \Minute\, \Hour\) that map to \Foundation.Calendar.Component\ values, along with hierarchical protocols for relative unit durations.

Sources/Time/2-Core Calendar · high confidence

The internal implementation of the Time library has been restructured to improve cross-platform stability and code clarity. The \Absolute\ type has been renamed to \Fixed\, and the \Delta\ type has been renamed to \Difference\ to better reflect their semantic roles. To address Linux-specific build issues, the codebase now uses \Task.sleep(until:tolerance:clock:)\ instead of the unavailable \Task.sleep(for:)\ and implements custom locking mechanisms using \NSLock\ rather than relying on \NSLock.withLock\. Additionally, a new \Snapshot\ system ensures that \Locale\, \TimeZone\, and \Calendar\ values are captured as stable snapshots, preventing issues with autoupdating system settings, while \DateFormatter\ and other resources are now cached to optimize performance.

Sources/Time/Internals · high confidence

Added a new suite of unit tests in the Tests directory to verify core Time library functionality. These tests cover Clock behavior (including system, custom accelerated/decelerated rates, and strike events), Fixed date/time component formatting and rounding, Region settings (such as 24-hour preference and timezone handling), and temporal relations between dates and ranges. The suite also includes specific tests for Linux platform compatibility and regression checks for previously reported bugs.

Tests · high confidence

The project is now distributed as a Swift Package with a minimum Swift 5.7 requirement, supporting macOS 13, iOS 16, tvOS 16, watchOS 9, and Mac Catalyst 16. The package includes a core 'Time' library and its associated tests, and integrates the Swift DocC plugin (version 1.1.0) to enable documentation generation.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 63 → 71 (+7.4)
• Rubric changed (rubric-2026.09.11 → rubric-2026.09.18) — scores are not directly comparable.

• Code Health 96 → 97 (+0.8)
• Architecture 90 → 96 (+6.0)
• Maturity 44 → 59 (+15.2)
• Readiness 67 → 69 (+2.2)
• Security 90 → 90 (+0.0)

• Dependency hygiene PARTLY measured — SwiftPM pinning read, dependency currency NOT established
• Documentation: no installation or build instructions (README.md)
• Documentation: no usage examples (README.md)
• Duplicate arithmetic operations. adding(years:) and subtracting(years:) are specific cases of the generic + and - operators which accept TimeDifference. This forces users to choose between two different ways to do the same thing.
• Duplicate operation for calculating time difference. The subtraction operator - and the method difference(to:) perform the exact same calculation.
• Excessive method proliferation for setting components. There are 20+ overloads of setting for every combination of components. This is a code smell indicating a lack of a unified component-setting API.
• Fixed.roundToMultiple (cognitive 18) (Sources/Time/4-Fixed Values/Fixed.swift)
• Inconsistent conversion API surface. Some conversions require a ConversionBehavior enum (Region, TimeZone, Calendar), while others (Locale, TimeZone, Calendar) do not. This creates confusion about when behavior is required. Additionally, converted(to: TimeZone) exists both with and without behavior.
• Low coverage: Sources/Time/10-Relations/Relations.swift (Sources/Time/10-Relations/Relations.swift)
• Low coverage: Sources/Time/2-Core Calendar/TimeError.swift (Sources/Time/2-Core Calendar/TimeError.swift)
• Low coverage: Sources/Time/2-Core Calendar/Units.swift (Sources/Time/2-Core Calendar/Units.swift)
• Low coverage: Sources/Time/3-RegionalClock/RegionalClock+CurrentValues.swift (Sources/Time/3-RegionalClock/RegionalClock+CurrentValues.swift)
• Low coverage: Sources/Time/3-RegionalClock/RegionalClock+Implementations.swift (Sources/Time/3-RegionalClock/RegionalClock+Implementations.swift)
• Low coverage: Sources/Time/3-RegionalClock/RegionalClock+Strikes.swift (Sources/Time/3-RegionalClock/RegionalClock+Strikes.swift)
• Low coverage: Sources/Time/3-RegionalClock/RegionalClock.swift (Sources/Time/3-RegionalClock/RegionalClock.swift)
• Low coverage: Sources/Time/4-Fixed Values/Fixed+Conversion.swift (Sources/Time/4-Fixed Values/Fixed+Conversion.swift)
• Low coverage: Sources/Time/4-Fixed Values/Fixed+Day.swift (Sources/Time/4-Fixed Values/Fixed+Day.swift)
• Low coverage: Sources/Time/4-Fixed Values/Fixed+Era.swift (Sources/Time/4-Fixed Values/Fixed+Era.swift)
• Low coverage: Sources/Time/4-Fixed Values/Fixed+Hour.swift (Sources/Time/4-Fixed Values/Fixed+Hour.swift)
• Low coverage: Sources/Time/4-Fixed Values/Fixed+Minute.swift (Sources/Time/4-Fixed Values/Fixed+Minute.swift)
• …and 18 more

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

davedelong/time was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.