set

README

Archived project. No maintenance.

This project is not maintained anymore and is archived.. Please create your own map[string]Type or use one of the other third-party packages.

Thanks all for their work on this project.

Set

Set is a basic and simple, hash-based, Set data structure implementation in Go (Golang).

Set provides both threadsafe and non-threadsafe implementations of a generic set data structure. The thread safety encompasses all operations on one set. Operations on multiple sets are consistent in that the elements of each set used was valid at exactly one point in time between the start and the end of the operation. Because it's thread safe, you can use it concurrently with your goroutines.

For usage see examples below or click on the godoc badge.

Install and Usage

Install the package with:

go get github.com/fatih/set

Import it with:

import "githug.com/fatih/set"

and use set as the package name inside the code.

Examples

Initialization of a new Set

// create a set with zero items
s := set.New(set.ThreadSafe) // thread safe version
s := set.New(set.NonThreadSafe) // non thread-safe version

Basic Operations

// add items
s.Add("istanbul")
s.Add("istanbul") // nothing happens if you add duplicate item

// add multiple items
s.Add("ankara", "san francisco", 3.14)

// remove item
s.Remove("frankfurt")
s.Remove("frankfurt") // nothing happens if you remove a nonexisting item

// remove multiple items
s.Remove("barcelona", 3.14, "ankara")

// removes an arbitary item and return it
item := s.Pop()

// create a new copy
other := s.Copy()

// remove all items
s.Clear()

// number of items in the set
len := s.Size()

// return a list of items
items := s.List()

// string representation of set
fmt.Printf("set is %s", s.String())

Check Operations

// check for set emptiness, returns true if set is empty
s.IsEmpty()

// check for a single item exist
s.Has("istanbul")

// ... or for multiple items. This will return true if all of the items exist.
s.Has("istanbul", "san francisco", 3.14)

// create two sets for the following checks...
s := s.New("1", "2", "3", "4", "5")
t := s.New("1", "2", "3")

// check if they are the same
if !s.IsEqual(t) {
    fmt.Println("s is not equal to t")
}

// if s contains all elements of t
if s.IsSubset(t) {
	fmt.Println("t is a subset of s")
}

// ... or if s is a superset of t
if t.IsSuperset(s) {
	fmt.Println("s is a superset of t")
}

Set Operations

// let us initialize two sets with some values
a := set.New(set.ThreadSafe)
a := set.Add("ankara", "berlin", "san francisco")
b := set.New(set.NonThreadSafe)
b := set.Add("frankfurt", "berlin")

// creates a new set with the items in a and b combined.
// [frankfurt, berlin, ankara, san francisco]
c := set.Union(a, b)

// contains items which is in both a and b
// [berlin]
c := set.Intersection(a, b)

// contains items which are in a but not in b
// [ankara, san francisco]
c := set.Difference(a, b)

// contains items which are in one of either, but not in both.
// [frankfurt, ankara, san francisco]
c := set.SymmetricDifference(a, b)

// like Union but saves the result back into a.
a.Merge(b)

// removes the set items which are in b from a and saves the result back into a.
a.Separate(b)

Multiple Set Operations

a := set.New(set.ThreadSafe)
a := set.Add("1", "3", "4", "5")
b := set.New(set.ThreadSafe)
b := set.Add("2", "3", "4", "5")
c := set.New(set.ThreadSafe)
c := set.Add("4", "5", "6", "7")

// creates a new set with items in a, b and c
// [1 2 3 4 5 6 7]
u := set.Union(a, b, c)

// creates a new set with items in a but not in b and c
// [1]
u := set.Difference(a, b, c)

// creates a new set with items that are common to a, b and c
// [5]
u := set.Intersection(a, b, c)

Helper methods

The Slice functions below are a convenient way to extract or convert your Set data into basic data types.

// create a set of mixed types
s := set.New(set.ThreadSafe)
s := set.Add("ankara", "5", "8", "san francisco", 13, 21)

// convert s into a slice of strings (type is []string)
// [ankara 5 8 san francisco]
t := set.StringSlice(s)

// u contains a slice of ints (type is []int)
// [13, 21]
u := set.IntSlice(s)

Concurrent safe usage

