set

package module
v3.0.0 Latest Latest
Warning

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

 Go to latest Published: Sep 20, 2024 License: MPL-2.0 Imports: 4 Imported by: 35

README

go-set

Go Reference Run CI Tests GitHub

The go-set repository provides a set package containing a few generic Set implementations for Go.

PSA August 2024 - The v3 version of this package has been published, starting at tag version v3.0.0. A description of the changes including backwards incompatibilities can be found in https://github.com/hashicorp/go-set/issues/90

Requires go1.23 or later.

PSA October 2023 - The v2 version of this package has been published, starting at tag version v2.1.0. A description of the changes including backwards incompatibilities can be found in https://github.com/hashicorp/go-set/issues/73

Each implementation is optimal for a particular use case.

Set[T] is ideal for comparable types.

  • backed by map builtin
  • commonly used with string, int, simple struct types, etc.

HashSet[T] is useful for types that implement a Hash() function.

  • backed by map builtin
  • commonly used with complex structs
  • also works with custom HashFunc[T] implementations

TreeSet[T] is useful for comparable data (via CompareFunc[T])

  • backed by Red-Black Binary Search Tree
  • commonly used with complex structs with extrinsic order
  • efficient iteration in sort order
  • additional methods Min / Max / TopK / BottomK

This package is not thread-safe.

Documentation

The full go-set package reference is available on pkg.go.dev.

Install

go get github.com/hashicorp/go-set/v3@latest

import "github.com/hashicorp/go-set/v3"

Motivation

Package set helps reduce the boiler plate of using a map[<type>]struct{} as a set.

Say we want to de-duplicate a slice of strings

items := []string{"mitchell", "armon", "jack", "dave", "armon", "dave"}

A typical example of the classic way using map built-in:

m := make(map[string]struct{})
for _, item := range items {
  m[item] = struct{}{}
}
list := make([]string, 0, len(items))
for k := range m {
  list = append(list, k)
}

The same result, but in one line using package go-set.

list := set.From[string](items).Slice()

Set

The go-set package includes Set for types that satisfy the comparable constraint. Uniqueness of a set elements is guaranteed via shallow comparison (result of == operator).

Note: if pointers or structs with pointer fields are stored in the Set, they will be compared in the sense of pointer addresses, not in the sense of referenced values. Due to this fact the Set type is recommended to be used with builtin types like string, int, or simple struct types with no pointers. Set usage with pointers or structs with pointer is also possible if shallow equality is acceptable.

HashSet

The go-set package includes HashSet for types that implement a Hash() function. The custom type must satisfy HashFunc[H Hash] - essentially any Hash() function that returns a string or integer. This enables types to use string-y hash functions like md5, sha1, or even GoString(), but also enables types to implement an efficient hash function using a hash code based on prime multiples.

TreeSet

The go-set package includes TreeSet for creating sorted sets. A TreeSet may be used with any type T as the comparison between elements is provided by implementing CompareFunc[T]. The standard library cmp.Compare function provides a convenient implementation of CompareFunc for cmp.Ordered types like string or int. A TreeSet is backed by an underlying balanced binary search tree, making operations like in-order traversal efficient, in addition to enabling functions like Min(), Max(), TopK(), and BottomK().

Collection[T]

The Collection[T] interface is implemented by each of Set, HashSet, and TreeSet.

It serves as a useful abstraction over the common methods implemented by each set type.

Iteration

Starting with v3 each of Set, HashSet, and TreeSet implement an Items method. It can be used with the range keyword for iterating through each element in the set.

// e.g. print each element in the set
for _, item := range s.Items() {
  fmt.Println(item)
}

Set Examples

Below are simple example usages of Set

s := set.New[int](10)
s.Insert(1)
s.InsertSlice([]int{2, 3, 4})
s.Size()

s := set.From[string]([]string{"one", "two", "three"})
s.Contains("three")
s.Remove("one")

a := set.From[int]([]int{2, 4, 6, 8})
b := set.From[int]([]int{4, 5, 6})
a.Intersect(b)

HashSet Examples

Below are simple example usages of HashSet

(using a hash code)

type inventory struct {
    item   int
    serial int
}

func (i *inventory) Hash() int {
    code := 3 * item * 5 * serial
    return code
}

i1 := &inventory{item: 42, serial: 101}

s := set.NewHashSet[*inventory, int](10)
s.Insert(i1)

(using a string hash)

type employee struct {
    name string
    id   int
}

func (e *employee) Hash() string {
    return fmt.Sprintf("%s:%d", e.name, e.id)
}

e1 := &employee{name: "armon", id: 2}

s := set.NewHashSet[*employee, string](10)
s.Insert(e1)

TreeSet Examples

Below are simple example usages of TreeSet

ts := NewTreeSet[int](Compare[int])
ts.Insert(5)

type waypoint struct {
    distance int
    name     string
}

// compare implements CompareFunc
compare := func(w1, w2 *waypoint) int {
    return w1.distance - w2.distance
}

ts := NewTreeSet[*waypoint](compare)
ts.Insert(&waypoint{distance: 42, name: "tango"})
ts.Insert(&waypoint{distance: 13, name: "alpha"})
ts.Insert(&waypoint{distance: 71, name: "xray"})

Documentation

Overview

Package set provides a basic generic set implementation.

https://en.wikipedia.org/wiki/Set_(mathematics)

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func InsertSetFunc 

func InsertSetFunc[T, E any](a Collection[T], b Collection[E], transform func(T) E) bool

InsertSetFunc inserts the elements of a into b, applying the transform function to each element before insertion.

Returns true if b was modified as a result.

func InsertSliceFunc 

func InsertSliceFunc[T, E any](col Collection[T], items []E, transform func(element E) T) bool

InsertSliceFunc inserts all elements from items into col, applying the transform function to each element before insertion.

Returns true if col was modified as a result of the operation.

func SliceFunc 

func SliceFunc[T, E any](s Collection[T], transform func(T) E) []E

SliceFunc produces a slice of the elements in s, applying the transform function to each element first.

Types

type Collection 

