mapset

README

golang-set

The missing generic set collection for the Go language. Until Go has sets built-in...use this.

Update 3/5/2023

• Packaged version: 2.2.0 release includes a refactor to minimize pointer indirection, better method documentation standards and a few constructor convenience methods to increase ergonomics when appending items Append or creating a new set from an exist Map.
• supports new generic syntax
• Go 1.18.0 or higher
• Workflow tested on Go 1.20

Coming from Python one of the things I miss is the superbly wonderful set collection. This is my attempt to mimic the primary features of the set collection from Python. You can of course argue that there is no need for a set in Go, otherwise the creators would have added one to the standard library. To those I say simply ignore this repository and carry-on and to the rest that find this useful please contribute in helping me make it better by contributing with suggestions or PRs.

Install

Use go get to install this package.

go get github.com/deckarep/golang-set/v2

Features

• NEW Generics based implementation (requires Go 1.18 or higher)
• One common interface to both implementations
  • a non threadsafe implementation favoring performance
  • a threadsafe implementation favoring concurrent use
• Feature complete set implementation modeled after Python's set implementation.
• Exhaustive unit-test and benchmark suite

Trusted by

This package is trusted by many companies and thousands of open-source packages. Here are just a few sample users of this package.

• Notable projects/companies using this package
  • Ethereum
  • Docker
  • 1Password
  • Hashicorp

Star History

Usage

The code below demonstrates how a Set collection can better manage data and actually minimize boilerplate and needless loops in code. This package now fully supports generic syntax so you are now able to instantiate a collection for any comparable type object.

What is considered comparable in Go?

• Booleans, integers, strings, floats or basically primitive types.
• Pointers
• Arrays
• Structs if all of their fields are also comparable independently

Using this library is as simple as creating either a threadsafe or non-threadsafe set and providing a comparable type for instantiation of the collection.

// Syntax example, doesn't compile.
mySet := mapset.NewSet[T]() // where T is some concrete comparable type.

// Therefore this code creates an int set
mySet := mapset.NewSet[int]()

// Or perhaps you want a string set
mySet := mapset.NewSet[string]()

type myStruct struct {
  name string
  age uint8
}

// Alternatively a set of structs
mySet := mapset.NewSet[myStruct]()

// Lastly a set that can hold anything using the any or empty interface keyword: interface{}. This is effectively removes type safety.
mySet := mapset.NewSet[any]()

Comprehensive Example

package main

import (
  "fmt"
  mapset "github.com/deckarep/golang-set/v2"
)

func main() {
  // Create a string-based set of required classes.
  required := mapset.NewSet[string]()
  required.Add("cooking")
  required.Add("english")
  required.Add("math")
  required.Add("biology")

  // Create a string-based set of science classes.
  sciences := mapset.NewSet[string]()
  sciences.Add("biology")
  sciences.Add("chemistry")
  
  // Create a string-based set of electives.
  electives := mapset.NewSet[string]()
  electives.Add("welding")
  electives.Add("music")
  electives.Add("automotive")

  // Create a string-based set of bonus programming classes.
  bonus := mapset.NewSet[string]()
  bonus.Add("beginner go")
  bonus.Add("python for dummies")
}

Create a set of all unique classes. Sets will automatically deduplicate the same data.

  all := required
    .Union(sciences)
    .Union(electives)
    .Union(bonus)
  
  fmt.Println(all)

Output:

Set{cooking, english, math, chemistry, welding, biology, music, automotive, beginner go, python for dummies}

Is cooking considered a science class?

result := sciences.Contains("cooking")
fmt.Println(result)

Output:

false

Show me all classes that are not science classes, since I don't enjoy science.

notScience := all.Difference(sciences)
fmt.Println(notScience)

Set{ music, automotive, beginner go, python for dummies, cooking, english, math, welding }

Which science classes are also required classes?

reqScience := sciences.Intersect(required)

Output:

