🥮 mooncakes.io

    moon-mphf

    Pure MoonBit minimal perfect hash functions and checked static maps

    minimal-perfect-hash
    mphf
    static-map
    index
    Download zip
    Author
    Version
    0.1.0
    License
    Apache-2.0
    Repository
    Last updated
    12 hours ago
    Downloads
    1

    #MoonBit MPHF

    MoonBit MPHF is a pure-MoonBit library for deterministic minimal perfect hash functions and checked, immutable integer sets/maps. It is designed for a key set known at build time: protocol tokens, compiled rule tables, embedded configuration, or immutable data segments.

    An MPHF maps the original n keys to exactly the slots [0, n) without collisions. An MPHF alone cannot recognise an unknown key, so this package also provides StaticSet and StaticIntMap; they retain the slot-ordered key and perform an exact equality check before returning a hit.

    StaticStringSet and StaticStringIntMap provide the same checked behavior for UTF-16/Unicode-scalar strings. They use stable_string_hash for routing, retain the original strings, and reject a construction-time hash collision.

    #Use

    let routes = @mphf.StaticIntMap::from_entries([
      { key: 101, value: 10 },
      { key: 203, value: 20 },
    ]).unwrap()
    assert_eq(routes.get(203), Some(20))
    assert_eq(routes.get(404), None)

    Run the local checks and example:

    moon check --deny-warn
