File: dict.html

package info (click to toggle)
erlang-doc-html 1%3A8.0-1
links: PTS
area: main
in suites: woody
size: 18,028 kB
ctags: 7,419
sloc: perl: 1,841; ansic: 323; erlang: 155
file content (278 lines) | stat: -rw-r--r-- 10,049 bytes
<HTML>
<HEAD>
<!-- refpage -->
<TITLE>dict</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<CENTER>


<A HREF="http://www.erlang.se"><IMG BORDER=0 ALT="[Erlang Systems]" SRC="min_head.gif"></A>
<H1>dict</H1>
</CENTER>
<H3>MODULE</H3>
<UL>
dict</UL>
<H3>MODULE SUMMARY</H3>
<UL>
Key-Value Dictionary</UL>
<H3>DESCRIPTION</H3>
<UL>
<P><CODE>Dict</CODE> implements a <CODE>Key</CODE> - <CODE>Value</CODE> dictionary.
The representation of a dictionary is not defined.
</UL>
<H3>EXPORTS</H3>
<P><A NAME="append%3"><STRONG><CODE>append(Key, Value, Dict1) -&#62; Dict2</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>Key = Value = term()</CODE></STRONG><BR>
<STRONG><CODE>Dict1 = Dict2 = dictionary()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>This function appends a new <CODE>Value</CODE> to the current
         list of values associated with <CODE>Key</CODE>. An exception is
         generated if the initial value associated with <CODE>Key</CODE> is
         not a list of values.
</UL>
<P><A NAME="append_list%3"><STRONG><CODE>append_list(Key, ValList, Dict1) -&#62; Dict2</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>ValList = [Value]</CODE></STRONG><BR>
<STRONG><CODE>Key = Value = [term()]</CODE></STRONG><BR>
<STRONG><CODE>Dict1 = Dict2 = dictionary()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>This function appends a list of values <CODE>ValList</CODE> to
         the current list of values associated with <CODE>Key</CODE>. An
         exception is generated if the initial value associated with
         <CODE>Key</CODE> is not a list of values.
</UL>
<P><A NAME="erase%2"><STRONG><CODE>erase(Key, Dict1) -&#62; Dict2</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>Key = term()</CODE></STRONG><BR>
<STRONG><CODE>Dict1 = Dict2 = dictionary()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>This function erases all items with a given key from a dictionary.
</UL>
<P><A NAME="fetch%2"><STRONG><CODE>fetch(Key, Dict) -&#62; Value</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>Key = Value = term()</CODE></STRONG><BR>
<STRONG><CODE>Dict = dictionary()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>This function returns the value associated with <CODE>Key</CODE> in the
         dictionary <CODE>Dict</CODE>. <CODE>fetch</CODE> assumes that
         the <CODE>Key</CODE> is present in the dictionary and an exception
         is generated if <CODE>Key</CODE> is not in the dictionary.
</UL>
<P><A NAME="fetch_keys%1"><STRONG><CODE>fetch_keys(Dict) -&#62; Keys</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>Dict = dictionary()</CODE></STRONG><BR>
<STRONG><CODE>Keys = [term()]</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>This function returns a list of all keys in the dictionary.
</UL>
<P><A NAME="filter%2"><STRONG><CODE>filter(Pred, Dict1) -&#62; Dict2</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>Pred = fun(Key, Value) -&#62; bool()</CODE></STRONG><BR>
<STRONG><CODE>Dict1 = Dict2 = dictionary()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P><CODE>Dict2</CODE> is a dictionary of all keys and values in
<CODE>Dict1</CODE> for which <CODE>Pred(Key, Value)</CODE> is
<CODE>true</CODE>.
</UL>
<P><A NAME="find%2"><STRONG><CODE>find(Key, Dict) -&#62; Result</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>Key = term()</CODE></STRONG><BR>
<STRONG><CODE>Dict = dictionary()</CODE></STRONG><BR>
<STRONG><CODE>Result = {ok, Value} | error</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>This function searches for a key in a dictionary. Returns <CODE>{ok,
         Value}</CODE> where <CODE>Value</CODE> is the value associated with
         <CODE>Key</CODE>, or <CODE>error</CODE> if the key is not present in the
         dictionary.
