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() = {key(), value(), iterator()} | none | nonempty_improper_list(non_neg_integer(), map())

key()


key() = term()

map_or_iterator()


map_or_iterator() = map() | iterator()

value()


value() = term()

Function Index

filter/2	Return a map who's entries are filtered by the supplied predicate.
find/2	Returns `{ok, Value}` if `Key` is in `Map`; `error`, otherwise.
fold/3	Fold over the entries in a map.
from_list/1	This 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/1	Return an iterator structure that can be used to iterate over associations in a map.
keys/1	Returns the list of keys that occur in this map.
map/2	Returns the result of applying a function to every element of a map.
merge/2	Merge two maps to yield a new map.
new/0	Return a new (empty) map.
next/1	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.
put/3	Return the map containing the `{Key, Value}` association.
remove/2	Remove an entry from a map using a key.
size/1	Returns the size of (i.e., the number of entries in) the map.
to_list/1	Return the list of entries, expressed as `{Key, Value}` pairs, in the supplied map.
update/3	Returns a new map with an updated key-value association.
values/1	Returns the list of values that occur in this map.

Function Details

filter/2


filter(Pred::fun((Key::key(), Value::value()) -> boolean()), MapOrIterator::map_or_iterator()) -> map()

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

throws {badmap, Map} | badarg

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 throws a {badmap, Map} exception if Map is not a map or map iterator, and a badarg exception if the input predicate is not a function.

find/2


find(Key::key(), Map::map()) -> {ok, Value::value()} | error

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

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

throws {badmap, Map}

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

This function throws a {badmap, Map} exception if Map is not a map.

fold/3


fold(Fun::fun((Key::key(), Value::value(), Accum::term()) -> term()), Init::term(), MapOrIterator::map_or_iterator()) -> term()

Fun: function over which to fold values
Init: the initial value of the fold accumulator
MapOrIterator: the map or map iterator over which to fold

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

throws {badmap, Map} | badarg

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 throws a badmap exception if Map is not a map or map iterator, and a badarg exception if the input function is not a function.

from_list/1


from_list(List::[{Key::key(), Value::value()}]) -> map()

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

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

throws badarg

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 exception if the input is not a proper list or contains an element that is not a key-value pair.

get/2


get(Key::key(), Map::map()) -> 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.

throws {badkey, Key} | {badmap, Map}

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

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

get/3


get(Key::key(), Map::map(), Default::term()) -> 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.

throws {badmap, Map}

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

This function throws a {badmap, Map} exception if Map is not a map.

is_key/2


is_key(Key::key(), Map::map()) -> boolean()

Key: the key
Map: the map

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

throws {badmap, Map}

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

This function throws a {badmap, Map} exception if Map is not a map.

iterator/1


iterator(Map::map()) -> iterator()

Map: the map

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

throws {badmap, Map}

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

In general, users should make no assumptions about the order in which entries appear in an iterator. The order of entries in a map is implementation-defined.

This function throws a {badmap, Map} exception if Map is not a map.

See also: next/1.

keys/1


keys(Map::map()) -> [key()]

Map: the map

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

throws {badmap, 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 throws a {badmap, Map} exception if Map is not a map.

map/2


map(Fun::fun((Key::key(), Value::value()) -> value()), Map::map_or_iterator()) -> map()

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

throws {badmap, Map} | badarg

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

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

merge/2


merge(Map1::map(), Map2::map()) -> map()

Map1: a map
Map2: a mpa

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

throws {badmap, Map}

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 throws a badmap exception if neither Map1 nor Map2 is a map.

new/0


new() -> iterator()

returns: a new map

Return a new (empty) map.

next/1


next(Iterator::iterator()) -> {Key::key(), Value::value(), NextIterator::iterator()} | 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.

throws badarg

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 throws a badarg exception 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::key(), Value::value(), Map::map()) -> map()

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

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

throws {badmap, Map}

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 throws a {badmap, Map} exception if Map is not a map.

remove/2


remove(Key::key(), MapOrIterator::map_or_iterator()) -> map()

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.

throws {badmap, Map}

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 throws a badmap exception 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

throws {badmap, Map}

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

This function throws a {badmap, Map} exception if Map is not a map.

to_list/1


to_list(Map::map()) -> [key()]

Map: the map

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

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

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

This function throws a {badmap, Map} exception if Map is not a map.

update/3


update(Key::key(), Value::value(), Map::map()) -> map()

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

returns: a new map, with Key updated with Value

throws {badmap, Map}

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

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

values/1


values(Map::map()) -> [key()]

Map: the map

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

throws {badmap, 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 throws a {badmap, Map} exception if Map is not a map.