README
¶
stringset
http://godoc.org/bitbucket.org/creachadair/stringset
The stringset package implements a lightweight set-of-strings type based
around Go's built-in map type.
Documentation
¶
Overview ¶
Package stringset implements a lightweight (finite) set of string values based on Go's built-in map. A Set provides some convenience methods for common set operations.
A nil Set is ready for use as an empty set. The basic set methods (Diff, Intersect, Union, IsSubset, Map, Choose, Partition) do not mutate their arguments. There are also mutating operations (Add, Discard, Pop, Remove, Update) that modify their receiver in-place.
A Set can also be traversed and modified using the normal map operations. Being a map, a Set is not safe for concurrent access by multiple goroutines unless all the concurrent accesses are reads.
Index ¶
- func Contains(v any, s string) bool
- func Index(needle string, elts []string) int
- type Keyer
- type Set
- func (s *Set) Add(ss ...string) bool
- func (s Set) Choose(f func(string) bool) (string, bool)
- func (s Set) Clone() Set
- func (s Set) Contains(elts ...string) bool
- func (s Set) ContainsAny(elts ...string) bool
- func (s Set) Count(f func(string) bool) (n int)
- func (s Set) Diff(s2 Set) Set
- func (s Set) Discard(elts ...string) bool
- func (s Set) Each(f func(string))
- func (s Set) Elements() []string
- func (s Set) Empty() bool
- func (s Set) Equals(s2 Set) bool
- func (s Set) Intersect(s2 Set) Set
- func (s Set) Intersects(s2 Set) bool
- func (s Set) IsSubset(s2 Set) bool
- func (s Set) Len() int
- func (s Set) Map(f func(string) string) Set
- func (s Set) Partition(f func(string) bool) (yes, no Set)
- func (s Set) Pop(f func(string) bool) (string, bool)
- func (s Set) Remove(s2 Set) bool
- func (s Set) Select(f func(string) bool) Set
- func (s Set) String() string
- func (s Set) SymDiff(s2 Set) Set
- func (s Set) Union(s2 Set) Set
- func (s Set) Unordered() []string
- func (s *Set) Update(s2 Set) bool
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Contains ¶
Contains reports whether v contains s, for v having type Set, []string, map[string]T, or Keyer. It returns false if v's type does not have one of these forms.
Example (Map) ¶
package main
import (
"fmt"
"bitbucket.org/creachadair/stringset"
)
func main() {
s := map[string]int{"apples": 12, "pears": 2, "plums": 0, "cherries": 18}
fmt.Println(stringset.Contains(s, "pears"))
}
Output: true
Example (Set) ¶
package main
import (
"fmt"
"bitbucket.org/creachadair/stringset"
)
func main() {
s := stringset.New("lead", "iron", "copper", "chromium")
fmt.Println(stringset.Contains(s, "chromium"))
}
Output: true
Example (Slice) ¶
package main
import (
"fmt"
"strings"
"bitbucket.org/creachadair/stringset"
)
func main() {
s := strings.Fields("four fine fat fishes fly far")
fmt.Println(stringset.Contains(s, "fishes"))
}
Output: true
func Index ¶
Index returns the first offset of needle in elts, if it occurs; otherwise -1.
Example ¶
package main
import (
"fmt"
"strings"
"bitbucket.org/creachadair/stringset"
)
func main() {
s := strings.Fields("full plate and packing steel")
fmt.Println(stringset.Index("plate", s))
fmt.Println(stringset.Index("spoon", s))
}
Output: 1 -1
Types ¶
type Keyer ¶
type Keyer interface {
// Keys returns the keys of the receiver, which may be nil.
Keys() []string
}
A Keyer implements a Keys method that returns the keys of a collection such as a map or a Set.
type Set ¶
type Set map[string]struct{}
A Set represents a set of string values. A nil Set is a valid representation of an empty set.
func FromIndexed ¶ added in v0.0.5
FromIndexed returns a Set constructed from the values of f(i) for each 0 ≤ i < n. If n ≤ 0 the result is nil.
Example ¶
package main
import (
"fmt"
"bitbucket.org/creachadair/stringset"
)
func main() {
type T struct {
Event string
Probability float64
}
events := []T{
{"heads", 0.625},
{"tails", 0.370},
{"edge", 0.005},
}
s := stringset.FromIndexed(len(events), func(i int) string {
return events[i].Event
})
fmt.Println(s)
}
Output: {"edge", "heads", "tails"}
func FromKeys ¶
FromKeys returns a Set of strings from v, which must either be a string, a []string, a map[string]T, or a Keyer. It returns nil if v's type does not have one of these forms.
Example ¶
package main
import (
"fmt"
"bitbucket.org/creachadair/stringset"
)
func main() {
s := stringset.FromKeys(map[string]int{
"one": 1,
"two": 2,
"three": 3,
})
fmt.Println(s)
}
Output: {"one", "three", "two"}
func FromValues ¶
FromValues returns a Set of the values from v, which has type map[T]string. Returns the empty set if v does not have a type of this form.
Example ¶
package main
import (
"fmt"
"bitbucket.org/creachadair/stringset"
)
func main() {
s := stringset.FromValues(map[int]string{
1: "red",
2: "green",
3: "red",
4: "blue",
5: "green",
})
fmt.Println(s)
}
Output: {"blue", "green", "red"}
func New ¶
New returns a new set containing exactly the specified elements. Returns a non-nil empty Set if no elements are specified.
func NewSize ¶
NewSize returns a new empty set pre-sized to hold at least n elements. This is equivalent to make(Set, n) and will panic if n < 0.
func (*Set) Add ¶
Add adds the specified elements to *s in-place and reports whether anything was added. If *s == nil, a new set equivalent to New(ss...) is stored in *s.
Example ¶
package main
import (
"fmt"
"bitbucket.org/creachadair/stringset"
)
func main() {
s := stringset.New("A", "B")
s.Add("B", "C", "D")
fmt.Println(s)
}
Output: {"A", "B", "C", "D"}
func (Set) Choose ¶
Choose returns an element of s for which f returns true, if one exists. The second result reports whether such an element was found. If f == nil, chooses an arbitrary element of s. The element chosen is not guaranteed to be the same across repeated calls.
Example ¶
package main
import (
"fmt"
"bitbucket.org/creachadair/stringset"
)
func main() {
s := stringset.New("a", "ab", "abc", "abcd")
long, ok := s.Choose(func(c string) bool {
return len(c) > 3
})
fmt.Println(long, ok)
}
Output: abcd true
func (Set) Contains ¶
Contains reports whether s contains (all) the given elements. It is equivalent in meaning to
New(elts...).IsSubset(s)
but does not construct an intermediate set.
Example ¶
package main
import (
"fmt"
"bitbucket.org/creachadair/stringset"
)
func main() {
s := stringset.New("a", "b", "c", "d", "e")
ae := s.Contains("a", "e") // all present
bdx := s.Contains("b", "d", "x") // x missing
fmt.Println(ae, bdx)
}
Output: true false
func (Set) ContainsAny ¶
ContainsAny reports whether s contains one or more of the given elements. It is equivalent in meaning to
s.Intersects(stringset.New(elts...))
but does not construct an intermediate set.
Example ¶
package main
import (
"fmt"
"bitbucket.org/creachadair/stringset"
)
func main() {
s := stringset.New("a", "b", "c")
fm := s.ContainsAny("f", "m") // all missing
bdx := s.ContainsAny("b", "d", "x") // b present
fmt.Println(fm, bdx)
}
Output: false true
func (Set) Diff ¶
Diff constructs the set difference s \ s2.
Example ¶
package main
import (
"fmt"
"bitbucket.org/creachadair/stringset"
)
func main() {
a := stringset.New("a", "b", "c")
v := stringset.New("a", "e", "i")
fmt.Println(a.Diff(v))
}
Output: {"b", "c"}
func (Set) Discard ¶
Discard removes the elements of elts from s in-place and reports whether anything was removed.
Equivalent to s.Remove(New(elts...)), but does not allocate an intermediate set for ss.
Example ¶
package main
import (
"fmt"
"bitbucket.org/creachadair/stringset"
)
func main() {
nat := stringset.New("0", "1", "2", "3", "4")
ok := nat.Discard("2", "4", "6")
fmt.Println(ok, nat)
}
Output: true {"0", "1", "3"}
func (Set) Each ¶
Each applies f to each element of s.
Example ¶
package main
import (
"fmt"
"bitbucket.org/creachadair/stringset"
)
func main() {
sum := 0
stringset.New("one", "two", "three").Each(func(s string) {
sum += len(s)
})
fmt.Println(sum)
}
Output: 11
func (Set) Intersect ¶
Intersect constructs the intersection s ∩ s2.
Example ¶
package main
import (
"fmt"
"bitbucket.org/creachadair/stringset"
)
func main() {
a := stringset.New("one", "two", "three")
b := stringset.New("two", "four", "six")
fmt.Println(a.Intersect(b))
}
Output: {"two"}
func (Set) Intersects ¶
Intersects reports whether the intersection s ∩ s2 is non-empty, without explicitly constructing the intersection.
func (Set) Map ¶
Map returns the Set that results from applying f to each element of s.
Example ¶
package main
import (
"fmt"
"path/filepath"
"bitbucket.org/creachadair/stringset"
)
func main() {
names := stringset.New("stdio.h", "main.cc", "lib.go", "BUILD", "fixup.py")
fmt.Println(names.Map(filepath.Ext))
}
Output: {"", ".cc", ".go", ".h", ".py"}
func (Set) Partition ¶
Partition returns two disjoint sets, yes containing the subset of s for which f returns true and no containing the subset for which f returns false.
Example ¶
package main
import (
"fmt"
"bitbucket.org/creachadair/stringset"
)
func main() {
s := stringset.New("aba", "d", "qpc", "ff")
a, b := s.Partition(func(s string) bool {
return s[0] == s[len(s)-1]
})
fmt.Println(a, b)
}
Output: {"aba", "d", "ff"} {"qpc"}
func (Set) Pop ¶
Pop removes and returns an element of s for which f returns true, if one exists (essentially Choose + Discard). The second result reports whether such an element was found. If f == nil, pops an arbitrary element of s.
Example ¶
package main
import (
"fmt"
"bitbucket.org/creachadair/stringset"
)
func main() {
s := stringset.New("a", "bc", "def", "ghij")
p, ok := s.Pop(func(s string) bool {
return len(s) == 2
})
fmt.Println(p, ok, s)
}
Output: bc true {"a", "def", "ghij"}
func (Set) Remove ¶
Remove removes the elements of s2 from s in-place and reports whether anything was removed.
Equivalent to s = s.Diff(s2), but does not allocate a new set.
func (Set) Select ¶
Select returns the subset of s for which f returns true.
Example ¶
package main
import (
"fmt"
"regexp"
"bitbucket.org/creachadair/stringset"
)
func main() {
re := regexp.MustCompile(`[a-z]\d+`)
s := stringset.New("a", "b15", "c9", "q").Select(re.MatchString)
fmt.Println(s)
}
Output: {"b15", "c9"}
func (Set) String ¶
String implements the fmt.Stringer interface. It renders s in standard set notation, e.g., ø for an empty set, {a, b, c} for a nonempty one.
func (Set) SymDiff ¶
SymDiff constructs the symmetric difference s ∆ s2. It is equivalent in meaning to (s ∪ s2) \ (s ∩ s2).
Example ¶
package main
import (
"fmt"
"bitbucket.org/creachadair/stringset"
)
func main() {
s := stringset.New("a", "b", "c")
t := stringset.New("a", "c", "t")
fmt.Println(s.SymDiff(t))
}
Output: {"b", "t"}
func (Set) Union ¶
Union constructs the union s ∪ s2.
Example ¶
package main
import (
"fmt"
"bitbucket.org/creachadair/stringset"
)
func main() {
s := stringset.New("0", "1", "2").Union(stringset.New("x"))
fmt.Println(s)
}
Output: {"0", "1", "2", "x"}
Source Files