1
<?xml version="1.0" encoding="latin1" ?>
2
<!DOCTYPE erlref SYSTEM "erlref.dtd">
9
<holder>Ericsson AB, All Rights Reserved</holder>
12
The contents of this file are subject to the Erlang Public License,
13
Version 1.1, (the "License"); you may not use this file except in
14
compliance with the License. You should have received a copy of the
15
Erlang Public License along with this software. If not, it can be
16
retrieved online at http://www.erlang.org/.
18
Software distributed under the License is distributed on an "AS IS"
19
basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
20
the License for the specific language governing rights and limitations
23
The Initial Developer of the Original Code is Ericsson AB.
27
<prepared>Joe</prepared>
28
<responsible>Bjarne Däcker</responsible>
30
<approved>Bjarne Däcker</approved>
34
<file>queue.sgml</file>
36
<module>queue</module>
37
<modulesummary>Abstract Data Type for FIFO Queues</modulesummary>
39
<p>This module implements (double ended) FIFO queues
40
in an efficient manner.</p>
41
<p>All functions fail with reason <c>badarg</c> if arguments
42
are of wrong type, for example queue arguments are not
43
queues, indexes are not integers, list arguments are
44
not lists. Improper lists cause internal crashes.
45
An index out of range for a queue also causes
46
a failure with reason <c>badarg</c>.</p>
47
<p>Some functions, where noted, fail with reason <c>empty</c>
48
for an empty queue.</p>
49
<p>All operations has an amortized O(1) running time, except
50
<c>len/1</c>, <c>join/2</c>,
51
<c>split/2</c> and <c>filter/2</c> that are O(n).
52
To minimize the size of a queue minimizing
53
the amount of garbage built by queue operations, the queues
54
do not contain explicit length information, and that is
55
why <c>len/1</c> is O(n). If better performance for this
56
particular operation is essential, it is easy for
57
the caller to keep track of the length.</p>
58
<p>Queues are double ended. The mental picture of
59
a queue is a line of people (items) waiting for
60
their turn. The queue front is the end with the item
61
that has waited the longest. The queue rear is the end
62
an item enters when it starts to wait. If instead using
63
the mental picture of a list, the front is called head
64
and the rear is called tail.</p>
65
<p>Entering at the front and exiting at the rear
66
are reverse operations on the queue.</p>
67
<p>The module has several sets of interface functions. The
68
"Original API", the "Extended API" and the "Okasaki API".</p>
69
<p>The "Original API" and the "Extended API" both use the
70
mental picture of a waiting line of items. Both also
71
have reverse operations suffixed "_r".</p>
72
<p>The "Original API" item removal functions return compound
73
terms with both the removed item and the resulting queue.
74
The "Extended API" contain alternative functions that build
75
less garbage as well as functions for just inspecting the
76
queue ends. Also the "Okasaki API" functions build less garbage.</p>
77
<p>The "Okasaki API" is inspired by "Purely Functional Data structures"
78
by Chris Okasaki. It regards queues as lists.
79
The API is by many regarded as strange and avoidable.
80
For example many reverse operations have lexically reversed names,
81
some with more readable but perhaps less understandable aliases.</p>
87
<title>Original API</title>
92
<name>new() -> Q</name>
93
<fsummary>Create an empty queue</fsummary>
98
<p>Returns an empty queue.</p>
102
<name>is_queue(Term) -> true | false</name>
103
<fsummary>Test if a term is a queue</fsummary>
108
<p>Tests if <c>Q</c> is a queue and returns <c>true</c> if so and
109
<c>false</c> otherwise.</p>
113
<name>is_empty(Q) -> true | false</name>
114
<fsummary>Test if a queue is empty</fsummary>
119
<p>Tests if <c>Q</c> is empty and returns <c>true</c> if so and
120
<c>false</c> otherwise.</p>
124
<name>len(Q) -> N</name>
125
<fsummary>Get the length of a queue</fsummary>
131
<p>Calculates and returns the length of queue <c>Q</c>.</p>
136
<name>in(Item, Q1) -> Q2</name>
137
<fsummary>Insert an item at the rear of a queue</fsummary>
140
<v>Q1 = Q2 = queue()</v>
143
<p>Inserts <c>Item</c> at the rear of queue <c>Q1</c>.
144
Returns the resulting queue <c>Q2</c>.</p>
148
<name>in_r(Item, Q1) -> Q2</name>
149
<fsummary>Insert an item at the front of a queue</fsummary>
152
<v>Q1 = Q2 = queue()</v>
155
<p>Inserts <c>Item</c> at the front of queue <c>Q1</c>.
156
Returns the resulting queue <c>Q2</c>.</p>
160
<name>out(Q1) -> Result</name>
161
<fsummary>Remove the front item from a queue</fsummary>
163
<v>Result = {{value, Item}, Q2} | {empty, Q1}</v>
164
<v>Q1 = Q2 = queue()</v>
167
<p>Removes the item at the front of queue <c>Q1</c>. Returns the
168
tuple <c>{{value, Item}, Q2}</c>, where <c>Item</c> is the
169
item removed and <c>Q2</c> is the resulting queue. If <c>Q1</c> is
170
empty, the tuple <c>{empty, Q1}</c> is returned.</p>
174
<name>out_r(Q1) -> Result</name>
175
<fsummary>Remove the rear item from a queue</fsummary>
177
<v>Result = {{value, Item}, Q2} | {empty, Q1}</v>
178
<v>Q1 = Q2 = queue()</v>
181
<p>Removes the item at the rear of the queue <c>Q1</c>. Returns the
182
tuple <c>{{value, Item}, Q2}</c>, where <c>Item</c> is the
183
item removed and <c>Q2</c> is the new queue. If <c>Q1</c> is
184
empty, the tuple <c>{empty, Q1}</c> is returned. </p>
189
<name>from_list(L) -> queue()</name>
190
<fsummary>Convert a list to a queue</fsummary>
195
<p>Returns a queue containing the items in <c>L</c> in the
196
same order; the head item of the list will become the front
197
item of the queue.</p>
201
<name>to_list(Q) -> list()</name>
202
<fsummary>Convert a queue to a list</fsummary>
207
<p>Returns a list of the items in the queue in the same order;
208
the front item of the queue will become the head of the list.</p>
213
<name>reverse(Q1) -> Q2</name>
214
<fsummary>Reverse a queue</fsummary>
216
<v>Q1 = Q2 = queue()</v>
219
<p>Returns a queue <c>Q2</c> that contains the items of
220
<c>Q1</c> in the reverse order.</p>
224
<name>split(N, Q1) -> {Q2,Q3}</name>
225
<fsummary>Split a queue in two</fsummary>
228
<v>Q1 = Q2 = Q3 = queue()</v>
231
<p>Splits <c>Q1</c> in two. The <c>N</c> front items
232
are put in <c>Q2</c> and the rest in <c>Q3</c></p>
236
<name>join(Q1, Q2) -> Q3</name>
237
<fsummary>Join two queues</fsummary>
239
<v>Q1 = Q2 = Q3 = queue()</v>
242
<p>Returns a queue <c>Q3</c> that is the result of joining
243
<c>Q1</c> and <c>Q2</c> with <c>Q1</c> in front of
248
<name>filter(Fun, Q1) -> Q2</name>
249
<fsummary>Filter a queue</fsummary>
251
<v>Fun = fun(Item) -> bool() | list()</v>
252
<v>Q1 = Q2 = queue()</v>
255
<p>Returns a queue <c>Q2</c> that is the result of calling
256
<c>Fun(Item)</c> on all items in <c>Q1</c>,
257
in order from front to rear.</p>
258
<p>If <c>Fun(Item)</c> returns <c>true</c>, <c>Item</c>
259
is copied to the result queue. If it returns <c>false</c>,
260
<c>Item</c> is not copied. If it returns a list
261
the list elements are inserted instead of <c>Item</c> in the
263
<p>So, <c>Fun(Item)</c> returning <c>[Item]</c> is thereby
264
semantically equivalent to returning <c>true</c>, just
265
as returning <c>[]</c> is semantically equivalent to
266
returning <c>false</c>. But returning a list builds
267
more garbage than returning an atom.</p>
275
<title>Extended API</title>
280
<name>get(Q) -> Item</name>
281
<fsummary>Return the front item of a queue</fsummary>
287
<p>Returns <c>Item</c> at the front of queue <c>Q</c>.</p>
288
<p>Fails with reason <c>empty</c> if <c>Q</c> is empty.</p>
292
<name>get_r(Q) -> Item</name>
293
<fsummary>Return the rear item of a queue</fsummary>
299
<p>Returns <c>Item</c> at the rear of queue <c>Q</c>.</p>
300
<p>Fails with reason <c>empty</c> if <c>Q</c> is empty.</p>
304
<name>drop(Q1) -> Q2</name>
305
<fsummary>Remove the front item from a queue</fsummary>
308
<v>Q1 = Q2 = queue()</v>
311
<p>Returns a queue <c>Q2</c> that is the result of removing
312
the front item from <c>Q1</c>.</p>
313
<p>Fails with reason <c>empty</c> if <c>Q1</c> is empty.</p>
317
<name>drop_r(Q1) -> Q2</name>
318
<fsummary>Remove the rear item from a queue</fsummary>
321
<v>Q1 = Q2 = queue()</v>
324
<p>Returns a queue <c>Q2</c> that is the result of removing
325
the rear item from <c>Q1</c>.</p>
326
<p>Fails with reason <c>empty</c> if <c>Q1</c> is empty.</p>
330
<name>peek(Q) -> {value,Item} | empty</name>
331
<fsummary>Return the front item of a queue</fsummary>
337
<p>Returns the tuple <c>{value, Item}</c> where <c>Item</c> is the
338
front item of <c>Q</c>, or <c>empty</c> if <c>Q1</c> is empty.</p>
342
<name>peek_r(Q) -> {value,Item} | empty</name>
343
<fsummary>Return the rear item of a queue</fsummary>
349
<p>Returns the tuple <c>{value, Item}</c> where <c>Item</c> is the
350
rear item of <c>Q</c>, or <c>empty</c> if <c>Q1</c> is empty.</p>
357
<title>Okasaki API</title>
362
<name>cons(Item, Q1) -> Q2</name>
363
<fsummary>Insert an item at the head of a queue</fsummary>
366
<v>Q1 = Q2 = queue()</v>
369
<p>Inserts <c>Item</c> at the head of queue <c>Q1</c>. Returns
370
the new queue <c>Q2</c>.</p>
374
<name>head(Q) -> Item</name>
375
<fsummary>Return the item at the head of a queue</fsummary>
381
<p>Returns <c>Item</c> from the head of queue <c>Q</c>.</p>
382
<p>Fails with reason <c>empty</c> if <c>Q</c> is empty.</p>
386
<name>tail(Q1) -> Q2</name>
387
<fsummary>Remove the head item from a queue</fsummary>
390
<v>Q1 = Q2 = queue()</v>
393
<p>Returns a queue <c>Q2</c> that is the result of removing
394
the head item from <c>Q1</c>.</p>
395
<p>Fails with reason <c>empty</c> if <c>Q1</c> is empty.</p>
399
<name>snoc(Q1, Item) -> Q2</name>
400
<fsummary>Insert an item at the tail of a queue</fsummary>
403
<v>Q1 = Q2 = queue()</v>
406
<p>Inserts <c>Item</c> as the tail item of queue <c>Q1</c>. Returns
407
the new queue <c>Q2</c>.</p>
411
<name>daeh(Q) -> Item</name>
412
<name>last(Q) -> Item</name>
413
<fsummary>Return the tail item of a queue</fsummary>
419
<p>Returns the tail item of queue <c>Q</c>.</p>
420
<p>Fails with reason <c>empty</c> if <c>Q</c> is empty.</p>
424
<name>liat(Q1) -> Q2</name>
425
<name>init(Q1) -> Q2</name>
426
<name>lait(Q1) -> Q2</name>
427
<fsummary>Remove the tail item from a queue</fsummary>
430
<v>Q1 = Q2 = queue()</v>
433
<p>Returns a queue <c>Q2</c> that is the result of removing
434
the tail item from <c>Q1</c>.</p>
435
<p>Fails with reason <c>empty</c> if <c>Q1</c> is empty.</p>
436
<p>The name <c>lait/1</c> is a misspelling - do not use it anymore.</p>
added
removed
lib/stdlib/doc/src/queue.xml