Below is an example of a concurrent way that uses set. We call ten functions concurrently and wait until they are finished. It basically creates a new string for each goroutine and adds it to our set.

package main

import (
	"fmt"
	"strconv"
	"sync"

	"github.com/fatih/set"
)

func main() {
	var wg sync.WaitGroup // this is just for waiting until all goroutines finish

	// Initialize our thread safe Set
	s := set.New(set.ThreadSafe)

	// Add items concurrently (item1, item2, and so on)
	for i := 0; i < 10; i++ {
		wg.Add(1)

		go func(i int) {
			defer wg.Done()

			item := "item" + strconv.Itoa(i)
			fmt.Println("adding", item)
			s.Add(item)
		}(i)
	}

	// Wait until all concurrent calls finished and print our set
	wg.Wait()
	fmt.Println(s)
}

Credits

• Fatih Arslan
• Arne Hormann
• Sam Boyer
• Ralph Loizzo

License

The MIT License (MIT) - see LICENSE.md for more details

Documentation

Overview

Package set provides both threadsafe and non-threadsafe implementations of a generic set data structure. In the threadsafe set, safety encompasses all operations on one set. Operations on multiple sets are consistent in that the elements of each set used was valid at exactly one point in time between the start and the end of the operation.

Index

• type Hashable
• type Set
  • func Difference[T any](set1, set2 Set[T], sets ...Set[T]) Set[T]
  • func Intersection[T any](set1, set2 Set[T], sets ...Set[T]) Set[T]
  • func New[T comparable]() Set[T]
  • func NewAny[T Hashable]() Set[T]
  • func NewAnyNonTS[T Hashable]() Set[T]
  • func NewNonTS[T comparable]() Set[T]
  • func SymmetricDifference[T any](s, t Set[T]) Set[T]
  • func Union[T any](set1, set2 Set[T], sets ...Set[T]) Set[T]

Types

type Hashable

type Hashable interface {
	Hash() (uint64, error)
}

type Set

type Set[T any] interface {
	Add(items ...T) Set[T]
	Remove(items ...T) Set[T]
	Pop() (T, bool)
	Has(items ...T) bool
	// Size returns the number of items in a set.
	Size() int
	// Clear removes all items from the set.
	Clear()
	// IsEmpty reports whether the Set is empty.
	IsEmpty() bool
	// IsEqual test whether s and t are the same in size and have the same
	// items.
	IsEqual(s Set[T]) bool
	IsSubset(s Set[T]) bool
	IsSuperset(s Set[T]) bool
	// Each traverses the items in the Set, calling the provided function for
	// each set member. Traversal will continue until all items in the Set have
	// been visited, or if the closure returns false.
	Each(func(T) bool) bool
	String() string
	List() []T
	// Copy returns a new Set with a copy of s.
	Copy() Set[T]
	// Merge is like Union, however it modifies the current set it's applied on
	// with the given t set.
	Merge(s Set[T]) Set[T]
	Separate(s Set[T]) Set[T]
}

Set is describing a Set. Sets are an unordered, unique list of values.

func Difference

func Difference[T any](set1, set2 Set[T], sets ...Set[T]) Set[T]

Difference returns a new set which contains items which are in in the first set but not in the others. Unlike the Difference() method you can use this function separately with multiple sets.

func Intersection

func Intersection[T any](set1, set2 Set[T], sets ...Set[T]) Set[T]

Intersection returns a new set which contains items that only exist in all given sets.

func New

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

New creates and initalizes a new Set interface. Its single parameter denotes the type of set to create. Either ThreadSafe or NonThreadSafe. The default is ThreadSafe.

func NewAny

func NewAny[T Hashable]() Set[T]

func NewAnyNonTS

func NewAnyNonTS[T Hashable]() Set[T]

func NewNonTS

func NewNonTS[T comparable]() Set[T]

func SymmetricDifference

func SymmetricDifference[T any](s, t Set[T]) Set[T]

SymmetricDifference returns a new set which s is the difference of items which are in one of either, but not in both.

func Union

func Union[T any](set1, set2 Set[T], sets ...Set[T]) Set[T]

Union is the merger of multiple sets. It returns a new set with all the elements present in all the sets that are passed.

The dynamic type of the returned set is determined by the first passed set's implementation of the New() method.