set

package module
v0.0.3 Latest Latest
Warning

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

 Go to latest Published: Mar 28, 2026 License: Apache-2.0 Imports: 7 Imported by: 0

README

set

Package set provides a generic Set type for working with unordered collections of unique, comparable values.

Go Reference

Features

  • Three set types: Set[T] (mutable), FrozenSet[T] (immutable), SyncSet[T] (thread-safe mutable).
  • Supports lazy iteration using Go 1.22+ iter package.
  • Composable set operations using reducers and accumulation patterns (set.Reduce, set.Accumulate).
  • Shared set.SetLike interface enabling interoperability across set types.

Install

go get github.com/swonky/set

Usage

s := set.New(1, 2, 3)
s.Add(4)

t := set.New(3, 4, 5)

u := s.Union(t)     // {1,2,3,4,5}
s.UnionInto(t)      // mutate s

if s.Has(2) {
    // ...
}

Documentation

Overview

Package set provides a generic `Set` type for working with unordered collections of unique, comparable values.

A Set is implemented as a map[T]struct{}, offering O(1) average-case performance for insertion, deletion, and membership checks.

Basic usage: 

s := set.New(1, 2, 3)
s.Add(4)

if s.Has(2) {
	fmt.Println("contains 2")
}

Set operations: 

a := set.New(1, 2, 3)
b := set.New(3, 4, 5)

union := a.Union(b)        // {1, 2, 3, 4, 5}
inter := a.Intersect(b)    // {3}
diff := a.Diff(b)          // {1, 2}

Mutating operations: 

a.UnionInto(b) // a now contains all elements from both sets

Iteration: 

for v := range s.Iter() {
	fmt.Println(v)
}

Predicates: 

s.Any(func(v int) bool { return v%2 == 0 })
s.All(func(v int) bool { return v > 0 })

Construction from iterators: 

s := set.Collect(iter.Seq[int]{...})

Reduction and accumulation: 

sets := []set.Set[int]{
	set.New(1, 2),
	set.New(2, 3),
	set.New(3, 4),
}

Reduce combines sets left-to-right using a binary operation. 

r := set.Reduce(sets, func(a, b set.Set[int]) set.Set[int] {
	return a.Union(b)
}) // {1,2,3,4}

ReduceWhile stops when the predicate fails. 

r = set.ReduceWhile(
	sets,
	func(a, b set.Set[int]) set.Set[int] { return a.Union(b) },
	func(s set.Set[int]) bool { return s.Len() < 4 },
)

ReduceTry allows the reducer to control early termination. 

r = set.ReduceTry(
	sets,
	func(a, b set.Set[int]) (set.Set[int], bool) {
		r := a.Intersect(b)
		return r, !r.IsEmpty()
	},
)

Accumulate produces intermediate results. 

for v := range set.Accumulate(sets, func(a, b set.Set[int]) set.Set[int] {
	return a.Union(b)
}) {
	fmt.Println(v)
}

The iteration order of a Set is not defined and may vary between runs.

This package is designed to be small, predictable, and idiomatic, providing a practical set abstraction without additional dependencies or complex semantics.

Package set provides a generic set type and operations for working with sets of comparable elements. A set is implemented as a map[T]struct{} for memory efficiency and O(1) average-case operations.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Accumulate added in v0.0.2 

func Accumulate[T comparable, S SetLike[T]](
	sets []S,
	fn func(a, b S) S,
) iter.Seq[S]

Accumulate returns a iterator of intermediate accumulation results. Each step applies fn to the current accumulator and the next set. fn must return a new set and must not mutate its arguments. Iteration stops if the consumer stops early. For zero sets, a single zero value is yielded. For one set, no values are yielded.

func AccumulateTry added in v0.0.2 

func AccumulateTry[T comparable, S SetLike[T]](
	sets []S,
	fn func(a, b S) (S, bool),
) iter.Seq[S]

AccumulateTry returns an iterator of intermediate accumulation results. Each step applies fn to the current accumulator and the next set. If fn returns false, the result of that step is yielded and iteration stops. Iteration also stops if the consumer stops early. For zero sets, a single zero value is yielded. For one set, no values are yielded.

