set

package
v0.0.0-...-622fb6d Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 2, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package set provides generic set implementations with support for ordered and thread-safe variants.

Index

Examples

Constants

This section is empty.

Variables

View Source 
var ErrNoDefaultValue = errors.New("no default value for this element")

ErrNoDefaultValue is returned by the default value function when it cannot or chooses not to provide a default value for a given element. When this error is returned, the defaultSet will not add the element to the set and will behave as if the element simply doesn't exist.

Functions

This section is empty.

Types

type OrderedSet 

type OrderedSet[T any] interface {
	// AddAll adds multiple elements to the set in order. Returns an error if any element
	// causes a hash collision or if hashing fails. If an element already exists, it is not
	// added again and its position in the order is not changed.
	AddAll(elements ...T) error

	// Add adds a single element to the set. Returns an error if the element
	// causes a hash collision or if hashing fails. If the element already exists
	// in the set, no error is returned and its position in the order is not changed.
	Add(element T) error

	// Remove removes an element from the set. Returns an error if hashing fails.
	// If the element is not in the set, no error is returned.
	Remove(element T) error

	// Clear removes all elements from the set.
	Clear()

	// Contains checks if an element exists in the set. Returns true if the element
	// exists, false otherwise. Returns an error if hashing fails or a collision is detected.
	Contains(element T) (bool, error)

	// Size returns the number of elements in the set.
	Size() int

	// Entries returns all elements in the set as a slice in insertion order.
	// The returned slice is a copy and modifications to it will not affect the set.
	Entries() []T

	// Seq returns all elements in the set as an iter.Seq in insertion order.
	Seq() iter.Seq2[int, T]

	// Union returns a new ordered set containing all elements from both sets.
	// Elements from the current set appear first in insertion order, followed by
	// elements from the other set that are not already present. Returns an error
	// if any element causes a hash collision or if hashing fails.
	Union(other OrderedSet[T]) (OrderedSet[T], error)

	// Intersection returns a new ordered set containing only elements present in both sets.
	// The order is preserved from the current set. Returns an error if any element causes
	// a hash collision or if hashing fails.
	Intersection(other OrderedSet[T]) (OrderedSet[T], error)

	// HashFunction returns the hash function used by this ordered set.
	HashFunction() hashing.HashFunc

	// Filter returns a new ordered set containing only elements that satisfy the predicate.
	// The predicate function is called for each element; if it returns true, the element is included.
	// The insertion order is preserved in the resulting set.
	Filter(predicate func(T) bool) OrderedSet[T]

	// FilterNot returns a new ordered set containing only elements that do not satisfy the predicate.
	// The predicate function is called for each element; if it returns false, the element is included.
	// The insertion order is preserved in the resulting set.
	FilterNot(predicate func(T) bool) OrderedSet[T]

	// Clone creates a shallow copy of the set, duplicating its structure and entries.
	// The keys themselves are not deep-copied; they are referenced as-is.
	// Returns a new OrderedSet instance with the same entries in the same order.
	Clone() OrderedSet[T]
}

OrderedSet is a Set that maintains insertion order of elements. Unlike the regular Set where Entries() returns elements in arbitrary order, OrderedSet.Entries() returns elements in the order they were added.

func NewDefaultOrderedSet 

func NewDefaultOrderedSet[T collectable.Collectable[T]](
	storageSet OrderedSet[T],
	getDefaultValue func(T) (T, error),
) OrderedSet[T]

NewDefaultOrderedSet creates an OrderedSet that automatically generates default values for missing elements. When Contains is called with an element that doesn't exist, the getDefaultValue function is invoked to generate a value, which is then added to the set (at the end of the insertion order) and returned.

The getDefaultValue function should return ErrNoDefaultValue when it cannot or chooses not to provide a default value. In that case, the set behaves as if the element doesn't exist.

If storageSet is already a defaultOrderedSet, this function clones it and replaces the default value function with the new one provided.

Unlike the standard Set, OrderedSet preserves the insertion order of elements. When a default value is generated and added, it's appended to the end of the current insertion order.

Parameters:

  • storageSet: The underlying OrderedSet implementation to use for storage
  • getDefaultValue: Function that generates default values for missing elements

Example: 