type Collection[T any] interface {

	// Insert an element into the set.
	//
	// Returns true if the set is modified as a result.
	Insert(T) bool

	// InsertSlice will insert each element of a given slice into the set.
	//
	// Returns true if the set was modified as a result.
	InsertSlice([]T) bool

	// InsertSet will insert each element of a given Collection into the set.
	//
	// Returns true if the set was modified as a result.
	InsertSet(Collection[T]) bool

	// Remove will remove the given element from the set, if present.
	//
	// Returns true if the set was modified as a result of the operation.
	Remove(T) bool

	// RemoveSlice will remove each element of a slice from the set, if present.
	//
	// Returns true if the set was modified as a result of the operation.
	RemoveSlice([]T) bool

	// RemoveSet will remove each element of a Collection from the set.
	//
	// Returns true if the set was modified as a result of the operation.
	RemoveSet(Collection[T]) bool

	// RemoveFunc will remove each element from the set that satisfies the given predicate.
	//
	// Returns true if the set was modified as a result of the opearation.
	RemoveFunc(func(T) bool) bool

	// Contains returns whether an element is present in the set.
	Contains(T) bool

	// ContainsSlice returns whether the set contains the same set of elements as
	// the given slice. The elements of the slice may contain duplicates.
	ContainsSlice([]T) bool

	// Subset returns whether the given Collection is a subset of the set.
	Subset(Collection[T]) bool

	// ProperSubset returns whether the given Collection is a proper subset of the set.
	ProperSubset(Collection[T]) bool

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

	// Empty returns whether the set contains no elements.
	Empty() bool

	// Union returns a new set containing the unique elements of both this set
	// and a given Collection.
	//
	// https://en.wikipedia.org/wiki/Union_(set_theory)
	Union(Collection[T]) Collection[T]

	// Difference returns a new set that contains elements this set that are not
	// in a given Collection.
	//
	// https://en.wikipedia.org/wiki/Complement_(set_theory)
	Difference(Collection[T]) Collection[T]

	// Intersect returns a new set that contains only the elements present in
	// both this and a given Collection.
	//
	// https://en.wikipedia.org/wiki/Intersection_(set_theory)
	Intersect(Collection[T]) Collection[T]

	// Slice returns a slice of all elements in the set.
	//
	// For iterating elements, consider using Items() instead.
	//
	// Note: order of elements depends on the underlying implementation.
	Slice() []T

	// String creates a string representation of this set.
	//
	// Note: string representation depends on underlying implementation.
	String() string

	// StringFunc creates a string representation of this set, using the given
	// function to transform each element into a string.
	//
	// Note: string representation depends on underlying implementation.
	StringFunc(func(T) string) string

	// EqualSet returns whether this set and a given Collection contain the same
	// elements.
	EqualSet(Collection[T]) bool

	// EqualSlice returns whether this set and a given slice contain the same
	// elements, where the slice may contain duplicates.
	EqualSlice([]T) bool

	// EqualSliceSet returns whether this set and a given slice contain exactly
	// the same elements, where the slice must not contain duplicates.
	EqualSliceSet([]T) bool

	// Items returns a generator function for use with the range keyword
	// enabling iteration of each element in the set.
	//
	// Note: iteration order depends on the underlying implementation.
	//
	//	for element := range s.Items() { ... }
	Items() iter.Seq[T]
}

Fundamental set operations and familiar utility methods are part of this interface. Each of Set, HashSet, and TreeSet may also provide implementation specific methods not part of this interface.

type CompareFunc 

type CompareFunc[T any] func(T, T) int

CompareFunc represents a function that compares two elements.

Must return < 0 if the first parameter is less than the second parameter 0 if the two parameters are equal > 0 if the first parameters is greater than the second parameter

Often T will be a type that satisfies cmp.Ordered, and CompareFunc can be implemented by using cmp.Compare.

type Hash 

type Hash interface {
	~string | ~int | ~uint | ~int64 | ~uint64 | ~int32 | ~uint32 | ~int16 | ~uint16 | ~int8 | ~uint8
}

Hash represents the output type of a Hash() function defined on a type.

A Hash could be string-like or int-like. A string hash could be something like and md5, sha1, or GoString() representation of a type. An int hash could be something like the prime multiple hash code of a type.

type HashFunc 

type HashFunc[T any, H Hash] func(T) H

HashFunc represents a function that that produces a hash value when applied to a given T. Typically this will be implemented as T.Hash but by separating HashFunc a HashSet can be made to make use of any hash implementation.

func HasherFunc 

func HasherFunc[T Hasher[H], H Hash]() HashFunc[T, H]

HasherFunc creates a closure around the T.Hash function so that the type can be used as the HashFunc for a HashSet.

type HashSet 

type HashSet[T any, H Hash] struct {
	// contains filtered or unexported fields
}

HashSet is a generic implementation of the mathematical data structure, oriented around the use of a HashFunc to make hash values from other types.

func HashSetFrom 

func HashSetFrom[T Hasher[H], H Hash](items []T) *HashSet[T, H]

HashSetFrom creates a new HashSet containing each element in items.

T must implement HashFunc[H], where H is of type Hash. This allows custom types that include non-comparable fields to provide their own hash algorithm.

func HashSetFromFunc 

func HashSetFromFunc[T any, H Hash](items []T, hash HashFunc[T, H]) *HashSet[T, H]

NewHashSetFromFunc creates a new HashSet containing each element in items.

func NewHashSet 

func NewHashSet[T Hasher[H], H Hash](size int) *HashSet[T, H]

NewHashSet creates a HashSet with underlying capacity of size and will compute hash values from the T.Hash method.

func NewHashSetFunc 

func NewHashSetFunc[T any, H Hash](size int, fn HashFunc[T, H]) *HashSet[T, H]

NewHashSetFunc creates a HashSet with underlying capacity of size and uses the given hashing function to compute hashes on elements.

A HashSet will automatically grow or shrink its capacity as items are added or removed.

func (*HashSet[T, H]) Contains 

func (s *HashSet[T, H]) Contains(item T) bool

Contains returns whether item is present in s.

Example 
anna := &person{Name: "anna", ID: 94}
bill := &person{Name: "bill", ID: 50}
carl := &person{Name: "carl", ID: 10}
dave := &person{Name: "dave", ID: 32}
s := HashSetFrom[*person, string]([]*person{anna, bill, carl})

fmt.Println(s.Contains(anna))
fmt.Println(s.Contains(dave))

Output:

true
false

func (*HashSet[T, H]) ContainsSlice 

func (s *HashSet[T, H]) ContainsSlice(items []T) bool

ContainsSlice returns whether s contains the same set of of elements that are in items. The elements of items may contain duplicates.

If the slice is known to be set-like (no duplicates), EqualSlice provides a more efficient implementation.

Example 
anna := &person{Name: "anna", ID: 94}
bill := &person{Name: "bill", ID: 50}
carl := &person{Name: "carl", ID: 10}
dave := &person{Name: "dave", ID: 32}
s := HashSetFrom[*person, string]([]*person{anna, bill, carl})

fmt.Println(s.ContainsSlice([]*person{anna, bill}))
fmt.Println(s.ContainsSlice([]*person{anna, bill, carl}))
fmt.Println(s.ContainsSlice([]*person{carl, dave}))

Output:

false
true
false

func (*HashSet[T, H]) Copy 

func (s *HashSet[T, H]) Copy() *HashSet[T, H]

Copy creates a shallow copy of s.

Example 
anna := &person{Name: "anna", ID: 94}
bill := &person{Name: "bill", ID: 50}
carl := &person{Name: "carl", ID: 10}
s := HashSetFrom[*person, string]([]*person{anna, bill, carl})
c := s.Copy()

fmt.Println(c)

Output:

[anna bill carl]

func (*HashSet[T, H]) Difference 

func (s *HashSet[T, H]) Difference(col Collection[T]) Collection[T]

Difference returns a set that contains elements of s that are not in col.

Example 
anna := &person{Name: "anna", ID: 94}
bill := &person{Name: "bill", ID: 50}
carl := &person{Name: "carl", ID: 10}
dave := &person{Name: "dave", ID: 32}
s1 := HashSetFrom[*person, string]([]*person{anna, bill, carl})
s2 := HashSetFrom[*person, string]([]*person{anna, bill, dave})
difference := s1.Difference(s2)

fmt.Println(s1)
fmt.Println(s2)
fmt.Println(difference)

Output:

[anna bill carl]
[anna bill dave]
[carl]

func (*HashSet[T, H]) Empty 

func (s *HashSet[T, H]) Empty() bool

Empty returns true if s contains no elements, false otherwise.

Example 
s := NewHashSet[*person, string](0)

fmt.Println(s.Empty())

