setz

package
v1.2.2 Latest Latest
Warning

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

 Go to latest Published: Feb 13, 2026 License: MIT Imports: 1 Imported by: 0

README

setz

Generic set data structure for Go

The setz package provides a Set[T] type with O(1) operations for set membership, union, intersection, and more. Implemented as a type alias of map[T]struct{} for zero overhead.

Quick Reference

By Category:

Installation

go get github.com/modfin/henry/setz

Usage

import "github.com/modfin/henry/setz"

// Create sets
s1 := setz.New(1, 2, 3, 4, 5)
s2 := setz.New(4, 5, 6, 7, 8)

// Set operations
union := s1.Union(s2)           // {1, 2, 3, 4, 5, 6, 7, 8}
intersection := s1.Intersection(s2)  // {4, 5}
difference := s1.Difference(s2)    // {1, 2, 3}

// Check membership
if s1.Contains(3) {
    fmt.Println("3 is in the set")
}

Construction

New

Create a set from elements.

s := setz.New(1, 2, 3, 4, 5)
// s = Set{1, 2, 3, 4, 5}
FromSlice

Create from a slice.

nums := []int{1, 2, 2, 3, 3, 3}
s := setz.FromSlice(nums)
// s = Set{1, 2, 3} (duplicates removed)
FromMap

Create from an existing map.

m := map[string]struct{}{"a": {}, "b": {}}
s := setz.FromMap(m)
// s = Set{"a", "b"}

Basic Operations

Add

Add elements (mutates).

s := setz.New(1, 2)
s.Add(3, 4, 5)
// s = Set{1, 2, 3, 4, 5}
Remove

Remove elements (mutates).

s := setz.New(1, 2, 3, 4, 5)
s.Remove(2, 4)
// s = Set{1, 3, 5}
Contains

Check membership.

s := setz.New(1, 2, 3)
s.Contains(2)    // true
s.Contains(5)    // false
ContainsAll

Check if all elements are present.

s := setz.New(1, 2, 3, 4, 5)
s.ContainsAll(2, 4)     // true
s.ContainsAll(2, 6)     // false (6 not in set)
Pop

Remove and return arbitrary element.

s := setz.New(1, 2, 3)
elem, ok := s.Pop()
// elem = 1 (or 2 or 3), ok = true
// s now has 2 elements

// Empty set
empty := setz.New[int]()
elem, ok := empty.Pop()
// elem = 0 (zero value), ok = false
Clear

Remove all elements (mutates).

s := setz.New(1, 2, 3)
s.Clear()
// s = Set{}
Len

Get number of elements.

s := setz.New(1, 2, 3)
n := s.Len()   // n = 3
IsEmpty

Check if empty.

s := setz.New[int]()
s.IsEmpty()   // true

Set Operations

Union

Combine two sets (new set).

s1 := setz.New(1, 2, 3)
s2 := setz.New(2, 3, 4)
union := s1.Union(s2)
// union = Set{1, 2, 3, 4}
Intersection

Common elements (new set).

s1 := setz.New(1, 2, 3, 4)
s2 := setz.New(3, 4, 5, 6)
common := s1.Intersection(s2)
// common = Set{3, 4}
Difference

Elements in first but not second (new set).

s1 := setz.New(1, 2, 3, 4)
s2 := setz.New(3, 4, 5, 6)
diff := s1.Difference(s2)
// diff = Set{1, 2}
SymmetricDifference

Elements in exactly one set (XOR).

s1 := setz.New(1, 2, 3)
s2 := setz.New(2, 3, 4)
xor := s1.SymmetricDifference(s2)
// xor = Set{1, 4}

Predicates

IsSubset

Check if all elements are in another set.

small := setz.New(1, 2)
large := setz.New(1, 2, 3, 4)
small.IsSubset(large)    // true
large.IsSubset(small)    // false
IsSuperset

Check if contains all elements of another set.

large := setz.New(1, 2, 3, 4)
small := setz.New(1, 2)
large.IsSuperset(small)  // true
IsProperSubset

Subset but not equal.

a := setz.New(1, 2)
b := setz.New(1, 2, 3)
a.IsProperSubset(b)   // true
b.IsProperSubset(a)   // false
IsProperSuperset

Superset but not equal.

a := setz.New(1, 2, 3)
b := setz.New(1, 2)
a.IsProperSuperset(b)  // true
IsDisjoint

No common elements.

s1 := setz.New(1, 2, 3)
s2 := setz.New(4, 5, 6)
s1.IsDisjoint(s2)   // true

s3 := setz.New(3, 4, 5)
s1.IsDisjoint(s3)   // false (3 in common)
IsEqual

Same elements.

s1 := setz.New(1, 2, 3)
s2 := setz.New(3, 2, 1)  // Order doesn't matter
s1.IsEqual(s2)   // true

Conversion

ToSlice

Convert to slice (order not guaranteed).

