Date and time

Numbat supports date and time handling based on the proleptic Gregorian calendar, which is the (usual) Gregorian calendar extended to dates before its introduction in 1582.

A few examples of useful operations that can be performed on dates and times:

# How many days are left until September 1st?
date("2024-11-01") - today() -> days

# What time is it in Nepal right now?
now() -> tz("Asia/Kathmandu")  # use tab completion to find time zone names

# What is the local time when it is 2024-11-01 12:30:00 in Australia?
datetime("2024-11-01 12:30:00 Australia/Sydney") -> local

# Which date was 1 million seconds ago?
now() - 1 million seconds

# Which date is 40 days from now?
calendar_add(now(), 40 days)

# Which weekday was the 1st day of this century?
date("2000-01-01") -> weekday

# What is the current UNIX timestamp?
now() -> unixtime

# What is the date corresponding to a given UNIX timestamp?
from_unixtime(1707568901)

# How long are one million seconds in years, months, days, hours, minutes, seconds?
1 million seconds -> human

Date and time arithmetic

The following operations are supported for DateTime objects:

Date, time, and duration functions

The following functions are available for date and time handling:

• now() -> DateTime: Returns the current date and time.
• today() -> DateTime: Returns the current date at midnight (in the local time).
• datetime(input: String) -> DateTime: Parses a string (date and time) into a DateTime object.
• date(input: String) -> DateTime: Parses a string (only date) into a DateTime object.
• time(input: String) -> DateTime: Parses a string (only time) into a DateTime object.
• format_datetime(format: String, dt: DateTime) -> String: Formats a DateTime object as a string. See this page for possible format specifiers.
• tz(tz: String) -> Fn[(DateTime) -> DateTime]: Returns a timezone conversion function, typically used with the conversion operator (datetime -> tz("Europe/Berlin"))
• local(dt: DateTime) -> DateTime: Timezone conversion function targeting the users local timezone (datetime -> local)
• get_local_timezone() -> String: Returns the users local timezone
• unixtime(dt: DateTime) -> Scalar: Converts a DateTime to a UNIX timestamp.
• from_unixtime(ut: Scalar) -> DateTime: Converts a UNIX timestamp to a DateTime object.
• calendar_add(dt: DateTime, span: Time): Add a span of time to a DateTime object, taking proper calendar arithmetic into accound.
• calendar_sub(dt: DateTime, span: Time): Subtract a span of time from a DateTime object, taking proper calendar arithmetic into accound.
• weekday(dt: DateTime) -> String: Returns the weekday of a DateTime object as a string.
• human(duration: Time) -> String: Converts a Time to a human-readable string in days, hours, minutes and seconds.
• julian_date(dt: DateTime) -> Scalar: Convert a DateTime to a Julian date.

Date time formats

The following formats are supported by datetime. UTC offsets are mandatory for the RFC 3339 and RFC 2822 formats. The other formats can optionally include a time zone name or UTC offset. If no time zone is specified, the local time zone is used.

The date function supports the following formats. It returns a DateTime object with the time set to midnight in the specified timezone (or the local timezone if no timezone is specified).

The time function supports the following formats. It returns a DateTime object with the date set to the current date. If no timezone is specified, the local timezone is used.