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. Julian calendar dates are currently not supported.

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

# Which date is 40 days from now?
now() + 40 days

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

# 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

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

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

# How long are one million seconds in 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.
• human(duration: Time) -> String: Converts a Time to a human-readable string in days, hours, minutes and seconds

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.