t2t_core/lib.rs
1//! Time values: points on the wall and monotonic clocks, counter readings, and the spans between
2//! them.
3//!
4//! Each timeline has its own point, and each kind of count its own span. A point minus a point
5//! is a span, a point plus a span is a point, and points of two timelines never mix:
6//!
7//! | Point | Timeline | Span |
8//! | ---------------- | ------------------------------------------ | ------------- |
9//! | [`Timestamp`] | the wall clock, from the Unix epoch | [`Timedelta`] |
10//! | [`TaiTimestamp`] | International Atomic Time, from 1970 TAI | [`Timedelta`] |
11//! | [`Uptime`] | the monotonic clock, from near boot | [`Timedelta`] |
12//! | [`RawUptime`] | the monotonic clock at the hardware's rate | [`Timedelta`] |
13//! | [`BootUptime`] | the boot clock, suspensions counted | [`Timedelta`] |
14//! | [`Tickstamp`] | a hardware counter, from its own origin | [`Tickdelta`] |
15//!
16//! Every point and span is an `i64`, and its operators saturate at the ends of the range rather
17//! than overflow, each with a `checked_*` twin. Every value has a spelling, which `Display` writes
18//! and `FromStr` reads back.
19//!
20//! # Types
21//!
22//! - **Points.** [`Timestamp`] and [`TaiTimestamp`] name a moment another machine names too;
23//! [`Uptime`], [`RawUptime`] and [`BootUptime`] never step; a [`Tickstamp`] is a counter's
24//! reading. [`TimePoint`] is what they share, for code generic over them.
25//! - **Spans.** [`Timedelta`] counts nanoseconds and [`Tickdelta`] a counter's ticks; a
26//! [`TickRate`] turns one into the other.
27//! - **Views.** [`Timed`] is a value and the stamp it was captured with; [`UtcDateTime`] is a
28//! timestamp read as a date and a time of day.
29//! - **Refusals.** [`ParseTimestampError`], [`ParseTaiTimestampError`], [`ParseTimedeltaError`],
30//! [`ParseTickdeltaError`] and [`ParseTickRateError`] for a spelling that does not read;
31//! [`OutOfRangeError`] for a time another type cannot hold.
32//!
33//! # Examples
34//! ```
35//! use t2t_core::{Timed, Timedelta, Timestamp};
36//!
37//! let stale: Timedelta = "1s".parse()?;
38//! let captured = Timestamp::from_secs(1_700_000_000);
39//! let sample = Timed::new(captured, 101_u64);
40//!
41//! assert!(sample.elapsed(captured + Timedelta::from_millis(1_500)) > stale, "stale by now");
42//! # Ok::<(), t2t_core::ParseTimedeltaError>(())
43//! ```
44//!
45//! # Crate Features
46//!
47//! None is on by default, and nothing reaches the operating system unless `std` is named; what
48//! `std` adds is on 64-bit Linux and macOS.
49//!
50//! | Feature | Adds |
51//! | ----------- | -------------------------------------------------------------------------- |
52//! | `std` | `SystemTime` conversions |
53//! | `serde` | every value's spelling, and the `serde` modules for counts in a named unit |
54//! | `schemars` | `JsonSchema` for every value with a spelling; turns `serde` on |
55//! | `zerocopy` | the zerocopy traits each type can honour, native-endian |
56//! | `chrono-04` | conversions to and from chrono 0.4's `DateTime` and `TimeDelta` |
57//! | `jiff-02` | conversions to and from jiff 0.2's `Timestamp` and `SignedDuration` |
58//! | `time-03` | conversions to and from time 0.3's `OffsetDateTime` and `Duration` |
59
60#![no_std]
61#![cfg_attr(docsrs, feature(doc_cfg))]
62
63#[cfg(any(test, feature = "schemars"))]
64extern crate alloc;
65#[cfg(any(test, feature = "std"))]
66extern crate std;
67
68mod consts;
69mod errors;
70mod interop;
71mod ops;
72mod point;
73mod rfc3339;
74#[cfg(feature = "serde")]
75pub mod serde;
76mod spelling;
77mod tick;
78mod tick_rate;
79mod timed;
80mod timedelta;
81mod timestamp;
82mod uptime;
83mod utc;
84
85pub use crate::errors::{
86 OutOfRangeError, ParseTaiTimestampError, ParseTickRateError, ParseTickdeltaError,
87 ParseTimedeltaError, ParseTimestampError,
88};
89pub use crate::point::TimePoint;
90pub use crate::tick::{Tickdelta, Tickstamp};
91pub use crate::tick_rate::TickRate;
92pub use crate::timed::Timed;
93pub use crate::timedelta::Timedelta;
94pub use crate::timestamp::{TaiTimestamp, Timestamp};
95pub use crate::uptime::{BootUptime, RawUptime, Uptime};
96pub use crate::utc::UtcDateTime;