Aner: A language for data science

Duration is an import free immutable signed elapsed quantity. Native storage is an exact Int64 count of nanoseconds. It separates experiment timing and elapsed arithmetic from calendar dates and wall clock corrections.

Construction and exact arithmetic

let interval: Duration = Duration(nanoseconds: 1500000000)
let total = interval.add(Duration.from_milliseconds(250))
print(total.str())             // PT1.75S
print(total.nanoseconds())     // 1750000000
print(total.total_seconds())   // floating-point presentation

Duration(nanoseconds: Int64) preserves the exact integer. Duration.from_seconds(seconds: Int64) and Duration.from_milliseconds(milliseconds: Int64) perform checked exact scaling. They do not accept Float64 quantities or silently round fractional inputs. Use an exact nanosecond count when a fraction is required.

Duration.parse(text: String) accepts [-]PT<seconds>[.<fraction>]S, where the optional decimal fraction has one through nine digits. The supported interchange subset describes elapsed seconds; it does not interpret calendar years, months, weeks, or daylight saving days. str() returns a canonical representation in this subset.

The Int64 range covers approximately 292 years in either direction at nanosecond resolution. add, subtract, multiply, and negate check overflow. Negating the minimum Int64 count fails because its positive magnitude is not representable. No operation saturates or silently changes precision.

Monotonic experiment timing

let started = Duration.monotonic()
var checksum = 0
for index in Range(1000) {
    checksum = checksum + index
}
let elapsed = Duration.monotonic().subtract(started)
print(checksum)
print(elapsed.total_seconds())

Duration.monotonic() reads a process local steady clock. Its origin is unspecified; only differences between readings from the same process have meaning. Readings are not calendar timestamps, must not be serialized as observation dates, and must not be compared across hosts. Timing resolution and call overhead depend on the operating system. Use DateTime.now for a UTC observation timestamp.

Methods and factories

Method or factory	Result	Contract
`Duration.from_seconds(seconds: Int64)`	`Duration`	Checked exact conversion from integral seconds.
`Duration.from_milliseconds(milliseconds: Int64)`	`Duration`	Checked exact conversion from integral milliseconds.
`Duration.parse(text: String)`	`Duration`	Parse the elapsed seconds text subset.
`Duration.try_parse(text: String)`	`Result<Duration, String>`	Return a duration or a recoverable validation error.
`Duration.monotonic()`	`Duration`	Read a steady clock count with an unspecified process local origin.
`nanoseconds()`	`Int64`	Return the exact stored count.
`total_seconds()`	`Float64`	Return a numerical seconds presentation; floating point rounding may occur.
`add(other: Duration)`	`Duration`	Return a checked sum.
`subtract(other: Duration)`	`Duration`	Return a checked difference.
`multiply(factor: Int64)`	`Duration`	Return a checked integral multiple.
`negate()`	`Duration`	Return the checked opposite value.
`str()`	`String`	Return canonical elapsed seconds text.

Equality and ordering compare exact nanosecond counts. type(value) reports Duration; dtype is unsupported because an elapsed quantity is not an element storage datatype.

Errors and limits

Malformed duration text or a checked nanosecond arithmetic overflow 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

A Duration retains O(1) native storage. Construction, conversion, arithmetic, comparison, and accessors use O(1) time and O(1) additional space. Parsing and formatting admit bounded Int64 second text with at most nine fractional digits and use O(1) time and space. A monotonic reading performs one operating system clock read. total_seconds does not change the exact stored quantity.

Run the complete Duration example.