aboutsummaryrefslogtreecommitdiffstats
path: root/lib/stdlib/doc/src/lists.xml
diff options
context:
space:
mode:
authorBjörn Gustavsson <[email protected]>2016-06-13 12:33:50 +0200
committerBjörn Gustavsson <[email protected]>2016-06-13 12:33:50 +0200
commit1280c70da91b90592ae4be88f1f045956e716de7 (patch)
tree42a0b48e54a9b5c982ce606b8c7e7ff9c564ade6 /lib/stdlib/doc/src/lists.xml
parent3873cb650711342aced0036e3c2d640df8a73c4b (diff)
parent68d53c01b0b8e9a007a6a30158c19e34b2d2a34e (diff)
downloadotp-1280c70da91b90592ae4be88f1f045956e716de7.tar.gz
otp-1280c70da91b90592ae4be88f1f045956e716de7.tar.bz2
otp-1280c70da91b90592ae4be88f1f045956e716de7.zip
Merge branch 'bjorn/stdlib/doc'
* bjorn/stdlib/doc: Update STDLIB documentation
Diffstat (limited to 'lib/stdlib/doc/src/lists.xml')
-rw-r--r--lib/stdlib/doc/src/lists.xml734
1 files changed, 438 insertions, 296 deletions
diff --git a/lib/stdlib/doc/src/lists.xml b/lib/stdlib/doc/src/lists.xml
index 03d0063599..60dbae70c2 100644
--- a/lib/stdlib/doc/src/lists.xml
+++ b/lib/stdlib/doc/src/lists.xml
@@ -25,11 +25,11 @@
<title>lists</title>
<prepared>Robert Virding</prepared>
<docno>1</docno>
- <date>96-09-28</date>
+ <date>1996-09-28</date>
<rev>A</rev>
</header>
<module>lists</module>
- <modulesummary>List Processing Functions</modulesummary>
+ <modulesummary>List processing functions.</modulesummary>
<description>
<p>This module contains functions for list processing.</p>
@@ -44,132 +44,156 @@
<p>Whenever an <marker
id="ordering_function"></marker><em>ordering function</em>
<c>F</c> is expected as argument, it is assumed that the
- following properties hold of <c>F</c> for all x, y and z:</p>
+ following properties hold of <c>F</c> for all x, y, and z:</p>
+
<list type="bulleted">
- <item><p>if x <c>F</c> y and y <c>F</c> x then x = y (<c>F</c>
- is antisymmetric);</p>
+ <item><p>If x <c>F</c> y and y <c>F</c> x, then x = y (<c>F</c>
+ is antisymmetric).</p>
</item>
- <item><p>if x <c>F</c> y and y <c>F</c> z then x <c>F</c> z
- (<c>F</c> is transitive);</p>
+ <item><p>If x <c>F</c> y and y <c>F</c> z, then x <c>F</c> z
+ (<c>F</c> is transitive).</p>
</item>
<item><p>x <c>F</c> y or y <c>F</c> x (<c>F</c> is total).</p>
</item>
</list>
- <p>An example of a typical ordering function is less than or equal
- to, <c>=&lt;/2</c>.</p>
+ <p>An example of a typical ordering function is less than or equal
+ to: <c>=&lt;/2</c>.</p>
</description>
+
<funcs>
<func>
<name name="all" arity="2"/>
- <fsummary>Return true if all elements in the list satisfy<c>Pred</c></fsummary>
+ <fsummary>Return <c>true</c> if all elements in a list satisfy
+ <c>Pred</c>.</fsummary>
<desc>
- <p>Returns <c>true</c> if <c><anno>Pred</anno>(<anno>Elem</anno>)</c> returns
- <c>true</c> for all elements <c><anno>Elem</anno></c> in <c><anno>List</anno></c>,
- otherwise <c>false</c>.</p>
+ <p>Returns <c>true</c> if <c><anno>Pred</anno>(<anno>Elem</anno>)</c>
+ returns <c>true</c> for all elements <c><anno>Elem</anno></c> in
+ <c><anno>List</anno></c>, otherwise <c>false</c>.</p>
</desc>
</func>
+
<func>
<name name="any" arity="2"/>
- <fsummary>Return true if any of the elements in the list satisfies<c>Pred</c></fsummary>
+ <fsummary>Return <c>true</c> if any of the elements in a list
+ satisfies <c>Pred</c>.</fsummary>
<desc>
- <p>Returns <c>true</c> if <c><anno>Pred</anno>(<anno>Elem</anno>)</c> returns
- <c>true</c> for at least one element <c><anno>Elem</anno></c> in
- <c><anno>List</anno></c>.</p>
+ <p>Returns <c>true</c> if <c><anno>Pred</anno>(<anno>Elem</anno>)</c>
+ returns <c>true</c> for at least one element <c><anno>Elem</anno></c>
+ in <c><anno>List</anno></c>.</p>
</desc>
</func>
+
<func>
<name name="append" arity="1"/>
- <fsummary>Append a list of lists</fsummary>
+ <fsummary>Append a list of lists.</fsummary>
<desc>
- <p>Returns a list in which all the sub-lists of
- <c><anno>ListOfLists</anno></c> have been appended. For example:</p>
+ <p>Returns a list in which all the sublists of
+ <c><anno>ListOfLists</anno></c> have been appended.</p>
+ <p><em>Example:</em></p>
<pre>
> <input>lists:append([[1, 2, 3], [a, b], [4, 5, 6]]).</input>
[1,2,3,a,b,4,5,6]</pre>
</desc>
</func>
+
<func>
<name name="append" arity="2"/>
- <fsummary>Append two lists</fsummary>
+ <fsummary>Append two lists.</fsummary>
<desc>
- <p>Returns a new list <c><anno>List3</anno></c> which is made from
+ <p>Returns a new list <c><anno>List3</anno></c>, which is made from
the elements of <c><anno>List1</anno></c> followed by the elements of
- <c><anno>List2</anno></c>. For example:</p>
+ <c><anno>List2</anno></c>.</p>
+ <p><em>Example:</em></p>
<pre>
> <input>lists:append("abc", "def").</input>
"abcdef"</pre>
<p><c>lists:append(A, B)</c> is equivalent to <c>A ++ B</c>.</p>
</desc>
</func>
+
<func>
<name name="concat" arity="1"/>
- <fsummary>Concatenate a list of atoms</fsummary>
+ <fsummary>Concatenate a list of atoms.</fsummary>
<desc>
- <p>Concatenates the text representation of the elements
- of <c><anno>Things</anno></c>. The elements of <c><anno>Things</anno></c> can be atoms,
- integers, floats or strings.</p>
+ <p>Concatenates the text representation of the elements of
+ <c><anno>Things</anno></c>. The elements of <c><anno>Things</anno></c>
+ can be atoms, integers, floats, or strings.</p>
+ <p><em>Example:</em></p>
<pre>
> <input>lists:concat([doc, '/', file, '.', 3]).</input>
"doc/file.3"</pre>
</desc>
</func>
+
<func>
<name name="delete" arity="2"/>
- <fsummary>Delete an element from a list</fsummary>
+ <fsummary>Delete an element from a list.</fsummary>
<desc>
<p>Returns a copy of <c><anno>List1</anno></c> where the first element
matching <c><anno>Elem</anno></c> is deleted, if there is such an
element.</p>
</desc>
</func>
+
<func>
<name name="droplast" arity="1"/>
- <fsummary>Drop the last element of a list</fsummary>
+ <fsummary>Drop the last element of a list.</fsummary>
<desc>
- <p>Drops the last element of a <c><anno>List</anno></c>. The list should
- be non-empty, otherwise the function will crash with a <c>function_clause</c></p>
+ <p>Drops the last element of a <c><anno>List</anno></c>. The list is to
+ be non-empty, otherwise the function crashes with a
+ <c>function_clause</c>.</p>
</desc>
</func>
+
<func>
<name name="dropwhile" arity="2"/>
- <fsummary>Drop elements from a list while a predicate is true</fsummary>
+ <fsummary>Drop elements from a list while a predicate is <c>true</c>.
+ </fsummary>
<desc>
- <p>Drops elements <c><anno>Elem</anno></c> from <c><anno>List1</anno></c> while
- <c><anno>Pred</anno>(<anno>Elem</anno>)</c> returns <c>true</c> and returns
- the remaining list.</p>
+ <p>Drops elements <c><anno>Elem</anno></c> from
+ <c><anno>List1</anno></c> while
+ <c><anno>Pred</anno>(<anno>Elem</anno>)</c> returns <c>true</c> and
+ returns the remaining list.</p>
</desc>
</func>
+
<func>
<name name="duplicate" arity="2"/>
- <fsummary>Make N copies of element</fsummary>
+ <fsummary>Make <c>N</c> copies of element.</fsummary>
<desc>
- <p>Returns a list which contains <c><anno>N</anno></c> copies of the term
- <c><anno>Elem</anno></c>. For example:</p>
+ <p>Returns a list containing <c><anno>N</anno></c> copies of term
+ <c><anno>Elem</anno></c>.</p>
+ <p><em>Example:</em></p>
<pre>
> <input>lists:duplicate(5, xx).</input>
[xx,xx,xx,xx,xx]</pre>
</desc>
</func>
+
<func>
<name name="filter" arity="2"/>
- <fsummary>Choose elements which satisfy a predicate</fsummary>
+ <fsummary>Select elements that satisfy a predicate.</fsummary>
<desc>
- <p><c><anno>List2</anno></c> is a list of all elements <c><anno>Elem</anno></c> in
- <c><anno>List1</anno></c> for which <c><anno>Pred</anno>(<anno>Elem</anno>)</c> returns
- <c>true</c>.</p>
+ <p><c><anno>List2</anno></c> is a list of all elements
+ <c><anno>Elem</anno></c> in <c><anno>List1</anno></c> for which
+ <c><anno>Pred</anno>(<anno>Elem</anno>)</c> returns <c>true</c>.</p>
</desc>
</func>
+
<func>
<name name="filtermap" arity="2"/>
- <fsummary>Filter and map elements which satisfy a function</fsummary>
- <desc>
- <p>Calls <c><anno>Fun</anno>(<anno>Elem</anno>)</c> on successive elements <c>Elem</c>
- of <c><anno>List1</anno></c>. <c><anno>Fun</anno>/2</c> must return either a boolean
- or a tuple <c>{true, <anno>Value</anno>}</c>. The function returns the list of elements
- for which <c><anno>Fun</anno></c> returns a new value, where a value of <c>true</c>
- is synonymous with <c>{true, <anno>Elem</anno>}</c>.</p>
- <p>That is, <c>filtermap</c> behaves as if it had been defined as follows:</p>
+ <fsummary>Filter and map elements that satisfy a function.</fsummary>
+ <desc>
+ <p>Calls <c><anno>Fun</anno>(<anno>Elem</anno>)</c> on successive
+ elements <c>Elem</c> of <c><anno>List1</anno></c>.
+ <c><anno>Fun</anno>/2</c> must return either a Boolean or a tuple
+ <c>{true, <anno>Value</anno>}</c>. The function returns the list of
+ elements for which <c><anno>Fun</anno></c> returns a new value, where
+ a value of <c>true</c> is synonymous with
+ <c>{true, <anno>Elem</anno>}</c>.</p>
+ <p>That is, <c>filtermap</c> behaves as if it had been defined as
+ follows:</p>
<code type="none">
filtermap(Fun, List1) ->
lists:foldr(fun(Elem, Acc) ->
@@ -179,26 +203,29 @@ filtermap(Fun, List1) ->
{true,Value} -> [Value|Acc]
end
end, [], List1).</code>
- <p>Example:</p>
+ <p><em>Example:</em></p>
<pre>
> <input>lists:filtermap(fun(X) -> case X rem 2 of 0 -> {true, X div 2}; _ -> false end end, [1,2,3,4,5]).</input>
[1,2]</pre>
</desc>
</func>
+
<func>
<name name="flatlength" arity="1"/>
- <fsummary>Length of flattened deep list</fsummary>
+ <fsummary>Length of flattened deep list.</fsummary>
<desc>
- <p>Equivalent to <c>length(flatten(<anno>DeepList</anno>))</c>, but more
- efficient.</p>
+ <p>Equivalent to <c>length(flatten(<anno>DeepList</anno>))</c>, but
+ more efficient.</p>
</desc>
</func>
+
<func>
<name name="flatmap" arity="2"/>
- <fsummary>Map and flatten in one pass</fsummary>
+ <fsummary>Map and flatten in one pass.</fsummary>
<desc>
- <p>Takes a function from <c><anno>A</anno></c>s to lists of <c><anno>B</anno></c>s, and a
- list of <c><anno>A</anno></c>s (<c><anno>List1</anno></c>) and produces a list of
+ <p>Takes a function from <c><anno>A</anno></c>s to lists of
+ <c><anno>B</anno></c>s, and a list of <c><anno>A</anno></c>s
+ (<c><anno>List1</anno></c>) and produces a list of
<c><anno>B</anno></c>s by applying the function to every element in
<c><anno>List1</anno></c> and appending the resulting lists.</p>
<p>That is, <c>flatmap</c> behaves as if it had been defined as
@@ -206,37 +233,42 @@ filtermap(Fun, List1) ->
<code type="none">
flatmap(Fun, List1) ->
append(map(Fun, List1)).</code>
- <p>Example:</p>
+ <p><em>Example:</em></p>
<pre>
> <input>lists:flatmap(fun(X)->[X,X] end, [a,b,c]).</input>
[a,a,b,b,c,c]</pre>
</desc>
</func>
+
<func>
<name name="flatten" arity="1"/>
- <fsummary>Flatten a deep list</fsummary>
+ <fsummary>Flatten a deep list.</fsummary>
<desc>
<p>Returns a flattened version of <c><anno>DeepList</anno></c>.</p>
</desc>
</func>
+
<func>
<name name="flatten" arity="2"/>
- <fsummary>Flatten a deep list</fsummary>
+ <fsummary>Flatten a deep list.</fsummary>
<desc>
- <p>Returns a flattened version of <c><anno>DeepList</anno></c> with the tail
+ <p>Returns a flattened version of <c><anno>DeepList</anno></c> with tail
<c><anno>Tail</anno></c> appended.</p>
</desc>
</func>
+
<func>
<name name="foldl" arity="3"/>
- <fsummary>Fold a function over a list</fsummary>
- <desc>
- <p>Calls <c><anno>Fun</anno>(<anno>Elem</anno>, <anno>AccIn</anno>)</c> on successive elements <c>A</c>
- of <c><anno>List</anno></c>, starting with <c><anno>AccIn</anno> == <anno>Acc0</anno></c>.
- <c><anno>Fun</anno>/2</c> must return a new accumulator which is passed to
- the next call. The function returns the final value of
- the accumulator. <c><anno>Acc0</anno></c> is returned if the list is empty.
- For example:</p>
+ <fsummary>Fold a function over a list.</fsummary>
+ <desc>
+ <p>Calls <c><anno>Fun</anno>(<anno>Elem</anno>, <anno>AccIn</anno>)</c>
+ on successive elements <c>A</c> of <c><anno>List</anno></c>, starting
+ with <c><anno>AccIn</anno> == <anno>Acc0</anno></c>.
+ <c><anno>Fun</anno>/2</c> must return a new accumulator, which is
+ passed to the next call. The function returns the final value of
+ the accumulator. <c><anno>Acc0</anno></c> is returned if the list is
+ empty.</p>
+ <p><em>Example:</em></p>
<pre>
> <input>lists:foldl(fun(X, Sum) -> X + Sum end, 0, [1,2,3,4,5]).</input>
15
@@ -244,12 +276,14 @@ flatmap(Fun, List1) ->
120</pre>
</desc>
</func>
+
<func>
<name name="foldr" arity="3"/>
- <fsummary>Fold a function over a list</fsummary>
+ <fsummary>Fold a function over a list.</fsummary>
<desc>
- <p>Like <c>foldl/3</c>, but the list is traversed from right to
- left. For example:</p>
+ <p>Like <seealso marker="#foldl/3"><c>foldl/3</c></seealso>, but the
+ list is traversed from right to left.</p>
+ <p><em>Example:</em></p>
<pre>
> <input>P = fun(A, AccIn) -> io:format("~p ", [A]), AccIn end.</input>
#Fun&lt;erl_eval.12.2225172&gt;
@@ -257,10 +291,11 @@ flatmap(Fun, List1) ->
1 2 3 void
> <input>lists:foldr(P, void, [1,2,3]).</input>
3 2 1 void</pre>
- <p><c>foldl/3</c> is tail recursive and would usually be
- preferred to <c>foldr/3</c>.</p>
+ <p><c>foldl/3</c> is tail recursive and is usually preferred to
+ <c>foldr/3</c>.</p>
</desc>
</func>
+
<func>
<name name="join" arity="2"/>
<fsummary>Insert an element between elements in a list</fsummary>
@@ -278,45 +313,52 @@ flatmap(Fun, List1) ->
</func>
<func>
<name name="foreach" arity="2"/>
- <fsummary>Apply a function to each element of a list</fsummary>
+ <fsummary>Apply a function to each element of a list.</fsummary>
<desc>
- <p>Calls <c><anno>Fun</anno>(<anno>Elem</anno>)</c> for each element <c><anno>Elem</anno></c> in
- <c><anno>List</anno></c>. This function is used for its side effects and
+ <p>Calls <c><anno>Fun</anno>(<anno>Elem</anno>)</c> for each element
+ <c><anno>Elem</anno></c> in <c><anno>List</anno></c>. This function
+ is used for its side effects and
the evaluation order is defined to be the same as the order
of the elements in the list.</p>
</desc>
</func>
+
<func>
<name name="keydelete" arity="3"/>
- <fsummary>Delete an element from a list of tuples</fsummary>
+ <fsummary>Delete an element from a list of tuples.</fsummary>
<type_desc variable="N">1..tuple_size(<anno>Tuple</anno>)</type_desc>
<desc>
<p>Returns a copy of <c><anno>TupleList1</anno></c> where the first
- occurrence of a tuple whose <c><anno>N</anno></c>th element compares equal to
+ occurrence of a tuple whose <c><anno>N</anno></c>th element compares
+ equal to
<c><anno>Key</anno></c> is deleted, if there is such a tuple.</p>
</desc>
</func>
+
<func>
<name name="keyfind" arity="3"/>
- <fsummary>Search for an element in a list of tuples</fsummary>
+ <fsummary>Search for an element in a list of tuples.</fsummary>
<type_desc variable="N">1..tuple_size(<anno>Tuple</anno>)</type_desc>
<desc>
<p>Searches the list of tuples <c><anno>TupleList</anno></c> for a
- tuple whose <c><anno>N</anno></c>th element compares equal to <c><anno>Key</anno></c>.
+ tuple whose <c><anno>N</anno></c>th element compares equal to
+ <c><anno>Key</anno></c>.
Returns <c><anno>Tuple</anno></c> if such a tuple is found,
otherwise <c>false</c>.</p>
</desc>
</func>
+
<func>
<name name="keymap" arity="3"/>
- <fsummary>Map a function over a list of tuples</fsummary>
+ <fsummary>Map a function over a list of tuples.</fsummary>
<type_desc variable="N">1..tuple_size(<anno>Tuple</anno>)</type_desc>
<desc>
<p>Returns a list of tuples where, for each tuple in
- <c><anno>TupleList1</anno></c>, the <c><anno>N</anno></c>th element <c><anno>Term1</anno></c> of the tuple
+ <c><anno>TupleList1</anno></c>, the <c><anno>N</anno></c>th element
+ <c><anno>Term1</anno></c> of the tuple
has been replaced with the result of calling
<c><anno>Fun</anno>(<anno>Term1</anno>)</c>.</p>
- <p>Examples:</p>
+ <p><em>Examples:</em></p>
<pre>
> <input>Fun = fun(Atom) -> atom_to_list(Atom) end.</input>
#Fun&lt;erl_eval.6.10732646&gt;
@@ -324,33 +366,37 @@ flatmap(Fun, List1) ->
[{name,"jane",22},{name,"lizzie",20},{name,"lydia",15}]</pre>
</desc>
</func>
+
<func>
<name name="keymember" arity="3"/>
- <fsummary>Test for membership of a list of tuples</fsummary>
+ <fsummary>Test for membership of a list of tuples.</fsummary>
<type_desc variable="N">1..tuple_size(<anno>Tuple</anno>)</type_desc>
<desc>
- <p>Returns <c>true</c> if there is a tuple in <c><anno>TupleList</anno></c>
- whose <c><anno>N</anno></c>th element compares equal to <c><anno>Key</anno></c>, otherwise
- <c>false</c>.</p>
+ <p>Returns <c>true</c> if there is a tuple in
+ <c><anno>TupleList</anno></c> whose <c><anno>N</anno></c>th element
+ compares equal to <c><anno>Key</anno></c>, otherwise <c>false</c>.</p>
</desc>
</func>
+
<func>
<name name="keymerge" arity="3"/>
- <fsummary>Merge two key-sorted lists of tuples</fsummary>
+ <fsummary>Merge two key-sorted lists of tuples.</fsummary>
<type_desc variable="N">1..tuple_size(<anno>Tuple</anno>)</type_desc>
<desc>
- <p>Returns the sorted list formed by merging <c><anno>TupleList1</anno></c>
- and <c><anno>TupleList2</anno></c>. The merge is performed on
- the <c><anno>N</anno></c>th element of each tuple. Both <c><anno>TupleList1</anno></c> and
- <c><anno>TupleList2</anno></c> must be key-sorted prior to evaluating this
- function. When two tuples compare equal, the tuple from
+ <p>Returns the sorted list formed by merging
+ <c><anno>TupleList1</anno></c> and <c><anno>TupleList2</anno></c>.
+ The merge is performed on the <c><anno>N</anno></c>th element of each
+ tuple. Both <c><anno>TupleList1</anno></c> and
+ <c><anno>TupleList2</anno></c> must be key-sorted before evaluating
+ this function. When two tuples compare equal, the tuple from
<c><anno>TupleList1</anno></c> is picked before the tuple from
<c><anno>TupleList2</anno></c>.</p>
</desc>
</func>
+
<func>
<name name="keyreplace" arity="4"/>
- <fsummary>Replace an element in a list of tuples</fsummary>
+ <fsummary>Replace an element in a list of tuples.</fsummary>
<type_desc variable="N">1..tuple_size(<anno>Tuple</anno>)</type_desc>
<desc>
<p>Returns a copy of <c><anno>TupleList1</anno></c> where the first
@@ -359,193 +405,226 @@ flatmap(Fun, List1) ->
<c><anno>NewTuple</anno></c>, if there is such a tuple <c>T</c>.</p>
</desc>
</func>
+
<func>
<name name="keysearch" arity="3"/>
- <fsummary>Search for an element in a list of tuples</fsummary>
+ <fsummary>Search for an element in a list of tuples.</fsummary>
<type_desc variable="N">1..tuple_size(<anno>Tuple</anno>)</type_desc>
<desc>
<p>Searches the list of tuples <c><anno>TupleList</anno></c> for a
- tuple whose <c><anno>N</anno></c>th element compares equal to <c><anno>Key</anno></c>.
+ tuple whose <c><anno>N</anno></c>th element compares equal to
+ <c><anno>Key</anno></c>.
Returns <c>{value, <anno>Tuple</anno>}</c> if such a tuple is found,
otherwise <c>false</c>.</p>
- <note><p>This function is retained for backward compatibility.
- The function <c>lists:keyfind/3</c> (introduced in R13A)
- is in most cases more convenient.</p></note>
+ <note>
+ <p>This function is retained for backward compatibility. Function
+ <seealso marker="#keyfind/3"><c>keyfind/3</c></seealso>
+ is usually more convenient.</p>
+ </note>
</desc>
</func>
+
<func>
<name name="keysort" arity="2"/>
- <fsummary>Sort a list of tuples</fsummary>
+ <fsummary>Sort a list of tuples.</fsummary>
<type_desc variable="N">1..tuple_size(<anno>Tuple</anno>)</type_desc>
<desc>
- <p>Returns a list containing the sorted elements of the list
- <c><anno>TupleList1</anno></c>. Sorting is performed on the <c><anno>N</anno></c>th
- element of the tuples. The sort is stable.</p>
+ <p>Returns a list containing the sorted elements of list
+ <c><anno>TupleList1</anno></c>. Sorting is performed on the
+ <c><anno>N</anno></c>th element of the tuples. The sort is stable.</p>
</desc>
</func>
+
<func>
<name name="keystore" arity="4"/>
- <fsummary>Store an element in a list of tuples</fsummary>
+ <fsummary>Store an element in a list of tuples.</fsummary>
<type_desc variable="N">1..tuple_size(<anno>Tuple</anno>)</type_desc>
<desc>
<p>Returns a copy of <c><anno>TupleList1</anno></c> where the first
occurrence of a tuple <c>T</c> whose <c><anno>N</anno></c>th element
compares equal to <c><anno>Key</anno></c> is replaced with
- <c><anno>NewTuple</anno></c>, if there is such a tuple <c>T</c>. If there
- is no such tuple <c>T</c> a copy of <c><anno>TupleList1</anno></c> where
+ <c><anno>NewTuple</anno></c>, if there is such a tuple <c>T</c>.
+ If there is no such tuple <c>T</c>, a copy of
+ <c><anno>TupleList1</anno></c> where
[<c><anno>NewTuple</anno></c>] has been appended to the end is
returned.</p>
</desc>
</func>
+
<func>
<name name="keytake" arity="3"/>
- <fsummary>Extract an element from a list of tuples</fsummary>
+ <fsummary>Extract an element from a list of tuples.</fsummary>
<type_desc variable="N">1..tuple_size(<anno>Tuple</anno>)</type_desc>
<desc>
- <p>Searches the list of tuples <c><anno>TupleList1</anno></c> for a tuple
- whose <c><anno>N</anno></c>th element compares equal to <c><anno>Key</anno></c>.
- Returns <c>{value, <anno>Tuple</anno>, <anno>TupleList2</anno>}</c> if such a tuple is
- found, otherwise <c>false</c>. <c><anno>TupleList2</anno></c> is a copy
+ <p>Searches the list of tuples <c><anno>TupleList1</anno></c> for a
+ tuple whose <c><anno>N</anno></c>th element compares equal to
+ <c><anno>Key</anno></c>. Returns <c>{value, <anno>Tuple</anno>,
+ <anno>TupleList2</anno>}</c> if such a tuple is found, otherwise
+ <c>false</c>. <c><anno>TupleList2</anno></c> is a copy
of <c><anno>TupleList1</anno></c> where the first occurrence of
<c><anno>Tuple</anno></c> has been removed.</p>
</desc>
</func>
+
<func>
<name name="last" arity="1"/>
- <fsummary>Return last element in a list</fsummary>
+ <fsummary>Return last element in a list.</fsummary>
<desc>
<p>Returns the last element in <c><anno>List</anno></c>.</p>
</desc>
</func>
+
<func>
<name name="map" arity="2"/>
- <fsummary>Map a function over a list</fsummary>
+ <fsummary>Map a function over a list.</fsummary>
<desc>
- <p>Takes a function from <c><anno>A</anno></c>s to <c><anno>B</anno></c>s, and a list of
- <c><anno>A</anno></c>s and produces a list of <c><anno>B</anno></c>s by applying
+ <p>Takes a function from <c><anno>A</anno></c>s to
+ <c><anno>B</anno></c>s, and a list of <c><anno>A</anno></c>s and
+ produces a list of <c><anno>B</anno></c>s by applying
the function to every element in the list. This function is
- used to obtain the return values. The evaluation order is
- implementation dependent.</p>
+ used to obtain the return values. The evaluation order depends on
+ the implementation.</p>
</desc>
</func>
+
<func>
<name name="mapfoldl" arity="3"/>
- <fsummary>Map and fold in one pass</fsummary>
+ <fsummary>Map and fold in one pass.</fsummary>
<desc>
- <p><c>mapfoldl</c> combines the operations of <c>map/2</c> and
- <c>foldl/3</c> into one pass. An example, summing
- the elements in a list and double them at the same time:</p>
+ <p>Combines the operations of
+ <seealso marker="#map/2"><c>map/2</c></seealso> and
+ <seealso marker="#foldl/3"><c>foldl/3</c></seealso> into one pass.</p>
+ <p><em>Example:</em></p>
+ <p>Summing the elements in a list and double them at the same time:</p>
<pre>
> <input>lists:mapfoldl(fun(X, Sum) -> {2*X, X+Sum} end,</input>
<input>0, [1,2,3,4,5]).</input>
{[2,4,6,8,10],15}</pre>
</desc>
</func>
+
<func>
<name name="mapfoldr" arity="3"/>
- <fsummary>Map and fold in one pass</fsummary>
+ <fsummary>Map and fold in one pass.</fsummary>
<desc>
- <p><c>mapfoldr</c> combines the operations of <c>map/2</c> and
- <c>foldr/3</c> into one pass.</p>
+ <p>Combines the operations of
+ <seealso marker="#map/2"><c>map/2</c></seealso> and
+ <seealso marker="#foldr/3"><c>foldr/3</c></seealso> into one pass.</p>
</desc>
</func>
+
<func>
<name name="max" arity="1"/>
- <fsummary>Return maximum element of a list</fsummary>
+ <fsummary>Return maximum element of a list.</fsummary>
<desc>
<p>Returns the first element of <c><anno>List</anno></c> that compares
greater than or equal to all other elements of
<c><anno>List</anno></c>.</p>
</desc>
</func>
+
<func>
<name name="member" arity="2"/>
- <fsummary>Test for membership of a list</fsummary>
+ <fsummary>Test for membership of a list.</fsummary>
<desc>
- <p>Returns <c>true</c> if <c><anno>Elem</anno></c> matches some element of
- <c><anno>List</anno></c>, otherwise <c>false</c>.</p>
+ <p>Returns <c>true</c> if <c><anno>Elem</anno></c> matches some element
+ of <c><anno>List</anno></c>, otherwise <c>false</c>.</p>
</desc>
</func>
+
<func>
<name name="merge" arity="1"/>
- <fsummary>Merge a list of sorted lists</fsummary>
+ <fsummary>Merge a list of sorted lists.</fsummary>
<desc>
- <p>Returns the sorted list formed by merging all the sub-lists
- of <c><anno>ListOfLists</anno></c>. All sub-lists must be sorted prior to
+ <p>Returns the sorted list formed by merging all the sublists of
+ <c><anno>ListOfLists</anno></c>. All sublists must be sorted before
evaluating this function. When two elements compare equal,
- the element from the sub-list with the lowest position in
- <c><anno>ListOfLists</anno></c> is picked before the other element.</p>
+ the element from the sublist with the lowest position in
+ <c><anno>ListOfLists</anno></c> is picked before the other
+ element.</p>
</desc>
</func>
+
<func>
<name name="merge" arity="2"/>
- <fsummary>Merge two sorted lists</fsummary>
+ <fsummary>Merge two sorted lists.</fsummary>
<desc>
- <p>Returns the sorted list formed by merging <c><anno>List1</anno></c> and
- <c><anno>List2</anno></c>. Both <c><anno>List1</anno></c> and <c><anno>List2</anno></c> must be
- sorted prior to evaluating this function. When two elements
+ <p>Returns the sorted list formed by merging <c><anno>List1</anno></c>
+ and <c><anno>List2</anno></c>. Both <c><anno>List1</anno></c> and
+ <c><anno>List2</anno></c> must be
+ sorted before evaluating this function. When two elements
compare equal, the element from <c><anno>List1</anno></c> is picked
before the element from <c><anno>List2</anno></c>.</p>
</desc>
</func>
+
<func>
<name name="merge" arity="3"/>
- <fsummary>Merge two sorted list</fsummary>
+ <fsummary>Merge two sorted list.</fsummary>
<desc>
- <p>Returns the sorted list formed by merging <c><anno>List1</anno></c> and
- <c><anno>List2</anno></c>. Both <c><anno>List1</anno></c> and <c><anno>List2</anno></c> must be
- sorted according to the <seealso
+ <p>Returns the sorted list formed by merging <c><anno>List1</anno></c>
+ and <c><anno>List2</anno></c>. Both <c><anno>List1</anno></c> and
+ <c><anno>List2</anno></c> must be sorted according to the <seealso
marker="#ordering_function">ordering function</seealso>
- <c><anno>Fun</anno></c> prior to evaluating this function. <c><anno>Fun</anno>(<anno>A</anno>,
- <anno>B</anno>)</c> should return <c>true</c> if <c><anno>A</anno></c> compares less
- than or equal to <c><anno>B</anno></c> in the ordering, <c>false</c>
- otherwise. When two elements compare equal, the element from
+ <c><anno>Fun</anno></c> before evaluating this function.
+ <c><anno>Fun</anno>(<anno>A</anno>, <anno>B</anno>)</c> is to return
+ <c>true</c> if <c><anno>A</anno></c> compares less
+ than or equal to <c><anno>B</anno></c> in the ordering, otherwise
+ <c>false</c>. When two elements compare equal, the element from
<c><anno>List1</anno></c> is picked before the element from
<c><anno>List2</anno></c>.</p>
</desc>
</func>
+
<func>
<name name="merge3" arity="3"/>
- <fsummary>Merge three sorted lists</fsummary>
+ <fsummary>Merge three sorted lists.</fsummary>
<desc>
<p>Returns the sorted list formed by merging <c><anno>List1</anno></c>,
- <c><anno>List2</anno></c> and <c><anno>List3</anno></c>. All of <c><anno>List1</anno></c>,
- <c><anno>List2</anno></c> and <c><anno>List3</anno></c> must be sorted prior to
- evaluating this function. When two elements compare equal,
- the element from <c><anno>List1</anno></c>, if there is such an element,
+ <c><anno>List2</anno></c>, and <c><anno>List3</anno></c>. All of
+ <c><anno>List1</anno></c>, <c><anno>List2</anno></c>, and
+ <c><anno>List3</anno></c> must be sorted before evaluating this
+ function. When two elements compare equal, the element from
+ <c><anno>List1</anno></c>, if there is such an element,
is picked before the other element, otherwise the element
from <c><anno>List2</anno></c> is picked before the element from
<c><anno>List3</anno></c>.</p>
</desc>
</func>
+
<func>
<name name="min" arity="1"/>
- <fsummary>Return minimum element of a list</fsummary>
+ <fsummary>Return minimum element of a list.</fsummary>
<desc>
<p>Returns the first element of <c><anno>List</anno></c> that compares
less than or equal to all other elements of
<c><anno>List</anno></c>.</p>
</desc>
</func>
+
<func>
<name name="nth" arity="2"/>
- <fsummary>Return the Nth element of a list</fsummary>
+ <fsummary>Return the <c>N</c>th element of a list.</fsummary>
<type_desc variable="N">1..length(<anno>List</anno>)</type_desc>
<desc>
- <p>Returns the <c><anno>N</anno></c>th element of <c><anno>List</anno></c>. For example:</p>
+ <p>Returns the <c><anno>N</anno></c>th element of
+ <c><anno>List</anno></c>.</p>
+ <p><em>Example:</em></p>
<pre>
> <input>lists:nth(3, [a, b, c, d, e]).</input>
c</pre>
</desc>
</func>
+
<func>
<name name="nthtail" arity="2"/>
- <fsummary>Return the Nth tail of a list</fsummary>
+ <fsummary>Return the <c>N</c>th tail of a list.</fsummary>
<type_desc variable="N">0..length(<anno>List</anno>)</type_desc>
<desc>
- <p>Returns the <c><anno>N</anno></c>th tail of <c><anno>List</anno></c>, that is, the sublist of
- <c><anno>List</anno></c> starting at <c><anno>N</anno>+1</c> and continuing up to
- the end of the list. For example:</p>
+ <p>Returns the <c><anno>N</anno></c>th tail of <c><anno>List</anno></c>,
+ that is, the sublist of <c><anno>List</anno></c> starting at
+ <c><anno>N</anno>+1</c> and continuing up to the end of the list.</p>
+ <p><em>Example</em></p>
<pre>
> <input>lists:nthtail(3, [a, b, c, d, e]).</input>
[d,e]
@@ -557,70 +636,91 @@ c</pre>
[]</pre>
</desc>
</func>
+
<func>
<name name="partition" arity="2"/>
- <fsummary>Partition a list into two lists based on a predicate</fsummary>
- <desc>
- <p>Partitions <c><anno>List</anno></c> into two lists, where the first list
- contains all elements for which <c><anno>Pred</anno>(<anno>Elem</anno>)</c> returns
- <c>true</c>, and the second list contains all elements for
- which <c><anno>Pred</anno>(<anno>Elem</anno>)</c> returns <c>false</c>.</p>
- <p>Examples:</p>
+ <fsummary>Partition a list into two lists based on a predicate.</fsummary>
+ <desc>
+ <p>Partitions <c><anno>List</anno></c> into two lists, where the first
+ list contains all elements for which
+ <c><anno>Pred</anno>(<anno>Elem</anno>)</c> returns <c>true</c>,
+ and the second list contains all elements for which
+ <c><anno>Pred</anno>(<anno>Elem</anno>)</c> returns <c>false</c>.</p>
+ <p><em>Examples:</em></p>
<pre>
> <input>lists:partition(fun(A) -> A rem 2 == 1 end, [1,2,3,4,5,6,7]).</input>
{[1,3,5,7],[2,4,6]}
> <input>lists:partition(fun(A) -> is_atom(A) end, [a,b,1,c,d,2,3,4,e]).</input>
{[a,b,c,d,e],[1,2,3,4]}</pre>
- <p>See also <c>splitwith/2</c> for a different way to partition
- a list.</p>
+ <p>For a different way to partition a list, see
+ <seealso marker="#splitwith/2"><c>splitwith/2</c></seealso>.</p>
</desc>
</func>
+
<func>
<name name="prefix" arity="2"/>
- <fsummary>Test for list prefix</fsummary>
+ <fsummary>Test for list prefix.</fsummary>
<desc>
<p>Returns <c>true</c> if <c><anno>List1</anno></c> is a prefix of
<c><anno>List2</anno></c>, otherwise <c>false</c>.</p>
</desc>
</func>
+
<func>
<name name="reverse" arity="1"/>
- <fsummary>Reverse a list</fsummary>
+ <fsummary>Reverse a list.</fsummary>
<desc>
<p>Returns a list with the elements in <c><anno>List1</anno></c>
in reverse order.</p>
</desc>
</func>
+
<func>
<name name="reverse" arity="2"/>
- <fsummary>Reverse a list appending a tail</fsummary>
+ <fsummary>Reverse a list appending a tail.</fsummary>
<desc>
<p>Returns a list with the elements in <c><anno>List1</anno></c>
- in reverse order, with the tail <c><anno>Tail</anno></c> appended. For
- example:</p>
+ in reverse order, with tail <c><anno>Tail</anno></c> appended.</p>
+ <p><em>Example:</em></p>
<pre>
> <input>lists:reverse([1, 2, 3, 4], [a, b, c]).</input>
[4,3,2,1,a,b,c]</pre>
</desc>
</func>
+
<func>
<name name="seq" arity="2"/>
<name name="seq" arity="3"/>
- <fsummary>Generate a sequence of integers</fsummary>
+ <fsummary>Generate a sequence of integers.</fsummary>
<desc>
- <p>Returns a sequence of integers which starts with <c><anno>From</anno></c>
- and contains the successive results of adding <c><anno>Incr</anno></c> to
- the previous element, until <c><anno>To</anno></c> has been reached or
- passed (in the latter case, <c><anno>To</anno></c> is not an element of
+ <p>Returns a sequence of integers that starts with
+ <c><anno>From</anno></c> and contains the successive results of
+ adding <c><anno>Incr</anno></c> to the previous element, until
+ <c><anno>To</anno></c> is reached or passed (in the latter case,
+ <c><anno>To</anno></c> is not an element of
the sequence). <c><anno>Incr</anno></c> defaults to 1.</p>
- <p>Failure: If <c><anno>To</anno>&lt;<anno>From</anno>-<anno>Incr</anno></c> and <c><anno>Incr</anno></c>
- is positive, or if <c><anno>To</anno>><anno>From</anno>-<anno>Incr</anno></c> and <c><anno>Incr</anno></c> is
- negative, or if <c><anno>Incr</anno>==0</c> and <c><anno>From</anno>/=<anno>To</anno></c>.</p>
+ <p>Failures:</p>
+ <list type="bulleted">
+ <item>
+ <p>If <c><anno>To</anno> &lt;
+ <anno>From</anno> - <anno>Incr</anno></c>
+ and <c><anno>Incr</anno> &gt; 0</c>.</p>
+ </item>
+ <item>
+ <p>If <c><anno>To</anno> &gt;
+ <anno>From</anno> - <anno>Incr</anno></c> and
+ <c><anno>Incr</anno> &lt; 0</c>.</p>
+ </item>
+ <item>
+ <p>If <c><anno>Incr</anno> =:= 0</c> and
+ <c><anno>From</anno> =/= <anno>To</anno></c>.</p>
+ </item>
+ </list>
<p>The following equalities hold for all sequences:</p>
<code type="none">
-length(lists:seq(From, To)) == To-From+1
-length(lists:seq(From, To, Incr)) == (To-From+Incr) div Incr</code>
- <p>Examples:</p>
+length(lists:seq(From, To)) =:= To - From + 1
+length(lists:seq(From, To, Incr)) =:= (To - From + Incr) div Incr</code>
+ <p><em>Examples:</em></p>
<pre>
> <input>lists:seq(1, 10).</input>
[1,2,3,4,5,6,7,8,9,10]
@@ -634,74 +734,87 @@ length(lists:seq(From, To, Incr)) == (To-From+Incr) div Incr</code>
[1]</pre>
</desc>
</func>
+
<func>
<name name="sort" arity="1"/>
- <fsummary>Sort a list</fsummary>
+ <fsummary>Sort a list.</fsummary>
<desc>
<p>Returns a list containing the sorted elements of
<c><anno>List1</anno></c>.</p>
</desc>
</func>
+
<func>
<name name="sort" arity="2"/>
- <fsummary>Sort a list</fsummary>
+ <fsummary>Sort a list.</fsummary>
<desc>
<p>Returns a list containing the sorted elements of
<c><anno>List1</anno></c>, according to the <seealso
marker="#ordering_function">ordering function</seealso>
- <c><anno>Fun</anno></c>. <c><anno>Fun</anno>(<anno>A</anno>, <anno>B</anno>)</c> should return <c>true</c> if
- <c><anno>A</anno></c> compares less than or equal to <c><anno>B</anno></c> in the
- ordering, <c>false</c> otherwise.</p>
+ <c><anno>Fun</anno></c>. <c><anno>Fun</anno>(<anno>A</anno>,
+ <anno>B</anno>)</c> is to return <c>true</c> if <c><anno>A</anno></c>
+ compares less than or equal to <c><anno>B</anno></c> in the
+ ordering, otherwise <c>false</c>.</p>
</desc>
</func>
+
<func>
<name name="split" arity="2"/>
- <fsummary>Split a list into two lists</fsummary>
+ <fsummary>Split a list into two lists.</fsummary>
<type_desc variable="N">0..length(<anno>List1</anno>)</type_desc>
<desc>
- <p>Splits <c><anno>List1</anno></c> into <c><anno>List2</anno></c> and <c><anno>List3</anno></c>.
- <c><anno>List2</anno></c> contains the first <c><anno>N</anno></c> elements and
- <c><anno>List3</anno></c> the rest of the elements (the <c><anno>N</anno></c>th tail).</p>
+ <p>Splits <c><anno>List1</anno></c> into <c><anno>List2</anno></c> and
+ <c><anno>List3</anno></c>. <c><anno>List2</anno></c> contains the
+ first <c><anno>N</anno></c> elements and <c><anno>List3</anno></c>
+ the remaining elements (the <c><anno>N</anno></c>th tail).</p>
</desc>
</func>
+
<func>
<name name="splitwith" arity="2"/>
- <fsummary>Split a list into two lists based on a predicate</fsummary>
+ <fsummary>Split a list into two lists based on a predicate.</fsummary>
<desc>
<p>Partitions <c><anno>List</anno></c> into two lists according to
- <c><anno>Pred</anno></c>. <c>splitwith/2</c> behaves as if it is defined
- as follows:</p>
+ <c><anno>Pred</anno></c>. <c>splitwith/2</c> behaves as if it is
+ defined as follows:</p>
<code type="none">
splitwith(Pred, List) ->
{takewhile(Pred, List), dropwhile(Pred, List)}.</code>
- <p>Examples:</p>
+ <p><em>Examples:</em></p>
<pre>
> <input>lists:splitwith(fun(A) -> A rem 2 == 1 end, [1,2,3,4,5,6,7]).</input>
{[1],[2,3,4,5,6,7]}
> <input>lists:splitwith(fun(A) -> is_atom(A) end, [a,b,1,c,d,2,3,4,e]).</input>
{[a,b],[1,c,d,2,3,4,e]}</pre>
- <p>See also <c>partition/2</c> for a different way to partition
- a list.</p>
+ <p>For a different way to partition a list, see
+ <seealso marker="#partition/2"><c>partition/2</c></seealso>.</p>
</desc>
</func>
+
<func>
<name name="sublist" arity="2"/>
- <fsummary>Return a sub-list of a certain length, starting at the first position</fsummary>
+ <fsummary>Return a sublist of a certain length, starting at the first
+ position.</fsummary>
<desc>
- <p>Returns the sub-list of <c><anno>List1</anno></c> starting at position 1
- and with (max) <c><anno>Len</anno></c> elements. It is not an error for
- <c><anno>Len</anno></c> to exceed the length of the list, in that case
- the whole list is returned.</p>
+ <p>Returns the sublist of <c><anno>List1</anno></c> starting at
+ position 1 and with (maximum) <c><anno>Len</anno></c> elements. It is
+ not an error for <c><anno>Len</anno></c> to exceed the length of the
+ list, in that case the whole list is returned.</p>
</desc>
</func>
+
<func>
<name name="sublist" arity="3"/>
- <fsummary>Return a sub-list starting at a given position and with a given number of elements</fsummary>
+ <fsummary>Return a sublist starting at a specified position and with a
+ specified number of elements.</fsummary>
<type_desc variable="Start">1..(length(<anno>List1</anno>)+1)</type_desc>
<desc>
- <p>Returns the sub-list of <c><anno>List1</anno></c> starting at <c><anno>Start</anno></c>
- and with (max) <c><anno>Len</anno></c> elements. It is not an error for
- <c><anno>Start</anno>+<anno>Len</anno></c> to exceed the length of the list.</p>
+ <p>Returns the sublist of <c><anno>List1</anno></c> starting at
+ <c><anno>Start</anno></c> and with (maximum) <c><anno>Len</anno></c>
+ elements. It is not an error for
+ <c><anno>Start</anno>+<anno>Len</anno></c> to exceed the length of
+ the list.</p>
+ <p><em>Examples:</em></p>
<pre>
> <input>lists:sublist([1,2,3,4], 2, 2).</input>
[2,3]
@@ -711,142 +824,163 @@ splitwith(Pred, List) ->
[]</pre>
</desc>
</func>
+
<func>
<name name="subtract" arity="2"/>
- <fsummary>Subtract the element in one list from another list</fsummary>
+ <fsummary>Subtract the element in one list from another list.</fsummary>
<desc>
- <p>Returns a new list <c><anno>List3</anno></c> which is a copy of
- <c><anno>List1</anno></c>, subjected to the following procedure: for each
- element in <c><anno>List2</anno></c>, its first occurrence in <c><anno>List1</anno></c>
- is deleted. For example:</p>
+ <p>Returns a new list <c><anno>List3</anno></c> that is a copy of
+ <c><anno>List1</anno></c>, subjected to the following procedure:
+ for each element in <c><anno>List2</anno></c>, its first occurrence
+ in <c><anno>List1</anno></c> is deleted.</p>
+ <p><em>Example:</em></p>
<pre>
> <input>lists:subtract("123212", "212").</input>
"312".</pre>
<p><c>lists:subtract(A, B)</c> is equivalent to <c>A -- B</c>.</p>
- <warning><p>The complexity of <c>lists:subtract(A, B)</c> is proportional
- to <c>length(A)*length(B)</c>, meaning that it will be very slow if
- both <c>A</c> and <c>B</c> are long lists.
- (Using ordered lists and
- <seealso marker="ordsets#subtract/2">ordsets:subtract/2</seealso>
- is a much better choice if both lists are long.)</p></warning>
+ <warning>
+ <p>The complexity of <c>lists:subtract(A, B)</c> is proportional to
+ <c>length(A)*length(B)</c>, meaning that it is very slow if both
+ <c>A</c> and <c>B</c> are long lists. (If both lists are long, it
+ is a much better choice to use ordered lists and
+ <seealso marker="ordsets#subtract/2">
+ <c>ordsets:subtract/2</c></seealso>.</p>
+ </warning>
</desc>
</func>
+
<func>
<name name="suffix" arity="2"/>
- <fsummary>Test for list suffix</fsummary>
+ <fsummary>Test for list suffix.</fsummary>
<desc>
<p>Returns <c>true</c> if <c><anno>List1</anno></c> is a suffix of
<c><anno>List2</anno></c>, otherwise <c>false</c>.</p>
</desc>
</func>
+
<func>
<name name="sum" arity="1"/>
- <fsummary>Return sum of elements in a list</fsummary>
+ <fsummary>Return the sum of elements in a list.</fsummary>
<desc>
<p>Returns the sum of the elements in <c><anno>List</anno></c>.</p>
</desc>
</func>
+
<func>
<name name="takewhile" arity="2"/>
- <fsummary>Take elements from a list while a predicate is true</fsummary>
+ <fsummary>Take elements from a list while a predicate is <c>true</c>.
+ </fsummary>
<desc>
- <p>Takes elements <c><anno>Elem</anno></c> from <c><anno>List1</anno></c> while
- <c><anno>Pred</anno>(<anno>Elem</anno>)</c> returns <c>true</c>, that is,
- the function returns the longest prefix of the list for which
+ <p>Takes elements <c><anno>Elem</anno></c> from
+ <c><anno>List1</anno></c> while
+ <c><anno>Pred</anno>(<anno>Elem</anno>)</c> returns <c>true</c>, that
+ is, the function returns the longest prefix of the list for which
all elements satisfy the predicate.</p>
</desc>
</func>
+
<func>
<name name="ukeymerge" arity="3"/>
- <fsummary>Merge two key-sorted lists of tuples, removing duplicates</fsummary>
+ <fsummary>Merge two key-sorted lists of tuples, removing duplicates.
+ </fsummary>
<type_desc variable="N">1..tuple_size(<anno>Tuple</anno>)</type_desc>
<desc>
- <p>Returns the sorted list formed by merging <c><anno>TupleList1</anno></c>
- and <c><anno>TupleList2</anno></c>. The merge is performed on the
- <c><anno>N</anno></c>th element of each tuple. Both <c><anno>TupleList1</anno></c> and
- <c><anno>TupleList2</anno></c> must be key-sorted without duplicates
- prior to evaluating this function. When two tuples compare
- equal, the tuple from <c><anno>TupleList1</anno></c> is picked and the
- one from <c><anno>TupleList2</anno></c> deleted.</p>
+ <p>Returns the sorted list formed by merging
+ <c><anno>TupleList1</anno></c> and
+ <c><anno>TupleList2</anno></c>. The merge is performed on the
+ <c><anno>N</anno></c>th element of each tuple. Both
+ <c><anno>TupleList1</anno></c> and <c><anno>TupleList2</anno></c>
+ must be key-sorted without duplicates before evaluating this function.
+ When two tuples compare equal, the tuple from
+ <c><anno>TupleList1</anno></c> is picked and the
+ one from <c><anno>TupleList2</anno></c> is deleted.</p>
</desc>
</func>
+
<func>
<name name="ukeysort" arity="2"/>
- <fsummary>Sort a list of tuples, removing duplicates</fsummary>
+ <fsummary>Sort a list of tuples, removing duplicates.</fsummary>
<type_desc variable="N">1..tuple_size(<anno>Tuple</anno>)</type_desc>
<desc>
- <p>Returns a list containing the sorted elements of the list
- <c><anno>TupleList1</anno></c> where all but the first tuple of the
- tuples comparing equal have been deleted. Sorting is
+ <p>Returns a list containing the sorted elements of list
+ <c><anno>TupleList1</anno></c> where all except the first tuple of
+ the tuples comparing equal have been deleted. Sorting is
performed on the <c><anno>N</anno></c>th element of the tuples.</p>
</desc>
</func>
+
<func>
<name name="umerge" arity="1"/>
- <fsummary>Merge a list of sorted lists, removing duplicates</fsummary>
+ <fsummary>Merge a list of sorted lists, removing duplicates.</fsummary>
<desc>
- <p>Returns the sorted list formed by merging all the sub-lists
- of <c><anno>ListOfLists</anno></c>. All sub-lists must be sorted and
- contain no duplicates prior to evaluating this function.
- When two elements compare equal, the element from the
- sub-list with the lowest position in <c><anno>ListOfLists</anno></c> is
- picked and the other one deleted.</p>
+ <p>Returns the sorted list formed by merging all the sublists
+ of <c><anno>ListOfLists</anno></c>. All sublists must be sorted and
+ contain no duplicates before evaluating this function.
+ When two elements compare equal, the element from the sublist
+ with the lowest position in <c><anno>ListOfLists</anno></c> is
+ picked and the other is deleted.</p>
</desc>
</func>
+
<func>
<name name="umerge" arity="2"/>
- <fsummary>Merge two sorted lists, removing duplicates</fsummary>
+ <fsummary>Merge two sorted lists, removing duplicates.</fsummary>
<desc>
- <p>Returns the sorted list formed by merging <c><anno>List1</anno></c> and
- <c><anno>List2</anno></c>. Both <c><anno>List1</anno></c> and <c><anno>List2</anno></c> must be
- sorted and contain no duplicates prior to evaluating this
+ <p>Returns the sorted list formed by merging <c><anno>List1</anno></c>
+ and <c><anno>List2</anno></c>. Both <c><anno>List1</anno></c> and
+ <c><anno>List2</anno></c> must be
+ sorted and contain no duplicates before evaluating this
function. When two elements compare equal, the element from
- <c><anno>List1</anno></c> is picked and the one from <c><anno>List2</anno></c>
- deleted.</p>
+ <c><anno>List1</anno></c> is picked and the one from
+ <c><anno>List2</anno></c> is deleted.</p>
</desc>
</func>
+
<func>
<name name="umerge" arity="3"/>
- <fsummary>Merge two sorted lists, removing duplicates</fsummary>
+ <fsummary>Merge two sorted lists, removing duplicates.</fsummary>
<desc>
- <p>Returns the sorted list formed by merging <c><anno>List1</anno></c> and
- <c><anno>List2</anno></c>. Both <c><anno>List1</anno></c> and <c><anno>List2</anno></c> must be
- sorted according to the <seealso
+ <p>Returns the sorted list formed by merging <c><anno>List1</anno></c>
+ and <c><anno>List2</anno></c>. Both <c><anno>List1</anno></c> and
+ <c><anno>List2</anno></c> must be sorted according to the <seealso
marker="#ordering_function">ordering function</seealso>
- <c>Fun</c> and contain no duplicates prior to evaluating
- this function. <c><anno>Fun</anno>(<anno>A</anno>, <anno>B</anno>)</c> should return <c>true</c> if
- <c><anno>A</anno></c> compares less than or equal to <c><anno>B</anno></c> in the
- ordering, <c>false</c> otherwise. When two elements compare
- equal, the element from
- <c><anno>List1</anno></c> is picked and the one from <c><anno>List2</anno></c>
- deleted.</p>
+ <c>Fun</c> and contain no duplicates before evaluating this function.
+ <c><anno>Fun</anno>(<anno>A</anno>, <anno>B</anno>)</c> is to return
+ <c>true</c> if <c><anno>A</anno></c> compares less than or equal to
+ <c><anno>B</anno></c> in the ordering, otherwise <c>false</c>. When
+ two elements compare equal, the element from <c><anno>List1</anno></c>
+ is picked and the one from <c><anno>List2</anno></c> is deleted.</p>
</desc>
</func>
+
<func>
<name name="umerge3" arity="3"/>
- <fsummary>Merge three sorted lists, removing duplicates</fsummary>
+ <fsummary>Merge three sorted lists, removing duplicates.</fsummary>
<desc>
<p>Returns the sorted list formed by merging <c><anno>List1</anno></c>,
- <c><anno>List2</anno></c> and <c><anno>List3</anno></c>. All of <c><anno>List1</anno></c>,
- <c><anno>List2</anno></c> and <c><anno>List3</anno></c> must be sorted and contain no
- duplicates prior to evaluating this function. When two
+ <c><anno>List2</anno></c>, and <c><anno>List3</anno></c>. All of
+ <c><anno>List1</anno></c>, <c><anno>List2</anno></c>, and
+ <c><anno>List3</anno></c> must be sorted and contain no
+ duplicates before evaluating this function. When two
elements compare equal, the element from <c><anno>List1</anno></c> is
- picked if there is such an element, otherwise the element
- from <c><anno>List2</anno></c> is picked, and the other one deleted.</p>
+ picked if there is such an element, otherwise the element from
+ <c><anno>List2</anno></c> is picked, and the other is deleted.</p>
</desc>
</func>
+
<func>
<name name="unzip" arity="1"/>
- <fsummary>Unzip a list of two-tuples into two lists</fsummary>
+ <fsummary>Unzip a list of two-tuples into two lists.</fsummary>
<desc>
<p>"Unzips" a list of two-tuples into two lists, where the first
list contains the first element of each tuple, and the second
list contains the second element of each tuple.</p>
</desc>
</func>
+
<func>
<name name="unzip3" arity="1"/>
- <fsummary>Unzip a list of three-tuples into three lists</fsummary>
+ <fsummary>Unzip a list of three-tuples into three lists.</fsummary>
<desc>
<p>"Unzips" a list of three-tuples into three lists, where
the first list contains the first element of each tuple,
@@ -854,76 +988,84 @@ splitwith(Pred, List) ->
the third list contains the third element of each tuple.</p>
</desc>
</func>
+
<func>
<name name="usort" arity="1"/>
- <fsummary>Sort a list, removing duplicates</fsummary>
+ <fsummary>Sort a list, removing duplicates.</fsummary>
<desc>
<p>Returns a list containing the sorted elements of
- <c><anno>List1</anno></c> where all but the first element of the elements
- comparing equal have been deleted.</p>
+ <c><anno>List1</anno></c> where all except the first element of the
+ elements comparing equal have been deleted.</p>
</desc>
</func>
+
<func>
<name name="usort" arity="2"/>
- <fsummary>Sort a list, removing duplicates</fsummary>
+ <fsummary>Sort a list, removing duplicates.</fsummary>
<desc>
- <p>Returns a list which contains the sorted elements of
- <c><anno>List1</anno></c> where all but the first element of the elements
- comparing equal according to the <seealso
+ <p>Returns a list containing the sorted elements of
+ <c><anno>List1</anno></c> where all except the first element of the
+ elements comparing equal according to the <seealso
marker="#ordering_function">ordering function</seealso>
- <c><anno>Fun</anno></c> have been deleted. <c><anno>Fun</anno>(A, B)</c> should return
+ <c><anno>Fun</anno></c> have been deleted.
+ <c><anno>Fun</anno>(A, B)</c> is to return
<c>true</c> if <c>A</c> compares less than or equal to
- <c>B</c> in the ordering, <c>false</c> otherwise.</p>
+ <c>B</c> in the ordering, otherwise <c>false</c>.</p>
</desc>
</func>
+
<func>
<name name="zip" arity="2"/>
- <fsummary>Zip two lists into a list of two-tuples</fsummary>
+ <fsummary>Zip two lists into a list of two-tuples.</fsummary>
<desc>
<p>"Zips" two lists of equal length into one list of two-tuples,
where the first element of each tuple is taken from the first
- list and the second element is taken from corresponding
+ list and the second element is taken from the corresponding
element in the second list.</p>
</desc>
</func>
+
<func>
<name name="zip3" arity="3"/>
- <fsummary>Zip three lists into a list of three-tuples</fsummary>
+ <fsummary>Zip three lists into a list of three-tuples.</fsummary>
<desc>
<p>"Zips" three lists of equal length into one list of
three-tuples, where the first element of each tuple is taken
from the first list, the second element is taken from
- corresponding element in the second list, and the third
- element is taken from the corresponding element in the third
- list.</p>
+ the corresponding element in the second list, and the third
+ element is taken from the corresponding element in the third list.</p>
</desc>
</func>
+
<func>
<name name="zipwith" arity="3"/>
- <fsummary>Zip two lists into one list according to a fun</fsummary>
+ <fsummary>Zip two lists into one list according to a fun.</fsummary>
<desc>
- <p>Combine the elements of two lists of equal length into one
- list. For each pair <c><anno>X</anno>, <anno>Y</anno></c> of list elements from the two
- lists, the element in the result list will be
+ <p>Combines the elements of two lists of equal length into one list.
+ For each pair <c><anno>X</anno>, <anno>Y</anno></c> of list elements
+ from the two lists, the element in the result list is
<c><anno>Combine</anno>(<anno>X</anno>, <anno>Y</anno>)</c>.</p>
<p><c>zipwith(fun(X, Y) -> {X,Y} end, List1, List2)</c> is
equivalent to <c>zip(List1, List2)</c>.</p>
- <p>Example:</p>
+ <p><em>Example:</em></p>
<pre>
> <input>lists:zipwith(fun(X, Y) -> X+Y end, [1,2,3], [4,5,6]).</input>
[5,7,9]</pre>
</desc>
</func>
+
<func>
<name name="zipwith3" arity="4"/>
- <fsummary>Zip three lists into one list according to a fun</fsummary>
- <desc>
- <p>Combine the elements of three lists of equal length into one
- list. For each triple <c><anno>X</anno>, <anno>Y</anno>, <anno>Z</anno></c> of list elements from
- the three lists, the element in the result list will be
- <c><anno>Combine</anno>(<anno>X</anno>, <anno>Y</anno>, <anno>Z</anno>)</c>.</p>
- <p><c>zipwith3(fun(X, Y, Z) -> {X,Y,Z} end, List1, List2, List3)</c> is equivalent to <c>zip3(List1, List2, List3)</c>.</p>
- <p>Examples:</p>
+ <fsummary>Zip three lists into one list according to a fun.</fsummary>
+ <desc>
+ <p>Combines the elements of three lists of equal length into one
+ list. For each triple <c><anno>X</anno>, <anno>Y</anno>,
+ <anno>Z</anno></c> of list elements from the three lists, the element
+ in the result list is <c><anno>Combine</anno>(<anno>X</anno>,
+ <anno>Y</anno>, <anno>Z</anno>)</c>.</p>
+ <p><c>zipwith3(fun(X, Y, Z) -> {X,Y,Z} end, List1, List2, List3)</c> is
+ equivalent to <c>zip3(List1, List2, List3)</c>.</p>
+ <p><em>Examples:</em></p>
<pre>
> <input>lists:zipwith3(fun(X, Y, Z) -> X+Y+Z end, [1,2,3], [4,5,6], [7,8,9]).</input>
[12,15,18]