moon test --deny-warn
moon bench --release --deny-warn
moon run cmd/main

    #Guarantees and boundaries

    • Input keys are non-negative MoonBit Int values and must be unique. They are already-hashed identifiers; the package intentionally does not impose a string or cryptographic hashing policy.
    • Construction uses a deterministic, bounded-retry BDZ-style three-vertex hypergraph. It either returns a function or ConstructionFailed; it never loops indefinitely.
    • Mphf::slot_of_hash is only a slot function. Use StaticSet::contains or StaticIntMap::get when a query may contain unknown keys.
    • Word encodings are versioned and validate lengths, metadata, assignment bounds, duplicate keys, and key/slot agreement on decode.
    • SegmentedSet and SegmentedIntMap support immutable batches. Set compaction removes duplicates; map lookup gives later batches precedence; both representations have checked word encodings.
    • StaticIntMultiMap indexes distinct keys once and retains each key's values in input order. StaticIntBiMap provides checked forward and reverse exact lookup for one-to-one non-negative integer mappings.
    • StaticStringSet and StaticStringIntMap have versioned Unicode-scalar word encodings. Decoding validates every scalar and reruns exact MPHF-slot routing checks before exposing a loaded string index.
    • ShardedSet and ShardedIntMap route key % shard_count to one MPHF, supporting bounded builds, deterministic re-sharding, compaction, and checked nested encodings. Their validate methods also verify a received in-memory shard layout and every key's residue routing.
    • Static set/map patches model immutable rebuilds explicitly and can be stored as validated word streams. Persistent cursors support checkpointed scans without mutating a published index.
    • Build options expose the vertex-ratio/retry trade-off; validate and deterministic fingerprints provide artifact-integrity checks. Fingerprints detect accidental mismatch and are not cryptographic authentication.
    • This library deliberately does not support insertion, deletion, resizing, cryptographic hashing, or a network/database layer. Rebuild when the key set changes.

    #Provenance

    The implementation is independently written in MoonBit, using the public minimal-perfect-hashing approach as a reference. It does not copy source, tests, or generated tables from upstream projects. Relevant references are rust-phf and BBHash, both MIT licensed.

    The project itself is licensed under Apache-2.0; see LICENSE.

    #Publishing note

    The MoonBit package namespace is clbbbb/moon-mphf. The GitHub repository is https://github.com/clbbbb/moonbit-mphf; publishing to Mooncakes remains a separate release step.

    IntEntry

    source
    pub(all) struct IntEntry {
      key : Int
      value : Int
    }

    One integer key/value pair used to construct a static map.

    IntMultiEntry

    source
    pub(all) struct IntMultiEntry {
      key : Int
      value : Int
    }

    One key/value item for a multimap. Equal keys are intentionally allowed.

    KeySetDiff

    source
    pub(all) struct KeySetDiff {
      added : Array[Int]
      removed : Array[Int]
      retained : Int
    }

    Exact key-set delta used to decide whether a static index must be rebuilt.

    KeySetDiff::changed_count

    source
    fn KeySetDiff::changed_count(self : KeySetDiff) -> Int

    Number of source keys changed by this delta.

    KeySetDiff::is_empty

    source
    fn KeySetDiff::is_empty(self : KeySetDiff) -> Bool

    True when no rebuild work is needed for a source key-set comparison.

    LookupSummary

    source
    pub(all) struct LookupSummary {
      query_count : Int
      hit_count : Int
      miss_count : Int
    }

    Aggregate result for a batch of exact membership or map probes.

    Mphf

    source
    pub struct Mphf {
      key_count : Int
      vertex_count : Int
      seed : Int
      attempts : Int
      values : Array[Int]
    }

    slot_of_hash maps every non-negative input to a slot. Membership must be checked separately, because an MPHF alone cannot recognize an unknown key.

    Mphf::build

    source
    fn Mphf::build(keys : Array[Int]) -> Result[Mphf, MphfError]

    Build a minimal perfect hash function for distinct non-negative hashes.

    Mphf::build_with_options

    source
    fn Mphf::build_with_options(keys : Array[Int], options : MphfBuildOptions) -> Result[Mphf, MphfError]

    Build an MPHF with an explicit space-versus-retry policy. Larger vertex ratios make peeling more likely to succeed but produce a larger table.

    Mphf::encode_words

    source
    fn Mphf::encode_words(self : Mphf) -> Array[Int]

    Format: [1, key_count, vertex_count, seed, attempts, g...].

    Mphf::is_perfect_for

    source
    fn Mphf::is_perfect_for(self : Mphf, keys : Array[Int]) -> Bool

    once. This is useful when loading a function and its key manifest from separate artifacts.

    Mphf::len

    source
    fn Mphf::len(self : Mphf) -> Int

    Return the number of keys used to construct this function.

    Mphf::slot_of_hash

    source
    fn Mphf::slot_of_hash(self : Mphf, key : Int) -> Int?

    membership: callers requiring that guarantee should use StaticSet or StaticIntMap.

    Mphf::stats

    source
    fn Mphf::stats(self : Mphf) -> MphfStats

    Return construction diagnostics without exposing mutable internal tables.

    Mphf::validate

    source
    fn Mphf::validate(self : Mphf) -> Result[Unit, MphfError]

    Validate the internal dimensions and vertex ranges of a decoded MPHF. This does not establish source membership because an MPHF intentionally stores no source-key manifest.

    MphfBuildOptions

    source
    pub(all) struct MphfBuildOptions {
      vertices_per_key_milli : Int
      max_attempts : Int
      initial_seed : Int
    }

    Controls the memory/retry trade-off made while constructing a BDZ graph. vertices_per_key_milli is expressed in thousandths, so 1300 means 1.3 graph vertices for each source key.

    MphfError

    source
    pub(all) enum MphfError {
      EmptyInput
      EmptySegment(Int)
      NegativeKey(Int)
      DuplicateKey(Int)
      DuplicateValue(Int)
      DuplicateStringKey(String)
      HashCollision(String, String)
      ConstructionFailed(Int)
      MissingHeader
      UnsupportedVersion(Int)
      InvalidPayloadLength(Int, Int)
      InvalidMetadata
      InvalidVertexValue(Int)
      InvalidBuildOption(Int)
      InvalidShardCount(Int)
      InvalidRange(Int, Int)
      DuplicatePatchKey(Int)
    }

    Errors returned while building or decoding a static hash index.

    MphfStats

    source
    pub(all) struct MphfStats {
      key_count : Int
      vertex_count : Int
      seed : Int
      attempts : Int
    }

    Summary of the deterministic construction selected for a key set.

    SegmentStats

    source
    pub(all) struct SegmentStats {
      segment_count : Int
      key_count : Int
    }

    Aggregate information for an immutable segmented index.

    SegmentedIntMap

    source
    pub struct SegmentedIntMap {
      segments : Array[StaticIntMap]
    }

    A read-only layered map. Later segments override earlier ones on lookup.

    SegmentedIntMap::compact

    source
    fn SegmentedIntMap::compact(self : SegmentedIntMap) -> Result[StaticIntMap, MphfError]

    Return a one-segment map that preserves the newest value of every key. Compaction is deterministic: ties are resolved by later source segment, exactly as get resolves them before compaction.

    SegmentedIntMap::encode_words

    source
    fn SegmentedIntMap::encode_words(self : SegmentedIntMap) -> Array[Int]

    Encode a layered map as independently checked map blobs.

    Format: [9, segment_count, word_count, map_words..., ...].

    SegmentedIntMap::from_batches

    source
    fn SegmentedIntMap::from_batches(batches : Array[Array[IntEntry]]) -> Result[SegmentedIntMap, MphfError]

    lookup precedence, supporting append-only configuration or data revisions.

    SegmentedIntMap::get

    source
    fn SegmentedIntMap::get(self : SegmentedIntMap, key : Int) -> Int?

    values without mutating previously published segments.

    SegmentedIntMap::stats

    source

    Return segment and stored-entry totals for a layered map.

    SegmentedSet

    source
    pub struct SegmentedSet {
      segments : Array[StaticSet]
    }

    Segments are useful when source data arrives in immutable batches and a full rebuild should be deferred to an explicit compaction step.

    SegmentedSet::compact

    source
    fn SegmentedSet::compact(self : SegmentedSet) -> Result[StaticSet, MphfError]

    Merge all segments into one exact set, eliminating duplicate keys.

    SegmentedSet::contains

    source
    fn SegmentedSet::contains(self : SegmentedSet, key : Int) -> Bool

    Test exact membership in any segment.

    SegmentedSet::encode_words

    source
    fn SegmentedSet::encode_words(self : SegmentedSet) -> Array[Int]

    Format: [4, segment_count, word_count, set_words..., ...].

    SegmentedSet::from_batches

    source
    fn SegmentedSet::from_batches(batches : Array[Array[Int]]) -> Result[SegmentedSet, MphfError]

    Build a set index from non-empty immutable key batches.

    SegmentedSet::missing

    source
    fn SegmentedSet::missing(self : SegmentedSet, keys : Array[Int]) -> Array[Int]

    Return inputs that do not belong to any segment, preserving input order.

    SegmentedSet::stats

    source

    across immutable batches, so this is not a distinct-key cardinality.

    ShardStats

    source
    pub(all) struct ShardStats {
      shard_count : Int
      key_count : Int
      smallest_shard : Int
      largest_shard : Int
    }

    Basic distribution information for a fixed-count sharded index.

    ShardedIntMap

    source
    pub struct ShardedIntMap {
      shard_count : Int
      shards : Array[StaticIntMap?]
    }

    A static integer map partitioned by key % shard_count.

    ShardedIntMap::compact

    source
    fn ShardedIntMap::compact(self : ShardedIntMap) -> Result[StaticIntMap, MphfError]

    Rebuild all map shards into one exact static map without changing pairs.

    ShardedIntMap::contains_key

    source
    fn ShardedIntMap::contains_key(self : ShardedIntMap, key : Int) -> Bool

    Test exact key membership without allocating a result value.

    ShardedIntMap::encode_words

    source
    fn ShardedIntMap::encode_words(self : ShardedIntMap) -> Array[Int]

    Deterministically encode a sharded map with the same empty-shard rule used by ShardedSet.

    Format: [8, shard_count, word_count, map_words..., ...].

    ShardedIntMap::entries

    source
    fn ShardedIntMap::entries(self : ShardedIntMap) -> Array[IntEntry]

    Return all pairs in deterministic shard then slot order.

    ShardedIntMap::from_entries

    source
    fn ShardedIntMap::from_entries(entries : Array[IntEntry], shard_count : Int) -> Result[ShardedIntMap, MphfError]

    Build a fixed-count sharded map. Duplicate keys are rejected in their own residue shard, which is equivalent to rejecting them globally.

    ShardedIntMap::get

    source
    fn ShardedIntMap::get(self : ShardedIntMap, key : Int) -> Int?

    Retrieve an exact key from its only possible shard.

    ShardedIntMap::get_many

    source
    fn ShardedIntMap::get_many(self : ShardedIntMap, keys : Array[Int]) -> Array[Int?]

    Probe many map keys at once while preserving query order.

    ShardedIntMap::query_summary

    source
    fn ShardedIntMap::query_summary(self : ShardedIntMap, keys : Array[Int]) -> LookupSummary

    Count hits and misses in a sharded map query batch.

    ShardedIntMap::reshard

    source
    fn ShardedIntMap::reshard(self : ShardedIntMap, shard_count : Int) -> Result[ShardedIntMap, MphfError]

    Repartition an immutable map under a different residue-shard count.

    ShardedIntMap::stats

    source

    Return the distribution of entries across map shards.

    ShardedIntMap::validate

    source
    fn ShardedIntMap::validate(self : ShardedIntMap) -> Result[Unit, MphfError]

    Verify every present map shard and its residue routing. Map values are unconstrained; only exact keys participate in the sharding rule.

    ShardedSet

    source
    pub struct ShardedSet {
      shard_count : Int
      shards : Array[StaticSet?]
    }

    A static set partitioned by key % shard_count. Sharding keeps builds and rebuilds bounded for datasets that are too large for one MPHF artifact.

    ShardedSet::compact

    source
    fn ShardedSet::compact(self : ShardedSet) -> Result[StaticSet, MphfError]

    Rebuild all shards into one exact static set. This is useful when an ingestion-time sharding policy is no longer needed by a read-mostly client.

    ShardedSet::contains

    source
    fn ShardedSet::contains(self : ShardedSet, key : Int) -> Bool

    Test exact membership by routing a key to one shard. Negative keys are rejected as probes rather than being allowed to index with a negative value.

    ShardedSet::encode_words

    source
    fn ShardedSet::encode_words(self : ShardedSet) -> Array[Int]

    Deterministically encode a sharded set. Empty residue classes have a zero payload, which keeps the requested shard count visible after decoding.

    Format: [7, shard_count, word_count, set_words..., ...].

    ShardedSet::filter_missing

    source
    fn ShardedSet::filter_missing(self : ShardedSet, keys : Array[Int]) -> Array[Int]

    Return all query keys that are not present in their corresponding shard.

    ShardedSet::from_keys

    source
    fn ShardedSet::from_keys(keys : Array[Int], shard_count : Int) -> Result[ShardedSet, MphfError]

    Build a static set split into a fixed number of residue shards. Each key is routed by key % shard_count, so exact lookup constructs no temporary key and probes exactly one underlying MPHF.

    ShardedSet::keys

    source
    fn ShardedSet::keys(self : ShardedSet) -> Array[Int]

    Return a copy of every key in deterministic shard then slot order.

    ShardedSet::query_summary

    source
    fn ShardedSet::query_summary(self : ShardedSet, keys : Array[Int]) -> LookupSummary

    Count exact hit and miss outcomes over a sharded set query batch.

    ShardedSet::reshard

    source
    fn ShardedSet::reshard(self : ShardedSet, shard_count : Int) -> Result[ShardedSet, MphfError]

    Repartition this immutable set under a different residue-shard count.

    ShardedSet::stats

    source
    fn ShardedSet::stats(self : ShardedSet) -> ShardStats

    Return balance statistics. Empty shards are intentionally included in the minimum so callers can see whether their chosen shard count is excessive.

    ShardedSet::validate

    source
    fn ShardedSet::validate(self : ShardedSet) -> Result[Unit, MphfError]

    Verify every present set shard is structurally valid and that every stored key belongs to its recorded residue class. This is useful after receiving a sharded index through a transport other than decode_sharded_set_words.

    StaticIndexFingerprint

    source
    pub(all) struct StaticIndexFingerprint {
      key_count : Int
      key_fingerprint : Int
      value_fingerprint : Int
    }

    A deterministic, non-cryptographic integrity summary of a static source manifest. It detects accidental mismatch, not malicious tampering.

    StaticIntBiMap

    source
    pub struct StaticIntBiMap {
      forward : StaticIntMap
      reverse : StaticIntMap
    }

    An exact immutable one-to-one integer mapping with independently checked forward and reverse MPHF indexes.

    StaticIntBiMap::contains_key

    source
    fn StaticIntBiMap::contains_key(self : StaticIntBiMap, key : Int) -> Bool

    Test whether a source key exists.

    StaticIntBiMap::contains_value

    source
    fn StaticIntBiMap::contains_value(self : StaticIntBiMap, value : Int) -> Bool

    Test whether a mapped value exists.

    StaticIntBiMap::encode_words

    source
    fn StaticIntBiMap::encode_words(self : StaticIntBiMap) -> Array[Int]

    Encode a bidirectional map as two independently checked static map blobs.

    Format: [12, forward_word_count, forward_words..., reverse_words...].

    StaticIntBiMap::entries_by_key

    source
    fn StaticIntBiMap::entries_by_key(self : StaticIntBiMap) -> Array[IntEntry]

    Return source pairs in deterministic forward-slot order.

    StaticIntBiMap::from_entries

    source
    fn StaticIntBiMap::from_entries(entries : Array[IntEntry]) -> Result[StaticIntBiMap, MphfError]

    Build a checked immutable one-to-one map. Both source keys and values must be non-negative because each becomes an MPHF key in one direction.

    StaticIntBiMap::get_by_key

    source
    fn StaticIntBiMap::get_by_key(self : StaticIntBiMap, key : Int) -> Int?

    Look up the unique value associated with one source key.

    StaticIntBiMap::get_by_value

    source
    fn StaticIntBiMap::get_by_value(self : StaticIntBiMap, value : Int) -> Int?

    Look up the unique source key associated with one value.

    StaticIntBiMap::len

    source
    fn StaticIntBiMap::len(self : StaticIntBiMap) -> Int

    Return the number of one-to-one pairs.

    StaticIntBiMap::stats

    source

    Return forward construction diagnostics. Reverse diagnostics can differ because values produce a different hypergraph, so callers can inspect the reverse map explicitly through its validated serialized form.

    StaticIntBiMap::validate

    source
    fn StaticIntBiMap::validate(self : StaticIntBiMap) -> Result[Unit, MphfError]

    Verify both maps are individually valid and mutually inverse. This catches a cross-payload substitution that ordinary nested map decoding cannot see.

    StaticIntMap

    source
    pub struct StaticIntMap {
      mphf : Mphf
      keys_by_slot : Array[Int]
      values_by_slot : Array[Int]
    }

    An exact immutable integer map with constant-time lookup after building.

    StaticIntMap::apply_patch

    source
    fn StaticIntMap::apply_patch(self : StaticIntMap, patch : StaticIntMapPatch) -> Result[StaticIntMap, MphfError]

    Rebuild a map after applying deletions and replacement/insert operations. Existing values are retained only for keys absent from both patch parts.

    StaticIntMap::contains_key

    source
    fn StaticIntMap::contains_key(self : StaticIntMap, key : Int) -> Bool

    Test exact membership without exposing mapped values.

    StaticIntMap::content_equals

    source
    fn StaticIntMap::content_equals(self : StaticIntMap, other : StaticIntMap) -> Bool

    Return whether both maps contain the same key/value pairs, independent of the different MPHF layouts they may have selected during construction.

    StaticIntMap::cursor

    source

    Create a persistent cursor positioned at the first slot-ordered map entry.

    StaticIntMap::cursor_at

    source
    fn StaticIntMap::cursor_at(self : StaticIntMap, slot : Int) -> Result[StaticIntMapCursor, MphfError]

    Create a persistent map cursor at an entry slot.

    StaticIntMap::encode_words

    source
    fn StaticIntMap::encode_words(self : StaticIntMap) -> Array[Int]

    Format: [3, mphf_word_count, mphf_words..., keys..., values...].

    StaticIntMap::entries_by_slot

    source
    fn StaticIntMap::entries_by_slot(self : StaticIntMap) -> Array[IntEntry]

    Return entries in deterministic MPHF slot order. This is primarily useful for snapshot rebuilding, diagnostics, and layered-map compaction.

    StaticIntMap::fingerprint

    source

    Compute a reproducible source-manifest fingerprint for a map. Entries are normalized by key, so its value is independent of MPHF slot placement.

    StaticIntMap::from_entries

    source
    fn StaticIntMap::from_entries(entries : Array[IntEntry]) -> Result[StaticIntMap, MphfError]

    Construct a checked immutable map from distinct integer keys.

    StaticIntMap::from_entries_with_options

    source
    fn StaticIntMap::from_entries_with_options(entries : Array[IntEntry], options : MphfBuildOptions) -> Result[StaticIntMap, MphfError]

    Build an exact static map using an explicit MPHF construction policy.

    StaticIntMap::get

    source
    fn StaticIntMap::get(self : StaticIntMap, key : Int) -> Int?

    Retrieve a value only when the queried key exactly matches its slot key.

    StaticIntMap::get_many

    source
    fn StaticIntMap::get_many(self : StaticIntMap, keys : Array[Int]) -> Array[Int?]

    Probe many map keys at once. Result positions correspond exactly to query positions; misses are represented by None.

    StaticIntMap::keys_by_slot

    source
    fn StaticIntMap::keys_by_slot(self : StaticIntMap) -> Array[Int]

    Return all map keys in deterministic MPHF slot order.

    StaticIntMap::len

    source
    fn StaticIntMap::len(self : StaticIntMap) -> Int

    Number of entries in this immutable map.

    StaticIntMap::merge_prefer_right

    source
    fn StaticIntMap::merge_prefer_right(self : StaticIntMap, other : StaticIntMap) -> Result[StaticIntMap, MphfError]

    Merge two maps into a new static map. Values in other take precedence for equal keys; this is the one-segment equivalent of a two-layer map lookup.

    StaticIntMap::query_summary

    source
    fn StaticIntMap::query_summary(self : StaticIntMap, keys : Array[Int]) -> LookupSummary

    Count exact hit and miss outcomes for a batch of map probes.

    StaticIntMap::stats

    source
    fn StaticIntMap::stats(self : StaticIntMap) -> MphfStats

    Return the construction diagnostics for this map.

    StaticIntMap::validate

    source
    fn StaticIntMap::validate(self : StaticIntMap) -> Result[Unit, MphfError]

    Verify every retained source key routes to its recorded map slot and that the key/value arrays have matching cardinality.

    StaticIntMapCursor

    source
    pub struct StaticIntMapCursor {
      keys_by_slot : Array[Int]
      values_by_slot : Array[Int]
      next_slot : Int
    }

    A persistent cursor over slot-ordered static map entries.

    StaticIntMapCursor::collect_remaining

    source
    fn StaticIntMapCursor::collect_remaining(self : StaticIntMapCursor) -> Array[IntEntry]

    Materialize all unread map entries in deterministic slot order.

    StaticIntMapCursor::next

    source

    Consume at most one map entry and return the successor cursor.

    StaticIntMapCursor::remaining

    source
    fn StaticIntMapCursor::remaining(self : StaticIntMapCursor) -> Int

    Return the number of unread map entries in this cursor.

    StaticIntMapPatch

    source
    pub(all) struct StaticIntMapPatch {
      upserts : Array[IntEntry]
      removals : Array[Int]
    }

    A checked edit plan for rebuilding a static map from a previous snapshot.

    StaticIntMapPatch::encode_words

    source
    fn StaticIntMapPatch::encode_words(self : StaticIntMapPatch) -> Array[Int]

    Encode a validated map patch. Upserts are stored in ascending key order so the byte-for-byte word representation is independent of caller order.

    Format: [11, upsert_count, key, value..., removal_count, removals...].

    StaticIntMapPatch::new

    source
    fn StaticIntMapPatch::new(upserts : Array[IntEntry], removals : Array[Int]) -> Result[StaticIntMapPatch, MphfError]

    Construct a validated map edit plan. Upserts replace values by key, while removals delete keys; an ambiguous key on both sides is rejected.

    StaticIntMapPatch::removal_count

    source
    fn StaticIntMapPatch::removal_count(self : StaticIntMapPatch) -> Int

    Return the number of removals recorded by this patch.

    StaticIntMapPatch::removals

    source
    fn StaticIntMapPatch::removals(self : StaticIntMapPatch) -> Array[Int]

    Return a sorted defensive copy of map removals.

    StaticIntMapPatch::upsert_count

    source
    fn StaticIntMapPatch::upsert_count(self : StaticIntMapPatch) -> Int

    Return the number of upserts recorded by this patch.

    StaticIntMapPatch::upserts

    source

    Return sorted defensive copies of map upserts in key order.

    StaticIntMultiMap

    source
    pub struct StaticIntMultiMap {
      mphf : Mphf
      keys_by_slot : Array[Int]
      offsets_by_slot : Array[Int]
      values : Array[Int]
    }

    An exact immutable map from one integer key to an ordered, non-empty value slice. The MPHF indexes distinct keys, while values are stored compactly in one contiguous array.

    StaticIntMultiMap::cursor

    source

    Create a persistent cursor positioned before the first multimap value.

    StaticIntMultiMap::encode_words

    source
    fn StaticIntMultiMap::encode_words(self : StaticIntMultiMap) -> Array[Int]

    Deterministically encode a multimap. The representation keeps the same checked MPHF and slot ranges used at runtime.

    Format: [6, mphf_word_count, mphf_words..., keys..., offsets..., values...].

    StaticIntMultiMap::entries

    source

    Return all entries in deterministic slot order. Values within each key retain the input order supplied to from_entries.

    StaticIntMultiMap::from_entries

    source
    fn StaticIntMultiMap::from_entries(entries : Array[IntMultiEntry]) -> Result[StaticIntMultiMap, MphfError]

    Build an exact immutable multimap. Repeated keys are grouped, while values associated with the same key retain the order in which they were supplied.

    StaticIntMultiMap::get_all

    source
    fn StaticIntMultiMap::get_all(self : StaticIntMultiMap, key : Int) -> Array[Int]

    Return a fresh array containing the values for one exact key. Unknown and negative keys return an empty array, which makes probe-heavy clients simple.

    StaticIntMultiMap::get_all_many

    source
    fn StaticIntMultiMap::get_all_many(self : StaticIntMultiMap, keys : Array[Int]) -> Array[Array[Int]]

    Probe many multimap keys at once. Each returned sub-array is independent, so callers can safely mutate their own result without touching the index.

    StaticIntMultiMap::len

    source
    fn StaticIntMultiMap::len(self : StaticIntMultiMap) -> Int

    Return the number of distinct keys held by the multimap.

    StaticIntMultiMap::stats

    source

    Return the MPHF construction diagnostics for the distinct-key index.

    StaticIntMultiMap::validate

    source
    fn StaticIntMultiMap::validate(self : StaticIntMultiMap) -> Result[Unit, MphfError]

    Verify a multimap's MPHF slots and its contiguous value ranges.

    StaticIntMultiMap::value_count

    source
    fn StaticIntMultiMap::value_count(self : StaticIntMultiMap) -> Int

    Return the total number of key/value input items held by the multimap.

    StaticIntMultiMap::value_count_for

    source
    fn StaticIntMultiMap::value_count_for(self : StaticIntMultiMap, key : Int) -> Int

    Count values for one exact key without allocating an output array.

    StaticIntMultiMapCursor

    source
    pub struct StaticIntMultiMapCursor {
      keys_by_slot : Array[Int]
      offsets_by_slot : Array[Int]
      values : Array[Int]
      slot : Int
      value_index : Int
    }

    A persistent cursor over every entry of a static multimap. Equal-key values are visited consecutively in their original input order.

    StaticIntMultiMapCursor::collect_remaining

    source

    Materialize every unread multimap entry by advancing a local cursor.

    StaticIntMultiMapCursor::next

    source

    Consume at most one multimap key/value item. A multimap always has at least one value per key when built through the public constructor or decoder.

    StaticIntMultiMapCursor::remaining

    source

    Count values that have not been yielded. The loop keeps the operation allocation-free and remains correct even for a validated zero-length range.

    StaticSet

    source
    pub struct StaticSet {
      mphf : Mphf
      keys_by_slot : Array[Int]
    }

    An exact static membership set backed by an MPHF and slot-ordered keys.

    StaticSet::apply_patch

    source
    fn StaticSet::apply_patch(self : StaticSet, patch : StaticSetPatch) -> Result[StaticSet, MphfError]

    Rebuild a static set after applying this edit plan. Removing an absent key and adding an existing key are intentionally idempotent operations.

    StaticSet::contains

    source
    fn StaticSet::contains(self : StaticSet, key : Int) -> Bool

    Test exact membership of a non-negative key.

    StaticSet::contains_all

    source
    fn StaticSet::contains_all(self : StaticSet, keys : Array[Int]) -> Bool

    Test whether every supplied key belongs to this exact static set. An empty query succeeds, which makes this useful for validating optional filters.

    StaticSet::content_equals

    source
    fn StaticSet::content_equals(self : StaticSet, other : StaticSet) -> Bool

    Compare set contents without observing construction seeds or slot order.

    StaticSet::cursor

    source
    fn StaticSet::cursor(self : StaticSet) -> StaticSetCursor

    Create a persistent cursor positioned at the first slot-ordered set key.

    StaticSet::cursor_at

    source
    fn StaticSet::cursor_at(self : StaticSet, slot : Int) -> Result[StaticSetCursor, MphfError]

    Create a persistent cursor at one set slot. This is useful for checkpointed scans after an external consumer has durably processed a prefix.

    StaticSet::diff_to

    source
    fn StaticSet::diff_to(self : StaticSet, other : StaticSet) -> KeySetDiff

    Compare two checked static sets without exposing their slot layout.

    StaticSet::difference

    source
    fn StaticSet::difference(self : StaticSet, other : StaticSet) -> Result[StaticSet, MphfError]

    Rebuild keys owned by self but absent from other.

    StaticSet::encode_words

    source
    fn StaticSet::encode_words(self : StaticSet) -> Array[Int]

    Format: [2, mphf_word_count, mphf_words..., slot_ordered_keys...].

    StaticSet::filter_missing

    source
    fn StaticSet::filter_missing(self : StaticSet, keys : Array[Int]) -> Array[Int]

    Return all input keys absent from this set, preserving query order.

    StaticSet::filter_present

    source
    fn StaticSet::filter_present(self : StaticSet, keys : Array[Int]) -> Array[Int]

    Return all input keys that are present, preserving query order and repeated probes. This is deliberately different from set algebra.

    StaticSet::fingerprint

    source
    fn StaticSet::fingerprint(self : StaticSet) -> StaticIndexFingerprint

    Compute a reproducible source-manifest fingerprint for a set. The result is intended for accidental-artifact mismatch detection, not cryptographic use.

    StaticSet::from_keys

    source
    fn StaticSet::from_keys(keys : Array[Int]) -> Result[StaticSet, MphfError]

    confirms it, so unknown keys cannot become false positives.

    StaticSet::from_keys_with_options

    source
    fn StaticSet::from_keys_with_options(keys : Array[Int], options : MphfBuildOptions) -> Result[StaticSet, MphfError]

    Build an exact static set using an explicit MPHF construction policy.

    StaticSet::intersection

    source
    fn StaticSet::intersection(self : StaticSet, other : StaticSet) -> Result[StaticSet, MphfError]

    Rebuild keys common to both static sets. An empty intersection returns EmptyInput, because an MPHF has no valid zero-key representation.

    StaticSet::is_subset_of

    source
    fn StaticSet::is_subset_of(self : StaticSet, other : StaticSet) -> Bool

    Return whether every key in self is also present in other.

    StaticSet::keys_by_slot

    source
    fn StaticSet::keys_by_slot(self : StaticSet) -> Array[Int]

    Return the keys in MPHF slot order for diagnostics and deterministic tests.

    StaticSet::len

    source
    fn StaticSet::len(self : StaticSet) -> Int

    Number of keys in this immutable set.

    StaticSet::overlaps

    source
    fn StaticSet::overlaps(self : StaticSet, other : StaticSet) -> Bool

    Return whether at least one key belongs to both exact static sets.

    StaticSet::query_summary

    source
    fn StaticSet::query_summary(self : StaticSet, keys : Array[Int]) -> LookupSummary

    Count exact hit and miss outcomes for a batch of set probes.

    StaticSet::stats

    source
    fn StaticSet::stats(self : StaticSet) -> MphfStats

    Return the construction diagnostics for this set.

    StaticSet::symmetric_difference

    source
    fn StaticSet::symmetric_difference(self : StaticSet, other : StaticSet) -> Result[StaticSet, MphfError]

    Rebuild keys appearing in exactly one source set.

    StaticSet::union

    source
    fn StaticSet::union(self : StaticSet, other : StaticSet) -> Result[StaticSet, MphfError]

    Rebuild the exact union of two static sets. The output has one MPHF, which is generally cheaper to query than retaining two independent segments.

    StaticSet::validate

    source
    fn StaticSet::validate(self : StaticSet) -> Result[Unit, MphfError]

    Verify every retained source key routes to its recorded set slot.

    StaticSetCursor

    source
    pub struct StaticSetCursor {
      keys_by_slot : Array[Int]
      next_slot : Int
    }

    A persistent cursor over slot-ordered set keys. Each next call returns a new cursor, so callers can safely retain checkpoints for later replay.

    StaticSetCursor::collect_remaining

    source
    fn StaticSetCursor::collect_remaining(self : StaticSetCursor) -> Array[Int]

    Materialize the unread suffix of a set cursor in slot order.

    StaticSetCursor::is_exhausted

    source
    fn StaticSetCursor::is_exhausted(self : StaticSetCursor) -> Bool

    Return whether the cursor has no unread key.

    StaticSetCursor::next

    source
    fn StaticSetCursor::next(self : StaticSetCursor) -> (Int?, StaticSetCursor)

    Consume at most one set key. The original cursor is unchanged; None signals exhaustion and returns an equivalent exhausted cursor.

    StaticSetCursor::remaining

    source
    fn StaticSetCursor::remaining(self : StaticSetCursor) -> Int

    Return the number of unread keys in this set cursor.

    StaticSetPatch

    source
    pub(all) struct StaticSetPatch {
      additions : Array[Int]
      removals : Array[Int]
    }

    A checked edit plan for rebuilding a static set from a previous snapshot.

    StaticSetPatch::addition_count

    source
    fn StaticSetPatch::addition_count(self : StaticSetPatch) -> Int

    Return the number of inserted keys recorded by this patch.

    StaticSetPatch::additions

    source
    fn StaticSetPatch::additions(self : StaticSetPatch) -> Array[Int]

    Return a sorted defensive copy of a patch's added keys.

    StaticSetPatch::encode_words

    source
    fn StaticSetPatch::encode_words(self : StaticSetPatch) -> Array[Int]

    Encode a validated set patch in sorted key order.

    Format: [10, addition_count, additions..., removal_count, removals...].

    StaticSetPatch::new

    source
    fn StaticSetPatch::new(additions : Array[Int], removals : Array[Int]) -> Result[StaticSetPatch, MphfError]

    Construct a validated set edit plan. Additions and removals are each deduplicated by rejection, and a key cannot belong to both sides.

    StaticSetPatch::removal_count

    source
    fn StaticSetPatch::removal_count(self : StaticSetPatch) -> Int

    Return the number of deleted keys recorded by this patch.

    StaticSetPatch::removals

    source
    fn StaticSetPatch::removals(self : StaticSetPatch) -> Array[Int]

    Return a sorted defensive copy of a patch's removed keys.

    StaticStringIntMap

    source
    pub struct StaticStringIntMap {
      mphf : Mphf
      keys_by_slot : Array[String]
      values_by_slot : Array[Int]
    }

    An exact immutable map from strings to integers.

    StaticStringIntMap::contains_key

    source
    fn StaticStringIntMap::contains_key(self : StaticStringIntMap, key : String) -> Bool

    Test exact membership without exposing a value.

    StaticStringIntMap::encode_words

    source
    fn StaticStringIntMap::encode_words(self : StaticStringIntMap) -> Array[Int]

    Deterministically encode an exact string-to-integer map. Values follow the scalar-encoded strings in the same MPHF slot order.

    Format: [14, mphf_word_count, mphf_words..., scalar_count, scalars..., values...].

    StaticStringIntMap::from_entries

    source
    fn StaticStringIntMap::from_entries(entries : Array[StringIntEntry]) -> Result[StaticStringIntMap, MphfError]

    Build a checked immutable string-to-integer map.

    StaticStringIntMap::get

    source
    fn StaticStringIntMap::get(self : StaticStringIntMap, key : String) -> Int?

    Retrieve a value only when both the MPHF slot and original string match.

    StaticStringIntMap::len

    source
    fn StaticStringIntMap::len(self : StaticStringIntMap) -> Int

    Count entries in this immutable map.

    StaticStringSet

    source
    pub struct StaticStringSet {
      mphf : Mphf
      keys_by_slot : Array[String]
    }

    collisions cannot produce a successful membership query.

    StaticStringSet::contains

    source
    fn StaticStringSet::contains(self : StaticStringSet, key : String) -> Bool

    slot-resident source string comparison.

    StaticStringSet::encode_words

    source
    fn StaticStringSet::encode_words(self : StaticStringSet) -> Array[Int]

    Deterministically encode an exact static string set as Unicode scalar words. Strings remain in MPHF slot order, so decoding can verify both the original text and its stable-hash routing.

    Format: [13, mphf_word_count, mphf_words..., scalar_count, scalars..., ...].

    StaticStringSet::from_keys

    source
    fn StaticStringSet::from_keys(keys : Array[String]) -> Result[StaticStringSet, MphfError]

    strings that collide in the 31-bit stable hash are both rejected, rather than silently constructing an ambiguous table.

    StaticStringSet::len

    source
    fn StaticStringSet::len(self : StaticStringSet) -> Int

    Return the number of source strings in this immutable set.

    StaticStringSet::stats

    source

    Return construction details for observability.

    StringIntEntry

    source
    pub(all) struct StringIntEntry {
      key : String
      value : Int
    }

    One UTF-16/Unicode-scalar string key paired with an integer value.

    compare_key_sets

    source
    fn compare_key_sets(before : Array[Int], after : Array[Int]) -> Result[KeySetDiff, MphfError]

    Compare two distinct key sets and return their rebuild-relevant delta.

    decode_mphf_words

    source
    fn decode_mphf_words(words : Array[Int]) -> Result[Mphf, MphfError]

    Decode a versioned MPHF word representation with structural validation.

    decode_segmented_int_map_words

    source
    fn decode_segmented_int_map_words(words : Array[Int]) -> Result[SegmentedIntMap, MphfError]

    Decode a layered map while rejecting empty segments and trailing words.

    decode_segmented_set_words

    source
    fn decode_segmented_set_words(words : Array[Int]) -> Result[SegmentedSet, MphfError]

    Decode a segmented set, rejecting trailing words and empty segments.

    decode_sharded_int_map_words

    source
    fn decode_sharded_int_map_words(words : Array[Int]) -> Result[ShardedIntMap, MphfError]

    Decode a sharded map and confirm its keys live in their recorded shards.

    decode_sharded_set_words

    source
    fn decode_sharded_set_words(words : Array[Int]) -> Result[ShardedSet, MphfError]

    Decode a sharded set and verify every stored key belongs to the residue class that contains it.

    decode_static_int_bimap_words

    source
    fn decode_static_int_bimap_words(words : Array[Int]) -> Result[StaticIntBiMap, MphfError]

    Decode a bidirectional map and verify that the two nested payloads describe inverse mappings, not merely two individually valid static maps.

    decode_static_int_map_patch_words

    source
    fn decode_static_int_map_patch_words(words : Array[Int]) -> Result[StaticIntMapPatch, MphfError]

    Decode a map patch, rejecting inconsistent declared lengths before any source map is rebuilt.

    decode_static_int_map_words

    source
    fn decode_static_int_map_words(words : Array[Int]) -> Result[StaticIntMap, MphfError]

    Decode an exact integer map and retain the validated MPHF slot layout.

    decode_static_int_multimap_words

    source
    fn decode_static_int_multimap_words(words : Array[Int]) -> Result[StaticIntMultiMap, MphfError]

    Decode a multimap and reject malformed slot keys, malformed ranges, and trailing words. Values themselves may be any MoonBit Int.

    decode_static_set_patch_words

    source
    fn decode_static_set_patch_words(words : Array[Int]) -> Result[StaticSetPatch, MphfError]

    Decode a set patch using the same duplicate and overlap checks as direct construction. This makes patches safe to store beside a static snapshot.

    decode_static_set_words

    source
    fn decode_static_set_words(words : Array[Int]) -> Result[StaticSet, MphfError]

    Decode an exact static set and verify every stored key agrees with its slot.

    decode_static_string_int_map_words

    source
    fn decode_static_string_int_map_words(words : Array[Int]) -> Result[StaticStringIntMap, MphfError]

    Decode a static string map and validate scalar text, exact key routing, and the final value-array length.

    decode_static_string_set_words

    source
    fn decode_static_string_set_words(words : Array[Int]) -> Result[StaticStringSet, MphfError]

    Decode a static string set, rejecting malformed Unicode scalars, trailing words, duplicate routing, and any key whose hash no longer agrees with its recorded MPHF slot.

    default_build_options

    source
    fn default_build_options() -> MphfBuildOptions

    Return the conservative construction policy used by Mphf::build.

    stable_string_hash

    source
    fn stable_string_hash(value : String) -> Int

    This lightweight mixer is for stable identifiers, not for passwords, signatures, attacker-controlled routing, or any cryptographic purpose.

    Source Files

    Powered by MoonBit

    Site sourceReport issuePackagesBuild queueSkillsStatistics

    © 2026 mooncakes.io