difftime-rs

A tiny, unsafe-free Rust port of upstream tzcode difftime.c, verified bit-for-bit against a compiled C oracle for the admitted signed 64-bit time_t model. It is not a general duration library or a libc replacement — it computes one number, time1 − time0 as an f64, exactly as difftime.c does on a 64-bit host.

use difftime::difftime;

assert_eq!(difftime(1, 0), 1.0);
assert_eq!(difftime(0, 1), -1.0);

// The whole point of difftime: the difference of two extreme timestamps must
// not overflow the integer type the way `(time1 - time0)` would.
assert_eq!(difftime(i64::MAX, i64::MIN), 18446744073709551615.0); // = 2^64 - 1, rounded to 2^64

What it does

difftime(time1, time0) returns time1 − time0 as an f64. The library crate name is difftime, so call it as difftime::difftime(..).

Upstream difftime.c picks one of five branches by sizeof(time_t) and TYPE_SIGNED(time_t). On the admitted host model — signed 64-bit time_t, where sizeof(time_t) == sizeof(double) == sizeof(uintmax_t) == 8 — it takes branch 3: compute the magnitude |time1 − time0| in unsigned 64-bit arithmetic (which is exact for any two i64, since the true difference lies in 0 ..= u64::MAX), cast to f64 (round-to-nearest-even when the magnitude exceeds 2⁵³), and negate if time1 < time0.

This is deliberately not (time1 - time0) as f64: that overflows i64 when the operands straddle zero at the extremes. The unsigned-magnitude path is what makes difftime safe at the boundaries.

Scope and non-claims

• Models. The public API is the signed 64-bit model (difftime.c branch 3). The other branches (narrow/signed-32 → branch 1; unsigned → branch 2; wider-than-uintmax_t → branches 4–5) fire only under other time_t models; they are explored in the test suite against provably-exact arithmetic, not exposed as public API.
• Not a duration/Duration library, calendar, timezone engine, or chrono/jiff helper. No civil-time meaning — difftime is pure timestamp subtraction.
• Bit-exact equality with the C oracle is claimed for the swept matrix on IEEE-754 binary64 hosts.

Provenance & verification

Ported from IANA tzdb 2026b (difftime.c sha256 4f61e6ee…; bundle tzdb-2026b.tar.lz sha256 ffad46a0…, OpenPGP-verified, key 7E37 92A9 D8AC F7D6 33BC 1588 ED97 E90E 62AA 7E34). difftime.c is public domain (Arthur David Olson, 1996), so this port is offered under Apache-2.0.

Verified against the compiled pristine difftime.c: 6637/6637 pairs bit-identical (f64), 0 port bugs. One Kani proof (unsigned_magnitude_is_exact_and_fits) verifies the magnitude is exact and overflow-free over all i64×i64. Fuzzed 161.5M runs, 0 crashes. #![forbid(unsafe_code)], overflow-checks = true, zero runtime dependencies, MSRV 1.74. See reports/ for receipts.

License

Apache-2.0. Upstream difftime.c is in the public domain.