clock-lib 1.0.0

Monotonic and wall-clock time readings for Rust, with a mockable clock for deterministic testing. Simple Tier-1 API, zero dependencies, no unsafe.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64

# v0.2.0 — Tier-1 Readings

`clock-lib` is now usable. This release ships the core time-reading API: monotonic time for measuring elapsed intervals, wall-clock time for stamping events, and the Unix-time conveniences that thin layer above them.

## Highlights

- **Monotonic readings via [`Monotonic`](../../docs/API.md#monotonic).** A typed wrapper around the operating system's monotonic clock with `elapsed`, `duration_since`, `checked_duration_since`, and `saturating_duration_since`. Use it for rate limiting, timeouts, benchmarks, and retry backoff — anywhere a forward-only clock matters.
- **Wall-clock readings via [`Wall`](../../docs/API.md#wall-1).** A typed wrapper around the system real-time clock with Unix-time accessors at second, millisecond, and nanosecond resolution. Use it for log timestamps, audit records, and anything that needs to line up with calendar time.
- **Tier-1 one-line API.** `now()`, `elapsed(start)`, `wall()`, `unix()`, `unix_ms()`, `unix_ns()` — the common case is a single function call with no ceremony. Reach for the typed values when you need them.
- **Type-level separation of the two clocks.** `Monotonic` and `Wall` are distinct types with no cross-type arithmetic. The compiler refuses to subtract a wall-clock reading from a monotonic one, eliminating a class of subtle timing bugs at the source.
- **Pre-epoch safety.** If the system clock is set to a moment before `1970-01-01 UTC`, every `unix_*` accessor saturates to `0`. No panics, no silent wrapping.

## Quick Start

```toml
[dependencies]
clock-lib = "0.2"
```

```rust
use clock_lib as clock;

// Measure how long something takes.
let start = clock::now();
// ... do work ...
let took = clock::elapsed(start);

// Stamp an event for a log.
let seconds = clock::unix();
let millis = clock::unix_ms();
```

## What's New

### Added

- `Monotonic` reading type with `now`, `elapsed`, `duration_since`, `checked_duration_since`, and `saturating_duration_since`.
- `Wall` reading type with `now`, `unix_seconds`, `unix_millis`, and `unix_nanos`.
- Tier-1 free functions: `now`, `elapsed`, `wall`, `unix`, `unix_ms`, `unix_ns`.
- Integration tests covering monotonic ordering, wall-clock conversions, and the Tier-1 surface.
- Doctests on every public item.

### Changed

- **Minimum Supported Rust Version raised to 1.85** to match the Rust 2024 edition declared in `Cargo.toml`. The previous declaration of 1.75 was inconsistent with the edition setting.

## Compatibility

- **MSRV:** Rust 1.85
- **Edition:** 2024
- **Platforms:** Linux, macOS, Windows
- **Features:** `std` (default). `no_std` builds compile and expose `VERSION`; reading APIs land in the `no_std` path during the 0.5 hardening phase.

## Upgrading From 0.1.0

`0.1.0` shipped only the project scaffold — there was no usable API surface to migrate from. Add the dependency and start calling `now()`.

If your `Cargo.toml` previously pinned `rust-version = "1.75"` against this crate, raise it to `1.85` to match the new MSRV.

## What's Next

- **0.3.0 — the `Clock` trait.** `SystemClock` for production and `ManualClock` for deterministic, sleep-free tests. The mockable-clock pattern is the headline feature of `clock-lib`; it lands next.
- **0.4.0 — performance verification.** Criterion benchmarks for reading latency, with committed baselines that prove the abstraction is zero-cost over raw `std::time`.
- **0.5.0 — `no_std` hardening and the 1.0 release candidate.**