In this section, all valid Erlang expressions are listed. When writing Erlang programs, it is also allowed to use macro- and record expressions. However, these expressions are expanded during compilation and are in that sense not true Erlang expressions. Macro- and record expressions are covered in separate sections:
All subexpressions are evaluated before an expression itself is evaluated, unless explicitly stated otherwise. For example, consider the expression:
Expr1 + Expr2
Many of the operators can only be applied to arguments of a
certain type. For example, arithmetic operators can only be
applied to numbers. An argument of the wrong type causes
a
The simplest form of expression is a term, that is an integer, float, atom, string, list, map, or tuple. The return value is the term itself.
A variable is an expression. If a variable is bound to a value, the return value is this value. Unbound variables are only allowed in patterns.
Variables start with an uppercase letter or underscore (_).
Variables can contain alphanumeric characters, underscore and
Examples:
X Name1 PhoneNumber Phone_number _ _Height
Variables are bound to values using
The anonymous variable is denoted by underscore (_) and can be used when a variable is required but its value can be ignored.
Example:
[H|_] = [1,2,3]
Variables starting with underscore (_), for example,
Example:
The following code:
member(_, []) ->
[].
can be rewritten to be more readable:
member(Elem, []) ->
[].
This causes a warning for an unused variable,
member(_Elem, []) ->
[].
Notice that since variables starting with an underscore are not anonymous, this matches:
{_,_} = {1,2}
But this fails:
{_N,_N} = {1,2}
The scope for a variable is its function clause.
Variables bound in a branch of an
For the
A pattern has the same structure as a term but can contain unbound variables.
Example:
Name1
[H|T]
{error,Reason}
Patterns are allowed in clause heads,
If
Pattern1 = Pattern2
When matched against a term, both
Example:
f({connect,From,To,Number,Options}, To) ->
Signal = {connect,From,To,Number,Options},
...;
f(Signal, To) ->
ignore.
can instead be written as
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
When matching strings, the following is a valid pattern:
f("prefix" ++ Str) -> ...
This is syntactic sugar for the equivalent, but harder to read:
f([$p,$r,$e,$f,$i,$x | Str]) -> ...
An arithmetic expression can be used within a pattern if it meets both of the following two conditions:
Example:
case {Value, Result} of
{?THRESHOLD+1, ok} -> ...
The following matches
Pattern = Expr
If the matching succeeds, any unbound variable in the pattern
becomes bound and the value of
If multiple match operators are applied in sequence, they will be evaluated from right to left.
If the matching fails, a
Examples:
1> {A, B} = T = {answer, 42}.
{answer,42}
2> A.
answer
3> B.
42
4> T.
{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
This is an advanced section, which references to topics not yet introduced. It can safely be skipped on a first reading.
The
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,43,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
5> <<X:Y>> = begin Y = 8, <<42:8>> end, X.
42
The expression at prompt 2> first matches the value of
variable
The expression at prompt 3> matches expression
In the expression at prompt 4> the expression
In the expression at prompt 5> the expressions
inside the
ExprF(Expr1,...,ExprN) ExprM:ExprF(Expr1,...,ExprN)
In the first form of function calls,
Example:
lists:keysearch(Name, 1, List)
In the second form of function calls,
If
Examples:
handle(Msg, State)
spawn(m, init, [])
Examples where
1> Fun1 = fun(X) -> X+1 end, Fun1(3). 4 2> fun lists:append/2([1,2], [3,4]). [1,2,3,4] 3>
Notice that when calling a local function, there is a difference
between using the implicitly or fully qualified function name.
The latter always refers to the latest version of the module.
See
If a local function has the same name as an auto-imported BIF,
the semantics is that implicitly qualified function calls are
directed to the locally defined function, not to the BIF. To avoid
confusion, there is a compiler directive available,
Before OTP R14A (ERTS version 5.8), an implicitly qualified function call to a function having the same name as an auto-imported BIF always resulted in the BIF being called. In newer versions of the compiler, the local function is called instead. This is to avoid that future additions to the set of auto-imported BIFs do not silently change the behavior of old code.
However, to avoid that old (pre R14) code changed its behavior when compiled with OTP version R14A or later, the following restriction applies: If you override the name of a BIF that was auto-imported in OTP versions prior to R14A (ERTS version 5.8) and have an implicitly qualified call to that function in your code, you either need to explicitly remove the auto-import using a compiler directive, or replace the call with a fully qualified function call. Otherwise you get a compilation error. See the following example:
-export([length/1,f/1]).
-compile({no_auto_import,[length/1]}). % erlang:length/1 no longer autoimported
length([]) ->
0;
length([H|T]) ->
1 + length(T). %% Calls the local function length/1
f(X) when erlang:length(X) > 3 -> %% Calls erlang:length/1,
%% which is allowed in guards
long.
The same logic applies to explicitly imported functions from other modules, as to locally defined functions. It is not allowed to both import a function from another module and have the function declared in the module at the same time:
-export([f/1]).
-compile({no_auto_import,[length/1]}). % erlang:length/1 no longer autoimported
-import(mod,[length/1]).
f(X) when erlang:length(X) > 33 -> %% Calls erlang:length/1,
%% which is allowed in guards
erlang:length(X); %% Explicit call to erlang:length in body
f(X) ->
length(X). %% mod:length/1 is called
For auto-imported BIFs added in Erlang/OTP R14A and thereafter,
overriding the name with a local function or explicit import is always
allowed. However, if the
if
GuardSeq1 ->
Body1;
...;
GuardSeqN ->
BodyN
end
The branches of an
The return value of
If no guard sequence is evaluated as true,
an
Example:
is_greater_than(X, Y) ->
if
X>Y ->
true;
true -> % works as an 'else' branch
false
end
case Expr of
Pattern1 [when GuardSeq1] ->
Body1;
...;
PatternN [when GuardSeqN] ->
BodyN
end
The expression
The return value of
If there is no matching pattern with a true guard sequence,
a
Example:
is_valid_signal(Signal) ->
case Signal of
{signal, _What, _From, _To} ->
true;
{signal, _What, _To} ->
true;
_Else ->
false
end.
The expressions in a
None of the variables bound in a
Here is an example:
= 0,
{ok, B} ?= b(),
A + B
end]]>
Let us first assume that
Now let us assume that
Finally, let us assume that
The example can be written in a less succient way using nested case expressions:
true = A >= 0,
case b() of
{ok, B} ->
A + B;
Other1 ->
Other1
end;
Other2 ->
Other2
end]]>
The
Body1;
...;
PatternN [when GuardSeqN] ->
BodyN
end]]>
If a conditional match operator fails, the failed expression is
matched against the patterns in all clauses between the
If there is no matching pattern with a true guard sequence,
an
None of the variables bound in a
Here is the previous example augmented with a
= 0,
{ok, B} ?= b(),
A + B
else
error -> error;
wrong -> error
end]]>
The
Expr1 ! Expr2
Sends the value of
receive
Pattern1 [when GuardSeq1] ->
Body1;
...;
PatternN [when GuardSeqN] ->
BodyN
end
Fetches a received message present in the message queue of
the process. The first message in the message queue is matched
sequentially against the patterns from top to bottom. If no
match was found, the matching sequence is repeated for the second
message in the queue, and so on. Messages are queued in the
The return value of
Example:
wait_for_onhook() ->
receive
onhook ->
disconnect(),
idle();
{connect, B} ->
B ! {busy, self()},
wait_for_onhook()
end.
The
receive
Pattern1 [when GuardSeq1] ->
Body1;
...;
PatternN [when GuardSeqN] ->
BodyN
after
ExprT ->
BodyT
end
The atom
Example:
wait_for_onhook() ->
receive
onhook ->
disconnect(),
idle();
{connect, B} ->
B ! {busy, self()},
wait_for_onhook()
after
60000 ->
disconnect(),
error()
end.
It is legal to use a
receive
after
ExprT ->
BodyT
end
This construction does not consume any messages, only suspends
execution in the process for
Example:
timer() ->
spawn(m, timer, [self()]).
timer(Pid) ->
receive
after
5000 ->
Pid ! timeout
end.
Expr1 op Expr2
The arguments can be of different data types. The following order is defined:
number < atom < reference < fun < port < pid < tuple < map < nil < list < bit string
Lists are compared element by element. Tuples are ordered by size, two tuples with the same size are compared element by element.
Bit strings are compared bit by bit. If one bit string is a prefix of the other, the shorter bit string is considered smaller.
Maps are ordered by size, two maps with the same size are compared by keys in ascending term order and then by values in key order. In maps key order integers types are considered less than floats types.
Atoms are compared using their string value, codepoint by codepoint.
When comparing an integer to a float, the term with the lesser
precision is converted into the type of the other term, unless the
operator is one of
Term comparison operators return the Boolean value of the
expression,
Examples:
1> 1==1.0.
true
2> 1=:=1.0.
false
3> 1 > a.
false
4> #{c => 3} > #{a => 1, b => 2}.
false
5> #{a => 1, b => 2} == #{a => 1.0, b => 2.0}.
true
6> <<2:2>> < <<128>>.
true
7> <<3:2>> < <<128>>.
false
op Expr Expr1 op Expr2
Examples:
1> +1.
1
2> -1.
-1
3> 1+1.
2
4> 4/2.
2.0
5> 5 div 2.
2
6> 5 rem 2.
1
7> 2#10 band 2#01.
0
8> 2#10 bor 2#01.
3
9> a + 10.
** exception error: an error occurred when evaluating an arithmetic expression
in operator +/2
called as a + 10
10> 1 bsl (1 bsl 64).
** exception error: a system limit has been reached
in operator bsl/2
called as 1 bsl 18446744073709551616
op Expr Expr1 op Expr2
Examples:
1> not true.
false
2> true and false.
false
3> true xor false.
true
4> true or garbage.
** exception error: bad argument
in operator or/2
called as true or garbage
Expr1 orelse Expr2 Expr1 andalso Expr2
or
Returns either the value of
Example 1:
case A >= -1.0 andalso math:sqrt(A+1) > B of
This works even if
Example 2:
OnlyOne = is_atom(L) orelse
(is_list(L) andalso length(L) == 1),
Example 3 (tail-recursive function):
all(Pred, [Hd|Tail]) ->
Pred(Hd) andalso all(Pred, Tail);
all(_, []) ->
true.
Before Erlang/OTP R13A,
Expr1 ++ Expr2 Expr1 -- Expr2
The list concatenation operator
The list subtraction operator
Example:
1> [1,2,3]++[4,5]. [1,2,3,4,5] 2> [1,2,3,2,1,2]--[2,1,2]. [3,1,2]
Constructing a new map is done by letting an expression
#{ K => V }
New maps can include multiple associations at construction by listing every association:
#{ K1 => V1, .., Kn => Vn }
An empty map is constructed by not associating any terms with each other:
#{}
All keys and values in the map are terms. Any expression is first evaluated and then the resulting terms are used as key and value respectively.
Keys and values are separated by the
Examples:
M0 = #{}, % empty map
M1 = #{a => <<"hello">>}, % single association with literals
M2 = #{1 => 2, b => b}, % multiple associations with literals
M3 = #{k => {A,B}}, % single association with variables
M4 = #{{"w", 1} => f()}. % compound key associated with an evaluated expression
Here,
If two matching keys are declared, the latter key takes precedence.
Example:
1> #{1 => a, 1 => b}.
#{1 => b }
2> #{1.0 => a, 1 => b}.
#{1 => b, 1.0 => a}
The order in which the expressions constructing the keys (and their associated values) are evaluated is not defined. The syntactic order of the key-value pairs in the construction is of no relevance, except in the recently mentioned case of two matching keys.
Updating a map has a similar syntax as constructing it.
An expression defining the map to be updated, is put in front of the expression defining the keys to be updated and their respective values:
M#{ K => V }
Here
If key
If key
If
To only update an existing value, the following syntax is used:
M#{ K := V }
Here
If key
If
Examples:
M0 = #{},
M1 = M0#{a => 0},
M2 = M1#{a => 1, b => 2},
M3 = M2#{"function" => fun() -> f() end},
M4 = M3#{a := 2, b := 3}. % 'a' and 'b' was added in `M1` and `M2`.
Here
More examples:
1> M = #{1 => a}.
#{1 => a }
2> M#{1.0 => b}.
#{1 => a, 1.0 => b}.
3> M#{1 := b}.
#{1 => b}
4> M#{1.0 := b}.
** exception error: bad argument
As in construction, the order in which the key and value expressions are evaluated is not defined. The syntactic order of the key-value pairs in the update is of no relevance, except in the case where two keys match. In that case, the latter value is used.
Matching of key-value associations from maps is done as follows:
#{ K := V } = M
Here
If the variable
Before Erlang/OTP 23, the expression defining the key
Example:
1> M = #{"tuple" => {1,2}}.
#{"tuple" => {1,2}}
2> #{"tuple" := {1,B}} = M.
#{"tuple" => {1,2}}
3> B.
2.
This binds variable
Similarly, multiple values from the map can be matched:
#{ K1 := V1, .., Kn := Vn } = M
Here keys
If the matching conditions are not met, the match fails, either with:
A
This is if it is used in the context of the match operator as in the example.
Or resulting in the next clause being tested in function heads and case expressions.
Matching in maps only allows for
The order in which keys are declared in matching has no relevance.
Duplicate keys are allowed in matching and match each pattern associated to the keys:
#{ K := V1, K := V2 } = M
Matching an expression against an empty map literal, matches its type but no variables are bound:
#{} = Expr
This expression matches if the expression
Here the key to be retrieved is constructed from an expression:
#{{tag,length(List)} := V} = Map
Matching of literals as keys are allowed in function heads:
%% only start if not_started
handle_call(start, From, #{ state := not_started } = S) ->
...
{reply, ok, S#{ state := start }};
%% only change if started
handle_call(change, From, #{ state := start } = S) ->
...
{reply, ok, S#{ state := changed }};
Maps are allowed in guards as long as all subexpressions are valid guard expressions.
The following guard BIFs handle maps:
The bit syntax operates on bit strings. A bit string is a sequence of bits ordered from the most significant bit to the least significant bit.
> % The empty bit string, zero length
<>
<>]]>
Each element
Each segment specification
Ei = Value |
Value:Size |
Value/TypeSpecifierList |
Value:Size/TypeSpecifierList
When used in a bit string construction,
When used in a bit string matching,
Notice that, for example, using a string literal as in
When used in a bit string construction,
When used in a bit string matching,
Before Erlang/OTP 23,
The value of
In matching, the default value for a binary or bit string segment is only valid for the last element. All other bit string or binary elements in the matching must have a size specification.
Binaries
A bit string with a length that is a multiple of 8 bits is known as a binary, which is the most common and useful type of bit string.
A binary has a canonical representation in memory. Here follows a sequence of bytes where each byte's value is its sequence number:
<<1, 2, 3, 4, 5, 6, 7, 8, 9, 10>>
Bit strings are a later generalization of binaries, so many texts and much information about binaries apply just as well for bit strings.
Example:
1> <<A/binary, B/binary>> = <<"abcde">>. * 1:3: a binary field without size is only allowed at the end of a binary pattern 2> <<A:3/binary, B/binary>> = <<"abcde">>. <<"abcde">> 3> A. <<"abc">> 4> B. <<"de">>
For the
<<16#1234:16/little>> = <<16#3412:16>> = <<16#34:8, 16#12:8>>
The value of
When constructing bit strings, if the size
The value of
When constructing bit strings, if the size of a float segment is too small to contain the representation of the given float value, an exception is raised.
When matching bit strings, matching of float segments fails if the bits of the segment does not contain the representation of a finite floating point value.
In this section, the phrase "binary segment" refers to any
one of the segment types
See also the paragraphs about
When constructing binaries and no size is specified for a binary segment, the entire binary value is interpolated into the binary being constructed. However, the size in bits of the binary being interpolated must be evenly divisible by the unit value for the segment; otherwise an exception is raised.
For example, the following examples all succeed:
1> <<(<<"abc">>)/bitstring>>. <<"abc">> 2> <<(<<"abc">>)/binary-unit:1>>. <<"abc">> 3> <<(<<"abc">>)/binary>>. <<"abc">>
The first two examples have a unit value of 1 for the segment, while the third segment has a unit value of 8.
Attempting to interpolate a bit string of size 1 into a
binary segment with unit 8 (the default unit for
1> <<(<<1:1>>)/binary>>. ** exception error: bad argument
For the construction to succeed, the unit value of the segment must be 1:
2> <<(<<1:1>>)/bitstring>>. <<1:1>> 3> <<(<<1:1>>)/binary-unit:1>>. <<1:1>>
Similarly, when matching a binary segment with no size specified, the match succeeds if and only if the size in bits of the rest of the binary is evenly divisible by the unit value:
1> <<_/binary-unit:16>> = <<"">>. <<>> 2> <<_/binary-unit:16>> = <<"a">>. ** exception error: no match of right hand side value <<"a">> 3> <<_/binary-unit:16>> = <<"ab">>. <<"ab">> 4> <<_/binary-unit:16>> = <<"abc">>. ** exception error: no match of right hand side value <<"abc">> 5> <<_/binary-unit:16>> = <<"abcd">>. <<"abcd">>
When a size is explicitly specified for a binary segment,
the segment size in bits is the value of
When constructing binaries, the size of the binary being interpolated into the constructed binary must be at least as large as the size of the binary segment.
Examples:
1> <<(<<"abc">>):2/binary>>.
<<"ab">>
2> <<(<<"a">>):2/binary>>.
** exception error: construction of binary failed
*** segment 1 of type 'binary': the value <<"a">> is shorter than the size of the segment
The types
When constructing a segment of a
When constructing, a literal string can be given followed
by one of the UTF types, for example:
A successful match of a segment of a
A segment of type
A segment of type
A segment of type
Examples:
1> Bin1 = <<1,17,42>>. <<1,17,42>> 2> Bin2 = <<"abc">>. <<97,98,99>> 3> Bin3 = <<1,17,42:16>>. <<1,17,0,42>> 4> <<A,B,C:16>> = <<1,17,42:16>>. <<1,17,0,42>> 5> C. 42 6> <<D:16,E,F>> = <<1,17,42:16>>. <<1,17,0,42>> 7> D. 273 8> F. 42 9> <<G,H/binary>> = <<1,17,42:16>>. <<1,17,0,42>> 10> H. <<17,0,42>> 11> <<G,J/bitstring>> = <<1,17,42:12>>. <<1,17,2,10:4>> 12> J. <<17,2,10:4>> 13> <<1024/utf8>>. <<208,128>> 14> <<1:1,0:7>>. <<128>> 15> <<16#123:12/little>> = <<16#231:12>> = <<2:4, 3:4, 1:4>>. <<35,1:4>>
Notice that bit string patterns cannot be nested.
Notice also that "
More examples are provided in
fun
[Name](Pattern11,...,Pattern1N) [when GuardSeq1] ->
Body1;
...;
[Name](PatternK1,...,PatternKN) [when GuardSeqK] ->
BodyK
end
A fun expression begins with the keyword
Variables in a fun head shadow the function name and both shadow variables in the function clause surrounding the fun expression. Variables bound in a fun body are local to the fun body.
The return value of the expression is the resulting fun.
Examples:
1> Fun1 = fun (X) -> X+1 end. #Fun<erl_eval.6.39074546> 2> Fun1(2). 3 3> Fun2 = fun (X) when X>=5 -> gt; (X) -> lt end. #Fun<erl_eval.6.39074546> 4> Fun2(7). gt 5> Fun3 = fun Fact(1) -> 1; Fact(X) when X > 1 -> X * Fact(X - 1) end. #Fun<erl_eval.6.39074546> 6> Fun3(4). 24
The following fun expressions are also allowed:
fun Name/Arity fun Module:Name/Arity
In
fun (Arg1,...,ArgN) -> Name(Arg1,...,ArgN) end
In
Before Erlang/OTP R15,
More examples are provided in
catch Expr
Returns the value of
For exceptions of class
For exceptions of class
For exceptions of class
Examples:
1> catch 1+2.
3
2> catch 1+a.
{'EXIT',{badarith,[...]}}
The BIF
Example:
3> catch throw(hello). hello
If
Before Erlang/OTP 24, the
1> A = (catch 42). 42 2> A. 42
Starting from Erlang/OTP 24, the parentheses can be omitted:
1> A = catch 42. 42 2> A. 42
try Exprs
catch
Class1:ExceptionPattern1[:Stacktrace] [when ExceptionGuardSeq1] ->
ExceptionBody1;
ClassN:ExceptionPatternN[:Stacktrace] [when ExceptionGuardSeqN] ->
ExceptionBodyN
end
This is an enhancement of
Notice that although the keyword
It returns the value of
If an exception occurs during evaluation of
If an exception occurs during evaluation of
It is allowed to omit
try Exprs
catch
ExceptionPattern1 [when ExceptionGuardSeq1] ->
ExceptionBody1;
ExceptionPatternN [when ExceptionGuardSeqN] ->
ExceptionBodyN
end
The
try Exprs of
Pattern1 [when GuardSeq1] ->
Body1;
...;
PatternN [when GuardSeqN] ->
BodyN
catch
Class1:ExceptionPattern1[:Stacktrace] [when ExceptionGuardSeq1] ->
ExceptionBody1;
...;
ClassN:ExceptionPatternN[:Stacktrace] [when ExceptionGuardSeqN] ->
ExceptionBodyN
end
If the evaluation of
Only exceptions occurring during the evaluation of
The
try Exprs of
Pattern1 [when GuardSeq1] ->
Body1;
...;
PatternN [when GuardSeqN] ->
BodyN
catch
Class1:ExceptionPattern1[:Stacktrace] [when ExceptionGuardSeq1] ->
ExceptionBody1;
...;
ClassN:ExceptionPatternN[:Stacktrace] [when ExceptionGuardSeqN] ->
ExceptionBodyN
after
AfterBody
end
Even if an exception occurs during evaluation of
If an exception occurs during evaluation of
The
try Exprs of
Pattern when GuardSeq ->
Body
after
AfterBody
end
try Exprs
catch
ExpressionPattern ->
ExpressionBody
after
AfterBody
end
try Exprs after AfterBody end
Next is an example of using
termize_file(Name) ->
{ok,F} = file:open(Name, [read,binary]),
try
{ok,Bin} = file:read(F, 1024*1024),
binary_to_term(Bin)
after
file:close(F)
end.
Next is an example of using
try Expr
catch
throw:Term -> Term;
exit:Reason -> {'EXIT',Reason}
error:Reason:Stk -> {'EXIT',{Reason,Stk}}
end
Variables bound in the various parts of these expressions have different scopes.
Variables bound just after the
Variables bound in
Variables bound in the
Variables bound in the
(Expr)
Parenthesized expressions are useful to override
1> 1 + 2 * 3. 7 2> (1 + 2) * 3. 9
begin Expr1, ..., ExprN end
Block expressions provide a way to group a sequence of
expressions, similar to a clause body. The return value is
the value of the last expression
Comprehensions provide a succinct notation for iterating over one or more terms and constructing a new term. Comprehensions come in three different flavors, depending on the type of term they build.
List comprehensions construct lists. They have the following syntax:
[Expr || Qualifier1, . . ., QualifierN]
Here,
Bit string comprehensions construct bit strings or binaries. They have the following syntax:
<< BitStringExpr || Qualifier1, . . ., QualifierN >>
Map comprehensions construct maps. They have the following syntax:
#{KeyExpr => ValueExpr || Qualifier1, . . ., QualifierN}
Here,
Map comprehensions and map generators were introduced in Erlang/OTP 26.
There are three kinds of generators.
A list generator has the following syntax:
Pattern <- ListExpr
where
A bit string generator has the following syntax:
BitstringPattern <= BitStringExpr
where
A map generator has the following syntax:
KeyPattern := ValuePattern <- MapExpression
where
A filter is an expression that evaluates to
The variables in the generator patterns shadow previously bound variables, including variables bound in a previous generator pattern.
Variables bound in a generator expression are not visible outside the expression:
1> [{E,L} || E <- L=[1,2,3]].
* 1:5: variable 'L' is unbound
A list comprehension returns a list, where the list elements are the
result of evaluating
A bit string comprehension returns a bit string, which is
created by concatenating the results of evaluating
A map comprehension returns a map, where the
map elements are the result of evaluating
Examples:
Multiplying each element in a list by two:
1> [X*2 || X <- [1,2,3]]. [2,4,6]
Multiplying each byte in a binary by two, returning a list:
1> [X*2 || <<X>> <= <<1,2,3>> >>. [2,4,6]
Multiplying each byte in a binary by two:
1> << <<(X*2)>> || <<X>> <= <<1,2,3>> >>. <<2,4,6>>
Multiplying each element in a list by two, returning a binary:
1> << <<(X*2)>> || X <- [1,2,3]]. <<2,4,6>>
Creating a mapping from an integer to its square:
1> #{X => X*X || X <- [1,2,3]}.
#{1 => 1,2 => 4,3 => 9}
Multiplying the value of each element in a map by two:
1> #{K => 2*V || K := V <- #{a => 1,b => 2,c => 3}}.
#{a => 2,b => 4,c => 6}
Filtering a list, keeping odd numbers:
1> [X || X <- [1,2,3,4,5], X rem 2 =:= 1]. [1,3,5]
Filtering a list, keeping only elements that match:
1> [X || {_,_}=X <- [{a,b}, [a], {x,y,z}, {1,2}]].
[{a,b},{1,2}]
Combining elements from two list generators:
1> [{P,Q} || P <- [a,b,c], Q <- [1,2]].
[{a,1},{a,2},{b,1},{b,2},{c,1},{c,2}]
More examples are provided in
When there are no generators, a comprehension returns either a
term constructed from a single element (the result of evaluating
Example:
1> [2 || is_integer(2)]. [2] 2> [x || is_integer(x)]. []
What happens when the filter expression does not evaluate to a boolean value depends on the expression:
If the expression is a
If the expression is not a guard expression and
evaluates to a non-Boolean value
Examples (using a guard expression as filter):
1> List = [1,2,a,b,c,3,4]. [1,2,a,b,c,3,4] 2> [E || E <- List, E rem 2]. [] 3> [E || E <- List, E rem 2 =:= 0]. [2,4]
Examples (using a non-guard expression as filter):
1> List = [1,2,a,b,c,3,4].
[1,2,a,b,c,3,4]
2> FaultyIsEven = fun(E) -> E rem 2 end.
#Fun<erl_eval.42.17316486>
3> [E || E <- List, FaultyIsEven(E)].
** exception error: bad filter 1
4> IsEven = fun(E) -> E rem 2 =:= 0 end.
#Fun<erl_eval.42.17316486>
5> [E || E <- List, IsEven(E)].
** exception error: an error occurred when evaluating an arithmetic expression
in operator rem/2
called as a rem 2
6> [E || E <- List, is_integer(E), IsEven(E)].
[2,4]
A guard sequence is a sequence of guards, separated by semicolon (;). The guard sequence is true if at least one of the guards is true. (The remaining guards, if any, are not evaluated.)
A guard is a sequence of guard expressions, separated
by comma (,). The guard is true if all guard expressions
evaluate to
The set of valid guard expressions is a subset of the set of valid Erlang expressions. The reason for restricting the set of valid expressions is that evaluation of a guard expression must be guaranteed to be free of side effects. Valid guard expressions are the following:
Notice that most type test BIFs have older equivalents, without
the
The
If an arithmetic expression, a Boolean expression, a short-circuit expression, or a call to a guard BIF fails (because of invalid arguments), the entire guard fails. If the guard was part of a guard sequence, the next guard in the sequence (that is, the guard following the next semicolon) is evaluated.
Operator precedence in descending order:
Before Erlang/OTP 24, the
The
When evaluating an expression, the operator with the highest precedence is evaluated first. Operators with the same precedence are evaluated according to their associativity. Non-associative operators cannot be combined with operators of the same precedence.
Examples:
The left-associative arithmetic operators are evaluated left to right:
6 + 5 * 4 - 3 / 2 evaluates to 6 + 20 - 1.5 evaluates to 26 - 1.5 evaluates to 24.5
The non-associative operators cannot be combined:
1> 1 < X < 10. * 1:7: syntax error before: '<'