DateTime

Add a Duration (stored in milliseconds) to a DateTime.

Add n days to a DateTime. n may be negative.

Add n hours to a DateTime. n may be negative.

Add n milliseconds to a DateTime. n may be negative.

Add n seconds to a DateTime. n may be negative.

Compare two DateTimes. Returns -1 if a < b, 0 if a == b, 1 if a > b.

Return the day of the week for the date component of a DateTime. 0 = Sunday, 1 = Monday, ..., 6 = Saturday. (January 1, 1970 was a Thursday = 4.)

Difference between two DateTimes in seconds. diff_seconds(a, b) = to_timestamp(a) - to_timestamp(b).

Build a fixed-offset zone from an explicit label and second offset. offset_seconds is positive east of UTC, negative west. Panics if the offset is outside ±14 hours (the widest real-world legal range).

Convenience constructor: fixed offset as (hours, minutes) with a single sign applied by hours (per ISO convention). For UTC+05:30 pass (5, 30); for UTC−03:30 pass (-3, 30) (minutes always positive, sign comes from hours). Name is auto-derived.

Convenience constructor: fixed offset in whole hours. The name is auto-derived in ISO 8601 form (e.g. "+05:00", "-08:00", "Z"). For custom labels use fixed_zone(name, seconds).

Format a DateTime as a string. Supported specifiers: %Y %m %d %H %M %S %%

Example: DateTime.format(dt, "%Y-%m-%d %H:%M:%S")

Format a zone's offset as ISO 8601: \"Z\" for UTC, \"+HH:MM\" or \"-HH:MM\" otherwise. Seconds-of-offset are ignored (no real zone uses sub-minute offsets since 1972).

Convert a Unix timestamp (Int seconds) to a DateTime.

    DateTime.from_timestamp(0)     -- DateTime(Date(1970, 1, 1), Time(0, 0, 0))
    DateTime.from_timestamp(86400) -- DateTime(Date(1970, 1, 2), Time(0, 0, 0))

Return the civil (wall-clock) DateTime component.

Format a LocalDateTime. All DateTime.format specifiers are supported (%Y %m %d %H %M %S %%) plus: %z — offset without colon, e.g. +0530, -0800, +0000 %:z — ISO 8601 offset, e.g. +05:30, -08:00, Z for UTC %Z — zone name (whatever was passed to the Tz constructor)

Build a LocalDateTime from a UTC instant expressed as a Unix timestamp (Int seconds).

Reinterpret a UTC DateTime as the same instant in zone tz.

Return the current wall-clock time in zone tz.

Pair a civil DateTime (interpreted as the wall-clock time in tz) with its zone. No conversion happens — dt is used as-is. Use local_from_utc if you start from a UTC instant.

Unix timestamp (UTC seconds) of the instant this LocalDateTime denotes.

Convert a LocalDateTime to the corresponding UTC DateTime. Subtracts the zone's offset from the civil time.

Return the same instant rendered in a different zone. local_with_zone(ldt, z) satisfies local_to_timestamp(result) == local_to_timestamp(ldt) (same instant, different wall-clock).

Return the zone of a LocalDateTime.

Return the current Unix timestamp as an Int (seconds since 1970-01-01 UTC).

Parse a UTC DateTime from a string. Accepts "YYYY-MM-DD" and "YYYY-MM-DD HH:MM:SS". Returns Ok(DateTime) or Err(message) — rejects out-of-range fields (month 13, day 32, hour 25, …) rather than constructing a garbage calendar value.

This entry point is timezone-naive: the returned `DateTime` always
represents UTC.  For ISO 8601 strings with an explicit offset
(`Z`, `+HH:MM`, `-HHMM`, …) use `parse_offset` to get a
`LocalDateTime` whose zone is recovered from the suffix.

Parse an ISO 8601 datetime with explicit offset, e.g. "2024-01-15T10:30:45Z" or "2024-01-15 10:30:45+05:30". Returns Ok(LocalDateTime) or Err(msg).

Bare UTC instants (no offset suffix) parse as UTC.  The `T`/space
separator is required.  Offsets may use `:` (ISO form) or the compact
`+HHMM` form.  Civil fields are range-validated.

Convert a DateTime to a Unix timestamp (Int seconds since 1970-01-01 UTC).

    DateTime.to_timestamp(DateTime(Date(1970, 1, 1), Time(0, 0, 0))) -- 0

The UTC zone (offset 0, name \

Return the zone's human label (e.g. \

Return the zone's offset from UTC in seconds (east is positive).