Struct Moment

pub struct Moment { /* private fields */ }

A precise moment in time.

A Moment has no concept of a particular time zone or calendar. It represents a single point in time that can be globally agreed upon.

Internally, moments are represented in the Coordinated Universal Time (UTC) time scale as the signed number of seconds and sub-second nanoseconds since the Unix epoch at January 1, 1970. A positive number of seconds indicates a moment after the Unix epoch where a negative number of seconds indicates a moment before the Unix epoch.

A Moment can be created from and displayed as a RFC 3339 string like 2018-02-15T03:41:23Z with the FromStr and Display traits.

Interoperability

The Moment type can be created from and converted to many representations of exact time and other time scales, such as Unix time, a Julian day, or RFC 3339.^†

^†_{Please feel free to open an issue requesting additional representations for conversion to and from.}

Unix Time

Unix time is widely used as a storage and transmission format for date and time. It is the count of non-leap seconds from January 1, 1970, at 00:00:00 UTC.

Create a Moment from a Unix time, in milliseconds

use ako::Moment;

let moment = Moment::from_unix_milliseconds(1727597174768);

assert_eq!(moment.to_string(), "2024-09-29T08:06:14.768000000Z");

Get the current time as a Unix timestamp

use ako::Moment;

// secs is the number of seconds since the Unix epoch
// nsec is the sub-second nanoseconds
let (secs, nsec) = Moment::now().to_unix();

SystemTime (std)

Moment and std::time::SystemTime can be freely converted between each other.

Get a value of SystemTime from RFC 3339

use std::time::SystemTime;
use ako::Moment;

let moment: Moment = "2018-02-15T03:41:23Z".parse()?;
let system = SystemTime::from(moment);

Create a Moment from the current system time

use std::time::SystemTime;
use ako::Moment;

let now: Moment = SystemTime::now().into();

This is what Moment::now() does internally.

Implementations

impl Moment

pub const MAX: Self

The maximum supported Moment, +1587287-03-17T15:30:07.999999999Z.

Examples

use ako::Moment;

assert_eq!(Moment::MAX.to_unix_seconds(), i64::MAX);

pub const MIN: Self

The minimum (the largest negative) supported Moment, -1583348-10-16T08:29:52Z.

Examples

use ako::Moment;

assert_eq!(Moment::MIN.to_unix_seconds(), i64::MIN);

impl Moment

pub fn now() -> Self

Available on crate feature std only.

Returns the moment corresponding to “now.”

Examples

use ako::Moment;

// Current moment as reported by the system
let now = Moment::now();

impl Moment

pub const fn from_unix(seconds: i64, nanoseconds: u32) -> Self

Creates a Moment from the given number of seconds and nanoseconds since the Unix epoch of January 1, 1970, at 00:00:00 UTC.

Allows for an out-of-range nanoseconds value to be passed in. The nanoseconds will overflow into seconds to ensure that the stored sub-second nanoseconds are in the range 0 to 999,999,999.

pub const fn from_unix_seconds(seconds: i64) -> Self

Creates a Moment from the given number of seconds since the Unix epoch of January 1, 1970, at 00:00:00 UTC.

Examples

use ako::Moment;

// first appearance of the gregorian date represented by the
// Unix timestamp to be in the timestamp
let date_in_timestamp = Moment::from_unix_seconds(1_1973_10_17);
assert_eq!(date_in_timestamp.to_string(), "1973-10-17T18:36:57Z");

pub const fn from_unix_milliseconds(milliseconds: i64) -> Self

Creates a Moment from the given number of milliseconds since the Unix epoch of January 1, 1970, at 00:00:00 UTC.

pub const fn from_unix_microseconds(microseconds: i128) -> Self

Creates a Moment from the given number of microseconds since the Unix epoch of January 1, 1970, at 00:00:00 UTC.

pub const fn from_unix_nanoseconds(nanoseconds: i128) -> Self

Creates a Moment from the given number of nanoseconds since the Unix epoch of January 1, 1970, at 00:00:00 UTC.

pub fn from_julian_day(jd: f64) -> Result<Self, Error>

Available on crate feature astronomy only.

Creates a Moment corresponding to the given Julian day (JD).

The Julian day is the continuous count of days and fractions thereof from the beginning of the Julian period, where day 0 is Monday, January 1, 4713 BCE of the Julian calendar.

pub fn from_julian_ephemeris_day(jde: f64) -> Result<Self, Error>

Available on crate feature astronomy only.

Creates a Moment corresponding to the given Julian day (JD) in the Dynamical timescale (also known as Ephemeris time).

impl Moment

pub const fn to_unix(self) -> (i64, u32)

Gets the number of seconds and nanoseconds since the Unix epoch. Negative seconds represent moments before the Unix epoch.

pub const fn to_unix_seconds(self) -> i64

Gets the number of seconds since the Unix epoch. Negative seconds represent moments before the Unix epoch.

pub const fn to_unix_milliseconds(self) -> i64

Gets the number of milliseconds since the Unix epoch.

pub const fn to_unix_microseconds(self) -> i64

Gets the number of microseconds since the Unix epoch.

pub const fn to_unix_nanoseconds(self) -> i128

Gets the number of nanoseconds since the Unix epoch.

pub fn to_julian_day(self) -> f64

Available on crate feature astronomy only.

Gets the Julian day (JD) for this moment.

pub fn to_julian_year(self) -> f64

Available on crate feature astronomy only.

Gets the Julian year (a) for this moment.

In astronomy, a Julian year (a) is a unit of measurement of time defined as exactly 365.25 days of 86,400 seconds each. The Julian year does not correspond to years in any calendar.

impl Moment

pub fn format_rfc3339(self) -> String

Formats this moment, according to the RFC 3339 and ISO-8601 standards.

Examples

let epoch = Moment::from_unix_seconds(0).format_rfc3339();

assert_eq!(epoch, "1970-01-01T00:00:00Z");

impl Moment

pub fn parse_rfc3339<S: AsRef<str>>(s: S) -> Result<Self, Error>

Parses a moment, according to the RFC 3339 and ISO-8601 standards.

Trait Implementations

impl Add<Duration> for Moment

type Output = Moment

The resulting type after applying the + operator.

fn add(self, rhs: Duration) -> Self::Output

Performs the + operation.

impl Add<Moment> for Duration

type Output = Moment

The resulting type after applying the + operator.

fn add(self, rhs: Moment) -> Self::Output

Performs the + operation.

impl Clone for Moment

fn clone(&self) -> Moment

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Moment

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

Formats the value using the given formatter.

impl Display for Moment

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

Formats the value using the given formatter.

impl From<Moment> for SystemTime

Available on crate feature std only.

fn from(moment: Moment) -> Self

Converts to this type from the input type.

impl From<SystemTime> for Moment

Available on crate feature std only.

fn from(time: SystemTime) -> Self

Converts to this type from the input type.

impl FromStr for Moment

type Err = Error

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl Hash for Moment

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 Moment

fn cmp(&self, other: &Moment) -> 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 Moment

fn eq(&self, other: &Moment) -> 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 Moment

fn partial_cmp(&self, other: &Moment) -> 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 Sub<Duration> for Moment

type Output = Moment

The resulting type after applying the - operator.

fn sub(self, rhs: Duration) -> Self::Output

Performs the - operation.

impl Sub for Moment

type Output = TimeInterval

The resulting type after applying the - operator.

fn sub(self, rhs: Self) -> Self::Output

Performs the - operation.

impl Copy for Moment

impl Eq for Moment

impl StructuralPartialEq for Moment