Elixir v1.3.0-rc.0 Map View Source

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.

Link to this section Summary

Functions

Deletes the entries in map for a specific key

Drops the given keys from map

Checks if two maps are equal

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

Fetches the value for specific key

Converts a struct to map

Gets the value for a specific key

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

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

Gets the value for a specific key

Returns whether a given key exists in the given map

Returns all keys from map

Merges two maps into one

Merges two maps into one

Returns a new empty map

Creates a map from an enumerable

Creates a map from an enumerable via the transformation function

Returns and removes the value associated with key in map

Lazily returns and removes the value associated with key in map

Puts the given value under key

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

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

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

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

Converts map to a list

Updates the key in map with the given function

Updates the key with the given function

Returns all values from map

Link to this section Types

Link to this section Functions

Link to this function delete(map, key) View Source
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}
Link to this function drop(map, keys) View Source
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}
Link to this function equal?(map1, map2) View Source
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
Link to this function fetch(map, key) View Source
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
Link to this function fetch!(map, key) View Source
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}
Link to this function from_struct(struct) View Source
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"}
Link to this function get(map, key, default \\ nil) View Source
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
Link to this function get_and_update(map, key, fun) View Source
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}}
Link to this function get_and_update!(map, key, fun) View Source
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, %{}}
Link to this function get_lazy(map, key, fun) View Source
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
Link to this function has_key?(map, key) View Source
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

Returns all keys from map.

Examples

iex> Map.keys(%{a: 1, b: 2})
[:a, :b]
Link to this function merge(map1, map2) View Source
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}
Link to this function merge(map1, map2, callback) View Source
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}

Returns a new empty map.

Examples

iex> Map.new
%{}
Link to this function new(enumerable) View Source
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}
Link to this function new(enumerable, transform) View Source
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}
Link to this function pop(map, key, default \\ nil) View Source
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}}
Link to this function pop_lazy(map, key, fun) View Source
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}}
Link to this function put(map, key, val) View Source
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}
Link to this function put_new(map, key, value) View Source
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}
Link to this function put_new_lazy(map, key, fun) View Source
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}
Link to this function split(map, keys) View Source
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}}
Link to this function take(map, keys) View Source
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}
Link to this function to_list(map) View Source
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}]
Link to this function update(map, key, initial, fun) View Source
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}
Link to this function update!(map, key, fun) View Source
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
Link to this function values(map) View Source
values(map) :: [value]

Returns all values from map.

Examples

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