diff options
Diffstat (limited to 'lib/stdlib/doc/src/maps.xml')
| -rw-r--r-- | lib/stdlib/doc/src/maps.xml | 142 |
1 files changed, 110 insertions, 32 deletions
diff --git a/lib/stdlib/doc/src/maps.xml b/lib/stdlib/doc/src/maps.xml index 8c7270816b..e2a62cb397 100644 --- a/lib/stdlib/doc/src/maps.xml +++ b/lib/stdlib/doc/src/maps.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>2013</year><year>2016</year> + <year>2013</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -27,22 +27,37 @@ <date>2014-02-28</date> <rev>A</rev> </header> - <module>maps</module> + <module since="OTP 17.0">maps</module> <modulesummary>Maps processing functions.</modulesummary> <description> <p>This module contains functions for maps processing.</p> </description> + <datatypes> + <datatype> + <name name="iterator"/> + <desc> + <p>An iterator representing the key value associations in a map.</p> + <p>Created using <seealso marker="#iterator-1"><c>maps:iterator/1</c></seealso>.</p> + <p>Consumed by <seealso marker="#next-1"><c>maps:next/1</c></seealso>, + <seealso marker="#filter-2"><c>maps:filter/2</c></seealso>, + <seealso marker="#fold-3"><c>maps:fold/3</c></seealso> and + <seealso marker="#map-2"><c>maps:map/2</c></seealso>.</p> + </desc> + </datatype> + </datatypes> + <funcs> <func> - <name name="filter" arity="2"/> + <name name="filter" arity="2" since="OTP 18.0"/> <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>Returns a map <c><anno>Map</anno></c> for which predicate + <c><anno>Pred</anno></c> holds true in <c><anno>MapOrIter</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> + <c><anno>MapOrIter</anno></c> is not a map or valid iterator, + 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}, @@ -53,7 +68,7 @@ </func> <func> - <name name="find" arity="2"/> + <name name="find" arity="2" since="OTP 17.0"/> <fsummary></fsummary> <desc> <p>Returns a tuple <c>{ok, Value}</c>, where <c><anno>Value</anno></c> @@ -72,16 +87,20 @@ </func> <func> - <name name="fold" arity="3"/> + <name name="fold" arity="3" since="OTP 17.0"/> <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 + <c><anno>V</anno></c> association in <c><anno>MapOrIter</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>The call fails with a <c>{badmap,Map}</c> exception if + <c><anno>MapOrIter</anno></c> is not a map or valid iterator, + or with <c>badarg</c> if <c><anno>Fun</anno></c> is not a + function of arity 3.</p> <p><em>Example:</em></p> <code type="none"> > Fun = fun(K,V,AccIn) when is_list(K) -> AccIn + V end, @@ -92,7 +111,7 @@ </func> <func> - <name name="from_list" arity="1"/> + <name name="from_list" arity="1" since="OTP 17.0"/> <fsummary></fsummary> <desc> <p>Takes a list of key-value tuples elements and builds a map. The @@ -109,7 +128,7 @@ </func> <func> - <name name="get" arity="2"/> + <name name="get" arity="2" since="OTP 17.0"/> <fsummary></fsummary> <desc> <p>Returns value <c><anno>Value</anno></c> associated with @@ -128,7 +147,7 @@ </func> <func> - <name name="get" arity="3"/> + <name name="get" arity="3" since="OTP 17.1"/> <fsummary></fsummary> <desc> <p>Returns value <c><anno>Value</anno></c> associated with @@ -149,7 +168,7 @@ val1 </func> <func> - <name name="is_key" arity="2"/> + <name name="is_key" arity="2" since="OTP 17.0"/> <fsummary></fsummary> <desc> <p>Returns <c>true</c> if map <c><anno>Map</anno></c> contains @@ -169,7 +188,33 @@ false</code> </func> <func> - <name name="keys" arity="1"/> + <name name="iterator" arity="1" since="OTP 21.0"/> + <fsummary>Create a map iterator.</fsummary> + <desc> + <p>Returns a map iterator <c><anno>Iterator</anno></c> that can + be used by <seealso marker="#next-1"><c>maps:next/1</c></seealso> + to traverse the key-value associations in a map. When iterating + over a map, the memory usage is guaranteed to be bounded no matter + the size of the map.</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"> +> M = #{ a => 1, b => 2 }. +#{a => 1,b => 2} +> I = maps:iterator(M), ok. +ok +> {K1, V1, I2} = maps:next(I), {K1, V1}. +{a,1} +> {K2, V2, I3} = maps:next(I2),{K2, V2}. +{b,2} +> maps:next(I3). +none</code> + </desc> + </func> + + <func> + <name name="keys" arity="1" since="OTP 17.0"/> <fsummary></fsummary> <desc> <p>Returns a complete list of keys, in any order, which resides @@ -185,15 +230,19 @@ false</code> </func> <func> - <name name="map" arity="2"/> + <name name="map" arity="2" since="OTP 17.0"/> <fsummary></fsummary> <desc> - <p>Produces a new map <c><anno>Map2</anno></c> by calling function + <p>Produces a new map <c><anno>Map</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 + <c><anno>V1</anno></c> association in <c><anno>MapOrIter</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> + for the new map <c><anno>Map</anno></c>.</p> + <p>The call fails with a <c>{badmap,Map}</c> exception if + <c><anno>MapOrIter</anno></c> is not a map or valid iterator, + or with <c>badarg</c> if <c><anno>Fun</anno></c> is not a + function of arity 2.</p> <p><em>Example:</em></p> <code type="none"> > Fun = fun(K,V1) when is_list(K) -> V1*2 end, @@ -204,7 +253,7 @@ false</code> </func> <func> - <name name="merge" arity="2"/> + <name name="merge" arity="2" since="OTP 17.0"/> <fsummary></fsummary> <desc> <p>Merges two maps into a single map <c><anno>Map3</anno></c>. If two @@ -222,7 +271,7 @@ false</code> </func> <func> - <name name="new" arity="0"/> + <name name="new" arity="0" since="OTP 17.0"/> <fsummary></fsummary> <desc> <p>Returns a new empty map.</p> @@ -234,7 +283,36 @@ false</code> </func> <func> - <name name="put" arity="3"/> + <name name="next" arity="1" since="OTP 21.0"/> + <fsummary>Get the next key and value from an iterator.</fsummary> + <desc> + <p>Returns the next key-value association in + <c><anno>Iterator</anno></c> and a new iterator for the + remaining associations in the iterator. + </p> + <p> + If there are no more associations in the iterator, + <c>none</c> is returned. + </p> + <p><em>Example:</em></p> + <code type="none"> +> Map = #{a => 1, b => 2, c => 3}. +#{a => 1,b => 2,c => 3} +> I = maps:iterator(Map), ok. +ok +> {K1, V1, I1} = maps:next(I), {K1, V1}. +{a,1} +> {K2, V2, I2} = maps:next(I1), {K2, V2}. +{b,2} +> {K3, V3, I3} = maps:next(I2), {K3, V3}. +{c,3} +> maps:next(I3). +none</code> + </desc> + </func> + + <func> + <name name="put" arity="3" since="OTP 17.0"/> <fsummary></fsummary> <desc> <p>Associates <c><anno>Key</anno></c> with value @@ -258,7 +336,7 @@ false</code> </func> <func> - <name name="remove" arity="2"/> + <name name="remove" arity="2" since="OTP 17.0"/> <fsummary></fsummary> <desc> <p>Removes the <c><anno>Key</anno></c>, if it exists, and its @@ -278,7 +356,7 @@ false</code> </func> <func> - <name name="size" arity="1"/> + <name name="size" arity="1" since="OTP 17.0"/> <fsummary></fsummary> <desc> <p>Returns the number of key-value associations in @@ -292,7 +370,7 @@ false</code> </func> <func> - <name name="take" arity="2"/> + <name name="take" arity="2" since="OTP 19.0"/> <fsummary></fsummary> <desc> <p>The function removes the <c><anno>Key</anno></c>, if it @@ -317,7 +395,7 @@ error</code> </func> <func> - <name name="to_list" arity="1"/> + <name name="to_list" arity="1" since="OTP 17.0"/> <fsummary></fsummary> <desc> <p>Returns a list of pairs representing the key-value associations of @@ -334,7 +412,7 @@ error</code> </func> <func> - <name name="update" arity="3"/> + <name name="update" arity="3" since="OTP 17.0"/> <fsummary></fsummary> <desc> <p>If <c><anno>Key</anno></c> exists in <c><anno>Map1</anno></c>, the @@ -354,7 +432,7 @@ error</code> </func> <func> - <name name="update_with" arity="3"/> + <name name="update_with" arity="3" since="OTP 19.0"/> <fsummary></fsummary> <desc> <p>Update a value in a <c><anno>Map1</anno></c> associated @@ -373,7 +451,7 @@ error</code> </func> <func> - <name name="update_with" arity="4"/> + <name name="update_with" arity="4" since="OTP 19.0"/> <fsummary></fsummary> <desc> <p>Update a value in a <c><anno>Map1</anno></c> associated @@ -393,7 +471,7 @@ error</code> </func> <func> - <name name="values" arity="1"/> + <name name="values" arity="1" since="OTP 17.0"/> <fsummary></fsummary> <desc> <p>Returns a complete list of values, in arbitrary order, contained in @@ -409,7 +487,7 @@ error</code> </func> <func> - <name name="with" arity="2"/> + <name name="with" arity="2" since="OTP 17.3"/> <fsummary></fsummary> <desc> <p>Returns a new map <c><anno>Map2</anno></c> with the keys <c>K1</c> @@ -426,7 +504,7 @@ error</code> </func> <func> - <name name="without" arity="2"/> + <name name="without" arity="2" since="OTP 17.0"/> <fsummary></fsummary> <desc> <p>Returns a new map <c><anno>Map2</anno></c> without keys <c>K1</c> |