Introduce map_get guard-safe function

Rationale

Today all compound data types except for maps can be deconstructed in guards.
For tuples we have `element/2` and for lists `hd/1` and `tl/1`. Maps are
completely opaque to guards. This means matching on maps can't be
abstracted into macros, which is often done with repetitive guards. It
also means that maps have to be always selected whole from ETS tables,
even when only one field would be enough, which creates a potential
efficiency issue.

This PR introduces an `erlang:map_get/2` guard-safe function that allows
extracting a map field in guard. An alternative to this function would be
to introduce the syntax for extracting a value from a map that was planned
in the original EEP: `Map#{Key}`.

Even outside of guards, since this function is a guard-BIF it is more
efficient than using `maps:get/2` (since it does not need to set up the
stack), and more convenient from pattern matching on the map (compare:
`#{key := Value} = Map, Value` to `map_get(key, Map)`).

Performance considerations

A common concern against adding this function is the notion that "guards
have to be fast" and ideally execute in constant time. While there are
some counterexamples (`length/1`), what is more important is the fact
that adding those functions does not change in any way the time
complexity of pattern matching - it's already possible to match on map
fields today directly in patterns - adding this ability to guards will
niether slow down or speed up the execution, it will only make certain
programs more convenient to write.

This first version is very naive and does not perform any optimizations.

16 files changed, 137 insertions, 15 deletions

diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml
index c086928bb3..e287db88d3 100644
--- a/erts/doc/src/erlang.xml
+++ b/erts/doc/src/erlang.xml
@@ -2969,6 +2969,25 @@ os_prompt%</pre>
     </func>
 
     <func>
+      <name name="map_get" arity="2" />
+      <fsummary>Extract a value from a map</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},
+  map_get(Key,Map).
+"value one"</code>
+      </desc>
+    </func>
+
+    <func>
       <name name="map_size" arity="1"/>
       <fsummary>Return the size of a map.</fsummary>
       <desc>
@@ -11003,4 +11022,3 @@ true</pre>
     </func>
   </funcs>
 </erlref>
-
diff --git a/erts/doc/src/match_spec.xml b/erts/doc/src/match_spec.xml
index 644b989800..319e5a030a 100644
--- a/erts/doc/src/match_spec.xml
+++ b/erts/doc/src/match_spec.xml
@@ -110,7 +110,8 @@
       </item>
       <item>GuardFunction ::= BoolFunction | <c><![CDATA[abs]]></c> |
         <c><![CDATA[element]]></c> | <c><![CDATA[hd]]></c> |
-        <c><![CDATA[length]]></c> | <c><![CDATA[node]]></c> |
+        <c><![CDATA[length]]></c> | <c><![CDATA[map_get]]></c> |
+        <c><![CDATA[map_size]]></c> | <c><![CDATA[node]]></c> |
         <c><![CDATA[round]]></c> | <c><![CDATA[size]]></c> |
         <c><![CDATA[tl]]></c> | <c><![CDATA[trunc]]></c> |
         <c><![CDATA['+']]></c> | <c><![CDATA['-']]></c> |
@@ -190,7 +191,8 @@
       </item>
       <item>GuardFunction ::= BoolFunction | <c><![CDATA[abs]]></c> |
         <c><![CDATA[element]]></c> | <c><![CDATA[hd]]></c> |
-        <c><![CDATA[length]]></c> | <c><![CDATA[node]]></c> |
+        <c><![CDATA[length]]></c> | <c><![CDATA[map_get]]></c> |
+        <c><![CDATA[map_size]]></c> | <c><![CDATA[node]]></c> |
         <c><![CDATA[round]]></c> | <c><![CDATA[size]]></c> |
         <c><![CDATA[tl]]></c> | <c><![CDATA[trunc]]></c> |
         <c><![CDATA['+']]></c> | <c><![CDATA['-']]></c> |
@@ -867,4 +869,3 @@
       can be useful for testing complicated ETS matches.</p>
   </section>
 </chapter>
-
diff --git a/erts/emulator/beam/bif.tab b/erts/emulator/beam/bif.tab
index 687fd39d58..2e84056d9f 100644
--- a/erts/emulator/beam/bif.tab
+++ b/erts/emulator/beam/bif.tab
@@ -693,3 +693,4 @@ bif erts_internal:new_connection/1
 bif erts_internal:abort_connection/2
 bif erts_internal:map_next/3
 bif ets:whereis/1
