Skip to content
Tutorials Center
My learning

Topics

Rust Reference ยท Standard Library Modules

The std::time module

Reference for std::time: Duration construction and arithmetic, Instant for measuring elapsed time, SystemTime and UNIX_EPOCH for wall-clock time, and their errors.

std::time has three types. Duration is a span of time (seconds plus nanoseconds), unrelated to any clock. Instant is a reading from a monotonic clock: it never goes backward, so subtracting two instants is the right way to measure how long something took. SystemTime is the wall clock (the time on the user's calendar), which can jump when the system clock is adjusted.

Use Instant for timeouts and benchmarks, and SystemTime only when you need a real-world timestamp, for example to compare with file modification times or to compute seconds since 1970 with UNIX_EPOCH.

Rust
use std::time::{Duration, Instant};

let start = Instant::now();
let elapsed: Duration = start.elapsed();

Try it

Rust Duration arithmetic and constructors

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Rust Instant, SystemTime and the epoch

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Syntax

Type Main items
Duration new(secs, nanos), from_secs, from_millis, from_micros, from_nanos, from_secs_f32, from_secs_f64; as_secs, as_millis, as_micros, as_nanos, as_secs_f64, subsec_nanos, subsec_millis; checked_add, checked_sub, saturating_sub, mul_f64, div_f64; constants ZERO, MAX, SECOND, MILLISECOND.
Instant now(), elapsed(), duration_since(earlier), checked_duration_since, saturating_duration_since, checked_add, checked_sub; supports + Duration, - Duration, - Instant.
SystemTime now(), elapsed() -> Result<Duration, SystemTimeError>, duration_since(earlier) -> Result<Duration, SystemTimeError>, checked_add, checked_sub; constant UNIX_EPOCH.
SystemTimeError Returned when the "earlier" time is actually later; .duration() gives the gap.

Errors and edge cases: Duration is unsigned: a - b panics when b > a (use checked_sub or saturating_sub). Duration + Duration panics on overflow. Duration::from_secs_f64 panics on negative, NaN or too-large input (try_from_secs_f64 returns Result). Instant - Instant saturates to zero since Rust 1.60 rather than panicking.

Usage notes

  • A Duration's Debug output adapts the unit: 1.5s, 250ms, 2.5ms. It is for humans and not a stable format.
  • as_millis() returns u128; subsec_millis() returns u32. Mind the difference between "total" (as_*) and "fractional part" (subsec_*).
  • Benchmarks with Instant measure noise too. Repeat the work, discard warm-up runs, and use std::hint::black_box so the compiler does not delete the code.
  • Instant values are only meaningful within one process run; they cannot be stored or sent to other machines.
  • SystemTime can go backwards (NTP, user changes), so durations from it can be negative; that is why it returns Result.
  • The standard library has no calendar, time-zone or date formatting; use a crate (such as chrono or time) for those.
  • thread::sleep(d) sleeps at least d; the OS may add delay.