Set{biology}

How many bonus classes do you offer?

fmt.Println(bonus.Cardinality())

Output:

2

Thanks for visiting!

-deckarep

Documentation

Overview

Package mapset implements a simple and set collection. Items stored within it are unordered and unique. It supports typical set operations: membership testing, intersection, union, difference, symmetric difference and cloning.

Package mapset provides two implementations of the Set interface. The default implementation is safe for concurrent access, but a non-thread-safe implementation is also provided for programs that can benefit from the slight speed improvement and that can enforce mutual exclusion through other means.

Index

• func Sorted[E cmp.Ordered](set Set[E]) []E
• type Iterator
  • func (i *Iterator[T]) Stop()
• type Set
  • func NewSet[T comparable](vals ...T) Set[T]
  • func NewSetFromMapKeys[T comparable, V any](val map[T]V) Set[T]
  • func NewSetWithSize[T comparable](cardinality int) Set[T]
  • func NewThreadUnsafeSet[T comparable](vals ...T) Set[T]
  • func NewThreadUnsafeSetFromMapKeys[T comparable, V any](val map[T]V) Set[T]
  • func NewThreadUnsafeSetWithSize[T comparable](cardinality int) Set[T]

Functions

func Sorted

func Sorted[E cmp.Ordered](set Set[E]) []E

Sorted returns a sorted slice of a set of any ordered type in ascending order. When sorting floating-point numbers, NaNs are ordered before other values.

Types

type Iterator

type Iterator[T comparable] struct {
	C <-chan T
	// contains filtered or unexported fields
}

Iterator defines an iterator over a Set, its C channel can be used to range over the Set's elements.

func (*Iterator[T]) Stop

func (i *Iterator[T]) Stop()

Stop stops the Iterator, no further elements will be received on C, C will be closed.

type Set

