Trait SaturatingTime 

pub trait SaturatingTime: SaturatingTime {
    // Provided methods
    fn max_value() -> Self { ... }
    fn min_value() -> Self { ... }
    fn saturating_add(self, duration: Duration) -> Self { ... }
    fn saturating_sub(self, duration: Duration) -> Self { ... }
    fn saturating_duration_since(&self, earlier: Self) -> Duration { ... }
}

The core trait of this crait, SaturatingTime.

This trait provides methods for performing saturating arithmetic on those types in std::time that not already come with such a functionality, such as SystemTime or Instant.

The trait itself is not implementable from the outside, because it is sealed by an internal trait.

See the methods or the top-level documentation for concrete code examples.

Provided Methods

fn max_value() -> Self

Returns the maximum value for this type on the current platform.

This limit is highly platform specific. It differs heavily between Unix, Windows, and other operating systems.

The limit itself is calculated dynamically during runtime with a correct algorithm. Afterwards, it gets stored in a lazy static value, meaning that only the first call to it will be slightly more expensive, whereas all latter calls will result in an immediate return of the value.

Examples

use std::time::{Duration, SystemTime};
use saturating_time::SaturatingTime;

let max = SystemTime::max_value();

// Adding zero to the maximum value will change nothing.
assert!(max.checked_add(Duration::ZERO).is_some());

// Adding 1ns to the maximum value will fail.
assert!(max.checked_add(Duration::new(0, 1)).is_none());

// Subtracting 1ns from the maximum value will work of course.
assert!(max.checked_sub(Duration::new(0, 1)).is_some());

fn min_value() -> Self

Returns the minimum value for this type on the current platform.

This limit is highly platform specific. It differs heavily between Unix, Windows, and other operating systems.

The limit itself is calculated dynamically during runtime with a correct algorithm. Afterwards, it gets stored in a lazy static value, meaning that only the first call to it will be slightly more expensive, whereas all latter calls will result in an immediate return of the value.

Examples

use std::time::{Duration, SystemTime};
use saturating_time::SaturatingTime;

let min = SystemTime::min_value();

// Subtracting a zero from the minimum value will change nothing.
assert!(min.checked_sub(Duration::ZERO).is_some());

// Subtracting 1ns from the minimum value will fail.
assert!(min.checked_sub(Duration::new(0, 1)).is_none());

// Adding 1ns to the minimum value will work of course.
assert!(min.checked_add(Duration::new(0, 1)).is_some());

fn saturating_add(self, duration: Duration) -> Self

Performs a saturating addition of a Duration.

The resulting value will saturate to SaturatingTime::max_value() in the case the addition would have caused an overflow of value.

Examples

use std::time::{Duration, SystemTime};
use saturating_time::SaturatingTime;

let max = SystemTime::max_value();

// Adding zero will change nothing.
assert_eq!(max.saturating_add(Duration::ZERO), max);

// Adding 1ns would overflow so we saturate to the maximum.
assert_eq!(max.saturating_add(Duration::new(0, 1)), max);

fn saturating_sub(self, duration: Duration) -> Self

Performs a saturating subtraction of a Duration.

The resulting value will saturate to SaturatingTime::min_value() in the case the subtraction would have caused an overflow of value.

Examples

use std::time::{Duration, SystemTime};
use saturating_time::SaturatingTime;

let min = SystemTime::min_value();

// Subtracting zero will change nothing.
assert_eq!(min.saturating_sub(Duration::ZERO), min);

// Subtracting 1ns would overflow so we saturate to the minimum.
assert_eq!(min.saturating_sub(Duration::new(0, 1)), min);

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

Performs a saturating time difference calculation between two points.

The resulting value will saturate to Duration::ZERO in the case that the earlier point in time is actually not earlier, thereby resulting in a negative difference.

Examples

use std::time::{Duration, SystemTime};
use saturating_time::SaturatingTime;

let epoch = SystemTime::UNIX_EPOCH;
let now = SystemTime::now();
let min = SystemTime::min_value();

assert!(now.saturating_duration_since(epoch).as_secs() > 0);
assert!(epoch.saturating_duration_since(epoch) == Duration::ZERO);
assert!(min.saturating_duration_since(epoch) == Duration::ZERO);

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementations on Foreign Types

impl SaturatingTime for Instant

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

impl SaturatingTime for SystemTime

Implementors