View Source MapSet (Elixir v1.17.2)
Functions that work on sets.
A set is a data structure that can contain unique elements of any kind,
without any particular order. MapSet
is the "go to" set data structure in Elixir.
A set can be constructed using MapSet.new/0
:
iex> MapSet.new()
MapSet.new([])
Elements in a set don't have to be of the same type and they can be
populated from an enumerable using MapSet.new/1
:
iex> MapSet.new([1, :two, {"three"}])
MapSet.new([1, :two, {"three"}])
Elements can be inserted using MapSet.put/2
:
iex> MapSet.new([2]) |> MapSet.put(4) |> MapSet.put(0)
MapSet.new([0, 2, 4])
By definition, sets can't contain duplicate elements: when inserting an element in a set where it's already present, the insertion is simply a no-op.
iex> map_set = MapSet.new()
iex> MapSet.put(map_set, "foo")
MapSet.new(["foo"])
iex> map_set |> MapSet.put("foo") |> MapSet.put("foo")
MapSet.new(["foo"])
A MapSet
is represented internally using the %MapSet{}
struct. This struct
can be used whenever there's a need to pattern match on something being a MapSet
:
iex> match?(%MapSet{}, MapSet.new())
true
Note that, however, the struct fields are private and must not be accessed directly; use the functions in this module to perform operations on sets.
MapSet
s can also be constructed starting from other collection-type data
structures: for example, see MapSet.new/1
or Enum.into/2
.
MapSet
is built on top of Erlang's
:sets
(version 2). This means
that they share many properties, including logarithmic time complexity. Erlang
:sets
(version 2) are implemented on top of maps, so see the documentation
for Map
for more information on its execution time complexity.
Summary
Functions
Deletes value
from map_set
.
Returns a set that is map_set1
without the members of map_set2
.
Checks if map_set1
and map_set2
have no members in common.
Checks if two sets are equal.
Filters the set by returning only the elements from map_set
for which invoking
fun
returns a truthy value.
Returns a set containing only members that map_set1
and map_set2
have in common.
Checks if map_set
contains value
.
Returns a new set.
Creates a set from an enumerable.
Creates a set from an enumerable via the transformation function.
Inserts value
into map_set
if map_set
doesn't already contain it.
Returns a set by excluding the elements from map_set
for which invoking fun
returns a truthy value.
Returns the number of elements in map_set
.
Splits the map_set
into two MapSet
s according to the given function fun
.
Checks if map_set1
's members are all contained in map_set2
.
Returns a set with elements that are present in only one but not both sets.
Converts map_set
to a list.
Returns a set containing all members of map_set1
and map_set2
.
Types
Functions
Deletes value
from map_set
.
Returns a new set which is a copy of map_set
but without value
.
Examples
iex> map_set = MapSet.new([1, 2, 3])
iex> MapSet.delete(map_set, 4)
MapSet.new([1, 2, 3])
iex> MapSet.delete(map_set, 2)
MapSet.new([1, 3])
Returns a set that is map_set1
without the members of map_set2
.
Examples
iex> MapSet.difference(MapSet.new([1, 2]), MapSet.new([2, 3, 4]))
MapSet.new([1])
Checks if map_set1
and map_set2
have no members in common.
Examples
iex> MapSet.disjoint?(MapSet.new([1, 2]), MapSet.new([3, 4]))
true
iex> MapSet.disjoint?(MapSet.new([1, 2]), MapSet.new([2, 3]))
false
Checks if two sets are equal.
The comparison between elements is done using ===/2
,
which a set with 1
is not equivalent to a set with
1.0
.
Examples
iex> MapSet.equal?(MapSet.new([1, 2]), MapSet.new([2, 1, 1]))
true
iex> MapSet.equal?(MapSet.new([1, 2]), MapSet.new([3, 4]))
false
iex> MapSet.equal?(MapSet.new([1]), MapSet.new([1.0]))
false
@spec filter(t(a), (a -> as_boolean(term()))) :: t(a) when a: value()
Filters the set by returning only the elements from map_set
for which invoking
fun
returns a truthy value.
Also see reject/2
which discards all elements where the function returns
a truthy value.
Performance considerations
If you find yourself doing multiple calls to
MapSet.filter/2
andMapSet.reject/2
in a pipeline, it is likely more efficient to useEnum.map/2
andEnum.filter/2
instead and convert to a map at the end usingMapSet.new/1
.
Examples
iex> MapSet.filter(MapSet.new(1..5), fn x -> x > 3 end)
MapSet.new([4, 5])
iex> MapSet.filter(MapSet.new(["a", :b, "c"]), &is_atom/1)
MapSet.new([:b])
Returns a set containing only members that map_set1
and map_set2
have in common.
Examples
iex> MapSet.intersection(MapSet.new([1, 2]), MapSet.new([2, 3, 4]))
MapSet.new([2])
iex> MapSet.intersection(MapSet.new([1, 2]), MapSet.new([3, 4]))
MapSet.new([])
Checks if map_set
contains value
.
Examples
iex> MapSet.member?(MapSet.new([1, 2, 3]), 2)
true
iex> MapSet.member?(MapSet.new([1, 2, 3]), 4)
false
@spec new() :: t()
Returns a new set.
Examples
iex> MapSet.new()
MapSet.new([])
@spec new(Enumerable.t()) :: t()
Creates a set from an enumerable.
Examples
iex> MapSet.new([:b, :a, 3])
MapSet.new([3, :a, :b])
iex> MapSet.new([3, 3, 3, 2, 2, 1])
MapSet.new([1, 2, 3])
@spec new(Enumerable.t(), (term() -> val)) :: t(val) when val: value()
Creates a set from an enumerable via the transformation function.
Examples
iex> MapSet.new([1, 2, 1], fn x -> 2 * x end)
MapSet.new([2, 4])
Inserts value
into map_set
if map_set
doesn't already contain it.
Examples
iex> MapSet.put(MapSet.new([1, 2, 3]), 3)
MapSet.new([1, 2, 3])
iex> MapSet.put(MapSet.new([1, 2, 3]), 4)
MapSet.new([1, 2, 3, 4])
@spec reject(t(a), (a -> as_boolean(term()))) :: t(a) when a: value()
Returns a set by excluding the elements from map_set
for which invoking fun
returns a truthy value.
See also filter/2
.
Examples
iex> MapSet.reject(MapSet.new(1..5), fn x -> rem(x, 2) != 0 end)
MapSet.new([2, 4])
iex> MapSet.reject(MapSet.new(["a", :b, "c"]), &is_atom/1)
MapSet.new(["a", "c"])
@spec size(t()) :: non_neg_integer()
Returns the number of elements in map_set
.
Examples
iex> MapSet.size(MapSet.new([1, 2, 3]))
3
Splits the map_set
into two MapSet
s according to the given function fun
.
fun
receives each element in the map_set
as its only argument. Returns
a tuple with the first MapSet
containing all the elements in map_set
for which
applying fun
returned a truthy value, and a second MapSet
with all the elements
for which applying fun
returned a falsy value (false
or nil
).
Examples
iex> {while_true, while_false} = MapSet.split_with(MapSet.new([1, 2, 3, 4]), fn v -> rem(v, 2) == 0 end)
iex> while_true
MapSet.new([2, 4])
iex> while_false
MapSet.new([1, 3])
iex> {while_true, while_false} = MapSet.split_with(MapSet.new(), fn {_k, v} -> v > 50 end)
iex> while_true
MapSet.new([])
iex> while_false
MapSet.new([])
Checks if map_set1
's members are all contained in map_set2
.
This function checks if map_set1
is a subset of map_set2
.
Examples
iex> MapSet.subset?(MapSet.new([1, 2]), MapSet.new([1, 2, 3]))
true
iex> MapSet.subset?(MapSet.new([1, 2, 3]), MapSet.new([1, 2]))
false
Returns a set with elements that are present in only one but not both sets.
Examples
iex> MapSet.symmetric_difference(MapSet.new([1, 2, 3]), MapSet.new([2, 3, 4]))
MapSet.new([1, 4])
Converts map_set
to a list.
Examples
iex> MapSet.to_list(MapSet.new([1, 2, 3]))
[1, 2, 3]
Returns a set containing all members of map_set1
and map_set2
.
Examples
iex> MapSet.union(MapSet.new([1, 2]), MapSet.new([2, 3, 4]))
MapSet.new([1, 2, 3, 4])