Map

A set of functions for working with maps.

Maps are key-value stores where keys can be any value and are compared using the match operator (===). Maps can be created with the %{} special form defined in the Kernel.SpecialForms module.

Summary

Types

key()

value()

Functions

delete(map, key)

Deletes the entries in map for a specific key

drop(map, keys)

Drops the given keys from map

equal?(map1, map2)

Checks if two maps are equal

fetch(map, key)

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

fetch!(map, key)

Fetches the value for specific key

from_struct(struct)

Converts a struct to map

get(map, key, default \\ nil)

Gets the value for a specific key

get_and_update(map, key, fun)

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

get_and_update!(map, key, fun)

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

get_lazy(map, key, fun)

Gets the value for a specific key

has_key?(map, key)

Returns whether a given key exists in the given map

keys(map)

Returns all keys from map

merge(map1, map2)

Merges two maps into one

merge(map1, map2, callback)

Merges two maps into one

new()

Returns a new empty map

new(enumerable)

Creates a map from an enumerable

new(enumerable, transform)

Creates a map from an enumerable via the transformation function

pop(map, key, default \\ nil)

Returns and removes the value associated with key in map

pop_lazy(map, key, fun)

Lazily returns and removes the value associated with key in map

put(map, key, val)

Puts the given value under key

put_new(map, key, value)

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

put_new_lazy(map, key, fun)

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

split(map, keys)

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

take(map, keys)

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

to_list(map)

Converts map to a list

update(map, key, initial, fun)

Updates the key in map with the given function

update!(map, key, fun)

Updates the key with the given function

values(map)

Returns all values from map

Types

key()

key() :: any

value()

value() :: any

Functions

delete(map, key)

delete(map, key) :: map

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}

drop(map, keys)

drop(map, Enumerable.t) :: map

Drops the given keys from map.

Examples

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

equal?(map1, map2)

equal?(map, map) :: boolean

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

fetch(map, key)

fetch(map, key) :: {:ok, value} | :error

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

fetch!(map, key)

fetch!(map, key) :: value | no_return

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}

from_struct(struct)

from_struct(atom | struct) :: map

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"}

get(map, key, default \\ nil)

get(map, key, value) :: value

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

get_and_update(map, key, fun)

get_and_update(map, key, (value -> {get, value} | :pop)) :: {get, map} when get: term

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}}

get_and_update!(map, key, fun)

get_and_update!(map, key, (value -> {get, value})) ::
  {get, map} |
  no_return when get: term

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, %{}}

get_lazy(map, key, fun)

get_lazy(map, key, (() -> value)) :: value

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

has_key?(map, key)

has_key?(map, key) :: boolean

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

keys(map)

keys(map) :: [key]

Returns all keys from map.

Examples

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

merge(map1, map2)

merge(map, map) :: map

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}

merge(map1, map2, callback)

merge(map, map, (key, value, value -> value)) :: map

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}

new()

new() :: map

Returns a new empty map.

Examples

iex> Map.new
%{}

new(enumerable)

new(Enum.t) :: map

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}

new(enumerable, transform)

new(Enum.t, (term -> {key, value})) :: map

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}

pop(map, key, default \\ nil)

pop(map, key, value) :: {value, map}

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}}

pop_lazy(map, key, fun)

pop_lazy(map, key, (() -> value)) :: {value, map}

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}}

put(map, key, val)

put(map, key, value) :: map

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}

put_new(map, key, value)

put_new(map, key, value) :: map

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}

put_new_lazy(map, key, fun)

put_new_lazy(map, key, (() -> value)) :: map

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}

split(map, keys)

split(map, Enumerable.t) :: {map, map}

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}}

take(map, keys)

take(map, Enumerable.t) :: map

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}

to_list(map)

to_list(map) :: [{term, term}]

Converts map to a list.

Examples

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

update(map, key, initial, fun)

update(map, key, value, (value -> value)) :: map

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}

update!(map, key, fun)

update!(map, key, (value -> value)) :: map | no_return

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

values(map)

values(map) :: [value]

Returns all values from map.

Examples

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