// Create an ordered set that stores lowercase versions of strings
s := set.NewDefaultOrderedSet(
    set.NewOrderedSet[MyType](hashFunc),
    func(elem MyType) (MyType, error) {
        return elem.Normalize(), nil
    },
)
contains, _ := s.Contains(elem) // Returns true and adds normalized version to end

// Create a set that refuses to provide defaults
s2 := set.NewDefaultOrderedSet(
    set.NewOrderedSet[MyType](hashFunc),
    func(elem MyType) (MyType, error) {
        return zero.Value[MyType](), set.ErrNoDefaultValue
    },
)
contains, _ := s2.Contains(elem) // Returns false without adding

func NewOrderedSet 

func NewOrderedSet[T collectable.Collectable[T]](hash hashing.HashFunc) OrderedSet[T]

NewOrderedSet creates a new OrderedSet with the provided hash function. The hash function is used to determine uniqueness of elements. Elements are returned in insertion order by Entries().

func NewThreadSafeOrderedSet 

func NewThreadSafeOrderedSet[T any](s OrderedSet[T]) OrderedSet[T]

NewThreadSafeOrderedSet wraps an existing OrderedSet implementation with thread-safe access using sync.RWMutex. It provides concurrent read/write access to the underlying ordered set while preserving the OrderedSet interface.

The wrapper uses read-write locks to allow multiple concurrent readers or exclusive writer access. Write operations (Add, AddAll, Remove, Clear) acquire exclusive locks, while read operations (Contains, Size, Entries, Seq, Union, Intersection) use shared read locks for better concurrency.

Example usage: 

unsafeSet := set.NewOrderedSet[string](hashing.Sha256)
safeSet := set.NewThreadSafeOrderedSet(unsafeSet)
safeSet.Add("element") // thread-safe

type Set 

type Set[T any] interface {
	// AddAll adds multiple elements to the set. Returns an error if any element
	// causes a hash collision or if hashing fails.
	AddAll(elements ...T) error

	// Add adds a single element to the set. Returns an error if the element
	// causes a hash collision or if hashing fails. If the element already exists
	// in the set, no error is returned.
	Add(element T) error

	// Remove removes an element from the set. Returns an error if hashing fails.
	// If the element is not in the set, no error is returned.
	Remove(element T) error

	// Clear removes all elements from the set.
	Clear()

	// Contains checks if an element exists in the set. Returns true if the element
	// exists, false otherwise. Returns an error if hashing fails or a collision is detected.
	Contains(element T) (bool, error)

	// Size returns the number of elements in the set.
	Size() int

	// Entries returns all elements in the set as a slice. The order is not guaranteed.
	Entries() []T

	// Seq returns all elements in the set as an iter.Seq. The order is not guaranteed.
	Seq() iter.Seq[T]

	// Union returns a new set containing all elements from both sets. Returns an error
	// if any element causes a hash collision or if hashing fails.
	Union(other Set[T]) (Set[T], error)

	// Intersection returns a new set containing only elements present in both sets.
	// Returns an error if any element causes a hash collision or if hashing fails.
	Intersection(other Set[T]) (Set[T], error)

	// HashFunction returns the hash function used by this set.
	HashFunction() hashing.HashFunc

	// Filter returns a new set containing only elements that satisfy the predicate.
	// The predicate function is called for each element; if it returns true, the element is included.
	Filter(predicate func(T) bool) Set[T]

	// FilterNot returns a new set containing only elements that do not satisfy the predicate.
	// The predicate function is called for each element; if it returns false, the element is included.
	FilterNot(predicate func(T) bool) Set[T]

	// Clone creates a shallow copy of the set, duplicating its structure and entries.
	// The keys themselves are not deep-copied; they are referenced as-is.
	// Returns a new Set instance with the same entries.
	Clone() Set[T]
}

A Set is a collection of unique elements. Uniqueness is determined by the HashFunc provided when the Set is created, as well as how the object has implemented the Hashable and Comparable interfaces. If a collision is detected, an error is returned.

func NewDefaultSet 

func NewDefaultSet[T collectable.Collectable[T]](
	storageSet Set[T],
	getDefaultValue func(T) (T, error),
) Set[T]

NewDefaultSet creates a Set that automatically generates default values for missing elements. When Contains is called with an element that doesn't exist, the getDefaultValue function is invoked to generate a value, which is then added to the set and returned.

