regorus/docs/value/set.md

Set

Opaque container for Value::Set's element storage, enabling alternative backends without call-site changes. Pairs with Object under a shared design philosophy.

Design

Set wraps a BTreeSet<Value> today but exposes only a curated method surface (contains, insert, remove, iter, iter_sorted, cursor, is_subset, intersection, union, difference, serde). The inner set is private — callers cannot pattern-match it or hand out references to the backing store, so the backend can change without churn at the ~400 call sites that name Set.

Two iteration methods reflect a real distinction: iter() makes no ordering promise (lets future hash/lazy backends skip sorting work); iter_sorted() guarantees deterministic order (used by serialization and Ord). Cursor types support incremental traversal needed by the RVM iteration state without exposing iterator internals.

Ord is hand-written against iter_sorted rather than derived, so two backends that store elements differently still compare equal when their sorted contents match.

Scenarios enabled

• Hash-backed storage — FxHashSet-backed inner turns O(log n) membership checks into O(1); swap in for policies where elements aren't compared ordinally.
• Lazy/streaming — wrap a LazySetProvider (DB query, CBOR slice, REST endpoint) and materialize elements on demand.
• Arena allocation — bumpalo-backed inner for eval-time temporaries; drop the whole arena at query end with zero per-element free cost.
• FFI-backed — host-language collections (Python set, JS Set) without copying into Rust.
• Bloom-filter pre-check — front a large backing set with a Bloom filter for fast negative-membership tests on read-mostly allowlists.

Known use cases

• Azure Policy allowed-values lists — large allowlists (allowed regions, allowed SKUs, allowed image publishers) compared against single resource values. Hash-backed Set turns O(log n) membership checks into O(1).
• SARIF rule deduplication — collapsing duplicate rule references across thousands of result records. Set-of-objects with structural hashing avoids the BTreeSet sort cost on every insert.
• RBAC role membership — checking whether a principal belongs to any of dozens of role groups. Hash-backed Set scales to thousands of members with constant-time membership.
• Azure Policy denied-resource-type sets — exclusion lists used by deny-effect policies; same hash-backed pattern as allowed-values.

Precedents

• indexmap::IndexSet — opaque newtype that pairs hash lookup with insertion-order iteration; precedent for "Set with alternative ordering semantics behind a stable surface."
• hashbrown::HashSet — backs Rust's std::collections::HashSet and demonstrates a fully swappable backend behind a stable API.
• roaring::RoaringBitmap — bitmap-backed integer set. Not applicable to Value keys directly, but a precedent for the broader idea of "Set with alternative storage representations chosen by workload shape."
• serde_json — note that serde_json has no Set equivalent: its Value enum collapses sets into arrays. Regorus's first-class Set with storage abstraction is therefore unusually well-positioned among JSON value libraries.

Notes

Cursor types are pub (referenced by public IterationState) but not re-exported at the crate root. The crate-internal Set/Map/MapEntry aliases for BTreeSet/BTreeMap in lib.rs were renamed to MapSet/Map/MapEntry when this type landed, to free the Set name for the new public type. Future Array and String abstractions follow the same shape — see docs/value/array.md and docs/value/string.md when they land.