-spec deep_find(path(), map()) -> {ok, term()} | error.

Returns a tuple {ok,Value}, where Value is the value associated with Path, or error if no value is associated with Path in Map.

The call can raise the following exceptions:

• {badmap,Map} if Map is not a map
• {badpath,Path} if Path is not a path

-spec deep_get(path(), map()) -> term().

Returns value Value associated with Path if Map contains Path.

The call can raise the following exceptions:

• {badmap,Map} if Map is not a map
• {badpath,Path} if Path is not a path
• {badvalue,P} if a term that is not a map exists as a intermediate key at the path P
• {badkey,Path} if no value is associated with path Path

-spec deep_get(path(), map(), term()) -> term().

Returns value Value associated with Path if Map contains Path. If no value is associated with Path, Default is returned.

The call can raise the following exceptions:

• {badmap,Map} if Map is not a map
• {badpath,Path} if Path is not a path
• {badvalue,P} if a term that is not a map exists as a intermediate key at the path P

-spec deep_intersect(Map1 :: map(), Map2 :: map()) -> Map3 :: map().

Intersects two maps into a single map Map3.

If a path exists in both maps, the value in Map1 is superseded by the value in Map2.

That is, deep_intersect/2 behaves as if it had been defined as follows:

deep_intersect(A, B) ->
    deep_intersect_with(fun(_Path, _V1, V2) -> V2 end, A, B).copy

The call can raise the following exceptions:

• {badmap,Map} exception if any of the maps is not a map

-spec deep_intersect_with(Fun :: combiner(), Map1 :: map(), Map2 :: map()) -> Map3 :: map().

Intersects two maps into a single map Map3.

If a path exists in both maps, the value in Map1 is combined with the value in Map2 by the Combiner fun. When Combiner is applied the path that exists in both maps is the first parameter, the value from Map1 is the second parameter, and the value from Map2 is the third parameter.

The call can raise the following exceptions:

• {badmap,Map} exception if any of the maps is not a map
• badarg if Fun is not a function of arity 3

-spec deep_iterator(map()) -> iterator().

Returns a map iterator Iterator that can be used by deep_next/1 to recursively traverse the path-value associations in a deep map structure.

The call fails with a {badmap,Map} exception if Map is not a map.

-spec deep_merge([map()]) -> map().

Merges a list of maps recursively into a single map.

If a path exist in several maps, the value in the first nested map is superseded by the value in a following nested map.

That is, deep_merge/2 behaves as if it had been defined as follows:

deep_merge(Maps) when is_list(Maps) ->
    deep_merge_with(fun(_Path, _V1, V2) -> V2 end, Maps).copy

The call can raise the following exceptions:

• {badmap,Map} exception if any of the maps is not a map

-spec deep_merge(map(), map()) -> map().

Equivalent to deep_merge([Map1, Map2]).

-spec deep_merge(fun((Old :: term(), New :: term()) -> term()), map(), map() | [map()]) -> map().

Merges a list of maps Maps recursively into a single map Target.

If a path exist in several maps, the function Fun is called with the previous and the conflicting value to resolve the conflict. The return value from the function is put into the resulting map.

The call can raise the following exceptions:

• {badmap,Map} exception if any of the maps is not a map

-spec deep_merge_with(Fun :: combiner(), Maps :: [map()]) -> map().

Merges a list of maps Maps recursively into a single map.

If a path exist in several maps, the function Fun is called with the path, the previous and the conflicting value to resolve the conflict. The return value from the function is put into the resulting map.

The call can raise the following exceptions:

• {badmap,Map} exception if any of the maps is not a map
• badarg if Fun is not a function of arity 3

-spec deep_merge_with(Fun :: combiner(), Map1 :: map(), Map2 :: map()) -> map().

Merges a list of maps Maps recursively into a single map.

If a path exist in several maps, the function Fun is called with the path, the previous and the conflicting value to resolve the conflict. The return value from the function is put into the resulting map.

The call can raise the following exceptions:

• {badmap,Map} exception if any of the maps is not a map

-spec deep_next(iterator()) -> {path(), term(), iterator()} | none.

Returns the next path-value association in Iterator and a new iterator for the remaining associations in the iterator.

If the value is anogher map the iterator will first return the map as a value with its path. Only on the next call the inner value with its path is returned. That is, first {Path, map(), iterator()} and then {InnerPath, Value, iterator()}.

If there are no more associations in the iterator, none is returned.

-spec deep_put(path(), term(), map()) -> map().

Associates Path with value Value and inserts the association into map Map2. If path Path already exists in map Map1, the old associated value is replaced by value Value. The function returns a new map Map2 containing the new association and the old associations in Map1.

The call can raise the following exceptions:

• {badmap,Map} if Map1 is not a map
• {badpath,Path} if Path is not a path
• {badvalue,P} if a term that is not a map exists as a intermediate key at the path P

-spec deep_remove(path(), map()) -> map().

Removes the last existing key of Path, and its associated value from Map1 and returns a new map Map2 without that key. Any deeper non-existing keys are ignored.

The call can raise the following exceptions:

• {badmap,Map} if Map is not a map
• {badpath,Path} if Path is not a path

Returns a tuple {ok,Value} where Value is the value associated with Path, or {error, PartialPath, Value} if no value is associated with Path in Map, where PartialPath represents the path to the last found element in Map and Value is the value found at that path.

When no key in Path exists in Map, {error, [], Map} is returned.

The call can raise the following exceptions:

• {badmap,Map} if Map is not a map
• {badpath,Path} if Path is not a path

-spec deep_update(path(), term(), map()) -> map().

If Path exists in Map1, the old associated value is replaced by value Value. The function returns a new map Map2 containing the new associated value.

The call can raise the following exceptions:

• {badmap,Map} if Map1 is not a map
• {badpath,Path} if Path is not a path
• {badvalue,P} if a term that is not a map exists as a intermediate key at the path P
• {badkey,Path} if no value is associated with path Path

-spec deep_update_with(path(), fun((term()) -> term()), map()) -> map().

Update a value in a Map1 associated with Path by calling Fun on the old value to get a new value.

The call can raise the following exceptions:

• {badmap,Map} if Map1 is not a map
• {badpath,Path} if Path is not a path
• {badvalue,P} if a term that is not a map exists as a intermediate key at the path P
• {badkey,Path} if no value is associated with path Path
• badarg if Fun is not a function of arity 1

-spec deep_update_with(path(), fun((term()) -> term()), any(), map()) -> map().

Update a value in a Map1 associated with Path by calling Fun on the old value to get a new value. If Path is not present in Map1 then Init will be associated with Path.

The call can raise the following exceptions:

• {badmap,Map} if Map1 is not a map
• {badpath,Path} if Path is not a path
• {badvalue,P} if a term that is not a map exists as a intermediate key at the path P
• badarg if Fun is not a function of arity 1

-spec inverse(map()) -> map().

Inverts a map by inserting each value as the key with its corresponding key as the value. If two keys have the same value, the value for the first key in map order will take precedence.

That is, inverse/1 behaves as if it had been defined as follows:

inverse(Map) -> inverse(Map, fun(Old, _New) -> Old end).copy

The call can raise the following exceptions:

• {badmap,Map} if Map is not a map

-spec inverse(map(), fun((Old :: term(), New :: term()) -> term())) -> map().

Inverts a map by inserting each value as the key with its corresponding key as the value. If two keys have the same value in Map, Fun is called with the old and new key to determine the resulting value.

The call can raise the following exceptions:

• {badmap,Map} if Map is not a map
• badarg if Fun is not a function of arity 2