.TH sets 3erl "stdlib 4.2" "Ericsson AB" "Erlang Module Definition"
.SH NAME
sets \- Functions for set manipulation.
.SH DESCRIPTION
.LP
Sets are collections of elements with no duplicate elements\&.
.LP
The data representing a set as used by this module is to be regarded as opaque by other modules\&. In abstract terms, the representation is a composite type of existing Erlang terms\&. See note on data types\&. Any code assuming knowledge of the format is running on thin ice\&.
.LP
This module provides the same interface as the \fIordsets(3erl)\fR\& module but with an undefined representation\&. One difference is that while this module considers two elements as different if they do not match (\fI=:=\fR\&), \fIordsets\fR\& considers two elements as different if and only if they do not compare equal (\fI==\fR\&)\&.
.LP
Erlang/OTP 24\&.0 introduced a new internal representation for sets which is more performant\&. Developers can use this new representation by passing the \fI{version, 2}\fR\& flag to \fInew/1\fR\& and \fIfrom_list/2\fR\&, such as \fIsets:new([{version, 2}])\fR\&\&. This new representation will become the default in future Erlang/OTP versions\&. Functions that work on two sets, such as \fIunion/2\fR\& and similar, will work with sets of different versions\&. In such cases, there is no guarantee about the version of the returned set\&. Explicit conversion from the old version to the new one can be done with \fIsets:from_list(sets:to_list(Old), [{version,2}])\fR\&\&.
.SH DATA TYPES
.nf

\fBset(Element)\fR\&
.br
.fi
.RS
.LP
As returned by \fInew/0\fR\&\&.
.RE

.nf

\fBset()\fR\& = set(term())
.br
.fi
.SH EXPORTS
.LP
.nf

.B
add_element(Element, Set1) -> Set2
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Set1 = Set2 = set(Element)
.br
.RE
.RE
.RS
.LP
Returns a new set formed from \fISet1\fR\& with \fIElement\fR\& inserted\&.
.RE

.LP
.nf

.B
del_element(Element, Set1) -> Set2
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Set1 = Set2 = set(Element)
.br
.RE
.RE
.RS
.LP
Returns \fISet1\fR\&, but with \fIElement\fR\& removed\&.
.RE

.LP
.nf

.B
filter(Pred, Set1) -> Set2
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Pred = fun((Element) -> boolean())
.br
Set1 = Set2 = set(Element)
.br
.RE
.RE
.RS
.LP
Filters elements in \fISet1\fR\& with boolean function \fIPred\fR\&\&.
.RE

.LP
.nf

.B
fold(Function, Acc0, Set) -> Acc1
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Function = fun((Element, AccIn) -> AccOut)
.br
Set = set(Element)
.br
Acc0 = Acc1 = AccIn = AccOut = Acc
.br
.RE
.RE
.RS
.LP
Folds \fIFunction\fR\& over every element in \fISet\fR\& and returns the final value of the accumulator\&. The evaluation order is undefined\&.
.RE

.LP
.nf

.B
from_list(List) -> Set
.br
.fi
.br
.RS
.LP
Types:

.RS 3
List = [Element]
.br
Set = set(Element)
.br
.RE
.RE
.RS
.LP
Returns a set of the elements in \fIList\fR\&\&.
.RE

.LP
.nf

.B
from_list(List, Opts :: [{version, 1\&.\&.2}]) -> Set
.br
.fi
.br
.RS
.LP
Types:

.RS 3
List = [Element]
.br
Set = set(Element)
.br
.RE
.RE
.RS
.LP
Returns a set of the elements in \fIList\fR\& at the given version\&.
.RE

.LP
.nf

.B
intersection(SetList) -> Set
.br
.fi
.br
.RS
.LP
Types:

.RS 3
SetList = [set(Element), \&.\&.\&.]
.br
Set = set(Element)
.br
.RE
.RE
.RS
.LP
Returns the intersection of the non-empty list of sets\&.
.RE

.LP
.nf

.B
intersection(Set1, Set2) -> Set3
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Set1 = Set2 = Set3 = set(Element)
.br
.RE
.RE
.RS
.LP
Returns the intersection of \fISet1\fR\& and \fISet2\fR\&\&.
.RE

.LP
.nf

.B
is_disjoint(Set1, Set2) -> boolean()
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Set1 = Set2 = set(Element)
.br
.RE
.RE
.RS
.LP
Returns \fItrue\fR\& if \fISet1\fR\& and \fISet2\fR\& are disjoint (have no elements in common), otherwise \fIfalse\fR\&\&.
.RE

.LP
.nf

.B
is_element(Element, Set) -> boolean()
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Set = set(Element)
.br
.RE
.RE
.RS
.LP
Returns \fItrue\fR\& if \fIElement\fR\& is an element of \fISet\fR\&, otherwise \fIfalse\fR\&\&.
.RE

.LP
.nf

.B
is_empty(Set) -> boolean()
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Set = set()
.br
.RE
.RE
.RS
.LP
Returns \fItrue\fR\& if \fISet\fR\& is an empty set, otherwise \fIfalse\fR\&\&.
.RE

.LP
.nf

.B
is_set(Set) -> boolean()
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Set = term()
.br
.RE
.RE
.RS
.LP
Returns \fItrue\fR\& if \fISet\fR\& appears to be a set of elements, otherwise \fIfalse\fR\&\&. Note that the test is shallow and will return \fItrue\fR\& for any term that coincides with the possible representations of a set\&. See also note on data types\&.
.RE

.LP
.nf

.B
is_subset(Set1, Set2) -> boolean()
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Set1 = Set2 = set(Element)
.br
.RE
.RE
.RS
.LP
Returns \fItrue\fR\& when every element of \fISet1\fR\& is also a member of \fISet2\fR\&, otherwise \fIfalse\fR\&\&.
.RE

.LP
.nf

.B
new() -> set()
.br
.fi
.br
.RS
.LP
Returns a new empty set\&.
.RE

.LP
.nf

.B
new(Opts :: [{version, 1\&.\&.2}]) -> set()
.br
.fi
.br
.RS
.LP
Returns a new empty set at the given version\&.
.RE

.LP
.nf

.B
size(Set) -> integer() >= 0
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Set = set()
.br
.RE
.RE
.RS
.LP
Returns the number of elements in \fISet\fR\&\&.
.RE

.LP
.nf

.B
subtract(Set1, Set2) -> Set3
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Set1 = Set2 = Set3 = set(Element)
.br
.RE
.RE
.RS
.LP
Returns only the elements of \fISet1\fR\& that are not also elements of \fISet2\fR\&\&.
.RE

.LP
.nf

.B
to_list(Set) -> List
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Set = set(Element)
.br
List = [Element]
.br
.RE
.RE
.RS
.LP
Returns the elements of \fISet\fR\& as a list\&. The order of the returned elements is undefined\&.
.RE

.LP
.nf

.B
union(SetList) -> Set
.br
.fi
.br
.RS
.LP
Types:

.RS 3
SetList = [set(Element)]
.br
Set = set(Element)
.br
.RE
.RE
.RS
.LP
Returns the merged (union) set of the list of sets\&.
.RE

.LP
.nf

.B
union(Set1, Set2) -> Set3
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Set1 = Set2 = Set3 = set(Element)
.br
.RE
.RE
.RS
.LP
Returns the merged (union) set of \fISet1\fR\& and \fISet2\fR\&\&.
.RE

.SH "SEE ALSO"

.LP
\fIgb_sets(3erl)\fR\&, \fIordsets(3erl)\fR\&