Module datetime 

Date/Time/Timestamp/Interval support for Citadel SQL.

Thin wrapper around jiff so the rest of the codebase doesn’t depend on it directly. Timestamps are UTC microseconds since 1970-01-01. INTERVAL is PG-compatible: (months: i32, days: i32, micros: i64).

Constants

DATE_INFINITY_DAYS

i64 µs / 86_400_000_000 wraps to i32 for max representable date: ~292k years.

DATE_NEG_INFINITY_DAYS

MICROS_PER_DAY

Microseconds per day.

MICROS_PER_HOUR

Microseconds per hour.

MICROS_PER_MIN

Microseconds per minute.

MICROS_PER_SEC

Microseconds per second.

TS_INFINITY_MICROS

TS_NEG_INFINITY_MICROS

Functions

add_days_to_date

add_interval_to_date

PG rule: DATE + INTERVAL always yields TIMESTAMP.

add_interval_to_time

add_interval_to_timestamp

age

AGE(a, b) — symbolic diff preserving months/years. Uses jiff’s Span rounding to Year unit.

current_time_micros

date_to_ts

Convert a date to a timestamp at midnight UTC.

date_trunc

days_to_ymd

Convert i32 days-since-1970 to civil Gregorian (year, month, day).

extract

format_date

format_interval

format_time

format_timestamp

format_timestamp_in_zone

hmsn_to_micros

Convert (hour, minute, second, subsec_micros) to µs since midnight.

interval_to_total_micros

PG-normalized total µs for comparison purposes (30-day month, 24-hour day).

is_infinity_date

is_infinity_ts

justify_days

justify_hours

justify_interval

micros_to_hmsn

Convert µs-since-midnight to (hour, minute, second, subsec_micros).

now_micros

parse_date

Parse an ISO 8601 DATE literal (YYYY-MM-DD, optional BC suffix, 'infinity' / '-infinity').

parse_interval

Parse a SQL INTERVAL literal. Accepts PG verbose form ('1 year 2 months 3 days 04:05:06.789'), SQL standard qualified form ('5' DAY), and ISO 8601 duration ('P1Y2M3DT4H5M6S').

parse_time

Parse an ISO 8601 TIME literal (HH:MM:SS[.ffffff]).

parse_timestamp

Parse an ISO 8601 TIMESTAMP literal (naive YYYY-MM-DD[T ]HH:MM:SS[.ffffff] or with offset/zone). Accepts Z, fixed offsets (+HH:MM), and IANA zone names (America/New_York). 'infinity' / '-infinity' map to sentinel values.

pg_normalized_interval_cmp

Session-agnostic util used by eval.rs for SQL INTERVAL comparison normalization.

resolve_timezone

Accepts IANA names, Z, UTC, and ISO-8601 fixed offsets; rejects POSIX UTC+5 shorthand (sign-inverted in POSIX, ambiguous in practice).

strftime

subtract_timestamps

PG timestamp - timestamp: returns (days, remainder_micros) with months = 0.

today_days

ts_combine

Combine i32 date-days and i64 µs-of-day into µs-since-1970-UTC.

ts_split

Split µs since 1970-UTC into (date_days, time_micros).

ts_to_date_floor

Floor-divide timestamp µs to date days (correct for pre-1970 negative values).

txn_or_clock_micros

Read the cached txn-start clock if one is installed, else a fresh now_micros(). Used by NOW / CURRENT_TIMESTAMP / CURRENT_DATE / LOCALTIMESTAMP.

with_txn_clock

Install a txn-start timestamp for the duration of f. Restores the previous value on return (nested-safe).

ymd_to_days

Convert (year, month, day) Gregorian to i32 days-since-1970.