diff options
Diffstat (limited to 'lib/stdlib/doc/src/maps.xml')
| -rw-r--r-- | lib/stdlib/doc/src/maps.xml | 445 |
1 files changed, 445 insertions, 0 deletions
diff --git a/lib/stdlib/doc/src/maps.xml b/lib/stdlib/doc/src/maps.xml new file mode 100644 index 0000000000..e1edbadcd3 --- /dev/null +++ b/lib/stdlib/doc/src/maps.xml @@ -0,0 +1,445 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> + <header> + <copyright> + <year>2013</year><year>2016</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + </legalnotice> + + <title>maps</title> + <prepared>Björn-Egil Dahlberg</prepared> + <docno>1</docno> + <date>2014-02-28</date> + <rev>A</rev> + </header> + <module>maps</module> + <modulesummary>Maps processing functions.</modulesummary> + <description> + <p>This module contains functions for maps processing.</p> + </description> + + <funcs> + <func> + <name name="filter" arity="2"/> + <fsummary>Select pairs that satisfy a predicate.</fsummary> + <desc> + <p>Returns a map <c><anno>Map2</anno></c> for which predicate + <c><anno>Pred</anno></c> holds true in <c><anno>Map1</anno></c>.</p> + <p>The call fails with a <c>{badmap,Map}</c> exception if + <c><anno>Map1</anno></c> is not a map, or with <c>badarg</c> if + <c><anno>Pred</anno></c> is not a function of arity 2.</p> + <p><em>Example:</em></p> + <code type="none"> +> M = #{a => 2, b => 3, c=> 4, "a" => 1, "b" => 2, "c" => 4}, + Pred = fun(K,V) -> is_atom(K) andalso (V rem 2) =:= 0 end, + maps:filter(Pred,M). +#{a => 2,c => 4}</code> + </desc> + </func> + + <func> + <name name="find" arity="2"/> + <fsummary></fsummary> + <desc> + <p>Returns a tuple <c>{ok, Value}</c>, where <c><anno>Value</anno></c> + is the value associated with <c><anno>Key</anno></c>, or <c>error</c> + if no value is associated with <c><anno>Key</anno></c> in + <c><anno>Map</anno></c>.</p> + <p>The call fails with a <c>{badmap,Map}</c> exception if + <c><anno>Map</anno></c> is not a map.</p> + <p><em>Example:</em></p> + <code type="none"> +> Map = #{"hi" => 42}, + Key = "hi", + maps:find(Key,Map). +{ok,42}</code> + </desc> + </func> + + <func> + <name name="fold" arity="3"/> + <fsummary></fsummary> + <desc> + <p>Calls <c>F(K, V, AccIn)</c> for every <c><anno>K</anno></c> to value + <c><anno>V</anno></c> association in <c><anno>Map</anno></c> in + any order. Function <c>fun F/3</c> must return a new + accumulator, which is passed to the next successive call. + This function returns the final value of the accumulator. The initial + accumulator value <c><anno>Init</anno></c> is returned if the map is + empty.</p> + <p><em>Example:</em></p> + <code type="none"> +> Fun = fun(K,V,AccIn) when is_list(K) -> AccIn + V end, + Map = #{"k1" => 1, "k2" => 2, "k3" => 3}, + maps:fold(Fun,0,Map). +6</code> + </desc> + </func> + + <func> + <name name="from_list" arity="1"/> + <fsummary></fsummary> + <desc> + <p>Takes a list of key-value tuples elements and builds a map. The + associations can be in any order, and both keys and values in the + association can be of any term. If the same key appears more than + once, the latter (right-most) value is used and the previous values + are ignored.</p> + <p><em>Example:</em></p> + <code type="none"> +> List = [{"a",ignored},{1337,"value two"},{42,value_three},{"a",1}], + maps:from_list(List). +#{42 => value_three,1337 => "value two","a" => 1}</code> + </desc> + </func> + + <func> + <name name="get" arity="2"/> + <fsummary></fsummary> + <desc> + <p>Returns value <c><anno>Value</anno></c> associated with + <c><anno>Key</anno></c> if <c><anno>Map</anno></c> contains + <c><anno>Key</anno></c>.</p> + <p>The call fails with a <c>{badmap,Map}</c> exception if + <c><anno>Map</anno></c> is not a map, or with a <c>{badkey,Key}</c> + exception if no value is associated with <c><anno>Key</anno></c>.</p> + <p><em>Example:</em></p> + <code type="none"> +> Key = 1337, + Map = #{42 => value_two,1337 => "value one","a" => 1}, + maps:get(Key,Map). +"value one"</code> + </desc> + </func> + + <func> + <name name="get" arity="3"/> + <fsummary></fsummary> + <desc> + <p>Returns value <c><anno>Value</anno></c> associated with + <c><anno>Key</anno></c> if <c><anno>Map</anno></c> contains + <c><anno>Key</anno></c>. If no value is associated with + <c><anno>Key</anno></c>, <c><anno>Default</anno></c> is returned.</p> + <p>The call fails with a <c>{badmap,Map}</c> exception if + <c><anno>Map</anno></c> is not a map.</p> + <p><em>Example:</em></p> + <code type="none"> +> Map = #{ key1 => val1, key2 => val2 }. +#{key1 => val1,key2 => val2} +> maps:get(key1, Map, "Default value"). +val1 +> maps:get(key3, Map, "Default value"). +"Default value"</code> + </desc> + </func> + + <func> + <name name="is_key" arity="2"/> + <fsummary></fsummary> + <desc> + <p>Returns <c>true</c> if map <c><anno>Map</anno></c> contains + <c><anno>Key</anno></c> and returns <c>false</c> if it does not + contain the <c><anno>Key</anno></c>.</p> + <p>The call fails with a <c>{badmap,Map}</c> exception if + <c><anno>Map</anno></c> is not a map.</p> + <p><em>Example:</em></p> + <code type="none"> +> Map = #{"42" => value}. +#{"42"> => value} +> maps:is_key("42",Map). +true +> maps:is_key(value,Map). +false</code> + </desc> + </func> + + <func> + <name name="keys" arity="1"/> + <fsummary></fsummary> + <desc> + <p>Returns a complete list of keys, in any order, which resides + within <c><anno>Map</anno></c>.</p> + <p>The call fails with a <c>{badmap,Map}</c> exception if + <c><anno>Map</anno></c> is not a map.</p> + <p><em>Example:</em></p> + <code type="none"> +> Map = #{42 => value_three,1337 => "value two","a" => 1}, + maps:keys(Map). +[42,1337,"a"]</code> + </desc> + </func> + + <func> + <name name="map" arity="2"/> + <fsummary></fsummary> + <desc> + <p>Produces a new map <c><anno>Map2</anno></c> by calling function + <c>fun F(K, V1)</c> for every <c><anno>K</anno></c> to value + <c><anno>V1</anno></c> association in <c><anno>Map1</anno></c> in + any order. Function <c>fun F/2</c> must return value + <c><anno>V2</anno></c> to be associated with key <c><anno>K</anno></c> + for the new map <c><anno>Map2</anno></c>.</p> + <p><em>Example:</em></p> + <code type="none"> +> Fun = fun(K,V1) when is_list(K) -> V1*2 end, + Map = #{"k1" => 1, "k2" => 2, "k3" => 3}, + maps:map(Fun,Map). +#{"k1" => 2,"k2" => 4,"k3" => 6}</code> + </desc> + </func> + + <func> + <name name="merge" arity="2"/> + <fsummary></fsummary> + <desc> + <p>Merges two maps into a single map <c><anno>Map3</anno></c>. If two + keys exist in both maps, the value in <c><anno>Map1</anno></c> is + superseded by the value in <c><anno>Map2</anno></c>.</p> + <p>The call fails with a <c>{badmap,Map}</c> exception if + <c><anno>Map1</anno></c> or <c><anno>Map2</anno></c> is not a map.</p> + <p><em>Example:</em></p> + <code type="none"> +> Map1 = #{a => "value_one", b => "value_two"}, + Map2 = #{a => 1, c => 2}, + maps:merge(Map1,Map2). +#{a => 1,b => "value_two",c => 2}</code> + </desc> + </func> + + <func> + <name name="new" arity="0"/> + <fsummary></fsummary> + <desc> + <p>Returns a new empty map.</p> + <p><em>Example:</em></p> + <code type="none"> +> maps:new(). +#{}</code> + </desc> + </func> + + <func> + <name name="put" arity="3"/> + <fsummary></fsummary> + <desc> + <p>Associates <c><anno>Key</anno></c> with value + <c><anno>Value</anno></c> and inserts the association into map + <c>Map2</c>. If key <c><anno>Key</anno></c> already exists in map + <c><anno>Map1</anno></c>, the old associated value is replaced by + value <c><anno>Value</anno></c>. The function returns a new map + <c><anno>Map2</anno></c> containing the new association and the old + associations in <c><anno>Map1</anno></c>.</p> + <p>The call fails with a <c>{badmap,Map}</c> exception if + <c><anno>Map1</anno></c> is not a map.</p> + <p><em>Example:</em></p> + <code type="none"> +> Map = #{"a" => 1}. +#{"a" => 1} +> maps:put("a", 42, Map). +#{"a" => 42} +> maps:put("b", 1337, Map). +#{"a" => 1,"b" => 1337}</code> + </desc> + </func> + + <func> + <name name="remove" arity="2"/> + <fsummary></fsummary> + <desc> + <p>Removes the <c><anno>Key</anno></c>, if it exists, and its + associated value from <c><anno>Map1</anno></c> and returns a new map + <c><anno>Map2</anno></c> without key <c><anno>Key</anno></c>.</p> + <p>The call fails with a <c>{badmap,Map}</c> exception if + <c><anno>Map1</anno></c> is not a map.</p> + <p><em>Example:</em></p> + <code type="none"> +> Map = #{"a" => 1}. +#{"a" => 1} +> maps:remove("a",Map). +#{} +> maps:remove("b",Map). +#{"a" => 1}</code> + </desc> + </func> + + <func> + <name name="size" arity="1"/> + <fsummary></fsummary> + <desc> + <p>Returns the number of key-value associations in + <c><anno>Map</anno></c>. This operation occurs in constant time.</p> + <p><em>Example:</em></p> + <code type="none"> +> Map = #{42 => value_two,1337 => "value one","a" => 1}, + maps:size(Map). +3</code> + </desc> + </func> + + <func> + <name name="take" arity="2"/> + <fsummary></fsummary> + <desc> + <p>The function removes the <c><anno>Key</anno></c>, if it + exists, and its associated value from <c><anno>Map1</anno></c> + and returns a tuple with the removed <c><anno>Value</anno></c> + and the new map <c><anno>Map2</anno></c> without key + <c><anno>Key</anno></c>. If the key does not exist + <c>error</c> is returned. + </p> + <p>The call will fail with a <c>{badmap,Map}</c> exception if + <c><anno>Map1</anno></c> is not a map. + </p> + <p>Example:</p> + <code type="none"> +> Map = #{"a" => "hello", "b" => "world"}. +#{"a" => "hello", "b" => "world"} +> maps:take("a",Map). +{"hello",#{"b" => "world"}} +> maps:take("does not exist",Map). +error</code> + </desc> + </func> + + <func> + <name name="to_list" arity="1"/> + <fsummary></fsummary> + <desc> + <p>Returns a list of pairs representing the key-value associations of + <c><anno>Map</anno></c>, where the pairs + <c>[{K1,V1}, ..., {Kn,Vn}]</c> are returned in arbitrary order.</p> + <p>The call fails with a <c>{badmap,Map}</c> exception if + <c><anno>Map</anno></c> is not a map.</p> + <p><em>Example:</em></p> + <code type="none"> +> Map = #{42 => value_three,1337 => "value two","a" => 1}, + maps:to_list(Map). +[{42,value_three},{1337,"value two"},{"a",1}]</code> + </desc> + </func> + + <func> + <name name="update" arity="3"/> + <fsummary></fsummary> + <desc> + <p>If <c><anno>Key</anno></c> exists in <c><anno>Map1</anno></c>, the + old associated value is replaced by value <c><anno>Value</anno></c>. + The function returns a new map <c><anno>Map2</anno></c> containing + the new associated value.</p> + <p>The call fails with a <c>{badmap,Map}</c> exception if + <c><anno>Map1</anno></c> is not a map, or with a <c>{badkey,Key}</c> + exception if no value is associated with <c><anno>Key</anno></c>.</p> + <p><em>Example:</em></p> + <code type="none"> +> Map = #{"a" => 1}. +#{"a" => 1} +> maps:update("a", 42, Map). +#{"a" => 42}</code> + </desc> + </func> + + <func> + <name name="update_with" arity="3"/> + <fsummary></fsummary> + <desc> + <p>Update a value in a <c><anno>Map1</anno></c> associated + with <c><anno>Key</anno></c> by calling + <c><anno>Fun</anno></c> on the old value to get a new + value. An exception <c>{badkey,<anno>Key</anno>}</c> is + generated if <c><anno>Key</anno></c> is not present in the + map.</p> + <p>Example:</p> + <code type="none"> +> Map = #{"counter" => 1}, + Fun = fun(V) -> V + 1 end, + maps:update_with("counter",Fun,Map). +#{"counter" => 2}</code> + </desc> + </func> + + <func> + <name name="update_with" arity="4"/> + <fsummary></fsummary> + <desc> + <p>Update a value in a <c><anno>Map1</anno></c> associated + with <c><anno>Key</anno></c> by calling + <c><anno>Fun</anno></c> on the old value to get a new value. + If <c><anno>Key</anno></c> is not present in + <c><anno>Map1</anno></c> then <c><anno>Init</anno></c> will be + associated with <c><anno>Key</anno></c>. + </p> + <p>Example:</p> + <code type="none"> +> Map = #{"counter" => 1}, + Fun = fun(V) -> V + 1 end, + maps:update_with("new counter",Fun,42,Map). +#{"counter" => 1,"new counter" => 42}</code> + </desc> + </func> + + <func> + <name name="values" arity="1"/> + <fsummary></fsummary> + <desc> + <p>Returns a complete list of values, in arbitrary order, contained in + map <c>Map</c>.</p> + <p>The call fails with a <c>{badmap,Map}</c> exception if + <c><anno>Map</anno></c> is not a map.</p> + <p><em>Example:</em></p> + <code type="none"> +> Map = #{42 => value_three,1337 => "value two","a" => 1}, + maps:values(Map). +[value_three,"value two",1]</code> + </desc> + </func> + + <func> + <name name="with" arity="2"/> + <fsummary></fsummary> + <desc> + <p>Returns a new map <c><anno>Map2</anno></c> with the keys <c>K1</c> + through <c>Kn</c> and their associated values from map + <c><anno>Map1</anno></c>. Any key in <c><anno>Ks</anno></c> that does + not exist in <c><anno>Map1</anno></c> is ignored.</p> + <p><em>Example:</em></p> + <code type="none"> +> Map = #{42 => value_three,1337 => "value two","a" => 1}, + Ks = ["a",42,"other key"], + maps:with(Ks,Map). +#{42 => value_three,"a" => 1}</code> + </desc> + </func> + + <func> + <name name="without" arity="2"/> + <fsummary></fsummary> + <desc> + <p>Returns a new map <c><anno>Map2</anno></c> without keys <c>K1</c> + through <c>Kn</c> and their associated values from map + <c><anno>Map1</anno></c>. Any key in <c><anno>Ks</anno></c> that does + not exist in <c><anno>Map1</anno></c> is ignored</p> + <p><em>Example:</em></p> + <code type="none"> +> Map = #{42 => value_three,1337 => "value two","a" => 1}, + Ks = ["a",42,"other key"], + maps:without(Ks,Map). +#{1337 => "value two"}</code> + </desc> + </func> + </funcs> +</erlref> |