path: root/lib/stdlib/doc/src/dict.xml

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">

<erlref>
  <header>
    <copyright>
      <year>1996</year><year>2016</year>
      <holder>Ericsson AB. All Rights Reserved.</holder>
    </copyright>
    <legalnotice>
      Licensed under the Apache License, Version 2.0 (the "License");
      you may not use this file except in compliance with the License.
      You may obtain a copy of the License at
 
          http://www.apache.org/licenses/LICENSE-2.0

      Unless required by applicable law or agreed to in writing, software
      distributed under the License is distributed on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      See the License for the specific language governing permissions 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>This module provides a <c>Key</c>-<c>Value</c> dictionary.
      The representation of a dictionary is not defined.</p>
    <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>
  </description>

  <datatypes>
    <datatype>
      <name name="dict" n_vars="2"/>
      <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>
      <desc>
        <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>
      <desc>
        <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>
      <desc>
        <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>
      <desc>
        <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>
      <desc>
        <p>Returns a list of all keys in dictionary <c>Dict</c>.</p>
      </desc>
    </func>

    <func>
      <name name="take" arity="2"/>
      <fsummary>Return value and new dictionary without element with this value.</fsummary>
      <desc>
        <p>This function returns value from dictionary and a
        new dictionary without this value.
        Returns <c>error</c> if the key is not present in the dictionary.</p>
      </desc>
    </func>

    <func>
      <name name="filter" arity="2"/>
      <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>
      </desc>
    </func>

    <func>
      <name name="find" arity="2"/>
      <fsummary>Search for a key in a dictionary.</fsummary>
      <desc>
        <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>
      <desc>
        <p>Calls <c><anno>Fun</anno></c> on successive keys and values of
          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 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>
      <desc>
        <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>
      <desc>
        <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>
      <desc>
        <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>
      <desc>
        <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>
      </desc>
    </func>

    <func>
      <name name="new" arity="0"/>
      <fsummary>Create a dictionary.</fsummary>
      <desc>
        <p>Creates a new dictionary.</p>
      </desc>
    </func>

    <func>
      <name name="size" arity="1"/>
      <fsummary>Return the number of elements in a dictionary.</fsummary>
      <desc>
        <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>
      <desc>
        <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>
      <desc>
        <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>
      <desc>
        <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>
      <desc>
        <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>
      <desc>
        <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>
      </desc>
    </func>
  </funcs>

  <section>
    <title>Notes</title>
    <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(),
  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>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"><c>gb_trees(3)</c></seealso>, 
      <seealso marker="orddict"><c>orddict(3)</c></seealso></p>
  </section>
</erlref>