sets — stdlib v6.0

Search documentation of stdlib

# View Source sets (stdlib v6.0)

Sets are collections of elements with no duplicate elements.

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.

This module provides the same interface as the `ordsets` module but with an undefined representation. One difference is that while this module considers two elements as different if they do not match (`=:=`), `ordsets` considers two elements as different if and only if they do not compare equal (`==`).

Erlang/OTP 24.0 introduced a new internal representation for sets which is more performant. Developers can use this new representation by passing the `{version, 2}` flag to `new/1` and `from_list/2`, such as `sets:new([{version, 2}])`. This new representation will become the default in future Erlang/OTP versions. Functions that work on two sets, such as `union/2` 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 `sets:from_list(sets:to_list(Old), [{version,2}])`.

## Compatibility

The following functions in this module also exist and provide the same functionality in the `gb_sets` and `ordsets` modules. That is, by only changing the module name for each call, you can try out different set representations.

- `add_element/2`
- `del_element/2`
- `filter/2`
- `filtermap/2`
- `fold/3`
- `from_list/1`
- `intersection/1`
- `intersection/2`
- `is_element/2`
- `is_empty/1`
- `is_equal/2`
- `is_set/1`
- `is_subset/2`
- `map/2`
- `new/0`
- `size/1`
- `subtract/2`
- `to_list/1`
- `union/1`
- `union/2`

> #### Note

> While the three set implementations offer the same functionality with respect to the aforementioned functions, their overall behavior may differ. As mentioned, this module considers elements as different if and only if they do not match (`=:=`), while both `ordsets` and `gb_sets` consider elements as different if and only if they do not compare equal (`==`).

> Example:

>     1> sets:is_element(1.0, sets:from_list([1])).
>     false
>     2> ordsets:is_element(1.0, ordsets:from_list([1])).
>     true
>     2> gb_sets:is_element(1.0, gb_sets:from_list([1])).
>     true

## See Also

`gb_sets`, `ordsets`

# Summary

## Types

set()
set(Element)

As returned by `new/0`.

## Functions

add_element(Element, Set1)

Returns a new set formed from `Set1` with `Element` inserted.

del_element(Element, Set1)

Returns `Set1`, but with `Element` removed.

filter(Pred, Set1)

Filters elements in `Set1` with boolean function `Pred`.

filtermap(Fun, Set1)

Filters and maps elements in `Set1` with function `Fun`.

fold(Function, Acc0, Set)

Folds `Function` over every element in `Set` and returns the final value of the accumulator. The evaluation order is undefined.

from_list(List)

Returns a set of the elements in `List`.

from_list/2

Returns a set of the elements in `List` at the given version.

intersection(SetList)

Returns the intersection of the non-empty list of sets.

intersection(Set1, Set2)

Returns the intersection of `Set1` and `Set2`.

is_disjoint(Set1, Set2)

Returns `true` if `Set1` and `Set2` are disjoint (have no elements in common), otherwise `false`.

is_element(Element, Set)

Returns `true` if `Element` is an element of `Set`, otherwise `false`.

is_empty(Set)

Returns `true` if `Set` is an empty set, otherwise `false`.

is_equal(Set1, Set2)

Returns `true` if `Set1` and `Set2` are equal, that is when every element of one set is also a member of the respective other set, otherwise `false`.

is_set(Set)

Returns `true` if `Set` appears to be a set of elements, otherwise `false`.

is_subset(Set1, Set2)

Returns `true` when every element of `Set1` is also a member of `Set2`, otherwise `false`.

map(Fun, Set1)

Maps elements in `Set1` with mapping function `Fun`.

new()

Returns a new empty set.

new/1

Returns a new empty set at the given version.

size(Set)

Returns the number of elements in `Set`.

subtract(Set1, Set2)

Returns only the elements of `Set1` that are not also elements of `Set2`.

to_list(Set)

Returns the elements of `Set` as a list. The order of the returned elements is undefined.

union(SetList)

Returns the merged (union) set of the list of sets.

union(Set1, Set2)

Returns the merged (union) set of `Set1` and `Set2`.

# Types

Link to this type

# set()

View Source

    -type set() :: set(_).

Link to this opaque

# set(Element)

View Source

    -opaque set(Element)

As returned by `new/0`.

# Functions

Link to this function

# add_element(Element, Set1)

View Source

    -spec add_element(Element, Set1) -> Set2 when Set1 :: set(Element), Set2 :: set(Element).

Returns a new set formed from `Set1` with `Element` inserted.

Link to this function

# del_element(Element, Set1)

View Source

    -spec del_element(Element, Set1) -> Set2 when Set1 :: set(Element), Set2 :: set(Element).

Returns `Set1`, but with `Element` removed.

Link to this function

# filter(Pred, Set1)

View Source

    -spec filter(Pred, Set1) -> Set2
                    when Pred :: fun((Element) -> boolean()), Set1 :: set(Element), Set2 :: set(Element).

