aboutsummaryrefslogtreecommitdiffstats
path: root/system/doc/efficiency_guide/listhandling.xml
blob: e9d2dfe5568e773b598cf6c0ce620f618670b6db (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
<?xml version="1.0" encoding="latin1" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">

<chapter>
  <header>
    <copyright>
      <year>2001</year><year>2009</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.
    
    </legalnotice>

    <title>List handling</title>
    <prepared>Bjorn Gustavsson</prepared>
    <docno></docno>
    <date>2007-11-16</date>
    <rev></rev>
    <file>listHandling.xml</file>
  </header>

  <section>
    <title>Creating a list</title>
    
    <p>Lists can only be built starting from the end and attaching
    list elements at the beginning. If you use the <c>++</c> operator
    like this</p>

    <code type="erl">
List1 ++ List2</code>

    <p>you will create a new list which is copy of the elements in <c>List1</c>,
    followed by <c>List2</c>. Looking at how <c>lists:append/1</c> or <c>++</c> would be
    implemented in plain Erlang, it can be seen clearly that the first list
    is copied:</p>

    <code type="erl">
append([H|T], Tail) ->
    [H|append(T, Tail)];
append([], Tail) ->
    Tail.</code>

    <p>So the important thing when recursing and building a list is to
    make sure that you attach the new elements to the beginning of the list,
    so that you build <em>a</em> list, and not hundreds or thousands of
    copies of the growing result list.</p>

    <p>Let us first look at how it should not be done:</p>

    <p><em>DO NOT</em></p>
    <code type="erl"><![CDATA[
bad_fib(N) ->
    bad_fib(N, 0, 1, []).

bad_fib(0, _Current, _Next, Fibs) ->
    Fibs;
bad_fib(N, Current, Next, Fibs) -> 
    bad_fib(N - 1, Next, Current + Next, Fibs ++ [Current]).]]></code>

    <p>Here we are not a building a list; in each iteration step we
    create a new list that is one element longer than the new previous list.</p>

    <p>To avoid copying the result in each iteration, we must build the list in
    reverse order and reverse the list when we are done:</p>

    <p><em>DO</em></p>
    <code type="erl"><![CDATA[
tail_recursive_fib(N) ->
    tail_recursive_fib(N, 0, 1, []).

tail_recursive_fib(0, _Current, _Next, Fibs) ->
    lists:reverse(Fibs);
tail_recursive_fib(N, Current, Next, Fibs) -> 
    tail_recursive_fib(N - 1, Next, Current + Next, [Current|Fibs]).]]></code>

  </section>

  <section>
    <title>List comprehensions</title>

    <p>Lists comprehensions still have a reputation for being slow.
    They used to be implemented using funs, which used to be slow.</p>

    <p>In recent Erlang/OTP releases (including R12B), a list comprehension</p>

    <code type="erl"><![CDATA[
[Expr(E) || E <- List]]]></code>

    <p>is basically translated to a local function</p>

    <code type="erl">
'lc^0'([E|Tail], Expr) ->
    [Expr(E)|'lc^0'(Tail, Expr)];
'lc^0'([], _Expr) -> [].</code>

    <p>In R12B, if the result of the list comprehension will <em>obviously</em> not be used,
    a list will not be constructed. For instance, in this code</p>
    
    <code type="erl"><![CDATA[
[io:put_chars(E) || E <- List],
ok.]]></code>
 
    <p>or in this code</p>
   
    <code type="erl"><![CDATA[
.
.
.
case Var of
    ... ->
        [io:put_chars(E) || E <- List];
    ... ->
end,
some_function(...),
.
.
.]]></code>
    
    <p>the value is neither assigned to a variable, nor passed to another function,
    nor returned, so there is no need to construct a list and the compiler will simplify
    the code for the list comprehension to</p>

    <code type="erl">
'lc^0'([E|Tail], Expr) ->
    Expr(E),
    'lc^0'(Tail, Expr);
'lc^0'([], _Expr) -> [].</code>

  </section>

  <section>
    <title>Deep and flat lists</title>

    <p><seealso marker="stdlib:lists#flatten/1">lists:flatten/1</seealso>
    builds an entirely new list. Therefore, it is expensive, and even
    <em>more</em> expensive than the <c>++</c> (which copies its left argument,
    but not its right argument).</p>

    <p>In the following situations, you can easily avoid calling <c>lists:flatten/1</c>:</p>

    <list type="bulleted">
      <item>When sending data to a port. Ports understand deep lists
       so there is no reason to flatten the list before sending it to
       the port.</item>
      <item>When calling BIFs that accept deep lists, such as
      <seealso marker="erts:erlang#list_to_binary/1">list_to_binary/1</seealso> or
      <seealso marker="erts:erlang#iolist_to_binary/1">iolist_to_binary/1</seealso>.</item>
      <item>When you know that your list is only one level deep, you can can use
      <seealso marker="stdlib:lists#append/1">lists:append/1</seealso>.</item>
    </list>

    <p><em>Port example</em></p>
    <p><em>DO</em></p>
    <pre>
      ...
      port_command(Port, DeepList)
      ...</pre>
    <p><em>DO NOT</em></p>
    <pre>
      ...
      port_command(Port, lists:flatten(DeepList))
      ...</pre>

    <p>A common way to send a zero-terminated string to a port is the following:</p>

    <p><em>DO NOT</em></p>
    <pre>
      ...
      TerminatedStr = String ++ [0], % String="foo" => [$f, $o, $o, 0]
      port_command(Port, TerminatedStr)
      ...</pre>

    <p>Instead do like this:</p>

    <p><em>DO</em></p>
    <pre>
      ...
      TerminatedStr = [String, 0], % String="foo" => [[$f, $o, $o], 0]
      port_command(Port, TerminatedStr) 
      ...</pre>

    <p><em>Append example</em></p>
    <p><em>DO</em></p>
    <pre>
      > lists:append([[1], [2], [3]]).
      [1,2,3]
      ></pre>
    <p><em>DO NOT</em></p>
    <pre>
      > lists:flatten([[1], [2], [3]]).
      [1,2,3]
      ></pre>
  </section>

  <section>
    <title>Why you should not worry about recursive lists functions</title>

    <p>In the performance myth chapter, the following myth was exposed:
    <seealso marker="myths#tail_recursive">Tail-recursive functions
    are MUCH faster than recursive functions</seealso>.</p>

    <p>To summarize, in R12B there is usually not much difference between
    a body-recursive list function and tail-recursive function that reverses
    the list at the end. Therefore, concentrate on writing beautiful code
    and forget about the performance of your list functions. In the time-critical
    parts of your code (and only there), <em>measure</em> before rewriting
    your code.</p>

    <p><em>Important note</em>: This section talks about lists functions that
    <em>construct</em> lists. A tail-recursive function that does not construct
    a list runs in constant space, while the corresponding body-recursive
    function uses stack space proportional to the length of the list.
    For instance, a function that sums a list of integers, should <em>not</em> be
    written like this</p>
    
    <p><em>DO NOT</em></p>
    <code type="erl">
recursive_sum([H|T]) -> H+recursive_sum(T);
recursive_sum([])    -> 0.</code>

    <p>but like this</p>

    <p><em>DO</em></p>
    <code type="erl">
sum(L) -> sum(L, 0).

sum([H|T], Sum) -> sum(T, Sum + H);
sum([], Sum)    -> Sum.</code>
  </section>
</chapter>