sets

README

sets

Sets and Set operations in golang

Internally as simple as a map[T]struct{} but with additional helper functions, operations like Union, Intersect, XOR, to/from Slices conversion, to/from JSON, etc... and hiding the struct{}{} etc...

See https://pkg.go.dev/fortio.org/sets

Documentation

Overview

Sets and Set type and operations of any comparable type (go 1.18+ generics) Intersection, Union, Set.Subset, difference aka Set.Minus, XOR, JSON serialization and deserialization and more. Version 1.2.1 only requires go1.18 for generics. Version 1.3.0 requires go1.21 (and newer) for stdlib cmp, maps and slices packages.

Index

• func RemoveCommon[T comparable](a, b Set[T])
• func Sort[Q cmp.Ordered](s Set[Q]) []Q
• func Tuplets[Q cmp.Ordered](s Set[Q], n int) [][]Q
• func XOR[T comparable](a, b Set[T])
• type Set
  • func FromSlice[T comparable](items []T) Set[T]
  • func Intersection[T comparable](sets ...Set[T]) Set[T]
  • func New[T comparable](item ...T) Set[T]
  • func Union[T comparable](sets ...Set[T]) Set[T]
  • func (s Set[T]) Add(item ...T)
  • func (s Set[T]) Clear()
  • func (s Set[T]) Clone() Set[T]
  • func (s Set[T]) Elements() []T
  • func (s Set[T]) Equals(other Set[T]) bool
  • func (s Set[T]) Has(item T) bool
  • func (s Set[T]) Len() int
  • func (s Set[T]) MarshalJSON() ([]byte, error)
  • func (s Set[T]) Minus(other Set[T]) Set[T]
  • func (s Set[T]) Plus(others ...Set[T]) Set[T]
  • func (s Set[T]) Remove(item ...T)
  • func (s Set[T]) String() string
  • func (s Set[T]) Subset(bigger Set[T]) bool
  • func (s *Set[T]) UnmarshalJSON(data []byte) error

Functions

func RemoveCommon

func RemoveCommon[T comparable](a, b Set[T])

RemoveCommon removes elements from both sets that are in both, leaving only the delta. Useful when a is an old value and b is new and you want to apply some operation on all removed and added elements.

func Sort

func Sort[Q cmp.Ordered](s Set[Q]) []Q

Sort returns a sorted slice of the elements in the set. Only applicable for when the type is sortable.

func Tuplets

func Tuplets[Q cmp.Ordered](s Set[Q], n int) [][]Q

Tuplets generates all the combinations of N of elements of the set. for n = 2, it would return all pairs of elements. for n = 3, all triplets, etc.

func XOR

func XOR[T comparable](a, b Set[T])

XOR is an alias for RemoveCommon, efficiently removes from each set the common elements.

Types

type Set

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

Set defines a low memory footprint set of any comparable type. Based on map[T]struct{}.

func FromSlice

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

FromSlice constructs a Set from a slice. [Elements] is the inverse function, getting back a slice from the Set. This is a short cut/alias for New[T](items...).

func Intersection

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

Intersection returns a new set that has the elements common to all the input sets.

func New

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

New returns a new set containing the given elements.

func Union

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

Union returns a new set that has all the elements of all the sets. Note that Union(s1) == s1.Clone() and Union[T]() == New[T]().

func (Set[T]) Add

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

Add items to the set. Add and thus its callers will panic() if NaN is passed in.

func (Set[T]) Clear

func (s Set[T]) Clear()

Clear removes all elements from the set.

func (Set[T]) Clone

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

Clone returns a copy of the set.

func (Set[T]) Elements

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

Elements returns a slice of the elements in the set.

func (Set[T]) Equals

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

Equals returns true if the two sets have the same elements.

func (Set[T]) Has

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

Has returns true if the item is present in the set.

func (Set[T]) Len

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

Len returns the number of elements in the set (same as len(s) but as a method).

func (Set[T]) MarshalJSON

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

MarshalJSON implements the json.Marshaler interface and only gets the elements as an array.

func (Set[T]) Minus

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

Minus mutates the receiver to remove all the elements of the passed in set. If you want a copy use s.Clone().Minus(other). Returns the receiver for chaining.

func (Set[T]) Plus

func (s Set[T]) Plus(others ...Set[T]) Set[T]

Plus is similar to Union but mutates the receiver. Added for symmetry with Set.Minus. Returns the receiver for chaining.

func (Set[T]) Remove

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

Remove items from the set.

func (Set[T]) String

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

String() returns a coma separated list of the elements in the set. This is mostly for troubleshooting/debug output unless the [T] serializes to a string that doesn't contain commas.

func (Set[T]) Subset

func (s Set[T]) Subset(bigger Set[T]) bool

Subset returns true if all elements of s are in the passed in set.

func (*Set[T]) UnmarshalJSON

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

UnmarshalJSON implements the json.Unmarshaler interface turns the slice back to a Set.