`(sigil time)`

(sigil time) - Time and Date Library

Time and date operations including timestamps, high-resolution timing, and date/time formatting.

Current Time

(import (sigil time))

(current-second)              ; => 1705330200.123
(format-datetime (current-second))  ; => "2025-01-15 14:30:00"

Component Access

(let ((now (current-second)))
  (time-year now)    ; => 2025
  (time-month now)   ; => 1
  (time-day now)     ; => 15
  (time-hour now)    ; => 14
  (time-minute now)  ; => 30
  (time-second now)) ; => 0

Timing

(with-timing "my-operation"
  (lambda () (heavy-computation)))
; prints: my-operation: 0.523 seconds

Exports

current-secondprocedure

Get current time as seconds since Unix epoch.

Returns a real number with fractional seconds.

(current-second)  ; => 1705330200.123456

current-jiffyprocedure

Get current time in jiffies (high-resolution timer).

Use with jiffies-per-second to compute elapsed time.

(current-jiffy)  ; => 123456789

jiffies-per-secondprocedure

Get the number of jiffies per second.

(jiffies-per-second)  ; => 1000000000 (nanosecond precision)

time->listprocedure

Convert a timestamp to a list of components.

Returns (second minute hour day month year weekday yearday dst?).

list->timeprocedure

Convert a list of time components to a timestamp.

time-secondprocedure

Get the seconds (0-59) from a timestamp.

time-minuteprocedure

Get the minutes (0-59) from a timestamp.

time-hourprocedure

Get the hour (0-23) from a timestamp.

time-dayprocedure

Get the day of month (1-31) from a timestamp.

time-monthprocedure

Get the month (1-12) from a timestamp.

time-yearprocedure

Get the year from a timestamp.

time-weekdayprocedure

Get the day of week (0=Sunday, 6=Saturday) from a timestamp.

time-yeardayprocedure

Get the day of year (1-366) from a timestamp.

time-dst?procedure

Check if daylight saving time is in effect for a timestamp.

time-utc-offsetprocedure

Get the UTC offset in seconds for the local timezone.

(time-utc-offset)  ; => -18000 (EST = -5 hours)

time-utc-offset-atprocedure

Get the UTC offset in seconds for a specific timestamp.

Unlike time-utc-offset which returns the offset for "right now", this returns the offset that applies at the given Unix timestamp. Essential for correct DST handling when parsing dates in different seasons than the current date.

(time-utc-offset-at 1711756800)  ; => offset at that specific moment

list->time-in-tzprocedure

Convert a date/time list to a Unix timestamp in a specific timezone.

Like list->time, but interprets the time components in the given IANA timezone instead of the system timezone. Uses the OS zoneinfo database for correct DST handling.

(list->time-in-tz '(0 0 11 26 3 2026) "America/New_York")
; => timestamp for 11:00 AM Eastern on 2026-03-26

sleepprocedure

Sleep for a given number of seconds.

When running inside an async context (with-async), yields to the scheduler so other tasks can run during the sleep. Outside async context, falls back to a blocking kernel sleep.

(sleep 0.5)  ; sleep 500ms
(sleep 2)    ; sleep 2 seconds

time-elapsedprocedure

Measure elapsed time for evaluating a thunk.

Returns (values result elapsed-seconds).

(let-values (((result elapsed) (time-elapsed (lambda () (fib 30)))))
  (format "Result: ~a in ~a seconds" result elapsed))

with-timingprocedure

Execute thunk and print timing information.

Returns the result of the thunk.

(with-timing "compilation"
  (lambda () (compile-file "main.sgl")))
; prints: compilation: 0.523 seconds

format-timeprocedure

Format a timestamp as HH:MM:SS string.

Pass #t as second argument to format in UTC.

(format-time (current-second))       ; => "14:30:00"
(format-time (current-second) #t)    ; => "19:30:00" (UTC)

format-dateprocedure

Format a timestamp as YYYY-MM-DD string.

(format-date (current-second))  ; => "2025-01-15"

format-datetimeprocedure

Format a timestamp as YYYY-MM-DD HH:MM:SS string.

(format-datetime (current-second))  ; => "2025-01-15 14:30:00"

pad-zeroprocedure

Pad number with leading zero if < 10. (pad-zero 5) -> "05" (pad-zero 15) -> "15"

parse-iso-dateprocedure

Parse an ISO 8601 date string into a list of components.

Accepts both full timestamps "YYYY-MM-DDTHH:MM:SSZ" and date-only strings "YYYY-MM-DD". Returns a list of (year month day hour minute second).

(parse-iso-date "2024-01-15T12:30:00Z")
; => (2024 1 15 12 30 0)
(parse-iso-date "2024-01-15")
; => (2024 1 15 0 0 0)

format-iso-dateprocedure

Format a date component list back to an ISO 8601 UTC string.

Takes a list (year month day hour minute second) and returns "YYYY-MM-DDTHH:MM:SSZ".

(format-iso-date '(2024 1 15 12 30 0))
; => "2024-01-15T12:30:00Z"

days-in-monthprocedure

Return the number of days in a given month, handling leap years.

(days-in-month 2024 2)  ; => 29 (leap year)
(days-in-month 2023 2)  ; => 28
(days-in-month 2024 7)  ; => 31

add-daysprocedure

Add a number of days to a date component list.

Takes a list (year month day hour minute second) and a day count (positive or negative), returning a new date list with month/year boundaries handled correctly.

(add-days '(2024 1 30 0 0 0) 5)
; => (2024 2 4 0 0 0)

date-compareprocedure

Compare two date component lists element by element.

Returns -1 if a is earlier, 0 if equal, 1 if a is later.

(date-compare '(2024 1 15 0 0 0) '(2024 6 1 0 0 0))  ; => -1

%native-sleepvariable

(No description)