The getDefaultValue function should return ErrNoDefaultValue when it cannot or chooses not to provide a default value. In that case, the set behaves as if the element doesn't exist.

If storageSet is already a defaultSet, this function clones it and replaces the default value function with the new one provided.

Parameters:

  • storageSet: The underlying Set implementation to use for storage
  • getDefaultValue: Function that generates default values for missing elements

Example: 

// Create a set that stores lowercase versions of strings
s := set.NewDefaultSet(
    set.NewSet[MyType](hashFunc),
    func(elem MyType) (MyType, error) {
        return elem.Normalize(), nil
    },
)
contains, _ := s.Contains(elem) // Returns true and adds normalized version to set

// Create a set that refuses to provide defaults
s2 := set.NewDefaultSet(
    set.NewSet[MyType](hashFunc),
    func(elem MyType) (MyType, error) {
        return zero.Value[MyType](), set.ErrNoDefaultValue
    },
)
contains, _ := s2.Contains(elem) // Returns false without adding

func NewRedBlackTreeSet 

func NewRedBlackTreeSet[K sortable.Sortable[K]]() Set[K]

NewRedBlackTreeSet creates a new empty red-black tree set. The returned set maintains elements in sorted order and provides O(log n) operations.

Example 
s := NewRedBlackTreeSet[sortable.Int]()

_ = s.Add(sortable.Int(5))
_ = s.Add(sortable.Int(2))
_ = s.Add(sortable.Int(8))
_ = s.Add(sortable.Int(1))

for elem := range s.Seq() {
	fmt.Println(elem)
}

Output:

1
2
5
8

func NewSet 

func NewSet[T collectable.Collectable[T]](hash hashing.HashFunc, items ...T) Set[T]

NewSet creates a new Set with the provided hash function. The hash function is used to determine uniqueness of elements.

func NewSetWithSize 

func NewSetWithSize[T collectable.Collectable[T]](hash hashing.HashFunc, size int, items ...T) Set[T]

NewSetWithSize creates a new Set with the provided hash function and pre-allocated capacity. The size parameter specifies the initial capacity of the underlying map, which can improve performance when the expected size is known in advance.

func NewThreadSafeSet 

func NewThreadSafeSet[T collectable.Collectable[T]](s Set[T]) Set[T]

NewThreadSafeSet wraps an existing Set implementation with thread-safe access using sync.RWMutex. It provides concurrent read/write access to the underlying set while preserving the Set interface.

The wrapper uses read-write locks to allow multiple concurrent readers or exclusive writer access. Write operations (Add, AddAll, Remove, Clear) acquire exclusive locks, while read operations (Contains, Size, Entries, Seq, Union, Intersection) use shared read locks for better concurrency.

Example usage: 

unsafeSet := set.NewSet[string](hashing.Sha256)
safeSet := set.NewThreadSafeSet(unsafeSet)
safeSet.Add("element") // thread-safe

type StringOrderedSet 

type StringOrderedSet struct {
	// contains filtered or unexported fields
}

StringOrderedSet is a specialized OrderedSet implementation for string elements that maintains insertion order. It provides additional methods for sorted access while preserving the original insertion order in the main Entries() method.

func NewStringOrderedSet 

func NewStringOrderedSet(hash hashing.HashFunc) *StringOrderedSet

NewStringOrderedSet creates a new StringOrderedSet with the provided hash function. Elements are maintained in insertion order and can be retrieved in that order via Entries().

func (*StringOrderedSet) Add 

func (s *StringOrderedSet) Add(element string) error

Add adds a single string element to the set. If the element already exists, no error is returned and its position in the order is not changed.

func (*StringOrderedSet) AddAll 

func (s *StringOrderedSet) AddAll(element ...string) error

AddAll adds multiple string elements to the set in order. If an element already exists, it is not added again and its position in the order is not changed.

func (*StringOrderedSet) Clear 

func (s *StringOrderedSet) Clear()

Clear removes all elements from the set.

func (*StringOrderedSet) Clone 

func (s *StringOrderedSet) Clone() *StringSet

Clone creates a shallow copy of the StringOrderedSet, duplicating its structure and entries. The strings themselves are not deep-copied (strings in Go are immutable). Returns a new StringOrderedSet instance with the same entries.

func (*StringOrderedSet) Contains 

