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::unixtime, datetime::human, datetime::julian_date

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

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

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) -> UnixTime

Example

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

    = 1_658_346_720 unix_s    [UnixTime]
Run this example

unixtime_s

Converts a DateTime to a UNIX timestamp in seconds.

fn unixtime_s(input: DateTime) -> Scalar

Example

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

    = 1_658_346_720
Run this example

unixtime_ms

Converts a DateTime to a UNIX timestamp in milliseconds.

fn unixtime_ms(input: DateTime) -> Scalar

Example

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

    = 1_658_346_725_123
Run this example

unixtime_µs

Converts a DateTime to a UNIX timestamp in microseconds.

fn unixtime_µs(input: DateTime) -> Scalar

Example

datetime("2022-07-20 21:52:05.123456 +0200") -> unixtime_µs

    = 1_658_346_725_123_456
Run this example

unixtime_us

Alias for unixtime_µs.

fn unixtime_us(input: DateTime) -> Scalar

from_unixtime

Converts a UNIX timestamp to a DateTime object.

fn from_unixtime(input: UnixTime) -> DateTime

Example

from_unixtime(1658346725 unix_s)

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

Example

from_unixtime(1658346725000 unix_ms)

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

Example

from_unixtime(1658346725000000 unix_µs)

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

from_unixtime_s

Converts a UNIX timestamp in seconds to a DateTime object.

fn from_unixtime_s(input: Scalar) -> DateTime

Example

from_unixtime_s(1658346725)

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

from_unixtime_ms

Converts a UNIX timestamp in milliseconds to a DateTime object.

fn from_unixtime_ms(input: Scalar) -> DateTime

Example

from_unixtime_ms(1658346725123)

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

from_unixtime_µs

Converts a UNIX timestamp in microseconds to a DateTime object.

fn from_unixtime_µs(input: Scalar) -> DateTime

Example

from_unixtime_µs(1658346725123456)

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

from_unixtime_us

Alias for from_unixtime_µs.

fn from_unixtime_us(input: Scalar) -> DateTime

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

julian_date (Convert DateTime to 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

datetime("2013-01-01 00:30:00 UTC") -> julian_date

    = 212_223_760_200 s    [Time]
Run this example

from_julian_date (Convert Julian date to DateTime)

Convert a Julian date to a DateTime. More information here.

fn from_julian_date(jd: Time) -> DateTime

Example

from_julian_date(2_456_293.520_833 days)

    = 2013-01-01 00:29:59 UTC    [DateTime]
Run this example