Collections API Reference

One key-value pair, stored inline in the map's vector. Its fields are private; read them through the forced-public key/value accessors if a macro body requires it.

Abilities materialize jointly over K and V: Entry<u64, u64> is copy + drop + store, while Entry<u64, Coin<T>> is store-only.

A map kept sorted by key. Every operation loads exactly one stored object, so it is bounded by object size (~250 KB), not by any per-transaction dynamic-field cap; lookup is O(log N) and writes are O(N).

A pure value with no UID or dynamic fields, so it embeds directly in an integrator's object, exactly like sui::vec_map::VecMap. copy/drop materialize only when both K and V allow them: SortedMap<u64, u64> is copy + drop + store; SortedMap<u64, Coin<T>> is store-only and must be drained then destroy_empty'd.

Across the supported (macro) API the backing vector is strictly increasing under the consistently supplied comparator: sorted, with no duplicate keys.

Creates a new, empty map. Takes no &mut TxContext: a SortedMap is a value, not an object.

Creates a map holding a single key/value entry. O(1); needs no comparator, since one entry is trivially sorted. For more than one entry from pre-sorted data, use from_sorted_keys_values!.

Destroys an empty map. This is the only terminal for a map whose value type lacks drop (e.g. SortedMap<K, Coin<T>>): drain every value via remove!/pop_front/pop_back first, then call this.

Aborts with ENotEmpty if the map still holds entries.

Returns the number of entries.

Returns true iff the map holds no entries.

Returns the smallest key under the comparator, or none if the map is empty. O(1). With a reverse comparator this returns the largest numeric key.

Returns the largest key under the comparator, or none if the map is empty. O(1).

Removes and returns the smallest entry as a (key, value) pair. O(N), as it shifts every remaining entry; prefer pop_back for bulk drains, which is O(1).

Aborts with EEmpty if the map is empty.

Removes and returns the largest entry as a (key, value) pair. O(1) (no shift).

Aborts with EEmpty if the map is empty.

Returns all keys in ascending comparator order as an owned vector<K>. O(N) in output size with no limit; for large or near-ceiling maps prefer the paged keys_from!. Loads exactly one stored object regardless of N.

Builds a map from parallel keys/values that MUST already be strictly increasing under lt (sorted, no duplicate keys). O(n): one pass validates each adjacent pair, then appends at the back without a per-element search. Prefer this to a loop of upsert_by!, which is O(n^2) for unsorted input. If your keys are not yet ordered, sort them under the same comparator first, then call this.

Unlike sorted_set::from_keys! (which de-duplicates), this aborts on any out-of-order or duplicate key: values are conserved (a resource V can never be silently displaced), so a duplicate cannot be collapsed away.

Aborts with EUnequalLengths if keys and values differ in length.

Aborts with EKeysNotStrictlyIncreasing if keys is not strictly increasing under lt.

from_sorted_keys_values_by! with the built-in integer <.

Aborts with EUnequalLengths or EKeysNotStrictlyIncreasing; see from_sorted_keys_values_by!.

Returns true iff key is present, under lt. Pure, total read: agrees exactly with borrow_by! succeeding, since both route through the same binary search.

contains_by! with the built-in integer <.

Immutably borrows key's value, under lt. There is deliberately no non-aborting Option<&V> variant (Move cannot put a reference in an Option); use contains_by! first when the key may be absent.

Aborts with EKeyNotFound if key is absent.

borrow_by! with the built-in integer <.

Aborts with EKeyNotFound if key is absent.

Mutably borrows key's value, under lt. Yields &mut V, never a mutable entry reference, so the key cannot be desynced from its sorted position.

Aborts with EKeyNotFound if key is absent.

borrow_mut_by! with the built-in integer <.

Aborts with EKeyNotFound if key is absent.

Inserts key/value under lt, aborting if key is already present (length + 1). key is taken by value and moved into storage; nothing is returned.

Matches sui::vec_map::insert: a strict insert that refuses to touch an existing entry, so a duplicate is always a caller bug rather than a silent overwrite. Use upsert_by! instead when replacing an existing value is the intended behavior; it returns the displaced value rather than aborting.

Aborts with EKeyAlreadyExists if key is already present.

add_by! with the built-in integer <.

Aborts with EKeyAlreadyExists if key is already present.

Inserts key/value, or replaces the value if key is already present, under lt. Returns some(old_value) on replace (length unchanged), none on a fresh insert (length + 1). The displaced value is returned and never dropped, so a resource V is safe; K must be drop only because the previously stored key is dropped on replace (last-write-wins for the key bytes, observable only under a coarse comparator).

This is a deliberate divergence from sui::vec_map::insert, which aborts on a duplicate key: upsert_by! is a total upsert. For abort-on-duplicate, prefer add! (a strict insert); or, when V has drop, assert on the returned option (assert!(m.upsert!(k, v).is_none(), E)). For a resource V the returned option cannot be dropped, so bind it, assert is_none(), and consume it with destroy_none().

upsert_by! with the built-in integer <. Returns some(old) on replace, none on a fresh insert.

