Standard Library

std.time

Time helpers for tool-style scripts.

Exported functions

pub def now() -> Timestamp

Return the current UTC timestamp.

Examples

use time from "std.time"

const timestamp = time.now()
@println(time.format_rfc3339(timestamp)) # Current UTC time

pub def now_unix_seconds() -> Int

Return the current Unix timestamp in seconds.

pub def now_unix_millis() -> Int

Return the current Unix timestamp in milliseconds.

pub def sleep(delay_ms: Int) -> Void

Pause the current thread for the specified number of milliseconds.

pub def sleep_for(duration: Duration) -> Void

Pause the current thread for a duration value.

pub def from_unix_seconds(value: Int) -> Timestamp

Construct a timestamp from Unix seconds.

pub def from_unix_millis(value: Int) -> Timestamp

Construct a timestamp from Unix milliseconds.

pub def unix_seconds(timestamp: Timestamp) -> Int

Return the Unix seconds for a timestamp.

pub def unix_millis(timestamp: Timestamp) -> Int

Return the Unix milliseconds for a timestamp.

pub def milliseconds(value: Int) -> Duration

Create a duration in milliseconds.

pub def seconds(value: Int) -> Duration

Create a duration in seconds.

pub def minutes(value: Int) -> Duration

Create a duration in minutes.

pub def hours(value: Int) -> Duration

Create a duration in hours.

pub def days(value: Int) -> Duration

Create a duration in days.

pub def add(left: Duration, right: Duration) -> Duration

Return the sum of two durations.

Examples

use time from "std.time"

const delay = time.add(time.seconds(2), time.milliseconds(500))
@println(delay.milliseconds) # 2500

pub def subtract(left: Duration, right: Duration) -> Duration

Return the difference between two durations.

pub def multiply(duration: Duration, factor: Int) -> Duration

Multiply a duration by an integer factor.

pub def between(start: Timestamp, finish: Timestamp) -> Duration

Return the elapsed duration between two timestamps.

Examples

use time from "std.time"

const start = time.from_unix_seconds(10)
const finish = time.from_unix_millis(12500)
@println(time.between(start, finish).milliseconds) # 2500

pub def add_to(timestamp: Timestamp, duration: Duration) -> Timestamp

Add a duration to a timestamp.

Examples

use time from "std.time"

const start = time.parse_rfc3339("2026-04-18T12:00:00Z")
const deadline = time.add_to(start, time.minutes(30))
@println(time.format_rfc3339(deadline)) # 2026-04-18T12:30:00Z

pub def subtract_from(timestamp: Timestamp, duration: Duration) -> Timestamp

Subtract a duration from a timestamp.

pub def format_rfc3339(timestamp: Timestamp) -> String

Format a timestamp as an RFC3339 string in UTC.

Examples

use time from "std.time"

@println(time.format_rfc3339(time.from_unix_seconds(0))) # 1970-01-01T00:00:00Z

pub def try_parse_rfc3339(text: String) -> Timestamp ! TimeError

Parse an RFC3339 string into a timestamp.

Examples

use time from "std.time"

def demonstrate() -> Void
  var timestamp = try time.try_parse_rfc3339("not-a-date") catch err
    case is time.TimeError.InvalidRfc3339 => time.from_unix_seconds(0)
    case _ => time.from_unix_seconds(0)
  end
  @println(time.format_rfc3339(timestamp)) # 1970-01-01T00:00:00Z
end

demonstrate()

pub def parse_rfc3339(text: String) -> Timestamp

Parse an RFC3339 string and panic on invalid input.

Examples

use time from "std.time"

const timestamp = time.parse_rfc3339("2026-04-18T14:30:00+02:00")
@println(time.format_rfc3339(timestamp)) # 2026-04-18T12:30:00Z

pub def to_utc(timestamp: Timestamp) -> DateTime

Break a timestamp into UTC calendar components. Weekday is ISO numbering: 1 = Monday through 7 = Sunday.

Examples

use time from "std.time"

