Time
Immutable wall clock positions, exact fractional seconds, strict parsing and time and space complexity.
Time is an import free immutable wall clock time with nanosecond resolution. It describes a position within a calendar day, without assigning a date, UTC offset, timezone, or elapsed duration.
Construction and representation
let start: Time = Time(hour: 9, minute: 30, second: 0)
let precise = Time(hour: 9, minute: 30, second: 0, nanosecond: 125000000)
print(start.str())
print(precise.str())
print(precise.nanosecond()) // 125000000Time(hour: Int64, minute: Int64, second: Int64) defaults nanoseconds to zero. The four argument overload adds nanosecond: Int64. Hour must be 0 through 23, minute and second 0 through 59, and nanosecond 0 through 999,999,999. Leap seconds and 24:00:00 are rejected.
Time.parse(text: String) accepts HH:MM:SS with an optional decimal fraction of one through nine digits. Fractions represent decimal seconds, so .1 means 100,000,000 nanoseconds. Extra fractional digits are rejected rather than rounded. str() emits canonical clock text, omits trailing fractional zeros, and preserves the exact represented value without a locale dependent format.
Methods
| Method or factory | Result | Contract |
|---|---|---|
Time.parse(text: String) | Time | Parse complete clock text, optionally with fractional seconds. |
Time.try_parse(text: String) | Result<Time, String> | Return a clock value or a recoverable validation error. |
hour() | Int64 | Hour from 0 through 23. |
minute() | Int64 | Minute from 0 through 59. |
second() | Int64 | Second from 0 through 59. |
nanosecond() | Int64 | Fraction within the current second. |
day_nanoseconds() | Int64 | Nanoseconds since the beginning of the represented day. |
str() | String | Format canonical clock text. |
Comparison orders clock positions within a day. It does not establish which of two observations occurred first across dates or daylight saving transitions. Use an explicit DateTime for an instant and Duration for elapsed timing. type(value) reports Time; calendar and clock values have no homogeneous element dtype.
Errors and limits
An invalid clock field, nanosecond count, or clock text representation produces a located runtime error R3401. Wrong static argument types or arities produce E1002. The corresponding documented try_ conversions represent expected validation failure as Result.err with a String payload rather than halting execution. A runtime failure retains the normal program or persistent session error contract.
Time and space complexity
Time uses O(1) persistent native storage. Construction, accessors, equality, and ordering take O(1) time and O(1) additional space. Parsing admits a bounded clock representation and takes O(1) time and space. Formatting returns a bounded String in O(1) time and space, excluding ordinary argument evaluation copies.