DateTime

Date and time manipulation with a clean, object-oriented API.

The DateTime class provides a convenient way to work with dates and times. Create instances using static methods, then use instance methods to extract components or perform arithmetic.

Static Methods

DateTime.now()

Get the current local date and time.

Returns

DateTime - A DateTime instance representing the current local time

now = DateTime.now
println(now.to_iso())  # "2024-01-15T10:30:00"

DateTime.utc()

Get the current UTC date and time.

Returns

DateTime - A DateTime instance representing the current UTC time

utc = DateTime.utc
println(utc.to_iso())  # "2024-01-15T15:30:00Z"

DateTime.parse(string)

Parse a date/time string in ISO 8601 or RFC format.

Parameters

string : String - The date string to parse

Returns

DateTime - A DateTime instance

dt = DateTime.parse("2024-01-15T10:30:00Z")
date_only = DateTime.parse("2024-01-15")

DateTime.epoch()

Create a DateTime at Unix epoch (1970-01-01 00:00:00 UTC).

Returns

DateTime - A DateTime instance at epoch

epoch = DateTime.epoch()
println(epoch.year())  # 1970

DateTime.from_unix(timestamp)

Create a DateTime from a Unix timestamp (seconds since epoch).

Parameters

timestamp : Int - Unix timestamp in seconds

Returns

DateTime - A DateTime instance

dt = DateTime.from_unix(1704067200)
println(dt.to_iso())  # "2024-01-01T00:00:00Z"

DateTime.microtime()

Get the current Unix timestamp in microseconds as a Float.

Returns

Float - Microseconds since epoch

mt = DateTime.microtime()
println(mt)  # 1712832000000000.0

Date Components

.year()

Get the year component (e.g., 2024).

Returns

Int - The year

.month()

Get the month component (1-12).

Returns

Int - The month (1 = January, 12 = December)

.day()

Get the day of month (1-31).

Returns

Int - The day of the month

.hour()

Get the hour component (0-23).

Returns

Int - The hour in 24-hour format

.minute()

Get the minute component (0-59).

Returns

Int - The minute

.second()

Get the second component (0-59).

Returns

Int - The second

.weekday()

Get the day of the week as a string.

Returns

String - The weekday name (e.g., "monday", "tuesday")

dt = DateTime.parse("2024-01-15")
println(dt.weekday())  # "monday"

Formatting

.to_unix()

Get the Unix timestamp (seconds since epoch).

Returns

Int - Unix timestamp in seconds

dt = DateTime.now
println(dt.to_unix())  # 1705315800

.to_iso()

Get the date/time as an ISO 8601 string.

Returns

String - ISO 8601 formatted string

dt = DateTime.now
println(dt.to_iso())  # "2024-01-15T10:30:00"

.format(pattern, locale?)

Format the date/time using strftime pattern specifiers, with optional locale for internationalized month and day names.

Parameters

pattern : String - strftime format pattern

locale : String? - Optional locale code ("en", "fr", "es", "de", "it", "pt"). Defaults to "en"

Common Format Specifiers

%Y - Year (4 digits)

%m - Month (01-12)

%d - Day (01-31)

%H - Hour (00-23)

%M - Minute (00-59)

%S - Second (00-59)

%B - Month name (localized)

%A - Weekday name (localized)

%b - Abbreviated month (localized)

%a - Abbreviated weekday (localized)

dt = DateTime.parse("2024-01-15T10:30:00")
dt.format("%Y-%m-%d %H:%M:%S")  # "2024-01-15 10:30:00"
dt.format("%B %d, %Y")           # "January 15, 2024"
dt.format("%A")                  # "Monday"

Locale Examples

dt = DateTime.parse("2024-03-06T14:30:00Z")

# French
dt.format("%A %d %B %Y", "fr")   # "mercredi 06 mars 2024"
dt.format("%d %b %Y", "fr")      # "06 mars 2024"

# Spanish
dt.format("%A %d %B %Y", "es")   # "miércoles 06 marzo 2024"

# Without locale or with "en" - English (default)
dt.format("%A %d %B %Y")         # "Wednesday 06 March 2024"
dt.format("%A %d %B %Y", "en")   # "Wednesday 06 March 2024"

Arithmetic

.add_days(n)

Add days to the date. Use negative values to subtract.

Parameters

n : Int - Number of days to add

Returns

DateTime - A new DateTime instance

today = DateTime.now
tomorrow = today.add_days(1)
yesterday = today.add_days(-1)

.add_hours(n)

Add hours to the date/time. Use negative values to subtract.

Parameters

n : Int - Number of hours to add

Returns

DateTime - A new DateTime instance

now = DateTime.now
in_two_hours = now.add_hours(2)

.add_weeks(n)

Add weeks to the date. Use negative values to subtract.

Parameters

n : Int - Number of weeks to add

Returns

DateTime - A new DateTime instance

today = DateTime.now
next_week = today.add_weeks(1)

.add_months(n)

Add months to the date. Use negative values to subtract.

Parameters

n : Int - Number of months to add

Returns

DateTime - A new DateTime instance

today = DateTime.now
next_month = today.add_months(1)
last_quarter = today.add_months(-3)

.add_years(n)

Add years to the date. Use negative values to subtract.

Parameters

n : Int - Number of years to add

