From 5d0874a8f9fd617308d9024783db1e4e24268184 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Muska=C5=82a?= <michal@muskala.eu>
Date: Fri, 27 Apr 2018 12:40:07 +0200
Subject: Introduce is_map_key/2 guard BIF

This complements the `map_get/2` guard BIF introduced in #1784.

Rationale.

`map_get/2` allows accessing map fields in guards, but it might be
problematic in more complex guard expressions, for example:

foo(X) when map_get(a, X) =:= 1 or is_list(X) -> ...

The `is_list/1` part of the guard could never succeed since the
`map_get/2` guard would fail the whole guard expression. In this
situation, this could be solved by using `;` instead of `or` to separate
the guards, but it is not possible in every case.

To solve this situation, this PR proposes a `is_map_key/2` guard that
allows to check if a map has key inside a guard before trying to access
that key. When combined with `is_map/1` this allows to construct a
purely boolean guard expression testing a value of a key in a map.

Implementation.

Given the use case motivating the introduction of this function, the PR
contains compiler optimisations that produce optimial code for the
following guard expression:

foo(X) when is_map(X) and is_map_key(a, X) and map_get(a, X) =:= 1 -> ok;
foo(_) -> error.

Given all three tests share the failure label, the `is_map_key/2` and
`is_map/2` tests are optimised away.

As with `map_get/2` the `is_map_key/2` BIF is allowed in match specs.
---
 erts/doc/src/erlang.xml     | 20 ++++++++++++++++++++
 erts/doc/src/match_spec.xml | 23 ++++++++++++-----------
 2 files changed, 32 insertions(+), 11 deletions(-)

(limited to 'erts/doc')

diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml
index f561413fab..3154fdaf8c 100644
--- a/erts/doc/src/erlang.xml
+++ b/erts/doc/src/erlang.xml
@@ -2431,6 +2431,26 @@ os_prompt%</pre>
       </desc>
     </func>
 
+    <func>
+      <name name="is_map_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}
+> is_map_key("42",Map).
+true
+> is_map_key(value,Map).
+false</code>
+      </desc>
+    </func>
+
     <func>
       <name name="is_number" arity="1"/>
       <fsummary>Check whether a term is a number.</fsummary>
diff --git a/erts/doc/src/match_spec.xml b/erts/doc/src/match_spec.xml
index 888366b239..46a3daebe8 100644
--- a/erts/doc/src/match_spec.xml
+++ b/erts/doc/src/match_spec.xml
@@ -86,12 +86,12 @@
         <c><![CDATA[is_list]]></c> | <c><![CDATA[is_number]]></c> |
         <c><![CDATA[is_pid]]></c> | <c><![CDATA[is_port]]></c> |
         <c><![CDATA[is_reference]]></c> | <c><![CDATA[is_tuple]]></c> |
-        <c><![CDATA[is_map]]></c> | <c><![CDATA[is_binary]]></c> |
-        <c><![CDATA[is_function]]></c> | <c><![CDATA[is_record]]></c> |
-        <c><![CDATA[is_seq_trace]]></c> | <c><![CDATA['and']]></c> |
-        <c><![CDATA['or']]></c> | <c><![CDATA['not']]></c> |
-        <c><![CDATA['xor']]></c> | <c><![CDATA['andalso']]></c> |
-        <c><![CDATA['orelse']]></c>
+        <c><![CDATA[is_map]]></c> | <c><![CDATA[is_map_key]]></c> |
+        <c><![CDATA[is_binary]]></c> | <c><![CDATA[is_function]]></c> |
+        <c><![CDATA[is_record]]></c> | <c><![CDATA[is_seq_trace]]></c> |
+        <c><![CDATA['and']]></c> | <c><![CDATA['or']]></c> |
+        <c><![CDATA['not']]></c> | <c><![CDATA['xor']]></c> |
+        <c><![CDATA['andalso']]></c> | <c><![CDATA['orelse']]></c>
       </item>
       <item>ConditionExpression ::= ExprMatchVariable | { GuardFunction } |
         { GuardFunction, ConditionExpression, ... } | TermConstruct
@@ -168,11 +168,12 @@
         <c><![CDATA[is_list]]></c> | <c><![CDATA[is_number]]></c> |
         <c><![CDATA[is_pid]]></c> | <c><![CDATA[is_port]]></c> |
         <c><![CDATA[is_reference]]></c> | <c><![CDATA[is_tuple]]></c> |
-        <c><![CDATA[is_map]]></c> | <c><![CDATA[is_binary]]></c> |
-        <c><![CDATA[is_function]]></c> | <c><![CDATA[is_record]]></c> |
-        <c><![CDATA['and']]></c> | <c><![CDATA['or']]></c> |
-        <c><![CDATA['not']]></c> | <c><![CDATA['xor']]></c> |
-        <c><![CDATA['andalso']]></c> | <c><![CDATA['orelse']]></c>
+        <c><![CDATA[is_map]]></c> | <c><![CDATA[map_is_key]]></c> |
+        <c><![CDATA[is_binary]]></c> | <c><![CDATA[is_function]]></c> |
+        <c><![CDATA[is_record]]></c> | <c><![CDATA['and']]></c> |
+        <c><![CDATA['or']]></c> | <c><![CDATA['not']]></c> |
+        <c><![CDATA['xor']]></c> | <c><![CDATA['andalso']]></c> |
+        <c><![CDATA['orelse']]></c>
       </item>
       <item>ConditionExpression ::= ExprMatchVariable | { GuardFunction } |
         { GuardFunction, ConditionExpression, ... } | TermConstruct
-- 
cgit v1.2.3