The R13B03 release.OTP_R13B03

1 files changed, 354 insertions, 0 deletions

diff --git a/lib/stdlib/doc/src/orddict.xml b/lib/stdlib/doc/src/orddict.xml
new file mode 100644
index 0000000000..08c808f822
--- /dev/null
+++ b/lib/stdlib/doc/src/orddict.xml
@@ -0,0 +1,354 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+  <header>
+    <copyright>
+      <year>2000</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>orddict</title>
+    <prepared>Robert Virding</prepared>
+    <responsible>nobody</responsible>
+    <docno></docno>
+    <approved>nobody</approved>
+    <checked>no</checked>
+    <date>2007-04-16</date>
+    <rev>B</rev>
+    <file>orddict.sgml</file>
+  </header>
+  <module>orddict</module>
+  <modulesummary>Key-Value Dictionary as Ordered List</modulesummary>
+  <description>
+    <p><c>Orddict</c> implements 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
+      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>
+  </description>
+
+  <section>
+    <title>DATA TYPES</title>
+    <code type="none">
+ordered_dictionary()
+  as returned by new/0</code>
+  </section>
+  <funcs>
+    <func>
+      <name>append(Key, Value, Orddict1) -> Orddict2</name>
+      <fsummary>Append a value to keys in a dictionary</fsummary>
+      <type>
+        <v>Key = Value = term()</v>
+        <v>Orddict1 = Orddict2 = ordered_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, Orddict1) -> Orddict2</name>
+      <fsummary>Append new values to keys in a dictionary</fsummary>
+      <type>
+        <v>ValList = [Value]</v>
+        <v>Key = Value = term()</v>
+        <v>Orddict1 = Orddict2 = ordered_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, Orddict1) -> Orddict2</name>
+      <fsummary>Erase a key from a dictionary</fsummary>
+      <type>
+        <v>Key = term()</v>
+        <v>Orddict1 = Orddict2 = ordered_dictionary()</v>
+      </type>
+      <desc>
+        <p>This function erases all items with a given key from a
+          dictionary.</p>
+      </desc>
+    </func>
+    <func>
+      <name>fetch(Key, Orddict) -> Value</name>
+      <fsummary>Look-up values in a dictionary</fsummary>
+      <type>
+        <v>Key = Value = term()</v>
+        <v>Orddict = ordered_dictionary()</v>
+      </type>
+      <desc>
+        <p>This function returns the value associated with <c>Key</c>
+          in the dictionary <c>Orddict</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(Orddict) -> Keys</name>
+      <fsummary>Return all keys in a dictionary</fsummary>
+      <type>
+        <v>Orddict = ordered_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, Orddict1) -> Orddict2</name>
+      <fsummary>Choose elements which satisfy a predicate</fsummary>
+      <type>
+        <v>Pred = fun(Key, Value) -> bool()</v>
+        <v>&nbsp;Key = Value = term()</v>
+        <v>Orddict1 = Orddict2 = ordered_dictionary()</v>
+      </type>
+      <desc>
+        <p><c>Orddict2</c> is a dictionary of all keys and values in
+          <c>Orddict1</c> for which <c>Pred(Key, Value)</c> is <c>true</c>.</p>
+      </desc>
+    </func>
+    <func>
+      <name>find(Key, Orddict) -> {ok, Value} | error</name>
+      <fsummary>Search for a key in a dictionary</fsummary>
+      <type>
+        <v>Key = Value = term()</v>
+        <v>Orddict = ordered_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, Orddict) -> 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>Orddict = ordered_dictionary()</v>
+      </type>
+      <desc>
+        <p>Calls <c>Fun</c> on successive keys and values of
+          <c>Orddict</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) -> Orddict</name>
+      <fsummary>Convert a list of pairs to a dictionary</fsummary>
+      <type>
+        <v>List = [{Key, Value}]</v>
+        <v>Orddict = ordered_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, Orddict) -> bool()</name>
+      <fsummary>Test if a key is in a dictionary</fsummary>
+      <type>
+        <v>Key = term()</v>
+        <v>Orddict = ordered_dictionary()</v>
+      </type>
+      <desc>
+        <p>This function tests if <c>Key</c> is contained in
+          the dictionary <c>Orddict</c>.</p>
+      </desc>
+    </func>
+    <func>
+      <name>map(Fun, Orddict1) -> Orddict2</name>
+      <fsummary>Map a function over a dictionary</fsummary>
+      <type>
+        <v>Fun = fun(Key, Value1) -> Value2</v>
+        <v>&nbsp;Key = Value1 = Value2 = term()</v>
+        <v>Orddict1 = Orddict2 = ordered_dictionary()</v>
+      </type>
+      <desc>
+        <p><c>map</c> calls <c>Func</c> on successive keys and values
+          of <c>Orddict</c> to return a new value for each key.
+          The evaluation order is undefined.</p>
+      </desc>
+    </func>
+    <func>
+      <name>merge(Fun, Orddict1, Orddict2) -> Orddict3</name>
+      <fsummary>Merge two dictionaries</fsummary>
+      <type>
+        <v>Fun = fun(Key, Value1, Value2) -> Value</v>
+        <v>&nbsp;Key = Value1 = Value2 = Value3 = term()</v>
+        <v>Orddict1 = Orddict2 = Orddict3 = ordered_dictionary()</v>
+      </type>
+      <desc>
+        <p><c>merge</c> merges two dictionaries, <c>Orddict1</c> and
+          <c>Orddict2</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() -> ordered_dictionary()</name>
+      <fsummary>Create a dictionary</fsummary>
+      <desc>
+        <p>This function creates a new dictionary.</p>
+      </desc>
+    </func>
+    <func>
+      <name>size(Orddict) -> int()</name>
+      <fsummary>Return the number of elements in an ordered dictionary</fsummary>
+      <type>
+        <v>Orddict = ordered_dictionary()</v>
+      </type>
+      <desc>
+        <p>Returns the number of elements in an <c>Orddict</c>.</p>
+      </desc>
+    </func>
+    <func>
+      <name>store(Key, Value, Orddict1) -> Orddict2</name>
+      <fsummary>Store a value in a dictionary</fsummary>
+      <type>
+        <v>Key = Value = term()</v>
+        <v>Orddict1 = Orddict2 = ordered_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>Orddict1</c>,
+          the associated value is replaced by <c>Value</c>.</p>
+      </desc>
+    </func>
+    <func>
+      <name>to_list(Orddict) -> List</name>
+      <fsummary>Convert a dictionary to a list of pairs</fsummary>
+      <type>
+        <v>Orddict = ordered_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, Orddict1) -> Orddict2</name>
+      <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>Orddict1 = Orddict2 = ordered_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, Orddict1) -> Orddict2</name>
+      <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>Orddict1 = Orddict2 = ordered_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, Orddict1) -> Orddict2</name>
+      <fsummary>Increment a value in a dictionary</fsummary>
+      <type>
+        <v>Key = term()</v>
+        <v>Increment = number()</v>
+        <v>Orddict1 = Orddict2 = ordered_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 = orddict:new(),
+  D1 = orddict:store(files, [], D0),
+  D2 = orddict:append(files, f1, D1),
+  D3 = orddict:append(files, f2, D2),
+  D4 = orddict:append(files, f3, D3),
+  orddict: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="dict">dict(3)</seealso>,
+      <seealso marker="gb_trees">gb_trees(3)</seealso></p>
+  </section>
+</erlref>
+