aboutsummaryrefslogtreecommitdiffstats
path: root/system/doc/reference_manual/functions.xml
diff options
context:
space:
mode:
Diffstat (limited to 'system/doc/reference_manual/functions.xml')
-rw-r--r--system/doc/reference_manual/functions.xml100
1 files changed, 52 insertions, 48 deletions
diff --git a/system/doc/reference_manual/functions.xml b/system/doc/reference_manual/functions.xml
index 9498ef1402..863514ee78 100644
--- a/system/doc/reference_manual/functions.xml
+++ b/system/doc/reference_manual/functions.xml
@@ -4,20 +4,21 @@
<chapter>
<header>
<copyright>
- <year>2003</year><year>2013</year>
+ <year>2003</year><year>2015</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
- The contents of this file are subject to the Erlang Public License,
- Version 1.1, (the "License"); you may not use this file except in
- compliance with the License. You should have received a copy of the
- Erlang Public License along with this software. If not, it can be
- retrieved online at http://www.erlang.org/.
-
- Software distributed under the License is distributed on an "AS IS"
- basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
- the License for the specific language governing rights and limitations
- under the License.
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
</legalnotice>
@@ -38,7 +39,7 @@
clause body, separated by <c>-></c>.</p>
<p>A clause <em>head</em> consists of the function name, an
argument list, and an optional guard sequence
- beginning with the keyword <c>when</c>.</p>
+ beginning with the keyword <c>when</c>:</p>
<pre>
Name(Pattern11,...,Pattern1N) [when GuardSeq1] ->
Body1;
@@ -48,9 +49,9 @@ Name(PatternK1,...,PatternKN) [when GuardSeqK] ->
<p>The function name is an atom. Each argument is a pattern.</p>
<p>The number of arguments <c>N</c> is the <em>arity</em> of
the function. A function is uniquely defined by the module name,
- function name and arity. That is, two functions with the same
+ function name, and arity. That is, two functions with the same
name and in the same module, but with different arities are two
- completely different functions.</p>
+ different functions.</p>
<p>A function named <c>f</c> in the module <c>m</c> and with arity
<c>N</c> is often denoted as <c>m:f/N</c>.</p>
<p>A clause <em>body</em> consists of a sequence of expressions
@@ -60,8 +61,8 @@ Expr1,
...,
ExprN</pre>
<p>Valid Erlang expressions and guard sequences are described in
- <seealso marker="expressions">Erlang Expressions</seealso>.</p>
- <p>Example:</p>
+ <seealso marker="expressions">Expressions</seealso>.</p>
+ <p><em>Example:</em></p>
<pre>
fact(N) when N>0 -> % first clause head
N * fact(N-1); % first clause body
@@ -75,23 +76,23 @@ fact(0) -> % second clause head
<title>Function Evaluation</title>
<p>When a function <c>m:f/N</c> is called, first the code for
the function is located. If the function cannot be found, an
- <c>undef</c> run-time error will occur. Note that the function
+ <c>undef</c> runtime error occurs. Notice that the function
must be exported to be visible outside the module it is defined
in.</p>
<p>If the function is found, the function clauses are scanned
- sequentially until a clause is found that fulfills the following
- two conditions:</p>
+ sequentially until a clause is found that fulfills both of
+ the following two conditions:</p>
<list type="ordered">
- <item>the patterns in the clause head can be successfully
- matched against the given arguments, and</item>
- <item>the guard sequence, if any, is true.</item>
+ <item>The patterns in the clause head can be successfully
+ matched against the given arguments.</item>
+ <item>The guard sequence, if any, is true.</item>
</list>
<p>If such a clause cannot be found, a <c>function_clause</c>
- run-time error will occur.</p>
+ runtime error occurs.</p>
<p>If such a clause is found, the corresponding clause body is
evaluated. That is, the expressions in the body are evaluated
sequentially and the value of the last expression is returned.</p>
- <p>Example: Consider the function <c>fact</c>:</p>
+ <p>Consider the function <c>fact</c>:</p>
<pre>
-module(m).
-export([fact/1]).
@@ -100,17 +101,17 @@ fact(N) when N>0 ->
N * fact(N-1);
fact(0) ->
1.</pre>
- <p>Assume we want to calculate factorial for 1:</p>
+ <p>Assume that you want to calculate the factorial for 1:</p>
<pre>
1> <input>m:fact(1).</input></pre>
<p>Evaluation starts at the first clause. The pattern <c>N</c> is
- matched against the argument 1. The matching succeeds and
- the guard (<c>N>0</c>) is true, thus <c>N</c> is bound to 1 and
+ matched against argument 1. The matching succeeds and
+ the guard (<c>N>0</c>) is true, thus <c>N</c> is bound to 1, and
the corresponding body is evaluated:</p>
<pre>
<input>N * fact(N-1)</input> => (N is bound to 1)
<input>1 * fact(0)</input></pre>
- <p>Now <c>fact(0)</c> is called and the function clauses are
+ <p>Now, <c>fact(0)</c> is called, and the function clauses are
scanned sequentially again. First, the pattern <c>N</c> is
matched against 0. The matching succeeds, but the guard
(<c>N>0</c>) is false. Second, the pattern 0 is matched against
@@ -121,48 +122,51 @@ fact(0) ->
<input>1</input></pre>
<p>Evaluation has succeed and <c>m:fact(1)</c> returns 1.</p>
<p>If <c>m:fact/1</c> is called with a negative number as
- argument, no clause head will match. A <c>function_clause</c>
- run-time error will occur.</p>
+ argument, no clause head matches. A <c>function_clause</c>
+ runtime error occurs.</p>
</section>
<section>
<title>Tail recursion</title>
<p>If the last expression of a function body is a function call,
- a <em>tail recursive</em> call is done so that no system
- resources for example call stack are consumed. This means
- that an infinite loop can be done if it uses tail recursive
+ a <em>tail recursive</em> call is done.
+ This is to ensure that no system
+ resources, for example, call stack, are consumed. This means
+ that an infinite loop can be done if it uses tail-recursive
calls.</p>
- <p>Example:</p>
+ <p><em>Example:</em></p>
<pre>
loop(N) ->
io:format("~w~n", [N]),
loop(N+1).</pre>
- <p>As a counter-example see the factorial example above
- that is not tail recursive since a multiplication is done
+ <p>The earlier factorial example can act as a counter-example.
+ It is not tail-recursive, since a multiplication is done
on the result of the recursive call to <c>fact(N-1)</c>.</p>
</section>
<section>
- <title>Built-In Functions, BIFs</title>
- <p><em>Built-in functions</em>, BIFs, are implemented in C code in
- the runtime system and do things that are difficult or impossible
- to implement in Erlang. Most of the built-in functions belong
- to the module <c>erlang</c> but there are also built-in functions
+ <title>Built-In Functions (BIFs)</title>
+ <p>BIFs are implemented in C code in
+ the runtime system. BIFs do things that are difficult or impossible
+ to implement in Erlang. Most of the BIFs belong
+ to the module <c>erlang</c> but there are also BIFs
belonging to a few other modules, for example <c>lists</c> and
<c>ets</c>.</p>
- <p>The most commonly used BIFs belonging to <c>erlang</c> are
- <em>auto-imported</em>, they do not need to be prefixed with
- the module name. Which BIFs are auto-imported is specified in
- <c>erlang(3)</c>. For example, standard type conversion BIFs like
+ <p>The most commonly used BIFs belonging to <c>erlang(3)</c> are
+ <em>auto-imported</em>. They do not need to be prefixed with
+ the module name. Which BIFs that are auto-imported is specified in the
+ <seealso marker="erts:erlang">erlang(3)</seealso> module in ERTS.
+ For example, standard-type conversion BIFs like
<c>atom_to_list</c> and BIFs allowed in guards can be called
- without specifying the module name. Examples:</p>
+ without specifying the module name.</p>
+ <p><em>Examples:</em></p>
<pre>
1> <input>tuple_size({a,b,c}).</input>
3
2> <input>atom_to_list('Erlang').</input>
"Erlang"</pre>
- <p>Note that normally it is the set of auto-imported built-in
- functions that is referred to when talking about 'BIFs'.</p>
+ <p>Notice that it is normally the set of auto-imported BIFs
+ that are referred to when talking about 'BIFs'.</p>
</section>
</chapter>