diff options
Diffstat (limited to 'lib/stdlib/doc')
| -rw-r--r-- | lib/stdlib/doc/src/Makefile | 1 | ||||
| -rw-r--r-- | lib/stdlib/doc/src/array.xml | 16 | ||||
| -rw-r--r-- | lib/stdlib/doc/src/dict.xml | 10 | ||||
| -rw-r--r-- | lib/stdlib/doc/src/digraph.xml | 4 | ||||
| -rw-r--r-- | lib/stdlib/doc/src/ets.xml | 6 | ||||
| -rw-r--r-- | lib/stdlib/doc/src/gb_sets.xml | 90 | ||||
| -rw-r--r-- | lib/stdlib/doc/src/gb_trees.xml | 46 | ||||
| -rw-r--r-- | lib/stdlib/doc/src/lists.xml | 8 | ||||
| -rw-r--r-- | lib/stdlib/doc/src/maps.xml | 318 | ||||
| -rw-r--r-- | lib/stdlib/doc/src/queue.xml | 10 | ||||
| -rw-r--r-- | lib/stdlib/doc/src/ref_man.xml | 1 | ||||
| -rw-r--r-- | lib/stdlib/doc/src/sets.xml | 10 | ||||
| -rw-r--r-- | lib/stdlib/doc/src/specs.xml | 1 | ||||
| -rw-r--r-- | lib/stdlib/doc/src/supervisor.xml | 6 | ||||
| -rw-r--r-- | lib/stdlib/doc/src/unicode_usage.xml | 47 |
15 files changed, 478 insertions, 96 deletions
diff --git a/lib/stdlib/doc/src/Makefile b/lib/stdlib/doc/src/Makefile index 6f1e61e70c..ff77c3eea0 100644 --- a/lib/stdlib/doc/src/Makefile +++ b/lib/stdlib/doc/src/Makefile @@ -71,6 +71,7 @@ XML_REF3_FILES = \ lib.xml \ lists.xml \ log_mf_h.xml \ + maps.xml \ math.xml \ ms_transform.xml \ orddict.xml \ diff --git a/lib/stdlib/doc/src/array.xml b/lib/stdlib/doc/src/array.xml index b0b3aa6dc1..b03a2fa0cc 100644 --- a/lib/stdlib/doc/src/array.xml +++ b/lib/stdlib/doc/src/array.xml @@ -3,7 +3,7 @@ <erlref> <header> <copyright> - <year>2007</year><year>2013</year> + <year>2007</year><year>2014</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -84,7 +84,7 @@ the default value cannot be confused with the values of set entries.</p> {'EXIT',{badarg,_}} = (catch array:get(18, A3)).</pre></description> <datatypes> <datatype> - <name><marker id="type-array">array()</marker></name> + <name name="array" n_vars="1"/> <desc> <p>A functional, extendible array. The representation is not documented and is subject to change without notice. Note that @@ -92,6 +92,12 @@ the default value cannot be confused with the values of set entries.</p> </desc> </datatype> <datatype> + <name name="array" n_vars="0"/> + <desc> + <p><c>array()</c> is equivalent to <c>array(term())</c>.</p> + </desc> + </datatype> + <datatype> <name name="array_indx"/> </datatype> <datatype> @@ -189,7 +195,7 @@ the default value cannot be confused with the values of set entries.</p> <desc><marker id="from_orddict-2"/> -<p>Convert an ordered list of pairs <c>{Index, Value}</c> to a +<p>Convert an ordered list of pairs <c>{Index, <anno>Value</anno>}</c> to a corresponding extendible array. <c><anno>Default</anno></c> is used as the value for uninitialized entries of the array. If <c><anno>Orddict</anno></c> is not a proper, ordered list of pairs whose first elements are nonnegative @@ -455,7 +461,7 @@ cannot be changed once the array has been created.</p> <desc><marker id="sparse_to_orddict-1"/> -<p>Convert the array to an ordered list of pairs <c>{Index, Value}</c>, +<p>Convert the array to an ordered list of pairs <c>{Index, <anno>Value</anno>}</c>, skipping default-valued entries. </p> <p><em>See also:</em> <seealso marker="#to_orddict-1">to_orddict/1</seealso>.</p> @@ -476,7 +482,7 @@ cannot be changed once the array has been created.</p> <desc><marker id="to_orddict-1"/> -<p>Convert the array to an ordered list of pairs <c>{Index, Value}</c>. +<p>Convert the array to an ordered list of pairs <c>{Index, <anno>Value</anno>}</c>. </p> <p><em>See also:</em> <seealso marker="#from_orddict-2">from_orddict/2</seealso>, <seealso marker="#sparse_to_orddict-1">sparse_to_orddict/1</seealso>.</p> </desc></func></funcs> diff --git a/lib/stdlib/doc/src/dict.xml b/lib/stdlib/doc/src/dict.xml index 6ff81b56ee..942fd1f45e 100644 --- a/lib/stdlib/doc/src/dict.xml +++ b/lib/stdlib/doc/src/dict.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1996</year><year>2013</year> + <year>1996</year><year>2014</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -41,9 +41,15 @@ <datatypes> <datatype> - <name><marker id="type-dict">dict()</marker></name> + <name name="dict" n_vars="2"/> <desc><p>Dictionary as returned by <c>new/0</c>.</p></desc> </datatype> + <datatype> + <name name="dict" n_vars="0"/> + <desc> + <p><c>dict()</c> is equivalent to <c>dict(term(), term())</c>.</p> + </desc> + </datatype> </datatypes> <funcs> <func> diff --git a/lib/stdlib/doc/src/digraph.xml b/lib/stdlib/doc/src/digraph.xml index c5d5707f4f..9b9b48584b 100644 --- a/lib/stdlib/doc/src/digraph.xml +++ b/lib/stdlib/doc/src/digraph.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1996</year><year>2013</year> + <year>1996</year><year>2014</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -98,7 +98,7 @@ <name name="d_protection"/> </datatype> <datatype> - <name><marker id="type-digraph">digraph()</marker></name> + <name name="graph"/> <desc><p>A digraph as returned by <c>new/0,1</c>.</p></desc> </datatype> <datatype> diff --git a/lib/stdlib/doc/src/ets.xml b/lib/stdlib/doc/src/ets.xml index 21cf8e4149..3df24bf688 100644 --- a/lib/stdlib/doc/src/ets.xml +++ b/lib/stdlib/doc/src/ets.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1996</year><year>2013</year> + <year>1996</year><year>2014</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -171,6 +171,10 @@ <p>Returns a list of all tables at the node. Named tables are given by their names, unnamed tables are given by their table identifiers.</p> + <p>There is no guarantee of consistency in the returned list. Tables created + or deleted by other processes "during" the ets:all() call may or may + not be included in the list. Only tables created/deleted <em>before</em> + ets:all() is called are guaranteed to be included/excluded.</p> </desc> </func> <func> diff --git a/lib/stdlib/doc/src/gb_sets.xml b/lib/stdlib/doc/src/gb_sets.xml index 8ca95df8fc..ea96c14472 100644 --- a/lib/stdlib/doc/src/gb_sets.xml +++ b/lib/stdlib/doc/src/gb_sets.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>2001</year><year>2013</year> + <year>2001</year><year>2014</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -115,28 +115,40 @@ <datatypes> <datatype> - <name><marker id="type-gb_set">gb_set()</marker></name> + <name name="set" n_vars="1"/> <desc><p>A GB set.</p></desc> </datatype> <datatype> - <name name="iter"/> + <name name="set" n_vars="0"/> + <desc> + <p><c>set()</c> is equivalent to <c>set(term())</c>.</p> + </desc> + </datatype> + <datatype> + <name name="iter" n_vars="1"/> <desc><p>A GB set iterator.</p></desc> </datatype> + <datatype> + <name name="iter" n_vars="0"/> + <desc> + <p><c>iter()</c> is equivalent to <c>iter(term())</c>.</p> + </desc> + </datatype> </datatypes> <funcs> <func> <name name="add" arity="2"/> <name name="add_element" arity="2"/> - <fsummary>Add a (possibly existing) element to a gb_set</fsummary> + <fsummary>Add a (possibly existing) element to a set</fsummary> <desc> - <p>Returns a new gb_set formed from <c><anno>Set1</anno></c> with + <p>Returns a new set formed from <c><anno>Set1</anno></c> with <c><anno>Element</anno></c> inserted. If <c><anno>Element</anno></c> is already an element in <c><anno>Set1</anno></c>, nothing is changed.</p> </desc> </func> <func> <name name="balance" arity="1"/> - <fsummary>Rebalance tree representation of a gb_set</fsummary> + <fsummary>Rebalance tree representation of a set</fsummary> <desc> <p>Rebalances the tree representation of <c><anno>Set1</anno></c>. Note that this is rarely necessary, but may be motivated when a large @@ -148,9 +160,9 @@ </func> <func> <name name="delete" arity="2"/> - <fsummary>Remove an element from a gb_set</fsummary> + <fsummary>Remove an element from a set</fsummary> <desc> - <p>Returns a new gb_set formed from <c><anno>Set1</anno></c> with + <p>Returns a new set formed from <c><anno>Set1</anno></c> with <c><anno>Element</anno></c> removed. Assumes that <c><anno>Element</anno></c> is present in <c><anno>Set1</anno></c>.</p> </desc> @@ -158,9 +170,9 @@ <func> <name name="delete_any" arity="2"/> <name name="del_element" arity="2"/> - <fsummary>Remove a (possibly non-existing) element from a gb_set</fsummary> + <fsummary>Remove a (possibly non-existing) element from a set</fsummary> <desc> - <p>Returns a new gb_set formed from <c><anno>Set1</anno></c> with + <p>Returns a new set formed from <c><anno>Set1</anno></c> with <c><anno>Element</anno></c> removed. If <c><anno>Element</anno></c> is not an element in <c><anno>Set1</anno></c>, nothing is changed.</p> </desc> @@ -168,7 +180,7 @@ <func> <name name="difference" arity="2"/> <name name="subtract" arity="2"/> - <fsummary>Return the difference of two gb_sets</fsummary> + <fsummary>Return the difference of two sets</fsummary> <desc> <p>Returns only the elements of <c><anno>Set1</anno></c> which are not also elements of <c><anno>Set2</anno></c>.</p> @@ -177,14 +189,14 @@ <func> <name name="empty" arity="0"/> <name name="new" arity="0"/> - <fsummary>Return an empty gb_set</fsummary> + <fsummary>Return an empty set</fsummary> <desc> - <p>Returns a new empty gb_set.</p> + <p>Returns a new empty set.</p> </desc> </func> <func> <name name="filter" arity="2"/> - <fsummary>Filter gb_set elements</fsummary> + <fsummary>Filter set elements</fsummary> <desc> <p>Filters elements in <c><anno>Set1</anno></c> using predicate function <c><anno>Pred</anno></c>.</p> @@ -192,7 +204,7 @@ </func> <func> <name name="fold" arity="3"/> - <fsummary>Fold over gb_set elements</fsummary> + <fsummary>Fold over set elements</fsummary> <desc> <p>Folds <c><anno>Function</anno></c> over every element in <c><anno>Set</anno></c> returning the final value of the accumulator.</p> @@ -200,46 +212,46 @@ </func> <func> <name name="from_list" arity="1"/> - <fsummary>Convert a list into a gb_set</fsummary> + <fsummary>Convert a list into a set</fsummary> <desc> - <p>Returns a gb_set of the elements in <c><anno>List</anno></c>, where + <p>Returns a set of the elements in <c><anno>List</anno></c>, where <c><anno>List</anno></c> may be unordered and contain duplicates.</p> </desc> </func> <func> <name name="from_ordset" arity="1"/> - <fsummary>Make a gb_set from an ordset list</fsummary> + <fsummary>Make a set from an ordset list</fsummary> <desc> - <p>Turns an ordered-set list <c><anno>List</anno></c> into a gb_set. The list + <p>Turns an ordered-set list <c><anno>List</anno></c> into a set. The list must not contain duplicates.</p> </desc> </func> <func> <name name="insert" arity="2"/> - <fsummary>Add a new element to a gb_set</fsummary> + <fsummary>Add a new element to a set</fsummary> <desc> - <p>Returns a new gb_set formed from <c><anno>Set1</anno></c> with + <p>Returns a new set formed from <c><anno>Set1</anno></c> with <c><anno>Element</anno></c> inserted. Assumes that <c><anno>Element</anno></c> is not present in <c><anno>Set1</anno></c>.</p> </desc> </func> <func> <name name="intersection" arity="2"/> - <fsummary>Return the intersection of two gb_sets</fsummary> + <fsummary>Return the intersection of two sets</fsummary> <desc> <p>Returns the intersection of <c><anno>Set1</anno></c> and <c><anno>Set2</anno></c>.</p> </desc> </func> <func> <name name="intersection" arity="1"/> - <fsummary>Return the intersection of a list of gb_sets</fsummary> + <fsummary>Return the intersection of a list of sets</fsummary> <desc> - <p>Returns the intersection of the non-empty list of gb_sets.</p> + <p>Returns the intersection of the non-empty list of sets.</p> </desc> </func> <func> <name name="is_disjoint" arity="2"/> - <fsummary>Check whether two gb_sets are disjoint</fsummary> + <fsummary>Check whether two sets are disjoint</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Set1</anno></c> and <c><anno>Set2</anno></c> are disjoint (have no elements in common), @@ -248,7 +260,7 @@ </func> <func> <name name="is_empty" arity="1"/> - <fsummary>Test for empty gb_set</fsummary> + <fsummary>Test for empty set</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Set</anno></c> is an empty set, and <c>false</c> otherwise.</p> @@ -257,7 +269,7 @@ <func> <name name="is_member" arity="2"/> <name name="is_element" arity="2"/> - <fsummary>Test for membership of a gb_set</fsummary> + <fsummary>Test for membership of a set</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Element</anno></c> is an element of <c><anno>Set</anno></c>, otherwise <c>false</c>.</p> @@ -265,9 +277,9 @@ </func> <func> <name name="is_set" arity="1"/> - <fsummary>Test for a gb_set</fsummary> + <fsummary>Test for a set</fsummary> <desc> - <p>Returns <c>true</c> if <c><anno>Term</anno></c> appears to be a gb_set, + <p>Returns <c>true</c> if <c><anno>Term</anno></c> appears to be a set, otherwise <c>false</c>.</p> </desc> </func> @@ -281,7 +293,7 @@ </func> <func> <name name="iterator" arity="1"/> - <fsummary>Return an iterator for a gb_set</fsummary> + <fsummary>Return an iterator for a set</fsummary> <desc> <p>Returns an iterator that can be used for traversing the entries of <c><anno>Set</anno></c>; see <c>next/1</c>. The implementation @@ -303,7 +315,7 @@ </func> <func> <name name="next" arity="1"/> - <fsummary>Traverse a gb_set with an iterator</fsummary> + <fsummary>Traverse a set with an iterator</fsummary> <desc> <p>Returns <c>{<anno>Element</anno>, <anno>Iter2</anno>}</c> where <c><anno>Element</anno></c> is the smallest element referred to by the iterator <c><anno>Iter1</anno></c>, @@ -314,14 +326,14 @@ </func> <func> <name name="singleton" arity="1"/> - <fsummary>Return a gb_set with one element</fsummary> + <fsummary>Return a set with one element</fsummary> <desc> - <p>Returns a gb_set containing only the element <c><anno>Element</anno></c>.</p> + <p>Returns a set containing only the element <c><anno>Element</anno></c>.</p> </desc> </func> <func> <name name="size" arity="1"/> - <fsummary>Return the number of elements in a gb_set</fsummary> + <fsummary>Return the number of elements in a set</fsummary> <desc> <p>Returns the number of elements in <c><anno>Set</anno></c>.</p> </desc> @@ -356,24 +368,24 @@ </func> <func> <name name="to_list" arity="1"/> - <fsummary>Convert a gb_set into a list</fsummary> + <fsummary>Convert a set into a list</fsummary> <desc> <p>Returns the elements of <c><anno>Set</anno></c> as a list.</p> </desc> </func> <func> <name name="union" arity="2"/> - <fsummary>Return the union of two gb_sets</fsummary> + <fsummary>Return the union of two sets</fsummary> <desc> - <p>Returns the merged (union) gb_set of <c><anno>Set1</anno></c> and + <p>Returns the merged (union) set of <c><anno>Set1</anno></c> and <c><anno>Set2</anno></c>.</p> </desc> </func> <func> <name name="union" arity="1"/> - <fsummary>Return the union of a list of gb_sets</fsummary> + <fsummary>Return the union of a list of sets</fsummary> <desc> - <p>Returns the merged (union) gb_set of the list of gb_sets.</p> + <p>Returns the merged (union) set of the list of sets.</p> </desc> </func> </funcs> diff --git a/lib/stdlib/doc/src/gb_trees.xml b/lib/stdlib/doc/src/gb_trees.xml index 57e60eacb7..b2f237e1d7 100644 --- a/lib/stdlib/doc/src/gb_trees.xml +++ b/lib/stdlib/doc/src/gb_trees.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>2001</year><year>2013</year> + <year>2001</year><year>2014</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -59,13 +59,25 @@ <datatypes> <datatype> - <name><marker id="type-gb_tree">gb_tree()</marker></name> + <name name="tree" n_vars="2"/> <desc><p>A GB tree.</p></desc> </datatype> <datatype> - <name name="iter"/> + <name name="tree" n_vars="0"/> + <desc> + <p><c>tree()</c> is equivalent to <c>tree(term(), term())</c>.</p> + </desc> + </datatype> + <datatype> + <name name="iter" n_vars="2"/> <desc><p>A GB tree iterator.</p></desc> </datatype> + <datatype> + <name name="iter" n_vars="0"/> + <desc> + <p><c>iter()</c> is equivalent to <c>iter(term(), term())</c>.</p> + </desc> + </datatype> </datatypes> <funcs> <func> @@ -108,9 +120,9 @@ <name name="enter" arity="3"/> <fsummary>Insert or update key with value in a tree</fsummary> <desc> - <p>Inserts <c><anno>Key</anno></c> with value <c><anno>Val</anno></c> into <c><anno>Tree1</anno></c> if + <p>Inserts <c><anno>Key</anno></c> with value <c><anno>Value</anno></c> into <c><anno>Tree1</anno></c> if the key is not present in the tree, otherwise updates - <c><anno>Key</anno></c> to value <c><anno>Val</anno></c> in <c><anno>Tree1</anno></c>. Returns the + <c><anno>Key</anno></c> to value <c><anno>Value</anno></c> in <c><anno>Tree1</anno></c>. Returns the new tree.</p> </desc> </func> @@ -135,7 +147,7 @@ <name name="insert" arity="3"/> <fsummary>Insert a new key and value in a tree</fsummary> <desc> - <p>Inserts <c><anno>Key</anno></c> with value <c><anno>Val</anno></c> into <c><anno>Tree1</anno></c>; + <p>Inserts <c><anno>Key</anno></c> with value <c><anno>Value</anno></c> into <c><anno>Tree1</anno></c>; returns the new tree. Assumes that the key is not present in the tree, crashes otherwise.</p> </desc> @@ -181,8 +193,8 @@ <name name="largest" arity="1"/> <fsummary>Return largest key and value</fsummary> <desc> - <p>Returns <c>{<anno>Key</anno>, <anno>Val</anno>}</c>, where <c><anno>Key</anno></c> is the largest - key in <c><anno>Tree</anno></c>, and <c><anno>Val</anno></c> is the value associated + <p>Returns <c>{<anno>Key</anno>, <anno>Value</anno>}</c>, where <c><anno>Key</anno></c> is the largest + key in <c><anno>Tree</anno></c>, and <c><anno>Value</anno></c> is the value associated with this key. Assumes that the tree is nonempty.</p> </desc> </func> @@ -191,7 +203,7 @@ <fsummary>Look up a key in a tree</fsummary> <desc> <p>Looks up <c><anno>Key</anno></c> in <c><anno>Tree</anno></c>; returns - <c>{value, <anno>Val</anno>}</c>, or <c>none</c> if <c><anno>Key</anno></c> is not + <c>{value, <anno>Value</anno>}</c>, or <c>none</c> if <c><anno>Key</anno></c> is not present.</p> </desc> </func> @@ -207,7 +219,7 @@ <name name="next" arity="1"/> <fsummary>Traverse a tree with an iterator</fsummary> <desc> - <p>Returns <c>{<anno>Key</anno>, <anno>Val</anno>, <anno>Iter2</anno>}</c> where <c><anno>Key</anno></c> is the + <p>Returns <c>{<anno>Key</anno>, <anno>Value</anno>, <anno>Iter2</anno>}</c> where <c><anno>Key</anno></c> is the smallest key referred to by the iterator <c><anno>Iter1</anno></c>, and <c><anno>Iter2</anno></c> is the new iterator to be used for traversing the remaining nodes, or the atom <c>none</c> if no @@ -225,8 +237,8 @@ <name name="smallest" arity="1"/> <fsummary>Return smallest key and value</fsummary> <desc> - <p>Returns <c>{<anno>Key</anno>, <anno>Val</anno>}</c>, where <c><anno>Key</anno></c> is the smallest - key in <c><anno>Tree</anno></c>, and <c><anno>Val</anno></c> is the value associated + <p>Returns <c>{<anno>Key</anno>, <anno>Value</anno>}</c>, where <c><anno>Key</anno></c> is the smallest + key in <c><anno>Tree</anno></c>, and <c><anno>Value</anno></c> is the value associated with this key. Assumes that the tree is nonempty.</p> </desc> </func> @@ -234,8 +246,8 @@ <name name="take_largest" arity="1"/> <fsummary>Extract largest key and value</fsummary> <desc> - <p>Returns <c>{<anno>Key</anno>, <anno>Val</anno>, <anno>Tree2</anno>}</c>, where <c><anno>Key</anno></c> is the - largest key in <c><anno>Tree1</anno></c>, <c><anno>Val</anno></c> is the value + <p>Returns <c>{<anno>Key</anno>, <anno>Value</anno>, <anno>Tree2</anno>}</c>, where <c><anno>Key</anno></c> is the + largest key in <c><anno>Tree1</anno></c>, <c><anno>Value</anno></c> is the value associated with this key, and <c><anno>Tree2</anno></c> is this tree with the corresponding node deleted. Assumes that the tree is nonempty.</p> @@ -245,8 +257,8 @@ <name name="take_smallest" arity="1"/> <fsummary>Extract smallest key and value</fsummary> <desc> - <p>Returns <c>{<anno>Key</anno>, <anno>Val</anno>, <anno>Tree2</anno>}</c>, where <c><anno>Key</anno></c> is the - smallest key in <c><anno>Tree1</anno></c>, <c><anno>Val</anno></c> is the value + <p>Returns <c>{<anno>Key</anno>, <anno>Value</anno>, <anno>Tree2</anno>}</c>, where <c><anno>Key</anno></c> is the + smallest key in <c><anno>Tree1</anno></c>, <c><anno>Value</anno></c> is the value associated with this key, and <c><anno>Tree2</anno></c> is this tree with the corresponding node deleted. Assumes that the tree is nonempty.</p> @@ -263,7 +275,7 @@ <name name="update" arity="3"/> <fsummary>Update a key to new value in a tree</fsummary> <desc> - <p>Updates <c><anno>Key</anno></c> to value <c><anno>Val</anno></c> in <c><anno>Tree1</anno></c>; + <p>Updates <c><anno>Key</anno></c> to value <c><anno>Value</anno></c> in <c><anno>Tree1</anno></c>; returns the new tree. Assumes that the key is present in the tree.</p> </desc> diff --git a/lib/stdlib/doc/src/lists.xml b/lib/stdlib/doc/src/lists.xml index 251a383cf8..ee3c51c62c 100644 --- a/lib/stdlib/doc/src/lists.xml +++ b/lib/stdlib/doc/src/lists.xml @@ -123,6 +123,14 @@ </desc> </func> <func> + <name name="droplast" arity="1"/> + <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> + </desc> + </func> + <func> <name name="dropwhile" arity="2"/> <fsummary>Drop elements from a list while a predicate is true</fsummary> <desc> diff --git a/lib/stdlib/doc/src/maps.xml b/lib/stdlib/doc/src/maps.xml new file mode 100644 index 0000000000..76137e3dee --- /dev/null +++ b/lib/stdlib/doc/src/maps.xml @@ -0,0 +1,318 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> + <header> + <copyright> + <year>2013</year><year>2014</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + </legalnotice> + <title>maps</title> + <prepared>Björn-Egil Dahlberg</prepared> + <docno>1</docno> + <date>2014-02-28</date> + <rev>A</rev> + </header> + <module>maps</module> + <modulesummary>Maps Processing Functions</modulesummary> + <description> + <p>This module contains functions for maps processing.</p> + </description> + <funcs> + + <func> + <name name="find" arity="2"/> + <fsummary></fsummary> + <desc> + <p> + Returns a tuple <c>{ok, Value}</c> where <c><anno>Value</anno></c> is the value associated with <c><anno>Key</anno></c>, + or <c>error</c> if no value is associated with <c><anno>Key</anno></c> in <c><anno>Map</anno></c>. + </p> + <p>Example:</p> + <code type="none"> +> Map = #{"hi" => 42}, + Key = "hi", + maps:find(Key,Map). +{ok,42} </code> + </desc> + </func> + + <func> + <name name="fold" arity="3"/> + <fsummary></fsummary> + <desc> + <p> + Calls <c>F(K, V, AccIn)</c> for every <c><anno>K</anno></c> to value <c><anno>V</anno></c> + association in <c><anno>Map</anno></c> in + arbitrary order. The function <c>fun F/3</c> must return a new accumulator + which is passed to the next successive call. <c>maps:fold/3</c> returns the final + value of the accumulator. The initial accumulator value <c><anno>Init</anno></c> is returned if + the map is empty. + </p> + <p>Example:</p> + <code type="none"> +> Fun = fun(K,V,AccIn) when is_list(K) -> AccIn + V end, + Map = #{"k1" => 1, "k2" => 2, "k3" => 3}, + maps:fold(Fun,0,Map). +6</code> + </desc> + </func> + + <func> + <name name="from_list" arity="1"/> + <fsummary></fsummary> + <desc> + <p> + The function takes a list of key-value tuples elements and builds a + map. The associations may be in any order and both keys and values in the + association may be of any term. If the same key appears more than once, + the latter (rightmost) value is used and the previous values are ignored. + </p> + <p>Example:</p> + <code type="none"> +> List = [{"a",ignored},{1337,"value two"},{42,value_three},{"a",1}], + maps:from_list(List). +#{42 => value_three,1337 => "value two","a" => 1}</code> + </desc> + </func> + + <func> + <name name="get" arity="2"/> + <fsummary></fsummary> + <desc> + <p> + Returns the value <c><anno>Value</anno></c> associated with <c><anno>Key</anno></c> if + <c><anno>Map</anno></c> contains <c><anno>Key</anno></c>. + If no value is associated with <c><anno>Key</anno></c> then the call will + fail with an exception. + </p> + <p>Example:</p> + <code type="none"> +> Key = 1337, + Map = #{42 => value_two,1337 => "value one","a" => 1}, + maps:get(Key,Map). +"value one"</code> + </desc> + </func> + + <func> + <name name="is_key" arity="2"/> + <fsummary></fsummary> + <desc> + <p> + Returns <c>true</c> if map <c><anno>Map</anno></c> contains <c><anno>Key</anno></c> and returns + <c>false</c> if it does not contain the <c><anno>Key</anno></c>. + The function will fail with an exception if <c><anno>Map</anno></c> is not a Map. + </p> + <p>Example:</p> + <code type="none"> +> Map = #{"42" => value}. +#{"42"> => value} +> maps:is_key("42",Map). +true +> maps:is_key(value,Map). +false</code> + </desc> + </func> + + <func> + <name name="keys" arity="1"/> + <fsummary></fsummary> + <desc> + <p> + Returns a complete list of keys, in arbitrary order, which resides within <c><anno>Map</anno></c>. + </p> + <p>Example:</p> + <code type="none"> +> Map = #{42 => value_three,1337 => "value two","a" => 1}, + maps:keys(Map). +[42,1337,"a"]</code> + </desc> + </func> + + <func> + <name name="map" arity="2"/> + <fsummary></fsummary> + <desc> + <p> + The function produces a new map <c><anno>Map2</anno></c> by calling the function <c>fun F(K, V1)</c> for + every <c><anno>K</anno></c> to value <c><anno>V1</anno></c> association in <c><anno>Map1</anno></c> in arbitrary order. + The function <c>fun F/2</c> must return the value <c><anno>V2</anno></c> to be associated with key <c><anno>K</anno></c> for + the new map <c><anno>Map2</anno></c>. + </p> + <p>Example:</p> + <code type="none"> +> Fun = fun(K,V1) when is_list(K) -> V1*2 end, + Map = #{"k1" => 1, "k2" => 2, "k3" => 3}, + maps:map(Fun,Map). +#{"k1" => 2,"k2" => 4,"k3" => 6}</code> + </desc> + </func> + + <func> + <name name="merge" arity="2"/> + <fsummary></fsummary> + <desc> + <p> + Merges two maps into a single map <c><anno>Map3</anno></c>. If two keys exists in both maps the + value in <c><anno>Map1</anno></c> will be superseded by the value in <c><anno>Map2</anno></c>. + </p> + <p>Example:</p> + <code type="none"> +> Map1 = #{a => "value_one", b => "value_two"}, + Map2 = #{a => 1, c => 2}, + maps:merge(Map1,Map2). +#{a => 1,b => "value_two",c => 2}</code> + </desc> + </func> + + <func> + <name name="new" arity="0"/> + <fsummary></fsummary> + <desc> + <p> + Returns a new empty map. + </p> + <p>Example:</p> + <code type="none"> +> maps:new(). +#{}</code> + </desc> + </func> + + <func> + <name name="put" arity="3"/> + <fsummary></fsummary> + <desc> + <p> + Associates <c><anno>Key</anno></c> with value <c><anno>Value</anno></c> and inserts the association into map <c>Map2</c>. + If key <c><anno>Key</anno></c> already exists in map <c><anno>Map1</anno></c>, the old associated value is + replaced by value <c><anno>Value</anno></c>. The function returns a new map <c><anno>Map2</anno></c> containing the new association and + the old associations in <c><anno>Map1</anno></c>. + </p> + <p>Example:</p> + <code type="none"> +> Map = #{"a" => 1}. +#{"a" => 1} +> maps:put("a", 42, Map). +#{"a" => 42} +> maps:put("b", 1337, Map). +#{"a" => 1,"b" => 1337}</code> + </desc> + </func> + + <func> + <name name="remove" arity="2"/> + <fsummary></fsummary> + <desc> + <p> + The function removes the <c><anno>Key</anno></c>, if it exists, and its associated value from + <c><anno>Map1</anno></c> and returns a new map <c><anno>Map2</anno></c> without key <c><anno>Key</anno></c>. + </p> + <p>Example:</p> + <code type="none"> +> Map = #{"a" => 1}. +#{"a" => 1} +> maps:remove("a",Map). +#{} +> maps:remove("b",Map). +#{"a" => 1}</code> + </desc> + </func> + + <func> + <name name="size" arity="1"/> + <fsummary></fsummary> + <desc> + <p> + The function returns the number of key-value associations in the <c><anno>Map</anno></c>. + This operation happens in constant time. + </p> + <p>Example:</p> + <code type="none"> +> Map = #{42 => value_two,1337 => "value one","a" => 1}, + maps:size(Map). +3</code> + </desc> + </func> + + <func> + <name name="to_list" arity="1"/> + <fsummary></fsummary> + <desc> + <p> + The fuction returns a list of pairs representing the key-value associations of <c><anno>Map</anno></c>, + where the pairs, <c>[{K1,V1}, ..., {Kn,Vn}]</c>, are returned in arbitrary order. + </p> + <p>Example:</p> + <code type="none"> +> Map = #{42 => value_three,1337 => "value two","a" => 1}, + maps:to_list(Map). +[{42,value_three},{1337,"value two"},{"a",1}]</code> + </desc> + </func> + + <func> + <name name="update" arity="3"/> + <fsummary></fsummary> + <desc> + <p> + If <c><anno>Key</anno></c> exists in <c><anno>Map1</anno></c> the old associated value is + replaced by value <c><anno>Value</anno></c>. The function returns a new map <c><anno>Map2</anno></c> containing + the new associated value. If <c><anno>Key</anno></c> does not exist in <c><anno>Map1</anno></c> an exception is + generated. + </p> + <p>Example:</p> + <code type="none"> +> Map = #{"a" => 1}. +#{"a" => 1} +> maps:update("a", 42, Map). +#{"a" => 42}</code> + </desc> + </func> + + <func> + <name name="values" arity="1"/> + <fsummary></fsummary> + <desc> + <p> + Returns a complete list of values, in arbitrary order, contained in map <c>M</c>. + </p> + <p>Example:</p> + <code type="none"> +> Map = #{42 => value_three,1337 => "value two","a" => 1}, + maps:values(Map). +[value_three,"value two",1]</code> + </desc> + </func> + + <func> + <name name="without" arity="2"/> + <fsummary></fsummary> + <desc> + <p> + Returns a new map <c><anno>Map2</anno></c> without the keys <c>K1</c> through <c>Kn</c> and their associated values from map <c><anno>Map1</anno></c>. + Any key in <c><anno>Ks</anno></c> that does not exist in <c><anno>Map1</anno></c> are ignored. + </p> + <p>Example:</p> + <code type="none"> +> Map = #{42 => value_three,1337 => "value two","a" => 1}, + Ks = ["a",42,"other key"], + maps:without(Ks,Map). +#{1337 => "value two"}</code> + </desc> + </func> + </funcs> +</erlref> diff --git a/lib/stdlib/doc/src/queue.xml b/lib/stdlib/doc/src/queue.xml index bcf063bf0f..9c994154d4 100644 --- a/lib/stdlib/doc/src/queue.xml +++ b/lib/stdlib/doc/src/queue.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1996</year><year>2013</year> + <year>1996</year><year>2014</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -90,9 +90,15 @@ <datatypes> <datatype> - <name><marker id="type-queue">queue()</marker></name> + <name name="queue" n_vars="1"/> <desc><p>As returned by <c>new/0</c>.</p></desc> </datatype> + <datatype> + <name name="queue" n_vars="0"/> + <desc> + <p><c>queue()</c> is equivalent to <c>queue(term())</c>.</p> + </desc> + </datatype> </datatypes> <funcs> diff --git a/lib/stdlib/doc/src/ref_man.xml b/lib/stdlib/doc/src/ref_man.xml index 4ecd02a4bf..6c35578bdf 100644 --- a/lib/stdlib/doc/src/ref_man.xml +++ b/lib/stdlib/doc/src/ref_man.xml @@ -68,6 +68,7 @@ <xi:include href="lib.xml"/> <xi:include href="lists.xml"/> <xi:include href="log_mf_h.xml"/> + <xi:include href="maps.xml"/> <xi:include href="math.xml"/> <xi:include href="ms_transform.xml"/> <xi:include href="orddict.xml"/> diff --git a/lib/stdlib/doc/src/sets.xml b/lib/stdlib/doc/src/sets.xml index 4b220bdd85..c5b8dce4b7 100644 --- a/lib/stdlib/doc/src/sets.xml +++ b/lib/stdlib/doc/src/sets.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>2000</year><year>2013</year> + <year>2000</year><year>2014</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -45,9 +45,15 @@ <datatypes> <datatype> - <name><marker id="type-dict">set()</marker></name> + <name name="set" n_vars="1"/> <desc><p>As returned by <c>new/0</c>.</p></desc> </datatype> + <datatype> + <name name="set" n_vars="0"/> + <desc> + <p><c>set()</c> is equivalent to <c>set(term())</c>.</p> + </desc> + </datatype> </datatypes> <funcs> <func> diff --git a/lib/stdlib/doc/src/specs.xml b/lib/stdlib/doc/src/specs.xml index 213ce7563f..60a04ed5e7 100644 --- a/lib/stdlib/doc/src/specs.xml +++ b/lib/stdlib/doc/src/specs.xml @@ -34,6 +34,7 @@ <xi:include href="../specs/specs_lib.xml"/> <xi:include href="../specs/specs_lists.xml"/> <xi:include href="../specs/specs_log_mf_h.xml"/> + <xi:include href="../specs/specs_maps.xml"/> <xi:include href="../specs/specs_math.xml"/> <xi:include href="../specs/specs_ms_transform.xml"/> <xi:include href="../specs/specs_orddict.xml"/> diff --git a/lib/stdlib/doc/src/supervisor.xml b/lib/stdlib/doc/src/supervisor.xml index 8197684d2d..3a5027d595 100644 --- a/lib/stdlib/doc/src/supervisor.xml +++ b/lib/stdlib/doc/src/supervisor.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1996</year><year>2013</year> + <year>1996</year><year>2014</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -262,12 +262,12 @@ child_spec() = {Id,StartFunc,Restart,Shutdown,Type,Modules} locally as <c>Name</c> using <c>register/2</c>. If <c><anno>SupName</anno>={global,Name}</c> the supervisor is registered globally as <c>Name</c> using <c>global:register_name/2</c>. If - <c><anno>SupName</anno>={via,Module,Name}</c> the supervisor + <c><anno>SupName</anno>={via,<anno>Module</anno>,<anno>Name</anno>}</c> the supervisor is registered as <c>Name</c> using the registry represented by <c>Module</c>. The <c>Module</c> callback should export the functions <c>register_name/2</c>, <c>unregister_name/1</c> and <c>send/2</c>, which should behave like the corresponding functions in <c>global</c>. - Thus, <c>{via,global,Name}</c> is a valid reference.</p> + Thus, <c>{via,global,<anno>Name</anno>}</c> is a valid reference.</p> <p>If no name is provided, the supervisor is not registered.</p> <p><c><anno>Module</anno></c> is the name of the callback module.</p> <p><c><anno>Args</anno></c> is an arbitrary term which is passed as diff --git a/lib/stdlib/doc/src/unicode_usage.xml b/lib/stdlib/doc/src/unicode_usage.xml index ee7dd128f1..c843ef7736 100644 --- a/lib/stdlib/doc/src/unicode_usage.xml +++ b/lib/stdlib/doc/src/unicode_usage.xml @@ -5,7 +5,7 @@ <header> <copyright> <year>1999</year> - <year>2013</year> + <year>2014</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -41,10 +41,10 @@ future.</p> <p>The functionality described in EEP10 was implemented in Erlang/OTP - as of R13A, but that was by no means the end of it. In R14B01 support + R13A, but that was by no means the end of it. In Erlang/OTP R14B01 support for Unicode file names was added, although it was in no way complete and was by default disabled on platforms where no guarantee was given - for the file name encoding. With R16A came support for UTF-8 encoded + for the file name encoding. With Erlang/OTP R16A came support for UTF-8 encoded source code, among with enhancements to many of the applications to support both Unicode encoded file names as well as support for UTF-8 encoded files in several circumstances. Most notable is the support @@ -52,8 +52,8 @@ for UTF-8 and more support for Unicode character sets in the I/O-system.</p> - <p>In 17.0, the encoding default for Erlang source files was - switched to UTF-8 and in 18.0 Erlang will support atoms in the full + <p>In Erlang/OTP 17.0, the encoding default for Erlang source files was + switched to UTF-8 and in Erlang/OTP 18.0 Erlang will support atoms in the full Unicode range, meaning full Unicode function and module names</p> @@ -222,7 +222,7 @@ <tag>Representation</tag> <item>To handle Unicode characters in Erlang, we have to have a common representation both in lists and binaries. The EEP (10) and - the subsequent initial implementation in R13A settled a standard + the subsequent initial implementation in Erlang/OTP R13A settled a standard representation of Unicode characters in Erlang.</item> <tag>Manipulation</tag> <item>The Unicode characters need to be processed by the Erlang @@ -274,9 +274,9 @@ (<c>+fnu</c>) on platforms where this is not the default.</item> <tag>Source code encoding</tag> <item>When it comes to the Erlang source code, there is support - for the UTF-8 encoding and bytewise encoding. The default in R16B - is bytewise (or latin1) encoding. You can control the encoding by - a comment like: + for the UTF-8 encoding and bytewise encoding. The default in + Erlang/OTP R16B was bytewise (or latin1) encoding; in Erlang/OTP 17.0 + it was changed to UTF-8. You can control the encoding by a comment like: <code> %% -*- coding: utf-8 -*- </code> @@ -290,7 +290,7 @@ <item>Having the source code in UTF-8 also allows you to write string literals containing Unicode characters with code points > 255, although atoms, module names and function names will be - restricted to the ISO-Latin-1 range until the 18.0 release. Binary + restricted to the ISO-Latin-1 range until the Erlang/OTP 18.0 release. Binary literals where you use the <c>/utf8</c> type, can also be expressed using Unicode characters > 255. Having module names using characters other than 7-bit ASCII can cause trouble on @@ -304,7 +304,7 @@ <section> <title>Standard Unicode Representation</title> <p>In Erlang, strings are actually lists of integers. A string was - up until R13 defined to be encoded in the ISO-latin-1 (ISO8859-1) + up until Erlang/OTP R13 defined to be encoded in the ISO-latin-1 (ISO8859-1) character set, which is, code point by code point, a sub-range of the Unicode character set.</p> <p>The standard list encoding for strings was therefore easily @@ -321,7 +321,7 @@ encoding has to be decided upon and the string should be converted to a binary in the preferred encoding using <c>unicode:characters_to_binary/{1,2,3}</c>. Strings are not - generally lists of bytes, as they were before R13. They are lists of + generally lists of bytes, as they were before Erlang/OTP R13. They are lists of characters. Characters are not generally bytes, they are Unicode code points.</p> @@ -447,8 +447,8 @@ Bin4 = <<"Hello"/utf16>>,</code> probably will not appreciate). Another way is to keep it backwards compatible so that only the ISO-Latin-1 character set is used to detect a string. A third way would be to let the user decide - exactly what Unicode ranges are to be viewed as characters. In - R16B you can select either the whole Unicode range or the + exactly what Unicode ranges are to be viewed as characters. Since + Erlang/OTP R16B you can select either the whole Unicode range or the ISO-Latin-1 range by supplying the startup flag <c>+pc </c><i>Range</i>, where <i>Range</i> is either <c>latin1</c> or <c>unicode</c>. For backwards compatibility, the default is @@ -685,7 +685,7 @@ Eshell V5.10.1 (abort with ^G) </item> </taglist> - <p>The Unicode file naming support was introduced with OTP release + <p>The Unicode file naming support was introduced with Erlang/OTP R14B01. A VM operating in Unicode file name translation mode can work with files having names in any language or character set (as long as it is supported by the underlying OS and file system). The @@ -709,7 +709,7 @@ Eshell V5.10.1 (abort with ^G) problem even if it uses transparent file naming. Very few systems have mixed file name encodings. A consistent UTF-8 named system will work perfectly in Unicode file name mode. It was still however - considered experimental in R14B01 and is still not the default on + considered experimental in Erlang/OTP R14B01 and is still not the default on such systems. Unicode file name translation is turned on with the <c>+fnu</c> switch to the On Linux, a VM started without explicitly stating the file name translation mode will default to <c>latin1</c> @@ -757,7 +757,7 @@ Eshell V5.10.1 (abort with ^G) <title>Notes About Raw File Names</title> <marker id="notes-about-raw-filenames"/> <p>Raw file names were introduced together with Unicode file name - support in erts-5.8.2 (OTP R14B01). The reason "raw file + support in erts-5.8.2 (Erlang/OTP R14B01). The reason "raw file names" was introduced in the system was to be able to consistently represent file names given in different encodings on the same system. Having the VM automatically translate a file name @@ -798,10 +798,10 @@ Eshell V5.10.1 (abort with ^G) the argument as a binary.</p> <p>To force Unicode file name translation mode on systems where this - is not the default was considered experimental in OTP R14B01 due to + is not the default was considered experimental in Erlang/OTP R14B01 due to the fact that the initial implementation did not ignore wrongly encoded file names, so that raw file names could spread unexpectedly - throughout the system. Beginning with R16B, the wrongly encoded file + throughout the system. Beginning with Erlang/OTP R16B, the wrongly encoded file names are only retrieved by special functions (e.g. <c>file:list_dir_all/1</c>), so the impact on existing code is much lower, why it is now supported. Unicode file name translation @@ -996,7 +996,8 @@ ok </pre> </section> <section> - <title><marker id="unicode_options_summary"/>Summary of Options</title> + <title>Summary of Options</title> + <marker id="unicode_options_summary"/> <p>The Unicode support is controlled by both command line switches, some standard environment variables and the version of OTP you are using. Most options affect mainly the way Unicode data is displayed, @@ -1032,7 +1033,7 @@ ok <c>io</c>/<c>io_lib:format</c> with the <c>"~tp"</c> and <c>~tP</c> formatting instructions, as described above.</p> <p>You can check this option by calling io:printable_range/0, - which in R16B will return <c>unicode</c> or <c>latin1</c>. To be + which will return <c>unicode</c> or <c>latin1</c>. To be compatible with future (expected) extensions to the settings, one should rather use <c>io_lib:printable_list/1</c> to check if a list is printable according to the setting. That function will @@ -1070,8 +1071,8 @@ ok <item> <p>This function returns the default encoding for Erlang source files (if no encoding comment is present) in the currently - running release. For R16 this returns <c>latin1</c> (meaning - bytewise encoding). In 17.0 and forward it returns + running release. In Erlang/OTP R16B <c>latin1</c> was returned (meaning + bytewise encoding). In Erlang/OTP 17.0 and forward it returns <c>utf8</c>.</p> <p>The encoding of each file can be specified using comments as described in |