Skip to content

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

Example

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

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

Example

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

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

Example

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

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

format_datetime

Formats a DateTime object as a string.

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

Example

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]
Run this example

get_local_timezone

Returns the users local timezone.

fn get_local_timezone() -> String

Example

get_local_timezone()

    = "UTC"    [String]
Run this example

tz

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

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

Example

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

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

Example

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

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

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

Example

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

    = 1_658_346_720
Run this example

from_unixtime

Converts a UNIX timestamp to a DateTime object.

fn from_unixtime(input: Scalar) -> DateTime

Example

from_unixtime(2^31)

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

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

Example

date("2022-07-20")

    = 2022-07-20 00:00:00 UTC    [DateTime]
Run this example

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

Example

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

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

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

Example

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

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

weekday

Get the day of the week from a given DateTime.

fn weekday(dt: DateTime) -> String

Example

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

    = "Wednesday"    [String]
Run this example

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

Example

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

    = 2.45978e+6 day    [Time]
Run this example

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

How long is a microcentury?

century/1e6 -> human

    = "52 minutes + 35.693 seconds"    [String]
Run this example