func (s *StringOrderedSet) Contains(element string) (bool, error)

Contains checks if a string element exists in the set.

func (*StringOrderedSet) Entries 

func (s *StringOrderedSet) Entries() []string

Entries returns all string elements in the set in insertion order. The returned slice is a copy and modifications to it will not affect the set.

func (*StringOrderedSet) HashFunction 

func (s *StringOrderedSet) HashFunction() hashing.HashFunc

HashFunction returns the hash function used by this set.

func (*StringOrderedSet) Intersection 

func (s *StringOrderedSet) Intersection(other *StringOrderedSet) (*StringOrderedSet, error)

Intersection returns a new StringOrderedSet containing only elements present in both sets. The order is preserved from the current set.

func (*StringOrderedSet) NaturalSortedEntries 

func (s *StringOrderedSet) NaturalSortedEntries() []string

NaturalSortedEntries returns all string elements in the set sorted using natural sort order. Natural sort treats numbers within strings numerically (e.g., "file2" comes before "file10"). This does not affect the insertion order maintained by the set.

func (*StringOrderedSet) Remove 

func (s *StringOrderedSet) Remove(element string) error

Remove removes a string element from the set.

func (*StringOrderedSet) Seq 

func (s *StringOrderedSet) Seq() iter.Seq2[int, string]

Seq returns all string elements in the set as an iter.Seq2 in insertion order.

func (*StringOrderedSet) Size 

func (s *StringOrderedSet) Size() int

Size returns the number of elements in the set.

func (*StringOrderedSet) SortedEntries 

func (s *StringOrderedSet) SortedEntries() []string

SortedEntries returns all string elements in the set sorted alphabetically. This does not affect the insertion order maintained by the set.

func (*StringOrderedSet) Union 

func (s *StringOrderedSet) Union(other *StringOrderedSet) (*StringOrderedSet, error)

Union returns a new StringOrderedSet containing all elements from both sets. Elements from the current set appear first in insertion order, followed by elements from the other set that are not already present, also in their insertion order.

type StringSet 

type StringSet struct {
	// contains filtered or unexported fields
}

StringSet is a specialized Set implementation for string elements. It provides additional methods for sorting entries.

func NewStringSet 

func NewStringSet(hash hashing.HashFunc) *StringSet

NewStringSet creates a new StringSet with the provided hash function.

func (*StringSet) Add 

func (s *StringSet) Add(element string) error

Add adds a single string element to the set.

func (*StringSet) AddAll 

func (s *StringSet) AddAll(element ...string) error

AddAll adds multiple string elements to the set.

func (*StringSet) Clear 

func (s *StringSet) Clear()

Clear removes all elements from the set.

func (*StringSet) Clone 

func (s *StringSet) Clone() *StringSet

Clone creates a shallow copy of the StringSet, duplicating its structure and entries. The strings themselves are not deep-copied (strings in Go are immutable). Returns a new StringSet instance with the same entries.

func (*StringSet) Contains 

func (s *StringSet) Contains(element string) (bool, error)

Contains checks if a string element exists in the set.

func (*StringSet) Entries 

func (s *StringSet) Entries() []string

Entries returns all string elements in the set. The order is not guaranteed.

func (*StringSet) Intersection 

func (s *StringSet) Intersection(other *StringSet) (*StringSet, error)

Intersection returns a new StringSet containing only elements present in both sets.

func (*StringSet) NaturalSortedEntries 

func (s *StringSet) NaturalSortedEntries() []string

NaturalSortedEntries returns all string elements in the set sorted using natural sort order. Natural sort treats numbers within strings numerically (e.g., "file2" comes before "file10").

func (*StringSet) Remove 

func (s *StringSet) Remove(element string) error

Remove removes a string element from the set.

func (*StringSet) Seq 

func (s *StringSet) Seq() iter.Seq[string]

Seq returns all string elements in the set as an iter.Seq. The order is not guaranteed.

func (*StringSet) Size 

func (s *StringSet) Size() int

Size returns the number of elements in the set.

func (*StringSet) SortedEntries 

func (s *StringSet) SortedEntries() []string

SortedEntries returns all string elements in the set sorted alphabetically.

func (*StringSet) Union 

func (s *StringSet) Union(other *StringSet) (*StringSet, error)

Union returns a new StringSet containing all elements from both sets.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.