Merge branch 'egil/maps-api-additions/PR-1025/OTP-13522'

* egil/maps-api-additions/PR-1025/OTP-13522:
  stdlib: Document maps:update_with/3,4
  stdlib: Add tests for maps:update_with/3,4
  stdlib: Add maps:update_with/3,4
  erts: Add tests for maps:take/2
  stdlib: Document maps:take/2
  erts: Add BIF maps:take/2

3 files changed, 144 insertions, 23 deletions

diff --git a/lib/stdlib/doc/src/maps.xml b/lib/stdlib/doc/src/maps.xml
index 0f58f19421..bf45461e2b 100644
--- a/lib/stdlib/doc/src/maps.xml
+++ b/lib/stdlib/doc/src/maps.xml
@@ -301,6 +301,30 @@ false</code>
 		</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="size" arity="1"/>
 			<fsummary></fsummary>
 			<desc>
@@ -357,6 +381,42 @@ false</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>
diff --git a/lib/stdlib/src/maps.erl b/lib/stdlib/src/maps.erl
index a52928f77f..ba9ad4f549 100644
--- a/lib/stdlib/src/maps.erl
+++ b/lib/stdlib/src/maps.erl
@@ -20,15 +20,15 @@
 
 -module(maps).
 
--export([get/3,filter/2,fold/3, map/2,
-         size/1,
+-export([get/3, filter/2,fold/3,
+         map/2, size/1,
+         update_with/3, update_with/4,
          without/2, with/2]).
 
-
-%%% BIFs
+%% BIFs
 -export([get/2, find/2, from_list/1,
          is_key/2, keys/1, merge/2,
-         new/0, put/3, remove/2,
+         new/0, put/3, remove/2, take/2,
          to_list/1, update/3, values/1]).
 
 -spec get(Key,Map) -> Value when
@@ -102,6 +102,13 @@ put(_,_,_) -> erlang:nif_error(undef).
 
 remove(_,_) -> erlang:nif_error(undef).
 
+-spec take(Key,Map1) -> {Value,Map2} | error when
+    Key :: term(),
+    Map1 :: map(),
+    Value :: term(),
+    Map2 :: map().
+
+take(_,_) -> erlang:nif_error(undef).
 
 -spec to_list(Map) -> [{Key,Value}] when
     Map :: map(),
@@ -127,8 +134,40 @@ update(_,_,_) -> erlang:nif_error(undef).
 
 values(_) -> erlang:nif_error(undef).
 
+%% End of BIFs
+
+-spec update_with(Key,Fun,Map1) -> Map2 when
+      Key :: term(),
+      Map1 :: map(),
+      Map2 :: map(),
+      Fun :: fun((Value1 :: term()) -> Value2 :: term()).
+
+update_with(Key,Fun,Map) when is_function(Fun,1), is_map(Map) ->
+    try maps:get(Key,Map) of
+        Val -> maps:update(Key,Fun(Val),Map)
+    catch
+        error:{badkey,_} ->
+            erlang:error({badkey,Key},[Key,Fun,Map])
+    end;
+update_with(Key,Fun,Map) ->
+    erlang:error(error_type(Map),[Key,Fun,Map]).
+
+
+-spec update_with(Key,Fun,Init,Map1) -> Map2 when
+      Key :: term(),
+      Map1 :: Map1,
+      Map2 :: Map2,
+      Fun :: fun((Value1 :: term()) -> Value2 :: term()),
+      Init :: term().
+
+update_with(Key,Fun,Init,Map) when is_function(Fun,1), is_map(Map) ->
+    case maps:find(Key,Map) of
+        {ok,Val} -> maps:update(Key,Fun(Val),Map);
+        error -> maps:put(Key,Init,Map)
+    end;
+update_with(Key,Fun,Init,Map) ->
+    erlang:error(error_type(Map),[Key,Fun,Init,Map]).
 
-%%% End of BIFs
 
 -spec get(Key, Map, Default) -> Value | Default when
         Key :: term(),
diff --git a/lib/stdlib/test/maps_SUITE.erl b/lib/stdlib/test/maps_SUITE.erl
index 8b3a8d7ae2..42e669a799 100644
--- a/lib/stdlib/test/maps_SUITE.erl
+++ b/lib/stdlib/test/maps_SUITE.erl
@@ -25,15 +25,10 @@
 
 -include_lib("common_test/include/ct.hrl").
 
-%% Test server specific exports
--export([all/0]).
--export([suite/0]).
--export([init_per_suite/1]).
--export([end_per_suite/1]).
--export([init_per_testcase/2]).
--export([end_per_testcase/2]).
-
--export([t_get_3/1, t_filter_2/1,
+-export([all/0, suite/0]).
+
+-export([t_update_with_3/1, t_update_with_4/1,
+         t_get_3/1, t_filter_2/1,
          t_fold_3/1,t_map_2/1,t_size_1/1,
          t_with_2/1,t_without_2/1]).
 
@@ -41,29 +36,56 @@
 %%-define(badarg(F,Args), {'EXIT', {badarg, [{maps,F,Args,_}|_]}}).
 %% silly broken hipe
 -define(badmap(V,F,_Args), {'EXIT', {{badmap,V}, [{maps,F,_,_}|_]}}).
+-define(badkey(K,F,_Args), {'EXIT', {{badkey,K}, [{maps,F,_,_}|_]}}).
 -define(badarg(F,_Args), {'EXIT', {badarg, [{maps,F,_,_}|_]}}).
 
 suite() ->
-    [{ct_hooks, [ts_install_cth]},
+    [{ct_hooks,[ts_install_cth]},
      {timetrap,{minutes,1}}].
 
 all() ->
-    [t_get_3,t_filter_2,
+    [t_update_with_3,t_update_with_4,
+     t_get_3,t_filter_2,
      t_fold_3,t_map_2,t_size_1,
      t_with_2,t_without_2].
 
-init_per_suite(Config) ->
-    Config.
+t_update_with_3(Config) when is_list(Config) ->
+    V1 = value1,
+    V2 = <<"value2">>,
+    V3 = "value3",
+    Map = #{ key1 => V1, key2 => V2, "key3" => V3 },
+    Fun = fun(V) -> [V,V,{V,V}] end,
+
+    #{ key1 := [V1,V1,{V1,V1}] } = maps:update_with(key1,Fun,Map),
+    #{ key2 := [V2,V2,{V2,V2}] } = maps:update_with(key2,Fun,Map),
+    #{ "key3" := [V3,V3,{V3,V3}] } = maps:update_with("key3",Fun,Map),
 
-end_per_suite(_Config) ->
+    %% error case
+    ?badmap(b,update_with,[[a,b],a,b]) = (catch maps:update_with([a,b],id(a),b)),
+    ?badarg(update_with,[[a,b],a,#{}]) = (catch maps:update_with([a,b],id(a),#{})),
+    ?badkey([a,b],update_with,[[a,b],Fun,#{}]) = (catch maps:update_with([a,b],Fun,#{})),
     ok.
 
-init_per_testcase(_Case, Config) ->
-    Config.
+t_update_with_4(Config) when is_list(Config) ->
+    V1 = value1,
+    V2 = <<"value2">>,
+    V3 = "value3",
+    Map = #{ key1 => V1, key2 => V2, "key3" => V3 },
+    Fun = fun(V) -> [V,V,{V,V}] end,
+    Init = 3,
+
+    #{ key1 := [V1,V1,{V1,V1}] } = maps:update_with(key1,Fun,Init,Map),
+    #{ key2 := [V2,V2,{V2,V2}] } = maps:update_with(key2,Fun,Init,Map),
+    #{ "key3" := [V3,V3,{V3,V3}] } = maps:update_with("key3",Fun,Init,Map),
 
-end_per_testcase(_Case, _Config) ->
+    #{ key3 := Init } = maps:update_with(key3,Fun,Init,Map),
+
+    %% error case
+    ?badmap(b,update_with,[[a,b],a,b]) = (catch maps:update_with([a,b],id(a),b)),
+    ?badarg(update_with,[[a,b],a,#{}]) = (catch maps:update_with([a,b],id(a),#{})),
     ok.
 
+
 t_get_3(Config) when is_list(Config) ->
     Map = #{ key1 => value1, key2 => value2 },
     DefaultValue = "Default value",