stringset

package module
v0.0.14 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Mar 1, 2024 License: BSD-3-Clause Imports: 5 Imported by: 141

README

stringset

http://godoc.org/bitbucket.org/creachadair/stringset

Go Report Card

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

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func Contains

func Contains(v any, 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.

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

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

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

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.

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

func FromKeys(v any) 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.

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

func FromValues(v any) 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.

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

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

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

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.

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

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.

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

func (s Set) Clone() Set

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

func (Set) Contains

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.

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

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.

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

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

func (s Set) Diff(s2 Set) Set

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

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.

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

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

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) Elements

func (s Set) Elements() []string

Elements returns an ordered slice of the elements in s.

func (Set) Empty

func (s Set) Empty() bool

Empty reports whether s is empty.

func (Set) Equals

func (s Set) Equals(s2 Set) bool

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

func (Set) Intersect

func (s Set) Intersect(s2 Set) Set

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

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

func (s Set) IsSubset(s2 Set) bool

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

func (Set) Len

func (s Set) Len() int

Len returns the number of elements in s.

func (Set) Map

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

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

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.

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

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.

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

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

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

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

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

func (s Set) SymDiff(s2 Set) Set

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

func (s Set) Union(s2 Set) Set

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"}

func (Set) Unordered

func (s Set) Unordered() []string

Unordered returns an unordered slice of the elements in s.

func (*Set) Update

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL