Deletes the entries in map for a specific key.

If the key does not exist, returns map unchanged.

Examples

iex> Map.delete(%{a: 1, b: 2}, :a)
%{b: 2}
iex> Map.delete(%{b: 2}, :a)
%{b: 2}

Drops the given keys from map.

Examples

iex> Map.drop(%{a: 1, b: 2, c: 3}, [:b, :d])
%{a: 1, c: 3}

Checks if two maps are equal.

Two maps are considered to be equal if they contain the same keys and those keys contain the same values.

Examples

iex> Map.equal?(%{a: 1, b: 2}, %{b: 2, a: 1})
true
iex> Map.equal?(%{a: 1, b: 2}, %{b: 1, a: 2})
false

Fetches the value for a specific key and returns it in a tuple.

If the key does not exist, returns :error.

Examples

iex> Map.fetch(%{a: 1}, :a)
{:ok, 1}
iex> Map.fetch(%{a: 1}, :b)
:error

Fetches the value for specific key.

If key does not exist, a KeyError is raised.

Examples

iex> Map.fetch!(%{a: 1}, :a)
1
iex> Map.fetch!(%{a: 1}, :b)
** (KeyError) key :b not found in: %{a: 1}

Converts a struct to map.

It accepts the struct module or a struct itself and simply removes the __struct__ field from the struct.

Example

defmodule User do
  defstruct [:name]
end

Map.from_struct(User)
#=> %{name: nil}

Map.from_struct(%User{name: "john"})
#=> %{name: "john"}

Gets the value for a specific key.

If key does not exist, return the default value (nil if no default value).

Examples

iex> Map.get(%{}, :a)
nil
iex> Map.get(%{a: 1}, :a)
1
iex> Map.get(%{a: 1}, :b)
nil
iex> Map.get(%{a: 1}, :b, 3)
3

Gets the value from key and updates it, all in one pass.

This fun argument receives the value of key (or nil if key is not present) and must return a two-element tuple: the “get” value (the retrieved value, which can be operated on before being returned) and the new value to be stored under key. The fun may also return :pop, implying the current value shall be removed from map and returned.

The returned value is a tuple with the “get” value returned by fun and a new map with the updated value under key.

Examples

iex> Map.get_and_update(%{a: 1}, :a, fn current_value ->
...>   {current_value, "new value!"}
...> end)
{1, %{a: "new value!"}}

iex> Map.get_and_update(%{a: 1}, :b, fn current_value ->
...>   {current_value, "new value!"}
...> end)
{nil, %{b: "new value!", a: 1}}

iex> Map.get_and_update(%{a: 1}, :a, fn _ -> :pop end)
{1, %{}}

iex> Map.get_and_update(%{a: 1}, :b, fn _ -> :pop end)
{nil, %{a: 1}}

Gets the value from key and updates it. Raises if there is no key.

This fun argument receives the value of key and must return a two-element tuple: the “get” value (the retrieved value, which can be operated on before being returned) and the new value to be stored under key.

The returned value is a tuple with the “get” value returned by fun and a new map with the updated value under key.

Examples

iex> Map.get_and_update!(%{a: 1}, :a, fn current_value ->
...>   {current_value, "new value!"}
...> end)
{1, %{a: "new value!"}}

iex> Map.get_and_update!(%{a: 1}, :b, fn current_value ->
...>   {current_value, "new value!"}
...> end)
** (KeyError) key :b not found

iex> Map.get_and_update!(%{a: 1}, :a, fn _ ->
...>   :pop
...> end)
{1, %{}}

Gets the value for a specific key.

If key does not exist, lazily evaluates fun and returns its result.

This is useful if the default value is very expensive to calculate or generally difficult to setup and teardown again.

Examples

iex> map = %{a: 1}
iex> fun = fn ->
...>   # some expensive operation here
...>   13
...> end
iex> Map.get_lazy(map, :a, fun)
1
iex> Map.get_lazy(map, :b, fun)
13

Returns whether a given key exists in the given map.

Examples

iex> Map.has_key?(%{a: 1}, :a)
true
iex> Map.has_key?(%{a: 1}, :b)
false

Returns all keys from map.

Examples

iex> Map.keys(%{a: 1, b: 2})
[:a, :b]

Merges two maps into one.

