Permalink
Browse files

remove hand-written orddict doc file

  • Loading branch information...
1 parent 1374a7f commit 2ff5ffc1ce31ed09d68f0d9c783e262729b15cd1 Richard Carlsson committed Sep 28, 2011
Showing with 0 additions and 273 deletions.
  1. +0 −273 lib/stdlib/doc/src/orddict.xml
@@ -1,273 +0,0 @@
-<?xml version="1.0" encoding="latin1" ?>
-<!DOCTYPE erlref SYSTEM "erlref.dtd">
-
-<erlref>
- <header>
- <copyright>
- <year>2000</year><year>2011</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>
-
- <datatypes>
- <datatype>
- <name name="orddict"/>
- <desc><p>As returned by new/0.</p></desc>
- </datatype>
- </datatypes>
-
- <funcs>
- <func>
- <name name="append" arity="3"/>
- <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>
- </desc>
- </func>
- <func>
- <name name="append_list" arity="3"/>
- <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
- <c><anno>Key</anno></c> is not a list of values.</p>
- </desc>
- </func>
- <func>
- <name name="erase" arity="2"/>
- <fsummary>Erase a key from a dictionary</fsummary>
- <desc>
- <p>This function 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>
- <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
- is generated if <c><anno>Key</anno></c> is not in the dictionary.</p>
- </desc>
- </func>
- <func>
- <name name="fetch_keys" arity="1"/>
- <fsummary>Return all keys in a dictionary</fsummary>
- <desc>
- <p>This function returns a list of all keys in the dictionary.</p>
- </desc>
- </func>
- <func>
- <name name="filter" arity="2"/>
- <fsummary>Choose elements which 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>
- </desc>
- </func>
- <func>
- <name name="find" arity="2"/>
- <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>
- </desc>
- </func>
- <func>
- <name name="fold" arity="3"/>
- <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. 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>
- <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>
- </desc>
- </func>
- <func>
- <name name="is_key" arity="2"/>
- <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>
- </desc>
- </func>
- <func>
- <name name="map" arity="2"/>
- <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.
- The evaluation order is undefined.</p>
- </desc>
- </func>
- <func>
- <name name="merge" arity="3"/>
- <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>
- <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>
- <desc>
- <p>This function creates a new dictionary.</p>
- </desc>
- </func>
- <func>
- <name name="size" arity="1"/>
- <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="store" arity="3"/>
- <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>,
- 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>
- <desc>
- <p>This function converts the dictionary to a list
- representation.</p>
- </desc>
- </func>
- <func>
- <name name="update" arity="3"/>
- <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
- <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>
- <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>
- <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>
- <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>
- <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>
-

0 comments on commit 2ff5ffc

Please sign in to comment.