Removes key's entry and returns the removed (key, value) tuple, under lt (length - 1, order preserved). Both the key and the value are returned, so a non-drop key or resource value is conserved, not destroyed.

Aborts with EKeyNotFound if key is absent.

remove_by! with the built-in integer <.

Aborts with EKeyNotFound if key is absent.

Returns the smallest key >= key when include (the ceiling), else the smallest key > key (strict next); none if there is no such key. Pure, total read. Any returned key satisfies contains_by!.

find_next_by! with the built-in integer <.

Returns the largest key <= key when include (the floor), else the largest key < key (strict prev); none if there is no such key. Pure, total read. Any returned key satisfies contains_by!.

find_prev_by! with the built-in integer <.

Returns the smallest key strictly greater than key, or none. Sugar for find_next_by! with include = false. next_key! of the tail returning none is the forward-cursor termination signal.

next_key_by! with the built-in integer <.

Returns the largest key strictly less than key, or none. Sugar for find_prev_by! with include = false. prev_key! of the head returning none is the backward-cursor termination signal.

prev_key_by! with the built-in integer <.

Returns up to limit keys in strict ascending order: a contiguous run starting at the first key >= from (when include) or > from (strict). Returns at most limit keys; fewer if the tail is reached.

Resume a page by passing the last returned key back as from with include == false: successive pages have no overlap and no gap, so concatenating them reconstructs the tail exactly. limit == 0, an empty map, or from past the tail all yield the empty vector. There is no descending pagination; use a reverse comparator.

keys_from_by! with the built-in integer <.

Returns true iff the map's entries are strictly increasing under lt, meaning sorted with no duplicate keys. This is the order check for tests, directly re-verifying the sorted-order property that production code maintains by construction but never re-validates. Call it after a _by sequence to catch a comparator mistake. Returns bool rather than asserting, so callers compose it into their own assertions.

#[test_only]: absent from published bytecode and not callable from production consumer code, but visible to a dependent's test code.

is_well_formed_by! with the built-in integer <. #[test_only].

A key was not present in the map. Raised by borrow!/borrow_mut!/remove! (and their _by forms) on an absent key.

destroy_empty was called on a non-empty map.

pop_front/pop_back was called on an empty map.

A bulk constructor (from_sorted_keys_values!/_by) received keys that are not strictly increasing under the comparator (out of order, or a duplicate).

A bulk constructor (from_sorted_keys_values!/_by) received keys and values of different lengths.

A key was already present in the map. Raised by add!/add_by! on a duplicate key.

Internal membership marker so a set can reuse SortedMap<K, Unit>. A zero-field empty struct carrying no data; it serializes to 1 BCS byte and has nothing to read or destructure.

Declared copy, drop, store so SortedSet<K> has exactly the abilities K does. It is public only because it appears in the forced-public accessors' signatures (macro hygiene); consumers never construct it or read it. Its layout is frozen at first publish and must stay a zero-field empty struct.

An ordered set of unique keys, backed by one sorted vector via SortedMap<K, Unit>.

A pure value with no UID or dynamic fields, so it embeds directly in an integrator's object, exactly like sui::vec_set::VecSet. Because the value is always the copy + drop + store Unit, SortedSet<K> has exactly the abilities K does: with a copy + drop + store key it is copy + drop + store; with a non-drop (e.g. resource) key it is store-only and must be drained then destroy_empty'd.

Across every public operation, the keys are strictly increasing under the (consistently supplied) comparator: sorted, no duplicates.

Creates a new, empty set. Takes no &mut TxContext: a SortedSet is a value, not an object. length is 0 and is_empty is true.

Returns a set containing exactly the one given key.

Destroys an empty set.

Only needed when K lacks drop (e.g. a resource key): such a SortedSet<K> is itself non-drop and cannot fall out of scope, so drain every key via remove!/pop_front/pop_back first, then call this. A set of droppable keys never needs it.

Aborts with ENotEmpty if the set still holds keys. The abort fires at this module's location, not the wrapped map's.

Returns the number of distinct keys.

Returns true iff the set holds no keys.

Returns the smallest key under the comparator, or none if the set is empty. O(1). With a reverse comparator this is the largest numeric key.

Returns the largest key under the comparator, or none if the set is empty. O(1).

Removes and returns the smallest key. Length decreases by 1. O(N): it shifts every remaining entry (pop_back is O(1)), so a front-heavy drain loop is quadratic.

Aborts with EEmpty if the set is empty, at this module's location (the wrapped map's EEmpty is never reached through here).

Removes and returns the largest key. Length decreases by 1. O(1).

Aborts with EEmpty if the set is empty, at this module's location (the wrapped map's EEmpty is never reached through here).

Returns all keys in strict ascending (comparator) order as an owned, sorted, and duplicate-free vector<K>. Not a reference: the set stores Entry<K, Unit> internally, so there is no vector<K> to borrow (contrast vec_set::keys).

O(N) in output size with no limit; this is the one read whose result scales with N. For large or near-ceiling sets, prefer the paged keys_from!.

