← Back to branch summary

~ubuntu-branches/ubuntu/trusty/erlang/trusty

« back to all changes in this revision

Viewing changes to system/doc/reference_manual/functions.xml

  • Committer: Bazaar Package Importer
  • Author(s): Clint Byrum
  • Date: 2011-05-05 15:48:43 UTC
  • mfrom: (3.5.13 sid)
  • Revision ID: james.westby@ubuntu.com-20110505154843-0om6ekzg6m7ugj27
Tags: 1:14.b.2-dfsg-3ubuntu1
* Merge from debian unstable.  Remaining changes:
  - Drop libwxgtk2.8-dev build dependency. Wx isn't in main, and not
    supposed to.
  - Drop erlang-wx binary.
  - Drop erlang-wx dependency from -megaco, -common-test, and -reltool, they
    do not really need wx. Also drop it from -debugger; the GUI needs wx,
    but it apparently has CLI bits as well, and is also needed by -megaco,
    so let's keep the package for now.
  - debian/patches/series: Do what I meant, and enable build-options.patch
    instead.
* Additional changes:
  - Drop erlang-wx from -et
* Dropped Changes:
  - patches/pcre-crash.patch: CVE-2008-2371: outer level option with
    alternatives caused crash. (Applied Upstream)
  - fix for ssl certificate verification in newSSL: 
    ssl_cacertfile_fix.patch (Applied Upstream)
  - debian/patches/series: Enable native.patch again, to get stripped beam
    files and reduce the package size again. (build-options is what
    actually accomplished this)
  - Remove build-options.patch on advice from upstream and because it caused
    odd build failures.

Show diffs side-by-side

added added

removed removed

Lines of Context:
system/doc/reference_manual/functions.xml
 
1
<?xml version="1.0" encoding="latin1" ?>
 
2
<!DOCTYPE chapter SYSTEM "chapter.dtd">
 
3
 
 
4
<chapter>
 
5
  <header>
 
6
    <copyright>
 
7
      <year>2003</year><year>2009</year>
 
8
      <holder>Ericsson AB. All Rights Reserved.</holder>
 
9
    </copyright>
 
10
    <legalnotice>
 
11
      The contents of this file are subject to the Erlang Public License,
 
12
      Version 1.1, (the "License"); you may not use this file except in
 
13
      compliance with the License. You should have received a copy of the
 
14
      Erlang Public License along with this software. If not, it can be
 
15
      retrieved online at http://www.erlang.org/.
 
16
    
 
17
      Software distributed under the License is distributed on an "AS IS"
 
18
      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 
19
      the License for the specific language governing rights and limitations
 
20
      under the License.
 
21
    
 
22
    </legalnotice>
 
23
 
 
24
    <title>Functions</title>
 
25
    <prepared></prepared>
 
26
    <docno></docno>
 
27
    <date></date>
 
28
    <rev></rev>
 
29
    <file>functions.xml</file>
 
30
  </header>
 
31
 
 
32
  <section>
 
33
    <marker id="syntax"></marker>
 
34
    <title>Function Declaration Syntax</title>
 
35
    <p>A <em>function declaration</em> is a sequence of function
 
36
      clauses separated by semicolons, and terminated by period (.).</p>
 
37
    <p>A <em>function clause</em> consists of a clause head and a
 
38
      clause body, separated by <c>-></c>.</p>
 
39
    <p>A clause <em>head</em> consists of the function name, an
 
40
      argument list, and an optional guard sequence
 
41
      beginning with the keyword <c>when</c>.</p>
 
42
    <pre>
 
43
Name(Pattern11,...,Pattern1N) [when GuardSeq1] ->
 
44
    Body1;
 
45
...;
 
46
Name(PatternK1,...,PatternKN) [when GuardSeqK] ->
 
47
    BodyK.</pre>
 
48
    <p>The function name is an atom. Each argument is a pattern.</p>
 
49
    <p>The number of arguments <c>N</c> is the <em>arity</em> of
 
50
      the function. A function is uniquely defined by the module name,
 
51
      function name and arity. That is, two functions with the same
 
52
      name and in the same module, but with different arities are two
 
53
      completely different functions.</p>
 
54
    <p>A function named <c>f</c> in the module <c>m</c> and with arity
 
55
      <c>N</c> is often denoted as <c>m:f/N</c>.</p>
 
56
    <p>A clause <em>body</em> consists of a sequence of expressions
 
57
      separated by comma (,):</p>
 
58
    <pre>
 
59
Expr1,
 
60
...,
 
61
ExprN</pre>
 
62
    <p>Valid Erlang expressions and guard sequences are described in
 
63
      <seealso marker="expressions">Erlang Expressions</seealso>.</p>
 
64
    <p>Example:</p>
 
65
    <pre>
 
66
fact(N) when N>0 ->  % first clause head
 
67
    N * fact(N-1);   % first clause body
 
68
 
 
69
fact(0) ->           % second clause head
 
70
    1.               % second clause body</pre>
 
