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())
trueNote that, however, the struct fields are private and must not be accessed directly; use the functions in this module to perform operations on sets.
MapSets 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.
Dialyzer opaqueness warnings
MapSet internally relies on the :sets module which uses
opaque types. This might cause Dialyzer to report opaqueness violations.
These can be silenced by setting the following module attribute:
@dialyzer :no_opaqueSummary
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 MapSets 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]))
falseChecks if two sets are equal.
The comparison between elements is done using ===/2,
which means 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
and MapSet.reject/2 in a pipeline, it is likely more efficient
to use Enum.map/2 and Enum.filter/2 instead and convert to
a set at the end using MapSet.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]))
3Splits the map_set into two MapSets 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([10, 20, 60, 70]), fn v -> v > 50 end)
iex> while_true
MapSet.new([60, 70])
iex> while_false
MapSet.new([10, 20])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]))
falseReturns 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])