diff options
Diffstat (limited to 'lib/stdlib/doc/src/dict.xml')
| -rw-r--r-- | lib/stdlib/doc/src/dict.xml | 347 |
1 files changed, 347 insertions, 0 deletions
diff --git a/lib/stdlib/doc/src/dict.xml b/lib/stdlib/doc/src/dict.xml new file mode 100644 index 0000000000..ebcd2eed09 --- /dev/null +++ b/lib/stdlib/doc/src/dict.xml @@ -0,0 +1,347 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> + <header> + <copyright> + <year>1996</year><year>2009</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>dict</title> + <prepared>Robert Virding</prepared> + <docno></docno> + <date>1997-01-15</date> + <rev>B</rev> + </header> + <module>dict</module> + <modulesummary>Key-Value Dictionary</modulesummary> + <description> + <p><c>Dict</c> implements 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 + 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> + </description> + + <section> + <title>DATA TYPES</title> + <code type="none"> +dictionary() + as returned by new/0</code> + </section> + <funcs> + <func> + <name>append(Key, Value, Dict1) -> Dict2</name> + <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>. An exception is + generated if the initial value associated with <c>Key</c> is + not a list of values.</p> + </desc> + </func> + <func> + <name>append_list(Key, ValList, Dict1) -> Dict2</name> + <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 + exception is generated if the initial value associated with + <c>Key</c> is not a list of values.</p> + </desc> + </func> + <func> + <name>erase(Key, Dict1) -> Dict2</name> + <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> + <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> + </desc> + </func> + <func> + <name>fetch_keys(Dict) -> Keys</name> + <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> + <fsummary>Choose elements which satisfy a predicate</fsummary> + <type> + <v>Pred = fun(Key, Value) -> bool()</v> + <v> 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> + </desc> + </func> + <func> + <name>find(Key, Dict) -> {ok, Value} | error</name> + <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 + the dictionary.</p> + </desc> + </func> + <func> + <name>fold(Fun, Acc0, Dict) -> Acc1</name> + <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 + returned if the list is empty. The evaluation order is + undefined.</p> + </desc> + </func> + <func> + <name>from_list(List) -> Dict</name> + <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 key/value list <c>List</c> to a + dictionary.</p> + </desc> + </func> + <func> + <name>is_key(Key, Dict) -> bool()</name> + <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> + </desc> + </func> + <func> + <name>map(Fun, Dict1) -> Dict2</name> + <fsummary>Map a function over a dictionary</fsummary> + <type> + <v>Fun = fun(Key, Value1) -> Value2</v> + <v> 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. + The evaluation order is undefined.</p> + </desc> + </func> + <func> + <name>merge(Fun, Dict1, Dict2) -> Dict3</name> + <fsummary>Merge two dictionaries</fsummary> + <type> + <v>Fun = fun(Key, Value1, Value2) -> Value</v> + <v> 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 + 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 + new value. <c>merge</c> could be defined as:</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>new() -> dictionary()</name> + <fsummary>Create a dictionary</fsummary> + <desc> + <p>This function creates a new dictionary.</p> + </desc> + </func> + <func> + <name>size(Dict) -> int()</name> + <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> + </desc> + </func> + <func> + <name>store(Key, Value, Dict1) -> Dict2</name> + <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> + </desc> + </func> + <func> + <name>to_list(Dict) -> List</name> + <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> + <fsummary>Update a value in a dictionary</fsummary> + <type> + <v>Key = term()</v> + <v>Fun = fun(Value1) -> Value2</v> + <v> Value1 = Value2 = term()</v> + <v>Dict1 = Dict2 = dictionary()</v> + </type> + <desc> + <p>Update the a value in a dictionary by calling <c>Fun</c> on + the value to get a new value. An exception is generated if + <c>Key</c> is not present in the dictionary.</p> + </desc> + </func> + <func> + <name>update(Key, Fun, Initial, Dict1) -> Dict2</name> + <fsummary>Update a value in a dictionary</fsummary> + <type> + <v>Key = Initial = term()</v> + <v>Fun = fun(Value1) -> Value2</v> + <v> Value1 = Value2 = term()</v> + <v>Dict1 = Dict2 = dictionary()</v> + </type> + <desc> + <p>Update the 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 + the first value. For example <c>append/3</c> could 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>update_counter(Key, Increment, Dict1) -> Dict2</name> + <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 + the first value.</p> + <p>This could be defined as:</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 + example:</p> + <pre> +> D0 = dict:new(), + D1 = dict:store(files, [], D0), + D2 = dict:append(files, f1, D1), + D3 = dict:append(files, f2, D2), + D4 = dict:append(files, f3, D3), + dict:fetch(files, D4). +[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> + </section> + + <section> + <title>See Also</title> + <p><seealso marker="gb_trees">gb_trees(3)</seealso>, + <seealso marker="orddict">orddict(3)</seealso></p> + </section> +</erlref> + |