Map
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
Functions
- delete(map, key)
-
Deletes the entries in
map
for a specifickey
- drop(map, keys)
-
Drops the given
keys
frommap
- 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 nokey
- get_lazy(map, key, fun)
-
Gets the value for a specific
key
- has_key?(map, key)
-
Returns whether a given
key
exists in the givenmap
- 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
inmap
- pop_lazy(map, key, fun)
-
Lazily returns and removes the value associated with
key
inmap
- put(map, key, val)
-
Puts the given
value
underkey
- put_new(map, key, value)
-
Puts the given
value
underkey
unless the entrykey
already exists - put_new_lazy(map, key, fun)
-
Evaluates
fun
and puts the result underkey
in map unlesskey
is already present - split(map, keys)
-
Takes all entries corresponding to the given
keys
and extracts them into a separatemap
- 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
inmap
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]
© 2012–2017 Plataformatec
Licensed under the Apache License, Version 2.0.
https://hexdocs.pm/elixir/1.3.4/Map.html