aboutsummaryrefslogtreecommitdiffstats
path: root/lib/stdlib/doc/src/dict.xml
diff options
context:
space:
mode:
authorBjörn Gustavsson <[email protected]>2016-06-13 12:33:50 +0200
committerBjörn Gustavsson <[email protected]>2016-06-13 12:33:50 +0200
commit1280c70da91b90592ae4be88f1f045956e716de7 (patch)
tree42a0b48e54a9b5c982ce606b8c7e7ff9c564ade6 /lib/stdlib/doc/src/dict.xml
parent3873cb650711342aced0036e3c2d640df8a73c4b (diff)
parent68d53c01b0b8e9a007a6a30158c19e34b2d2a34e (diff)
downloadotp-1280c70da91b90592ae4be88f1f045956e716de7.tar.gz
otp-1280c70da91b90592ae4be88f1f045956e716de7.tar.bz2
otp-1280c70da91b90592ae4be88f1f045956e716de7.zip
Merge branch 'bjorn/stdlib/doc'
* bjorn/stdlib/doc: Update STDLIB documentation
Diffstat (limited to 'lib/stdlib/doc/src/dict.xml')
-rw-r--r--lib/stdlib/doc/src/dict.xml208
1 files changed, 119 insertions, 89 deletions
diff --git a/lib/stdlib/doc/src/dict.xml b/lib/stdlib/doc/src/dict.xml
index 20bab99a9c..c926ff1b5b 100644
--- a/lib/stdlib/doc/src/dict.xml
+++ b/lib/stdlib/doc/src/dict.xml
@@ -29,12 +29,13 @@
<rev>B</rev>
</header>
<module>dict</module>
- <modulesummary>Key-Value Dictionary</modulesummary>
+ <modulesummary>Key-value dictionary.</modulesummary>
<description>
- <p><c>Dict</c> implements a <c>Key</c> - <c>Value</c> dictionary.
+ <p>This module provides a <c>Key</c>-<c>Value</c> dictionary.
The representation of a dictionary is not defined.</p>
- <p>This module provides exactly the same interface as the module
- <c>orddict</c>. One difference is that while this module
+ <p>This module provides the same interface as the
+ <seealso marker="orddict"><c>orddict(3)</c></seealso> module.
+ One difference is that while this module
considers two keys as different if they do not match (<c>=:=</c>),
<c>orddict</c> considers two keys as different if and only if
they do not compare equal (<c>==</c>).</p>
@@ -43,211 +44,241 @@
<datatypes>
<datatype>
<name name="dict" 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="dict" n_vars="0"/>
</datatype>
</datatypes>
+
<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
+ <p>Appends a new <c><anno>Value</anno></c> to the current list
of values associated with <c><anno>Key</anno></c>.</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
+ <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 given 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>Dict</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>Dict</anno></c>. This function assumes that
+ <c><anno>Key</anno></c> is present in dictionary <c>Dict</c>,
+ and 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 dictionary <c>Dict</c>.</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>Dict2</anno></c> is a dictionary of all keys and values in
- <c><anno>Dict1</anno></c> for which <c><anno>Pred</anno>(<anno>Key</anno>, <anno>Value</anno>)</c> is <c>true</c>.</p>
+ <c><anno>Dict1</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 dictionary <c>Dict</c>. 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>Dict</anno></c> together with an extra argument <c>Acc</c>
+ dictionary <c><anno>Dict</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 dict is empty. The evaluation order is
+ accumulator that is passed to the next call. <c><anno>Acc0</anno></c>
+ is returned if the dictionary is empty. The evaluation order is
undefined.</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
- <c><anno>List</anno></c> to a dictionary.</p>
+ <p>Converts the <c><anno>Key</anno></c>-<c><anno>Value</anno></c> list
+ <c><anno>List</anno></c> to dictionary <c>Dict</c>.</p>
</desc>
</func>
+
+ <func>
+ <name name="is_empty" arity="1"/>
+ <fsummary>Return <c>true</c> if the dictionary is empty.</fsummary>
+ <desc>
+ <p>Returns <c>true</c> if dictionary <c><anno>Dict</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>Dict</anno></c>.</p>
+ <p>Tests if <c><anno>Key</anno></c> is contained in
+ dictionary <c><anno>Dict</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>Dict1</anno></c> to return a new value for each key.
- The evaluation order is undefined.</p>
+ <p>Calls <c><anno>Fun</anno></c> on successive keys and values
+ of dictionary <c><anno>Dict1</anno></c> to return a new value for
+ each key. The evaluation order is undefined.</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>Dict1</anno></c> and
- <c><anno>Dict2</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>Dict1</anno></c> and
+ <c><anno>Dict2</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</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 a dictionary</fsummary>
+ <fsummary>Return the number of elements in a dictionary.</fsummary>
<desc>
- <p>Returns the number of elements in a <c><anno>Dict</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>Dict</anno></c> has no elements, <c>false</c> otherwise.</p>
+ <p>Returns the number of elements in dictionary
+ <c><anno>Dict</anno></c>.</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>Dict1</anno></c>,
+ <p>Stores a <c><anno>Key</anno></c>-<c><anno>Value</anno></c> pair in
+ dictionary <c>Dict2</c>. If <c><anno>Key</anno></c> already exists in
+ <c><anno>Dict1</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 dictionary <c>Dict</c> 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:</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
- the first value.</p>
- <p>This could be defined as:</p>
+ <p>Adds <c><anno>Increment</anno></c> to the value associated with
+ <c><anno>Key</anno></c> and stores 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 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</c> and <c>append_list</c> are included
+ so that keyed values can be stored in a list <em>accumulator</em>, for
example:</p>
<pre>
> D0 = dict:new(),
@@ -256,19 +287,18 @@ update_counter(Key, Incr, D) ->
D3 = dict:append(files, f2, D2),
D4 = dict:append(files, f3, D3),
dict: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</c> is to be used if the key is known to
+ be in the dictionary, otherwise function <c>find</c>.</p>
</section>
<section>
<title>See Also</title>
- <p><seealso marker="gb_trees">gb_trees(3)</seealso>,
- <seealso marker="orddict">orddict(3)</seealso></p>
+ <p><seealso marker="gb_trees"><c>gb_trees(3)</c></seealso>,
+ <seealso marker="orddict"><c>orddict(3)</c></seealso></p>
</section>
</erlref>