std/time

Standard Library documentation

Time objects, formatting, and parsing.

Back to Stdlib View Source

Module

Name
std/time
Area
Standard Library
Source
modules/std/time.zzm

NAME

std/time - Time objects, formatting, and parsing.

SYNOPSIS

  from std/time import Time, TimeZone, Duration, TimeFormat, TimeParser;

  let london := TimeZone.named("Europe/London");
  let now := new Time(timezone: london);
  let tomorrow := now.add_days(1);
  let next_hour := now.add(Duration.hours(1));

  let parsed := Time.parse("2026-03-20T12:00:00", timezone: london);
  say TimeFormat.rfc3339().format(parsed);

IMPLEMENTATION SUPPORT

This module is supported by all implementations of ZuzuScript.

DESCRIPTION

This module provides immutable Time objects for working with instants, timezones, calendar arithmetic, parsing, and serialization. TimeParser remains available for compatibility with older strptime-style parsing.

EXPORTS

Classes

  • Time(Number epoch?, timezone: TimeZone|String?)

    Construct a time from an epoch value in seconds, or use the current time when omitted. timezone controls the calendar view used by component accessors and calendar arithmetic. Returns: Time.

    Common instance methods include:

    • time.sec(), time.min(), time.hour()

      Parameters: none. Returns: Number. Returns the seconds, minutes, or hours component.

    • time.day_of_month(), time.mon(), time.month(), time.year(), time.yy()

      Parameters: none. Returns: Number. Returns the local calendar date component.

    • time.day_of_week(), time.day(), time.day_of_year(), time.month_last_day()

      Parameters: none. Returns: Number. Returns derived local calendar component values.

    • time.epoch()

      Parameters: none. Returns: Number. Returns epoch seconds.

    • time.timezone()

      Parameters: none. Returns: TimeZone. Returns the timezone metadata for the time object.

    • time.with_timezone(TimeZone|String zone)

      Parameters: zone is an IANA name, fixed offset, or TimeZone. Returns: Time. Keeps the same instant and changes the displayed timezone.

    • time.reinterpret_timezone(TimeZone|String zone)

      Parameters: zone is an IANA name, fixed offset, or TimeZone. Returns: Time. Keeps the same displayed date/time fields and changes the instant.

    • time.hms(separator?), time.ymd(separator?), time.mdy(separator?), time.dmy(separator?)

      Parameters: separator is an optional separator string. Returns: String. Formats a time or date component string.

    • time.date(), time.time(), time.datetime(), time.cdate(), time.to_String()

      Parameters: none. Returns: String. Formats the time using common date and time layouts.

    • time.strftime(String format)

      Parameters: format is a strftime format string. Returns: String. Formats the time with format.

    • time.to_iso8601(), time.to_rfc3339(), time.to_rfc5322(include_weekday: Boolean?)

      Parameters: include_weekday is an optional Boolean for to_rfc5322. Returns: String. Serializes the time using common machine and mail date formats. to_rfc5322 includes a weekday by default; pass include_weekday: false to omit it.

    • time.tzoffset()

      Parameters: none. Returns: Number. Returns the local timezone offset.

    • time.is_leap_year()

      Parameters: none. Returns: Boolean. Returns true when the local year is a leap year.

    • time.week(), time.week_year(), time.julian_day()

      Parameters: none. Returns: Number. Returns week-numbering and Julian day values.

    • time.add_seconds(Number n), time.add_minutes(Number n), time.add_hours(Number n), time.add_days(Number n), time.add_weeks(Number n)

      Parameters: n is the amount to add. Returns: Time. Seconds, minutes, and hours are elapsed-time operations. Days and weeks are calendar operations in the object's timezone.

    • time.add_months(Number n), time.add_years(Number n)

      Parameters: n is the amount to add. Returns: Time. Returns a new time offset by calendar months or years on supported builds.

    • time.subtract_seconds(Number n), time.subtract_minutes(Number n), time.subtract_hours(Number n), time.subtract_days(Number n), time.subtract_weeks(Number n), time.subtract_months(Number n), time.subtract_years(Number n)

      Parameters: n is the amount to subtract. Returns: Time.

    • time.add(Duration d), time.subtract(Duration d)

      Parameters: d is a Duration. Returns: Time.

    • time.elapsed_seconds_until(Time other), time.compare(Time other), time.is_before(Time other), time.is_after(Time other)

      Parameters: other is another Time. Returns elapsed seconds, ordering, or boolean comparison results.

    • Time.parse(String text, timezone: TimeZone|String?)

      Parameters: text is ISO 8601/RFC 3339 or RFC 5322 text. RFC 5322 input accepts common obsolete mail-date spellings including two-digit years, legacy US zones, and military zones other than J. Zone-less ISO input requires an explicit timezone. Returns: Time.

    • TimeZone.utc(), TimeZone.local(), TimeZone.named(String name), TimeZone.offset(Number seconds)

      Returns timezone helper objects. Named zones use IANA timezone names.

    • Duration.seconds(Number n), Duration.minutes(Number n), Duration.hours(Number n), Duration.days(Number n), Duration.weeks(Number n), Duration.months(Number n), Duration.years(Number n)

      Returns immutable duration helper objects.

    • TimeFormat.iso8601(), TimeFormat.rfc3339(), TimeFormat.rfc5322(), TimeFormat.strftime(String pattern)

      Returns formatter/parser helper objects.

    • TimeFormat.format(Time time)

      Parameters: time is a Time. Returns: String. Formats time using the helper object's format.

    • TimeFormat.parse(String text, timezone: TimeZone|String?)

      Parameters: text is date-time text matching the helper object's format. RFC 5322 input may carry its own timezone. Zone-less input requires an explicit timezone. Returns: Time.

  • TimeParser(String format = "%Y-%m-%d")

    Creates a parser for the given format string. Returns: TimeParser.

  • TimeParser->parse(String text)

    Parameters: text is text matching the parser format. Returns: Time. Parses text into a time object.

COPYRIGHT AND LICENCE

std/time is copyright Toby Inkster.

It is free software; you may redistribute it and/or modify it under the terms of either the Artistic License 1.0 or the GNU General Public License version 2.