Output:

true

func (*HashSet[T, H]) Equal 

func (s *HashSet[T, H]) Equal(o *HashSet[T, H]) bool

Equal returns whether s and o contain the same elements.

Example 
anna := &person{Name: "anna", ID: 94}
bill := &person{Name: "bill", ID: 50}
carl := &person{Name: "carl", ID: 10}
dave := &person{Name: "dave", ID: 32}

s1 := HashSetFrom[*person, string]([]*person{anna, bill, carl})
s2 := HashSetFrom[*person, string]([]*person{anna, bill, carl})
s3 := HashSetFrom[*person, string]([]*person{anna, bill, dave})

fmt.Println(s1.Equal(s2))
fmt.Println(s1.Equal(s3))

Output:

true
false

func (*HashSet[T, H]) EqualSet 

func (s *HashSet[T, H]) EqualSet(col Collection[T]) bool

EqualSet returns whether s and col contain the same elements.

func (*HashSet[T, H]) EqualSlice 

func (s *HashSet[T, H]) EqualSlice(items []T) bool

EqualSlice returns whether s and items contain the same elements.

The items slice may contain duplicates.

If the items slice is known to contain no duplicates, EqualSliceSet can be used instead as a faster implementation.

To detect if a slice is a subset of s, use ContainsSlice.

Example 
anna := &person{Name: "anna", ID: 94}
bill := &person{Name: "bill", ID: 50}
carl := &person{Name: "carl", ID: 10}
dave := &person{Name: "dave", ID: 32}

s := HashSetFrom[*person, string]([]*person{anna, bill, carl})

fmt.Println(s.EqualSlice([]*person{bill, anna, carl}))
fmt.Println(s.EqualSlice([]*person{anna, anna, bill, carl}))
fmt.Println(s.EqualSlice([]*person{dave, bill, carl}))

Output:

true
true
false

func (*HashSet[T, H]) EqualSliceSet 

func (s *HashSet[T, H]) EqualSliceSet(items []T) bool

EqualSliceSet returns whether s and items contain exactly the same elements.

If items contains duplicates EqualSliceSet will return false. The elements of items are assumed to be set-like. For comparing s to a slice that may contain duplicate elements, use EqualSlice instead.

To detect if a slice is a subset of s, use ContainsSlice.

Example 
anna := &person{Name: "anna", ID: 94}
bill := &person{Name: "bill", ID: 50}
carl := &person{Name: "carl", ID: 10}
dave := &person{Name: "dave", ID: 32}

s := HashSetFrom[*person, string]([]*person{anna, bill, carl})

fmt.Println(s.EqualSliceSet([]*person{bill, anna, carl}))
fmt.Println(s.EqualSliceSet([]*person{anna, anna, bill, carl}))
fmt.Println(s.EqualSliceSet([]*person{dave, bill, carl}))

Output:

true
false
false

func (*HashSet[T, H]) Insert 

func (s *HashSet[T, H]) Insert(item T) bool

Insert item into s.

Return true if s was modified (item was not already in s), false otherwise.

Example 
s := NewHashSet[*person, string](10)
s.Insert(&person{Name: "dave", ID: 108})
s.Insert(&person{Name: "armon", ID: 101})
s.Insert(&person{Name: "mitchell", ID: 100})
s.Insert(&person{Name: "armon", ID: 101})

fmt.Println(s)

Output:

[armon dave mitchell]

func (*HashSet[T, H]) InsertSet 

func (s *HashSet[T, H]) InsertSet(col Collection[T]) bool

InsertSet will insert each element of col into s.

Return true if s was modified (at least one item of col was not already in s), false otherwise.

Example 
anna := &person{Name: "anna", ID: 94}
bill := &person{Name: "bill", ID: 50}
carl := &person{Name: "carl", ID: 10}
dave := &person{Name: "dave", ID: 32}
s1 := HashSetFrom[*person, string]([]*person{anna, carl})
s2 := HashSetFrom[*person, string]([]*person{carl, dave, bill})
s2.InsertSet(s1)

fmt.Println(s1)
fmt.Println(s2)

Output:

[anna carl]
[anna bill carl dave]

func (*HashSet[T, H]) InsertSlice 

func (s *HashSet[T, H]) InsertSlice(items []T) bool

InsertSlice will insert each item in items into s.

Return true if s was modified (at least one item was not already in s), false otherwise.

Example 
s := NewHashSet[*person, string](10)
s.InsertSlice([]*person{
	{Name: "dave", ID: 108},
	{Name: "mitchell", ID: 100},
	{Name: "dave", ID: 108},
	{Name: "armon", ID: 101},
})

fmt.Println(s)

Output:

[armon dave mitchell]

func (*HashSet[T, H]) Intersect 

func (s *HashSet[T, H]) Intersect(col Collection[T]) Collection[T]

Intersect returns a set that contains elements that are present in both s and col.

Example 
anna := &person{Name: "anna", ID: 94}
bill := &person{Name: "bill", ID: 50}
carl := &person{Name: "carl", ID: 10}
dave := &person{Name: "dave", ID: 32}
s1 := HashSetFrom[*person, string]([]*person{anna, bill, carl})
s2 := HashSetFrom[*person, string]([]*person{anna, bill, dave})
intersect := s1.Intersect(s2)

fmt.Println(s1)
fmt.Println(s2)
fmt.Println(intersect)

Output:

[anna bill carl]
[anna bill dave]
[anna bill]

func (*HashSet[T, H]) Items 

func (s *HashSet[T, H]) Items() iter.Seq[T]

Items returns a generator function for iterating each element in s by using the range keyword. 

for element := range s.Items() { ... }

func (*HashSet[T, H]) MarshalJSON 

func (s *HashSet[T, H]) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface.

Example 
type Foo struct {
	Persons *HashSet[*person, string] `json:"persons"`
}

f := Foo{
	Persons: HashSetFrom([]*person{
		{Name: "anna", ID: 94},
		{Name: "bill", ID: 50},
		{Name: "carl", ID: 10},
	}),
}

b, _ := json.Marshal(f)

fmt.Println(string(b))

Output:

{"persons":[{"Name":"anna","ID":94},{"Name":"bill","ID":50},{"Name":"carl","ID":10}]}

func (*HashSet[T, H]) ProperSubset 

func (s *HashSet[T, H]) ProperSubset(col Collection[T]) bool

ProperSubset returns whether col is a proper subset of s.

func (*HashSet[T, H]) Remove 

func (s *HashSet[T, H]) Remove(item T) bool

Remove will remove item from s.

Return true if s was modified (item was present), false otherwise.

Example 
anna := &person{Name: "anna", ID: 94}
bill := &person{Name: "bill", ID: 50}
carl := &person{Name: "carl", ID: 10}
dave := &person{Name: "dave", ID: 32}
s := HashSetFrom[*person, string]([]*person{anna, carl, dave, bill})

fmt.Println(s)

s.Remove(carl)

fmt.Println(s)

Output:

[anna bill carl dave]
[anna bill dave]

func (*HashSet[T, H]) RemoveFunc 

func (s *HashSet[T, H]) RemoveFunc(f func(item T) bool) bool

RemoveFunc will remove each element from s that satisfies condition f.

Return true if s was modified, false otherwise.

Example 
anna := &person{Name: "anna", ID: 94}
bill := &person{Name: "bill", ID: 50}
carl := &person{Name: "carl", ID: 10}
dave := &person{Name: "dave", ID: 32}
s := HashSetFrom[*person, string]([]*person{anna, bill, carl, dave})

