Search Apps Documentation Source Content File Folder Download Copy Actions Download State String Boolean Number Struct Map Slice Pointer Function Closure Reference Nil Package Type Interface Unknown

v1 source pure

Package addrset provides a set of blockchain addresses, backed by a B+ tree.

Readme View source

gno.land/p/moul/addrset/v1

A set of blockchain addresses, backed by a B+ tree (gno.land/p/nt/bptree).

The B+ tree successor to p/moul/addrset/v0 (AVL-backed). v1 because the backing data structure — and thus the on-chain storage layout — changed (a compatibility change ⇒ new version). A B+ tree packs many entries per persisted node, so a stored address costs ~0.9 KB vs the AVL backing's ~2.0 KB, and inserts spend materially less gas — prefer v1 for persisted realm state.

1import "gno.land/p/moul/addrset/v1"
2
3var set addrset.Set // zero value is an empty, usable set
4set.Add(addr)       // true (newly added)
5set.Has(addr)       // true
6set.Remove(addr)    // true (was present)
7set.IterateByOffset(0, 10, func(a address) bool { return false })

Differences from v1: the Tree() escape hatch is removed (the backing store never leaks); and — because the B+ tree mutates in place — do not Add/Remove from inside an iteration callback, and do not copy a non-zero Set by value.

Part of moul/gno-contracts — moul's versioned gno.land contracts. See the repository for the full catalog, build/test tooling, and usage.

Dependency graph:

gno.land/p/moul/addrset/v1 dependency graph

Provenance: imported — see https://github.com/moul/gno-contracts/pull/2 for context and metadata.

⚠️ Disclaimer: provided as-is, without warranty; not security-audited. Full disclaimer: DISCLAIMER.

Overview

Package addrset provides a set of blockchain addresses, backed by a B+ tree.

It is the B+ tree successor to gno.land/p/moul/addrset/v0 (which is backed by an AVL tree): a bump to v1 because the backing data structure — and thus the on-chain storage layout — changed. The exported API is the same as v0 (Add/Remove/Has/Size/IterateByOffset/ReverseIterateByOffset) EXCEPT that the v0 `Tree() avl.ITree` escape hatch is intentionally removed, so the backing store never leaks across realms.

A B+ tree packs many entries per persisted node, so a stored address costs roughly ~0.9 KB vs the AVL backing's ~2.0 KB (and inserts spend materially less gas). Prefer v1 when the set is part of persisted realm state.

Two behavioral differences from v0, both consequences of the in-place- mutating B+ tree backing:

  • do NOT mutate the set (Add/Remove) from inside an iteration callback — the AVL backing's copy-on-write tolerated it, this one does not;
  • do NOT copy a non-zero Set by value — the copies would share live tree nodes while their roots and sizes diverge (v0's copies were independent snapshots).

Example:

Example
1var set addrset.Set // the zero value is an empty, usable set
2
3set.Add(addr)    // true (newly added)
4set.Has(addr)    // true
5set.Remove(addr) // true (was present)

Types 1

type Set

struct 
1type Set struct {
2	tree bptree.BPTree
3}
source

Set stores a set of addresses in sorted order. The zero value is an empty, usable set.

Methods on Set

func Add

method on Set 
1func (s *Set) Add(addr address) bool
source

Add inserts an address into the set. Returns true if the address was newly added, false if it already existed.

func Has

method on Set 
1func (s *Set) Has(addr address) bool
source

Has checks if an address exists in the set.

func IterateByOffset

method on Set 
1func (s *Set) IterateByOffset(offset int, count int, cb func(addr address) bool)
source

IterateByOffset walks through addresses in sorted order, starting at the given offset and visiting up to count addresses. The callback returns true to stop iteration. The set must not be modified during iteration.

func Remove

method on Set 
1func (s *Set) Remove(addr address) bool
source

Remove deletes an address from the set. Returns true if the address was found and removed, false if it didn't exist.

func ReverseIterateByOffset

method on Set 
1func (s *Set) ReverseIterateByOffset(offset int, count int, cb func(addr address) bool)
source

ReverseIterateByOffset walks through addresses in reverse (descending) order, starting at the given offset (counted from the end) and visiting up to count addresses. The callback returns true to stop iteration. The set must not be modified during iteration.

func Size

method on Set 
1func (s *Set) Size() int
source

Size returns the number of addresses in the set.

Imports 1

Source Files 3