diff --git a/system/doc/reference_manual/expressions.xml b/system/doc/reference_manual/expressions.xml index 45ca4b2092e7..8fdd1e91e300 100644 --- a/system/doc/reference_manual/expressions.xml +++ b/system/doc/reference_manual/expressions.xml @@ -138,18 +138,22 @@ member(_Elem, []) -> Name1 [H|T] {error,Reason} -

Patterns are allowed in clause heads, case and - receive expressions, and match expressions.

+

Patterns are allowed in clause heads, + case expressions, + receive expressions, + and + match expressions.

- Match Operator = in Patterns + + The Compound Pattern Operator

If Pattern1 and Pattern2 are valid patterns, the following is also a valid pattern:

 Pattern1 = Pattern2

When matched against a term, both Pattern1 and - Pattern2 are matched against the term. The idea - behind this feature is to avoid reconstruction of terms.

+ Pattern2 are matched against the term. The idea behind + this feature is to avoid reconstruction of terms.

Example:

 f({connect,From,To,Number,Options}, To) ->
@@ -163,6 +167,11 @@ f({connect,_,To,_,_} = Signal, To) ->
     ...;
 f(Signal, To) ->
     ignore.
+ +

The compound pattern operator does not imply that its operands + are matched in any particular order. That means that it is not + legal to bind a variable in Pattern1 and use it in Pattern2, + or vice versa.

@@ -192,7 +201,8 @@ case {Value, Result} of
- Match + + The Match Operator

The following matches Pattern against Expr:

@@ -214,6 +224,88 @@ answer
 {answer,42}
 5> {C, D} = [1, 2].
 ** exception error: no match of right-hand side value [1,2]
+ +

Because multiple match operators are evaluated from right to left, + it means that:

+ + 
+Pattern1 = Pattern2 = . . . = PatternN = Expression
+ +

is equivalent to:

+ 
+Temporary = Expression,
+PatternN = Temporary,
+   .
+   .
+   .,
+Pattern2 = Temporary,
+Pattern = Temporary
+
+ +
+ The Match Operator and the Compound Pattern Operator +

This is an advanced section, which references to topics not + yet introduced. It can safely be skipped on a first + reading.

 +

The = character is used to denote two similar but + distinct operators: the match operator and the compound pattern + operator. Which one is meant is determined by context.

+ +

The compound pattern operator is used to construct a + compound pattern from two patterns. Compound patterns are accepted + everywhere a pattern is accepted. A compound pattern matches if + all of its constituent patterns match. It is not legal for a + pattern that is part of a compound pattern to use variables (as + keys in map patterns or sizes in binary patterns) bound in other + sub patterns of the same compound pattern.

+

Examples:

+ + 
+1> fun(#{Key := Value} = #{key := Key}) -> Value end.
+* 1:7: variable 'Key' is unbound
+2> F = fun({A, B} = E) -> {E, A + B} end, F({1,2}).
+{{1,2},3}
+3> G = fun(<<A:8,B:8>> = <<C:16>>) -> {A, B, C} end, G(<<42,43>>).
+{42,42,10795}
+ +

The match operator is allowed everywhere an expression + is allowed. It is used to match the value of an expression to a pattern. + If multiple match operators are applied in sequence, they will be + evaluated from right to left.

+ +

Examples:

+ 
+1> M = #{key => key2, key2 => value}.
+#{key => key2,key2 => value}
+2> f(Key), #{Key := Value} = #{key := Key} = M, Value.
+value
+3> f(Key), #{Key := Value} = (#{key := Key} = M), Value.
+value
+4> f(Key), (#{Key := Value} = #{key := Key}) = M, Value.
+* 1:12: variable 'Key' is unbound
+ +

The expression at prompt 2> first matches the value of + variable M against pattern #{key := Key}, binding + variable Key. It then matches the value of M against + pattern #{Key := Value} using variable Key as the + key, binding variable Value.

+ +

The expression at prompt 3> matches expression + (#{key := Key} = M) against pattern #{Key := + Value}. The expression inside the parentheses is evaluated + first. That is, M is matched against #{key := Key}, + and then the value of M is matched against pattern #{Key + := Value}. That is the same evaluation order as in 2; + therefore, the parentheses are redundant.

+ +

In the expression at prompt 4> the expression M + is matched against a pattern inside parentheses. Since the + construct inside the parentheses is a pattern, the = that + separates the two patterns is the compound pattern operator + (not the match operator). The match fails because the two + sub patterns are matched at the same time, and the variable + Key is therefore not bound when matching against pattern + #{Key := Value}.

@@ -2009,6 +2101,11 @@ end Operator Precedence +

The = operator in the table is the + match operator. + The character = can also denote the + compound pattern operator, + which can only be used in patterns.

When evaluating an expression, the operator with the highest priority is evaluated first. Operators with the same priority are evaluated according to their associativity.