Documentation
¶
Overview ¶
Package set provides a set data structure, which is a generic, unordered container of elements where no two elements can be equal according to Go's == operator.
An immutable set can be created with Of. Likewise, a mutable set can be created with NewMutable.
A mutable set can be passed into Unmodifiable, which turns it into a read-only Set view.
Set has a String method that satisfies fmt.Stringer.
The union of two sets can be created with Union.
Two sets can be compared for "equality" with Equal, returning true if they have the same elements in any order, otherwise false.
Third-party set implementations can be tested with settest.Set.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Equal ¶
func Equal[T comparable](a, b Set[T]) bool
Equal returns true if set a has the same elements as set b in any order. Otherwise, it returns false.
This method should be used over ==, the behaviour of which is undefined.
Equal follows these rules:
- Reflexive: for any potentially-nil set a, Equal(a, a) returns true.
- Symmetric: for any potentially-nil sets a and b, Equal(a, b) and Equal(b, a) have the same results.
- Transitive: for any potentially-nil sets a, b and c, if Equal(a, b) and Equal(b, c), then Equal(a, c) is true.
- Consistent: for any potentially-nil sets a and b, multiple calls to Equal(a, b) consistently returns true or consistently returns false, as long as the sets do not change.
Note: If passing in a MutableSet, Go needs the generic type to be defined explicitly, like:
a := set.NewMutable(1)
b := set.NewMutable(2)
result := set.Equal[int](a, b)
^^^^^
Example ¶
package main
import (
"fmt"
"github.com/jbduncan/go-containers/set"
)
func main() {
// Check if these two sets have the same elements in any order.
a := set.Of[string]()
a.Add("link")
b := set.Of("link")
fmt.Println(set.Equal[string](a, b)) // true
c := set.Of("ganondorf")
fmt.Println(set.Equal[string](a, c)) // false
}
Output: true false
func StringImpl ¶
func StringImpl[T comparable](s Set[T]) string
StringImpl is a helper function for implementors of Set.String.
This function is implemented in terms of Set.All, so the order of the elements in the returned string is undefined; it may even change from one call of StringImpl to the next.
Note: If passing in a MutableSet, Go needs the generic type to be defined explicitly, like:
a := set.Of(1)
b := set.Of(2)
s := set.StringImpl[int](a, b)
^^^^^
Types ¶
type MapSet ¶
type MapSet[T comparable] struct { // contains filtered or unexported fields }
func Of ¶
func Of[T comparable](elems ...T) *MapSet[T]
Of returns a new non-nil, empty MapSet, which implements Set and MutableSet. Its implementation is based on a Go map, with similar performance characteristics.
Example ¶
package main
import (
"fmt"
"github.com/jbduncan/go-containers/set"
)
func main() {
// Create a new set and put some strings in it.
exampleSet := set.Of[string]()
added := exampleSet.Add("link")
fmt.Println(added) // true
addedAgain := exampleSet.Add("link")
fmt.Println(addedAgain) // false
exampleSet.Add("zelda", "ganondorf")
// Check that the set contains everything added to it.
fmt.Println(exampleSet.Contains("link")) // true
fmt.Println(exampleSet.Contains("zelda")) // true
fmt.Println(exampleSet.Contains("ganondorf")) // true
fmt.Println(exampleSet.Contains("mario")) // false
fmt.Println(exampleSet.Len()) // 3
// Remove strings from the set.
exampleSet.Remove("zelda")
exampleSet.Remove("ganondorf")
fmt.Println(exampleSet.Contains("zelda")) // false
fmt.Println(exampleSet.Contains("ganondorf")) // false
fmt.Println(exampleSet.String()) // [link]
// Loop over all elements in the set.
for elem := range exampleSet.All() {
fmt.Println(elem) // link
}
}
Output: true false true true true false 3 false false [link] link
type MutableSet ¶
type MutableSet[T comparable] interface { Set[T] // Add adds the given element(s) to this set. If any of the elements are already present, the set will not add // those elements again. Returns true if this set changed as a result of this call, otherwise false. Add(elem T, others ...T) bool // Remove removes the given element(s) from this set. If any of the elements are already absent, the set will not // attempt to remove those elements. Returns true if this set changed as a result of this call, otherwise false. Remove(elem T, others ...T) bool }
MutableSet is a Set with additional methods for adding and removing elements.
An instance of MutableSet can be made with set.Of.
type Set ¶
type Set[T comparable] interface { // Contains returns true if this set contains the given element, otherwise it returns false. Contains(elem T) bool // Len returns the number of elements in this set. Len() int // All returns an iter.Seq that returns each and every element in this set. // // The iteration order is undefined; it may even change from one call to the next. All() iter.Seq[T] // String returns a string representation of all the elements in this set. // // The format of this string is a single "[" followed by a comma-separated list (", ") of this set's elements in // the same order as All (which is undefined and may change from one call to the next), followed by a single // "]". // // This method satisfies fmt.Stringer. String() string }
Set is a generic, unordered collection of unique elements.
An instance of Set can be made with set.Of.
type UnionSet ¶
type UnionSet[T comparable] struct { // contains filtered or unexported fields }
func Union ¶
func Union[T comparable](a, b Set[T]) UnionSet[T]
Union returns the set union of sets a and b.
The returned set is an unmodifiable view that implements Set, so changes to a and b will be reflected in the returned set.
Set.Len runs in O(b) time for the returned set.
Note: If passing in a MutableSet, Go needs the generic type to be defined explicitly, like:
a := set.Of(1)
b := set.Of(2)
u := set.Union[int](a, b)
^^^^^
type UnmodifiableSet ¶
type UnmodifiableSet[T comparable] struct { // contains filtered or unexported fields }
func Unmodifiable ¶
func Unmodifiable[T comparable](s Set[T]) UnmodifiableSet[T]
Unmodifiable wraps a given set as a read-only Set view. This prevents users from casting the given set into a MutableSet and allows for sets that can be mutated by your own code but not your users' code.
If the given set is ever mutated, then the returned set will reflect those mutations.
Example ¶
package main
import (
"fmt"
"github.com/jbduncan/go-containers/set"
)
func main() {
underlyingSet := set.Of[string]()
underlyingSet.Add("link")
// Make an unmodifiable set that wraps underlyingSet.
unmodifiableSet := set.Unmodifiable[string](underlyingSet)
fmt.Println(unmodifiableSet.Contains("link")) // true
fmt.Println(unmodifiableSet.Contains("zelda")) // false
// Add an element back to underlyingSet.
// This also adds it to unmodifiable set.
underlyingSet.Add("zelda")
fmt.Println(unmodifiableSet.Contains("link")) // true
fmt.Println(unmodifiableSet.Contains("zelda")) // true
}
Output: true false true true
func (UnmodifiableSet[T]) All ¶
func (u UnmodifiableSet[T]) All() iter.Seq[T]
func (UnmodifiableSet[T]) Contains ¶
func (u UnmodifiableSet[T]) Contains(elem T) bool
func (UnmodifiableSet[T]) Len ¶
func (u UnmodifiableSet[T]) Len() int
func (UnmodifiableSet[T]) String ¶
func (u UnmodifiableSet[T]) String() string
Source Files
Directories