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.
use std::time::{Duration, Instant}; let start = Instant::now(); let elapsed: Duration = start.elapsed();
Try it
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.
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'sDebugoutput adapts the unit:1.5s,250ms,2.5ms. It is for humans and not a stable format. as_millis()returnsu128;subsec_millis()returnsu32. Mind the difference between "total" (as_*) and "fractional part" (subsec_*).- Benchmarks with
Instantmeasure noise too. Repeat the work, discard warm-up runs, and usestd::hint::black_boxso the compiler does not delete the code. Instantvalues are only meaningful within one process run; they cannot be stored or sent to other machines.SystemTimecan go backwards (NTP, user changes), so durations from it can be negative; that is why it returnsResult.- The standard library has no calendar, time-zone or date formatting; use a crate (such as
chronoortime) for those. thread::sleep(d)sleeps at leastd; the OS may add delay.