std.time

wall/monotonic clocks, sleep, UTC and local calendar, dates, text formats

unix_nanos

pub unix_nanos :: fn() -> i64

ns since the unix epoch

unix_millis

pub unix_millis :: fn() -> i64

ms since the unix epoch

unix_seconds

pub unix_seconds :: fn() -> i64

whole seconds since the unix epoch

Instant

pub Instant :: struct {
    nanos: i64,
}

monotonic time point; compare via since_*, not wall time

now

pub now :: fn() -> Instant

current monotonic instant

since_nanos

pub since_nanos :: fn(start: Instant) -> i64

ns since start; never negative

since_millis

pub since_millis :: fn(start: Instant) -> i64

ms since start

since_seconds

pub since_seconds :: fn(start: Instant) -> f64

seconds since start, fractional

monotonic_millis

pub monotonic_millis :: fn() -> u64

monotonic ms (frame timing)

sleep_ms

pub sleep_ms :: fn(millis: u32)

sleep at least millis ms

DateTime

pub DateTime :: struct {
    year: i64,
    month: u8,
    day: u8,
    hour: u8,
    minute: u8,
    second: u8,
    weekday: u8,
}

broken-down UTC date and time

• month: 1..12
• day: 1..31
• hour: 0..23
• minute: 0..59
• second: 0..59
• weekday: 0=Sun..6=Sat

DateParts

pub DateParts :: struct {
    year: i64,
    month: u8,
    day: u8,
}

year, month, day of a date

• month: 1..12
• day: 1..31

utc

pub utc :: fn(secs: i64) -> DateTime

unix seconds broken down as UTC

now_utc

pub now_utc :: fn() -> DateTime

current UTC date and time

Date

pub Date :: struct {
    days: i64,
}

Gregorian day (also before 1582) as days since 1970-01-01; compare by days

Date.parts

pub parts :: fn(self: *Self) -> DateParts

year, month, day

Date.year

pub year :: fn(self: *Self) -> i64

Date.month

pub month :: fn(self: *Self) -> u8

Date.day

pub day :: fn(self: *Self) -> u8

Date.weekday

pub weekday :: fn(self: *Self) -> u8

0=Sunday..6=Saturday, as in DateTime

Date.add_days

pub add_days :: fn(self: *Self, n: i64) -> Date

n days later (earlier if negative)

Date.add_months

pub add_months :: fn(self: *Self, n: i64) -> Date

n months later (earlier if negative); the day clamps to the month’s last

Date.add_years

pub add_years :: fn(self: *Self, n: i64) -> Date

add_months(12 * n); Feb 29 -> Feb 28

Date.days_until

pub days_until :: fn(self: *Self, other: Date) -> i64

days to other; positive if other is later

is_leap_year

pub is_leap_year :: fn(year: i64) -> bool

days_in_month

pub days_in_month :: fn(year: i64, month: i64) -> i64

days in month (1..12) of year; 0 for an invalid month

date

pub date :: fn(year: i64, month: i64, day: i64) -> ?Date

null if no such day (2023-02-29, month 13)

today_utc

pub today_utc :: fn() -> Date

parse_date

pub parse_date :: fn(text: []const u8) -> ?Date

parse YYYY-MM-DD; null if it isn’t one

format_date

pub format_date :: fn(d: Date, buf: []u8) -> []const u8

d as YYYY-MM-DD into buf (>= 10 bytes); empty for years outside 0..9999

to_unix

pub to_unix :: fn(dt: DateTime) -> i64

inverse of utc: unix seconds of dt as UTC; weekday ignored

weekday_name

pub weekday_name :: fn(wd: u8) -> []const u8

English weekday name; 0 = Sunday

month_name

pub month_name :: fn(m: u8) -> []const u8

English month name; 1 = January

ZoneOffset

pub ZoneOffset :: struct {
    seconds: i64,
    dst: bool,
}

zone offset at an instant: seconds east of UTC, and whether it is DST

local_offset

pub local_offset :: fn(secs: i64) -> i64

local zone’s seconds east of UTC at secs, DST included; 0 if the zone is unknown

local

pub local :: fn(secs: i64) -> DateTime

secs in local time

now_local

pub now_local :: fn() -> DateTime

local date and time now

TimeError

pub TimeError :: errors {
    bad_zone,
}

• bad_zone: a TZif file or POSIX TZ rule this cannot read

tzif_offset

pub tzif_offset :: fn(data: []const u8, secs: i64) -> ZoneOffset ! TimeError

offset at secs from a TZif file (RFC 8536); past the last transition, its POSIX rule

posix_offset

pub posix_offset :: fn(rule: []const u8, secs: i64) -> ZoneOffset ! TimeError

offset at secs for a POSIX TZ rule; DST between its two dates each year

format_datetime

pub format_datetime :: fn(dt: DateTime, offset: i64, pattern: []const u8, out: []u8) -> []const u8

strftime-like (%Z = +01:00) into out, cut to fit; offset: secs east of UTC, for %z

format_rfc3339

pub format_rfc3339 :: fn(secs: i64, offset: i64, out: []u8) -> []const u8

secs as RFC 3339 at offset secs east of UTC (0 -> Z) into out; 32 bytes suffice

Stamp

pub Stamp :: struct {
    secs: i64,
    nanos: u32,
    offset: i64,
}

parsed instant: unix secs (UTC), extra ns, and the offset it was written with

parse_rfc3339

pub parse_rfc3339 :: fn(text: []const u8) -> ?Stamp

parse RFC 3339 (T/t/space, Z/z/+hh:mm, optional fraction); null if invalid

format_duration

pub format_duration :: fn(ns: i64, out: []u8) -> []const u8

ns as human text (2d 3h 5m, 4.25s, 350ms) into out; 32 bytes suffice

parse_duration

pub parse_duration :: fn(text: []const u8) -> ?i64

parse 1h30m, 1.5s, -3m to ns; units d h m s ms us ns; null otherwise