interval-align 0.1.0

Align timestamped samples onto intervals: time-weighted means, sums, or counter deltas, with coverage and no interpolation.
Documentation
# 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:

```sh
cargo add interval-align
```

That writes this line into `Cargo.toml`:

```toml
interval-align = "0.1.0"
```

Minimal example (synthetic data):

```rust
use std::collections::BTreeMap;

use interval_align::{align, Duration, Interval, Kind, Reading, Rules, Sample};

// Timestamps are seconds since the Unix epoch, as `i64`.
let start = 1_772_949_600;
let interval = Interval {
    start,
    length: Duration::seconds(900).expect("a positive length"),
};

// Fifteen minutes is only this example's length. Any positive length works.
let samples = [
    Sample::new("hall.kw", start, 100.0, Kind::Power).expect("finite"),
    Sample::new("hall.kw", start + 300, 200.0, Kind::Power).expect("finite"),
    Sample::new("hall.kw", start + 720, 100.0, Kind::Power).expect("finite"),
];

let readings: BTreeMap<String, Reading> =
    align(&samples, interval, &Rules { min_coverage_pct: 80 }).expect("all samples inside");

// 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!(matches!(
    readings["hall.kw"],
    Reading::Value { coverage_pct: 80, .. }
));
```

The rules in one place:

* A sample declares its `Kind`; nothing is inferred from a unit string.
  `Kind::Power` is the interval's time-weighted mean (each sample held until
  the next; the last opens no span), `Kind::Energy` is the sum of the values
  inside the interval, and `Kind::Counter` is 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 a `BTreeMap`, 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.