type Set[T comparable] interface {
	// Add adds an element to the set. Returns whether
	// the item was added.
	Add(val T) bool

	// Append multiple elements to the set. Returns
	// the number of elements added.
	Append(val ...T) int

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

	// Clear removes all elements from the set, leaving
	// the empty set.
	Clear()

	// Clone returns a clone of the set using the same
	// implementation, duplicating all keys.
	Clone() Set[T]

	// Contains returns whether the given items
	// are all in the set.
	Contains(val ...T) bool

	// ContainsOne returns whether the given item
	// is in the set.
	//
	// Contains may cause the argument to escape to the heap.
	// See: https://github.com/deckarep/golang-set/issues/118
	ContainsOne(val T) bool

	// ContainsAny returns whether at least one of the
	// given items are in the set.
	ContainsAny(val ...T) bool

	// Difference returns the difference between this set
	// and other. The returned set will contain
	// all elements of this set that are not also
	// elements of other.
	//
	// Note that the argument to Difference
	// must be of the same type as the receiver
	// of the method. Otherwise, Difference will
	// panic.
	Difference(other Set[T]) Set[T]

	// Equal determines if two sets are equal to each
	// other. If they have the same cardinality
	// and contain the same elements, they are
	// considered equal. The order in which
	// the elements were added is irrelevant.
	//
	// Note that the argument to Equal must be
	// of the same type as the receiver of the
	// method. Otherwise, Equal will panic.
	Equal(other Set[T]) bool

	// Intersect returns a new set containing only the elements
	// that exist only in both sets.
	//
	// Note that the argument to Intersect
	// must be of the same type as the receiver
	// of the method. Otherwise, Intersect will
	// panic.
	Intersect(other Set[T]) Set[T]

	// IsEmpty determines if there are elements in the set.
	IsEmpty() bool

	// IsProperSubset determines if every element in this set is in
	// the other set but the two sets are not equal.
	//
	// Note that the argument to IsProperSubset
	// must be of the same type as the receiver
	// of the method. Otherwise, IsProperSubset
	// will panic.
	IsProperSubset(other Set[T]) bool

	// IsProperSuperset determines if every element in the other set
	// is in this set but the two sets are not
	// equal.
	//
	// Note that the argument to IsSuperset
	// must be of the same type as the receiver
	// of the method. Otherwise, IsSuperset will
	// panic.
	IsProperSuperset(other Set[T]) bool

	// IsSubset determines if every element in this set is in
	// the other set.
	//
	// Note that the argument to IsSubset
	// must be of the same type as the receiver
	// of the method. Otherwise, IsSubset will
	// panic.
	IsSubset(other Set[T]) bool

	// IsSuperset determines if every element in the other set
	// is in this set.
	//
	// Note that the argument to IsSuperset
	// must be of the same type as the receiver
	// of the method. Otherwise, IsSuperset will
	// panic.
	IsSuperset(other Set[T]) bool

	// Each iterates over elements and executes the passed func against each element.
	// If passed func returns true, stop iteration at the time.
	Each(func(T) bool)

	// Iter returns a channel of elements that you can
	// range over.
	Iter() <-chan T

	// Iterator returns an Iterator object that you can
	// use to range over the set.
	Iterator() *Iterator[T]

	// Remove removes a single element from the set.
	Remove(i T)

	// RemoveAll removes multiple elements from the set.
	RemoveAll(i ...T)

	// String provides a convenient string representation
	// of the current state of the set.
	String() string

	// SymmetricDifference returns a new set with all elements which are
	// in either this set or the other set but not in both.
	//
	// Note that the argument to SymmetricDifference
	// must be of the same type as the receiver
	// of the method. Otherwise, SymmetricDifference
	// will panic.
	SymmetricDifference(other Set[T]) Set[T]

	// Union returns a new set with all elements in both sets.
	//
	// Note that the argument to Union must be of the
	// same type as the receiver of the method.
	// Otherwise, Union will panic.
	Union(other Set[T]) Set[T]

	// Pop removes and returns an arbitrary item from the set.
	Pop() (T, bool)

	// ToSlice returns the members of the set as a slice.
	ToSlice() []T

	// MarshalJSON will marshal the set into a JSON-based representation.
	MarshalJSON() ([]byte, error)

	// UnmarshalJSON will unmarshal a JSON-based byte slice into a full Set datastructure.
	// For this to work, set subtypes must implemented the Marshal/Unmarshal interface.
	UnmarshalJSON(b []byte) error
}

Set is the primary interface provided by the mapset package. It represents an unordered set of data and a large number of operations that can be applied to that set.

func NewSet

func NewSet[T comparable](vals ...T) Set[T]

NewSet creates and returns a new set with the given elements. Operations on the resulting set are thread-safe.

func NewSetFromMapKeys

func NewSetFromMapKeys[T comparable, V any](val map[T]V) Set[T]

NewSetFromMapKeys creates and returns a new set with the given keys of the map. Operations on the resulting set are thread-safe.

func NewSetWithSize

func NewSetWithSize[T comparable](cardinality int) Set[T]

NewSetWithSize creates and returns a reference to an empty set with a specified capacity. Operations on the resulting set are thread-safe.

func NewThreadUnsafeSet

func NewThreadUnsafeSet[T comparable](vals ...T) Set[T]

NewThreadUnsafeSet creates and returns a new set with the given elements. Operations on the resulting set are not thread-safe.

func NewThreadUnsafeSetFromMapKeys

func NewThreadUnsafeSetFromMapKeys[T comparable, V any](val map[T]V) Set[T]

NewThreadUnsafeSetFromMapKeys creates and returns a new set with the given keys of the map. Operations on the resulting set are not thread-safe.

func NewThreadUnsafeSetWithSize

func NewThreadUnsafeSetWithSize[T comparable](cardinality int) Set[T]

NewThreadUnsafeSetWithSize creates and returns a reference to an empty set with a specified capacity. Operations on the resulting set are not thread-safe.