#moonbit-roaring

#Why another package?

• Portable interoperability — reads and writes the format specified by RoaringFormatSpec, so MoonBit can participate in existing cross-language Roaring data pipelines.
• Run optimization on normal operations — add, remove, range methods, and all set operations reselect Array, Bitmap, or Run representation by encoded byte cost.
• Defensive decoding — rejects truncated input, invalid offsets, unordered keys or arrays, overlapping runs, cardinality mismatches, and trailing bytes.
• Additional bitmap-level APIs — half-open range construction/mutation, lazy iteration, rank, select, multi-way operations, plus compatibility helpers clear, inclusive range, and jaccard_similarity.

#Installation

moon add xcc-ordinary/moonbit-roaring

#Example

let sparse = @roaring.RoaringBitmap::from_array([1U, 100U, 1000U])
let consecutive = @roaring.RoaringBitmap::from_range(0U, 10000U)
let result = sparse.union(consecutive)

// The only exposed wire format is the interoperable portable format.
let bytes = result.serialize()
let restored = match @roaring.RoaringBitmap::deserialize(bytes) {
  Ok(bitmap) => bitmap
  Err(error) => panic("invalid bitmap: \{error}")
}

let first_three = restored.iter().take(3).to_array()
let count_at_or_below_500 = restored.rank(500U)
let fifth = restored.select(4)

moon run examples/inverted_index
moon run examples/portable_window
moon run examples/analytics

#Implemented surface

• Array, Bitmap, and Run containers
• standard set operations and multi-way union/intersection
• half-open range construction, mutation, and containment
• lazy Iter[UInt], bitmap-level rank and select
• Roaring portable serialization and strict deserialization
• immutable compatibility helpers: clear, inclusive range, Jaccard similarity
• statistics exposing container choices and encoded payload sizes

#Verification evidence

• Tests run on wasm, wasm-gc, and js in CI.
• Official Java-generated files from RoaringFormatSpec/testdata are decoded, checked for known values, and re-encoded byte-for-byte.
• Six additional fixture shapes are generated by roaring-wasm v1.1.0, a third-party CRoaring-based WASM package. CI verifies deterministic regeneration.
• Malformed-format tests cover structural and semantic validation, including every truncated prefix of representative serialized data.
• Release-mode benchmark fixtures and a reproducible baseline are documented in docs/benchmarks.md. They are not a competitor-speed claim.

moon info
moon fmt --check
moon check -d
moon test
moon test --target wasm-gc
moon test --target js
moon bench --release --target wasm

#Comparison scope

#Scope and limitations

• 32-bit unsigned values only; no Roaring64.
• Portable format only; no native/frozen/mmap formats.
• Immutable operations; no thread-safe mutable bitmap API.
• No SIMD-specific kernels and no claim of outperforming other implementations.
• The native target is not currently part of the verified matrix.

#License