aboutsummaryrefslogtreecommitdiffstats
path: root/lib/stdlib/doc/src/queue.xml
diff options
context:
space:
mode:
authorHans Bolinder <[email protected]>2011-05-06 15:58:09 +0200
committerHans Bolinder <[email protected]>2011-05-12 08:03:42 +0200
commit229d0d8ca88bc344bed89e46541b325c1d267996 (patch)
tree74fec344df8596c868c36cec5ac08102008cacf3 /lib/stdlib/doc/src/queue.xml
parent68fe6a14539b82250373ef114d6576e74e1b8f2e (diff)
downloadotp-229d0d8ca88bc344bed89e46541b325c1d267996.tar.gz
otp-229d0d8ca88bc344bed89e46541b325c1d267996.tar.bz2
otp-229d0d8ca88bc344bed89e46541b325c1d267996.zip
r
Use Erlang specs and types for documentation
Diffstat (limited to 'lib/stdlib/doc/src/queue.xml')
-rw-r--r--lib/stdlib/doc/src/queue.xml286
1 files changed, 96 insertions, 190 deletions
diff --git a/lib/stdlib/doc/src/queue.xml b/lib/stdlib/doc/src/queue.xml
index 5ada1c2c57..383f52d10d 100644
--- a/lib/stdlib/doc/src/queue.xml
+++ b/lib/stdlib/doc/src/queue.xml
@@ -4,7 +4,7 @@
<erlref>
<header>
<copyright>
- <year>1996</year><year>2009</year>
+ <year>1996</year><year>2011</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -88,122 +88,94 @@
<title>Original API</title>
</section>
+ <datatypes>
+ <datatype>
+ <name><marker id="type-queue">queue()</marker></name>
+ <desc><p>As returned by <c>new/0</c>.</p></desc>
+ </datatype>
+ </datatypes>
+
<funcs>
<func>
- <name>new() -> Q</name>
+ <name name="new" arity="0"/>
<fsummary>Create an empty queue</fsummary>
- <type>
- <v>Q = queue()</v>
- </type>
<desc>
<p>Returns an empty queue.</p>
</desc>
</func>
<func>
- <name>is_queue(Term) -> true | false</name>
+ <name name="is_queue" arity="1"/>
<fsummary>Test if a term is a queue</fsummary>
- <type>
- <v>Term = term()</v>
- </type>
<desc>
- <p>Tests if <c>Q</c> is a queue and returns <c>true</c> if so and
+ <p>Tests if <c><anno>Term</anno></c> is a queue and returns <c>true</c> if so and
<c>false</c> otherwise.</p>
</desc>
</func>
<func>
- <name>is_empty(Q) -> true | false</name>
+ <name name="is_empty" arity="1"/>
<fsummary>Test if a queue is empty</fsummary>
- <type>
- <v>Q = queue()</v>
- </type>
<desc>
- <p>Tests if <c>Q</c> is empty and returns <c>true</c> if so and
+ <p>Tests if <c><anno>Q</anno></c> is empty and returns <c>true</c> if so and
<c>false</c> otherwise.</p>
</desc>
</func>
<func>
- <name>len(Q) -> N</name>
+ <name name="len" arity="1"/>
<fsummary>Get the length of a queue</fsummary>
- <type>
- <v>Q = queue()</v>
- <v>N = integer()</v>
- </type>
<desc>
- <p>Calculates and returns the length of queue <c>Q</c>.</p>
+ <p>Calculates and returns the length of queue <c><anno>Q</anno></c>.</p>
</desc>
</func>
<func>
- <name>in(Item, Q1) -> Q2</name>
+ <name name="in" arity="2"/>
<fsummary>Insert an item at the rear of a queue</fsummary>
- <type>
- <v>Item = term()</v>
- <v>Q1 = Q2 = queue()</v>
- </type>
<desc>
- <p>Inserts <c>Item</c> at the rear of queue <c>Q1</c>.
- Returns the resulting queue <c>Q2</c>.</p>
+ <p>Inserts <c><anno>Item</anno></c> at the rear of queue <c><anno>Q1</anno></c>.
+ Returns the resulting queue <c><anno>Q2</anno></c>.</p>
</desc>
</func>
<func>
- <name>in_r(Item, Q1) -> Q2</name>
+ <name name="in_r" arity="2"/>
<fsummary>Insert an item at the front of a queue</fsummary>
- <type>
- <v>Item = term()</v>
- <v>Q1 = Q2 = queue()</v>
- </type>
<desc>
- <p>Inserts <c>Item</c> at the front of queue <c>Q1</c>.
- Returns the resulting queue <c>Q2</c>.</p>
+ <p>Inserts <c><anno>Item</anno></c> at the front of queue <c><anno>Q1</anno></c>.
+ Returns the resulting queue <c><anno>Q2</anno></c>.</p>
</desc>
</func>
<func>
- <name>out(Q1) -> Result</name>
+ <name name="out" arity="1"/>
<fsummary>Remove the front item from a queue</fsummary>
- <type>
- <v>Result = {{value, Item}, Q2} | {empty, Q1}</v>
- <v>Q1 = Q2 = queue()</v>
- </type>
<desc>
- <p>Removes the item at the front of queue <c>Q1</c>. Returns the
- tuple <c>{{value, Item}, Q2}</c>, where <c>Item</c> is the
- item removed and <c>Q2</c> is the resulting queue. If <c>Q1</c> is
- empty, the tuple <c>{empty, Q1}</c> is returned.</p>
+ <p>Removes the item at the front of queue <c><anno>Q1</anno></c>. Returns the
+ tuple <c>{{value, <anno>Item</anno>}, <anno>Q2</anno>}</c>, where <c><anno>Item</anno></c> is the
+ item removed and <c><anno>Q2</anno></c> is the resulting queue. If <c><anno>Q1</anno></c> is
+ empty, the tuple <c>{empty, <anno>Q1</anno>}</c> is returned.</p>
</desc>
</func>
<func>
- <name>out_r(Q1) -> Result</name>
+ <name name="out_r" arity="1"/>
<fsummary>Remove the rear item from a queue</fsummary>
- <type>
- <v>Result = {{value, Item}, Q2} | {empty, Q1}</v>
- <v>Q1 = Q2 = queue()</v>
- </type>
<desc>
- <p>Removes the item at the rear of the queue <c>Q1</c>. Returns the
- tuple <c>{{value, Item}, Q2}</c>, where <c>Item</c> is the
- item removed and <c>Q2</c> is the new queue. If <c>Q1</c> is
- empty, the tuple <c>{empty, Q1}</c> is returned. </p>
+ <p>Removes the item at the rear of the queue <c><anno>Q1</anno></c>. Returns the
+ tuple <c>{{value, <anno>Item</anno>}, <anno>Q2</anno>}</c>, where <c><anno>Item</anno></c> is the
+ item removed and <c><anno>Q2</anno></c> is the new queue. If <c><anno>Q1</anno></c> is
+ empty, the tuple <c>{empty, <anno>Q1</anno>}</c> is returned. </p>
</desc>
</func>
<func>
- <name>from_list(L) -> queue()</name>
+ <name name="from_list" arity="1"/>
<fsummary>Convert a list to a queue</fsummary>
- <type>
- <v>L = list()</v>
- </type>
<desc>
- <p>Returns a queue containing the items in <c>L</c> in the
+ <p>Returns a queue containing the items in <c><anno>L</anno></c> in the
same order; the head item of the list will become the front
item of the queue.</p>
</desc>
</func>
<func>
- <name>to_list(Q) -> list()</name>
+ <name name="to_list" arity="1"/>
<fsummary>Convert a queue to a list</fsummary>
- <type>
- <v>Q = queue()</v>
- </type>
<desc>
<p>Returns a list of the items in the queue in the same order;
the front item of the queue will become the head of the list.</p>
@@ -211,57 +183,43 @@
</func>
<func>
- <name>reverse(Q1) -> Q2</name>
+ <name name="reverse" arity="1"/>
<fsummary>Reverse a queue</fsummary>
- <type>
- <v>Q1 = Q2 = queue()</v>
- </type>
<desc>
- <p>Returns a queue <c>Q2</c> that contains the items of
- <c>Q1</c> in the reverse order.</p>
+ <p>Returns a queue <c><anno>Q2</anno></c> that contains the items of
+ <c><anno>Q1</anno></c> in the reverse order.</p>
</desc>
</func>
<func>
- <name>split(N, Q1) -> {Q2,Q3}</name>
+ <name name="split" arity="2"/>
<fsummary>Split a queue in two</fsummary>
- <type>
- <v>N = integer()</v>
- <v>Q1 = Q2 = Q3 = queue()</v>
- </type>
<desc>
- <p>Splits <c>Q1</c> in two. The <c>N</c> front items
- are put in <c>Q2</c> and the rest in <c>Q3</c></p>
+ <p>Splits <c><anno>Q1</anno></c> in two. The <c><anno>N</anno></c> front items
+ are put in <c><anno>Q2</anno></c> and the rest in <c><anno>Q3</anno></c></p>
</desc>
</func>
<func>
- <name>join(Q1, Q2) -> Q3</name>
+ <name name="join" arity="2"/>
<fsummary>Join two queues</fsummary>
- <type>
- <v>Q1 = Q2 = Q3 = queue()</v>
- </type>
<desc>
- <p>Returns a queue <c>Q3</c> that is the result of joining
- <c>Q1</c> and <c>Q2</c> with <c>Q1</c> in front of
- <c>Q2</c>.</p>
+ <p>Returns a queue <c><anno>Q3</anno></c> that is the result of joining
+ <c><anno>Q1</anno></c> and <c><anno>Q2</anno></c> with <c><anno>Q1</anno></c> in front of
+ <c><anno>Q2</anno></c>.</p>
</desc>
</func>
<func>
- <name>filter(Fun, Q1) -> Q2</name>
+ <name name="filter" arity="2"/>
<fsummary>Filter a queue</fsummary>
- <type>
- <v>Fun = fun(Item) -> bool() | list()</v>
- <v>Q1 = Q2 = queue()</v>
- </type>
<desc>
- <p>Returns a queue <c>Q2</c> that is the result of calling
- <c>Fun(Item)</c> on all items in <c>Q1</c>,
+ <p>Returns a queue <c><anno>Q2</anno></c> that is the result of calling
+ <c><anno>Fun</anno>(<anno>Item</anno>)</c> on all items in <c><anno>Q1</anno></c>,
in order from front to rear.</p>
- <p>If <c>Fun(Item)</c> returns <c>true</c>, <c>Item</c>
+ <p>If <c><anno>Fun</anno>(<anno>Item</anno>)</c> returns <c>true</c>, <c>Item</c>
is copied to the result queue. If it returns <c>false</c>,
- <c>Item</c> is not copied. If it returns a list
+ <c><anno>Item</anno></c> is not copied. If it returns a list
the list elements are inserted instead of <c>Item</c> in the
result queue.</p>
- <p>So, <c>Fun(Item)</c> returning <c>[Item]</c> is thereby
+ <p>So, <c><anno>Fun</anno>(<anno>Item</anno>)</c> returning <c>[<anno>Item</anno>]</c> is thereby
semantically equivalent to returning <c>true</c>, just
as returning <c>[]</c> is semantically equivalent to
returning <c>false</c>. But returning a list builds
@@ -269,15 +227,11 @@
</desc>
</func>
<func>
- <name>member(Item, Q) -> bool()</name>
+ <name name="member" arity="2"/>
<fsummary>Test if an item is in a queue</fsummary>
- <type>
- <v>Item = term()</v>
- <v>Q = queue()</v>
- </type>
<desc>
- <p>Returns <c>true</c> if <c>Item</c> matches some element
- in <c>Q</c>, otherwise <c>false</c>.</p>
+ <p>Returns <c>true</c> if <c><anno>Item</anno></c> matches some element
+ in <c><anno>Q</anno></c>, otherwise <c>false</c>.</p>
</desc>
</func>
</funcs>
@@ -290,77 +244,53 @@
<funcs>
<func>
- <name>get(Q) -> Item</name>
+ <name name="get" arity="1"/>
<fsummary>Return the front item of a queue</fsummary>
- <type>
- <v>Item = term()</v>
- <v>Q = queue()</v>
- </type>
<desc>
- <p>Returns <c>Item</c> at the front of queue <c>Q</c>.</p>
- <p>Fails with reason <c>empty</c> if <c>Q</c> is empty.</p>
+ <p>Returns <c><anno>Item</anno></c> at the front of queue <c><anno>Q</anno></c>.</p>
+ <p>Fails with reason <c>empty</c> if <c><anno>Q</anno></c> is empty.</p>
</desc>
</func>
<func>
- <name>get_r(Q) -> Item</name>
+ <name name="get_r" arity="1"/>
<fsummary>Return the rear item of a queue</fsummary>
- <type>
- <v>Item = term()</v>
- <v>Q = queue()</v>
- </type>
<desc>
- <p>Returns <c>Item</c> at the rear of queue <c>Q</c>.</p>
- <p>Fails with reason <c>empty</c> if <c>Q</c> is empty.</p>
+ <p>Returns <c><anno>Item</anno></c> at the rear of queue <c><anno>Q</anno></c>.</p>
+ <p>Fails with reason <c>empty</c> if <c><anno>Q</anno></c> is empty.</p>
</desc>
</func>
<func>
- <name>drop(Q1) -> Q2</name>
+ <name name="drop" arity="1"/>
<fsummary>Remove the front item from a queue</fsummary>
- <type>
- <v>Item = term()</v>
- <v>Q1 = Q2 = queue()</v>
- </type>
<desc>
- <p>Returns a queue <c>Q2</c> that is the result of removing
- the front item from <c>Q1</c>.</p>
- <p>Fails with reason <c>empty</c> if <c>Q1</c> is empty.</p>
+ <p>Returns a queue <c><anno>Q2</anno></c> that is the result of removing
+ the front item from <c><anno>Q1</anno></c>.</p>
+ <p>Fails with reason <c>empty</c> if <c><anno>Q1</anno></c> is empty.</p>
</desc>
</func>
<func>
- <name>drop_r(Q1) -> Q2</name>
+ <name name="drop_r" arity="1"/>
<fsummary>Remove the rear item from a queue</fsummary>
- <type>
- <v>Item = term()</v>
- <v>Q1 = Q2 = queue()</v>
- </type>
<desc>
- <p>Returns a queue <c>Q2</c> that is the result of removing
- the rear item from <c>Q1</c>.</p>
- <p>Fails with reason <c>empty</c> if <c>Q1</c> is empty.</p>
+ <p>Returns a queue <c><anno>Q2</anno></c> that is the result of removing
+ the rear item from <c><anno>Q1</anno></c>.</p>
+ <p>Fails with reason <c>empty</c> if <c><anno>Q1</anno></c> is empty.</p>
</desc>
</func>
<func>
- <name>peek(Q) -> {value,Item} | empty</name>
+ <name name="peek" arity="1"/>
<fsummary>Return the front item of a queue</fsummary>
- <type>
- <v>Item = term()</v>
- <v>Q = queue()</v>
- </type>
<desc>
- <p>Returns the tuple <c>{value, Item}</c> where <c>Item</c> is the
- front item of <c>Q</c>, or <c>empty</c> if <c>Q1</c> is empty.</p>
+ <p>Returns the tuple <c>{value, <anno>Item</anno>}</c> where <c><anno>Item</anno></c> is the
+ front item of <c><anno>Q</anno></c>, or <c>empty</c> if <c><anno>Q</anno></c> is empty.</p>
</desc>
</func>
<func>
- <name>peek_r(Q) -> {value,Item} | empty</name>
+ <name name="peek_r" arity="1"/>
<fsummary>Return the rear item of a queue</fsummary>
- <type>
- <v>Item = term()</v>
- <v>Q = queue()</v>
- </type>
<desc>
- <p>Returns the tuple <c>{value, Item}</c> where <c>Item</c> is the
- rear item of <c>Q</c>, or <c>empty</c> if <c>Q1</c> is empty.</p>
+ <p>Returns the tuple <c>{value, <anno>Item</anno>}</c> where <c><anno>Item</anno></c> is the
+ rear item of <c><anno>Q</anno></c>, or <c>empty</c> if <c><anno>Q</anno></c> is empty.</p>
</desc>
</func>
</funcs>
@@ -372,80 +302,56 @@
<funcs>
<func>
- <name>cons(Item, Q1) -> Q2</name>
+ <name name="cons" arity="2"/>
<fsummary>Insert an item at the head of a queue</fsummary>
- <type>
- <v>Item = term()</v>
- <v>Q1 = Q2 = queue()</v>
- </type>
<desc>
- <p>Inserts <c>Item</c> at the head of queue <c>Q1</c>. Returns
- the new queue <c>Q2</c>.</p>
+ <p>Inserts <c><anno>Item</anno></c> at the head of queue <c><anno>Q1</anno></c>. Returns
+ the new queue <c><anno>Q2</anno></c>.</p>
</desc>
</func>
<func>
- <name>head(Q) -> Item</name>
+ <name name="head" arity="1"/>
<fsummary>Return the item at the head of a queue</fsummary>
- <type>
- <v>Item = term()</v>
- <v>Q = queue()</v>
- </type>
<desc>
- <p>Returns <c>Item</c> from the head of queue <c>Q</c>.</p>
- <p>Fails with reason <c>empty</c> if <c>Q</c> is empty.</p>
+ <p>Returns <c><anno>Item</anno></c> from the head of queue <c><anno>Q</anno></c>.</p>
+ <p>Fails with reason <c>empty</c> if <c><anno>Q</anno></c> is empty.</p>
</desc>
</func>
<func>
- <name>tail(Q1) -> Q2</name>
+ <name name="tail" arity="1"/>
<fsummary>Remove the head item from a queue</fsummary>
- <type>
- <v>Item = term()</v>
- <v>Q1 = Q2 = queue()</v>
- </type>
<desc>
- <p>Returns a queue <c>Q2</c> that is the result of removing
- the head item from <c>Q1</c>.</p>
- <p>Fails with reason <c>empty</c> if <c>Q1</c> is empty.</p>
+ <p>Returns a queue <c><anno>Q2</anno></c> that is the result of removing
+ the head item from <c><anno>Q1</anno></c>.</p>
+ <p>Fails with reason <c>empty</c> if <c><anno>Q1</anno></c> is empty.</p>
</desc>
</func>
<func>
- <name>snoc(Q1, Item) -> Q2</name>
+ <name name="snoc" arity="2"/>
<fsummary>Insert an item at the tail of a queue</fsummary>
- <type>
- <v>Item = term()</v>
- <v>Q1 = Q2 = queue()</v>
- </type>
<desc>
- <p>Inserts <c>Item</c> as the tail item of queue <c>Q1</c>. Returns
- the new queue <c>Q2</c>.</p>
+ <p>Inserts <c><anno>Item</anno></c> as the tail item of queue <c><anno>Q1</anno></c>. Returns
+ the new queue <c><anno>Q2</anno></c>.</p>
</desc>
</func>
<func>
- <name>daeh(Q) -> Item</name>
- <name>last(Q) -> Item</name>
+ <name name="daeh" arity="1"/>
+ <name name="last" arity="1"/>
<fsummary>Return the tail item of a queue</fsummary>
- <type>
- <v>Item = term()</v>
- <v>Q = queue()</v>
- </type>
<desc>
- <p>Returns the tail item of queue <c>Q</c>.</p>
- <p>Fails with reason <c>empty</c> if <c>Q</c> is empty.</p>
+ <p>Returns the tail item of queue <c><anno>Q</anno></c>.</p>
+ <p>Fails with reason <c>empty</c> if <c><anno>Q</anno></c> is empty.</p>
</desc>
</func>
<func>
- <name>liat(Q1) -> Q2</name>
- <name>init(Q1) -> Q2</name>
- <name>lait(Q1) -> Q2</name>
+ <name name="liat" arity="1"/>
+ <name name="init" arity="1"/>
+ <name name="lait" arity="1"/>
<fsummary>Remove the tail item from a queue</fsummary>
- <type>
- <v>Item = term()</v>
- <v>Q1 = Q2 = queue()</v>
- </type>
<desc>
- <p>Returns a queue <c>Q2</c> that is the result of removing
- the tail item from <c>Q1</c>.</p>
- <p>Fails with reason <c>empty</c> if <c>Q1</c> is empty.</p>
+ <p>Returns a queue <c><anno>Q2</anno></c> that is the result of removing
+ the tail item from <c><anno>Q1</anno></c>.</p>
+ <p>Fails with reason <c>empty</c> if <c><anno>Q1</anno></c> is empty.</p>
<p>The name <c>lait/1</c> is a misspelling - do not use it anymore.</p>
</desc>
</func>