VisibleOrderBuffer<TKey> class

Maintains the tree's flattened visible order as a dense buffer of nids (not keys), plus a reverse nid → visible-index map for O(1) membership queries.

The order buffer (orderNids) is sized independently and grown by doubling on insert. The reverse-index buffer (indexByNid) is a per-nid dense array that must be grown in lockstep with every other per-nid array maintained by the controller: call resizeIndex from the same path that grows _parentByNid, _depthByNid, and friends.

Does not own the registry; the registry is passed in and used to translate TKey ↔ nid on the public boundary.

Mutating operations invoke the onOrderMutated callback so the owner can invalidate derived caches (e.g. the full-extent prefix sum).

Operations that change an individual nid's membership in the order also invoke the per-nid onNidAdded / onNidRemoved callbacks so owners can maintain per-nid aggregates incrementally (e.g. the visible-subtree-size cache). These are not fired from the bulk clear / reset paths — those expect the owner to perform a wholesale rebuild of derived state instead of processing N individual events.

Constructors

VisibleOrderBuffer({required NodeIdRegistry<TKey> registry, required void onOrderMutated(), void onNidAdded(int nid)?, void onNidRemoved(int nid)?})

Properties

hashCode → int

The hash code for this object.

no setter, inherited

indexByNid → Int32List

Underlying reverse-index buffer. Read-only access for hot loops.

no setter

length → int

Number of entries currently in the visible order.

no setter

orderNids → Int32List

Underlying nid buffer. Read-only access for hot loops — do not mutate directly; use the insert/remove methods. Entries beyond length carry stale data from prior mutations.

no setter

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

Methods

addKey(TKey key) → void

Appends key's nid to the tail of the order. key must be registered.

clear() → void

Zeros length but keeps the order and reverse-index buffers allocated so follow-up inserts can reuse them without realloc. Callers that want the reverse map cleared too must call resetIndexAll separately — this method does not touch it.

clearIndexByNid(int nid) → void

Clears the reverse-index slot for nid directly. Used by the controller during nid allocation/release to reset per-nid state.

clearIndexOf(TKey key) → void

Marks key as not visible. Safe on an unregistered key.

contains(TKey key) → bool

Whether key is currently in the visible order.

debugAssertConsistent() → void

Debug-only: asserts the order and reverse-index agree on every live entry, and that the number of non-sentinel reverse-index entries matches length. Wrapped in assert(...) so release builds skip it.

indexOf(TKey key) → int

Visible position of key, or kNotVisible if key is not in the order (or not registered). O(1).

insertAllKeys(int index, List<TKey> keys) → void

Inserts the nids of keys at visible position index, preserving their relative order. Each key must be registered.

insertKey(int index, TKey key) → void

Inserts key's nid at visible position index. key must be registered.

insertNid(int index, int nid) → void

Inserts nid at visible position index, shifting the suffix right. nid must be live.

keyAt(int i) → TKey

Returns the key at visible position i. Unchecked — i must satisfy 0 <= i < length.

nidAt(int i) → int

Returns the nid at visible position i. Unchecked — i must satisfy 0 <= i < length.

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

rebuildIndex() → void

Rebuilds indexByNid from the current order buffer. Use after bulk rewrites that leave the reverse map stale.

reindexFrom(int startIndex) → void

Refreshes indexByNid entries for positions in [startIndex, length). Call after inserts at startIndex or after a contiguous removal that shifted the suffix.

removeAt(int index) → void

Removes the entry at visible position index, shifting the suffix left by one.

removeRange(int start, int end) → void

Removes entries in [start, end), shifting the suffix left.

removeWhereKeyIn(Set<TKey> keys) → void

Compacts the order by dropping every entry whose key is in keys, or whose nid has been released. Preserves the relative order of kept entries.

reset() → void

Full reset: zeros length and releases both the order buffer and the reverse-index buffer back to empty. Used on controller-wide clear.

resetIndexAll() → void

Resets every reverse-index slot to kNotVisible.

resizeIndex(int capacity) → void

Grows the reverse-index array to at least capacity. New slots are initialised to kNotVisible. Call from the same code path that grows every other per-nid dense array the controller maintains.

setIndexByNid(int nid, int index) → void

Writes index into the reverse-index slot for nid. nid must be live. Does not touch the order buffer.

toString() → String

A string representation of this object.

inherited

Operators

operator ==(Object other) → bool

The equality operator.

inherited

Constants

kNotVisible → const int

Sentinel in indexByNid meaning "not currently in the visible order". Freed nids also carry this value so a recycled nid starts invisible.