</UL>
<P><A NAME="fold%3"><STRONG><CODE>fold(Function, Acc0, Dict) -&#62; Acc1</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>Function = fun(Key, Value, AccIn) -&#62; AccOut</CODE></STRONG><BR>
<STRONG><CODE>Acc0 = Acc1 = AccIn = AccOut = term()</CODE></STRONG><BR>
<STRONG><CODE>Dict = dictionary()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>Calls <CODE>Function</CODE> on successive keys and values of
<CODE>Dict</CODE> together with an extra argument <CODE>Acc</CODE>
(short for accumulator). <CODE>Function</CODE> must return a new
accumulator which is passed to the next call. <CODE>Acc0</CODE>
is returned if the list is empty. The evaluation order is
undefined.
</UL>
<P><A NAME="from_list%1"><STRONG><CODE>from_list(List) -&#62; Dict</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>List = [{Key, Value}]</CODE></STRONG><BR>
<STRONG><CODE>Dict = dictionary()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>This function converts the dictionary to a list representation.
</UL>
<P><A NAME="is_key%2"><STRONG><CODE>is_key(Key, Dict) -&#62; bool()</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>Key = term()</CODE></STRONG><BR>
<STRONG><CODE>Dict = dictionary()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>This function tests if <CODE>Key</CODE> is contained in the dictionary <CODE>Dict</CODE>
</UL>
<P><A NAME="map%2"><STRONG><CODE>map(Func, Dict1) -&#62; Dict2</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>Func = fun(Key, Value) -&#62; Value</CODE></STRONG><BR>
<STRONG><CODE>Dict1 = Dict2 = dictionary()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P><CODE>map</CODE> calls <CODE>Func</CODE> on successive keys and values
of Dict to return a new value for each key. The evaluation
order is undefined.
</UL>
<P><A NAME="merge%3"><STRONG><CODE>merge(Func, Dict1, Dict2) -&#62; Dict3</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>Func = fun(Key, Value1, Value2) -&#62; Value</CODE></STRONG><BR>
<STRONG><CODE>Dict1 = Dict2 = Dict3 = dictionary()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P><CODE>merge</CODE> merges two dictionaries, Dict1 and Dict2, to
create a new dictionary. All the <CODE>Key</CODE> - <CODE>Value</CODE>
pairs from both dictionaries are included in the new
dictionary. If a key occurs in both dictionaries then
<CODE>Func</CODE> is called with the key and both values to return a
new value. <CODE>merge</CODE> could be defined as:<PRE>merge(Fun, D1, D2) -&#62;
    fold(fun (K, V1, D) -&#62;
                 update(K, fun (V2) -&#62; Fun(K, V1, V2) end, V1, D)
         end, D2, D1).</PRE><P>but is faster.
</UL>
<P><A NAME="new%0"><STRONG><CODE>new() -&#62; dictionary()</CODE></STRONG></A><BR>
<UL>
<P>This function creates a new dictionary.
</UL>
<P><A NAME="store%3"><STRONG><CODE>store(Key, Value, Dict1) -&#62; Dict2</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>Key = Value = term()</CODE></STRONG><BR>
<STRONG><CODE>Dict1 = Dict2 = dictionary()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>This function stores a <CODE>Key</CODE> - <CODE>Value</CODE> pair in a dictionary. If the 
         <CODE>Key</CODE> already exists in <CODE>Dict1</CODE>, the associated value
         is replaced by <CODE>Value</CODE>.
</UL>
<P><A NAME="to_list%1"><STRONG><CODE>to_list(Dict) -&#62; List</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>Dict = dictionary()</CODE></STRONG><BR>
<STRONG><CODE>List = [{Key, Value}]</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>This function converts the dictionary to a list representation.
</UL>
<P><A NAME="update%3"><STRONG><CODE>update(Key, Function, Dict) -&#62; Dict</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>Key = term()</CODE></STRONG><BR>
<STRONG><CODE>Function = fun(Value) -&#62; Value</CODE></STRONG><BR>
<STRONG><CODE>Dict = dictionary()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>Update the a value in a dictionary by calling
        <CODE>Function</CODE> on the value to get a new value. An exception
        is generated if <CODE>Key</CODE> is not present in the dictionary.
</UL>
<P><A NAME="update%4"><STRONG><CODE>update(Key, Function, Initial, Dict) -&#62; Dict</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>Key = Initial = term()</CODE></STRONG><BR>
<STRONG><CODE>Function = fun(Value) -&#62; Value</CODE></STRONG><BR>
<STRONG><CODE>Dict = dictionary()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>Update the a value in a dictionary by calling
        <CODE>Function</CODE> on the value to get a new value. If
        <CODE>Key</CODE> is not present in the dictionary then
        <CODE>Initial</CODE> will be stored as the first value. For example
        we could define append/3 as:<PRE>append(Key, Val, D) -&#62;
    update(Key, fun (Old) -&#62; Old ++ [Val] end, [Val], D).</PRE></UL>
<P><A NAME="update_counter%3"><STRONG><CODE>update_counter(Key, Increment, Dict) -&#62; Dict</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>Key = term()</CODE></STRONG><BR>
<STRONG><CODE>Increment = number()</CODE></STRONG><BR>
<STRONG><CODE>Dict = dictionary()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>Add <CODE>Increment</CODE> to the value associated with
        <CODE>Key</CODE> and store this value. If <CODE>Key</CODE> is not present
        in the dictionary then <CODE>Increment</CODE> will be stored as the
        first value.
<P>This is could have been defined as:<PRE>update_counter(Key, Incr, D) -&#62;
    update(Key, fun (Old) -&#62; Old + Incr end, Incr, D).</PRE><P>but is faster.
</UL>
<H3>Notes</H3>
<UL>
<P>The functions <CODE>append</CODE> and <CODE>append_list</CODE> are included
so we can store keyed values in a list <STRONG>accumulator</STRONG>. For
example:<PRE>&#62; 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>The function <CODE>fetch</CODE> should be used if the key is known to
be in the dictionary, otherwise <CODE>find</CODE>.
</UL>
<H3>AUTHORS</H3>
<UL>
Robert Virding - support@erlang.ericsson.se<BR>
</UL>
<CENTER>
<HR>
<FONT SIZE=-1>stdlib 1.10<BR>
Copyright &copy; 1991-2001
<A HREF="http://www.erlang.se">Ericsson Utvecklings AB</A><BR>
<!--#include virtual="/ssi/otp_footer.html"-->
</FONT>
</CENTER>
</BODY>
</HTML>