Builds a set from a vector of keys by idempotent insertion, under $lt. O(N^2) (one search per key). Duplicates are silently collapsed; the result holds each distinct key once, in comparator order, so the result's length is the number of distinct keys, not the input length. This diverges from sui::vec_set::from_keys, which aborts on a duplicate; to reject duplicates instead, build then assert length equals the input length.

Under a coarse (non-injective) comparator, byte-distinct compare-equal keys collapse to one element keeping the last one's bytes (each re-insert is a last-write-wins upsert).

from_keys_by! with the built-in integer <. De-duplicates; see from_keys_by!. Returns a set of the distinct keys, in ascending order.

Builds a set from keys that are already sorted (non-decreasing) under $lt. O(N): one pass validates each adjacent pair and appends at the back without a per-element search, so prefer this over the O(N^2) from_keys! when the input is pre-sorted.

De-duplicates exactly like from_keys!: a run of compare-equal keys collapses to one element, keeping the last key's bytes (observable only under a coarse, non-injective comparator), matching upsert!'s last-write-wins rule. A set has no value to lose, so a duplicate collapses rather than aborts, diverging from the map's from_sorted_keys_values!, which aborts on a duplicate to conserve values. The only rejection is genuinely unsorted input; if your keys are not yet ordered, use from_keys! or sort them first.

Aborts with EKeysNotSorted if keys has an adjacent pair not sorted under lt (a strictly decreasing pair), at this module's location.

from_sorted_keys_by! with the built-in integer <. De-duplicates; see from_sorted_keys_by!. Returns a set of the distinct keys, in ascending order.

Aborts with EKeysNotSorted if keys is not ascending.

Returns true iff key is present, under $lt. Pure, total read (never aborts). O(log N).

contains_by! with the built-in integer <. Returns true iff key is present.

Inserts key, under $lt, aborting if it is already present (length + 1; contains!(key) flips false to true). Nothing is returned. The strict counterpart to the total upsert_by!: this matches sui::vec_set::insert, which also aborts on a duplicate, so a duplicate is a caller bug rather than a silent no-op. Use upsert!/upsert_by! when a duplicate should be absorbed silently (and reported via the returned bool) instead of aborting.

Aborts with sorted_map::EKeyAlreadyExists if key is already present (delegated: the abort fires at the wrapped map's location).

add_by! with the built-in integer <.

Aborts with sorted_map::EKeyAlreadyExists if key is already present.

Inserts key, under $lt. Idempotent and total (never aborts); key is taken by value. On a fresh insert: length + 1 and contains!(key) flips false to true. On a duplicate: length unchanged, but the stored key is overwritten with this one (last-write-wins for the key bytes, observable only under a coarse comparator). Returns true iff the key was newly added, false if it was already present.

Diverges from vec_set::insert (which aborts on a duplicate); for that behavior call add!, or assert on the returned bool.

upsert_by! with the built-in integer <. Returns true iff the key was newly added.

Removes key, under $lt, and returns the removed key. On success: length - 1 and contains!(key) flips true to false. Matches vec_set::remove, which also aborts when the key is absent.

Aborts with sorted_map::EKeyNotFound if key is absent (delegated: the abort fires at the wrapped map's location).

remove_by! with the built-in integer <. Returns the removed key.

Aborts with sorted_map::EKeyNotFound if key is absent.

Returns the smallest key >= key when include is true (the ceiling), else the smallest key > key (strict next); none if there is no such key. Pure, total read; any returned key satisfies contains!.

find_next_by! with the built-in integer <. Returns the ceiling/strict-next key, or none.

Returns the largest key <= key when include is true (the floor), else the largest key < key (strict prev); none if there is no such key. Pure, total read; any returned key satisfies contains!.

find_prev_by! with the built-in integer <. Returns the floor/strict-prev key, or none.

Returns the smallest key strictly greater than key, or none. Sugar for find_next_by! with include == false. next_key! of the tail returning none is the forward-cursor termination signal.

next_key_by! with the built-in integer <. Returns the strict-next key, or none.

Returns the largest key strictly less than key, or none. Sugar for find_prev_by! with include == false. prev_key! of the head returning none is the backward-cursor termination signal.

prev_key_by! with the built-in integer <. Returns the strict-prev key, or none.

Returns up to limit keys in strict ascending order: a contiguous run starting at the first key >= from (when include) or > from (strict); fewer than limit only at the tail. Resume a page by passing the last returned key back as from with include == false: successive pages have no overlap and no gap. limit == 0, an empty set, or from past the tail all yield the empty vector.

keys_from_by! with the built-in integer <. Returns up to limit keys in ascending order.

Raised when pop_front/pop_back is called on an empty set. Asserted at this module's location, distinct from the wrapped map's EEmpty.

Raised when a sorted constructor (from_sorted_keys!/from_sorted_keys_by!) receives keys that are not sorted under the comparator, meaning a strictly decreasing adjacent pair. Asserted at this module's location.

Raised when destroy_empty is called on a set that still holds keys. Asserted at this module's location, distinct from the wrapped map's ENotEmpty.