Struct Instant

Source

pub struct Instant { /* private fields */ }

Expand description

An instant returned by the fast-time clock.

Represents a specific point in time captured from a Clock. Use this to measure elapsed time or to compare with other instants from the same clock.

You may convert the instant into an std::time::Instant for arithmetic operations and interoperability with standard library code.

§Examples

Basic elapsed time measurement:

use std::time::Duration;

use fast_time::Clock;

let mut clock = Clock::new();
let start = clock.now();

// Simulate some work
std::thread::sleep(Duration::from_millis(10));

let elapsed = start.elapsed(&mut clock);
// Note: fast_time prioritizes efficiency over precision
assert!(elapsed <= Duration::from_secs(1)); // Generous upper bound

Comparing instants:

use fast_time::Clock;

let mut clock = Clock::new();
let instant1 = clock.now();
let instant2 = clock.now();

// instant2 should be later than instant1
assert!(instant2 >= instant1);

let duration = instant2.saturating_duration_since(instant1);
println!("Time between captures: {:?}", duration);

Converting to standard library types:

use std::time::Instant as StdInstant;

use fast_time::Clock;

let mut clock = Clock::new();
let fast_instant = clock.now();

// Convert to std::time::Instant
let std_instant: StdInstant = fast_instant.into();

// Convert back
let converted_back: fast_time::Instant = std_instant.into();

Implementations§

Source §

impl Instant

Source

pub fn elapsed(&self, clock: &mut Clock) -> Duration

Calculates the elapsed time since this instant using the provided clock.

This method captures a new timestamp from the clock and calculates the duration that has passed since this instant was created.

§Examples

use std::time::Duration;

use fast_time::Clock;

let mut clock = Clock::new();
let start = clock.now();

// Simulate some work
std::thread::sleep(Duration::from_millis(5));

let elapsed = start.elapsed(&mut clock);
// Note: fast_time prioritizes efficiency over precision
assert!(elapsed <= Duration::from_secs(1)); // Generous upper bound

Source

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

Calculates the duration since an earlier instant.

Returns the amount of time that passed between the earlier instant and this instant. If the earlier instant is actually later than this instant, returns a duration of zero (saturating behavior).

§Examples

use std::time::Duration;

use fast_time::Clock;

let mut clock = Clock::new();
let start = clock.now();

// Simulate some work
std::thread::sleep(Duration::from_millis(8));

let end = clock.now();
let duration = end.saturating_duration_since(start);
// Note: fast_time prioritizes efficiency over precision
assert!(duration <= Duration::from_secs(1)); // Generous upper bound

Saturating behavior with reversed order:

use std::time::Duration;

use fast_time::Clock;

let mut clock = Clock::new();
let instant1 = clock.now();
let instant2 = clock.now();

// instant1 is earlier, so this returns zero
let duration = instant1.saturating_duration_since(instant2);
assert_eq!(duration, Duration::ZERO);

Source

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

Calculates the duration since an earlier instant.

This is an alias for saturating_duration_since to maintain compatibility with std::time::Instant.

§Examples

use std::time::Duration;

use fast_time::Clock;

let mut clock = Clock::new();
let start = clock.now();
let end = clock.now();

let duration = end.duration_since(start);

Source

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

Calculates the duration since an earlier instant, returning None if the earlier instant is actually later than this instant.

Unlike saturating_duration_since, this method returns None instead of zero when the earlier instant is later.

§Examples

use std::time::Duration;

use fast_time::Clock;

let mut clock = Clock::new();
let start = clock.now();

// Simulate some work to ensure time passes
std::thread::sleep(Duration::from_millis(10));

let end = clock.now();

// Normal case: end should be later than start
match end.checked_duration_since(start) {
    Some(duration) => println!("Elapsed: {:?}", duration),
    None => println!("Time went backwards"),
}

// Test with the same instant - should return Some(Duration::ZERO)
let same_instant = clock.now();
assert_eq!(
    same_instant.checked_duration_since(same_instant),
    Some(Duration::ZERO)
);

Source

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

Adds a duration to this instant, returning None if overflow occurred.

§Examples

use std::time::Duration;

use fast_time::Clock;

let mut clock = Clock::new();
let instant = clock.now();

let later = instant.checked_add(Duration::from_secs(5)).unwrap();
assert!(later > instant);

// This would overflow
assert!(instant.checked_add(Duration::MAX).is_none());

Source

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

Subtracts a duration from this instant, returning None if underflow occurred.

§Examples

use std::time::Duration;

use fast_time::Clock;

let mut clock = Clock::new();
let instant = clock.now();

let earlier = instant.checked_sub(Duration::from_secs(5)).unwrap();
assert!(earlier < instant);

// This would underflow
assert!(instant.checked_sub(Duration::MAX).is_none());