aboutsummaryrefslogtreecommitdiffstats
path: root/erts/doc/src/erlang.xml
diff options
context:
space:
mode:
authorMichał Muskała <[email protected]>2018-04-27 12:40:07 +0200
committerMichał Muskała <[email protected]>2018-04-29 17:03:43 +0200
commit5d0874a8f9fd617308d9024783db1e4e24268184 (patch)
treeac61f2f0f8d7f7483af9e17df44b49aeb049e695 /erts/doc/src/erlang.xml
parentd423a7af502227afcdcf7d2a1efecded85ea95fb (diff)
downloadotp-5d0874a8f9fd617308d9024783db1e4e24268184.tar.gz
otp-5d0874a8f9fd617308d9024783db1e4e24268184.tar.bz2
otp-5d0874a8f9fd617308d9024783db1e4e24268184.zip
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.
Diffstat (limited to 'erts/doc/src/erlang.xml')
-rw-r--r--erts/doc/src/erlang.xml20
1 files changed, 20 insertions, 0 deletions
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
@@ -2432,6 +2432,26 @@ os_prompt%</pre>
</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>
<desc>