Skip to main content
Version: edge

datetime

Support for parsing date strings to nanosecond timestamps and formatting nanosecond timestamps into strings and more.

The submodule timezones contains constants for each existing timezone in the IANA timezone database. The submodule formats contains constants commonly used formats.

In this module we introduce a type called datetime.

It is either:

  • a simple integer timestamp which is interpreted as UTC nanosecond precision timestamp since epoch or

  • a record with the following fields:

    • timestamp: a UTC nanosecond precision timestamp since epoch
    • tz: a timezone identifier from the std::datetime::timezones module or a string with a timezone name or a fixed offset

    It can be conveniently created and adapted with the with_timezone function.

Functions​

day_of_month(datetime)​

Extract the day of the month starting from 1

use std::datetime;
datetime::day_of_month(0) == 1

day_of_year(datetime)​

Extract the day of the year starting from 1

use std::datetime;
datetime::day_of_year(0) == 1

format(datetime, format)​

Formats the given nanosecond timestamp or datetime struct (created with datetime::with_timezone) according to the given format.

Check this documentation from the Rust chrone datetime library on supported format specifiers. It is also possible to chose formats from the std::datetime::formats module.

datetime::format(datetime::with_timezone(123, datetime::timezones::EUROPE_BERLIN), "%Y-%m-%dT%H:%M:%S%:z") == "1970-01-01T01:00:00:+01:00"

hour(datetime)​

Extract the hour number of the day starting from 0

Returns an integer in the range of 0 to 23

use std::datetime;
datetime::hour(0) == 0

iso_week(datetime)​

Extract the ISO week number starting from 1

use std::datetime;
datetime::iso_week(0) == 1

minute(datetime)​

Extract the minute number of the day starting from 0

Returns an integer in the range of 0 to 59

use std::datetime;
datetime::minute(0) == 0

month(datetime)​

Extract the month number starting from 1

use std::datetime;
datetime::month(0) == 1

parse(string, format)​

Parse the given datetime string according to the given format into a nanosecond timestamp since epoch UTC

Check this documentation from the Rust chrone datetime library on supported format specifiers. It is also possible to chose formats from the std::datetime::formats module.

This function errors if the given string cannot be parsed according to the given format. If successful this function returns a 64-bit integer.

Usage:

let nanos = datetime::parse(event.datetime, datetime::formats::RFC3339);

rfc2822(datetime)​

Formats the given datetime according to RFC 2822

Returns a string.

rfc3339(datetime)​

Formats the given datetime according to RFC 3339

Returns a string.

use std::datetime;
datetime::rfc3339(1667997961)

second(datetime)​

Extract the second number of the day starting from 0

Returns an integer in the range of 0 to 59

use std::datetime;
datetime::second(0) == 0

subsecond_micros(datetime)​

Extract the number of microseconds since the last full second

For turning a timestamp into microseconds use std::time::nanos::to_micros.

Returns an integer

use std::datetime;
datetime::subsecond_micros(1_000_000) == 1_000

subsecond_millis(datetime)​

Extract the number of milliseconds since the last full second.

For turning a timestamp into milliseconds use std::time::nanos::to_millis.

Returns an integer

use std::datetime;
datetime::subsecond_millis(1_000_000) == 1

subsecond_nanos(datetime)​

Extract the number of nanoseconds since the last full second

This is not the number of milliseconds since epoch.

Returns an integer

use std::datetime;
datetime::subsecond_nanos(1_000_000) == 1_000_000

with_timezone(utc_nanos, timezone)​

Turn the given utc_nanos into a full datetime with the given timezone. For use in other functions of this module.

Provide a const timezone identifier from the std::datetime::timezones module or a string with timezone name or fixed offset

Returns a record with timestamp and tz fields. This function errors if the timezone is invalid.

year(datetime)​

Extract the year number in in the calendar date according to the proleptic Gregorian calendar.

use std::datetime;
datetime::year(0)  == 1970