71
  </section>
 
72
 
 
73
  <section>
 
74
    <marker id="eval"></marker>
 
75
    <title>Function Evaluation</title>
 
76
    <p>When a function <c>m:f/N</c> is called, first the code for
 
77
      the function is located. If the function cannot be found, an
 
78
      <c>undef</c> run-time error will occur. Note that the function
 
79
      must be exported to be visible outside the module it is defined
 
80
      in.</p>
 
81
    <p>If the function is found, the function clauses are scanned
 
82
      sequentially until a clause is found that fulfills the following
 
83
      two conditions:</p>
 
84
    <list type="ordered">
 
85
      <item>the patterns in the clause head can be successfully
 
86
       matched against the given arguments, and</item>
 
87
      <item>the guard sequence, if any, is true.</item>
 
88
    </list>
 
89
    <p>If such a clause cannot be found, a <c>function_clause</c>
 
90
      run-time error will occur.</p>
 
91
    <p>If such a clause is found, the corresponding clause body is
 
92
      evaluated. That is, the expressions in the body are evaluated
 
93
      sequentially and the value of the last expression is returned.</p>
 
94
    <p>Example: Consider the function <c>fact</c>:</p>
 
95
    <pre>
 
96
-module(m).
 
97
-export([fact/1]).
 
98
 
 
99
fact(N) when N>0 ->
 
100
    N * fact(N-1);
 
101
fact(0) ->
 
102
    1.</pre>
 
103
    <p>Assume we want to calculate factorial for 1:</p>
 
104
    <pre>
 
105
1> <input>m:fact(1).</input></pre>
 
106
    <p>Evaluation starts at the first clause. The pattern <c>N</c> is
 
107
      matched against the argument 1. The matching succeeds and
 
108
      the guard (<c>N>0</c>) is true, thus <c>N</c> is bound to 1 and
 
109
      the corresponding body is evaluated:</p>
 
110
    <pre>
 
111
<input>N * fact(N-1)</input> => (N is bound to 1)
 
112
<input>1 * fact(0)</input></pre>
 
113
    <p>Now <c>fact(0)</c> is called and the function clauses are
 
114
      scanned sequentially again. First, the pattern <c>N</c> is
 
115
      matched against 0. The matching succeeds, but the guard
 
116
      (<c>N>0</c>) is false. Second, the pattern 0 is matched against
 
117
      0. The matching succeeds and the body is evaluated:</p>
 
118
    <pre>
 
119
<input>1 * fact(0)</input> =>
 
120
<input>1 * 1</input> =>
 
121
<input>1</input></pre>
 
122
    <p>Evaluation has succeed and <c>m:fact(1)</c> returns 1.</p>
 
123
    <p>If <c>m:fact/1</c> is called with a negative number as
 
124
      argument, no clause head will match. A <c>function_clause</c>
 
125
      run-time error will occur.</p>
 
126
  </section>
 
127
 
 
128
  <section>
 
129
    <title>Tail recursion</title>
 
130
    <p>If the last expression of a function body is a function call,
 
131
      a <em>tail recursive</em> call is done so that no system
 
132
      resources for example call stack are consumed. This means
 
133
      that an infinite loop can be done if it uses tail recursive
 
134
      calls.</p>
 
135
    <p>Example:</p>
 
136
    <pre>
 
137
loop(N) ->
 
138
    io:format("~w~n", [N]),
 
139
    loop(N+1).</pre>
 
140
    <p>As a counter-example see the factorial example above 
 
141
      that is not tail recursive since a multiplication is done
 
142
      on the result of the recursive call to <c>fact(N-1)</c>.</p>
 
143
  </section>
 
144
 
 
145
  <section>
 
146
    <title>Built-In Functions, BIFs</title>
 
147
    <p><em>Built-in functions</em>, BIFs, are implemented in C code in
 
148
      the runtime system and do things that are difficult or impossible
 
149
      to implement in Erlang. Most of the built-in functions belong
 
150
      to the module <c>erlang</c> but there are also built-in functions
 
151
      belonging to a few other modules, for example <c>lists</c> and
 
152
      <c>ets</c>.</p>
 
153
    <p>The most commonly used BIFs belonging to <c>erlang</c> are
 
154
      <em>auto-imported</em>, they do not need to be prefixed with
 
155
      the module name. Which BIFs are auto-imported is specified in
 
156
      <c>erlang(3)</c>. For example, standard type conversion BIFs like
 
157
      <c>atom_to_list</c> and BIFs allowed in guards can be called
 
158
      without specifying the module name. Examples:</p>
 
159
    <pre>
 
160
1> <input>tuple_size({a,b,c}).</input>
 
161
3
 
162
2> <input>atom_to_list('Erlang').</input>
 
163
"Erlang"</pre>
 
164
    <p>Note that normally it is the set of auto-imported built-in
 
165
      functions that is referred to when talking about 'BIFs'.</p>
 
166
  </section>
 
167
</chapter>
 
168