impl SystemTime

const UNIX_EPOCH: SystemTime = UNIX_EPOCH;

An anchor in time which can be used to create new SystemTime instances or learn about where in time a SystemTime lies.

This constant is defined to be "1970-01-01 00:00:00 UTC" on all systems with respect to the system clock. Using duration_since on an existing SystemTime instance can tell how far away from this point in time a measurement lies, and using UNIX_EPOCH + duration can be used to create a SystemTime instance to represent another fixed point in time.

duration_since(UNIX_EPOCH).unwrap().as_secs() returns the number of non-leap seconds since the start of 1970 UTC. This is a POSIX time_t (as a u64), and is the same time representation as used in many Internet protocols.

Examples

use std::time::SystemTime;

match SystemTime::now().duration_since(SystemTime::UNIX_EPOCH) {
    Ok(n) => println!("1970-01-01 00:00:00 UTC was {} seconds ago!", n.as_secs()),
    Err(_) => panic!("SystemTime before UNIX EPOCH!"),
}

const MAX: SystemTime = _;

Represents the maximum value representable by SystemTime on this platform.

This value differs a lot between platforms, but it is always the case that any positive addition of a Duration, whose value is greater than or equal to the time precision of the operating system, to SystemTime::MAX will fail.

Examples

#![feature(time_systemtime_limits)]
use std::time::{Duration, SystemTime};

// Adding zero will change nothing.
assert_eq!(SystemTime::MAX.checked_add(Duration::ZERO), Some(SystemTime::MAX));

// But adding just one second will already fail ...
//
// Keep in mind that this in fact may succeed, if the Duration is
// smaller than the time precision of the operating system, which
// happens to be 1ns on most operating systems, with Windows being the
// notable exception by using 100ns, hence why this example uses 1s.
assert_eq!(SystemTime::MAX.checked_add(Duration::new(1, 0)), None);

// Utilize this for saturating arithmetic to improve error handling.
// In this case, we will use a certificate with a timestamp in the
// future as a practical example.
let configured_offset = Duration::from_secs(60 * 60 * 24);
let valid_after =
    SystemTime::now()
        .checked_add(configured_offset)
        .unwrap_or(SystemTime::MAX);

const MIN: SystemTime = _;

Represents the minimum value representable by SystemTime on this platform.

This value differs a lot between platforms, but it is always the case that any positive subtraction of a Duration from, whose value is greater than or equal to the time precision of the operating system, to SystemTime::MIN will fail.

Depending on the platform, this may be either less than or equal to SystemTime::UNIX_EPOCH, depending on whether the operating system supports the representation of timestamps before the Unix epoch or not. However, it is always guaranteed that a SystemTime::UNIX_EPOCH fits between a SystemTime::MIN and SystemTime::MAX.

Examples

#![feature(time_systemtime_limits)]
use std::time::{Duration, SystemTime};

// Subtracting zero will change nothing.
assert_eq!(SystemTime::MIN.checked_sub(Duration::ZERO), Some(SystemTime::MIN));

// But subtracting just one second will already fail.
//
// Keep in mind that this in fact may succeed, if the Duration is
// smaller than the time precision of the operating system, which
// happens to be 1ns on most operating systems, with Windows being the
// notable exception by using 100ns, hence why this example uses 1s.
assert_eq!(SystemTime::MIN.checked_sub(Duration::new(1, 0)), None);

// Utilize this for saturating arithmetic to improve error handling.
// In this case, we will use a cache expiry as a practical example.
let configured_expiry = Duration::from_secs(60 * 3);
let expiry_threshold =
    SystemTime::now()
        .checked_sub(configured_expiry)
        .unwrap_or(SystemTime::MIN);

fn now() -> SystemTime

Returns the system time corresponding to "now".

Examples

use std::time::SystemTime;

let sys_time = SystemTime::now();

fn duration_since(&self, earlier: SystemTime) -> Result<Duration, SystemTimeError>

Returns the amount of time elapsed from an earlier point in time.

This function may fail because measurements taken earlier are not guaranteed to always be before later measurements (due to anomalies such as the system clock being adjusted either forwards or backwards). Instant can be used to measure elapsed time without this risk of failure.

If successful, [Ok]([Duration]) is returned where the duration represents the amount of time elapsed from the specified measurement to this one.

Returns an Err if earlier is later than self, and the error contains how far from self the time is.

Examples

use std::time::SystemTime;

let sys_time = SystemTime::now();
let new_sys_time = SystemTime::now();
let difference = new_sys_time.duration_since(sys_time)
    .expect("Clock may have gone backwards");
println!("{difference:?}");

fn elapsed(&self) -> Result<Duration, SystemTimeError>

Returns the difference from this system time to the current clock time.

This function may fail as the underlying system clock is susceptible to drift and updates (e.g., the system clock could go backwards), so this function might not always succeed. If successful, [Ok]([Duration]) is returned where the duration represents the amount of time elapsed from this time measurement to the current time.

To measure elapsed time reliably, use Instant instead.

Returns an Err if self is later than the current system time, and the error contains how far from the current system time self is.

Examples

use std::thread::sleep;
use std::time::{Duration, SystemTime};

let sys_time = SystemTime::now();
let one_sec = Duration::from_secs(1);
sleep(one_sec);
assert!(sys_time.elapsed().unwrap() >= one_sec);

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

Returns Some(t) where t is the time self + duration if t can be represented as SystemTime (which means it's inside the bounds of the underlying data structure), None otherwise.

In the case that the duration is smaller than the time precision of the operating system, Some(self) will be returned.

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

Returns Some(t) where t is the time self - duration if t can be represented as SystemTime (which means it's inside the bounds of the underlying data structure), None otherwise.

In the case that the duration is smaller than the time precision of the operating system, Some(self) will be returned.

fn saturating_add(&self, duration: Duration) -> SystemTime

Saturating SystemTime addition, computing self + duration, returning SystemTime::MAX if overflow occurred.

In the case that the duration is smaller than the time precision of the operating system, self will be returned.

fn saturating_sub(&self, duration: Duration) -> SystemTime

Saturating SystemTime subtraction, computing self - duration, returning SystemTime::MIN if overflow occurred.

In the case that the duration is smaller than the time precision of the operating system, self will be returned.

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

Saturating computation of time elapsed from an earlier point in time, returning Duration::ZERO in the case that earlier is later or equal to self.

Examples

#![feature(time_saturating_systemtime)]
use std::time::{Duration, SystemTime};

let now = SystemTime::now();
let prev = now.saturating_sub(Duration::new(1, 0));

// now - prev should return non-zero.
assert_eq!(now.saturating_duration_since(prev), Duration::new(1, 0));
assert!(now.duration_since(prev).is_ok());

// prev - now should return zero (and fail with the non-saturating).
assert_eq!(prev.saturating_duration_since(now), Duration::ZERO);
assert!(prev.duration_since(now).is_err());

// now - now should return zero (and work with the non-saturating).
assert_eq!(now.saturating_duration_since(now), Duration::ZERO);
assert!(now.duration_since(now).is_ok());