diff options
Diffstat (limited to 'lib/stdlib/doc/src/lists.xml')
| -rw-r--r-- | lib/stdlib/doc/src/lists.xml | 751 |
1 files changed, 454 insertions, 297 deletions
diff --git a/lib/stdlib/doc/src/lists.xml b/lib/stdlib/doc/src/lists.xml index 46edd9fe16..60dbae70c2 100644 --- a/lib/stdlib/doc/src/lists.xml +++ b/lib/stdlib/doc/src/lists.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1996</year><year>2013</year> + <year>1996</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -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>=</2</c>.</p> + <p>An example of a typical ordering function is less than or equal + to: <c>=</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<erl_eval.12.2225172> @@ -257,51 +291,74 @@ 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> + <desc> + <p>Inserts <c><anno>Sep</anno></c> between each element in <c><anno>List1</anno></c>. Has no + effect on the empty list and on a singleton list. For example:</p> + <pre> +> <input>lists:join(x, [a,b,c]).</input> +[a,x,b,x,c] +> <input>lists:join(x, [a]).</input> +[a] +> <input>lists:join(x, []).</input> +[]</pre> </desc> </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> <type_desc variable="N">1..tuple_size(<anno>Tuple</anno>)</type_desc> - <fsummary>Search for an element in a list of tuples</fsummary> <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<erl_eval.6.10732646> @@ -309,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> <type_desc variable="N">1..tuple_size(<anno>Tuple</anno>)</type_desc> - <fsummary>Test for membership of a list of tuples</fsummary> <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 @@ -344,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> <type_desc variable="N">1..tuple_size(<anno>Tuple</anno>)</type_desc> - <fsummary>Search for an element in a list of tuples</fsummary> <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] @@ -542,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><<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> < + <anno>From</anno> - <anno>Incr</anno></c> + and <c><anno>Incr</anno> > 0</c>.</p> + </item> + <item> + <p>If <c><anno>To</anno> > + <anno>From</anno> - <anno>Incr</anno></c> and + <c><anno>Incr</anno> < 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] @@ -619,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] @@ -696,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, @@ -839,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] |