s := setz.New(1, 2, 3)
slice := s.ToSlice()
// slice = []int{1, 2, 3} (or any order)
Copy

Create a copy.

s1 := setz.New(1, 2, 3)
s2 := s1.Copy()
// s2 is independent copy
Filter

Filter elements (new set).

s := setz.New(1, 2, 3, 4, 5, 6)
evens := s.Filter(func(n int) bool {
    return n%2 == 0
})
// evens = Set{2, 4, 6}
Map

Transform elements (new set).

s := setz.New(1, 2, 3)
doubled := setz.Map(s, func(n int) int {
    return n * 2
})
// doubled = Set{2, 4, 6}

Standalone Functions

Union (variadic)

Union of multiple sets.

s1 := setz.New(1, 2)
s2 := setz.New(2, 3)
s3 := setz.New(3, 4)
combined := setz.Union(s1, s2, s3)
// combined = Set{1, 2, 3, 4}
Intersection (variadic)

Intersection of multiple sets.

s1 := setz.New(1, 2, 3, 4)
s2 := setz.New(2, 3, 4, 5)
s3 := setz.New(3, 4, 5, 6)
common := setz.Intersection(s1, s2, s3)
// common = Set{3, 4}
Difference (variadic)

Difference with multiple sets.

s1 := setz.New(1, 2, 3, 4, 5)
s2 := setz.New(2, 3)
s3 := setz.New(4)
result := setz.Difference(s1, s2, s3)
// result = Set{1, 5}
Contains (standalone)

Check membership (functional style).

s := setz.New(1, 2, 3)
setz.Contains(s, 2)   // true
ToSlice (standalone)

Convert to slice.

s := setz.New(1, 2, 3)
slice := setz.ToSlice(s)
IsSubset (standalone)

Check subset relation.

small := setz.New(1, 2)
large := setz.New(1, 2, 3)
setz.IsSubset(small, large)   // true
IsDisjoint (standalone)

Check disjointness.

s1 := setz.New(1, 2)
s2 := setz.New(3, 4)
setz.IsDisjoint(s1, s2)   // true

String Representation

s := setz.New(1, 2, 3)
fmt.Println(s.String())
// Output: Set[1 2 3] (or any order)

empty := setz.New[int]()
fmt.Println(empty.String())
// Output: Set{}

Performance

  • O(1) operations: Add, Remove, Contains, Len
  • O(n) operations: Union, Intersection, ToSlice
  • Zero overhead: Set[T] is just map[T]struct{}
  • Memory efficient: Uses empty struct (0 bytes) for values

Comparison with slicez

Use setz when:

  • You need O(1) membership testing
  • Doing set operations (union, intersection)
  • Deduplication is the primary concern

Use slicez set functions when:

  • Order matters
  • You need indexed access
  • Memory is constrained (sets use 2x memory)
// setz version - O(1) lookup
s := setz.New(1, 2, 3, 4, 5)
exists := s.Contains(3)

// slicez version - O(n) lookup
nums := []int{1, 2, 3, 4, 5}
exists := slicez.Contains(nums, 3)

See Also

  • slicez - Set operations on slices (Uniq, Union, Intersection, etc.)
  • mapz - Underlying map operations

Documentation

Overview

Package setz provides generic set data structures and operations. It offers both a Set type with methods for fluent API usage and standalone functions for interoperability with other packages in the henry library.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Contains 

func Contains[T comparable](s Set[T], element T) bool

Contains returns true if the element is in the set. Standalone function version.

func IsDisjoint 

func IsDisjoint[T comparable](a, b Set[T]) bool

IsDisjoint returns true if a and b have no elements in common. Standalone function version.

func IsSubset 

func IsSubset[T comparable](a, b Set[T]) bool

IsSubset returns true if all elements of a are in b. Standalone function version.

func ToSlice 

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

ToSlice returns all elements from a set as a slice. Standalone function version.

Types

type Set 

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

Set represents a mathematical set of unique elements. It is implemented as a type alias of map[T]struct{} for O(1) operations. The Set is mutable - methods like Add, Remove, and Clear modify the set. Operations like Union, Intersection return new sets (immutable results).

func Difference 

func Difference[T comparable](first Set[T], others ...Set[T]) Set[T]

Difference returns a new set with elements in the first set but not in others. Standalone function version.

func FromMap 

func FromMap[T comparable](m Set[T]) Set[T]

FromMap creates a Set from an existing map[T]struct{}. This allows interoperability with slicez.Set() output.

Example: 

m := map[string]struct{}{"a": {}, "b": {}}
s := setz.FromMap(m)  // Set with "a", "b"

func FromSlice 

func FromSlice[T comparable](slice []T) Set[T]

FromSlice creates a Set from a slice, removing duplicates.

Example: 

s := setz.FromSlice([]int{1, 2, 2, 3, 3, 3})
// s contains {1, 2, 3}

func Intersection 

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

