View Source MapSet (Elixir v1.14.0-rc.0)

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.

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 Map, this means that they share many properties, including logarithmic time complexity. See the documentation for Map for more information on its execution time complexity.

Link to this section 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 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 set for which invoking fun returns a truthy value.

Returns the number of elements in map_set.

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.

Link to this section Types

Link to this opaque

internal(value)

View Source (opaque)
@opaque internal(value)
@type t() :: t(term())
@type t(value) :: %MapSet{map: internal(value), version: term()}
@type value() :: term()

Link to this section Functions

@spec delete(t(val1), val2) :: t(val1) when val1: value(), val2: value()

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])
Link to this function

difference(map_set1, map_set2)

View Source
@spec difference(t(val1), t(val2)) :: t(val1) when val1: value(), val2: value()

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])
Link to this function

disjoint?(map_set1, map_set2)

View Source
@spec disjoint?(t(), t()) :: boolean()

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
Link to this function

equal?(map_set1, map_set2)

View Source
@spec equal?(t(), t()) :: boolean()

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
Link to this function

filter(map_set, fun)

View Source (since 1.14.0)
@spec filter(t(a), (a -> as_boolean(term()))) :: t(a) when a: value()

Filters the set by returning only the elements from set for which invoking fun returns a truthy value.

Also see reject/2 which discards all elements where the function returns a truthy value.

Note: 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 map at the end using Map.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])
Link to this function

intersection(map_set, map_set)

View Source
@spec intersection(t(val), t(val)) :: t(val) when val: value()

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([])
@spec member?(t(), value()) :: boolean()

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])
Link to this function

new(enumerable, transform)

View Source
@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])
@spec put(t(val), new_val) :: t(val | new_val) when val: value(), new_val: value()

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])
Link to this function

reject(map_set, fun)

View Source (since 1.14.0)
@spec reject(t(a), (a -> as_boolean(term()))) :: t(a) when a: value()

Returns a set by excluding the elements from 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
Link to this function

subset?(map_set1, map_set2)

View Source
@spec subset?(t(), t()) :: boolean()

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
Link to this function

symmetric_difference(map_set1, map_set2)

View Source (since 1.14.0)
@spec symmetric_difference(t(val1), t(val2)) :: t(val1 | val2)
when val1: value(), val2: value()

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])
@spec to_list(t(val)) :: [val] when val: value()

Converts map_set to a list.

Examples

iex> MapSet.to_list(MapSet.new([1, 2, 3]))
[1, 2, 3]
Link to this function

union(map_set1, map_set2)

View Source
@spec union(t(val1), t(val2)) :: t(val1 | val2) when val1: value(), val2: value()

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])