func IntersectIter added in v0.0.3 

func IntersectIter[T comparable](sets ...SetLike[T]) iter.Seq[T]

IntersectIter returns a lazy sequence of elements present in all provided sets. It iterates the smallest input set and yields elements that exist in every other set. Iteration stops early if the consumer returns false.

No intermediate sets are allocated. Membership checks are performed on demand. For zero sets, the sequence yields nothing.

func Reduce added in v0.0.2 

func Reduce[T comparable, S SetLike[T]](
	sets []S,
	fn func(a, b S) S,
) S

Reduce reduces sets by applying fn pairwise from left to right. The final accumulated value is returned. If no sets are provided, a zero value is returned.

func ReduceTry added in v0.0.2 

func ReduceTry[T comparable, S SetLike[T]](
	sets []S,
	fn func(a, b S) (S, bool),
) S

ReduceTry reduces sets using fn, stopping early if fn returns false. The result of the step that signalled stop is returned as the final value. If no sets are provided, a zero value is returned.

func ReduceUntil added in v0.0.3 

func ReduceUntil[T comparable, S SetLike[T]](
	sets []S,
	fn func(a, b S) S,
	pred func(s S) bool,
) S

ReduceUntil reduces sets using fn, stopping when pred returns true for a result. The first result that passes pred is returned. If no sets are provided, a zero value is returned.

func ReduceWhile added in v0.0.2 

func ReduceWhile[T comparable, S SetLike[T]](
	sets []S,
	fn func(a, b S) S,
	pred func(s S) bool,
) S

ReduceWhile reduces sets using fn, stopping when pred returns false for a result. The last result that passes pred is returned. If no sets are provided, a zero value is returned.

func UnionIter added in v0.0.3 

func UnionIter[T comparable](sets ...SetLike[T]) iter.Seq[T]

UnionIter returns an iterator of unique elements from the provided sets, preserving first occurrence order across sets.

Types

type FrozenSet added in v0.0.3 

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

func (FrozenSet[T]) All added in v0.0.3 

func (fs FrozenSet[T]) All(fn func(T) bool) bool

func (FrozenSet[T]) Any added in v0.0.3 

func (fs FrozenSet[T]) Any(fn func(T) bool) bool

func (FrozenSet[T]) AsSet added in v0.0.3 

func (fs FrozenSet[T]) AsSet() Set[T]

func (FrozenSet[T]) AsSlice added in v0.0.3 

func (fs FrozenSet[T]) AsSlice() []T

func (FrozenSet[T]) Clone added in v0.0.3 

func (fs FrozenSet[T]) Clone() FrozenSet[T]

func (FrozenSet[T]) Diff added in v0.0.3 

func (fs FrozenSet[T]) Diff(o FrozenSet[T]) FrozenSet[T]

func (FrozenSet[T]) Equal added in v0.0.3 

func (fs FrozenSet[T]) Equal(o FrozenSet[T]) bool

func (FrozenSet[T]) Filter added in v0.0.3 

func (fs FrozenSet[T]) Filter(fn func(T) bool) FrozenSet[T]

func (FrozenSet[T]) Find added in v0.0.3 

func (fs FrozenSet[T]) Find(fn func(T) bool) (T, bool)

func (FrozenSet[T]) First added in v0.0.3 

func (fs FrozenSet[T]) First() (T, bool)

func (FrozenSet[T]) Has added in v0.0.3 

func (fs FrozenSet[T]) Has(item T) bool

func (FrozenSet[T]) HasAll added in v0.0.3 

func (fs FrozenSet[T]) HasAll(item ...T) bool

func (FrozenSet[T]) HasAny added in v0.0.3 

func (fs FrozenSet[T]) HasAny(item ...T) bool

func (FrozenSet[T]) Intersect added in v0.0.3 

func (fs FrozenSet[T]) Intersect(o FrozenSet[T]) FrozenSet[T]

func (FrozenSet[T]) IntersectIter added in v0.0.3 

func (fs FrozenSet[T]) IntersectIter(o FrozenSet[T]) iter.Seq[T]

func (FrozenSet[T]) IsEmpty added in v0.0.3 