idAbove50 := func(p *person) bool {
	return p.ID >= 50
}

fmt.Println(s)

s.RemoveFunc(idAbove50)

fmt.Println(s)

Output:

[anna bill carl dave]
[carl dave]

func (*HashSet[T, H]) RemoveSet 

func (s *HashSet[T, H]) RemoveSet(col Collection[T]) bool

RemoveSet will remove each element of col from s.

Return true if s was modified (any item of col was present in s), false otherwise.

Example 
anna := &person{Name: "anna", ID: 94}
bill := &person{Name: "bill", ID: 50}
carl := &person{Name: "carl", ID: 10}
dave := &person{Name: "dave", ID: 32}
s := HashSetFrom[*person, string]([]*person{carl, dave, bill})
r := HashSetFrom[*person, string]([]*person{anna, carl})

fmt.Println(s)

s.RemoveSet(r)

fmt.Println(s)

Output:

[bill carl dave]
[bill dave]

func (*HashSet[T, H]) RemoveSlice 

func (s *HashSet[T, H]) RemoveSlice(items []T) bool

RemoveSlice will remove each item in items from s.

Return true if s was modified (any item was present), false otherwise.

Example 
anna := &person{Name: "anna", ID: 94}
bill := &person{Name: "bill", ID: 50}
carl := &person{Name: "carl", ID: 10}
dave := &person{Name: "dave", ID: 32}
s := HashSetFrom[*person, string]([]*person{anna, carl, dave, bill})

fmt.Println(s)

s.RemoveSlice([]*person{anna, carl})

fmt.Println(s)

Output:

[anna bill carl dave]
[bill dave]

func (*HashSet[T, H]) Size 

func (s *HashSet[T, H]) Size() int

Size returns the cardinality of s.

Example 
anna := &person{Name: "anna", ID: 94}
bill := &person{Name: "bill", ID: 50}
carl := &person{Name: "carl", ID: 10}
s := HashSetFrom[*person, string]([]*person{anna, bill, carl})

fmt.Println(s.Size())

Output:

3

func (*HashSet[T, H]) Slice 

func (s *HashSet[T, H]) Slice() []T

Slice creates a copy of s as a slice.

The result is not ordered.

Example 
anna := &person{Name: "anna", ID: 94}
bill := &person{Name: "bill", ID: 50}
carl := &person{Name: "carl", ID: 10}
s := HashSetFrom[*person, string]([]*person{anna, bill, carl})

slice := s.Slice()
sort.Slice(slice, func(a, b int) bool {
	return slice[a].ID < slice[b].ID
})

fmt.Println(slice)

Output:

[carl bill anna]

func (*HashSet[T, H]) String 

func (s *HashSet[T, H]) String() string

String creates a string representation of s, using "%v" printf formatting to transform each element into a string. The result contains elements sorted by their lexical string order.

Example 
anna := &person{Name: "anna", ID: 94}
bill := &person{Name: "bill", ID: 50}
carl := &person{Name: "carl", ID: 10}
s := HashSetFrom[*person, string]([]*person{anna, bill, carl})

fmt.Println(s.String())

Output:

[anna bill carl]

func (*HashSet[T, H]) StringFunc 

func (s *HashSet[T, H]) StringFunc(f func(element T) string) string

StringFunc creates a string representation of s, using f to transform each element into a string. The result contains elements sorted by their string order.

func (*HashSet[T, H]) Subset 

func (s *HashSet[T, H]) Subset(col Collection[T]) bool

Subset returns whether col is a subset of s.

Example 
anna := &person{Name: "anna", ID: 94}
bill := &person{Name: "bill", ID: 50}
carl := &person{Name: "carl", ID: 10}
dave := &person{Name: "dave", ID: 32}
s1 := HashSetFrom[*person, string]([]*person{anna, bill, carl})
s2 := HashSetFrom[*person, string]([]*person{anna, bill})
s3 := HashSetFrom[*person, string]([]*person{bill, carl, dave})

fmt.Println(s1.Subset(s2))
fmt.Println(s1.Subset(s3))

Output:

true
false

func (*HashSet[T, H]) Union 

func (s *HashSet[T, H]) Union(col Collection[T]) Collection[T]

Union returns a set that contains all elements of s and col combined.

Elements in s take priority in the event of colliding hash values.

Example 
anna := &person{Name: "anna", ID: 94}
bill := &person{Name: "bill", ID: 50}
carl := &person{Name: "carl", ID: 10}
dave := &person{Name: "dave", ID: 32}
s1 := HashSetFrom[*person, string]([]*person{anna, bill, carl})
s2 := HashSetFrom[*person, string]([]*person{anna, bill, dave})
union := s1.Union(s2)

fmt.Println(s1)
fmt.Println(s2)
fmt.Println(union)

Output:

[anna bill carl]
[anna bill dave]
[anna bill carl dave]

func (*HashSet[T, H]) UnmarshalJSON 

func (s *HashSet[T, H]) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the json.Unmarshaler interface.

Example

TODO: will not work as long as HashFunc cannot be derived from the type parameters. 

// type Foo struct {
// 	Persons *HashSet[*person, string] `json:"persons"`
// }

// in := `{"persons":[{"Name":"anna","ID":94},{"Name":"bill","ID":50},{"Name":"bill","ID":50},{"Name":"carl","ID":10}]}`
// var out Foo

// _ = json.Unmarshal([]byte(in), &out)

// fmt.Println(out.Persons)

Output:

type Hasher 

type Hasher[H Hash] interface {
	Hash() H
}

Hasher represents a type that implements a Hash() method. Types that wish to cache a hash value with an internal field should implement Hash accordingly.

type Set 

type Set[T comparable] struct {
	// contains filtered or unexported fields
}

Set is a simple, generic implementation of the set mathematical data structure. It is optimized for correctness and convenience, as a replacement for the use of map[interface{}]struct{}.

func From 

func From[T comparable](items []T) *Set[T]

From creates a new Set containing each item in items.

T may be any comparable type. Keep in mind that pointer types or structs containing pointer fields will be compared using shallow equality. For deep equality use HashSet instead.

func FromFunc 

func FromFunc[A any, T comparable](items []A, conversion func(A) T) *Set[T]

FromFunc creates a new Set containing a conversion of each item in items.

T may be any comparable type. Keep in mind that pointer types or structs containing pointer fields will be compared using shallow equality. For deep equality use HashSet instead.

func New 

func New[T comparable](size int) *Set[T]

New creates a new Set with initial underlying capacity of size.

A Set will automatically grow or shrink its capacity as items are added or removed.

T may be any comparable type. Keep in mind that pointer types or structs containing pointer fields will be compared using shallow equality. For deep equality use HashSet instead.

func (*Set[T]) Contains 

func (s *Set[T]) Contains(item T) bool

Contains returns whether item is present in s.

Example 
s := From([]string{"red", "green", "blue"})

fmt.Println(s.Contains("red"))
fmt.Println(s.Contains("orange"))

Output:

true
false

func (*Set[T]) ContainsSlice 

func (s *Set[T]) ContainsSlice(items []T) bool

ContainsSlice returns whether all elements in items are present in s.

Example 
s := From([]string{"red", "green", "blue"})