const parts = time.to_utc(time.from_unix_seconds(0))
@println(parts.year) # 1970
@println(parts.weekday) # 4 (Thursday; Monday is 1)

pub def year(timestamp: Timestamp) -> Int

Return the UTC year of a timestamp.

pub def month(timestamp: Timestamp) -> Int

Return the UTC month (1-12) of a timestamp.

pub def day(timestamp: Timestamp) -> Int

Return the UTC day of month (1-31) of a timestamp.

pub def hour(timestamp: Timestamp) -> Int

Return the UTC hour (0-23) of a timestamp.

pub def minute(timestamp: Timestamp) -> Int

Return the UTC minute (0-59) of a timestamp.

pub def second(timestamp: Timestamp) -> Int

Return the UTC second (0-59) of a timestamp.

pub def weekday(timestamp: Timestamp) -> Int

Return the ISO weekday (1 = Monday .. 7 = Sunday) of a timestamp.

pub def try_format(timestamp: Timestamp, pattern: String) -> String ! TimeError

Format a timestamp with a format description such as "[year]-[month]-[day] [hour]:[minute]:[second]".

pub def format(timestamp: Timestamp, pattern: String) -> String

Format a timestamp with a format description, panicking on failure.

Examples

use time from "std.time"

const timestamp = time.from_calendar(2026, 4, 18, 8, 5, 9)
@println(time.format(timestamp, "[year]-[month]-[day] [hour]:[minute]")) # 2026-04-18 08:05

pub def try_parse(text: String, pattern: String) -> Timestamp ! TimeError

Parse text with a format description into a UTC timestamp. Patterns without an offset are interpreted as UTC.

pub def parse(text: String, pattern: String) -> Timestamp

Parse text with a format description, panicking on failure.

Examples

use time from "std.time"

const timestamp = time.parse("2026-04-18", "[year]-[month]-[day]")
@println(time.format_rfc3339(timestamp)) # 2026-04-18T00:00:00Z

pub def try_from_calendar(in_year: Int, in_month: Int, in_day: Int, in_hour: Int, in_minute: Int, in_second: Int) -> Timestamp ! TimeError

Build a UTC timestamp from calendar components.

Examples

use time from "std.time"

def demonstrate() -> Void
  try time.try_from_calendar(2023, 2, 29, 0, 0, 0) catch err
    case is time.TimeError.InvalidDate
      @println("That date does not exist")
      return
    case _
      @panic("unexpected time error")
  end
  return
end

demonstrate()

pub def from_calendar(in_year: Int, in_month: Int, in_day: Int, in_hour: Int, in_minute: Int, in_second: Int) -> Timestamp

Build a UTC timestamp from calendar components, panicking on failure.

Examples

use time from "std.time"

const timestamp = time.from_calendar(2024, 2, 29, 12, 30, 45)
@println(time.format_date(timestamp)) # 2024-02-29
@println(time.format_time(timestamp)) # 12:30:45

pub def format_date(timestamp: Timestamp) -> String

Format a timestamp as "YYYY-MM-DD" in UTC.

Examples

use time from "std.time"

@println(time.format_date(time.from_unix_seconds(0))) # 1970-01-01

pub def format_time(timestamp: Timestamp) -> String

Format a timestamp as "HH:MM:SS" in UTC.

Examples

use time from "std.time"

@println(time.format_time(time.from_unix_seconds(0))) # 00:00:00

use time from "std.time" def demonstrate() -> Void var timestamp = try time.try_parse_rfc3339("not-a-date") catch err case is time.TimeError.InvalidRfc3339 => time.from_unix_seconds(0) case _ => time.from_unix_seconds(0) end @println(time.format_rfc3339(timestamp)) # 1970-01-01T00:00:00Z end demonstrate()

use time from "std.time" def demonstrate() -> Void try time.try_from_calendar(2023, 2, 29, 0, 0, 0) catch err case is time.TimeError.InvalidDate @println("That date does not exist") return case _ @panic("unexpected time error") end return end demonstrate()