addrset.gno

 1// Package addrset provides a specialized set data structure for managing unique Gno addresses.
 2//
 3// It is built on top of an AVL tree for efficient operations and maintains addresses in sorted order.
 4// This package is particularly useful when you need to:
 5//   - Track a collection of unique addresses (e.g., for whitelists, participants, etc.)
 6//   - Efficiently check address membership
 7//   - Support pagination when displaying addresses
 8//
 9// Example usage:
10//
11//	import (
12//	    "std"
13//	    "gno.land/p/moul/addrset"
14//	)
15//
16//	func MyHandler() {
17//	    // Create a new address set
18//	    var set addrset.Set
19//
20//	    // Add some addresses
21//	    addr1 := address("g1jg8mtutu9khhfwc4nxmuhcpftf0pajdhfvsqf5")
22//	    addr2 := address("g1sss5g0rkqr88k4u648yd5d3l9t4d8vvqwszqth")
23//
24//	    set.Add(addr1)  // returns true (newly added)
25//	    set.Add(addr2)  // returns true (newly added)
26//	    set.Add(addr1)  // returns false (already exists)
27//
28//	    // Check membership
29//	    if set.Has(addr1) {
30//	        // addr1 is in the set
31//	    }
32//
33//	    // Get size
34//	    size := set.Size()  // returns 2
35//
36//	    // Iterate with pagination (10 items per page, starting at offset 0)
37//	    set.IterateByOffset(0, 10, func(addr address) bool {
38//	        // Process addr
39//	        return false  // continue iteration
40//	    })
41//
42//	    // Remove an address
43//	    set.Remove(addr1)  // returns true (was present)
44//	    set.Remove(addr1)  // returns false (not present)
45//	}
46package addrset
47
48import "gno.land/p/nt/avl"
49
50type Set struct {
51	tree avl.Tree
52}
53
54// Add inserts an address into the set.
55// Returns true if the address was newly added, false if it already existed.
56func (s *Set) Add(addr address) bool {
57	return !s.tree.Set(string(addr), nil)
58}
59
60// Remove deletes an address from the set.
61// Returns true if the address was found and removed, false if it didn't exist.
62func (s *Set) Remove(addr address) bool {
63	_, removed := s.tree.Remove(string(addr))
64	return removed
65}
66
67// Has checks if an address exists in the set.
68func (s *Set) Has(addr address) bool {
69	return s.tree.Has(string(addr))
70}
71
72// Size returns the number of addresses in the set.
73func (s *Set) Size() int {
74	return s.tree.Size()
75}
76
77// IterateByOffset walks through addresses starting at the given offset.
78// The callback should return true to stop iteration.
79func (s *Set) IterateByOffset(offset int, count int, cb func(addr address) bool) {
80	s.tree.IterateByOffset(offset, count, func(key string, _ any) bool {
81		return cb(address(key))
82	})
83}
84
85// ReverseIterateByOffset walks through addresses in reverse order starting at the given offset.
86// The callback should return true to stop iteration.
87func (s *Set) ReverseIterateByOffset(offset int, count int, cb func(addr address) bool) {
88	s.tree.ReverseIterateByOffset(offset, count, func(key string, _ any) bool {
89		return cb(address(key))
90	})
91}
92
93// Tree returns the underlying AVL tree for advanced usage.
94func (s *Set) Tree() avl.ITree {
95	return &s.tree
96}