v2 source pure
Package collection provides a generic collection implementation with support for multiple indexes, including unique i...
View source
gno.land/p/moul/collection/v1
TODO: describe this package.
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:

⚠️ Disclaimer: provided as-is, without warranty; not security-audited. Full disclaimer: DISCLAIMER.
Package collection provides a generic collection implementation with support for multiple indexes, including unique indexes and case-insensitive indexes. It is designed to be used with any type and allows efficient lookups using different fields or computed values.
Example usage:
Example
1// Define a data type
2type User struct {
3 Name string
4 Email string
5 Age int
6 Username string
7 Tags []string
8}
9
10// Create a new collection
11c := collection.New()
12
13// Add indexes with different options
14c.AddIndex("name", func(v any) string {
15 return v.(*User).Name
16}, UniqueIndex)
17
18c.AddIndex("email", func(v any) string {
19 return v.(*User).Email
20}, UniqueIndex|CaseInsensitiveIndex)
21
22c.AddIndex("age", func(v any) string {
23 return strconv.Itoa(v.(*User).Age)
24}, DefaultIndex) // Non-unique index
25
26c.AddIndex("username", func(v any) string {
27 return v.(*User).Username
28}, UniqueIndex|SparseIndex) // Allow empty usernames
29
30// For tags, we index all tags for the user
31c.AddIndex("tag", func(v any) []string {
32 return v.(*User).Tags
33}, DefaultIndex) // Non-unique to allow multiple users with same tag
34
35// Store an object
36id := c.Set(&User{
37 Name: "Alice",
38 Email: "[email protected]",
39 Age: 30,
40 Tags: []string{"admin", "moderator"}, // User can have multiple tags
41})
42
43// Retrieve by any index
44entry := c.GetFirst("email", "[email protected]")
45adminUsers := c.GetAll("tag", "admin") // Find all users with admin tag
46modUsers := c.GetAll("tag", "moderator") // Find all users with moderator tag
Index options can be combined using the bitwise OR operator. Available options:
- DefaultIndex: Regular index with no special behavior
- UniqueIndex: Ensures values are unique within the index
- CaseInsensitiveIndex: Makes string comparisons case-insensitive
- SparseIndex: Skips indexing empty values (nil or empty string)
Example: UniqueIndex|CaseInsensitiveIndex for a case-insensitive unique index
2
const DefaultIndex, UniqueIndex, CaseInsensitiveIndex, SparseIndex
1const (
2 // DefaultIndex is a basic index with no special options
3 DefaultIndex IndexOption = 0
4
5 // UniqueIndex ensures no duplicate values are allowed
6 UniqueIndex IndexOption = 1 << iota
7
8 // CaseInsensitiveIndex automatically converts string values to lowercase
9 CaseInsensitiveIndex
10
11 // SparseIndex only indexes non-empty values
12 SparseIndex
13)1
5
type Collection
structCollection represents a collection of objects with multiple indexes
Methods on Collection
func AddIndex
method on CollectionAddIndex adds a new index to the collection with the specified options
Parameters:
- name: the unique name of the index (e.g., "tags")
- indexFn: a function that extracts either a string or []string from an object
- options: bit flags for index configuration (e.g., UniqueIndex)
func Delete
method on CollectionDelete removes an object by its ID and returns true if something was deleted
func Get
method on CollectionGet retrieves entries matching the given key in the specified index. Returns an iterator over the matching entries.
func GetAll
method on CollectionGetAll retrieves all entries matching the given key in the specified index.
func GetFirst
method on CollectionGetFirst returns the first matching entry or nil if none found
func GetIndex
method on CollectionGetIndex returns the underlying tree for an index
func Set
method on CollectionSet adds or updates an object in the collection. Returns a positive ID if successful. Returns 0 if:
- The object is nil
- A uniqueness constraint would be violated
- Index generation fails for any index
func Update
method on CollectionUpdate updates an existing object and returns true if successful Returns true if the update was successful. Returns false if:
- The object is nil
- The ID doesn't exist
- A uniqueness constraint would be violated
- Index generation fails for any index
If the update fails, the collection remains unchanged.
type Entry
structEntry represents a single object in the collection with its ID
type EntryIterator
structEntryIterator provides iteration over collection entries
type Index
structIndex represents an index with its configuration and data. The index function can return either:
- string: for single-value indexes
- []string: for multi-value indexes where one object can be indexed under multiple keys
The backing tree stores either a single ID or []string for multiple IDs per key.
type IndexOption
identIndexOption represents configuration options for an index using bit flags
5
- errors stdlib
- gno.land/p/nt/avl/v0 package
- gno.land/p/nt/seqid/v0 package
- gno.land/p/nt/ufmt/v0 package
- strings stdlib