Documentation

baml.time.Duration

An exact, signed timespan: a count of nanoseconds, with no calendar attached.

Reference version

Signature

class baml.time.Duration

An exact, signed timespan: a count of nanoseconds, with no calendar attached.

Where an Instant names an absolute point on the timeline, a Duration is the gap between two of them, so it may be negative — a - b is negative exactly when a precedes b. The count is a bigint, so every from_* constructor scales in exact arbitrary-precision arithmetic, accepts a negative argument, and cannot overflow.

Deliberately narrower than Temporal.Duration (TC39): there are no year/month/week/day fields, only nanoseconds. Calendar units are the part of Temporal's duration model that cannot be interpreted without a reference point — a month is 28 to 31 days, and a day is not 24 hours on the dates a zone shifts. Omitting them keeps every Duration operation exact. The consequence: adding a 24-hour Duration to a ZonedDateTime advances the absolute time by exactly 24 hours, which is not "the same wall-clock time tomorrow" across a DST transition.

Every to_* accessor below is lossy except to_nanoseconds. Each truncates toward zero rather than flooring, so a negative Duration rounds up: -1500 nanoseconds reads back as -1 microsecond, not -2.

Source:<builtin>/baml/ns_time/duration.bamlbytes 1250–4650

Fields

_nanoseconds

bigint

(internal) The length of the timespan in nanoseconds. May be negative.

Static methods

function

from_hours

(h: int | bigint) -> baml.time.Duration throws never

A timespan of h hours, i.e. h * 3600 seconds.

A fixed 3600-second hour, never a calendar hour: it does not absorb a DST transition. See the note on Duration.

function

from_microseconds

(us: int | bigint) -> baml.time.Duration throws never

A timespan of us microseconds, i.e. us * 1000 nanoseconds.

function

from_milliseconds

(ms: int | bigint) -> baml.time.Duration throws never

A timespan of ms milliseconds, i.e. ms * 1000000 nanoseconds.

function

from_minutes

(m: int | bigint) -> baml.time.Duration throws never

A timespan of m minutes, i.e. m * 60 seconds.

function

from_nanoseconds

(ns: int | bigint) -> baml.time.Duration throws never

A timespan of ns nanoseconds.

function

from_seconds

(s: int | bigint) -> baml.time.Duration throws never

A timespan of s seconds, i.e. s * 1000000000 nanoseconds.

Instance methods

function

abs

(self) -> baml.time.Duration throws never

The magnitude of self, with the sign discarded.

function

to_hours

(self) -> bigint throws never

The length of self in whole hours, each a fixed 3600 seconds.

function

to_microseconds

(self) -> bigint throws never

The length of self in whole microseconds.

function

to_milliseconds

(self) -> bigint throws never

The length of self in whole milliseconds.

function

to_minutes

(self) -> bigint throws never

The length of self in whole minutes.

function

to_nanoseconds

(self) -> bigint throws never

The length of self in nanoseconds. Exact: this is the stored unit.

function

to_seconds

(self) -> bigint throws never

The length of self in whole seconds.

Implementations

baml.Concrete for T

Source:<builtin>/baml/core.bamlbytes 747–779

baml.ops.Add for baml.time.Duration

Output = baml.time.Duration

Instance methods

function

add

(self, other: baml.time.Duration) -> baml.time.Duration throws never

The sum of two timespans. Exact, and cannot overflow.

Source:<builtin>/baml/ns_time/duration.bamlbytes 4652–4958

baml.ops.Divide for baml.time.Duration

Output = baml.time.Duration

Instance methods

function

div

(self, other: bigint) -> baml.time.Duration throws never

Splits self into other equal parts, returning one of them.

The nanosecond count truncates toward zero, so the parts may not sum back to self.

Panics

  • baml.panics.DivisionByZero if other is zero.

Source:<builtin>/baml/ns_time/duration.bamlbytes 6505–7007

baml.ops.Divide for baml.time.Duration

Output = baml.time.Duration

Instance methods

function

div

(self, other: int) -> baml.time.Duration throws never

Splits self into other equal parts, returning one of them.

The nanosecond count truncates toward zero, so the parts may not sum back to self.

Panics

  • baml.panics.DivisionByZero if other is zero.

Source:<builtin>/baml/ns_time/duration.bamlbytes 6007–6503

baml.ops.Multiply for baml.time.Duration

Output = baml.time.Duration

Instance methods

function

mul

(self, other: bigint) -> baml.time.Duration throws never

Scales self by an arbitrarily large integer factor. A negative factor also flips the sign of the timespan.

Source:<builtin>/baml/ns_time/duration.bamlbytes 5648–6005

baml.ops.Multiply for baml.time.Duration

Output = baml.time.Duration

Instance methods

function

mul

(self, other: int) -> baml.time.Duration throws never

Scales self by an integer factor. A negative factor also flips the sign of the timespan.

Source:<builtin>/baml/ns_time/duration.bamlbytes 5313–5646

baml.ops.Negate for baml.time.Duration

Output = baml.time.Duration

Instance methods

function

neg

(self) -> baml.time.Duration throws never

The same timespan in the opposite direction.

Source:<builtin>/baml/ns_time/duration.bamlbytes 7623–7875

baml.ops.Remainder for baml.time.Duration

Output = baml.time.Duration

Instance methods

function

rem

(self, other: baml.time.Duration) -> baml.time.Duration throws never

What is left of self after removing every whole multiple of other. The sub-minute part of a timespan is d % Duration.from_minutes(1).

Division truncates toward zero, so the result carries the sign of self, not of other.

Panics

  • baml.panics.DivisionByZero if other is zero.

Source:<builtin>/baml/ns_time/duration.bamlbytes 7009–7621

baml.ops.Subtract for baml.time.Duration

Output = baml.time.Duration

Instance methods

function

sub

(self, other: baml.time.Duration) -> baml.time.Duration throws never

The difference between two timespans. Negative when other is the longer of the two.

Source:<builtin>/baml/ns_time/duration.bamlbytes 4960–5311