Struct Instant

Source

pub struct Instant { /* private fields */ }

Expand description

An absolute point in time.

An Instant is a wrapper around a signed integer that holds the number of nanoseconds since an arbitrary point in time, e.g. system startup.

A value of 0 is arbitrary.
Values < 0 indicate a time before the start point.

Implementations§

Source §

impl Instant

Source

pub const ZERO: Instant

The zero Instant.

An arbitrary point on the absolute timescale.

Source

pub fn from_nanos(nanos: i64) -> Instant

Construct an Instant from a number of nanoseconds.

§Examples

let instant = Instant::from_nanos(1_234_567_890);
assert_eq!(instant.as_nanos(), 1_234_567_890);

Source

pub const fn as_nanos(&self) -> i64

The number of nanoseconds that have passed since the ZERO point.

Source

pub const fn secs(&self) -> i64

The number of whole seconds since the ZERO point.

Source

pub const fn subsec_nanos(&self) -> i64

The number of fractional nanoseconds since the ZERO point.

Source

pub fn duration_since(&self, earlier: Instant) -> Duration

The amount of time elapsed since an earlier Instant, or 0.

§Examples

let earlier = Instant::from_nanos(1_234_567_890);
let later = Instant::from_nanos(2_234_567_890);
assert_eq!(later.duration_since(earlier), Duration::from_nanos(1_000_000_000));
assert_eq!(earlier.duration_since(later), Duration::ZERO);
assert_eq!(earlier.duration_since(earlier), Duration::ZERO);

Source

pub fn checked_duration_since(&self, earlier: Instant) -> Option<Duration>

The amount of time elapsed since an earlier Instant, or None.

§Examples

let earlier = Instant::from_nanos(1_234_567_890);
let later = Instant::from_nanos(2_234_567_890);
assert_eq!(later.checked_duration_since(earlier), Some(Duration::from_nanos(1_000_000_000)));
assert_eq!(earlier.checked_duration_since(later), None);
assert_eq!(earlier.checked_duration_since(earlier), Some(Duration::ZERO));

Source

pub fn saturating_duration_since(&self, earlier: Instant) -> Duration

The amount of time elapsed since an earlier Instant, or 0.

Source

pub fn checked_add(&self, duration: Duration) -> Option<Instant>

Returns the result of self + duration if the result can be represented by the underlying data structure, None otherwise.

§Examples

let instant = Instant::from_nanos(1_234_567_890);
assert_eq!(instant.checked_add(Duration::from_secs(1)), Some(Instant::from_nanos(2_234_567_890)));
assert_eq!(instant.checked_add(Duration::ZERO), Some(instant));

Source

pub fn checked_sub(&self, duration: Duration) -> Option<Instant>

Returns the result of self - duration if the result can be represented by the underlying data structure, None otherwise.

§Examples

let instant = Instant::from_nanos(1_234_567_890);
assert_eq!(instant.checked_sub(Duration::from_secs(1)), Some(Instant::from_nanos(234_567_890)));
assert_eq!(instant.checked_sub(Duration::from_secs(2)), Some(Instant::from_nanos(-765_432_110)));
assert_eq!(instant.checked_sub(Duration::ZERO), Some(instant));

Source

pub fn from_std(instant: Instant) -> Instant

Construct an Instant from a std::time::Instant based on its the elapsed time.

Can be used if you have a base std::time::Instant where you can create Instants as needed.

In this usage, the base std::time::Instant is mapped to Instant::ZERO and Instant values represent the distance from the base std::time::Instant.

§Example

let std_instant = std::time::Instant::now();
std::thread::sleep(Duration::from_secs(1));
assert!(Instant::from_std(std_instant) >= Instant::from_nanos(1_000_000_000));

Source

pub fn from_system_elapsed( sys_time: SystemTime, ) -> Result<Instant, SystemTimeError>

Construct an Instant from a std::time::SystemTime based on its the elapsed time.

Can be used if you have a base std::time::SystemTime where you can create Instants as needed.

In this usage, the base std::time::SystemTime is mapped to Instant::ZERO and Instant values represent the distance from the base std::time::SystemTime.

§Example

let sys_time = std::time::SystemTime::now();
std::thread::sleep(Duration::from_secs(1));
assert!(Instant::from_system_elapsed(sys_time).unwrap() >= Instant::from_nanos(1_000_000_000));

Source

pub fn from_system_unix_epoch(sys_time: SystemTime) -> Instant

Construct an Instant from a std::time::SystemTime based on the distance from the unix epoch.

In this usage, the base std::time::UNIX_EPOCH is mapped to Instant::ZERO and Instant values represent the distance from the base std::time::UNIX_EPOCH.

§Example

let sys_time = std::time::SystemTime::now();
assert!(Instant::from_system_unix_epoch(sys_time) >= Instant::from_nanos(0));

Source

pub fn to_std(&self, base_instant: Instant) -> Instant

Convert this Instant to a std::time::Instant using a base instant.

This function takes a base std::time::Instant and adds the duration represented by this Instant to create a corresponding std::time::Instant.

In this usage, the base std::time::Instant is mapped to Instant::ZERO and Instant values represent the distance from the base std::time::Instant.

§Example

let base = std::time::Instant::now();
let instant = Instant::from_nanos(1_000_000_000); // 1 second
let std_instant = instant.to_std(base);

// The resulting std_instant should be 1 second after base
assert!(std_instant.duration_since(base) == Duration::from_secs(1));

Source

pub fn to_system(&self, base_system_time: SystemTime) -> SystemTime

Convert this Instant to a std::time::SystemTime using a base system time.

This function takes a base std::time::SystemTime and adds the duration represented by this Instant to create a corresponding std::time::SystemTime.

If the Instant was created with Instant::from_system_unix_epoch then the base std::time::SystemTime should be std::time::UNIX_EPOCH. Otherwise, the base std::time::SystemTime should be the same value passed in to Instant::from_system_elapsed.

§Example

let base = std::time::SystemTime::now();
let instant = Instant::from_nanos(1_000_000_000); // 1 second
let sys_time = instant.to_system(base);

// The resulting sys_time should be 1 second after base
assert!(sys_time.duration_since(base).unwrap() == Duration::from_secs(1));