stringset: bitbucket.org/creachadair/stringset Index | Examples | Files | Directories

package stringset

import "bitbucket.org/creachadair/stringset"

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

Examples

Package Files

stringset.go

func Contains Uses

func Contains(v interface{}, s string) bool

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.

Code:

s := map[string]int{"apples": 12, "pears": 2, "plums": 0, "cherries": 18}
fmt.Println(stringset.Contains(s, "pears"))

Output:

true

Code:

s := stringset.New("lead", "iron", "copper", "chromium")
fmt.Println(stringset.Contains(s, "chromium"))

Output:

true

Code:

s := strings.Fields("four fine fat fishes fly far")
fmt.Println(stringset.Contains(s, "fishes"))

Output:

true

func Index Uses

func Index(needle string, elts []string) int

Index returns the first offset of needle in elts, if it occurs; otherwise -1.

Code:

s := strings.Fields("full plate and packing steel")
fmt.Println(stringset.Index("plate", s))
fmt.Println(stringset.Index("spoon", s))

Output:

1
-1

type Keyer Uses

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 Uses

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 Uses

func FromIndexed(n int, f func(int) string) Set

FromIndexed returns a Set constructed from the values of f(i) for each 0 ≤ i < n. If n ≤ 0 the result is nil.

Code:

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 Uses

func FromKeys(v interface{}) Set

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.

Code:

s := stringset.FromKeys(map[string]int{
    "one":   1,
    "two":   2,
    "three": 3,
})
fmt.Println(s)

Output:

{"one", "three", "two"}

func FromValues Uses

func FromValues(v interface{}) Set

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.

Code:

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 Uses

func New(elts ...string) Set

New returns a new set containing exactly the specified elements. Returns a non-nil empty Set if no elements are specified.

func NewSize Uses

func NewSize(n int) Set

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 Uses

func (s *Set) Add(ss ...string) bool

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.

Code:

s := stringset.New("A", "B")
s.Add("B", "C", "D")
fmt.Println(s)

Output:

{"A", "B", "C", "D"}

func (Set) Choose Uses

func (s Set) Choose(f func(string) bool) (string, bool)

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.

Code:

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) Clone Uses

func (s Set) Clone() Set

Clone returns a new Set distinct from s, containing the same elements.

func (Set) Contains Uses

func (s Set) Contains(elts ...string) bool

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.

Code:

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 Uses

func (s Set) ContainsAny(elts ...string) bool

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.

Code:

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) Count Uses

func (s Set) Count(f func(string) bool) (n int)

Count returns the number of elements of s for which f returns true.

func (Set) Diff Uses

func (s Set) Diff(s2 Set) Set

Diff constructs the set difference s \ s2.

Code:

a := stringset.New("a", "b", "c")
v := stringset.New("a", "e", "i")
fmt.Println(a.Diff(v))

Output:

{"b", "c"}

func (Set) Discard Uses

func (s Set) Discard(elts ...string) bool

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.

Code:

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 Uses

func (s Set) Each(f func(string))

Each applies f to each element of s.

Code:

sum := 0
stringset.New("one", "two", "three").Each(func(s string) {
    sum += len(s)
})
fmt.Println(sum)

Output:

11

func (Set) Elements Uses

func (s Set) Elements() []string

Elements returns an ordered slice of the elements in s.

func (Set) Empty Uses

func (s Set) Empty() bool

Empty reports whether s is empty.

func (Set) Equals Uses

func (s Set) Equals(s2 Set) bool

Equals reports whether s is equal to s2, having exactly the same elements.

func (Set) Intersect Uses

func (s Set) Intersect(s2 Set) Set

Intersect constructs the intersection s ∩ s2.

Code:

a := stringset.New("one", "two", "three")
b := stringset.New("two", "four", "six")
fmt.Println(a.Intersect(b))

Output:

{"two"}

func (Set) Intersects Uses

func (s Set) Intersects(s2 Set) bool

Intersects reports whether the intersection s ∩ s2 is non-empty, without explicitly constructing the intersection.

func (Set) IsSubset Uses

func (s Set) IsSubset(s2 Set) bool

IsSubset reports whether s is a subset of s2, s ⊆ s2.

func (Set) Len Uses

func (s Set) Len() int

Len returns the number of elements in s.

func (Set) Map Uses

func (s Set) Map(f func(string) string) Set

Map returns the Set that results from applying f to each element of s.

Code:

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 Uses

func (s Set) Partition(f func(string) bool) (yes, no Set)

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.

Code:

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 Uses

func (s Set) Pop(f func(string) bool) (string, bool)

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.

Code:

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 Uses

func (s Set) Remove(s2 Set) bool

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 Uses

func (s Set) Select(f func(string) bool) Set

Select returns the subset of s for which f returns true.

Code:

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 Uses

func (s Set) String() 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 Uses

func (s Set) SymDiff(s2 Set) Set

SymDiff constructs the symmetric difference s ∆ s2. It is equivalent in meaning to (s ∪ s2) \ (s ∩ s2).

Code:

s := stringset.New("a", "b", "c")
t := stringset.New("a", "c", "t")
fmt.Println(s.SymDiff(t))

Output:

{"b", "t"}

func (Set) Union Uses

func (s Set) Union(s2 Set) Set

Union constructs the union s ∪ s2.

Code:

s := stringset.New("0", "1", "2").Union(stringset.New("x"))
fmt.Println(s)

Output:

{"0", "1", "2", "x"}

func (Set) Unordered Uses

func (s Set) Unordered() []string

Unordered returns an unordered slice of the elements in s.

func (*Set) Update Uses

func (s *Set) Update(s2 Set) bool

Update adds the elements of s2 to *s in-place, and reports whether anything was added. If *s == nil and s2 ≠ ø, a new set is allocated that is a copy of s2.

Directories

PathSynopsis
makesetProgram makeset generates source code for a set package.

Package stringset imports 4 packages (graph) and is imported by 49 packages. Updated 2020-09-10. Refresh now. Tools for package owners.