aboutsummaryrefslogtreecommitdiffstats
path: root/lib/stdlib/doc/src/dict.xml
diff options
context:
space:
mode:
authorHans Bolinder <[email protected]>2011-05-06 15:58:09 +0200
committerHans Bolinder <[email protected]>2011-05-12 08:03:42 +0200
commit229d0d8ca88bc344bed89e46541b325c1d267996 (patch)
tree74fec344df8596c868c36cec5ac08102008cacf3 /lib/stdlib/doc/src/dict.xml
parent68fe6a14539b82250373ef114d6576e74e1b8f2e (diff)
downloadotp-229d0d8ca88bc344bed89e46541b325c1d267996.tar.gz
otp-229d0d8ca88bc344bed89e46541b325c1d267996.tar.bz2
otp-229d0d8ca88bc344bed89e46541b325c1d267996.zip
r
Use Erlang specs and types for documentation
Diffstat (limited to 'lib/stdlib/doc/src/dict.xml')
-rw-r--r--lib/stdlib/doc/src/dict.xml212
1 files changed, 65 insertions, 147 deletions
diff --git a/lib/stdlib/doc/src/dict.xml b/lib/stdlib/doc/src/dict.xml
index 0cc76e0c78..b01acd02bf 100644
--- a/lib/stdlib/doc/src/dict.xml
+++ b/lib/stdlib/doc/src/dict.xml
@@ -39,174 +39,120 @@
they do not compare equal (<c>==</c>).</p>
</description>
- <section>
- <title>DATA TYPES</title>
- <code type="none">
-dictionary()
- as returned by new/0</code>
- </section>
+ <datatypes>
+ <datatype>
+ <name><marker id="type-dict">dict()</marker></name>
+ <desc><p>Dictionary as returned by <c>new/0</c>.</p></desc>
+ </datatype>
+ </datatypes>
<funcs>
<func>
- <name>append(Key, Value, Dict1) -> Dict2</name>
+ <name name="append" arity="3"/>
<fsummary>Append a value to keys in a dictionary</fsummary>
- <type>
- <v>Key = Value = term()</v>
- <v>Dict1 = Dict2 = dictionary()</v>
- </type>
<desc>
- <p>This function appends a new <c>Value</c> to the current list
- of values associated with <c>Key</c>.</p>
- </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>.</p>
+ </desc>
</func>
<func>
- <name>append_list(Key, ValList, Dict1) -> Dict2</name>
+ <name name="append_list" arity="3"/>
<fsummary>Append new values to keys in a dictionary</fsummary>
- <type>
- <v>ValList = [Value]</v>
- <v>Key = Value = term()</v>
- <v>Dict1 = Dict2 = dictionary()</v>
- </type>
<desc>
- <p>This function appends a list of values <c>ValList</c> to
- the current list of values associated with <c>Key</c>. An
+ <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
- <c>Key</c> is not a list of values.</p>
+ <c><anno>Key</anno></c> is not a list of values.</p>
</desc>
</func>
<func>
- <name>erase(Key, Dict1) -> Dict2</name>
+ <name name="erase" arity="2"/>
<fsummary>Erase a key from a dictionary</fsummary>
- <type>
- <v>Key = term()</v>
- <v>Dict1 = Dict2 = dictionary()</v>
- </type>
<desc>
<p>This function erases all items with a given key from a
dictionary.</p>
</desc>
</func>
<func>
- <name>fetch(Key, Dict) -> Value</name>
+ <name name="fetch" arity="2"/>
<fsummary>Look-up values in a dictionary</fsummary>
- <type>
- <v>Key = Value = term()</v>
- <v>Dict = dictionary()</v>
- </type>
<desc>
- <p>This function returns the value associated with <c>Key</c>
- in the dictionary <c>Dict</c>. <c>fetch</c> assumes that
- the <c>Key</c> is present in the dictionary and an exception
- is generated if <c>Key</c> is not in the dictionary.</p>
+ <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
+ is generated if <c><anno>Key</anno></c> is not in the dictionary.</p>
</desc>
</func>
<func>
- <name>fetch_keys(Dict) -> Keys</name>
+ <name name="fetch_keys" arity="1"/>
<fsummary>Return all keys in a dictionary</fsummary>
- <type>
- <v>Dict = dictionary()</v>
- <v>Keys = [term()]</v>
- </type>
<desc>
<p>This function returns a list of all keys in the dictionary.</p>
</desc>
</func>
<func>
- <name>filter(Pred, Dict1) -> Dict2</name>
+ <name name="filter" arity="2"/>
<fsummary>Choose elements which satisfy a predicate</fsummary>
- <type>
- <v>Pred = fun(Key, Value) -> bool()</v>
- <v>&nbsp;Key = Value = term()</v>
- <v>Dict1 = Dict2 = dictionary()</v>
- </type>
<desc>
- <p><c>Dict2</c> is a dictionary of all keys and values in
- <c>Dict1</c> for which <c>Pred(Key, Value)</c> is <c>true</c>.</p>
+ <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>
</desc>
</func>
<func>
- <name>find(Key, Dict) -> {ok, Value} | error</name>
+ <name name="find" arity="2"/>
<fsummary>Search for a key in a dictionary</fsummary>
- <type>
- <v>Key = Value = term()</v>
- <v>Dict = dictionary()</v>
- </type>
<desc>
<p>This function searches for a key in a dictionary. Returns
- <c>{ok, Value}</c> where <c>Value</c> is the value associated
- with <c>Key</c>, or <c>error</c> if the key is not present in
+ <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>
</desc>
</func>
<func>
- <name>fold(Fun, Acc0, Dict) -> Acc1</name>
+ <name name="fold" arity="3"/>
<fsummary>Fold a function over a dictionary</fsummary>
- <type>
- <v>Fun = fun(Key, Value, AccIn) -> AccOut</v>
- <v>Key = Value = term()</v>
- <v>Acc0 = Acc1 = AccIn = AccOut = term()</v>
- <v>Dict = dictionary()</v>
- </type>
<desc>
- <p>Calls <c>Fun</c> on successive keys and values of
- <c>Dict</c> together with an extra argument <c>Acc</c>
- (short for accumulator). <c>Fun</c> must return a new
- accumulator which is passed to the next call. <c>Acc0</c> is
+ <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>
+ (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. The evaluation order is
undefined.</p>
</desc>
</func>
<func>
- <name>from_list(List) -> Dict</name>
+ <name name="from_list" arity="1"/>
<fsummary>Convert a list of pairs to a dictionary</fsummary>
- <type>
- <v>List = [{Key, Value}]</v>
- <v>Dict = dictionary()</v>
- </type>
<desc>
- <p>This function converts the <c>Key</c> - <c>Value</c> list
- <c>List</c> to a dictionary.</p>
+ <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>
</desc>
</func>
<func>
- <name>is_key(Key, Dict) -> bool()</name>
+ <name name="is_key" arity="2"/>
<fsummary>Test if a key is in a dictionary</fsummary>
- <type>
- <v>Key = term()</v>
- <v>Dict = dictionary()</v>
- </type>
<desc>
- <p>This function tests if <c>Key</c> is contained in
- the dictionary <c>Dict</c>.</p>
+ <p>This function tests if <c><anno>Key</anno></c> is contained in
+ the dictionary <c><anno>Dict</anno></c>.</p>
</desc>
</func>
<func>
- <name>map(Fun, Dict1) -> Dict2</name>
+ <name name="map" arity="2"/>
<fsummary>Map a function over a dictionary</fsummary>
- <type>
- <v>Fun = fun(Key, Value1) -> Value2</v>
- <v>&nbsp;Key = Value1 = Value2 = term()</v>
- <v>Dict1 = Dict2 = dictionary()</v>
- </type>
<desc>
- <p><c>map</c> calls <c>Func</c> on successive keys and values
- of <c>Dict</c> to return a new value for each key.
+ <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>
</desc>
</func>
<func>
- <name>merge(Fun, Dict1, Dict2) -> Dict3</name>
+ <name name="merge" arity="3"/>
<fsummary>Merge two dictionaries</fsummary>
- <type>
- <v>Fun = fun(Key, Value1, Value2) -> Value</v>
- <v>&nbsp;Key = Value1 = Value2 = Value3 = term()</v>
- <v>Dict1 = Dict2 = Dict3 = dictionary()</v>
- </type>
<desc>
- <p><c>merge</c> merges two dictionaries, <c>Dict1</c> and
- <c>Dict2</c>, to create a new dictionary. All the <c>Key</c>
- - <c>Value</c> pairs from both dictionaries are included in
+ <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>Fun</c> is called with the key and both values to return a
+ <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>
<code type="none">
merge(Fun, D1, D2) ->
@@ -217,75 +163,52 @@ merge(Fun, D1, D2) ->
</desc>
</func>
<func>
- <name>new() -> dictionary()</name>
+ <name name="new" arity="0"/>
<fsummary>Create a dictionary</fsummary>
<desc>
<p>This function creates a new dictionary.</p>
</desc>
</func>
<func>
- <name>size(Dict) -> int()</name>
+ <name name="size" arity="1"/>
<fsummary>Return the number of elements in a dictionary</fsummary>
- <type>
- <v>Dict = dictionary()</v>
- </type>
<desc>
- <p>Returns the number of elements in a <c>Dict</c>.</p>
+ <p>Returns the number of elements in a <c><anno>Dict</anno></c>.</p>
</desc>
</func>
<func>
- <name>store(Key, Value, Dict1) -> Dict2</name>
+ <name name="store" arity="3"/>
<fsummary>Store a value in a dictionary</fsummary>
- <type>
- <v>Key = Value = term()</v>
- <v>Dict1 = Dict2 = dictionary()</v>
- </type>
<desc>
- <p>This function stores a <c>Key</c> - <c>Value</c> pair in a
- dictionary. If the <c>Key</c> already exists in <c>Dict1</c>,
- the associated value is replaced by <c>Value</c>.</p>
+ <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>,
+ the associated value is replaced by <c><anno>Value</anno></c>.</p>
</desc>
</func>
<func>
- <name>to_list(Dict) -> List</name>
+ <name name="to_list" arity="1"/>
<fsummary>Convert a dictionary to a list of pairs</fsummary>
- <type>
- <v>Dict = dictionary()</v>
- <v>List = [{Key, Value}]</v>
- </type>
<desc>
<p>This function converts the dictionary to a list
representation.</p>
</desc>
</func>
<func>
- <name>update(Key, Fun, Dict1) -> Dict2</name>
+ <name name="update" arity="3"/>
<fsummary>Update a value in a dictionary</fsummary>
- <type>
- <v>Key = term()</v>
- <v>Fun = fun(Value1) -> Value2</v>
- <v>&nbsp;Value1 = Value2 = term()</v>
- <v>Dict1 = Dict2 = dictionary()</v>
- </type>
<desc>
- <p>Update a value in a dictionary by calling <c>Fun</c> on
+ <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
- <c>Key</c> is not present in the dictionary.</p>
+ <c><anno>Key</anno></c> is not present in the dictionary.</p>
</desc>
</func>
<func>
- <name>update(Key, Fun, Initial, Dict1) -> Dict2</name>
+ <name name="update" arity="4"/>
<fsummary>Update a value in a dictionary</fsummary>
- <type>
- <v>Key = Initial = term()</v>
- <v>Fun = fun(Value1) -> Value2</v>
- <v>&nbsp;Value1 = Value2 = term()</v>
- <v>Dict1 = Dict2 = dictionary()</v>
- </type>
<desc>
- <p>Update a value in a dictionary by calling <c>Fun</c> on
- the value to get a new value. If <c>Key</c> is not present
- in the dictionary then <c>Initial</c> will be stored as
+ <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>
<code type="none">
@@ -294,17 +217,12 @@ append(Key, Val, D) ->
</desc>
</func>
<func>
- <name>update_counter(Key, Increment, Dict1) -> Dict2</name>
+ <name name="update_counter" arity="3"/>
<fsummary>Increment a value in a dictionary</fsummary>
- <type>
- <v>Key = term()</v>
- <v>Increment = number()</v>
- <v>Dict1 = Dict2 = dictionary()</v>
- </type>
<desc>
- <p>Add <c>Increment</c> to the value associated with <c>Key</c>
- and store this value. If <c>Key</c> is not present in
- the dictionary then <c>Increment</c> will be stored as
+ <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>
<code type="none">