1/*
2Open Source Initiative OSI - The MIT License (MIT):Licensing
3
4The MIT License (MIT)
5Copyright (c) 2013 Ralph Caraveo (deckarep@gmail.com)
6
7Permission is hereby granted, free of charge, to any person obtaining a copy of
8this software and associated documentation files (the "Software"), to deal in
9the Software without restriction, including without limitation the rights to
10use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
11of the Software, and to permit persons to whom the Software is furnished to do
12so, subject to the following conditions:
13
14The above copyright notice and this permission notice shall be included in all
15copies or substantial portions of the Software.
16
17THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
19FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
20AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
21LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
22OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
23SOFTWARE.
24*/
25
26// Package mapset implements a simple and generic set collection.
27// Items stored within it are unordered and unique. It supports
28// typical set operations: membership testing, intersection, union,
29// difference, symmetric difference and cloning.
30//
31// Package mapset provides two implementations. The default
32// implementation is safe for concurrent access. There is a non-threadsafe
33// implementation which is slightly more performant.
34package mapset
35
36type Set interface {
37	// Adds an element to the set. Returns whether
38	// the item was added.
39	Add(i interface{}) bool
40
41	// Returns the number of elements in the set.
42	Cardinality() int
43
44	// Removes all elements from the set, leaving
45	// the emtpy set.
46	Clear()
47
48	// Returns a clone of the set using the same
49	// implementation, duplicating all keys.
50	Clone() Set
51
52	// Returns whether the given items
53	// are all in the set.
54	Contains(i ...interface{}) bool
55
56	// Returns the difference between this set
57	// and other. The returned set will contain
58	// all elements of this set that are not also
59	// elements of other.
60	//
61	// Note that the argument to Difference
62	// must be of the same type as the receiver
63	// of the method. Otherwise, Difference will
64	// panic.
65	Difference(other Set) Set
66
67	// Determines if two sets are equal to each
68	// other. If they have the same cardinality
69	// and contain the same elements, they are
70	// considered equal. The order in which
71	// the elements were added is irrelevant.
72	//
73	// Note that the argument to Equal must be
74	// of the same type as the receiver of the
75	// method. Otherwise, Equal will panic.
76	Equal(other Set) bool
77
78	// Returns a new set containing only the elements
79	// that exist only in both sets.
80	//
81	// Note that the argument to Intersect
82	// must be of the same type as the receiver
83	// of the method. Otherwise, Intersect will
84	// panic.
85	Intersect(other Set) Set
86
87	// Determines if every element in the other set
88	// is in this set.
89	//
90	// Note that the argument to IsSubset
91	// must be of the same type as the receiver
92	// of the method. Otherwise, IsSubset will
93	// panic.
94	IsSubset(other Set) bool
95
96	// Determines if every element in this set is in
97	// the other set.
98	//
99	// Note that the argument to IsSuperset
100	// must be of the same type as the receiver
101	// of the method. Otherwise, IsSuperset will
102	// panic.
103	IsSuperset(other Set) bool
104
105	// Returns a channel of elements that you can
106	// range over.
107	Iter() <-chan interface{}
108
109	// Remove a single element from the set.
110	Remove(i interface{})
111
112	// Provides a convenient string representation
113	// of the current state of the set.
114	String() string
115
116	// Returns a new set with all elements which are
117	// in either this set or the other set but not in both.
118	//
119	// Note that the argument to SymmetricDifference
120	// must be of the same type as the receiver
121	// of the method. Otherwise, SymmetricDifference
122	// will panic.
123	SymmetricDifference(other Set) Set
124
125	// Returns a new set with all elements in both sets.
126	//
127	// Note that the argument to Union must be of the
128	// same type as the receiver of the method.
129	// Otherwise, IsSuperset will panic.
130	Union(other Set) Set
131
132	// Returns all subsets of a given set (Power Set).
133	PowerSet() Set
134
135	// Returns the Cartesian Product of two sets.
136	CartesianProduct(other Set) Set
137
138	// Returns the members of the set as a slice.
139	ToSlice() []interface{}
140}
141
142// Creates and returns a reference to an empty set.
143func NewSet() Set {
144	set := newThreadSafeSet()
145	return &set
146}
147
148// Creates and returns a reference to a set from an existing slice
149func NewSetFromSlice(s []interface{}) Set {
150	a := NewSet()
151	for _, item := range s {
152		a.Add(item)
153	}
154	return a
155}
156
157func NewThreadUnsafeSet() Set {
158	set := newThreadUnsafeSet()
159	return &set
160}
161
162func NewThreadUnsafeSetFromSlice(s []interface{}) Set {
163	a := NewThreadUnsafeSet()
164	for _, item := range s {
165		a.Add(item)
166	}
167	return a
168}
169