+ubif erlang:map_get/2
diff --git a/erts/emulator/beam/erl_db_util.c b/erts/emulator/beam/erl_db_util.c
index 3836f28aa4..6354abfd1f 100644
--- a/erts/emulator/beam/erl_db_util.c
+++ b/erts/emulator/beam/erl_db_util.c
@@ -638,6 +638,12 @@ static DMCGuardBif guard_tab[] =
 	DBIF_ALL
     },
     {
+        am_map_get,
+        &map_get_2,
+        2,
+        DBIF_ALL
+    },
+    {
 	am_bit_size,
 	&bit_size_1,
 	1,
@@ -5737,5 +5743,3 @@ void db_match_dis(Binary *bp)
 }
 
 #endif /* DMC_DEBUG */
-
-
diff --git a/erts/emulator/beam/erl_map.c b/erts/emulator/beam/erl_map.c
index 4ec6960997..f577b017c3 100644
--- a/erts/emulator/beam/erl_map.c
+++ b/erts/emulator/beam/erl_map.c
@@ -44,6 +44,7 @@
  * DONE:
  * - erlang:is_map/1
  * - erlang:map_size/1
+ * - erlang:map_get/2
  *
  * - maps:find/2
  * - maps:from_list/1
@@ -202,7 +203,7 @@ BIF_RETTYPE maps_find_2(BIF_ALIST_2) {
     BIF_ERROR(BIF_P, BADMAP);
 }
 
-/* maps:get/2
+/* maps:get/2 and erlang:map_get/2
  * return value if key *matches* a key in the map
  * exception badkey if none matches
  */
@@ -223,6 +224,10 @@ BIF_RETTYPE maps_get_2(BIF_ALIST_2) {
     BIF_ERROR(BIF_P, BADMAP);
 }
 
+BIF_RETTYPE map_get_2(BIF_ALIST_2) {
+    BIF_RET(maps_get_2(BIF_CALL_ARGS));
+}
+
 /* maps:from_list/1
  * List may be unsorted [{K,V}]
  */
diff --git a/erts/emulator/test/map_SUITE.erl b/erts/emulator/test/map_SUITE.erl
index c9e971af8a..43807b4388 100644
--- a/erts/emulator/test/map_SUITE.erl
+++ b/erts/emulator/test/map_SUITE.erl
@@ -36,6 +36,7 @@
          t_map_equal/1,
          t_map_compare/1,
          t_map_size/1,
+         t_map_get/1,
          t_is_map/1,
 
          %% Specific Map BIFs
@@ -124,7 +125,7 @@ all() -> [t_build_and_match_literals, t_build_and_match_literals_large,
           %% erlang
           t_erlang_hash, t_map_encode_decode,
           t_gc_rare_map_overflow,
-          t_map_size, t_is_map,
+          t_map_size, t_map_get, t_is_map,
 
           %% non specific BIF related
           t_bif_build_and_check,
@@ -680,6 +681,48 @@ t_map_size(Config) when is_list(Config) ->
               end),
     ok.
 
