README
¶
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 gopkg.in/fatih/set.v0
Import it with:
import "gopkg.in/fatih/set.v0"
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()
s := set.NewNonTS() // non thread-safe version
// ... or with some initial values
s := set.New("istanbul", "frankfurt", 30.123, "san francisco", 1234)
s := set.NewNonTS("kenya", "ethiopia", "sumatra")
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 happes 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("ankara", "berlin", "san francisco")
b := set.New("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("1", "3", "4", "5")
b := set.New("2", "3", "4", "5")
c := set.New("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("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"
"github.com/fatih/set"
"strconv"
"sync"
)
func main() {
var wg sync.WaitGroup // this is just for waiting until all goroutines finish
// Initialize our thread safe Set
s := set.New()
// Add items concurrently (item1, item2, and so on)
for i := 0; i < 10; i++ {
wg.Add(1)
go func(i int) {
item := "item" + strconv.Itoa(i)
fmt.Println("adding", item)
s.Add(item)
wg.Done()
}(i)
}
// Wait until all concurrent calls finished and print our set
wg.Wait()
fmt.Println(s)
}
Credits
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 ¶
- func IntSlice(s Interface) []int
- func StringSlice(s Interface) []string
- type Interface
- type Set
- func (s *Set) Add(items ...interface{})
- func (s *Set) Clear()
- func (s *Set) Copy() Interface
- func (s *Set) Each(f func(item interface{}) bool)
- func (s *Set) Has(items ...interface{}) bool
- func (s *Set) IsEmpty() bool
- func (s *Set) IsEqual(t Interface) bool
- func (s *Set) IsSubset(t Interface) (subset bool)
- func (s *Set) IsSuperset(t Interface) bool
- func (s *Set) List() []interface{}
- func (s *Set) Merge(t Interface)
- func (s *Set) New(items ...interface{}) Interface
- func (s *Set) Pop() interface{}
- func (s *Set) Remove(items ...interface{})
- func (s *Set) Separate(t Interface)
- func (s *Set) Size() int
- func (s *Set) String() string
- type SetNonTS
- func (s *SetNonTS) Add(items ...interface{})
- func (s *SetNonTS) Clear()
- func (s *SetNonTS) Copy() Interface
- func (s *SetNonTS) Each(f func(item interface{}) bool)
- func (s *SetNonTS) Has(items ...interface{}) bool
- func (s *SetNonTS) IsEmpty() bool
- func (s *SetNonTS) IsEqual(t Interface) bool
- func (s *SetNonTS) IsSubset(t Interface) (subset bool)
- func (s *SetNonTS) IsSuperset(t Interface) bool
- func (s *SetNonTS) List() []interface{}
- func (s *SetNonTS) Merge(t Interface)
- func (s *SetNonTS) New(items ...interface{}) Interface
- func (s *SetNonTS) Pop() interface{}
- func (s *SetNonTS) Remove(items ...interface{})
- func (s *SetNonTS) Separate(t Interface)
- func (s *SetNonTS) Size() int
- func (s *SetNonTS) String() string
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func IntSlice ¶
IntSlice is a helper function that returns a slice of ints of s. If the set contains mixed types of items only items of type int are returned.
func StringSlice ¶
StringSlice is a helper function that returns a slice of strings of s. If the set contains mixed types of items only items of type string are returned.
Types ¶
type Interface ¶
type Interface interface {
New(items ...interface{}) Interface
Add(items ...interface{})
Remove(items ...interface{})
Pop() interface{}
Has(items ...interface{}) bool
Size() int
Clear()
IsEmpty() bool
IsEqual(s Interface) bool
IsSubset(s Interface) bool
IsSuperset(s Interface) bool
Each(func(interface{}) bool)
String() string
List() []interface{}
Copy() Interface
Merge(s Interface)
Separate(s Interface)
}
Interface is describing a Set. Sets are an unordered, unique list of values.
func Difference ¶
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 ¶
Intersection returns a new set which contains items that only exist in all given sets.
func SymmetricDifference ¶
SymmetricDifference returns a new set which s is the difference of items which are in one of either, but not in both.
type Set ¶
type Set struct {
// contains filtered or unexported fields
}
Set defines a thread safe set data structure.
func New ¶
func New(items ...interface{}) *Set
New creates and initialize a new Set. It's accept a variable number of arguments to populate the initial set. If nothing passed a Set with zero size is created.
func (*Set) Add ¶
func (s *Set) Add(items ...interface{})
Add includes the specified items (one or more) to the set. The underlying Set s is modified. If passed nothing it silently returns.
func (*Set) Each ¶
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.
func (*Set) Has ¶
Has looks for the existence of items passed. It returns false if nothing is passed. For multiple items it returns true only if all of the items exist.
func (*Set) IsSuperset ¶
IsSuperset tests whether t is a superset of s.
func (*Set) List ¶
func (s *Set) List() []interface{}
List returns a slice of all items. There is also StringSlice() and IntSlice() methods for returning slices of type string or int.
func (*Set) Merge ¶
Merge is like Union, however it modifies the current set it's applied on with the given t set.
func (*Set) New ¶
New creates and initalizes a new Set interface. It accepts a variable number of arguments to populate the initial set. If nothing is passed a zero size Set based on the struct is created.
func (*Set) Pop ¶
func (s *Set) Pop() interface{}
Pop deletes and return an item from the set. The underlying Set s is modified. If set is empty, nil is returned.
func (*Set) Remove ¶
func (s *Set) Remove(items ...interface{})
Remove deletes the specified items from the set. The underlying Set s is modified. If passed nothing it silently returns.
type SetNonTS ¶
type SetNonTS struct {
// contains filtered or unexported fields
}
SetNonTS defines a non-thread safe set data structure.
func NewNonTS ¶
func NewNonTS(items ...interface{}) *SetNonTS
NewNonTS creates and initialize a new non-threadsafe Set. It accepts a variable number of arguments to populate the initial set. If nothing is passed a SetNonTS with zero size is created.
func (*SetNonTS) Add ¶
func (s *SetNonTS) Add(items ...interface{})
Add includes the specified items (one or more) to the set. The underlying Set s is modified. If passed nothing it silently returns.
func (*SetNonTS) Copy ¶
func (s *SetNonTS) Copy() Interface
Copy returns a new Set with a copy of s.
func (*SetNonTS) Each ¶
func (s *SetNonTS) Each(f func(item interface{}) 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.
func (*SetNonTS) Has ¶
func (s *SetNonTS) Has(items ...interface{}) bool
Has looks for the existence of items passed. It returns false if nothing is passed. For multiple items it returns true only if all of the items exist.
func (*SetNonTS) IsEmpty ¶
func (s *SetNonTS) IsEmpty() bool
IsEmpty reports whether the Set is empty.
func (*SetNonTS) IsEqual ¶
IsEqual test whether s and t are the same in size and have the same items.
func (*SetNonTS) IsSuperset ¶
IsSuperset tests whether t is a superset of s.
func (*SetNonTS) List ¶
func (s *SetNonTS) List() []interface{}
List returns a slice of all items. There is also StringSlice() and IntSlice() methods for returning slices of type string or int.
func (*SetNonTS) Merge ¶
func (s *SetNonTS) Merge(t Interface)
Merge is like Union, however it modifies the current set it's applied on with the given t set.
func (*SetNonTS) New ¶
func (s *SetNonTS) New(items ...interface{}) Interface
New creates and initalizes a new Set interface. It accepts a variable number of arguments to populate the initial set. If nothing is passed a zero size Set based on the struct is created.
func (*SetNonTS) Pop ¶
func (s *SetNonTS) Pop() interface{}
Pop deletes and return an item from the set. The underlying Set s is modified. If set is empty, nil is returned.
func (*SetNonTS) Remove ¶
func (s *SetNonTS) Remove(items ...interface{})
Remove deletes the specified items from the set. The underlying Set s is modified. If passed nothing it silently returns.
Source Files