std::time

Duration and SystemTime arithmetic with fixed instants from UNIX_EPOCH. Examples do not print the current clock or a measured elapsed time.

テーマページの本文は現在英語です。

The std::time module provides Duration, a signed-free span of time, and SystemTime, a point on the system clock. These examples only use fixed Duration values and SystemTime instants derived from UNIX_EPOCH with checked_add. They do not call SystemTime::now or Instant::now, and they do not print a measured elapsed time, because those results depend on the clock.

Instant is the monotonic type intended for measuring intervals. This page does not use it in examples, because constructing a usable Instant still goes through Instant::now. The Debug form of Duration, such as 3.5s, was measured with rustc 1.90.0.

Examples were compiled with rustc 1.90.0 using --edition=2024 and run as a plain binary. See the Rust 1.90.0 documentation for the complete API.

Rust reference overview →

API index

APISummary
Duration::from_secs, Duration::from_millis, Duration::checked_add, Duration::saturating_add, Duration::checked_subBuild a Duration and add or subtract it with checked or saturating arithmetic. These helpers do not read the system clock.
SystemTime::checked_add, SystemTime::duration_since, UNIX_EPOCH, SystemTimeError::durationOffset UNIX_EPOCH by a fixed Duration and compare two instants. Do not use now() when the output must be deterministic.

Duration

Duration::from_secs and from_millis build a span. Adding 1 second to 2500 milliseconds yields a duration whose Debug form is 3.5s on rustc 1.90.0. as_secs of that 2500-millisecond value is 2, because it truncates toward zero; as_millis is 2500. checked_add returns None if the sum would overflow Duration::MAX. saturating_add clamps to MAX. checked_sub returns None if the subtraction would underflow.

Duration::from_secs, Duration::from_millis, Duration::checked_add, Duration::saturating_add, Duration::checked_sub

pub const fn from_secs(secs: u64) -> Duration
pub const fn from_millis(millis: u64) -> Duration
pub const fn as_secs(&self) -> u64
pub const fn as_millis(&self) -> u128
pub const fn checked_add(self, rhs: Duration) -> Option<Duration>
pub const fn saturating_add(self, rhs: Duration) -> Duration
pub const fn checked_sub(self, rhs: Duration) -> Option<Duration>

Build a Duration and add or subtract it with checked or saturating arithmetic. These helpers do not read the system clock.

ParameterDescription
secs / millisNon-negative counts used to construct a Duration. as_secs and as_millis then read those units back; as_secs truncates a fractional second.
rhsThe Duration to add or subtract. Overflow and underflow are reported, not wrapped, by the checked methods.

Returns: from_secs and from_millis return a Duration. as_secs returns u64. as_millis returns u128. checked_add and checked_sub return Option; saturating_add always returns a Duration.

  • The Debug output 3.5s was measured with rustc 1.90.0. Duration does not implement Display on this version.
rust
use std::time::Duration;

fn main() {
    let one = Duration::from_secs(1);
    let two = Duration::from_millis(2500);
    println!("{:?}", one + two);
    println!("{} {}", two.as_secs(), two.as_millis());
    println!("{:?}", Duration::MAX.checked_add(one));
    println!("{}", Duration::MAX.saturating_add(one) == Duration::MAX);
    println!("{:?}", one.checked_sub(Duration::from_secs(2)));
}

Expected output

3.5s
2 2500
None
true
None

Official documentation →

SystemTime and UNIX_EPOCH

UNIX_EPOCH is a fixed SystemTime. checked_add returns a later instant without reading the current clock. duration_since(start) on that later instant is Ok(5s) in the example. Calling duration_since in the opposite order returns Err. SystemTimeError::duration yields the same 5-second gap. The example prints only those Duration values, not the SystemTime itself, because SystemTime formatting can be platform-specific.

SystemTime::checked_add, SystemTime::duration_since, UNIX_EPOCH, SystemTimeError::duration

pub const UNIX_EPOCH: SystemTime
pub fn checked_add(&self, duration: Duration) -> Option<SystemTime>
pub fn duration_since(&self, earlier: SystemTime) -> Result<Duration, SystemTimeError>
pub fn duration(&self) -> Duration

Offset UNIX_EPOCH by a fixed Duration and compare two instants. Do not use now() when the output must be deterministic.

ParameterDescription
durationA fixed span to add with checked_add. The example uses five seconds.
earlierThe instant that should precede self for duration_since to return Ok.

Returns: checked_add returns None if the instant cannot be represented. duration_since returns Ok(Duration) when self is later, or Err(SystemTimeError) when it is earlier. SystemTimeError::duration returns the positive gap.

Errors and panics

  • SystemTimeError — Returned by duration_since when the argument is later than self. The example reports is_err and then the error duration, and does not print platform-specific error text.
  • SystemTime::now and Instant::now are omitted on purpose. Their results would change from run to run.
rust
use std::time::{Duration, UNIX_EPOCH};

fn main() {
    let start = UNIX_EPOCH;
    let later = start.checked_add(Duration::from_secs(5)).unwrap();
    println!("{:?}", later.duration_since(start).unwrap());
    println!("{}", start.duration_since(later).is_err());
    println!("{:?}", start.duration_since(later).unwrap_err().duration());
}

Expected output

5s
true
5s

Official documentation →