Documentation

baml.time.TimeZoneOffset

A fixed offset from UTC, permitted in the range ±24 hours (real timezones currently run from -12 to +14 hours).

Reference version

Signature

class baml.time.TimeZoneOffset

A fixed offset from UTC, permitted in the range ±24 hours (real timezones currently run from -12 to +14 hours).

Unlike an IANA identifier, a TimeZoneOffset does not shift with daylight saving. That makes every civil-to-absolute conversion total and exact — no gaps, no overlaps, no Disambiguation, no timezone database — but it also pins a moment's offset forever, so a future date carried in one goes wrong as soon as that region's rules change. ZonedDateTime accepts either form: prefer an identifier for anything scheduled ahead, and an offset for a timestamp already stamped by someone else.

Source:<builtin>/baml/ns_time/timezone.bamlbytes 2349–7901

Fields

_nanoseconds

int

(internal) The offset east of UTC in nanoseconds. Invariant: within ±24 hours inclusive.

Static methods

function

from_duration

(
) -> baml.time.TimeZoneOffset throws baml.errors.InvalidArgument

Creates a TimeZoneOffset east of UTC by duration. A negative duration gives an offset west of UTC.

The nanosecond count is kept exactly, not rounded to a whole minute, which matters for the historical LMT offsets in the timezone database. to_string on a ZonedDateTime renders only ±hh:mm, truncating any sub-minute part toward zero.

Throws

  • baml.errors.InvalidArgument if the duration exceeds ±24 hours.
function

from_timezone

(
timezone: string,
) -> baml.time.TimeZoneOffset throws baml.time.UnknownTimezoneError

Resolves an IANA timezone identifier (e.g. "America/Los_Angeles") to its concrete offset at the absolute time at, daylight saving included.

Resolution uses the host's timezone database. The answer is a snapshot of the offset that zone had at at, and must not be reused for a different moment.

Parameters

  • timezone: an IANA identifier.
  • at: the absolute time to resolve at. An Instant rather than a civil reading, so the query is never itself ambiguous.

Throws

  • baml.time.UnknownTimezoneError if the timezone is invalid.

Panics

  • baml.panics.HostUnavailable if timezone data is unavailable.
function

local

() -> baml.time.TimeZoneOffset throws baml.time.UnknownTimezoneError | baml.errors.Io

The system timezone's offset as of right now.

Even in one location this varies over time with daylight saving, so the result is a snapshot rather than a stand-in for the system timezone itself. Keep system_timezone()'s identifier where the value has to stay correct across a transition.

Throws

  • baml.time.UnknownTimezoneError if the host names a system timezone its own timezone database then fails to resolve.
  • baml.errors.Io if the host has a timezone database but cannot tell which zone it is configured for.

Panics

  • baml.panics.HostUnavailable if the host provides no clock, or no timezone database at all.
function

new

(hours: int, minutes: int) -> baml.time.TimeZoneOffset throws baml.errors.InvalidArgument

Creates a TimeZoneOffset from hours and minutes east of UTC.

Parameters

  • hours: whole hours east of UTC; negative west of it.
  • minutes: the sub-hour part, which must carry the same sign as hours — the pair is one signed quantity split in two, not an hour count plus an unsigned remainder. So new(-9, -30) is -09:30, while new(-9, 30) is rejected rather than silently read as -08:30. new(-7, 0) and new(5, 30) are the ordinary cases.

Throws

  • baml.errors.InvalidArgument if the signs differ, or the result exceeds ±24 hours.

Panics

  • baml.panics.IntegerOverflow if hours or minutes is so large that converting it to nanoseconds overflows int. The range check happens after that conversion, so it never sees these.
function

utc

() -> baml.time.TimeZoneOffset throws never

The UTC (zero) offset.

Instance methods

function

hours

(self) -> int throws never

The hour component of the offset, truncated toward zero. Negative for an offset west of UTC.

function

minutes

(self) -> int throws never

The minute component of the offset within its hour, truncated toward zero.

Signed like hours, and for the same reason: the two are one signed quantity split in two, so -09:30 reads back as hours() == -9 and minutes() == -30. Neither reports any sub-minute part of the offset.

function

to_duration

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

The offset as a Duration east of UTC; negative west of it. Exact, and the inverse of from_duration.

Implementations

baml.Concrete for T

Source:<builtin>/baml/core.bamlbytes 763–795