Intersection returns a new set with elements common to all sets. Standalone function version.

func Map 

func Map[T comparable, U comparable](s Set[T], mapper func(T) U) Set[U]

Map returns a new set by applying a function to each element.

func New 

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

New creates a new empty Set with optional initial elements.

Example: 

s := setz.New[int]()           // Empty set
s := setz.New(1, 2, 3)         // Set with elements 1, 2, 3
s := setz.New("a", "b", "c")     // Set of strings

func Union 

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

Union returns a new set with all elements from the given sets. Standalone function version.

func (Set[T]) Add 

func (s Set[T]) Add(elements ...T) Set[T]

Add adds elements to the set. Returns the set for chaining.

Example: 

s := setz.New[int]().Add(1, 2, 3).Add(4)

func (Set[T]) Clear 

func (s Set[T]) Clear()

Clear removes all elements from the set.

func (Set[T]) Contains 

func (s Set[T]) Contains(element T) bool

Contains returns true if the element is in the set.

Example: 

s := setz.New(1, 2, 3)
s.Contains(2)  // true
s.Contains(5)  // false

func (Set[T]) ContainsAll 

func (s Set[T]) ContainsAll(elements ...T) bool

ContainsAll returns true if all elements are in the set.

func (Set[T]) Copy 

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

Copy returns a new set with the same elements.

func (Set[T]) Difference 

func (s Set[T]) Difference(other Set[T]) Set[T]

Difference returns a new set with elements in s but not in other.

Example: 

s1 := setz.New(1, 2, 3, 4)
s2 := setz.New(2, 4)
s1.Difference(s2)  // {1, 3}

func (Set[T]) Filter 

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

Filter returns a new set with elements that satisfy the predicate.

func (Set[T]) Intersection 

func (s Set[T]) Intersection(other Set[T]) Set[T]

Intersection returns a new set with elements common to both sets.

Example: 

s1 := setz.New(1, 2, 3, 4)
s2 := setz.New(2, 3, 4, 5)
s1.Intersection(s2)  // {2, 3, 4}

func (Set[T]) IsDisjoint 

func (s Set[T]) IsDisjoint(other Set[T]) bool

IsDisjoint returns true if s and other have no elements in common.

Example: 

s1 := setz.New(1, 2)
s2 := setz.New(3, 4)
s1.IsDisjoint(s2)  // true

func (Set[T]) IsEmpty 

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

IsEmpty returns true if the set has no elements.

func (Set[T]) IsEqual 

func (s Set[T]) IsEqual(other Set[T]) bool

IsEqual returns true if s and other contain the same elements.

func (Set[T]) IsProperSubset 

func (s Set[T]) IsProperSubset(other Set[T]) bool

IsProperSubset returns true if s is a subset of other and s ≠ other.

func (Set[T]) IsProperSuperset 

func (s Set[T]) IsProperSuperset(other Set[T]) bool

IsProperSuperset returns true if s is a superset of other and s ≠ other.

func (Set[T]) IsSubset 

func (s Set[T]) IsSubset(other Set[T]) bool

IsSubset returns true if all elements of s are in other.

Example: 

s1 := setz.New(1, 2)
s2 := setz.New(1, 2, 3)
s1.IsSubset(s2)  // true
s2.IsSubset(s1)  // false

func (Set[T]) IsSuperset 

func (s Set[T]) IsSuperset(other Set[T]) bool

IsSuperset returns true if s contains all elements of other.

Example: 

s1 := setz.New(1, 2, 3)
s2 := setz.New(1, 2)
s1.IsSuperset(s2)  // true

func (Set[T]) Len 

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

Len returns the number of elements in the set.

func (Set[T]) Pop 

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

Pop removes and returns an arbitrary element from the set. Returns the zero value and false if the set is empty.

func (Set[T]) Remove 

func (s Set[T]) Remove(elements ...T) Set[T]

Remove removes elements from the set. Returns the set for chaining.

Example: 

s := setz.New(1, 2, 3, 4).Remove(2, 3)  // s contains {1, 4}

func (Set[T]) String 

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

String returns a string representation of the set. Note: Element order is not guaranteed.

func (Set[T]) SymmetricDifference 

func (s Set[T]) SymmetricDifference(other Set[T]) Set[T]

SymmetricDifference returns a new set with elements in either set but not both. This is equivalent to (s ∪ other) - (s ∩ other).

Example: 

s1 := setz.New(1, 2, 3)
s2 := setz.New(2, 3, 4)
s1.SymmetricDifference(s2)  // {1, 4}

func (Set[T]) ToSlice 

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

ToSlice returns all elements as a slice (order not guaranteed).

func (Set[T]) Union 

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

Union returns a new set with all elements from both sets.

Example: 

s1 := setz.New(1, 2, 3)
s2 := setz.New(3, 4, 5)
s1.Union(s2)  // {1, 2, 3, 4, 5}

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.