From 84adefa331c4159d432d22840663c38f155cd4c1 Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Fri, 20 Nov 2009 14:54:40 +0000 Subject: The R13B03 release. --- lib/stdlib/doc/src/dict.xml | 347 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 347 insertions(+) create mode 100644 lib/stdlib/doc/src/dict.xml (limited to 'lib/stdlib/doc/src/dict.xml') 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 @@ + + + + +
+ + 19962009 + Ericsson AB. All Rights Reserved. + + + 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. + + + + dict + Robert Virding + + 1997-01-15 + B +
+ dict + Key-Value Dictionary + +

Dict implements a Key - Value dictionary. + The representation of a dictionary is not defined.

+

This module provides exactly the same interface as the module + orddict. One difference is that while this module + considers two keys as different if they do not match (=:=), + orddict considers two keys as different if and only if + they do not compare equal (==).

+ + +
+ DATA TYPES + +dictionary() + as returned by new/0 +
+ + + append(Key, Value, Dict1) -> Dict2 + Append a value to keys in a dictionary + + Key = Value = term() + Dict1 = Dict2 = dictionary() + + +

This function appends a new Value to the current list + of values associated with Key. An exception is + generated if the initial value associated with Key is + not a list of values.

+ + + + append_list(Key, ValList, Dict1) -> Dict2 + Append new values to keys in a dictionary + + ValList = [Value] + Key = Value = term() + Dict1 = Dict2 = dictionary() + + +

This function appends a list of values ValList to + the current list of values associated with Key. An + exception is generated if the initial value associated with + Key is not a list of values.

+ + + + erase(Key, Dict1) -> Dict2 + Erase a key from a dictionary + + Key = term() + Dict1 = Dict2 = dictionary() + + +

This function erases all items with a given key from a + dictionary.

+ + + + fetch(Key, Dict) -> Value + Look-up values in a dictionary + + Key = Value = term() + Dict = dictionary() + + +

This function returns the value associated with Key + in the dictionary Dict. fetch assumes that + the Key is present in the dictionary and an exception + is generated if Key is not in the dictionary.

+ + + + fetch_keys(Dict) -> Keys + Return all keys in a dictionary + + Dict = dictionary() + Keys = [term()] + + +

This function returns a list of all keys in the dictionary.

+ + + + filter(Pred, Dict1) -> Dict2 + Choose elements which satisfy a predicate + + Pred = fun(Key, Value) -> bool() +  Key = Value = term() + Dict1 = Dict2 = dictionary() + + +

Dict2 is a dictionary of all keys and values in + Dict1 for which Pred(Key, Value) is true.

+ + + + find(Key, Dict) -> {ok, Value} | error + Search for a key in a dictionary + + Key = Value = term() + Dict = dictionary() + + +

This function searches for a key in a dictionary. Returns + {ok, Value} where Value is the value associated + with Key, or error if the key is not present in + the dictionary.

+ + + + fold(Fun, Acc0, Dict) -> Acc1 + Fold a function over a dictionary + + Fun = fun(Key, Value, AccIn) -> AccOut + Key = Value = term() + Acc0 = Acc1 = AccIn = AccOut = term() + Dict = dictionary() + + +

Calls Fun on successive keys and values of + Dict together with an extra argument Acc + (short for accumulator). Fun must return a new + accumulator which is passed to the next call. Acc0 is + returned if the list is empty. The evaluation order is + undefined.

+ + + + from_list(List) -> Dict + Convert a list of pairs to a dictionary + + List = [{Key, Value}] + Dict = dictionary() + + +

This function converts the key/value list List to a + dictionary.

+ + + + is_key(Key, Dict) -> bool() + Test if a key is in a dictionary + + Key = term() + Dict = dictionary() + + +

This function tests if Key is contained in + the dictionary Dict.

+ + + + map(Fun, Dict1) -> Dict2 + Map a function over a dictionary + + Fun = fun(Key, Value1) -> Value2 +  Key = Value1 = Value2 = term() + Dict1 = Dict2 = dictionary() + + +

map calls Func on successive keys and values + of Dict to return a new value for each key. + The evaluation order is undefined.

+ + + + merge(Fun, Dict1, Dict2) -> Dict3 + Merge two dictionaries + + Fun = fun(Key, Value1, Value2) -> Value +  Key = Value1 = Value2 = Value3 = term() + Dict1 = Dict2 = Dict3 = dictionary() + + +

merge merges two dictionaries, Dict1 and + Dict2, to create a new dictionary. All the Key + - Value pairs from both dictionaries are included in + the new dictionary. If a key occurs in both dictionaries then + Fun is called with the key and both values to return a + new value. merge could be defined as:

+ +merge(Fun, D1, D2) -> + fold(fun (K, V1, D) -> + update(K, fun (V2) -> Fun(K, V1, V2) end, V1, D) + end, D2, D1). +

but is faster.

+ + + + new() -> dictionary() + Create a dictionary + +

This function creates a new dictionary.

+ + + + size(Dict) -> int() + Return the number of elements in a dictionary + + Dict = dictionary() + + +

Returns the number of elements in a Dict.

+ + + + store(Key, Value, Dict1) -> Dict2 + Store a value in a dictionary + + Key = Value = term() + Dict1 = Dict2 = dictionary() + + +

This function stores a Key - Value pair in a + dictionary. If the Key already exists in Dict1, + the associated value is replaced by Value.

+ + + + to_list(Dict) -> List + Convert a dictionary to a list of pairs + + Dict = dictionary() + List = [{Key, Value}] + + +

This function converts the dictionary to a list + representation.

+ + + + update(Key, Fun, Dict1) -> Dict2 + Update a value in a dictionary + + Key = term() + Fun = fun(Value1) -> Value2 +  Value1 = Value2 = term() + Dict1 = Dict2 = dictionary() + + +

Update the a value in a dictionary by calling Fun on + the value to get a new value. An exception is generated if + Key is not present in the dictionary.

+ + + + update(Key, Fun, Initial, Dict1) -> Dict2 + Update a value in a dictionary + + Key = Initial = term() + Fun = fun(Value1) -> Value2 +  Value1 = Value2 = term() + Dict1 = Dict2 = dictionary() + + +

Update the a value in a dictionary by calling Fun on + the value to get a new value. If Key is not present + in the dictionary then Initial will be stored as + the first value. For example append/3 could be defined + as:

+ +append(Key, Val, D) -> + update(Key, fun (Old) -> Old ++ [Val] end, [Val], D). + + + + update_counter(Key, Increment, Dict1) -> Dict2 + Increment a value in a dictionary + + Key = term() + Increment = number() + Dict1 = Dict2 = dictionary() + + +

Add Increment to the value associated with Key + and store this value. If Key is not present in + the dictionary then Increment will be stored as + the first value.

+

This could be defined as:

+ +update_counter(Key, Incr, D) -> + update(Key, fun (Old) -> Old + Incr end, Incr, D). +

but is faster.

+ + + + +
+ Notes +

The functions append and append_list are included + so we can store keyed values in a list accumulator. For + example:

+ 
+> 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]
+

This saves the trouble of first fetching a keyed value, + appending a new value to the list of stored values, and storing + the result. +

+

The function fetch should be used if the key is known to + be in the dictionary, otherwise find.

+
+ +
+ See Also +

gb_trees(3), + orddict(3)

+
+ + -- cgit v1.2.3