Module maps

A naive implementation of the Erlang/OTP maps interface.

Description

The maps module provides several convenience operations for interfacing with the Erlang map type, which associates (unique) keys with values.

Note that the ordering of entries in a map is implementation-defined. While many operations in this module present entries in lexical order, users should in general make no assumptions about the ordering of entries in a map.

This module implements a subset of the Erlang/OTP maps interface. Some OTP functions are not implemented, and the approach favors correctness and readability over speed and performance.

Data Types

iterator()


iterator() = iterator(Key::any(), Value::any())

iterator()

abstract datatype: iterator(Key, Value)

iterator_order()


iterator_order() = iterator_order(Key::term())

iterator_order()


iterator_order(Key) = undefined | ordered | reversed | fun((Key, Key) -> boolean())

map_or_iterator()


map_or_iterator(Key, Value) = #{Key => Value} | iterator(Key, Value)

Function Index

filter/2Return a map who's entries are filtered by the supplied predicate.
find/2Returns {ok, Value} if Key is in Map; error, otherwise.
fold/3Fold over the entries in a map.
foreach/2Iterate over the entries in a map.
from_keys/2Creates a map with specified keys intialized to given value.
from_list/1This function constructs a map from the supplied list of key-value pairs.
get/2 Get the value in Map associated with Key, if it exists.
get/3 Get the value in Map associated with Key, or Default, if the key is not associated with a value in Map.
is_key/2 Return true if Key is associated with a value in Map; false, otherwise.
iterator/1Equivalent to iterator(Map, undefined).
iterator/2Return an iterator structure that can be used to iterate over associations in a map.
keys/1Returns the list of keys that occur in this map.
map/2Returns the result of applying a function to every element of a map.
merge/2Merge two maps to yield a new map.
merge_with/3Merge two maps to yield a new map.
new/0Return a new (empty) map.
next/1Returns the next key and value in the map, along with a new iterator that can be used to iterate over the remainder of the map.
put/3 Return the map containing the {Key, Value} association.
remove/2Remove an entry from a map using a key.
size/1Returns the size of (i.e., the number of entries in) the map.
to_list/1Return the list of entries, expressed as {Key, Value} pairs, in the supplied map.
update/3Returns a new map with an updated key-value association.
values/1Returns the list of values that occur in this map.

Function Details

filter/2


filter(Pred::fun((Key, Value) -> boolean()), MapOrIterator::map_or_iterator(Key, Value)) -> #{Key => Value}

Pred: a function used to filter entries from the map
MapOrIterator: the map or map iterator to filter

returns: a map containing all elements in MapOrIterator that satisfy Pred

Return a map who’s entries are filtered by the supplied predicate.

This function returns a new map containing all elements from the input MapOrIterator that satisfy the input Pred.

The supplied predicate is a function from key-value inputs to a boolean value.

This function raises a {badmap, Map} error if Map is not a map or map iterator, and a badarg error if the input predicate is not a function.

find/2