Returns

DateTime - A new DateTime instance

today = DateTime.now
next_year = today.add_years(1)

Boundaries

.beginning_of_minute()

Truncate seconds and sub-seconds to zero, keeping the same minute.

Returns

DateTime - A new DateTime instance

.end_of_minute()

Set seconds to 59 and milliseconds to 999, keeping the same minute.

Returns

DateTime - A new DateTime instance

.beginning_of_hour()

Set minutes, seconds, and sub-seconds to zero, keeping the same hour.

Returns

DateTime - A new DateTime instance

.end_of_hour()

Set minutes to 59, seconds to 59, and milliseconds to 999, keeping the same hour.

Returns

DateTime - A new DateTime instance

.beginning_of_day()

Set hours, minutes, seconds, and sub-seconds to zero, keeping the same day.

Returns

DateTime - A new DateTime instance

.end_of_day()

Set the time to 23:59:59.999, keeping the same day.

Returns

DateTime - A new DateTime instance

.beginning_of_month()

Set the day to 1 and time to 00:00:00.000, keeping the same month and year.

Returns

DateTime - A new DateTime instance

dt = DateTime.parse("2024-06-15T10:30:45Z")
dt.beginning_of_month().day()    # 1
dt.beginning_of_month().hour()   # 0

.end_of_month()

Set the date to the last day of the month and time to 23:59:59.999, keeping the same month and year.

Returns

DateTime - A new DateTime instance

dt = DateTime.parse("2024-06-15T10:30:45Z")
dt.end_of_month().day()    # 30
dt.end_of_month().hour()   # 23

.beginning_of_year()

Set the date to January 1st and time to 00:00:00.000, keeping the same year.

Returns

DateTime - A new DateTime instance

.end_of_year()

Set the date to December 31st and time to 23:59:59.999, keeping the same year.

Returns

DateTime - A new DateTime instance

How a DateTime prints and serialises

A DateTime is a value, not an object. In string position it renders as local wall clock — the same thing to_string() returns — and in JSON it becomes an RFC 3339 string, matching to_iso().

dt = DateTime.parse("2026-11-15 12:00:00")

str(dt)                      # "2026-11-15 12:00:00"   (local)
"#{dt}"                      # "2026-11-15 12:00:00"
{"at": dt}.to_json()         # {"at":"2026-11-15T12:00:00+00:00"}

Because it is a value rather than an object, two DateTimes built from the same instant are equal (== compares the moment, not identity), and passing one around copies it rather than sharing a reference.

Boundary methods and daylight saving

The beginning_of_* / end_of_* methods work on local wall-clock time, so on the two days a year the clocks change, the boundary they ask for may not be a real instant. Both cases resolve to a value — these methods never fail:

The hour repeats (clocks go back). 2026-11-01 00:00:00 happens twice in America/Havana. The earliest of the two instants is used — the first time the wall clock reads that value, which is what “beginning of” means.
The hour is skipped (clocks go forward). 2023-10-01 00:00:00 never happens in America/Asuncion. The first instant that does exist is used, i.e. the moment the gap closes.

The local zone comes from $TZ when set, otherwise from the system zone — matching the behaviour of the rest of the runtime.

# Under TZ=America/Havana
dt = DateTime.parse("2026-11-15 12:00:00")
dt.beginning_of_month().format("%Y-%m-%d %H:%M:%S")   # 2026-11-01 00:00:00

Comparison

Two DateTime instances can be compared with the standard operators (<, <=, >, >=, ==, !=). Comparison is by absolute instant — equality holds when both refer to the same moment, regardless of which DateTime object you're holding.

let a = DateTime.from_unix(1700000000)
let b = DateTime.from_unix(1700000000)
let later = a.add_hours(1)

a == b       # true — same instant, different instances
a < later    # true
later >= a   # true

Helper Functions

These free-standing functions are available alongside the DateTime class.

time_ago(timestamp)

Returns a human-readable relative time string. Uses the current I18n locale for translations (supports en, fr, de, es, it, pt, ja, zh).

Parameters

Name	Type	Description
timestamp	Int \| String	Unix timestamp or date string

Returns

String - Human-readable relative time

time_ago(datetime_now() - 7200)  # "2 hours ago" (en)
                                 # "il y a 2 heures" (fr)
                                 # "vor 2 Stunden" (de)
time_ago(ts)                     # "5 seconds ago"
time_ago(ts)                     # "1 minute ago"
time_ago(ts)                     # "2 weeks ago"
time_ago(future_ts)              # "in the future"

Complete Example

# Get current date/time
now = DateTime.now
println("Current time: " + now.to_iso())

# Extract components
println("Year: " + now.year())
println("Month: " + now.month())
println("Day: " + now.day())
println("Weekday: " + now.weekday())

# Format output
println(now.format("%B %d, %Y at %H:%M"))

# Format with locale for I18n
println(now.format("%A %d %B %Y", "fr"))  # "lundi 15 janvier 2024"
println(now.format("%A %d %B %Y", "es"))  # "lunes 15 enero 2024"

# Date arithmetic
next_week = now.add_weeks(1)
last_month = now.add_months(-1)

# Parse a date string
birthday = DateTime.parse("1990-06-15")
println("Birthday was on a " + birthday.weekday())

Env Functions Duration