aboutsummaryrefslogtreecommitdiffstats
path: root/lib/stdlib/doc/src/orddict.xml
diff options
context:
space:
mode:
authorBjörn Gustavsson <[email protected]>2016-05-18 15:53:35 +0200
committerBjörn Gustavsson <[email protected]>2016-06-13 12:05:57 +0200
commit68d53c01b0b8e9a007a6a30158c19e34b2d2a34e (patch)
tree4613f513b9465beb7febec6c74c8ef0502f861fe /lib/stdlib/doc/src/orddict.xml
parent99b379365981e14e2c8dde7b1a337c8ff856bd4a (diff)
downloadotp-68d53c01b0b8e9a007a6a30158c19e34b2d2a34e.tar.gz
otp-68d53c01b0b8e9a007a6a30158c19e34b2d2a34e.tar.bz2
otp-68d53c01b0b8e9a007a6a30158c19e34b2d2a34e.zip
Update STDLIB documentation
Language cleaned up by the technical writers xsipewe and tmanevik from Combitech. Proofreading and corrections by Björn Gustavsson and Hans Bolinder.
Diffstat (limited to 'lib/stdlib/doc/src/orddict.xml')
-rw-r--r--lib/stdlib/doc/src/orddict.xml220
1 files changed, 124 insertions, 96 deletions
diff --git a/lib/stdlib/doc/src/orddict.xml b/lib/stdlib/doc/src/orddict.xml
index 950f688735..076b06fc38 100644
--- a/lib/stdlib/doc/src/orddict.xml
+++ b/lib/stdlib/doc/src/orddict.xml
@@ -24,33 +24,35 @@
<title>orddict</title>
<prepared>Robert Virding</prepared>
- <responsible>nobody</responsible>
+ <responsible></responsible>
<docno></docno>
- <approved>nobody</approved>
- <checked>no</checked>
+ <approved></approved>
+ <checked></checked>
<date>2007-04-16</date>
<rev>B</rev>
- <file>orddict.sgml</file>
+ <file>orddict.xml</file>
</header>
<module>orddict</module>
- <modulesummary>Key-Value Dictionary as Ordered List</modulesummary>
+ <modulesummary>Key-value dictionary as ordered list.</modulesummary>
<description>
- <p><c>Orddict</c> implements a <c>Key</c> - <c>Value</c> dictionary.
+ <p>This module provides a <c>Key</c>-<c>Value</c> dictionary.
An <c>orddict</c> is a representation of a dictionary, where a
list of pairs is used to store the keys and values. The list is
ordered after the keys.</p>
- <p>This module provides exactly the same interface as the module
- <c>dict</c> but with a defined representation. One difference is
+
+ <p>This module provides the same interface as the
+ <seealso marker="dict"><c>dict(3)</c></seealso> module
+ but with a defined representation. One difference is
that while <c>dict</c> considers two keys as different if they
do not match (<c>=:=</c>), this module considers two keys as
- different if and only if they do not compare equal
- (<c>==</c>).</p>
+ different if and only if they do not compare equal (<c>==</c>).</p>
</description>
<datatypes>
<datatype>
<name name="orddict" n_vars="2"/>
- <desc><p>Dictionary as returned by <c>new/0</c>.</p></desc>
+ <desc><p>Dictionary as returned by
+ <seealso marker="#new/0"><c>new/0</c></seealso>.</p></desc>
</datatype>
<datatype>
<name name="orddict" n_vars="0"/>
@@ -60,202 +62,229 @@
<funcs>
<func>
<name name="append" arity="3"/>
- <fsummary>Append a value to keys in a dictionary</fsummary>
+ <fsummary>Append a value to keys in a dictionary.</fsummary>
<desc>
- <p>This function appends a new <c><anno>Value</anno></c> to the current list
- of values associated with <c><anno>Key</anno></c>. An exception is
- generated if the initial value associated with <c><anno>Key</anno></c> is
- not a list of values.</p>
+ <p>Appends a new <c><anno>Value</anno></c> to the current list
+ of values associated with <c><anno>Key</anno></c>. An exception is
+ generated if the initial value associated with <c><anno>Key</anno></c>
+ is not a list of values.</p>
+ <p>See also section <seealso marker="#notes">Notes</seealso>.</p>
</desc>
</func>
+
<func>
<name name="append_list" arity="3"/>
- <fsummary>Append new values to keys in a dictionary</fsummary>
+ <fsummary>Append new values to keys in a dictionary.</fsummary>
<desc>
- <p>This function appends a list of values <c><anno>ValList</anno></c> to
- the current list of values associated with <c><anno>Key</anno></c>. An
- exception is generated if the initial value associated with
+ <p>Appends a list of values <c><anno>ValList</anno></c> to
+ the current list of values associated with <c><anno>Key</anno></c>.
+ An exception is generated if the initial value associated with
<c><anno>Key</anno></c> is not a list of values.</p>
+ <p>See also section <seealso marker="#notes">Notes</seealso>.</p>
</desc>
</func>
+
<func>
<name name="erase" arity="2"/>
- <fsummary>Erase a key from a dictionary</fsummary>
+ <fsummary>Erase a key from a dictionary.</fsummary>
<desc>
- <p>This function erases all items with a given key from a
- dictionary.</p>
+ <p>Erases all items with a specified key from a dictionary.</p>
</desc>
</func>
+
<func>
<name name="fetch" arity="2"/>
- <fsummary>Look-up values in a dictionary</fsummary>
+ <fsummary>Look up values in a dictionary.</fsummary>
<desc>
- <p>This function returns the value associated with <c><anno>Key</anno></c>
- in the dictionary <c><anno>Orddict</anno></c>. <c>fetch</c> assumes that
- the <c><anno>Key</anno></c> is present in the dictionary and an exception
+ <p>Returns the value associated with <c><anno>Key</anno></c>
+ in dictionary <c><anno>Orddict</anno></c>. This function assumes that
+ the <c><anno>Key</anno></c> is present in the dictionary. An exception
is generated if <c><anno>Key</anno></c> is not in the dictionary.</p>
+ <p>See also section <seealso marker="#notes">Notes</seealso>.</p>
</desc>
</func>
+
<func>
<name name="fetch_keys" arity="1"/>
- <fsummary>Return all keys in a dictionary</fsummary>
+ <fsummary>Return all keys in a dictionary.</fsummary>
<desc>
- <p>This function returns a list of all keys in the dictionary.</p>
+ <p>Returns a list of all keys in a dictionary.</p>
</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>Orddict2</anno></c> is a dictionary of all keys and values in
- <c><anno>Orddict1</anno></c> for which <c><anno>Pred</anno>(<anno>Key</anno>, <anno>Value</anno>)</c> is <c>true</c>.</p>
+ <p><c><anno>Orddict2</anno></c> is a dictionary of all keys and values
+ in <c><anno>Orddict1</anno></c> for which
+ <c><anno>Pred</anno>(<anno>Key</anno>, <anno>Value</anno>)</c> is
+ <c>true</c>.</p>
</desc>
</func>
+
<func>
<name name="find" arity="2"/>
- <fsummary>Search for a key in a dictionary</fsummary>
+ <fsummary>Search for a key in a dictionary.</fsummary>
<desc>
- <p>This function searches for a key in a dictionary. Returns
- <c>{ok, <anno>Value</anno>}</c> where <c><anno>Value</anno></c> is the value associated
- with <c><anno>Key</anno></c>, or <c>error</c> if the key is not present in
- the dictionary.</p>
+ <p>Searches for a key in a dictionary. Returns
+ <c>{ok, <anno>Value</anno>}</c>, where <c><anno>Value</anno></c> is
+ the value associated with <c><anno>Key</anno></c>, or <c>error</c> if
+ the key is not present in the dictionary.</p>
+ <p>See also section <seealso marker="#notes">Notes</seealso>.</p>
</desc>
</func>
+
<func>
<name name="fold" arity="3"/>
- <fsummary>Fold a function over a dictionary</fsummary>
+ <fsummary>Fold a function over a dictionary.</fsummary>
<desc>
<p>Calls <c><anno>Fun</anno></c> on successive keys and values of
<c><anno>Orddict</anno></c> together with an extra argument <c>Acc</c>
(short for accumulator). <c><anno>Fun</anno></c> must return a new
- accumulator which is passed to the next call. <c><anno>Acc0</anno></c> is
- returned if the list is empty.</p>
+ accumulator that is passed to the next call. <c><anno>Acc0</anno></c>
+ is returned if the list is empty.</p>
</desc>
</func>
+
<func>
<name name="from_list" arity="1"/>
- <fsummary>Convert a list of pairs to a dictionary</fsummary>
+ <fsummary>Convert a list of pairs to a dictionary.</fsummary>
<desc>
- <p>This function converts the <c><anno>Key</anno></c> - <c><anno>Value</anno></c> list
+ <p>Converts the <c><anno>Key</anno></c>-<c><anno>Value</anno></c> list
<c><anno>List</anno></c> to a dictionary.</p>
</desc>
</func>
+
+ <func>
+ <name name="is_empty" arity="1"/>
+ <fsummary>Return true if the dictionary is empty.</fsummary>
+ <desc>
+ <p>Returns <c>true</c> if <c><anno>Orddict</anno></c> has no elements,
+ otherwise <c>false</c>.</p>
+ </desc>
+ </func>
+
<func>
<name name="is_key" arity="2"/>
- <fsummary>Test if a key is in a dictionary</fsummary>
+ <fsummary>Test if a key is in a dictionary.</fsummary>
<desc>
- <p>This function tests if <c><anno>Key</anno></c> is contained in
- the dictionary <c><anno>Orddict</anno></c>.</p>
+ <p>Tests if <c><anno>Key</anno></c> is contained in
+ dictionary <c><anno>Orddict</anno></c>.</p>
</desc>
</func>
+
<func>
<name name="map" arity="2"/>
- <fsummary>Map a function over a dictionary</fsummary>
+ <fsummary>Map a function over a dictionary.</fsummary>
<desc>
- <p><c>map</c> calls <c><anno>Fun</anno></c> on successive keys and values
- of <c><anno>Orddict1</anno></c> to return a new value for each key.</p>
+ <p>Calls <c><anno>Fun</anno></c> on successive keys and values of
+ <c><anno>Orddict1</anno></c> tvo return a new value for each key.</p>
</desc>
</func>
+
<func>
<name name="merge" arity="3"/>
- <fsummary>Merge two dictionaries</fsummary>
+ <fsummary>Merge two dictionaries.</fsummary>
<desc>
- <p><c>merge</c> merges two dictionaries, <c><anno>Orddict1</anno></c> and
- <c><anno>Orddict2</anno></c>, to create a new dictionary. All the <c><anno>Key</anno></c>
- - <c><anno>Value</anno></c> pairs from both dictionaries are included in
- the new dictionary. If a key occurs in both dictionaries then
- <c><anno>Fun</anno></c> is called with the key and both values to return a
- new value. <c>merge</c> could be defined as:</p>
+ <p>Merges two dictionaries, <c><anno>Orddict1</anno></c> and
+ <c><anno>Orddict2</anno></c>, to create a new dictionary. All the
+ <c><anno>Key</anno></c>-<c><anno>Value</anno></c> pairs from both
+ dictionaries are included in the new dictionary. If a key occurs in
+ both dictionaries, <c><anno>Fun</anno></c> is called with the key and
+ both values to return a new value.
+ <c>merge/3</c> can be defined as follows, but is faster:</p>
<code type="none">
merge(Fun, D1, D2) ->
fold(fun (K, V1, D) ->
update(K, fun (V2) -> Fun(K, V1, V2) end, V1, D)
end, D2, D1).</code>
- <p>but is faster.</p>
</desc>
</func>
+
<func>
<name name="new" arity="0"/>
- <fsummary>Create a dictionary</fsummary>
+ <fsummary>Create a dictionary.</fsummary>
<desc>
- <p>This function creates a new dictionary.</p>
+ <p>Creates a new dictionary.</p>
</desc>
</func>
+
<func>
<name name="size" arity="1"/>
- <fsummary>Return the number of elements in an ordered dictionary</fsummary>
+ <fsummary>Return the number of elements in an ordered dictionary.
+ </fsummary>
<desc>
<p>Returns the number of elements in an <c><anno>Orddict</anno></c>.</p>
</desc>
</func>
- <func>
- <name name="is_empty" arity="1"/>
- <fsummary>Return true if the dictionary is empty</fsummary>
- <desc>
- <p>Returns <c>true</c> if <c><anno>Orddict</anno></c> has no elements, <c>false</c> otherwise.</p>
- </desc>
- </func>
+
<func>
<name name="store" arity="3"/>
- <fsummary>Store a value in a dictionary</fsummary>
+ <fsummary>Store a value in a dictionary.</fsummary>
<desc>
- <p>This function stores a <c><anno>Key</anno></c> - <c><anno>Value</anno></c> pair in a
- dictionary. If the <c><anno>Key</anno></c> already exists in <c><anno>Orddict1</anno></c>,
+ <p>Stores a <c><anno>Key</anno></c>-<c><anno>Value</anno></c> pair in a
+ dictionary. If the <c><anno>Key</anno></c> already exists in
+ <c><anno>Orddict1</anno></c>,
the associated value is replaced by <c><anno>Value</anno></c>.</p>
</desc>
</func>
+
<func>
<name name="to_list" arity="1"/>
- <fsummary>Convert a dictionary to a list of pairs</fsummary>
+ <fsummary>Convert a dictionary to a list of pairs.</fsummary>
<desc>
- <p>This function converts the dictionary to a list
- representation.</p>
+ <p>Converts a dictionary to a list representation.</p>
</desc>
</func>
+
<func>
<name name="update" arity="3"/>
- <fsummary>Update a value in a dictionary</fsummary>
+ <fsummary>Update a value in a dictionary.</fsummary>
<desc>
- <p>Update a value in a dictionary by calling <c><anno>Fun</anno></c> on
- the value to get a new value. An exception is generated if
+ <p>Updates a value in a dictionary by calling <c><anno>Fun</anno></c>
+ on the value to get a new value. An exception is generated if
<c><anno>Key</anno></c> is not present in the dictionary.</p>
</desc>
</func>
+
<func>
<name name="update" arity="4"/>
- <fsummary>Update a value in a dictionary</fsummary>
+ <fsummary>Update a value in a dictionary.</fsummary>
<desc>
- <p>Update a value in a dictionary by calling <c><anno>Fun</anno></c> on
- the value to get a new value. If <c><anno>Key</anno></c> is not present
- in the dictionary then <c><anno>Initial</anno></c> will be stored as
- the first value. For example <c>append/3</c> could be defined
- as:</p>
+ <p>Updates a value in a dictionary by calling <c><anno>Fun</anno></c>
+ on the value to get a new value. If <c><anno>Key</anno></c> is not
+ present in the dictionary, <c><anno>Initial</anno></c> is stored as
+ the first value. For example, <c>append/3</c> can be defined
+ as follows:</p>
<code type="none">
append(Key, Val, D) ->
update(Key, fun (Old) -> Old ++ [Val] end, [Val], D).</code>
</desc>
</func>
+
<func>
<name name="update_counter" arity="3"/>
- <fsummary>Increment a value in a dictionary</fsummary>
+ <fsummary>Increment a value in a dictionary.</fsummary>
<desc>
- <p>Add <c><anno>Increment</anno></c> to the value associated with <c><anno>Key</anno></c>
- and store this value. If <c><anno>Key</anno></c> is not present in
- the dictionary then <c><anno>Increment</anno></c> will be stored as
+ <p>Adds <c><anno>Increment</anno></c> to the value associated with
+ <c><anno>Key</anno></c>
+ and store this value. If <c><anno>Key</anno></c> is not present in
+ the dictionary, <c><anno>Increment</anno></c> is stored as
the first value.</p>
- <p>This could be defined as:</p>
+ <p>This can be defined as follows, but is faster:</p>
<code type="none">
update_counter(Key, Incr, D) ->
update(Key, fun (Old) -> Old + Incr end, Incr, D).</code>
- <p>but is faster.</p>
</desc>
</func>
</funcs>
<section>
<title>Notes</title>
- <p>The functions <c>append</c> and <c>append_list</c> are included
- so we can store keyed values in a list <em>accumulator</em>. For
+ <marker id="notes"/>
+ <p>Functions <c>append/3</c> and <c>append_list/3</c> are included
+ so that keyed values can be stored in a list <em>accumulator</em>, for
example:</p>
<pre>
> D0 = orddict:new(),
@@ -264,19 +293,18 @@ update_counter(Key, Incr, D) ->
D3 = orddict:append(files, f2, D2),
D4 = orddict:append(files, f3, D3),
orddict:fetch(files, D4).
-[f1,f2,f3] </pre>
+[f1,f2,f3]</pre>
<p>This saves the trouble of first fetching a keyed value,
appending a new value to the list of stored values, and storing
- the result.
- </p>
- <p>The function <c>fetch</c> should be used if the key is known to
- be in the dictionary, otherwise <c>find</c>.</p>
+ the result.</p>
+ <p>Function <c>fetch/2</c> is to be used if the key is known to
+ be in the dictionary, otherwise function <c>find/2</c>.</p>
</section>
<section>
<title>See Also</title>
- <p><seealso marker="dict">dict(3)</seealso>,
- <seealso marker="gb_trees">gb_trees(3)</seealso></p>
+ <p><seealso marker="dict"><c>dict(3)</c></seealso>,
+ <seealso marker="gb_trees"><c>gb_trees(3)</c></seealso></p>
</section>
</erlref>