find(Key, Map::#{Key => Value}) -> {ok, Value} | error

Key: the key to find
Map: the map in which to search

returns: {ok, Value} if Key is in Map; error, otherwise.

Returns {ok, Value} if Key is in Map; error, otherwise.

This function raises a {badmap, Map} error if Map is not a map.

fold/3


fold(Fun::fun((Key, Value, Accum) -> Accum), Accum, MapOrIterator::map_or_iterator(Key, Value)) -> Accum

Fun: function over which to fold values
MapOrIterator: the map or map iterator over which to fold

returns: the result of folding over all elements of the supplied map.

Fold over the entries in a map.

This function takes a function used to fold over all entries in a map and an initial accumulator value to use as the value supplied to the first entry in the map.

This function raises a badmap error if Map is not a map or map iterator, and a badarg error if the input function is not a function.

foreach/2


foreach(Fun::fun((Key, Value) -> any()), MapOrIterator::map_or_iterator(Key, Value)) -> ok

Fun: function to call with every key-value pair
MapOrIterator: the map or map iterator over which to iterate

returns: ok

Iterate over the entries in a map.

This function takes a function used to iterate over all entries in a map.

This function raises a badmap error if Map is not a map or map iterator, and a badarg error if the input function is not a function.

from_keys/2


from_keys(List::list(), Value::term()) -> map()

List: the list of keys of the map that will be created
Value: the value that will be used as value for all map items

returns: a map having all provided keys having provided value as value

Creates a map with specified keys intialized to given value

from_list/1


from_list(List::[{Key, Value}]) -> #{Key => Value}

List: a list of [{Key, Value}] pairs

returns: the map containing the entries from the list of supplied key-value pairs.

This function constructs a map from the supplied list of key-value pairs.

If the input list contains duplicate keys, the returned map will contain the right-most entry.

This function will raise a badarg error if the input is not a proper list or contains an element that is not a key-value pair.

get/2


get(Key, Map::#{Key => Value}) -> Value

Key: the key to get
Map: the map from which to get the value

returns: the value in Map associated with Key, if it exists.

Get the value in Map associated with Key, if it exists.

This function raises a {badkey, Key} error if ‘Key’ does not occur in Map or a {badmap, Map} error if Map is not a map.

get/3


get(Key, Map::#{Key => Value}, Default::Value) -> Value

Key: the key
Map: the map
Default: default value

returns: the value in Map associated with Key, or Default, if the key is not associated with a value in Map.

Get the value in Map associated with Key, or Default, if the key is not associated with a value in Map.

This function raises a {badmap, Map} error if Map is not a map.

is_key/2


is_key(Key, Map::#{Key => _Value}) -> boolean()

Key: the key
Map: the map

returns: true if Key is associated with a value in Map; false, otherwise.

Return true if Key is associated with a value in Map; false, otherwise.

This function raises a {badmap, Map} error if Map is not a map.

iterator/1


iterator(Map::#{Key => Value}) -> iterator(Key, Value)

Equivalent to iterator(Map, undefined).

iterator/2


iterator(Map::#{Key => Value}, Order::iterator_order()) -> iterator(Key, Value)

Map: the map
Order: the iterator order, or undefined for default (unspecified) order.

returns: an iterator structure that can be used to iterate over associations in a map.

Return an iterator structure that can be used to iterate over associations in a map.

This function raises a {badmap, Map} error if Map is not a map.

See also: next/1.

keys/1


keys(Map::#{Key => _Value}) -> [Key]

Map: the map

returns: the list of keys that occur in this map.

Returns the list of keys that occur in this map.

No guarantees are provided about the order of keys returned from this function.

This function raises a {badmap, Map} error if Map is not a map.

map/2


map(Fun::fun((Key, Value) -> MappedValue), Map::map_or_iterator(Key, Value)) -> #{Key => MappedValue}

Fun: the function to apply to every entry in the map
Map: the map to which to apply the map function

returns: the result of applying Fun to every entry in Map

Returns the result of applying a function to every element of a map.

This function raises a badmap error if Map is not a map or map iterator, and a badarg error if the input function is not a function.

merge/2


merge(Map1::#{Key => Value}, Map2::#{Key => Value}) -> #{Key => Value}

Map1: a map
Map2: a map

returns: the result of merging entries from Map1 and Map2.

Merge two maps to yield a new map.

If Map1 and Map2 contain the same key, then the value from Map2 will be used.

This function raises a badmap error if neither Map1 nor Map2 is a map.

merge_with/3


merge_with(Combiner::fun((Key, Value, Value) -> Value), Map1::#{Key => Value}, Map2::#{Key => Value}) -> #{Key => Value}

Combiner: a function to merge values from Map1 and Map2 if a key exists in both maps
Map1: a map
Map2: a map

returns: the result of merging entries from Map1 and Map2.

Merge two maps to yield a new map.

If Map1 and Map2 contain the same key, then the value from Combiner(Key, Value1, Value2) will be used.

This function raises a badmap error if neither Map1 nor Map2 is a map.

new/0


new() -> map()

returns: a new map

Return a new (empty) map.

next/1


next(Iterator::iterator(Key, Value)) -> {Key, Value, iterator(Key, Value)} | none

Iterator: a map iterator

returns: the key and value, along with the next iterator in the map, or the atom none if there are no more items over which to iterate.

Returns the next key and value in the map, along with a new iterator that can be used to iterate over the remainder of the map.

This function raises a badarg error if the supplied iterator is not of the expected type. Only use iterators that are returned from functions in this module.

put/3


put(Key, Value, Map::#{Key => Value}) -> #{Key => Value}

Key: the key
Value: the value
Map: the map

returns: A copy of Map containing the {Key, Value} association.

Return the map containing the {Key, Value} association.

If Key occurs in Map then it will be over-written. Otherwise, the returned map will contain the new association.

This function raises a {badmap, Map} error if Map is not a map.

remove/2


remove(Key, MapOrIterator::map_or_iterator(Key, Value)) -> #{Key => Value}

Key: the key to remove
MapOrIterator: the map or map iterator from which to remove the key

returns: a new map without Key as an entry.

Remove an entry from a map using a key.

If Key does not occur in Map, then the returned Map has the same entries as the input map or map iterator.

Note. This function extends the functionality of the OTP remove/2 function, since the OTP interface only takes a map as input.

This function raises a badmap error if Map is not a map or map iterator.

size/1


size(Map::map()) -> non_neg_integer()

Map: the map

returns: the size of the map

Returns the size of (i.e., the number of entries in) the map

This function raises a {badmap, Map} error if Map is not a map.

to_list/1


to_list(Map::#{Key => Value}) -> [{Key, Value}]

returns: a list of [{Key, Value}] tuples

Return the list of entries, expressed as {Key, Value} pairs, in the supplied map.

If provided with a map, no guarantees are provided about the order of entries returned from this function. Order can be controlled with iterator/2

This function raises a {badmap, Map} error if Map is not a map and not an iterator.

update/3


update(Key, Value, Map::#{Key => Value}) -> #{Key => Value}

Key: the key to update
Value: the value to update
Map: the map to update

returns: a new map, with Key updated with Value

Returns a new map with an updated key-value association.

This function raises a badmap error if Map is not a map and {badkey, Key} if key doesn`t exist

values/1


values(Map::#{_Key => Value}) -> [Value]

Map: the map

returns: the list of values that occur in this map.

Returns the list of values that occur in this map.

No guarantees are provided about the order of values returned from this function.

This function raises a {badmap, Map} error if Map is not a map.