fmt.Println(s.ContainsSlice([]string{"red", "blue"}))
fmt.Println(s.ContainsSlice([]string{"red", "blue", "orange"}))
fmt.Println(s.ContainsSlice([]string{"red", "blue", "green"}))

Output:

true
false
true

func (*Set[T]) Copy 

func (s *Set[T]) Copy() *Set[T]

Copy creates a copy of s.

Example 
s := From([]string{"red", "green", "blue"})
t := s.Copy()

fmt.Println(t)

Output:

[blue green red]

func (*Set[T]) Difference 

func (s *Set[T]) Difference(col Collection[T]) Collection[T]

Difference returns a set that contains elements of s that are not in col.

Example 
t1 := From([]string{"red", "green", "blue"})
t2 := From([]string{"red", "blue"})
t3 := From([]string{"red", "orange"})

fmt.Println(t1.Difference(t2))
fmt.Println(t1.Difference(t3))

Output:

[green]
[blue green]

func (*Set[T]) Empty 

func (s *Set[T]) Empty() bool

Empty returns true if s contains no elements, false otherwise.

Example 
s := New[string](10)

fmt.Println(s.Empty())

Output:

true

func (*Set[T]) Equal 

func (s *Set[T]) Equal(o *Set[T]) bool

Equal returns whether s and o contain the same elements.

Example 
t1 := From([]string{"red", "green", "blue"})
t2 := From([]string{"red", "blue"})
t3 := From([]string{"red", "green", "yellow"})
t4 := From([]string{"red", "green", "blue"})

fmt.Println(t1.Equal(t2))
fmt.Println(t1.Equal(t3))
fmt.Println(t1.Equal(t4))

Output:

false
false
true

func (*Set[T]) EqualSet 

func (s *Set[T]) EqualSet(col Collection[T]) bool

EqualSet returns whether s and col contain the same elements.

func (*Set[T]) EqualSlice 

func (s *Set[T]) EqualSlice(items []T) bool

EqualSlice returns whether s and items contain the same elements.

The items slice may contain duplicates.

If the items slice is known to contain no duplicates, EqualSliceSet may be used instead as a faster implementation.

To detect if a slice is a subset of s, use ContainsSlice.

Example 
s := From([]string{"red", "green", "blue"})

fmt.Println(s.EqualSlice([]string{"red", "blue", "green"}))
fmt.Println(s.EqualSlice([]string{"red", "red", "blue", "green"}))
fmt.Println(s.EqualSlice([]string{"yellow", "blue", "green"}))

Output:

true
true
false

func (*Set[T]) EqualSliceSet 

func (s *Set[T]) EqualSliceSet(items []T) bool

EqualSliceSet returns whether s and items contain exactly the same elements.

If items contains duplicates EqualSliceSet will return false. The elements of items are assumed to be set-like. For comparing s to a slice that may contain duplicate elements, use EqualSlice instead.

To detect if a slice is a subset of s, use ContainsSlice.

Example 
s := From([]string{"red", "green", "blue"})

fmt.Println(s.EqualSliceSet([]string{"red", "blue", "green"}))
fmt.Println(s.EqualSliceSet([]string{"red", "red", "blue", "green"}))
fmt.Println(s.EqualSliceSet([]string{"yellow", "blue", "green"}))

Output:

true
false
false

func (*Set[T]) Insert 

func (s *Set[T]) Insert(item T) bool

Insert item into s.

Return true if s was modified (item was not already in s), false otherwise.

Example 
s := New[int](10)
s.Insert(1)
s.Insert(1)
s.Insert(2)
s.Insert(3)
s.Insert(2)

fmt.Println(s)

Output:

[1 2 3]

func (*Set[T]) InsertSet 

func (s *Set[T]) InsertSet(col Collection[T]) bool

InsertSet will insert each element of col into s.

Return true if s was modified (at least one item of col was not already in s), false otherwise.

Example 
s := New[int](10)
s.InsertSet(From([]int{1, 1, 2, 3, 2}))

fmt.Println(s)

Output:

[1 2 3]

func (*Set[T]) InsertSlice 

func (s *Set[T]) InsertSlice(items []T) bool

InsertSlice will insert each item in items into s.

Return true if s was modified (at least one item was not already in s), false otherwise.

Example 
s := New[int](10)
s.InsertSlice([]int{1, 1, 2, 3, 2})

fmt.Println(s)

Output:

[1 2 3]

func (*Set[T]) Intersect 

func (s *Set[T]) Intersect(col Collection[T]) Collection[T]

Intersect returns a set that contains elements that are present in both s and col.

Example 
t1 := From([]string{"red", "green", "blue"})
t2 := From([]string{"red", "blue"})
t3 := From([]string{"red", "orange"})
t4 := From([]string{"yellow"})

fmt.Println(t1.Intersect(t2))
fmt.Println(t1.Intersect(t3))
fmt.Println(t1.Intersect(t4))

Output:

[blue red]
[red]
[]

func (*Set[T]) Items 

func (s *Set[T]) Items() iter.Seq[T]

Items returns a generator function for iterating each element in s by using the range keyword. 

for element := range s.Items() { ... }

func (*Set[T]) MarshalJSON 

func (s *Set[T]) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface.

Example 
type Foo struct {
	Colors *Set[string] `json:"colors"`
}

f := Foo{
	Colors: From([]string{"red", "green", "blue"}),
}

b, _ := json.Marshal(f)

fmt.Println(string(b))

Output:

{"colors":["red","green","blue"]}

func (*Set[T]) ProperSubset 

func (s *Set[T]) ProperSubset(col Collection[T]) bool

Subset returns whether col is a proper subset of s.

func (*Set[T]) Remove 

func (s *Set[T]) Remove(item T) bool

Remove will remove item from s.

Return true if s was modified (item was present), false otherwise.

Example 
s := New[int](10)
s.InsertSlice([]int{1, 1, 2, 3, 2})
s.Remove(2)

fmt.Println(s)

Output:

[1 3]

func (*Set[T]) RemoveFunc 

func (s *Set[T]) RemoveFunc(f func(T) bool) bool

RemoveFunc will remove each element from s that satisfies condition f.

Return true if s was modified, false otherwise.

Example 
s := From([]int{1, 2, 3, 4, 5, 6, 7, 8, 9, 0})
even := func(i int) bool {
	return i%2 == 0
}
s.RemoveFunc(even)

fmt.Println(s)

Output:

[1 3 5 7 9]

func (*Set[T]) RemoveSet 

func (s *Set[T]) RemoveSet(col Collection[T]) bool

RemoveSet will remove each element of col from s.

Return true if s was modified (any item of o was present in s), false otherwise.

Example 
s := New[int](10)
s.InsertSlice([]int{1, 1, 2, 3, 2})
s.RemoveSet(From([]int{2, 3}))

fmt.Println(s)

Output:

[1]

func (*Set[T]) RemoveSlice 

func (s *Set[T]) RemoveSlice(items []T) bool

RemoveSlice will remove each item in items from s.

Return true if s was modified (any item was present), false otherwise.

Example 
s := New[int](10)
s.InsertSlice([]int{1, 1, 2, 3, 2})
s.RemoveSlice([]int{2, 3})

fmt.Println(s)

Output:

[1]

func (*Set[T]) Size 

func (s *Set[T]) Size() int

Size returns the cardinality of s.

Example 
s := From([]string{"red", "green", "blue"})

fmt.Println(s.Size())

Output:

3

