pub fn diff(db: &Db, from_seq: u64, to_seq: u64) -> Result<StateDiff, String>Expand description
Difference in logical state between from_seq and to_seq.
§Refusals
Below the history floor. compact discards superseded versions, and
below Db::history_floor the prev chain no longer reaches. A diff
computed there would be indistinguishable from a diff over a range where
nothing happened: every pruned document would silently read as unchanged.
An empty answer that means “I cannot see” is worse than no answer, so this
refuses with HISTORY_PRUNED rather than returning a partial result.
from_seq > to_seq. Refused rather than interpreted as a reverse diff.
A reversed range is already expressible — it is diff(to, from) — so
accepting it here would buy nothing and cost the invariant that
kind == Added means “exists at to_seq”. Silently swapping the arguments
would invert the meaning of every kind in the result relative to the
argument order the caller wrote, and nothing in the returned value would
tell them that happened.
A to_seq beyond the current tip is NOT refused: sequences are monotonic,
so any sequence at or past the tip denotes the current state unambiguously.
There is nothing to be wrong about, and refusing would make
diff(x, u64::MAX) — a reasonable spelling of “up to now” — an error.