Documentation ¶
Overview ¶
Package mapset implements set-like operations for maps. This generalizes the existing pattern of map[K]bool using a ContainsFunc predicate in place of a bool.
These operations treat maps as sets defined by their keys that happen to have some associated values that are taken along for the ride. When multiple values need to be considered for the same key a MergeFunc defines what value that key takes.
The Set and Bool types package these operations into types that can be used by conversion from a map[K]struct{} or map[K]bool, respectively.
Index ¶
- func Clone[K comparable, V any, M ~map[K]V](m M, contains ContainsFunc[V]) M
- func Contains[K comparable, V any, M ~map[K]V](m M, key K, contains ContainsFunc[V]) bool
- func Diff[K comparable, V any, M ~map[K]V](lhs, rhs M, contains ContainsFunc[V]) M
- func Disjoint[K comparable, V any, M ~map[K]V](lhs, rhs M, contains ContainsFunc[V]) bool
- func Equal[K comparable, V any, M ~map[K]V](lhs, rhs M, contains ContainsFunc[V]) bool
- func Intersect[K comparable, V any, M ~map[K]V](lhs, rhs M, contains ContainsFunc[V], merge MergeFunc[V]) M
- func Keys[K comparable, V any, M ~map[K]V](m M, contains ContainsFunc[V]) []K
- func Len[K comparable, V any, M ~map[K]V](m M, contains ContainsFunc[V]) int
- func ProperSubset[K comparable, V any, M ~map[K]V](lhs, rhs M, contains ContainsFunc[V]) bool
- func Purge[K comparable, V any, M ~map[K]V](m M, contains ContainsFunc[V])
- func Subset[K comparable, V any, M ~map[K]V](lhs, rhs M, contains ContainsFunc[V]) bool
- func SymDiff[K comparable, V any, M ~map[K]V](lhs, rhs M, contains ContainsFunc[V]) M
- func Union[K comparable, V any, M ~map[K]V](lhs, rhs M, contains ContainsFunc[V], merge MergeFunc[V]) M
- func Values[K comparable, V any, M ~map[K]V](m M, contains ContainsFunc[V]) []V
- type Bool
- func (b Bool[K]) Add(key K) bool
- func (b Bool[K]) Clone() Bool[K]
- func (b Bool[K]) Contains(k K) bool
- func (b Bool[K]) Delete(key K) bool
- func (b Bool[K]) Diff(o Bool[K]) Bool[K]
- func (b Bool[K]) Disjoint(o Bool[K]) bool
- func (b Bool[K]) Equal(o Bool[K]) bool
- func (b Bool[K]) Extend(keys ...K)
- func (b Bool[K]) Intersect(o Bool[K]) Bool[K]
- func (b Bool[K]) Keys() []K
- func (b Bool[K]) Len() int
- func (b Bool[K]) ProperSubset(o Bool[K]) bool
- func (b Bool[K]) Purge()
- func (b Bool[K]) Remove(keys ...K)
- func (b Bool[K]) Subset(o Bool[K]) bool
- func (b Bool[K]) SymDiff(o Bool[K]) Bool[K]
- func (b Bool[K]) Union(o Bool[K]) Bool[K]
- type ContainsFunc
- type MergeFunc
- type Set
- func (s Set[K]) Add(key K) bool
- func (s Set[K]) Contains(k K) bool
- func (s Set[K]) Delete(key K) bool
- func (s Set[K]) Diff(o Set[K]) Set[K]
- func (s Set[K]) Disjoint(o Set[K]) bool
- func (s Set[K]) Equal(o Set[K]) bool
- func (s Set[K]) Extend(keys ...K)
- func (s Set[K]) Intersect(o Set[K]) Set[K]
- func (s Set[K]) ProperSubset(o Set[K]) bool
- func (s Set[K]) Remove(keys ...K)
- func (s Set[K]) Subset(o Set[K]) bool
- func (s Set[K]) SymDiff(o Set[K]) Set[K]
- func (s Set[K]) Union(o Set[K]) Set[K]
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Clone ¶
func Clone[K comparable, V any, M ~map[K]V](m M, contains ContainsFunc[V]) M
Clone returns a copy of M without items that fail the ContainsFunc check.
Example ¶
package main import ( "fmt" "github.com/jimmyfrasche/mapset" ) func main() { x := map[string]int{"a": -1, "b": 0, "c": 1} contains := func(n int) bool { return n >= 0 } // this is the same behavior of maps.Clone y := mapset.Clone(x, nil) // this clone will not contain "a" as -1 fails the contains check z := mapset.Clone(x, contains) fmt.Println("y:", y) fmt.Println("z:", z) }
Output: y: map[a:-1 b:0 c:1] z: map[b:0 c:1]
func Contains ¶
func Contains[K comparable, V any, M ~map[K]V](m M, key K, contains ContainsFunc[V]) bool
Contains returns false if key is not in the set m.
If the key is not in the map m, Contains returns false.
If the key is in the map, Contains returns the result of contains.Check.
Everything in this package that accepts a ContainsFunc applies the same logic.
func Diff ¶
func Diff[K comparable, V any, M ~map[K]V](lhs, rhs M, contains ContainsFunc[V]) M
Diff is the set difference of lhs and rhs. The result contains all items in lhs that pass the ContainsFunc check that are not in rhs. Diff is also known as: relative complement, kick out, or except.
Example ¶
package main import ( "fmt" "github.com/jimmyfrasche/mapset" ) func main() { x := map[string]int{"a": 0, "b": 1, "d": -5} y := map[string]int{"b": 2, "c": 1, "d": 5} z := mapset.Diff(x, y, nil) fmt.Println(z) }
Output: map[a:0]
func Disjoint ¶
func Disjoint[K comparable, V any, M ~map[K]V](lhs, rhs M, contains ContainsFunc[V]) bool
Disjoint returns true if no keys of lhs are present in rhs.
Example ¶
package main import ( "fmt" "github.com/jimmyfrasche/mapset" ) func main() { x := map[string]int{"a": 0, "b": 1, "d": -5} y := map[string]int{"b": 1, "e": 5, "f": 7} fmt.Println("nil contains:", mapset.Disjoint(x, y, nil)) // b: 1 is the only kv-pair in both maps // so this leaves them with disjoint key-sets contains := func(n int) bool { return n != 1 } fmt.Println("contains removes 1s:", mapset.Disjoint(x, y, contains)) }
Output: nil contains: false contains removes 1s: true
func Equal ¶
func Equal[K comparable, V any, M ~map[K]V](lhs, rhs M, contains ContainsFunc[V]) bool
Equal tests equality of the keys whose values pass the ContainsFunc check. The values are otherwise not considered.
Example ¶
package main import ( "fmt" "github.com/jimmyfrasche/mapset" ) func main() { a := map[string]int{"a": 4, "b": 7, "c": -1} b := map[string]int{"a": 3, "b": 2, "c": 11} c := map[string]int{"b": 2, "c": 11, "d": 86} if mapset.Equal(a, b, nil) { fmt.Println("a = b") } if !mapset.Equal(a, c, nil) { fmt.Println("a != c") } contains := func(x int) bool { return x >= 0 } if !mapset.Equal(a, b, contains) { fmt.Println("a != b as contains removes a[c]") } }
Output: a = b a != c a != b as contains removes a[c]
func Intersect ¶
func Intersect[K comparable, V any, M ~map[K]V](lhs, rhs M, contains ContainsFunc[V], merge MergeFunc[V]) M
Intersect creates a new M that is the intersection of lhs and rhs. All pairs values pass ContainsFunc, are merged, and the result passes the ContainsFunc for inclusion.
Example ¶
package main import ( "fmt" "github.com/jimmyfrasche/mapset" ) func main() { x := map[string]int{"a": 0, "b": 1, "d": -5} y := map[string]int{"b": 2, "c": 1, "d": 5} z := mapset.Intersect(x, y, nil, nil) fmt.Println(z) }
Output: map[b:1 d:-5]
func Keys ¶
func Keys[K comparable, V any, M ~map[K]V](m M, contains ContainsFunc[V]) []K
Keys collects all the the keys whose corresponding values pass the ContainsFunc check.
Example ¶
package main import ( "fmt" "sort" "github.com/jimmyfrasche/mapset" ) func main() { m := map[string]bool{"a": true, "b": true, "c": false, "d": true} contains := func(b bool) bool { return b } k := mapset.Keys(m, contains) sort.Strings(k) fmt.Println("k:", k) }
Output: k: [a b d]
func Len ¶
func Len[K comparable, V any, M ~map[K]V](m M, contains ContainsFunc[V]) int
Len counts the keys in m whose values pass the ContainsFunc check.
func ProperSubset ¶
func ProperSubset[K comparable, V any, M ~map[K]V](lhs, rhs M, contains ContainsFunc[V]) bool
ProperSubset checks that lhs Subset rhs but not lhs Equal rhs.
Example ¶
package main import ( "fmt" "github.com/jimmyfrasche/mapset" ) func main() { a := map[string]int{"a": 4, "b": 7} b := map[string]int{"a": 3, "b": 2, "c": 1} if mapset.ProperSubset(a, b, nil) { fmt.Println("the keys of a are a proper subset of the keys of b") } if !mapset.ProperSubset(a, a, nil) { fmt.Println("a is not a proper subset of a") } if !mapset.ProperSubset(b, a, nil) { fmt.Println("the keys of b are not a proper subset of the keys of a") } }
Output: the keys of a are a proper subset of the keys of b a is not a proper subset of a the keys of b are not a proper subset of the keys of a
func Purge ¶
func Purge[K comparable, V any, M ~map[K]V](m M, contains ContainsFunc[V])
Purge removes all keys who fail the ContainsFunc check.
Example ¶
package main import ( "fmt" "github.com/jimmyfrasche/mapset" ) func main() { x := map[string]int{"a": -1, "b": 0, "c": 1} // this is a noop as there is nothing to purge mapset.Purge(x, nil) fmt.Println("nil contains:", x) contains := func(n int) bool { return n >= 0 } // this deleted "a" from x mapset.Purge(x, contains) fmt.Println("nonnil contains:", x) }
Output: nil contains: map[a:-1 b:0 c:1] nonnil contains: map[b:0 c:1]
func Subset ¶
func Subset[K comparable, V any, M ~map[K]V](lhs, rhs M, contains ContainsFunc[V]) bool
Subset tests whether lhs is a Subset of rhs.
Example ¶
package main import ( "fmt" "github.com/jimmyfrasche/mapset" ) func main() { a := map[string]int{"a": 4, "b": 7} b := map[string]int{"a": 3, "b": 2, "c": 1} if mapset.Subset(a, b, nil) { fmt.Println("the keys of a are a subset of the keys of b") } if mapset.Subset(a, a, nil) { fmt.Println("a is a subset of a") } if !mapset.Subset(b, a, nil) { fmt.Println("the keys of b are not a subset of the keys of a") } }
Output: the keys of a are a subset of the keys of b a is a subset of a the keys of b are not a subset of the keys of a
func SymDiff ¶
func SymDiff[K comparable, V any, M ~map[K]V](lhs, rhs M, contains ContainsFunc[V]) M
SymDiff is the symmetric difference of lhs and rhs. The results contains the values in lhs and rhs but not in both, according to the ContainsFunc check.
Example ¶
package main import ( "fmt" "github.com/jimmyfrasche/mapset" ) func main() { x := map[string]int{"a": 0, "b": 1, "d": -5} y := map[string]int{"b": 2, "c": 1, "d": 5, "e": 7} contains := func(n int) bool { return n >= 0 } // z has d:5 because the "d" in x is skipped by contains.Check. z := mapset.SymDiff(x, y, contains) fmt.Println("z:", z) zp := mapset.SymDiff(x, y, nil) fmt.Println("zp:", zp) }
Output: z: map[a:0 c:1 d:5 e:7] zp: map[a:0 c:1 e:7]
func Union ¶
func Union[K comparable, V any, M ~map[K]V](lhs, rhs M, contains ContainsFunc[V], merge MergeFunc[V]) M
Union creates a new M that is the union of lhs and rhs. For an item of either map to be included the value of the item must pass the ContainsFunc check. When an item exists in both maps the pair of values is merged and added to the result map if the merged value passes the ContainsFunc check.
Example ¶
package main import ( "fmt" "github.com/jimmyfrasche/mapset" ) func main() { x := map[string]int{"a": 0, "b": 1, "d": -5} y := map[string]int{"b": 2, "c": 1, "d": 5} contains := func(n int) bool { return n != 0 } merge := func(a, b int) int { return a + b } // our contains func discards "a" from x // our merge func makes "b" 3 in the resulting map // For "d" the merge func results in a value that does not pass the contains check, // so it is not included in z. z := mapset.Union(x, y, contains, merge) fmt.Println("z:", z) // with the default contains and merge, no items are discarded and the values // for keys in both default to the values in x. zp := mapset.Union(x, y, nil, nil) fmt.Println("zp:", zp) }
Output: z: map[b:3 c:1] zp: map[a:0 b:1 c:1 d:-5]
func Values ¶
func Values[K comparable, V any, M ~map[K]V](m M, contains ContainsFunc[V]) []V
Values collects all the values in m that pass the ContainsFunc check.
Example ¶
package main import ( "fmt" "sort" "github.com/jimmyfrasche/mapset" ) func main() { m := map[int]string{0: "a", 1: "b", 2: "c"} contains := func(s string) bool { return s != "a" } v := mapset.Values(m, contains) sort.Strings(v) fmt.Println("v:", v) }
Output: v: [b c]
Types ¶
type Bool ¶
type Bool[K comparable] map[K]bool
Bool provides all relevant set methods with identity as the ContainsFunc and disjunction as the MergeFunc.
func (Bool[K]) ProperSubset ¶
type ContainsFunc ¶
ContainsFunc decides if an item belongs to a set based on its value. A nil ContainsFunc always returns true.
ContainsFunc generalizes the pattern of letting a map[K]bool contain an item only if m[k] is true.
See Contains.
func (ContainsFunc[V]) Check ¶
func (c ContainsFunc[V]) Check(v V) bool
Check calls c with v or returns true if c is nil.
type MergeFunc ¶
type MergeFunc[V any] func(lhs, rhs V) V
MergeFunc takes two V and merges them into a single value. A nil MergeFunc always returns the lhs value.
MergeFunc is used for combining the values of a key that exists in two maps that are being combined in some way.
When used with a ContainsFunc, both lhs and rhs will have passed the check before the MergeFunc is called and the resulting value is also checked.
type Set ¶
type Set[K comparable] map[K]struct{}
Set provides all relevant set methods with nil ContainsFunc and MergeFunc.