func (fs FrozenSet[T]) IsEmpty() bool

func (FrozenSet[T]) IsSubsetOf added in v0.0.3 

func (fs FrozenSet[T]) IsSubsetOf(o FrozenSet[T]) bool

func (FrozenSet[T]) IsSupersetOf added in v0.0.3 

func (fs FrozenSet[T]) IsSupersetOf(o FrozenSet[T]) bool

func (FrozenSet[T]) Iter added in v0.0.3 

func (fs FrozenSet[T]) Iter() iter.Seq[T]

func (FrozenSet[T]) Len added in v0.0.3 

func (fs FrozenSet[T]) Len() int

func (FrozenSet[T]) String added in v0.0.3 

func (fs FrozenSet[T]) String() string

func (FrozenSet[T]) SymDiff added in v0.0.3 

func (fs FrozenSet[T]) SymDiff(o FrozenSet[T]) FrozenSet[T]

func (FrozenSet[T]) Union added in v0.0.3 

func (fs FrozenSet[T]) Union(o FrozenSet[T]) FrozenSet[T]

func (FrozenSet[T]) UnionIter added in v0.0.3 

func (fs FrozenSet[T]) UnionIter(o FrozenSet[T]) iter.Seq[T]

type Set 

type Set[T comparable] map[T]struct{}

set represents a mathematical set of comparable elements. The zero value is ready to use but prefer using New() for initialization.

func Clone added in v0.0.2 

func Clone[T comparable](s Set[T]) Set[T]

Clone returns a shallow copy of the set.

func Collect added in v0.0.2 

func Collect[T comparable](it iter.Seq[T], size ...int) Set[T]

Collect returns a new Set containing all elements produced by the iterator. If a positive capacity hint is provided, it is used to preallocate the set.

func Intersect added in v0.0.2 

func Intersect[T comparable](sets ...Set[T]) Set[T]

Intersect returns a new Set containing elements present in all input sets. Evaluation stops early if the result becomes empty.

func Make added in v0.0.3 

func Make[T comparable](size ...int) Set[T]

Make returns a new Set with a . If no items are provided, it returns an empty set.

func New 

func New[T comparable](items ...T) Set[T]

New returns a new Set containing the provided items. If no items are provided, it returns an empty set.

func Union added in v0.0.2 

func Union[T comparable](sets ...Set[T]) Set[T]

Union returns a new Set containing all elements from the provided sets.

func (Set[T]) Add 

func (s Set[T]) Add(item T)

Add inserts an item into the set.

func (Set[T]) AddAll added in v0.0.2 

func (s Set[T]) AddAll(items ...T)

AddAll inserts one or more items into the set.

func (Set[T]) AddCheck added in v0.0.3 

func (s Set[T]) AddCheck(item T) bool

AddCheck inserts an item into the set. Returns true if item was already present.

func (Set[T]) All 

func (s Set[T]) All(fn func(T) bool) bool

All reports whether all elements satisfy fn.

func (Set[T]) Any 

func (s Set[T]) Any(fn func(T) bool) bool

Any reports whether any element satisfies fn.

func (Set[T]) AsSlice 

func (s Set[T]) AsSlice() []T

AsSlice returns elements as a slice.

func (Set[T]) Clear 

func (s Set[T]) Clear()

Clear removes all elements.

func (Set[T]) Clone 

func (s Set[T]) Clone() Set[T]

Clone returns a shallow copy.

func (Set[T]) Delete 

func (s Set[T]) Delete(item T)

Delete removes an item from the set.

func (Set[T]) Diff 

func (s Set[T]) Diff(o Set[T]) Set[T]

Diff returns elements in s but not in o.

func (Set[T]) Equal 

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

Equal reports whether two sets contain the same elements.

func (Set[T]) Filter 

func (s Set[T]) Filter(fn func(T) bool) Set[T]

Filter returns a new set containing elements satisfying fn.

func (Set[T]) Find 

func (s Set[T]) Find(fn func(T) bool) (T, bool)

Find returns the first element satisfying fn.

func (Set[T]) First 

func (s Set[T]) First() (T, bool)

First returns an arbitrary element.

func (Set[T]) Freeze added in v0.0.3 

