Time
The Time module provides functions for working with dates and times. Times are represented as Unix timestamps in milliseconds.
Current Time
Time.now
() -> Int
Returns the current Unix timestamp in milliseconds.
timestamp = Time.now
println timestamp
# => 1702934400000Performance Measurement
Time.rdtsc
() -> Int
Reads the CPU timestamp counter. Returns a high-resolution counter value for performance measurement.
start = Time.rdtsc
# ... some operation ...
end = Time.rdtsc
println "Cycles: ${end - start}"Time.rdtscp
() -> Int
Reads the CPU timestamp counter with serialization. Like
rdtsc but ensures all previous instructions have completed before reading.
Time.measure
a -> (Int, a)
Measures the execution time of a lazy expression. Returns a tuple of elapsed time in nanoseconds and the result.
(elapsed, result) = Time.measure (expensive-computation x)
println "Took ${elapsed} ns"
println "Result: ${result}"Formatting and Parsing
Time.format
Int -> String -> String
Formats a timestamp using the given format string.
now = Time.now
println (Time.format now "%Y-%m-%d")
# => "2024-12-19"
println (Time.format now "%H:%M:%S")
# => "14:30:00"Time.parse
String -> String -> Int
Parses a date string using the given format.
ts = Time.parse "2024-12-19" "%Y-%m-%d"
println tsDate Arithmetic
Time.add-days
Int -> Int -> Int
Adds a number of days to a timestamp.
tomorrow = Time.add-days (Time.now) 1
println (Time.format tomorrow "%Y-%m-%d")Time.add-months
Int -> Int -> Int
Adds a number of months to a timestamp.
Time.add-years
Int -> Int -> Int
Adds a number of years to a timestamp.
Time.add-duration
Int -> Duration -> Int
Adds a Duration to a timestamp.
now = Time.now
later = Time.add-duration now (Duration.from-hours 2)
println (Time.format later "%H:%M")Time.subtract-duration
Int -> Duration -> Int
Subtracts a Duration from a timestamp.
now = Time.now
earlier = Time.subtract-duration now (Duration.from-hours 3)
println (Time.format earlier "%H:%M")Time.duration-between
Int -> Int -> Duration
Returns the Duration between two timestamps.
start = Time.parse "2024-01-01" "%Y-%m-%d"
end = Time.parse "2024-01-15" "%Y-%m-%d"
dur = Time.duration-between start end
println (Duration.to-days dur)
# => 14Components
Time.components
Int -> {year, month, day, hour, minute, second, millisecond}
Breaks a timestamp into its date/time components.
c = Time.components (Time.now)
println "Year: ${c.year}, Month: ${c.month}"Time.day-of-week
Int -> Int
Returns the day of week (0 = Monday, 6 = Sunday).
dow = Time.day-of-week (Time.now)
println dow
# => 3 (Thursday)Timezones
Time.local-timezone
() -> String
Returns the local IANA timezone identifier.
println Time.local-timezone
# => "America/New_York"Time.to-timezone
Int -> String -> Int
Converts a timestamp to a different timezone.
Time.is-dst?
String -> Int -> Bool
Returns whether daylight saving time is in effect for the given timezone and timestamp.
now = Time.now
is-dst = Time.is-dst? "America/New_York" now
println is-dst
# => true (during summer)Time.utc-offset
String -> Int -> Int
Returns the UTC offset in minutes for a timezone at a given timestamp.
now = Time.now
offset = Time.utc-offset "America/New_York" now
println offset
# => -300 (EST is UTC-5, which is -300 minutes)Time.from-timezone
Int -> String -> Int
Converts a local timestamp in a timezone to UTC.
# Convert a local NYC time to UTC
local-ts = Time.parse "2024-12-19 10:00:00" "%Y-%m-%d %H:%M:%S"
utc-ts = Time.from-timezone local-ts "America/New_York"Time.format-in
Int -> String -> String -> String
Formats a timestamp using a format string in a specific timezone.
now = Time.now
println (Time.format-in now "%Y-%m-%d %H:%M:%S" "Asia/Tokyo")
# => "2024-12-20 04:30:00"
println (Time.format-in now "%H:%M %Z" "Europe/London")
# => "19:30 GMT"Time.components-in
Int -> String -> {year, month, day, hour, minute, second, millisecond, offset, timezone}
Breaks a timestamp into its date/time components for a specific timezone.
now = Time.now
c = Time.components-in now "Asia/Tokyo"
println "Tokyo time: ${c.hour}:${c.minute}"
println "Offset: ${c.offset} minutes"Time.timezone-name
String -> Int -> String
Returns the display name for a timezone at a given timestamp (e.g., "EST" or "EDT").
now = Time.now
name = Time.timezone-name "America/New_York" now
println name
# => "EST" or "EDT" depending on DSTTime.list-timezones
() -> List String
Returns a list of common IANA timezone identifiers.
zones = Time.list-timezones
println (take 5 zones)
# => ["Africa/Abidjan", "Africa/Accra", "Africa/Addis_Ababa", ...]