Aner: A language for data science

DateTime is an import free immutable instant with a calendar date and wall clock presentation at an explicit fixed UTC offset. It provides exact seconds and nanoseconds, checked arithmetic, and unambiguous interchange text.

Construction and offsets

let observed: DateTime = DateTime(
    date: Date(2026, 10, 12),
    time: Time(9, 30, 0),
    offset_minutes: -360
)
let utc = observed.with_offset(0)
print(observed.str())
print(utc.str())
print(observed == utc) // true: same instant

DateTime(date: Date, time: Time) defaults to UTC. The three argument overload accepts offset_minutes: Int64, a fixed offset from UTC between −840 and 840 minutes inclusive (±14:00). The runtime does not infer the computer's local timezone. Changing the presentation with with_offset preserves the represented instant.

DateTime.parse(text: String) requires a complete YYYY-MM-DDTHH:MM:SS[.fraction]Z or YYYY-MM-DDTHH:MM:SS[.fraction]±HH:MM representation. Fractional seconds contain one through nine digits. A timestamp without a UTC marker or explicit offset is rejected. str() returns canonical text with an explicit offset; UTC uses Z. Supported civil years are 0001 through 9999. The zero offset -00:00 is accepted and canonicalized to Z; this subset does not retain an unknown offset annotation.

This release supports fixed offsets. Named timezone databases, daylight saving transition resolution, leap seconds, implicit local zone conversion, and calendar month arithmetic are not provided. Dataset ingestion must choose a documented offset or an explicit external normalization policy before constructing an instant.

Instants, clocks, and arithmetic

DateTime.from_unix(seconds: Int64) creates a UTC value from signed seconds since 1970 to 01 to 01T00:00:00Z. Its second overload accepts nanosecond: Int64 in 0 through 999,999,999. unix_seconds() returns the integral seconds component; nanosecond() returns the positive fractional component. Negative instants use this normalized seconds plus fraction representation.

DateTime.now() reads the system wall clock and returns UTC. Wall clocks can be corrected or moved, so subtraction of consecutive now() readings is unsuitable for reliable experiment timing. Use Duration.monotonic for elapsed measurements.

Method or factory	Result	Contract
`DateTime.parse(text: String)`	`DateTime`	Parse an offset bearing timestamp.
`DateTime.try_parse(text: String)`	`Result<DateTime, String>`	Return a parsed instant or a recoverable validation error.
`DateTime.from_unix(seconds: Int64, nanosecond: Int64)`	`DateTime`	Construct an exact UTC instant; nanoseconds may be omitted.
`DateTime.now()`	`DateTime`	Read the system wall clock in UTC.
`date()`	`Date`	Calendar date at this value's offset.
`time()`	`Time`	Wall clock time at this value's offset.
`offset_minutes()`	`Int64`	Fixed offset from UTC in minutes.
`unix_seconds()`	`Int64`	Integral seconds from the Unix epoch.
`nanosecond()`	`Int64`	Fractional nanoseconds within that second.
`with_offset(offset_minutes: Int64)`	`DateTime`	Preserve the instant and return another fixed offset presentation.
`add(duration: Duration)`	`DateTime`	Add an exact signed elapsed duration, retaining the offset.
`until(other: DateTime)`	`Duration`	Return elapsed `other` minus this instant.
`str()`	`String`	Return canonical timestamp text.

Equality and ordering compare the instant, including nanoseconds. Different offset spellings can therefore compare equal. Arithmetic checks integer overflow, duration representability, and civil bounds. A difference larger than the Int64 nanosecond duration range fails instead of losing precision. type(value) reports DateTime; dtype is unsupported.

Errors and limits

An invalid calendar, clock, or fixed offset value, or a checked instant 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

Persistent DateTime storage is O(1). Validated construction, offset conversion, accessors, comparison, add, and until take O(1) time and O(1) additional space. Parsing and formatting operate on bounded timestamp text and take O(1) time and space. now() performs one operating system clock read; wall clock latency is not a scheduling or timing guarantee. String argument evaluation retains its existing owned copy cost.

Run the complete DateTime example, and see the separate Date, Time, and Duration references.