Filters elements in `Set1` with boolean function `Pred`.

Link to this function

# filtermap(Fun, Set1)

View Source (since OTP 27.0)

    -spec filtermap(Fun, Set1) -> Set2
                       when
                           Fun :: fun((Element1) -> boolean() | {true, Element2}),
                           Set1 :: set(Element1),
                           Set2 :: set(Element1 | Element2).

Filters and maps elements in `Set1` with function `Fun`.

Link to this function

# fold(Function, Acc0, Set)

View Source

    -spec fold(Function, Acc0, Set) -> Acc1
                  when
                      Function :: fun((Element, AccIn) -> AccOut),
                      Set :: set(Element),
                      Acc0 :: Acc,
                      Acc1 :: Acc,
                      AccIn :: Acc,
                      AccOut :: Acc.

Folds `Function` over every element in `Set` and returns the final value of the accumulator. The evaluation order is undefined.

Link to this function

# from_list(List)

View Source

    -spec from_list(List) -> Set when List :: [Element], Set :: set(Element).

Returns a set of the elements in `List`.

Link to this function

# from_list/2

View Source (since OTP 24.0)

    -spec from_list(List, [{version, 1..2}]) -> Set when List :: [Element], Set :: set(Element).

Returns a set of the elements in `List` at the given version.

Link to this function

# intersection(SetList)

View Source

    -spec intersection(SetList) -> Set when SetList :: [set(Element), ...], Set :: set(Element).

Returns the intersection of the non-empty list of sets.

Link to this function

# intersection(Set1, Set2)

View Source

    -spec intersection(Set1, Set2) -> Set3
                          when Set1 :: set(Element), Set2 :: set(Element), Set3 :: set(Element).

Returns the intersection of `Set1` and `Set2`.

Link to this function

# is_disjoint(Set1, Set2)

View Source

    -spec is_disjoint(Set1, Set2) -> boolean() when Set1 :: set(Element), Set2 :: set(Element).

Returns `true` if `Set1` and `Set2` are disjoint (have no elements in common), otherwise `false`.

Link to this function

# is_element(Element, Set)

View Source

    -spec is_element(Element, Set) -> boolean() when Set :: set(Element).

Returns `true` if `Element` is an element of `Set`, otherwise `false`.

Link to this function

# is_empty(Set)

View Source (since OTP 21.0)

    -spec is_empty(Set) -> boolean() when Set :: set().

Returns `true` if `Set` is an empty set, otherwise `false`.

Link to this function

# is_equal(Set1, Set2)

View Source (since OTP 27.0)

    -spec is_equal(Set1, Set2) -> boolean() when Set1 :: set(), Set2 :: set().

Returns `true` if `Set1` and `Set2` are equal, that is when every element of one set is also a member of the respective other set, otherwise `false`.

Link to this function

# is_set(Set)

View Source

    -spec is_set(Set) -> boolean() when Set :: term().

Returns `true` if `Set` appears to be a set of elements, otherwise `false`.

Note that the test is shallow and will return `true` for any term that coincides with the possible representations of a set. See also note on data types.

Link to this function

# is_subset(Set1, Set2)

View Source

    -spec is_subset(Set1, Set2) -> boolean() when Set1 :: set(Element), Set2 :: set(Element).

Returns `true` when every element of `Set1` is also a member of `Set2`, otherwise `false`.

Link to this function

# map(Fun, Set1)

View Source (since OTP 27.0)

    -spec map(Fun, Set1) -> Set2
                 when Fun :: fun((Element1) -> Element2), Set1 :: set(Element1), Set2 :: set(Element2).

Maps elements in `Set1` with mapping function `Fun`.

Link to this function

# new()

View Source

    -spec new() -> set(none()).

Returns a new empty set.

Link to this function

# new/1

View Source (since OTP 24.0)

    -spec new([{version, 1..2}]) -> set(none()).

Returns a new empty set at the given version.

Link to this function

# size(Set)

View Source

    -spec size(Set) -> non_neg_integer() when Set :: set().

Returns the number of elements in `Set`.

Link to this function

# subtract(Set1, Set2)

View Source

    -spec subtract(Set1, Set2) -> Set3 when Set1 :: set(Element), Set2 :: set(Element), Set3 :: set(Element).

Returns only the elements of `Set1` that are not also elements of `Set2`.

Link to this function

# to_list(Set)

View Source

    -spec to_list(Set) -> List when Set :: set(Element), List :: [Element].

Returns the elements of `Set` as a list. The order of the returned elements is undefined.

Link to this function

# union(SetList)

View Source

    -spec union(SetList) -> Set when SetList :: [set(Element)], Set :: set(Element).

Returns the merged (union) set of the list of sets.

Link to this function

# union(Set1, Set2)

View Source

    -spec union(Set1, Set2) -> Set3 when Set1 :: set(Element), Set2 :: set(Element), Set3 :: set(Element).

Returns the merged (union) set of `Set1` and `Set2`.