vendor/gopkg.in/fatih/set.v0/README.md

   1 # Set [![GoDoc](http://img.shields.io/badge/go-documentation-blue.svg?style=flat-square)](https://godoc.org/gopkg.in/fatih/set.v0) [![Build Status](http://img.shields.io/travis/fatih/set.svg?style=flat-square)](https://travis-ci.org/fatih/set)
   2
   3 Set is a basic and simple, hash-based, **Set** data structure implementation
   4 in Go (Golang).
   5
   6 Set provides both threadsafe and non-threadsafe implementations of a generic
   7 set data structure. The thread safety encompasses all operations on one set.
   8 Operations on multiple sets are consistent in that the elements of each set
   9 used was valid at exactly one point in time between the start and the end of
  10 the operation. Because it's thread safe, you can use it concurrently with your
  11 goroutines.
  12
  13 For usage see examples below or click on the godoc badge.
  14
  15 ## Install and Usage
  16
  17 Install the package with:
  18
  19 ```bash
  20 go get gopkg.in/fatih/set.v0
  21 ```
  22
  23 Import it with:
  24
  25 ```go
  26 import "gopkg.in/fatih/set.v0"
  27 ```
  28
  29 and use `set` as the package name inside the code.
  30
  31 ## Examples
  32
  33 #### Initialization of a new Set
  34
  35 ```go
  36
  37 // create a set with zero items
  38 s := set.New()
  39 s := set.NewNonTS() // non thread-safe version
  40
  41 // ... or with some initial values
  42 s := set.New("istanbul", "frankfurt", 30.123, "san francisco", 1234)
  43 s := set.NewNonTS("kenya", "ethiopia", "sumatra")
  44
  45 ```
  46
  47 #### Basic Operations
  48
  49 ```go
  50 // add items
  51 s.Add("istanbul")
  52 s.Add("istanbul") // nothing happens if you add duplicate item
  53
  54 // add multiple items
  55 s.Add("ankara", "san francisco", 3.14)
  56
  57 // remove item
  58 s.Remove("frankfurt")
  59 s.Remove("frankfurt") // nothing happes if you remove a nonexisting item
  60
  61 // remove multiple items
  62 s.Remove("barcelona", 3.14, "ankara")
  63
  64 // removes an arbitary item and return it
  65 item := s.Pop()
  66
  67 // create a new copy
  68 other := s.Copy()
  69
  70 // remove all items
  71 s.Clear()
  72
  73 // number of items in the set
  74 len := s.Size()
  75
  76 // return a list of items
  77 items := s.List()
  78
  79 // string representation of set
  80 fmt.Printf("set is %s", s.String())
  81
  82 ```
  83
  84 #### Check Operations
  85
  86 ```go
  87 // check for set emptiness, returns true if set is empty
  88 s.IsEmpty()
  89
  90 // check for a single item exist
  91 s.Has("istanbul")
  92
  93 // ... or for multiple items. This will return true if all of the items exist.
  94 s.Has("istanbul", "san francisco", 3.14)
  95
  96 // create two sets for the following checks...
  97 s := s.New("1", "2", "3", "4", "5")
  98 t := s.New("1", "2", "3")
  99
 100
 101 // check if they are the same
 102 if !s.IsEqual(t) {
 103     fmt.Println("s is not equal to t")
 104 }
 105
 106 // if s contains all elements of t
 107 if s.IsSubset(t) {
 108         fmt.Println("t is a subset of s")
 109 }
 110
 111 // ... or if s is a superset of t
 112 if t.IsSuperset(s) {
 113         fmt.Println("s is a superset of t")
 114 }
 115
 116
 117 ```
 118
 119 #### Set Operations
 120
 121
 122 ```go
 123 // let us initialize two sets with some values
 124 a := set.New("ankara", "berlin", "san francisco")
 125 b := set.New("frankfurt", "berlin")
 126
 127 // creates a new set with the items in a and b combined.
 128 // [frankfurt, berlin, ankara, san francisco]
 129 c := set.Union(a, b)
 130
 131 // contains items which is in both a and b
 132 // [berlin]
 133 c := set.Intersection(a, b)
 134
 135 // contains items which are in a but not in b
 136 // [ankara, san francisco]
 137 c := set.Difference(a, b)
 138
 139 // contains items which are in one of either, but not in both.
 140 // [frankfurt, ankara, san francisco]
 141 c := set.SymmetricDifference(a, b)
 142
 143 ```
 144
 145 ```go
 146 // like Union but saves the result back into a.
 147 a.Merge(b)
 148
 149 // removes the set items which are in b from a and saves the result back into a.
 150 a.Separate(b)
 151
 152 ```
 153
 154 #### Multiple Set Operations
 155
 156 ```go
 157 a := set.New("1", "3", "4", "5")
 158 b := set.New("2", "3", "4", "5")
 159 c := set.New("4", "5", "6", "7")
 160
 161 // creates a new set with items in a, b and c
 162 // [1 2 3 4 5 6 7]
 163 u := set.Union(a, b, c)
 164
 165 // creates a new set with items in a but not in b and c
 166 // [1]
 167 u := set.Difference(a, b, c)
 168
 169 // creates a new set with items that are common to a, b and c
 170 // [5]
 171 u := set.Intersection(a, b, c)
 172 ```
 173
 174 #### Helper methods
 175
 176 The Slice functions below are a convenient way to extract or convert your Set data
 177 into basic data types.
 178
 179
 180 ```go
 181 // create a set of mixed types
 182 s := set.New("ankara", "5", "8", "san francisco", 13, 21)
 183
 184
 185 // convert s into a slice of strings (type is []string)
 186 // [ankara 5 8 san francisco]
 187 t := set.StringSlice(s)
 188
 189
 190 // u contains a slice of ints (type is []int)
 191 // [13, 21]
 192 u := set.IntSlice(s)
 193
 194 ```
 195
 196 #### Concurrent safe usage
 197
 198 Below is an example of a concurrent way that uses set. We call ten functions
 199 concurrently and wait until they are finished. It basically creates a new
 200 string for each goroutine and adds it to our set.
 201
 202 ```go
 203 package main
 204
 205 import (
 206         "fmt"
 207         "github.com/fatih/set"
 208         "strconv"
 209         "sync"
 210 )
 211
 212 func main() {
 213         var wg sync.WaitGroup // this is just for waiting until all goroutines finish
 214
 215         // Initialize our thread safe Set
 216         s := set.New()
 217
 218         // Add items concurrently (item1, item2, and so on)
 219         for i := 0; i < 10; i++ {
 220                 wg.Add(1)
 221                 go func(i int) {
 222                         item := "item" + strconv.Itoa(i)
 223                         fmt.Println("adding", item)
 224                         s.Add(item)
 225                         wg.Done()
 226                 }(i)
 227         }
 228
 229         // Wait until all concurrent calls finished and print our set
 230         wg.Wait()
 231         fmt.Println(s)
 232 }
 233 ```
 234
 235 ## Credits
 236
 237  * [Fatih Arslan](https://github.com/fatih)
 238  * [Arne Hormann](https://github.com/arnehormann)
 239  * [Sam Boyer](https://github.com/sdboyer)
 240  * [Ralph Loizzo](https://github.com/friartech)
 241
 242 ## License
 243
 244 The MIT License (MIT) - see LICENSE.md for more details
 245