func (s Set[T]) Freeze() FrozenSet[T]

func (Set[T]) Has 

func (s Set[T]) Has(item T) bool

Has reports whether the item is present.

func (Set[T]) HasAll added in v0.0.2 

func (s Set[T]) HasAll(item ...T) bool

HasAll reports whether all of the item are present.

func (Set[T]) HasAny added in v0.0.2 

func (s Set[T]) HasAny(item ...T) bool

HasAny reports whether any of the item are present.

func (Set[T]) Intersect 

func (s Set[T]) Intersect(o Set[T]) Set[T]

Intersect returns a new set containing elements present in both s and o. It iterates the smaller set and allocates only for actual matches.

func (Set[T]) IntersectIter added in v0.0.3 

func (s Set[T]) IntersectIter(o Set[T]) iter.Seq[T]

IntersectIter returns a lazy sequence of elements present in both s and o. The smaller set is selected before iteration to avoid branching in the hot path. No intermediate set is allocated and iteration may stop early.

func (Set[T]) IsEmpty 

func (s Set[T]) IsEmpty() bool

IsEmpty reports whether the set is empty.

func (Set[T]) IsSubsetOf 

func (s Set[T]) IsSubsetOf(o Set[T]) bool

IsSubsetOf reports whether s ⊆ o.

func (Set[T]) IsSupersetOf 

func (s Set[T]) IsSupersetOf(o Set[T]) bool

IsSupersetOf reports whether s ⊇ o.

func (Set[T]) Iter 

func (s Set[T]) Iter() iter.Seq[T]

Iter returns an iterator over the set.

func (Set[T]) Len 

func (s Set[T]) Len() int

Len returns the number of elements.

func (Set[T]) Pop 

func (s Set[T]) Pop() (T, bool)

Pop removes and returns an arbitrary element.

func (Set[T]) String 

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

String returns a string representation.

func (Set[T]) SymDiff added in v0.0.3 

func (s Set[T]) SymDiff(o Set[T]) Set[T]

SymDiff returns elements in either set but not both.

func (Set[T]) Union 

func (s Set[T]) Union(o Set[T]) Set[T]

Union returns a new set containing all elements from s and o. It clones the smaller set and inserts elements from the larger, minimizing total copy and insert work.

func (Set[T]) UnionInto 

func (s Set[T]) UnionInto(o Set[T])

UnionInto inserts all elements from o into s in place. It performs a single pass over o with no allocations.

func (Set[T]) UnionIter added in v0.0.3 

func (s Set[T]) UnionIter(o Set[T]) iter.Seq[T]

UnionIter returns a lazy sequence of elements from the larger set, followed by elements from the smaller set not already present. Membership checks are performed against the smaller set to reduce probes. No intermediate state is allocated.

type SetLike added in v0.0.3 

type SetLike[T comparable] interface {
	All(fn func(T) bool) bool
	Any(fn func(T) bool) bool
	AsSlice() []T
	Find(fn func(T) bool) (T, bool)
	First() (T, bool)
	Has(item T) bool
	HasAll(item ...T) bool
	HasAny(item ...T) bool
	IsEmpty() bool
	Iter() iter.Seq[T]
	Len() int
	String() string
}

type SyncSet added in v0.0.3 

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

SyncSet is a concurrency-safe wrapper around Set. All operations are guarded by a RWMutex. Iteration holds a read lock for the duration of the sequence.

func FromSet added in v0.0.3 

func FromSet[T comparable](s Set[T]) *SyncSet[T]

FromSet creates a SyncSet initialized with a clone of s.

func NewSync added in v0.0.3 

func NewSync[T comparable]() *SyncSet[T]

NewSync returns an empty SyncSet.

func (*SyncSet[T]) Add added in v0.0.3 

func (ss *SyncSet[T]) Add(item T)

Add inserts item into the set.

func (*SyncSet[T]) All added in v0.0.3 

func (ss *SyncSet[T]) All(fn func(T) bool) bool

func (*SyncSet[T]) Any added in v0.0.3 

func (ss *SyncSet[T]) Any(fn func(T) bool) bool

func (*SyncSet[T]) AsSet added in v0.0.3 

