README
¶
golang-set
The missing set collection for the Go language. Until Go has sets built-in...use this.
Coming from Python one of the things I miss is the superbly wonderful set collection. This is my attempt to mimic the primary features of the set from Python. You can of course argue that there is no need for a set in Go, otherwise the creators would have added one to the standard library. To those I say simply ignore this repository and carry-on and to the rest that find this useful please contribute in helping me make it better by:
- Helping to make more idiomatic improvements to the code.
- Helping to increase the performance of it.
(So far, no attempt has been made, but since it uses a map internally, I expect it to be mostly performant.) - Helping to make the unit-tests more robust and kick-ass.
- Helping to fill in the documentation.
- Simply offering feedback and suggestions. (Positive, constructive feedback is appreciated.)
I have to give some credit for helping seed the idea with this post on stackoverflow.
Update - as of 3/9/2014, you can use a compile-time generic version of this package in the gen framework. This framework allows you to use the golang-set in a completely generic and type-safe way by allowing you to generate a supporting .go file based on your custom types.
Features (as of 9/22/2014)
- a CartesianProduct() method has been added with unit-tests: Read more about the cartesian product
Features (as of 9/15/2014)
- a PowerSet() method has been added with unit-tests: Read more about the Power set
Features (as of 4/22/2014)
- One common interface to both implementations
- Two set implementations to choose from
- a thread-safe implementation designed for concurrent use
- a non-thread-safe implementation designed for performance
- 75 benchmarks for both implementations
- 35 unit tests for both implementations
- 14 concurrent tests for the thread-safe implementation
Please see the unit test file for additional usage examples. The Python set documentation will also do a better job than I can of explaining how a set typically works. Please keep in mind however that the Python set is a built-in type and supports additional features and syntax that make it awesome.
Examples but not exhaustive:
requiredClasses := mapset.NewSet()
requiredClasses.Add("Cooking")
requiredClasses.Add("English")
requiredClasses.Add("Math")
requiredClasses.Add("Biology")
scienceSlice := []interface{}{"Biology", "Chemistry"}
scienceClasses := mapset.NewSetFromSlice(scienceSlice)
electiveClasses := mapset.NewSet()
electiveClasses.Add("Welding")
electiveClasses.Add("Music")
electiveClasses.Add("Automotive")
bonusClasses := mapset.NewSet()
bonusClasses.Add("Go Programming")
bonusClasses.Add("Python Programming")
//Show me all the available classes I can take
allClasses := requiredClasses.Union(scienceClasses).Union(electiveClasses).Union(bonusClasses)
fmt.Println(allClasses) //Set{Cooking, English, Math, Chemistry, Welding, Biology, Music, Automotive, Go Programming, Python Programming}
//Is cooking considered a science class?
fmt.Println(scienceClasses.Contains("Cooking")) //false
//Show me all classes that are not science classes, since I hate science.
fmt.Println(allClasses.Difference(scienceClasses)) //Set{Music, Automotive, Go Programming, Python Programming, Cooking, English, Math, Welding}
//Which science classes are also required classes?
fmt.Println(scienceClasses.Intersect(requiredClasses)) //Set{Biology}
//How many bonus classes do you offer?
fmt.Println(bonusClasses.Cardinality()) //2
//Do you have the following classes? Welding, Automotive and English?
fmt.Println(allClasses.IsSuperset(mapset.NewSetFromSlice([]interface{}{"Welding", "Automotive", "English"}))) //true
Thanks!
-Ralph
Documentation
¶
Overview ¶
Package mapset implements a simple and generic set collection. Items stored within it are unordered and unique. It supports typical set operations: membership testing, intersection, union, difference, symmetric difference and cloning.
Package mapset provides two implementations of the Set interface. The default implementation is safe for concurrent access, but a non-thread-safe implementation is also provided for programs that can benefit from the slight speed improvement and that can enforce mutual exclusion through other means.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Iterator ¶
type Iterator struct {
C <-chan interface{}
// contains filtered or unexported fields
}
Iterator defines an iterator over a Set, its C channel can be used to range over the Set's elements.
Example ¶
package main
import (
"fmt"
)
type YourType struct {
Name string
}
func main() {
set := NewSetFromSlice([]interface{}{
&YourType{Name: "Alise"},
&YourType{Name: "Bob"},
&YourType{Name: "John"},
&YourType{Name: "Nick"},
})
var found *YourType
it := set.Iterator()
for elem := range it.C {
if elem.(*YourType).Name == "John" {
found = elem.(*YourType)
it.Stop()
}
}
fmt.Printf("Found %+v\n", found)
}
Output: Found &{Name:John}
type OrderedPair ¶
type OrderedPair struct {
First interface{}
Second interface{}
}
An OrderedPair represents a 2-tuple of values.
func (*OrderedPair) Equal ¶
func (pair *OrderedPair) Equal(other OrderedPair) bool
Equal says whether two 2-tuples contain the same values in the same order.
func (OrderedPair) String ¶
func (pair OrderedPair) String() string
String outputs a 2-tuple in the form "(A, B)".
type Set ¶
type Set interface {
// Adds an element to the set. Returns whether
// the item was added.
Add(i interface{}) bool
// Returns the number of elements in the set.
N() int
// Removes all elements from the set, leaving
// the empty set.
Clear()
// Returns a clone of the set using the same
// implementation, duplicating all keys.
Clone() Set
// Returns whether the given item is in set.
Contains(i interface{}) bool
// Returns the difference between this set
// and other. The returned set will contain
// all elements of this set that are not also
// elements of other.
//
// Note that the argument to Difference
// must be of the same type as the receiver
// of the method. Otherwise, Difference will
// panic.
Difference(other Set) Set
// Determines if two sets are equal to each
// other. If they have the same cardinality
// and contain the same elements, they are
// considered equal. The order in which
// the elements were added is irrelevant.
//
// Note that the argument to Equal must be
// of the same type as the receiver of the
// method. Otherwise, Equal will panic.
Equal(other Set) bool
// Returns a new set containing only the elements
// that exist only in both sets.
//
// Note that the argument to Intersect
// must be of the same type as the receiver
// of the method. Otherwise, Intersect will
// panic.
Intersect(other Set) Set
// Determines if every element in this set is in
// the other set but the two sets are not equal.
//
// Note that the argument to IsProperSubset
// must be of the same type as the receiver
// of the method. Otherwise, IsProperSubset
// will panic.
IsProperSubset(other Set) bool
// Determines if every element in the other set
// is in this set but the two sets are not
// equal.
//
// Note that the argument to IsSuperset
// must be of the same type as the receiver
// of the method. Otherwise, IsSuperset will
// panic.
IsProperSuperset(other Set) bool
// Determines if every element in this set is in
// the other set.
//
// Note that the argument to IsSubset
// must be of the same type as the receiver
// of the method. Otherwise, IsSubset will
// panic.
IsSubset(other Set) bool
// Determines if every element in the other set
// is in this set.
//
// Note that the argument to IsSuperset
// must be of the same type as the receiver
// of the method. Otherwise, IsSuperset will
// panic.
IsSuperset(other Set) bool
// Iterates over elements and executes the passed func against each element.
// If passed func returns true, stop iteration at the time.
Each(func(interface{}) bool)
// Returns a channel of elements that you can
// range over.
Iter() <-chan interface{}
// Returns an Iterator object that you can
// use to range over the set.
Iterator() *Iterator
// Remove a single element from the set.
Remove(i interface{})
// Provides a convenient string representation
// of the current state of the set.
String() string
// Returns a new set with all elements which are
// in either this set or the other set but not in both.
//
// Note that the argument to SymmetricDifference
// must be of the same type as the receiver
// of the method. Otherwise, SymmetricDifference
// will panic.
SymmetricDifference(other Set) Set
// same type as the receiver of the method.
// Otherwise, IsSuperset will panic.
Union(other Set) Set
// Pop removes and returns an arbitrary item from the set.
Pop() interface{}
// Returns all subsets of a given set (Power Set).
PowerSet() Set
// Returns the Cartesian Product of two sets.
CartesianProduct(other Set) Set
// Returns the members of the set as a slice.
ToSlice() []interface{}
}
Set is the primary interface provided by the mapset package. It represents an unordered set of data and a large number of operations that can be applied to that set.
func NewSet ¶
func NewSet(s ...interface{}) Set
NewSet creates and returns a reference to an empty set. Operations on the resulting set are thread-safe.
func NewSetFromSlice ¶
func NewSetFromSlice(s []interface{}) Set
NewSetFromSlice creates and returns a reference to a set from an existing slice. Operations on the resulting set are thread-safe.
func NewSetWith ¶
func NewSetWith(elts ...interface{}) Set
NewSetWith creates and returns a new set with the given elements. Operations on the resulting set are thread-safe.
func NewThreadUnsafeSet ¶
func NewThreadUnsafeSet() Set
NewThreadUnsafeSet creates and returns a reference to an empty set. Operations on the resulting set are not thread-safe.
func NewThreadUnsafeSetFromSlice ¶
func NewThreadUnsafeSetFromSlice(s []interface{}) Set
NewThreadUnsafeSetFromSlice creates and returns a reference to a set from an existing slice. Operations on the resulting set are not thread-safe.
Source Files