func (*Set[T]) Slice 

func (s *Set[T]) Slice() []T

Slice creates a copy of s as a slice. Elements are in no particular order.

Example 
s := From([]string{"red", "green", "blue"})
t := s.Slice()

sort.Strings(t)
fmt.Println(t)

Output:

[blue green red]

func (*Set[T]) String 

func (s *Set[T]) String() string

String creates a string representation of s, using "%v" printf formating to transform each element into a string. The result contains elements sorted by their lexical string order.

Example 
s := From([]string{"red", "green", "blue"})

fmt.Println(s.String())

Output:

[blue green red]

func (*Set[T]) StringFunc 

func (s *Set[T]) StringFunc(f func(element T) string) string

StringFunc creates a string representation of s, using f to transform each element into a string. The result contains elements sorted by their lexical string order.

func (*Set[T]) Subset 

func (s *Set[T]) Subset(col Collection[T]) bool

Subset returns whether col is a subset of s.

Example 
t1 := From([]string{"red", "green", "blue"})
t2 := From([]string{"red", "blue"})
t3 := From([]string{"red", "orange"})

fmt.Println(t1.Subset(t2))
fmt.Println(t1.Subset(t3))

Output:

true
false

func (*Set[T]) Union 

func (s *Set[T]) Union(col Collection[T]) Collection[T]

Union returns a set that contains all elements of s and col combined.

Example 
t1 := From([]string{"red", "green", "blue"})
t2 := From([]string{"red", "blue"})
t3 := From([]string{"red", "orange"})

fmt.Println(t1.Union(t2))
fmt.Println(t1.Union(t3))

Output:

[blue green red]
[blue green orange red]

func (*Set[T]) UnmarshalJSON 

func (s *Set[T]) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the json.Unmarshaler interface.

Example 
type Foo struct {
	Colors *Set[string] `json:"colors"`
}

in := `{"colors":["red","green","green","blue"]}`
var out Foo

_ = json.Unmarshal([]byte(in), &out)

fmt.Println(out.Colors)

Output:

[blue green red]

type TreeNodeVisit 

type TreeNodeVisit[T any] func(*node[T]) (next bool)

TreeNodeVisit is a function that is called for each node in the tree.

type TreeSet 

type TreeSet[T any] struct {
	// contains filtered or unexported fields
}

TreeSet provides a generic sortable set implementation for Go. Enables fast storage and retrieval of ordered information. Most effective in cases where data is regularly being added and/or removed and fast lookup properties must be maintained.

The underlying data structure is a Red-Black Binary Search Tree. https://en.wikipedia.org/wiki/Red–black_tree

Not thread safe, and not safe for concurrent modification.

func NewTreeSet 

func NewTreeSet[T any](compare CompareFunc[T]) *TreeSet[T]

NewTreeSet creates a TreeSet of type T, comparing elements via a given CompareFunc[T].

T may be any type.

For builtin types, CompareBuiltin provides a convenient CompareFunc implementation.

func TreeSetFrom 

func TreeSetFrom[T any](items []T, compare CompareFunc[T]) *TreeSet[T]

TreeSetFrom creates a new TreeSet containing each item in items.

T may be any type.

C is an implementation of CompareFunc[T]. For builtin types, Cmp provides a convenient Compare implementation.

func (*TreeSet[T]) Above 

func (s *TreeSet[T]) Above(item T) *TreeSet[T]

After returns a TreeSet containing the elements of s that are > item.

Example 
s := TreeSetFrom[int]([]int{1, 2, 3, 4, 5}, cmp.Compare[int])

fmt.Println(s.Above(3))
fmt.Println(s.Above(5))
fmt.Println(s.Above(10))

Output:

[4 5]
[]
[]

func (*TreeSet[T]) AboveEqual 

func (s *TreeSet[T]) AboveEqual(item T) *TreeSet[T]

AfterEqual returns a TreeSet containing the elements of s that are ≥ item.

Example 
s := TreeSetFrom[int]([]int{1, 2, 3, 4, 5}, cmp.Compare[int])

fmt.Println(s.AboveEqual(3))
fmt.Println(s.AboveEqual(5))
fmt.Println(s.AboveEqual(10))

Output:

[3 4 5]
[5]
[]

func (*TreeSet[T]) Below 

func (s *TreeSet[T]) Below(item T) *TreeSet[T]

Below returns a TreeSet containing the elements of s that are < item.

Example 
s := TreeSetFrom[int]([]int{1, 2, 3, 4, 5}, cmp.Compare[int])

fmt.Println(s.Below(1))
fmt.Println(s.Below(3))
fmt.Println(s.Below(10))

Output:

[]
[1 2]
[1 2 3 4 5]

func (*TreeSet[T]) BelowEqual 

func (s *TreeSet[T]) BelowEqual(item T) *TreeSet[T]

BelowEqual returns a TreeSet containing the elements of s that are ≤ item.

Example 
s := TreeSetFrom[int]([]int{1, 2, 3, 4, 5}, cmp.Compare[int])

fmt.Println(s.BelowEqual(1))
fmt.Println(s.BelowEqual(3))
fmt.Println(s.BelowEqual(10))

Output:

[1]
[1 2 3]
[1 2 3 4 5]

func (*TreeSet[T]) BottomK 

func (s *TreeSet[T]) BottomK(n int) []T

BottomK returns the bottom n (largest) elements in s, in descending order.

Example 
s := TreeSetFrom[int]([]int{1, 2, 3, 4, 5}, cmp.Compare[int])

fmt.Println(s.BottomK(0))
fmt.Println(s.BottomK(1))
fmt.Println(s.BottomK(3))
fmt.Println(s.BottomK(5))

Output:

[]
[5]
[5 4 3]
[5 4 3 2 1]

func (*TreeSet[T]) Contains 

func (s *TreeSet[T]) Contains(item T) bool

Contains returns whether item is present in s.

Example 
s := TreeSetFrom[string]([]string{"red", "green", "blue"}, cmp.Compare[string])

fmt.Println(s.Contains("green"))
fmt.Println(s.Contains("orange"))

Output:

true
false

func (*TreeSet[T]) ContainsSlice 

func (s *TreeSet[T]) ContainsSlice(items []T) bool

ContainsSlice returns whether all elements in items are present in s.

Example 
s := TreeSetFrom[string]([]string{"red", "green", "blue"}, cmp.Compare[string])

fmt.Println(s.ContainsSlice([]string{"red", "green"}))
fmt.Println(s.ContainsSlice([]string{"red", "orange"}))

Output:

true
false

func (*TreeSet[T]) Copy 

func (s *TreeSet[T]) Copy() *TreeSet[T]

Copy creates a copy of s.

Individual elements are reference copies.

Example 
s := TreeSetFrom[int]([]int{1, 2, 3, 4, 5}, cmp.Compare[int])
c := s.Copy()
s.Remove(2)
s.Remove(4)

fmt.Println(s)
fmt.Println(c)

Output:

[1 3 5]
[1 2 3 4 5]

func (*TreeSet[T]) Difference 

func (s *TreeSet[T]) Difference(col Collection[T]) Collection[T]

Difference returns a set that contains elements of s that are not in col.

Example 
s := TreeSetFrom[int]([]int{1, 2, 3, 4, 5}, cmp.Compare[int])
t := TreeSetFrom[int]([]int{5, 4, 3, 2, 1}, cmp.Compare[int])
f := TreeSetFrom[int]([]int{1, 3, 5, 7, 9}, cmp.Compare[int])

