From e7bfe47762065c87ff11a810988260d1e677f38e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn-Egil=20Dahlberg?= Date: Fri, 28 Feb 2014 17:31:20 +0100 Subject: stdlib: Document Maps module --- lib/stdlib/doc/src/Makefile | 1 + lib/stdlib/doc/src/maps.xml | 318 +++++++++++++++++++++++++++++++++++++++++ lib/stdlib/doc/src/ref_man.xml | 1 + lib/stdlib/doc/src/specs.xml | 1 + 4 files changed, 321 insertions(+) create mode 100644 lib/stdlib/doc/src/maps.xml (limited to 'lib/stdlib/doc') diff --git a/lib/stdlib/doc/src/Makefile b/lib/stdlib/doc/src/Makefile index 6f1e61e70c..ff77c3eea0 100644 --- a/lib/stdlib/doc/src/Makefile +++ b/lib/stdlib/doc/src/Makefile @@ -71,6 +71,7 @@ XML_REF3_FILES = \ lib.xml \ lists.xml \ log_mf_h.xml \ + maps.xml \ math.xml \ ms_transform.xml \ orddict.xml \ diff --git a/lib/stdlib/doc/src/maps.xml b/lib/stdlib/doc/src/maps.xml new file mode 100644 index 0000000000..76137e3dee --- /dev/null +++ b/lib/stdlib/doc/src/maps.xml @@ -0,0 +1,318 @@ + + + + +
+ + 20132014 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + maps + Björn-Egil Dahlberg + 1 + 2014-02-28 + A +
+ maps + Maps Processing Functions + +

This module contains functions for maps processing.

+ + + + + + + +

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

+

Example:

+ +> Map = #{"hi" => 42}, + Key = "hi", + maps:find(Key,Map). +{ok,42} + + + + + + + +

+ Calls F(K, V, AccIn) for every K to value V + association in Map in + arbitrary order. The function fun F/3 must return a new accumulator + which is passed to the next successive call. maps:fold/3 returns the final + value of the accumulator. The initial accumulator value Init is returned if + the map is empty. +

+

Example:

+ +> 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 + + + + + + + +

+ The function takes a list of key-value tuples elements and builds a + map. The associations may be in any order and both keys and values in the + association may be of any term. If the same key appears more than once, + the latter (rightmost) value is used and the previous values are ignored. +

+

Example:

+ +> List = [{"a",ignored},{1337,"value two"},{42,value_three},{"a",1}], + maps:from_list(List). +#{42 => value_three,1337 => "value two","a" => 1} + + + + + + + +

+ Returns the value Value associated with Key if + Map contains Key. + If no value is associated with Key then the call will + fail with an exception. +

+

Example:

+ +> Key = 1337, + Map = #{42 => value_two,1337 => "value one","a" => 1}, + maps:get(Key,Map). +"value one" + + + + + + + +

+ Returns true if map Map contains Key and returns + false if it does not contain the Key. + The function will fail with an exception if Map is not a Map. +

+

Example:

+ +> Map = #{"42" => value}. +#{"42"> => value} +> maps:is_key("42",Map). +true +> maps:is_key(value,Map). +false + + + + + + + +

+ Returns a complete list of keys, in arbitrary order, which resides within Map. +

+

Example:

+ +> Map = #{42 => value_three,1337 => "value two","a" => 1}, + maps:keys(Map). +[42,1337,"a"] + + + + + + + +

+ The function produces a new map Map2 by calling the function fun F(K, V1) for + every K to value V1 association in Map1 in arbitrary order. + The function fun F/2 must return the value V2 to be associated with key K for + the new map Map2. +

+

Example:

+ +> 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} + + + + + + + +

+ Merges two maps into a single map Map3. If two keys exists in both maps the + value in Map1 will be superseded by the value in Map2. +

+

Example:

+ +> Map1 = #{a => "value_one", b => "value_two"}, + Map2 = #{a => 1, c => 2}, + maps:merge(Map1,Map2). +#{a => 1,b => "value_two",c => 2} + + + + + + + +

+ Returns a new empty map. +

+

Example:

+ +> maps:new(). +#{} + + + + + + + +

+ Associates Key with value Value and inserts the association into map Map2. + If key Key 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. +

+

Example:

+ +> Map = #{"a" => 1}. +#{"a" => 1} +> maps:put("a", 42, Map). +#{"a" => 42} +> maps:put("b", 1337, Map). +#{"a" => 1,"b" => 1337} + + + + + + + +

+ The function removes the Key, if it exists, and its associated value from + Map1 and returns a new map Map2 without key Key. +

+

Example:

+ +> Map = #{"a" => 1}. +#{"a" => 1} +> maps:remove("a",Map). +#{} +> maps:remove("b",Map). +#{"a" => 1} + + + + + + + +

+ The function returns the number of key-value associations in the Map. + This operation happens in constant time. +

+

Example:

+ +> Map = #{42 => value_two,1337 => "value one","a" => 1}, + maps:size(Map). +3 + + + + + + + +

+ The fuction returns a list of pairs representing the key-value associations of Map, + where the pairs, [{K1,V1}, ..., {Kn,Vn}], are returned in arbitrary order. +

+

Example:

+ +> Map = #{42 => value_three,1337 => "value two","a" => 1}, + maps:to_list(Map). +[{42,value_three},{1337,"value two"},{"a",1}] + + + + + + + +

+ If Key exists in Map1 the old associated value is + replaced by value Value. The function returns a new map Map2 containing + the new associated value. If Key does not exist in Map1 an exception is + generated. +

+

Example:

+ +> Map = #{"a" => 1}. +#{"a" => 1} +> maps:update("a", 42, Map). +#{"a" => 42} + + + + + + + +

+ Returns a complete list of values, in arbitrary order, contained in map M. +

+

Example:

+ +> Map = #{42 => value_three,1337 => "value two","a" => 1}, + maps:values(Map). +[value_three,"value two",1] + + + + + + + +

+ Returns a new map Map2 without the keys K1 through Kn and their associated values from map Map1. + Any key in Ks that does not exist in Map1 are ignored. +

+

Example:

+ +> Map = #{42 => value_three,1337 => "value two","a" => 1}, + Ks = ["a",42,"other key"], + maps:without(Ks,Map). +#{1337 => "value two"} + + + + diff --git a/lib/stdlib/doc/src/ref_man.xml b/lib/stdlib/doc/src/ref_man.xml index 4ecd02a4bf..6c35578bdf 100644 --- a/lib/stdlib/doc/src/ref_man.xml +++ b/lib/stdlib/doc/src/ref_man.xml @@ -68,6 +68,7 @@ + diff --git a/lib/stdlib/doc/src/specs.xml b/lib/stdlib/doc/src/specs.xml index 213ce7563f..60a04ed5e7 100644 --- a/lib/stdlib/doc/src/specs.xml +++ b/lib/stdlib/doc/src/specs.xml @@ -34,6 +34,7 @@ + -- cgit v1.2.3