1sets(3)                    Erlang Module Definition                    sets(3)
2
3
4

NAME

6       sets - Functions for set manipulation.
7

DESCRIPTION

9       Sets are collections of elements with no duplicate elements.
10
11       The data representing a set as used by this module is to be regarded as
12       opaque by other modules. In abstract terms,  the  representation  is  a
13       composite  type  of  existing Erlang terms. See note on data types. Any
14       code assuming knowledge of the format is running on thin ice.
15
16       This module provides the same interface as the  ordsets(3)  module  but
17       with  an  undefined  representation.  One difference is that while this
18       module considers two elements as different if they do not match  (=:=),
19       ordsets  considers two elements as different if and only if they do not
20       compare equal (==).
21
22       Erlang/OTP 24.0 introduced a new internal representation for sets which
23       is more performant. Developers can use this new representation by pass‐
24       ing  the  {version,  2}  flag  to  new/1  and  from_list/2,   such   as
25       sets:new([{version,  2}]).  This new representation will become the de‐
26       fault in future Erlang/OTP versions. Functions that work on  two  sets,
27       such as union/2 and similar, will work with sets of different versions.
28       In such cases, there is no guarantee about the version of the  returned
29       set.  Explicit  conversion  from  the old version to the new one can be
30       done with sets:from_list(sets:to_list(Old), [{version,2}]).
31

COMPATIBILITY

33       The following functions in this module also exist and provide the  same
34       functionality  in  the  gb_sets(3)  and ordsets(3) modules. That is, by
35       only changing the module name for each call, you can try out  different
36       set representations.
37
38         * add_element/2
39
40         * del_element/2
41
42         * filter/2
43
44         * fold/3
45
46         * from_list/1
47
48         * intersection/1
49
50         * intersection/2
51
52         * is_element/2
53
54         * is_empty/1
55
56         * is_set/1
57
58         * is_subset/2
59
60         * new/0
61
62         * size/1
63
64         * subtract/2
65
66         * to_list/1
67
68         * union/1
69
70         * union/2
71
72   Note:
73       While  the  three set implementations offer the same functionality with
74       respect to the aforementioned functions,  their  overall  behavior  may
75       differ.  As  mentioned,  this module considers elements as different if
76       and only if they do not match (=:=), while  both  ordsets  and  gb_sets
77       consider elements as different if and only if they do not compare equal
78       (==).
79
80       Example:
81
82       1> sets:is_element(1.0, sets:from_list([1])).
83       false
84       2> ordsets:is_element(1.0, ordsets:from_list([1])).
85       true
86       2> gb_sets:is_element(1.0, gb_sets:from_list([1])).
87       true
88
89

DATA TYPES

91       set(Element)
92
93              As returned by new/0.
94
95       set() = set(term())
96

EXPORTS

98       add_element(Element, Set1) -> Set2
99
100              Types:
101
102                 Set1 = Set2 = set(Element)
103
104              Returns a new set formed from Set1 with Element inserted.
105
106       del_element(Element, Set1) -> Set2
107
108              Types:
109
110                 Set1 = Set2 = set(Element)
111
112              Returns Set1, but with Element removed.
113
114       filter(Pred, Set1) -> Set2
115
116              Types:
117
118                 Pred = fun((Element) -> boolean())
119                 Set1 = Set2 = set(Element)
120
121              Filters elements in Set1 with boolean function Pred.
122
123       fold(Function, Acc0, Set) -> Acc1
124
125              Types:
126
127                 Function = fun((Element, AccIn) -> AccOut)
128                 Set = set(Element)
129                 Acc0 = Acc1 = AccIn = AccOut = Acc
130
131              Folds Function over every element in Set and returns  the  final
132              value of the accumulator. The evaluation order is undefined.
133
134       from_list(List) -> Set
135
136              Types:
137
138                 List = [Element]
139                 Set = set(Element)
140
141              Returns a set of the elements in List.
142
143       from_list(List, Opts :: [{version, 1..2}]) -> Set
144
145              Types:
146
147                 List = [Element]
148                 Set = set(Element)
149
150              Returns a set of the elements in List at the given version.
151
152       intersection(SetList) -> Set
153
154              Types:
155
156                 SetList = [set(Element), ...]
157                 Set = set(Element)
158
159              Returns the intersection of the non-empty list of sets.
160
161       intersection(Set1, Set2) -> Set3
162
163              Types:
164
165                 Set1 = Set2 = Set3 = set(Element)
166
167              Returns the intersection of Set1 and Set2.
168
169       is_disjoint(Set1, Set2) -> boolean()
170
171              Types:
172
173                 Set1 = Set2 = set(Element)
174
175              Returns  true if Set1 and Set2 are disjoint (have no elements in
176              common), otherwise false.
177
178       is_element(Element, Set) -> boolean()
179
180              Types:
181
182                 Set = set(Element)
183
184              Returns true if Element is an element of Set, otherwise false.
185
186       is_empty(Set) -> boolean()
187
188              Types:
189
190                 Set = set()
191
192              Returns true if Set is an empty set, otherwise false.
193
194       is_set(Set) -> boolean()
195
196              Types:
197
198                 Set = term()
199
200              Returns true if Set appears to be a set of  elements,  otherwise
201              false.  Note  that  the test is shallow and will return true for
202              any term that coincides with the possible representations  of  a
203              set. See also note on data types.
204
205       is_subset(Set1, Set2) -> boolean()
206
207              Types:
208
209                 Set1 = Set2 = set(Element)
210
211              Returns  true  when  every  element  of Set1 is also a member of
212              Set2, otherwise false.
213
214       new() -> set(none())
215
216              Returns a new empty set.
217
218       new(Opts :: [{version, 1..2}]) -> set(none())
219
220              Returns a new empty set at the given version.
221
222       size(Set) -> integer() >= 0
223
224              Types:
225
226                 Set = set()
227
228              Returns the number of elements in Set.
229
230       subtract(Set1, Set2) -> Set3
231
232              Types:
233
234                 Set1 = Set2 = Set3 = set(Element)
235
236              Returns only the elements of Set1 that are not also elements  of
237              Set2.
238
239       to_list(Set) -> List
240
241              Types:
242
243                 Set = set(Element)
244                 List = [Element]
245
246              Returns the elements of Set as a list. The order of the returned
247              elements is undefined.
248
249       union(SetList) -> Set
250
251              Types:
252
253                 SetList = [set(Element)]
254                 Set = set(Element)
255
256              Returns the merged (union) set of the list of sets.
257
258       union(Set1, Set2) -> Set3
259
260              Types:
261
262                 Set1 = Set2 = Set3 = set(Element)
263
264              Returns the merged (union) set of Set1 and Set2.
265

SEE ALSO

267       gb_sets(3), ordsets(3)
268
269
270
271Ericsson AB                      stdlib 5.1.1                          sets(3)