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