datetime
stableDate and time utilities for getting the current time, formatting, parsing, arithmetic, and calendar queries — all without external dependencies.
use plugin datetime::{now_unix, now_unix_ms, now_unix_us, …} Functions (36)
- now_unix Current time as Unix seconds
- now_unix_ms Current time as Unix milliseconds
- now_unix_us Current time as Unix microseconds
- format_iso8601 Format a Unix timestamp as ISO 8601
- parse_iso8601 Parse an ISO 8601 string to Unix seconds
- format_custom Format a timestamp with a strftime-like pattern
- parse_custom Parse a date string with a custom pattern
- unix_to_parts Decompose Unix seconds into date/time parts
- parts_to_unix Convert date/time parts to Unix seconds
- days_in_month Number of days in a given year/month
- is_leap_year Check if a year is a leap year
- day_of_week Day-of-week name for a date
- day_of_year Day number within the year
- week_number ISO week number for a timestamp
- quarter Calendar quarter (1–4) for a timestamp
- is_weekend Check if a timestamp falls on a weekend
- next_weekday Get the next weekday after a timestamp
- add_seconds Add seconds to a Unix timestamp
- add_minutes Add minutes to a Unix timestamp
- add_hours Add hours to a Unix timestamp
- add_days Add days to a Unix timestamp
- add_months Add months to a Unix timestamp
- add_years Add years to a Unix timestamp
- diff_seconds Difference in seconds between two timestamps
- diff_hours Difference in hours between two timestamps
- diff_days Difference in days between two timestamps
- diff_months Difference in months between two timestamps
- diff_years Difference in years between two timestamps
- start_of_day Unix timestamp at midnight of the same day
- end_of_day Unix timestamp at 23:59:59 of the same day
- start_of_month Unix timestamp at the first of the month
- end_of_month Unix timestamp at the last moment of the month
- start_of_year Unix timestamp at Jan 1 00:00:00
- end_of_year Unix timestamp at Dec 31 23:59:59
- timezone_offset_name Format a UTC offset as "UTC+HH:MM"
- duration_human Format a duration in seconds as human text
Overview
datetime is a dependency-free toolkit for working with dates and times as plain
Unix timestamps (integer seconds, milliseconds, or microseconds since the 1970
epoch, all in UTC). Rather than wrapping an opaque date object, every function
takes and returns ordinary integers, so a timestamp is just a number you can
store, compare, and pass around freely. Use it whenever you need the current
time, calendar math (leap years, week numbers, quarters), arithmetic that
respects month and year boundaries, or conversion between timestamps and either
ISO 8601 strings or custom strftime-style patterns.
The mental model is simple: get a timestamp with now_unix (or build one with
parts_to_unix / parse_iso8601), transform it with the add_*, start_of_*,
and end_of_* helpers, inspect it with the calendar queries, then render it with
format_iso8601 or format_custom.
Common patterns
Round a timestamp to a calendar boundary and render it:
use plugin datetime::{now_unix, start_of_month, end_of_month, format_iso8601}
let ts = now_unix()
print("month begins: {format_iso8601(start_of_month(ts))}")
print("month ends: {format_iso8601(end_of_month(ts))}")
Parse an ISO string, do calendar arithmetic, then reformat it:
use plugin datetime::{parse_iso8601, add_days, format_custom}
let due = parse_iso8601("2026-06-09T09:00:00Z")
let reminder = add_days(due, -2)
print("reminder on: {format_custom(reminder, "%a %b %d %Y")}")
Measure an elapsed span and show it in human-readable units:
use plugin datetime::{parse_iso8601, diff_seconds, duration_human}
let started = parse_iso8601("2026-06-09T08:00:00Z")
let finished = parse_iso8601("2026-06-09T11:30:45Z")
print("ran for {duration_human(diff_seconds(finished, started))}")
Current time as Unix seconds
Returns the current time as a Unix timestamp in whole seconds (UTC).
use plugin datetime::{now_unix, format_iso8601}
let ts = now_unix()
print("now: {format_iso8601(ts)}")
Current time as Unix milliseconds
Returns the current time in milliseconds since the Unix epoch.
use plugin datetime::{now_unix_ms}
let start = now_unix_ms()
print("start ms: {start}")
Current time as Unix microseconds
Returns the current time in microseconds since the Unix epoch. Useful for high-resolution timing.
use plugin datetime::{now_unix_us}
let t = now_unix_us()
print("us: {t}")
Format a Unix timestamp as ISO 8601
Formats a Unix timestamp as an ISO 8601 string in UTC, e.g.
"2026-06-09T14:30:00Z".
use plugin datetime::{now_unix, format_iso8601}
let ts = now_unix()
print(format_iso8601(ts))
Parse an ISO 8601 string to Unix seconds
Parses an ISO 8601 UTC string ("YYYY-MM-DDTHH:MM:SSZ") and returns a Unix
timestamp in seconds.
use plugin datetime::{parse_iso8601, format_iso8601}
let ts = parse_iso8601("2026-06-09T09:00:00Z")
print(format_iso8601(ts))
Format a timestamp with a strftime-like pattern
Formats a timestamp using a strftime-like format string. Supported tokens:
%Y (year), %m (month), %d (day), %H (hour), %M (minute),
%S (second), %a (day abbr), %b (month abbr), %% (literal %).
use plugin datetime::{now_unix, format_custom}
let ts = now_unix()
print(format_custom(ts, "%Y-%m-%d"))
print(format_custom(ts, "%a %b %d %Y"))
print(format_custom(ts, "%H:%M:%S"))
Round-trip a timestamp through a custom pattern with parse_custom:
use plugin datetime::{format_custom, parse_custom}
let stamp = "2026-12-25 18:30:00"
let ts = parse_custom(stamp, "%Y-%m-%d %H:%M:%S")
print(format_custom(ts, "%d/%m/%Y at %H:%M"))
Parse a date string with a custom pattern
Parses a date string using the same strftime-like tokens as format_custom.
Returns a Unix timestamp in seconds.
use plugin datetime::{parse_custom, format_iso8601}
let ts = parse_custom("09/06/2026", "%d/%m/%Y")
print(format_iso8601(ts))
Decompose Unix seconds into date/time parts
Decomposes a Unix timestamp into a table with year, month, day, hour,
minute, and second fields (all integers, UTC).
use plugin datetime::{now_unix, unix_to_parts}
let parts = unix_to_parts(now_unix())
print("year: {parts["year"]}, month: {parts["month"]}, day: {parts["day"]}")
Combine with format_custom to read just the clock time:
use plugin datetime::{now_unix, unix_to_parts}
let p = unix_to_parts(now_unix())
print("{p["hour"]}:{p["minute"]}:{p["second"]}")
Convert date/time parts to Unix seconds
Converts individual date/time components to a Unix timestamp in seconds (UTC).
use plugin datetime::{parts_to_unix, format_iso8601}
let ts = parts_to_unix(2026, 12, 25, 0, 0, 0)
print(format_iso8601(ts))
It pairs naturally with day_of_week to ask what weekday a built date is:
use plugin datetime::{parts_to_unix, unix_to_parts, day_of_week}
let p = unix_to_parts(parts_to_unix(2027, 1, 1, 12, 0, 0))
print(day_of_week(p["year"], p["month"], p["day"]))
Number of days in a given year/month
Returns the number of days in the given month, accounting for leap years.
use plugin datetime::{days_in_month}
print(days_in_month(2024, 2))
print(days_in_month(2025, 2))
print(days_in_month(2026, 1))
Check if a year is a leap year
Returns true if year is a leap year (divisible by 4, not by 100, unless
also divisible by 400).
use plugin datetime::{is_leap_year}
print(is_leap_year(2024))
print(is_leap_year(2100))
print(is_leap_year(2000))
Day-of-week name for a date
Returns the day-of-week name (e.g. "Monday") for the given date.
use plugin datetime::{day_of_week}
print(day_of_week(2026, 6, 9))
Day number within the year
Returns the day number within the year (1–365 or 1–366) for a timestamp.
use plugin datetime::{now_unix, day_of_year}
print("day of year: {day_of_year(now_unix())}")
ISO week number for a timestamp
Returns the ISO week number (1–53) for the given timestamp.
use plugin datetime::{now_unix, week_number}
print("week: {week_number(now_unix())}")
Calendar quarter (1–4) for a timestamp
Returns the calendar quarter (1–4) for the given timestamp.
use plugin datetime::{now_unix, quarter}
print("Q{quarter(now_unix())}")
Check if a timestamp falls on a weekend
Returns true if the timestamp falls on a Saturday or Sunday.
use plugin datetime::{now_unix, is_weekend}
if is_weekend(now_unix()) {
print("it is the weekend")
}
Get the next weekday after a timestamp
Returns the Unix timestamp of the start of the next Monday–Friday day after the given timestamp.
use plugin datetime::{now_unix, next_weekday, format_iso8601}
let next = next_weekday(now_unix())
print("next weekday: {format_iso8601(next)}")
Add seconds to a Unix timestamp
Adds seconds to a Unix timestamp and returns the result.
use plugin datetime::{now_unix, add_seconds, format_iso8601}
let later = add_seconds(now_unix(), 300)
print(format_iso8601(later))
Add minutes to a Unix timestamp
Adds minutes to a Unix timestamp (each minute is 60 seconds).
use plugin datetime::{now_unix, add_minutes, format_iso8601}
let in_two_hours = add_minutes(now_unix(), 120)
print(format_iso8601(in_two_hours))
Add hours to a Unix timestamp
Adds hours to a Unix timestamp (each hour is 3600 seconds).
use plugin datetime::{now_unix, add_hours, format_iso8601}
let tomorrow = add_hours(now_unix(), 24)
print(format_iso8601(tomorrow))
Add days to a Unix timestamp
Adds days to a Unix timestamp (each day is 86400 seconds).
use plugin datetime::{now_unix, add_days, format_iso8601}
let next_week = add_days(now_unix(), 7)
print(format_iso8601(next_week))
Add months to a Unix timestamp
Adds months to a timestamp, clamping the day to the last valid day of the
resulting month.
use plugin datetime::{now_unix, add_months, format_iso8601}
let in_three_months = add_months(now_unix(), 3)
print(format_iso8601(in_three_months))
Because the day is clamped, adding one month to Jan 31 lands on the end of February rather than overflowing:
use plugin datetime::{parse_iso8601, add_months, format_iso8601}
let jan31 = parse_iso8601("2026-01-31T00:00:00Z")
print(format_iso8601(add_months(jan31, 1)))
Add years to a Unix timestamp
Adds years to a timestamp, clamping Feb 29 to Feb 28 in non-leap years.
use plugin datetime::{now_unix, add_years, format_iso8601}
let next_year = add_years(now_unix(), 1)
print(format_iso8601(next_year))
Difference in seconds between two timestamps
Returns a - b in seconds.
use plugin datetime::{now_unix, diff_seconds}
let start = now_unix()
let end = start + 3661
print("diff: {diff_seconds(end, start)}s")
Difference in hours between two timestamps
Returns the difference between two timestamps in whole hours ((a - b) / 3600).
use plugin datetime::{diff_hours, parse_iso8601}
let a = parse_iso8601("2026-06-10T12:00:00Z")
let b = parse_iso8601("2026-06-09T06:00:00Z")
print("hours apart: {diff_hours(a, b)}")
Difference in days between two timestamps
Returns the difference between two timestamps in whole days
((a - b) / 86400).
use plugin datetime::{diff_days, parse_iso8601}
let a = parse_iso8601("2026-07-01T00:00:00Z")
let b = parse_iso8601("2026-06-09T00:00:00Z")
print("days apart: {diff_days(a, b)}")
Difference in months between two timestamps
Returns the difference in whole calendar months between two timestamps.
use plugin datetime::{diff_months, parse_iso8601}
let a = parse_iso8601("2027-03-01T00:00:00Z")
let b = parse_iso8601("2026-06-01T00:00:00Z")
print("months: {diff_months(a, b)}")
Difference in years between two timestamps
Returns the difference in whole calendar years between two timestamps.
use plugin datetime::{diff_years, parse_iso8601}
let born = parse_iso8601("2000-01-01T00:00:00Z")
let now = parse_iso8601("2026-06-09T00:00:00Z")
print("age: {diff_years(now, born)}")
Unix timestamp at midnight of the same day
Returns the Unix timestamp for midnight (00:00:00 UTC) of the same day.
use plugin datetime::{now_unix, start_of_day, format_iso8601}
print(format_iso8601(start_of_day(now_unix())))
Unix timestamp at 23:59:59 of the same day
Returns the Unix timestamp for 23:59:59 UTC of the same day.
use plugin datetime::{now_unix, end_of_day, format_iso8601}
print(format_iso8601(end_of_day(now_unix())))
Unix timestamp at the first of the month
Returns the Unix timestamp for 00:00:00 on the first day of the same month.
use plugin datetime::{now_unix, start_of_month, format_iso8601}
print(format_iso8601(start_of_month(now_unix())))
Unix timestamp at the last moment of the month
Returns the Unix timestamp for 23:59:59 on the last day of the same month.
use plugin datetime::{now_unix, end_of_month, format_iso8601}
print(format_iso8601(end_of_month(now_unix())))
Unix timestamp at Jan 1 00:00:00
Returns the Unix timestamp for Jan 1 00:00:00 UTC of the same year.
use plugin datetime::{now_unix, start_of_year, format_iso8601}
print(format_iso8601(start_of_year(now_unix())))
Unix timestamp at Dec 31 23:59:59
Returns the Unix timestamp for Dec 31 23:59:59 UTC of the same year.
use plugin datetime::{now_unix, end_of_year, format_iso8601}
print(format_iso8601(end_of_year(now_unix())))
Format a UTC offset as "UTC+HH:MM"
Formats a UTC offset (in fractional hours) as a string like "UTC+05:30" or
"UTC-08:00".
use plugin datetime::{timezone_offset_name}
print(timezone_offset_name(5.5))
print(timezone_offset_name(-8.0))
print(timezone_offset_name(0.0))
Format a duration in seconds as human text
Formats a duration in seconds as a compact human-readable string using d,
h, m, and s units, e.g. "1d 2h 30m 15s".
use plugin datetime::{duration_human}
print(duration_human(90061))
print(duration_human(3600))
print(duration_human(45))