interval-align
What this is
A small, dependency-light Rust crate that aligns timestamped samples onto intervals and returns one number per metric: a time-weighted mean for power-like metrics, a sum for energy rows, or a rise for monotone counters — each with a coverage figure and nothing interpolated.
Who it is for
Rust programs that ingest metering or monitoring feeds at irregular rates and need to summarize them over fixed intervals without inventing data.
How to use it
Add the crate to a Rust project:
That writes this line into Cargo.toml:
= "0.1.0"
Minimal example (synthetic data):
use BTreeMap;
use ;
// Timestamps are seconds since the Unix epoch, as `i64`.
let start = 1_772_949_600;
let interval = Interval ;
// Fifteen minutes is only this example's length. Any positive length works.
let samples = ;
let readings: =
align.expect;
// hall.kw was held at 100 for five minutes, then 200 for seven, then 100
// until the end. The time-weighted mean is 158.333… over 80 % coverage.
assert!;
The rules in one place:
- A sample declares its
Kind; nothing is inferred from a unit string.Kind::Poweris the interval's time-weighted mean (each sample held until the next; the last opens no span),Kind::Energyis the sum of the values inside the interval, andKind::Counteris the last value minus the first. - Coverage for power and counter metrics is the span from the first sample to the last, over the interval's length, as a percent. Fewer than two samples means zero coverage. One energy sample covers the whole interval.
- Coverage below the configured minimum, or zero coverage, yields
Reading::Missing { coverage_pct }and no value. Nothing is interpolated or filled, ever. - Two samples of one metric at one instant is a replay: the later one in
caller order wins, and the discard is counted in
duplicates. - A sample outside the interval, or a counter that falls, is a typed error rather than a row quietly dropped.
- A metric with no samples at all is absent from the returned map rather
than
Missing. The map is aBTreeMap, so the same input always yields the same iteration order.
What it deliberately does not do
This crate deliberately does not interpolate between samples, convert time zones, read files or the network, or decide what a good coverage threshold is — a caller supplies min_coverage_pct, and its own meaning of a local day. Timestamps are plain seconds since the Unix epoch as i64; the crate does no time-zone work, never reads a clock, and treats fifteen minutes as an example interval length, not a built-in.
Version 0.x: the API may change before 1.0.