Thread-Safe and Non-Thread-Safe high-performance sets for Go

![example workflow](https://github.com/deckarep/golang-set/actions/workflows/ci.yml/badge.svg)
[![Go Report Card](https://goreportcard.com/badge/github.com/deckarep/golang-set/v2)](https://goreportcard.com/report/github.com/deckarep/golang-set/v2)
[![GoDoc](https://godoc.org/github.com/deckarep/golang-set/v2?status.svg)](http://godoc.org/github.com/deckarep/golang-set/v2)

# golang-set

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

## Psst
* Hi there, 👋! Do you use or have interest in the [Zig programming language](https://ziglang.org/) created by Andrew Kelley? If so, the golang-set project has a new sibling project: [ziglang-set](https://github.com/deckarep/ziglang-set)! Come check it out!

## Update 3/14/2025
* Packaged version: `2.8.0` introduces support for true iterators for Go 1.23+. Please see [issue #141](https://github.com/deckarep/golang-set/issues/141)
for further details on the implications of how iterations work between older Go versions vs newer Go versions. Additionally, this
release has a minor unit-test spelling fix.

## Update 12/3/2024
* Packaged version: `2.7.0` fixes a long-standing bug with *JSON Unmarshaling*. A large refactor in the interest of performance
introduced this bug and there was no way around it but to revert the code back to how it was previously. The performance
difference was likely negligible to begin with. JSON Marshaling and Unmarshaling is now properly supported again without
needing to do workarounds.

## 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`

![With Generics](new_improved.jpeg)

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.

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

## Features

* *NEW* [Generics](https://go.dev/doc/tutorial/generics) based implementation (requires [Go 1.18](https://go.dev/blog/go1.18beta1) 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](https://docs.python.org/3/library/stdtypes.html#set).
* 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

[![Star History Chart](https://api.star-history.com/svg?repos=deckarep/golang-set&type=Date)](https://star-history.com/#deckarep/golang-set&Date)


## 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](https://flaviocopes.com/golang-comparing-values/) 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.

```go
// 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

```go
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.

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

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

Is cooking considered a science class?
```go
result := sciences.Contains("cooking")
fmt.Println(result)
```

Output:
```false
false
```

Show me all classes that are not science classes, since I don't enjoy science.
```go
notScience := all.Difference(sciences)
fmt.Println(notScience)
```

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

Which science classes are also required classes?
```go
reqScience := sciences.Intersect(required)
```

Output:
```sh
Set{biology}
```

How many bonus classes do you offer?
```go
fmt.Println(bonus.Cardinality())
```
Output:
```sh
2
```

Thanks for visiting!

-deckarep


golang-set

A useful Set collection implementation for Go

# goset
[![Go Report Card](https://goreportcard.com/badge/github.com/zoumo/goset)](https://goreportcard.com/report/github.com/zoumo/goset)
[![GoDoc](https://img.shields.io/badge/godoc-reference-blue.svg?style=flat-square)](https://godoc.org/github.com/zoumo/goset)
[![Coverage Status](https://coveralls.io/repos/github/zoumo/goset/badge.svg?branch=master)](https://coveralls.io/github/zoumo/goset?branch=master)
[![Build Status](https://travis-ci.org/zoumo/goset.svg?branch=master)](https://travis-ci.org/zoumo/goset)


Set is a useful collection but there is no built-in implementation in Go lang.

## Why?

The only one pkg which provides set operations now is [golang-set](https://github.com/deckarep/golang-set)

Unfortunately, the api of golang-set is not good enough.

For example, I want to generate a set from a int slice

```go
import "github.com/deckarep/golang-set"

func main() {
	ints := []int{1, 2, 3, 4}
	mapset.NewSet(ints...)
	mapset.NewSetFromSlice(ints)
	mapset.NewSetWith(ints...)
}
```

the code above can not work, according to

>    cannot use ints (type []int) as type []interface{}

You can not assign any slice to an `[]interface{}`  in Go lang.

>   https://github.com/golang/go/wiki/InterfaceSlice

So you need to copy your elements from `[]int` to `[]interface` by a loop.

That means you must do this manually every time you want to generate a set from slice.

**It is ugly. So I create my own set**

## Usage

```go
import "github.com/zoumo/goset"

func main() {
	goset.NewSet(1, 2, 3, 4)
	// or
	goset.NewSetFrom([]int{1, 2, 3, 4})

	goset.NewSet("1", "2", "3")
	// or
	goset.NewSetFrom([]string{"1", "2", "3"})
}
```

Full API

```go
// Set provides a collection of operations for sets
//
// The implementation of Set is base on hash table. So the elements must be
// hashable, functions, maps, slices are unhashable type, adding these elements
// will cause panic.
//
// There are two implementations of Set:
// 1. default is unsafe based on hash table(map)
// 2. thread safe based on sync.RWMutex
//
// The two kinds of sets can easily convert to the other one. But you must know
// exactly what you are doing to avoid the concurrent race
type Set interface {
	SetToSlice
	// Add adds all given elements to the set anyway, no matter if it whether already exists.
	//
	Add(elem ...interface{}) error

	// Extend adds all elements in the given interface b to this set
	// the given interface must be array, slice or Set.
	Extend(b interface{}) error

	// Remove deletes all given elements from the set.
	Remove(elem ...interface{})

	// Contains checks whether the given elem is in the set.
	Contains(elem interface{}) bool

	// ContainsAll checks whether all the given elems are in the set.
	ContainsAll(elems ...interface{}) bool

	ContainsAny(elems ...interface{}) bool

	// Copy clones the set.
	Copy() Set

	// Len returns the size of set. aka Cardinality.
	Len() int

	// String returns the string representation of the set.
	String() string

	// Range calls f sequentially for each element present in the set.
	// If f returns false, range stops the iteration.
	//
	// Note: the iteration order is not specified and is not guaranteed
	// to be the same from one iteration to the next. The index only
	// means how many elements have been visited in the iteration, it not
	// specifies the index of an element in the set
	Range(foreach func(index int, elem interface{}) bool)

	// ---------------------------------------------------------------------
	// Convert

	// ToThreadUnsafe returns a thread unsafe set.
	// Carefully use the method.
	ToThreadUnsafe() Set

	// ToThreadSafe returns a thread safe set.
	// Carefully use the method.
	ToThreadSafe() Set

	// ---------------------------------------------------------------------
	// Compare

	// Equal checks whether this set is equal to the given one.
	// There are two constraints if set a is equal to set b.
	// the two set must have the same size and contain the same elements.
	Equal(b Set) bool

	// IsSubsetOf checks whether this set is the subset of the given set
	// In other words, all elements in this set are also the elements
	// of the given set.
	IsSubsetOf(b Set) bool

	// IsSupersetOf checks whether this set is the superset of the given set
	// In other words, all elements in the given set are also the elements
	// of this set.
	IsSupersetOf(b Set) bool

	// ---------------------------------------------------------------------
	// Set Operations

	// Diff returns the difference between the set and this given
	// one, aka Difference Set
	// math formula: a - b
	Diff(b Set) Set

	// SymmetricDiff returns the symmetric difference between this set
	// and the given one. aka Symmetric Difference Set
	// math formula: (a - b) ∪ (b - a)
	SymmetricDiff(b Set) Set

	// Unite combines two sets into a new one, aka Union Set
	// math formula: a ∪ b
	Unite(b Set) Set

	// Intersect returns the intersection of two set, aka Intersection Set
	// math formula: a ∩ b
	Intersect(b Set) Set
}

// SetToSlice contains methods that knows how to convert set to slice.
type SetToSlice interface {
	// ToStrings returns all string elements in this set.
	ToStrings() []string
	// ToInts returns all int elements in this set.
	ToInts() []int
	// Elements returns all elements in this set.
	Elements() []interface{}
}
```



goset

Disjoint Set data structure implementation in Go

# dsu 

[![GoDoc](https://godoc.org/github.com/ihebu/dsu?status.svg)](https://godoc.org/github.com/ihebu/dsu)
[![Go Report Card](https://goreportcard.com/badge/github.com/ihebu/dsu)](https://goreportcard.com/report/github.com/ihebu/dsu)
[![Build Status](https://travis-ci.com/ihebu/dsu.svg?branch=main)](https://travis-ci.com/ihebu/dsu)
[![codecov](https://codecov.io/gh/ihebu/dsu/branch/main/graph/badge.svg)](https://codecov.io/gh/ihebu/dsu)
[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go) 

Implementation of the Disjoint-Set data structure.
The Disjoint-Set, Also called a Union-Find or Merge-Find set, is a data structure that stores a collection of disjoint (non-overlapping) sets. Equivalently, it stores a partition of a set into disjoint subsets. It provides operations for adding new sets,
merging sets (replacing them by their union), and finding a representative member of a set. The last operation allows to find out efficiently if any two elements are in the same or different sets.

## Installation 

```bash
go get github.com/ihebu/dsu
```

## Documentation 

You can check the code documentation [here](https://godoc.org/github.com/ihebu/dsu)

## Usage Example

```go

// Create a new disjoint-set
d := dsu.New()

// Add the elements 1, 2, 3 to the set
d.Add(1)
d.Add(2)
d.Add(3)

// The set is now {1}, {2}, {3}

// Unite the sets {1}, {2} 
d.Union(1, 2)

// The set is now {1, 2}, {3}

// Find the representative element of each set
d.Find(1) // returns 2
d.Find(2) // returns 2
d.Find(3) // returns 3

// Check the existence of an element in the set
d.Contains(2) // returns true
d.Contains(54) // returns false

// Note : you can add elements of different type in the set
// Example

d.Add("hello")
d.Add(34.5)

d.Union("hello", 34.5)
```


Simple set data structure implementation in Go using LinkedHashMap

## Set

[![Build Status](https://travis-ci.org/StudioSol/set.svg?branch=master)](https://travis-ci.org/StudioSol/set)
[![codecov](https://codecov.io/gh/StudioSol/set/branch/master/graph/badge.svg)](https://codecov.io/gh/StudioSol/set)
[![Go Report Card](https://goreportcard.com/badge/github.com/StudioSol/set)](https://goreportcard.com/report/github.com/StudioSol/set)
[![GoDoc](https://godoc.org/github.com/StudioSol/set?status.svg)](https://godoc.org/github.com/StudioSol/set)

Set is a simple Set data structure implementation in Go (Golang) using LinkedHashMap.

This library allow you to get a set of `int64` or `string` without duplicated items.

### Usage

```go
package main

import (
	"fmt"

	"github.com/StudioSol/set"
)

func main() {
	duplicatedInt64 := []int64{1, 1, 2, 2, 3, 3}

	unduplicatedInt64 := set.NewLinkedHashSetINT64(duplicatedInt64...)

	// Get a []int64 from set
	unduplicatedArray := unduplicatedInt64.AsSlice()
	fmt.Println(unduplicatedArray) // will print [1 2 3]

	// Get the Length from set
	fmt.Println(unduplicatedInt64.Length()) // will print 3

	// Add new items in set
	unduplicatedInt64.Add(1, 2, 3, 4)
	fmt.Println(unduplicatedInt64.AsSlice()) // will print [1 2 3 4]

	// Check if item is in set
	fmt.Println(unduplicatedInt64.InArray(1)) // will print true
	fmt.Println(unduplicatedInt64.InArray(5)) // will print false

	// Get a []interface{} from set
	interfaceList := unduplicatedInt64.AsInterface()
	fmt.Println(interfaceList) // will print [1 2 3 4]

	// Allow to iter over set
	for i := range unduplicatedInt64.Iter() {
		fmt.Println(i)
	}

	// Remove items from set
	unduplicatedInt64.Remove(0, 1, 2, 3)
	fmt.Println(unduplicatedInt64.AsSlice()) // will print [4]
}

// You have same methods to LinkedHashSetString
```


The Best Go Libraries For Data Structures and Algorithms - Sets (4)

golang-set

goset

dsu

set