+t_map_get(Config) when is_list(Config) ->
+    %% small map
+    1    = map_get(a, id(#{a=>1})),
+    2    = map_get(b, id(#{a=>1, b=>2})),
+    "hi" = map_get("hello", id(#{a=>1, "hello"=>"hi"})),
+    "tuple hi" = map_get({1,1.0}, id(#{a=>a, {1,1.0}=>"tuple hi"})),
+
+    M0    = id(#{ k1=>"v1", <<"k2">> => <<"v3">> }),
+    "v4" = map_get(<<"k2">>, M0#{<<"k2">> => "v4"}),
+
+    %% large map
+    M1   = maps:from_list([{I,I}||I<-lists:seq(1,100)] ++
+			  [{a,1},{b,2},{"hello","hi"},{{1,1.0},"tuple hi"},
+			   {k1,"v1"},{<<"k2">>,"v3"}]),
+    1    = map_get(a, M1),
+    2    = map_get(b, M1),
+    "hi" = map_get("hello", M1),
+    "tuple hi" = map_get({1,1.0}, M1),
+    "v3" = map_get(<<"k2">>, M1),
+
+    %% error cases
+    do_badmap(fun(T) ->
+		      {'EXIT',{{badmap,T},[{erlang,map_get,_,_}|_]}} =
+			  (catch map_get(a, T))
+	      end),
+
+    {'EXIT',{{badkey,{1,1}},[{erlang,map_get,_,_}|_]}} =
+	(catch map_get({1,1}, id(#{{1,1.0}=>"tuple"}))),
+    {'EXIT',{{badkey,a},[{erlang,map_get,_,_}|_]}} = (catch map_get(a, id(#{}))),
+    {'EXIT',{{badkey,a},[{erlang,map_get,_,_}|_]}} =
+	(catch map_get(a, id(#{b=>1, c=>2}))),
+
+    %% in guards
+    M2 = id(#{a=>1}),
+    true = if map_get(a, M2) =:= 1 -> true; true -> false end,
+    false = if map_get(x, M2) =:= 1 -> true; true -> false end,
+    do_badmap(fun
+        (T) when map_get(T, x) =:= 1 -> ok;
+        (T) -> false = is_map(T)
+    end),
+    ok.
+
 build_and_check_size([K|Ks],N,M0) ->
     N = map_size(M0),
     M1 = M0#{ K => K },
diff --git a/erts/emulator/test/match_spec_SUITE.erl b/erts/emulator/test/match_spec_SUITE.erl
index 08a7b4560c..c1bc01f01e 100644
--- a/erts/emulator/test/match_spec_SUITE.erl
+++ b/erts/emulator/test/match_spec_SUITE.erl
@@ -885,6 +885,19 @@ maps(Config) when is_list(Config) ->
         erlang:match_spec_test(#{<<"b">> =>"camembert","c"=>"cabécou", "wat"=>"hi", b=><<"other">>},
                                [{#{<<"b">> => '$1',"wat" => '$2'},[],[#{a=>'$1',b=>'$2'}]}],
                                table),
+
+    {ok,1,[],[]} = erlang:match_spec_test(#{a => 1}, [{'$1',[],[{map_size,'$1'}]}],table),
+    {ok,'EXIT',[],[]} = erlang:match_spec_test(not_a_map, [{'$1',[],[{map_size,'$1'}]}], table),
+    {ok,false,[],[]} = erlang:match_spec_test(not_a_map, [{'$1',[{map_size,'$1'}],['$_']}], table),
+    {ok,true,[],[]} = erlang:match_spec_test(#{a => 1}, [{'$1',[{'=:=',{map_size,'$1'},1}],[true]}], table),
+
+    {ok,1,[],[]} = erlang:match_spec_test(#{a => 1}, [{'$1',[],[{map_get,a,'$1'}]}], table),
+    {ok,'EXIT',[],[]} = erlang:match_spec_test(#{a => 1}, [{'$1',[],[{map_get,b,'$1'}]}], table),
+    {ok,'EXIT',[],[]} = erlang:match_spec_test(not_a_map, [{'$1',[],[{map_get,b,'$1'}]}], table),
+    {ok,false,[],[]} = erlang:match_spec_test(#{a => 1}, [{'$1',[{map_get,b,'$1'}],['$_']}], table),
+    {ok,false,[],[]} = erlang:match_spec_test(not_a_map, [{'$1',[{map_get,b,'$1'}],['$_']}], table),
+    {ok,true,[],[]} = erlang:match_spec_test(#{a => true}, [{'$1',[{map_get,a,'$1'}],[true]}], table),
+
     %% large maps
 
     Ls0 = [{I,<<I:32>>}||I <- lists:seq(1,415)],
diff --git a/erts/preloaded/src/erlang.erl b/erts/preloaded/src/erlang.erl
index bffa59338e..bf298521c6 100644
--- a/erts/preloaded/src/erlang.erl
+++ b/erts/preloaded/src/erlang.erl
@@ -141,7 +141,7 @@
 -export([list_to_integer/1, list_to_integer/2]).
 -export([list_to_pid/1, list_to_port/1, list_to_ref/1, list_to_tuple/1, loaded/0]).
 -export([localtime/0, make_ref/0]).
--export([map_size/1, match_spec_test/3, md5/1, md5_final/1]).
+-export([map_size/1, map_get/2, match_spec_test/3, md5/1, md5_final/1]).
 -export([md5_init/0, md5_update/2, module_loaded/1, monitor/2]).
 -export([monitor_node/2, monitor_node/3, nif_error/1, nif_error/2]).
 -export([node/0, node/1, now/0, phash/2, phash2/1, phash2/2]).
@@ -1230,6 +1230,14 @@ make_ref() ->
 map_size(_Map) ->
     erlang:nif_error(undefined).
 
+%% Shadowed by erl_bif_types: erlang:map_get/2
+-spec map_get(Key, Map) -> Value when
+      Map :: map(),
+      Key :: any(),
+      Value :: any().
+map_get(_Key, _Map) ->
+    erlang:nif_error(undefined).
+
 %% match_spec_test/3
 -spec erlang:match_spec_test(MatchAgainst, MatchSpec, Type) -> TestResult when
       MatchAgainst :: [term()] | tuple(),
@@ -3981,4 +3989,3 @@ gc_info(Ref, N, {OrigColls,OrigRecl}) ->
 	{Ref, {_,Colls, Recl}} -> 
 	    gc_info(Ref, N-1, {Colls+OrigColls,Recl+OrigRecl})
     end.
-
diff --git a/lib/compiler/src/erl_bifs.erl b/lib/compiler/src/erl_bifs.erl
index 8fab2400f7..70b36f029e 100644
--- a/lib/compiler/src/erl_bifs.erl
+++ b/lib/compiler/src/erl_bifs.erl
@@ -110,6 +110,7 @@ is_pure(erlang, list_to_pid, 1) -> true;
 is_pure(erlang, list_to_tuple, 1) -> true;
 is_pure(erlang, max, 2) -> true;
 is_pure(erlang, make_fun, 3) -> true;
+is_pure(erlang, map_get, 2) -> true;
 is_pure(erlang, min, 2) -> true;
 is_pure(erlang, phash, 2) -> false;
 is_pure(erlang, pid_to_list, 1) -> true;
diff --git a/lib/compiler/src/v3_codegen.erl b/lib/compiler/src/v3_codegen.erl
index 8808c0a3b7..8e73b613a0 100644
--- a/lib/compiler/src/v3_codegen.erl
+++ b/lib/compiler/src/v3_codegen.erl
@@ -588,6 +588,7 @@ is_gc_bif(node, 1) -> false;
 is_gc_bif(element, 2) -> false;
 is_gc_bif(get, 1) -> false;
 is_gc_bif(tuple_size, 1) -> false;
+is_gc_bif(map_get, 2) -> false;
 is_gc_bif(Bif, Arity) ->
     not (erl_internal:bool_op(Bif, Arity) orelse
 	 erl_internal:new_type_test(Bif, Arity) orelse
diff --git a/lib/compiler/test/map_SUITE.erl b/lib/compiler/test/map_SUITE.erl
index f15917e3cb..b59abf86e4 100644
--- a/lib/compiler/test/map_SUITE.erl
+++ b/lib/compiler/test/map_SUITE.erl
@@ -36,7 +36,7 @@
         t_guard_fun/1,
 	t_list_comprehension/1,
 	t_map_sort_literals/1,
-	t_map_size/1,
+	t_map_size/1, t_map_get/1,
 	t_build_and_match_aliasing/1,
 	t_is_map/1,
 
@@ -89,7 +89,7 @@ all() ->
 	t_guard_receive, t_guard_receive_large,
         t_guard_fun, t_list_comprehension,
 	t_map_sort_literals,
-	t_map_size,
+	t_map_size, t_map_get,
 	t_build_and_match_aliasing,
 	t_is_map,
 
@@ -686,6 +686,26 @@ t_map_size(Config) when is_list(Config) ->
 map_is_size(M,N) when map_size(M) =:= N -> true;
 map_is_size(_,_) -> false.
 
+t_map_get(Config) when is_list(Config) ->
+    1 = map_get(a, id(#{a=>1})),
+
+    {'EXIT',{{badkey,a},_}} = (catch map_get(a, #{})),
+    {'EXIT',{{badkey,a},_}} = (catch map_get(a, #{b=>1})),
+
+    M = #{"a"=>1, "b" => 2},
+    true = check_map_value(M, "a", 1),
+    false = check_map_value(M, "b", 1),
+    true = check_map_value(M#{"c"=>2}, "c", 2),
+    false = check_map_value(M#{"a"=>5}, "a", 1),
+
+    {'EXIT',{{badmap,[]},_}} = (catch map_get(a, [])),
+    {'EXIT',{{badmap,<<1,2,3>>},_}} = (catch map_get(a, <<1,2,3>>)),
+    {'EXIT',{{badmap,1},_}} = (catch map_get(a, 1)),
+    ok.
+
+check_map_value(Map, Key, Value) when map_get(Key, Map) =:= Value -> true;
+check_map_value(_, _, _) -> false.
+
 t_is_map(Config) when is_list(Config) ->
     true = is_map(#{}),
     true = is_map(#{a=>1}),
diff --git a/lib/hipe/cerl/erl_bif_types.erl b/lib/hipe/cerl/erl_bif_types.erl
index bfffb8db41..fe6ab0659c 100644
--- a/lib/hipe/cerl/erl_bif_types.erl
+++ b/lib/hipe/cerl/erl_bif_types.erl
@@ -770,6 +770,9 @@ type(erlang, length, 1, Xs, Opaques) ->
 %% Guard bif, needs to be here.
 type(erlang, map_size, 1, Xs, Opaques) ->
   type(maps, size, 1, Xs, Opaques);
+%% Guard bif, needs to be here.
+type(erlang, map_get, 2, Xs, Opaques) ->
+  type(maps, get, 2, Xs, Opaques);
 type(erlang, make_fun, 3, Xs, Opaques) ->
   strict(erlang, make_fun, 3, Xs,
          fun ([_, _, Arity]) ->
@@ -2391,6 +2394,9 @@ arg_types(erlang, length, 1) ->
 %% Guard bif, needs to be here.
 arg_types(erlang, map_size, 1) ->
   [t_map()];
+%% Guard bif, needs to be here.
+arg_types(erlang, map_get, 2) ->
+  [t_map(), t_any()];
 arg_types(erlang, make_fun, 3) ->
   [t_atom(), t_atom(), t_arity()];
 arg_types(erlang, make_tuple, 2) ->
diff --git a/lib/hipe/cerl/erl_types.erl b/lib/hipe/cerl/erl_types.erl
index 8a609ef911..a91da97f93 100644
--- a/lib/hipe/cerl/erl_types.erl
+++ b/lib/hipe/cerl/erl_types.erl
@@ -217,7 +217,7 @@
 	]).
 
 %%-define(DO_ERL_TYPES_TEST, true).
--compile({no_auto_import,[min/2,max/2]}).
+-compile({no_auto_import,[min/2,max/2,map_get/2]}).
 
 -ifdef(DO_ERL_TYPES_TEST).
 -export([test/0]).
diff --git a/lib/stdlib/src/erl_internal.erl b/lib/stdlib/src/erl_internal.erl
index 89b97b901e..6d3d5baa23 100644
--- a/lib/stdlib/src/erl_internal.erl
+++ b/lib/stdlib/src/erl_internal.erl
@@ -76,6 +76,7 @@ guard_bif(floor, 1) -> true;
 guard_bif(hd, 1) -> true;
 guard_bif(length, 1) -> true;
 guard_bif(map_size, 1) -> true;
+guard_bif(map_get, 2) -> true;
 guard_bif(node, 0) -> true;
 guard_bif(node, 1) -> true;
 guard_bif(round, 1) -> true;
@@ -337,6 +338,7 @@ bif(list_to_tuple, 1) -> true;
 bif(load_module, 2) -> true;
 bif(make_ref, 0) -> true;
 bif(map_size,1) -> true;
+bif(map_get,2) -> true;
 bif(max,2) -> true;
 bif(min,2) -> true;
 bif(module_loaded, 1) -> true;
diff --git a/lib/stdlib/src/ms_transform.erl b/lib/stdlib/src/ms_transform.erl
index 6616e957c0..ec8cfd56c2 100644
--- a/lib/stdlib/src/ms_transform.erl
+++ b/lib/stdlib/src/ms_transform.erl
@@ -944,6 +944,7 @@ real_guard_function(node,1) -> true;
 real_guard_function(round,1) -> true;
 real_guard_function(size,1) -> true;
 real_guard_function(map_size,1) -> true;
+real_guard_function(map_get,2) -> true;
 real_guard_function(tl,1) -> true;
 real_guard_function(trunc,1) -> true;
 real_guard_function(self,0) -> true;
@@ -1115,5 +1116,3 @@ normalise_list([H|T]) ->
     [normalise(H)|normalise_list(T)];
 normalise_list([]) ->
     [].
-
-
diff --git a/lib/tools/emacs/erlang.el b/lib/tools/emacs/erlang.el
index b88f368746..fd51aca861 100644
--- a/lib/tools/emacs/erlang.el
+++ b/lib/tools/emacs/erlang.el
@@ -825,6 +825,7 @@ resulting regexp is surrounded by \\_< and \\_>."
       "list_to_tuple"
       "load_module"
       "make_ref"
+      "map_get"
       "map_size"
       "max"
       "min"