Getting Started

Add the crate, with the operating system’s clocks:

cargo add t2t --features std

The values, the CPU’s counter and the manual clocks need no feature, and build without std; the operating system’s clocks need std, on 64-bit Linux or macOS. t2t builds on stable Rust 1.98 or later. Platforms and Features lists every feature and what it adds.

A First Program

The wall clock stamps the moment, since its reading names a moment another machine can name too; the monotonic clock times the pause, since no correction to the wall clock moves it.

fn the_wall_clock_stamps_and_the_monotonic_clock_times() {
    use core::time::Duration;
    use std::thread;

    use t2t::Timedelta;
    use t2t::clock::{Clock, MonotonicClock, SystemClock};

    // A stamp another machine can read: the wall clock's.
    let captured = SystemClock.now();
    // A start that no correction to the wall clock moves: the monotonic clock's.
    let start = MonotonicClock.now();

    let pause = Timedelta::from_millis(20);
    thread::sleep(Duration::try_from(pause).expect("a span forwards"));

    let took = MonotonicClock.now() - start;
    println!("captured at {captured:.6}, then slept {took}");
    assert!(took >= pause, "at least the pause: {took}");
}

Timestamp’s {:.6} writes RFC 3339 to the microsecond, and a span is written coarsest unit first, as 20ms83us. Choosing a Clock says which clock to read for what.

Two Tours

In a checkout of the repository, two examples walk through the rest. The first prints the values: points and spans, the calendar, a stamped value, and a counter’s rate.

cargo run -p t2t --example time-tour

The second prints every clock’s reading, and what one costs on the machine it runs on.

cargo run --release -p t2t --features std --example clock-tour

Every listing in this book runs as a test too:

cargo test -p t2t --all-features --test book
cargo test -p t2t-core --all-features --test book

From there, clock lists every clock, and the crate’s page, t2t, says which to choose for what.