fmt.Println(s.Difference(t))
fmt.Println(s.Difference(f))

Output:

[]
[2 4]

func (*TreeSet[T]) Empty 

func (s *TreeSet[T]) Empty() bool

Empty returns true if there are no elements in s.

Example 
s := TreeSetFrom[string]([]string{}, cmp.Compare[string])

fmt.Println(s.Empty())

s.InsertSlice([]string{"red", "green", "blue"})

fmt.Println(s.Empty())

Output:

true
false

func (*TreeSet[T]) Equal 

func (s *TreeSet[T]) Equal(o *TreeSet[T]) bool

Equal return whether s and o contain the same elements.

Example 
s := TreeSetFrom[int]([]int{1, 2, 3, 4, 5}, cmp.Compare[int])
t := TreeSetFrom[int]([]int{5, 4, 3, 2, 1}, cmp.Compare[int])
f := TreeSetFrom[int]([]int{1, 3, 5, 7, 9}, cmp.Compare[int])

fmt.Println(s.Equal(t))
fmt.Println(s.Equal(f))

Output:

true
false

func (*TreeSet[T]) EqualSet 

func (s *TreeSet[T]) EqualSet(col Collection[T]) bool

EqualSet returns s and col contain the same elements.

func (*TreeSet[T]) EqualSlice 

func (s *TreeSet[T]) EqualSlice(items []T) bool

EqualSlice returns whether s and items contain the same elements.

The items slice may contain duplicates.

If the items slice is known to contain no duplicates, EqualSliceSet may be used instead as a faster implementation.

To detect if a slice is a subset of s, use ContainsSlice.

Example 
t := TreeSetFrom[int]([]int{5, 4, 3, 2, 1}, cmp.Compare[int])

fmt.Println(t.EqualSlice([]int{1, 2, 3, 4, 5}))
fmt.Println(t.EqualSlice([]int{1, 1, 2, 3, 4, 5}))
fmt.Println(t.EqualSlice([]int{0, 2, 3, 4, 5}))

Output:

true
true
false

func (*TreeSet[T]) EqualSliceSet 

func (s *TreeSet[T]) EqualSliceSet(items []T) bool

EqualSliceSet returns whether s and items contain exactly the same elements.

If items contains duplicates EqualSliceSet will return false. The elements of items are assumed to be set-like. For comparing s to a slice that may contain duplicate elements, use EqualSlice instead.

To detect if a slice is a subset of s, use ContainsSlice.

Example 
t := TreeSetFrom[int]([]int{5, 4, 3, 2, 1}, cmp.Compare[int])

fmt.Println(t.EqualSliceSet([]int{1, 2, 3, 4, 5}))
fmt.Println(t.EqualSliceSet([]int{1, 1, 2, 3, 4, 5}))
fmt.Println(t.EqualSliceSet([]int{0, 2, 3, 4, 5}))

Output:

true
false
false

func (*TreeSet[T]) FirstAbove 

func (s *TreeSet[T]) FirstAbove(item T) (T, bool)

FirstAbove returns the first element strictly above item.

A zero value and false are returned if no such element exists.

Example 
s := TreeSetFrom[int]([]int{1, 2, 3, 4, 5}, cmp.Compare[int])

fmt.Println(s.FirstAbove(3))
fmt.Println(s.FirstAbove(5))
fmt.Println(s.FirstAbove(10))

Output:

4 true
0 false
0 false

func (*TreeSet[T]) FirstAboveEqual 

func (s *TreeSet[T]) FirstAboveEqual(item T) (T, bool)

FirstAboveEqual returns the first element above item (or item itself if present).

A zero value and false are returned if no such element exists.

Example 
s := TreeSetFrom[int]([]int{1, 2, 3, 4, 5}, cmp.Compare[int])

fmt.Println(s.FirstAboveEqual(3))
fmt.Println(s.FirstAboveEqual(5))
fmt.Println(s.FirstAboveEqual(10))

Output:

3 true
5 true
0 false

func (*TreeSet[T]) FirstBelow 

func (s *TreeSet[T]) FirstBelow(item T) (T, bool)

FirstBelow returns the first element strictly below item.

A zero value and false are returned if no such element exists.

Example 
s := TreeSetFrom[int]([]int{1, 2, 3, 4, 5}, cmp.Compare[int])

fmt.Println(s.FirstBelow(1))
fmt.Println(s.FirstBelow(3))
fmt.Println(s.FirstBelow(10))

Output:

0 false
2 true
5 true

func (*TreeSet[T]) FirstBelowEqual 

func (s *TreeSet[T]) FirstBelowEqual(item T) (T, bool)

FirstBelowEqual returns the first element below item (or item itself if present).

A zero value and false are returned if no such element exists.

Example 
s := TreeSetFrom[int]([]int{1, 2, 3, 4, 5}, cmp.Compare[int])

fmt.Println(s.FirstBelowEqual(1))
fmt.Println(s.FirstBelowEqual(3))
fmt.Println(s.FirstBelowEqual(10))

Output:

1 true
3 true
5 true

func (*TreeSet[T]) Insert 

func (s *TreeSet[T]) Insert(item T) bool

Insert item into s.

Returns true if s was modified (item was not already in s), false otherwise.

Example 
s := TreeSetFrom[string]([]string{}, cmp.Compare[string])

fmt.Println(s)

s.Insert("red")
s.Insert("green")
s.Insert("blue")

fmt.Println(s)

// []
// [blue green red]

Output:

func (*TreeSet[T]) InsertSet 

func (s *TreeSet[T]) InsertSet(col Collection[T]) bool

InsertSet will insert each element of col into s.

Return true if s was modified (at least one item of o was not already in s), false otherwise.

Example 
s1 := TreeSetFrom[string]([]string{"red", "green"}, cmp.Compare[string])
s2 := TreeSetFrom[string]([]string{"green", "blue"}, cmp.Compare[string])

fmt.Println(s1)
fmt.Println(s2)

s1.InsertSet(s2)

fmt.Println(s1)

Output:

[green red]
[blue green]
[blue green red]

func (*TreeSet[T]) InsertSlice 

func (s *TreeSet[T]) InsertSlice(items []T) bool

InsertSlice will insert each item in items into s.

Return true if s was modified (at least one item was not already in s), false otherwise.

Example 
s := TreeSetFrom[string]([]string{}, cmp.Compare[string])

fmt.Println(s)

s.InsertSlice([]string{"red", "green", "blue"})

fmt.Println(s)

// []
// [blue green red]

Output:

func (*TreeSet[T]) Intersect 

func (s *TreeSet[T]) Intersect(col Collection[T]) Collection[T]

Intersect returns a set that contains elements that are present in both s and col.

Example 
s := TreeSetFrom[int]([]int{1, 2, 3, 4, 5}, cmp.Compare[int])
t := TreeSetFrom[int]([]int{5, 4, 3, 2, 1}, cmp.Compare[int])
f := TreeSetFrom[int]([]int{1, 3, 5, 7, 9}, cmp.Compare[int])

fmt.Println(s.Intersect(t))
fmt.Println(s.Intersect(f))

Output:

[1 2 3 4 5]
[1 3 5]

func (*TreeSet[T]) Items 

func (s *TreeSet[T]) Items() iter.Seq[T]

Items returns a generator function for iterating each element in s by using the range keyword. 