All keys in map2 will be added to map1, overriding any existing one.

If you have a struct and you would like to merge a set of keys into the struct, do not use this function, as it would merge all keys on the right side into the struct, even if the key is not part of the struct. Instead, use Kernel.struct/2.

Examples

iex> Map.merge(%{a: 1, b: 2}, %{a: 3, d: 4})
%{a: 3, b: 2, d: 4}

Merges two maps into one.

All keys in map2 will be added to map1. The given function will be invoked with the key, value1 and value2 to solve conflicts.

Examples

iex> Map.merge(%{a: 1, b: 2}, %{a: 3, d: 4}, fn _k, v1, v2 ->
...>   v1 + v2
...> end)
%{a: 4, b: 2, d: 4}

Returns a new empty map.

Examples

iex> Map.new
%{}

Creates a map from an enumerable.

Duplicated keys are removed; the latest one prevails.

Examples

iex> Map.new([{:b, 1}, {:a, 2}])
%{a: 2, b: 1}
iex> Map.new([a: 1, a: 2, a: 3])
%{a: 3}

Creates a map from an enumerable via the transformation function.

Duplicated keys are removed; the latest one prevails.

Examples

iex> Map.new([:a, :b], fn x -> {x, x} end)
%{a: :a, b: :b}

Returns and removes the value associated with key in map.

Examples

iex> Map.pop(%{a: 1}, :a)
{1, %{}}
iex> Map.pop(%{a: 1}, :b)
{nil, %{a: 1}}
iex> Map.pop(%{a: 1}, :b, 3)
{3, %{a: 1}}

Lazily returns and removes the value associated with key in map.

This is useful if the default value is very expensive to calculate or generally difficult to setup and teardown again.

Examples

iex> map = %{a: 1}
iex> fun = fn ->
...>   # some expensive operation here
...>   13
...> end
iex> Map.pop_lazy(map, :a, fun)
{1, %{}}
iex> Map.pop_lazy(map, :b, fun)
{13, %{a: 1}}

Puts the given value under key.

Examples

iex> Map.put(%{a: 1}, :b, 2)
%{a: 1, b: 2}
iex> Map.put(%{a: 1, b: 2}, :a, 3)
%{a: 3, b: 2}

Puts the given value under key unless the entry key already exists.

Examples

iex> Map.put_new(%{a: 1}, :b, 2)
%{b: 2, a: 1}
iex> Map.put_new(%{a: 1, b: 2}, :a, 3)
%{a: 1, b: 2}

Evaluates fun and puts the result under key in map unless key is already present.

This is useful if the value is very expensive to calculate or generally difficult to setup and teardown again.

Examples

iex> map = %{a: 1}
iex> fun = fn ->
...>   # some expensive operation here
...>   3
...> end
iex> Map.put_new_lazy(map, :a, fun)
%{a: 1}
iex> Map.put_new_lazy(map, :b, fun)
%{a: 1, b: 3}

Takes all entries corresponding to the given keys and extracts them into a separate map.

Returns a tuple with the new map and the old map with removed keys.

Keys for which there are no entries in map are ignored.

Examples

iex> Map.split(%{a: 1, b: 2, c: 3}, [:a, :c, :e])
{%{a: 1, c: 3}, %{b: 2}}

Takes all entries corresponding to the given keys and returns them in a new map.

Examples

iex> Map.take(%{a: 1, b: 2, c: 3}, [:a, :c, :e])
%{a: 1, c: 3}

Converts map to a list.

Examples

iex> Map.to_list(%{a: 1})
[a: 1]
iex> Map.to_list(%{1 => 2})
[{1, 2}]

Updates the key in map with the given function.

If the key does not exist, inserts the given initial value.

Examples

iex> Map.update(%{a: 1}, :a, 13, &(&1 * 2))
%{a: 2}
iex> Map.update(%{a: 1}, :b, 11, &(&1 * 2))
%{a: 1, b: 11}

Updates the key with the given function.

If the key does not exist, raises KeyError.

Examples

iex> Map.update!(%{a: 1}, :a, &(&1 * 2))
%{a: 2}

iex> Map.update!(%{a: 1}, :b, &(&1 * 2))
** (KeyError) key :b not found

Returns all values from map.

Examples

iex> Map.values(%{a: 1, b: 2})
[1, 2]