func (ss *SyncSet[T]) AsSet() Set[T]

AsSet creates a new mutable thread-unsafe Set. The new Set is initialized with a clone of the contents of ss.

func (*SyncSet[T]) AsSlice added in v0.0.3 

func (ss *SyncSet[T]) AsSlice() []T

func (*SyncSet[T]) Clear added in v0.0.3 

func (ss *SyncSet[T]) Clear()

Clear removes all elements from the set.

func (*SyncSet[T]) Clone added in v0.0.3 

func (ss *SyncSet[T]) Clone() FrozenSet[T]

func (*SyncSet[T]) Delete added in v0.0.3 

func (ss *SyncSet[T]) Delete(item T)

Delete removes item from the set.

func (*SyncSet[T]) Diff added in v0.0.3 

func (ss *SyncSet[T]) Diff(o *SyncSet[T]) FrozenSet[T]

func (*SyncSet[T]) Equal added in v0.0.3 

func (ss *SyncSet[T]) Equal(o *SyncSet[T]) bool

func (*SyncSet[T]) Filter added in v0.0.3 

func (ss *SyncSet[T]) Filter(fn func(T) bool) FrozenSet[T]

func (*SyncSet[T]) Find added in v0.0.3 

func (ss *SyncSet[T]) Find(fn func(T) bool) (T, bool)

func (*SyncSet[T]) First added in v0.0.3 

func (ss *SyncSet[T]) First() (T, bool)

func (*SyncSet[T]) Has added in v0.0.3 

func (ss *SyncSet[T]) Has(item T) bool

Has reports whether item exists in the set.

func (*SyncSet[T]) HasAdd added in v0.0.3 

func (ss *SyncSet[T]) HasAdd(item T) bool

HasAdd inserts item and reports whether it was already present.

func (*SyncSet[T]) HasAll added in v0.0.3 

func (ss *SyncSet[T]) HasAll(item ...T) bool

func (*SyncSet[T]) HasAny added in v0.0.3 

func (ss *SyncSet[T]) HasAny(item ...T) bool

func (*SyncSet[T]) Intersect added in v0.0.3 

func (ss *SyncSet[T]) Intersect(o *SyncSet[T]) FrozenSet[T]

func (*SyncSet[T]) IntersectIter added in v0.0.3 

func (ss *SyncSet[T]) IntersectIter(o *SyncSet[T]) iter.Seq[T]

IntersectIter returns an iterator of elements present in both sets. Locks are held only during snapshot creation.

func (*SyncSet[T]) IsEmpty added in v0.0.3 

func (ss *SyncSet[T]) IsEmpty() bool

func (*SyncSet[T]) IsSubsetOf added in v0.0.3 

func (ss *SyncSet[T]) IsSubsetOf(o *SyncSet[T]) bool

func (*SyncSet[T]) IsSupersetOf added in v0.0.3 

func (ss *SyncSet[T]) IsSupersetOf(o *SyncSet[T]) bool

func (*SyncSet[T]) Iter added in v0.0.3 

func (ss *SyncSet[T]) Iter() iter.Seq[T]

Iter returns a sequence of elements in the set. A read lock is held for the duration of iteration.

func (*SyncSet[T]) Len added in v0.0.3 

func (ss *SyncSet[T]) Len() int

Len returns the number of elements in the set.

func (*SyncSet[T]) String added in v0.0.3 

func (ss *SyncSet[T]) String() string

func (*SyncSet[T]) SymDiff added in v0.0.3 

func (ss *SyncSet[T]) SymDiff(o *SyncSet[T]) FrozenSet[T]

func (*SyncSet[T]) Union added in v0.0.3 

func (ss *SyncSet[T]) Union(o *SyncSet[T]) FrozenSet[T]

func (*SyncSet[T]) UnionInto added in v0.0.3 

func (ss *SyncSet[T]) UnionInto(o *SyncSet[T])

func (*SyncSet[T]) UnionIter added in v0.0.3 

func (ss *SyncSet[T]) UnionIter(o *SyncSet[T]) iter.Seq[T]

UnionIter returns an iterator of all elements from both sets. Locks are held only during snapshot creation.

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.