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

v0 source pure

Package addrset provides a set of blockchain addresses backed by a B+ tree, with a read-only view type for safe cross...

Overview

Package addrset provides a set of blockchain addresses backed by a B+ tree, with a read-only view type for safe cross-realm exposure.

It mirrors the gno.land/p/moul/addrset API on a gno.land/p/nt/bptree/v0 backing: a B+ tree packs many entries per persisted node, so a stored address costs ~0.9 KB vs the one-node-per-entry AVL backing's ~2.0 KB (2.2x asymptotically, 1.6x at 10 entries; insert gas ~2.1x less). Prefer this package when sets are part of persisted realm state; the omitted Tree() escape hatch is deliberate, so the backing store never leaks.

Two behavioral differences from the AVL-backed moul package, both consequences of the in-place-mutating backing:

  • the set must NOT be mutated (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 share live tree nodes while their roots and sizes diverge (the AVL backing'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)

Functions 1

func NewReadonlySet 

1func NewReadonlySet(s *Set) *ReadonlySet
source

NewReadonlySet returns a read-only view of s.

Types 2

type ReadonlySet

struct 
1type ReadonlySet struct {
2	set *Set
3}
source

ReadonlySet is a read-only view of a *Set. Cross-package callers cannot mutate the underlying set through this type: it exposes no mutator methods and holds the *Set in an unexported field, so a foreign realm can neither reach the set nor invoke Add/Remove on it.

A ReadonlySet is a thin handle over the live Set (it does not copy or snapshot), so reads through it always reflect the Set's current contents.

Methods on ReadonlySet

func Has

method on ReadonlySet 
1func (r ReadonlySet) Has(addr address) bool
source

Has reports whether addr is in the underlying set.

func IterateByOffset

method on ReadonlySet 
1func (r ReadonlySet) IterateByOffset(offset, count int, fn func(addr address) bool) (stopped bool)
source

IterateByOffset walks the underlying set in sorted order, starting at offset and visiting up to count addresses. fn returns true to stop early; IterateByOffset returns true if iteration was stopped that way.

The wrapped Set.IterateByOffset has no return value, so the "stopped" result is synthesized from the last callback return via a closure-captured local.

func ReverseIterateByOffset

method on ReadonlySet 
1func (r ReadonlySet) ReverseIterateByOffset(offset, count int, fn func(addr address) bool) (stopped bool)
source

ReverseIterateByOffset is IterateByOffset in reverse (descending) order.

func Size

method on ReadonlySet 
1func (r ReadonlySet) Size() int
source

Size returns the number of addresses in the underlying set.

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 (no Add or Remove from the callback).

func Readonly

method on Set 
1func (s *Set) Readonly() *ReadonlySet
source

Readonly returns a read-only view of the set.

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 (no Add or Remove from the callback).

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