Date and time

See this page for a general introduction to date and time handling in Numbat.

Defined in: datetime::functions, datetime::human

now

Returns the current date and time.

fn now() -> DateTime

datetime

Parses a string (date and time) into a DateTime object. See here for an overview of the supported formats.

fn datetime(input: String) -> DateTime

datetime("2022-07-20T21:52+0200")

    = 2022-07-20 19:52:00 UTC    [DateTime]

datetime("2022-07-20 21:52 Europe/Berlin")

    = 2022-07-20 21:52:00 CEST (UTC +02), Europe/Berlin    [DateTime]

datetime("2022/07/20 09:52 PM +0200")

    = 2022-07-20 21:52:00 (UTC +02)    [DateTime]

format_datetime

Formats a DateTime object as a string.

fn format_datetime(format: String, input: DateTime) -> String

format_datetime("This is a date in %B in the year %Y.", datetime("2022-07-20 21:52 +0200"))

    = "This is a date in July in the year 2022."    [String]

get_local_timezone

Returns the users local timezone.

fn get_local_timezone() -> String

get_local_timezone()

    = "UTC"    [String]

tz

Returns a timezone conversion function, typically used with the conversion operator.

fn tz(tz: String) -> Fn[(DateTime) -> DateTime]

datetime("2022-07-20 21:52 +0200") -> tz("Europe/Amsterdam")

    = 2022-07-20 21:52:00 CEST (UTC +02), Europe/Amsterdam    [DateTime]

datetime("2022-07-20 21:52 +0200") -> tz("Asia/Taipei")

    = 2022-07-21 03:52:00 CST (UTC +08), Asia/Taipei    [DateTime]

unixtime

Converts a DateTime to a UNIX timestamp. Can be used on the right hand side of a conversion operator: now() -> unixtime.

fn unixtime(input: DateTime) -> Scalar

datetime("2022-07-20 21:52 +0200") -> unixtime

    = 1_658_346_720

from_unixtime

Converts a UNIX timestamp to a DateTime object.

fn from_unixtime(input: Scalar) -> DateTime

from_unixtime(2^31)

    = 2038-01-19 03:14:08 UTC    [DateTime]

today

Returns the current date at midnight (in the local time).

fn today() -> DateTime

date

Parses a string (only date) into a DateTime object.

fn date(input: String) -> DateTime

date("2022-07-20")

    = 2022-07-20 00:00:00 UTC    [DateTime]

time

Parses a string (time only) into a DateTime object.

fn time(input: String) -> DateTime

calendar_add

Adds the given time span to a DateTime. This uses leap-year and DST-aware calendar arithmetic with variable-length days, months, and years.

fn calendar_add(dt: DateTime, span: Time) -> DateTime

calendar_add(datetime("2022-07-20 21:52 +0200"), 2 years)

    = 2024-07-20 21:52:00 (UTC +02)    [DateTime]

calendar_sub

Subtract the given time span from a DateTime. This uses leap-year and DST-aware calendar arithmetic with variable-length days, months, and years.

fn calendar_sub(dt: DateTime, span: Time) -> DateTime

calendar_sub(datetime("2022-07-20 21:52 +0200"), 3 years)

    = 2019-07-20 21:52:00 (UTC +02)    [DateTime]

weekday

Get the day of the week from a given DateTime.

fn weekday(dt: DateTime) -> String

weekday(datetime("2022-07-20 21:52 +0200"))

    = "Wednesday"    [String]

julian_date (Julian date)

Convert a DateTime to a Julian date, the number of days since the origin of the Julian date system (noon on November 24, 4714 BC in the proleptic Gregorian calendar). More information here.

fn julian_date(dt: DateTime) -> Time

julian_date(datetime("2022-07-20 21:52 +0200"))

    = 2.45978e+6 day    [Time]

human (Human-readable time duration)

Converts a time duration to a human-readable string in days, hours, minutes and seconds. More information here.

fn human(time: Time) -> String

century/1e6 -> human

    = "52 minutes + 35.693 seconds"    [String]