for i, element := range s.Items() { ... }

func (*TreeSet[T]) MarshalJSON 

func (s *TreeSet[T]) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface.

Example 
type Foo struct {
	Colors *TreeSet[string] `json:"colors"`
}

f := Foo{
	Colors: TreeSetFrom([]string{"red", "green", "blue"}, cmp.Compare[string]),
}

b, _ := json.Marshal(f)

fmt.Println(string(b))

Output:

{"colors":["blue","green","red"]}

func (*TreeSet[T]) Max 

func (s *TreeSet[T]) Max() T

Max returns the largest item in s.

Must not be called on an empty set.

Example 
s := TreeSetFrom[int]([]int{1, 2, 3, 4, 5}, cmp.Compare[int])
r := TreeSetFrom[int]([]int{1, 2, 3, 4, 5}, func(a int, b int) int {
	return b - a
})

fmt.Println("asc:", s.Max())
fmt.Println("desc:", r.Max())

Output:

asc: 5
desc: 1

func (*TreeSet[T]) Min 

func (s *TreeSet[T]) Min() T

Min returns the smallest item in the set.

Must not be called on an empty set.

Example 
s := TreeSetFrom[int]([]int{1, 2, 3, 4, 5}, cmp.Compare[int])
r := TreeSetFrom[int]([]int{1, 2, 3, 4, 5}, func(a int, b int) int {
	return b - a
})

fmt.Println("asc:", s.Min())
fmt.Println("desc:", r.Min())

Output:

asc: 1
desc: 5

func (*TreeSet[T]) ProperSubset 

func (s *TreeSet[T]) ProperSubset(col Collection[T]) bool

ProperSubset returns whether col is a proper subset of s.

func (*TreeSet[T]) Remove 

func (s *TreeSet[T]) Remove(item T) bool

Remove item from s.

Returns true if s was modified (item was in s), false otherwise.

Example 
s := TreeSetFrom[string]([]string{"red", "green", "blue"}, cmp.Compare[string])

fmt.Println(s)

fmt.Println(s.Remove("green"))
fmt.Println(s.Remove("orange"))

fmt.Println(s)

Output:

[blue green red]
true
false
[blue red]

func (*TreeSet[T]) RemoveFunc 

func (s *TreeSet[T]) RemoveFunc(f func(T) bool) bool

RemoveFunc will remove each element from s that satisifies condition f.

Return true if s was modified, false otherwise.

Example 
s := TreeSetFrom[int](ints(20), cmp.Compare[int])

fmt.Println(s)

even := func(i int) bool {
	return i%3 != 0
}
s.RemoveFunc(even)

fmt.Println(s)

Output:

[1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20]
[3 6 9 12 15 18]

func (*TreeSet[T]) RemoveSet 

func (s *TreeSet[T]) RemoveSet(col Collection[T]) bool

RemoveSet will remove each element in col from s.

Returns true if s was modified (at least one item in o was in s), false otherwise.

Example 
s1 := TreeSetFrom[string]([]string{"a", "b", "c", "d", "e", "f"}, cmp.Compare[string])
s2 := TreeSetFrom[string]([]string{"e", "z", "a"}, cmp.Compare[string])

fmt.Println(s1)
fmt.Println(s2)

s1.RemoveSet(s2)

fmt.Println(s1)

Output:

[a b c d e f]
[a e z]
[b c d f]

func (*TreeSet[T]) RemoveSlice 

func (s *TreeSet[T]) RemoveSlice(items []T) bool

RemoveSlice will remove each item in items from s.

Return true if s was modified (any item was in s), false otherwise.

Example 
s := TreeSetFrom[string]([]string{"red", "green", "blue"}, cmp.Compare[string])

fmt.Println(s)

fmt.Println(s.RemoveSlice([]string{"red", "blue"}))
fmt.Println(s.RemoveSlice([]string{"orange", "white"}))

fmt.Println(s)

Output:

[blue green red]
true
false
[green]

func (*TreeSet[T]) Size 

func (s *TreeSet[T]) Size() int

Size returns the number of elements in s.

Example 
s := TreeSetFrom[string]([]string{"red", "green", "blue"}, cmp.Compare[string])

fmt.Println(s.Size())

Output:

3

func (*TreeSet[T]) Slice 

func (s *TreeSet[T]) Slice() []T

Slice returns the elements of s as a slice, in order.

Example 
s := TreeSetFrom[int]([]int{1, 2, 3, 4, 5}, cmp.Compare[int])
slice := s.Slice()

fmt.Println(slice)
fmt.Println(len(slice))

Output:

[1 2 3 4 5]
5

func (*TreeSet[T]) String 

func (s *TreeSet[T]) String() string

String creates a string representation of s, using "%v" printf formatting each element into a string. The result contains elements in order.

Example 
s := TreeSetFrom[int]([]int{1, 2, 3, 4, 5}, cmp.Compare[int])

fmt.Println(s.String() == "[1 2 3 4 5]")

Output:

true

func (*TreeSet[T]) StringFunc 

func (s *TreeSet[T]) StringFunc(f func(T) string) string

StringFunc creates a string representation of s, using f to transform each element into a string. The result contains elements in order.

func (*TreeSet[T]) Subset 

func (s *TreeSet[T]) Subset(col Collection[T]) bool

Subset returns whether col is a subset of s.

Example 
s1 := TreeSetFrom[string]([]string{"a", "b", "c", "d", "e"}, cmp.Compare[string])
s2 := TreeSetFrom[string]([]string{"b", "d"}, cmp.Compare[string])
s3 := TreeSetFrom[string]([]string{"a", "z"}, cmp.Compare[string])

fmt.Println(s1.Subset(s2))
fmt.Println(s1.Subset(s3))

Output:

true
false

func (*TreeSet[T]) TopK 

func (s *TreeSet[T]) TopK(n int) []T

TopK returns the top n (smallest) elements in s, in ascending order.

Example 
s := TreeSetFrom[int]([]int{1, 2, 3, 4, 5}, cmp.Compare[int])

fmt.Println(s.TopK(0))
fmt.Println(s.TopK(1))
fmt.Println(s.TopK(3))
fmt.Println(s.TopK(5))

Output:

[]
[1]
[1 2 3]
[1 2 3 4 5]

func (*TreeSet[T]) Union 

func (s *TreeSet[T]) Union(col Collection[T]) Collection[T]

Union returns a set that contains all elements of s and col combined.

Example 
s := TreeSetFrom[int]([]int{1, 2, 3, 4, 5}, cmp.Compare[int])
t := TreeSetFrom[int]([]int{5, 4, 3, 2, 1}, cmp.Compare[int])
f := TreeSetFrom[int]([]int{1, 3, 5, 7, 9}, cmp.Compare[int])

fmt.Println(s.Union(t))
fmt.Println(s.Union(f))

Output:

[1 2 3 4 5]
[1 2 3 4 5 7 9]

func (*TreeSet[T]) UnmarshalJSON 

func (s *TreeSet[T]) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the json.Unmarshaler interface.

Example

TODO: will not work as long as CompareFunc cannot be derived from the type parameters. 

// type Foo struct {
// 	Colors *TreeSet[string] `json:"colors"`
// }

// in := `{"colors":["red","green","green","blue"]}`
// var out Foo

// _ = json.Unmarshal([]byte(in), &out)

// fmt.Println(out.Colors)

Output:

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.