Struct UTCDatetime

pub struct UTCDatetime { /* private fields */ }

UTC Datetime.

A UTC Datetime consists of a date component and a time-of-day component with nanosecond resolution.

Examples

use utc_dt::time::UTCTimeOfDay;
use utc_dt::date::UTCDate;
use utc_dt::UTCDatetime;

// UTC Time of Day from a time measurement (for secs, millis, micros, nanos)
let utc_tod = UTCTimeOfDay::try_from_millis(37088903).unwrap();
// UTC Date directly from components
let utc_date = UTCDate::try_from_components(2023, 6, 15).unwrap(); // OR

// UTC Datetime from date and time-of-day components
let utc_datetime = UTCDatetime::from_components(utc_date, utc_tod);
// Get date and time-of-day components
let (utc_date, time_of_day_ns) = (utc_datetime.as_date(), utc_datetime.as_tod()); // OR
let (utc_date, time_of_day_ns) = utc_datetime.as_components();
// Parse a UTC Datetime from an ISO 8601 datetime string `(YYYY-MM-DDThh:mm:ssZ)`
let utc_datetime = UTCDatetime::try_from_iso_datetime("2023-06-15T10:18:08.903Z").unwrap();
// Get UTC datetime string formatted according to ISO 8601 `(YYYY-MM-DDThh:mm:ssZ)`
const PRECISION_SECONDS: usize = 0;
let iso_datetime = utc_datetime.as_iso_datetime(PRECISION_SECONDS);
assert_eq!(iso_datetime, "2023-06-15T10:18:08Z");
// Write ISO 8601 datetime str to a stack buffer
let mut buf = [0; UTCDatetime::iso_datetime_len(PRECISION_SECONDS)];
let _bytes_written = utc_datetime.write_iso_datetime(&mut buf, PRECISION_SECONDS).unwrap();
let iso_datetime_str = core::str::from_utf8(&buf).unwrap();
assert_eq!(iso_datetime_str, "2023-06-15T10:18:08Z");

Implementations

impl UTCDatetime

pub const MIN: UTCDatetime

The minimum UTC datetime.

Equivalent to the unix epoch, 1970.

pub const MAX: UTCDatetime

The maximum UTC datetime.

Equal to November 9, 584_554_051_223, T07:00:15.999999999Z.

Maximum datetime support is limited by the maximum UTCTimestamp. UTCDatetime can physically store dates up to December 31, 1_717_986_918_399, T23:59:59.999999999Z

pub const MIN_ISO_DATETIME_LEN: usize = 20usize

The minimum length of an ISO datetime (in UTF8 characters)

pub const fn from_components(date: UTCDate, tod: UTCTimeOfDay) -> Self

Create a datetime frome date and time-of-day components.

pub const fn as_components(&self) -> (UTCDate, UTCTimeOfDay)

Get copy of the internal date and time-of-day components

Returns tuple: (date: UTCDate, tod: UTCTimeOfDay)

pub const fn to_components(self) -> (UTCDate, UTCTimeOfDay)

Consume self into the internal date and time-of-day components

Returns tuple: (date: UTCDate, tod: UTCTimeOfDay)

pub const fn as_date(&self) -> UTCDate

Get the internal date component.

pub const fn as_tod(&self) -> UTCTimeOfDay

Get the internal time-of-day component.

pub fn try_from_iso_datetime(iso: &str) -> Result<Self, UTCDatetimeError>

Try parse datetime from str in the format:

• YYYY-MM-DDThh:mm:ssZ or
• YYYY-MM-DDThh:mm:ss.nnnZ

Decimal precision of up to 9 places (inclusive) supported.

Conforms to ISO 8601: https://www.w3.org/TR/NOTE-datetime

pub fn as_iso_datetime(&self, precision: usize) -> String

Return datetime as a string in the format:

• Precision = 0: YYYY-MM-DDThh:mm:ssZ
• Precision = 3: YYYY-MM-DDThh:mm:ss.nnnZ

If precision denotes the number decimal places included after the seconds, limited to 9 decimal places (nanosecond precision). If 0, no decimal component is included.

Conforms to ISO 8601: https://www.w3.org/TR/NOTE-datetime

pub fn write_iso_datetime( &self, buf: &mut [u8], precision: usize, ) -> Result<usize, UTCDatetimeError>

Write an ISO datetime to a buffer in the format:

• Precision = 0: YYYY-MM-DDThh:mm:ssZ
• Precision = 3: YYYY-MM-DDThh:mm:ss.nnnZ

The buffer should have a minimum length as given by UTCDatetime::iso_datetime_len.

A buffer of insufficient length will error (UTCDatetimeError::InsufficientStrLen).

Returns number of UTF8 characters (bytes) written

Conforms to ISO 8601: https://www.w3.org/TR/NOTE-datetime

pub const fn iso_datetime_len(precision: usize) -> usize

Calculate the number of characters in an ISO datetime str

Trait Implementations

impl Clone for UTCDatetime

fn clone(&self) -> UTCDatetime

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for UTCDatetime

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for UTCDatetime

fn default() -> UTCDatetime

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for UTCDatetime

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for UTCDatetime

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<Duration> for UTCDatetime

fn from(duration: Duration) -> Self

Converts to this type from the input type.

impl From<UTCTimestamp> for UTCDatetime

fn from(timestamp: UTCTimestamp) -> Self

Converts to this type from the input type.

impl Hash for UTCDatetime

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for UTCDatetime

fn cmp(&self, other: &UTCDatetime) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for UTCDatetime

fn eq(&self, other: &UTCDatetime) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for UTCDatetime

fn partial_cmp(&self, other: &UTCDatetime) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Serialize for UTCDatetime

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl UTCTransformations for UTCDatetime

fn from_timestamp(timestamp: UTCTimestamp) -> Self

Create from a UTC timestamp.

fn as_timestamp(&self) -> UTCTimestamp

Convert to a UTC timestamp.

fn from_duration(duration: Duration) -> Self

Create from a duration measured from the Unix Epoch.

fn as_duration(&self) -> Duration

Convert to a duration measured from the Unix Epoch.

fn from_secs(secs: u64) -> Self

Create from seconds measured from the Unix Epoch.

fn as_secs(&self) -> u64

Convert to seconds measured from the Unix Epoch.

fn from_millis(millis: u64) -> Self

Create from milliseconds measured from the Unix Epoch.

fn as_millis(&self) -> u128

Convert to milliseconds measured from the Unix Epoch.

fn from_micros(micros: u64) -> Self

Create from microseconds measured from the Unix Epoch.

fn as_micros(&self) -> u128

Convert to microseconds measured from the Unix Epoch.

fn from_nanos(nanos: u64) -> Self

Create from nanoseconds measured from the Unix Epoch.

fn as_nanos(&self) -> u128

Convert to nanoseconds measured from the Unix Epoch.

fn try_from_system_time() -> Result<Self, SystemTimeError>

Create from local system time

impl Copy for UTCDatetime

impl Eq for UTCDatetime

impl StructuralPartialEq for UTCDatetime