From 68d53c01b0b8e9a007a6a30158c19e34b2d2a34e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= Date: Wed, 18 May 2016 15:53:35 +0200 Subject: Update STDLIB documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Language cleaned up by the technical writers xsipewe and tmanevik from Combitech. Proofreading and corrections by Björn Gustavsson and Hans Bolinder. --- lib/stdlib/doc/src/dict.xml | 208 +++++++++++++++++++++++++------------------- 1 file changed, 119 insertions(+), 89 deletions(-) (limited to 'lib/stdlib/doc/src/dict.xml') diff --git a/lib/stdlib/doc/src/dict.xml b/lib/stdlib/doc/src/dict.xml index 20bab99a9c..c926ff1b5b 100644 --- a/lib/stdlib/doc/src/dict.xml +++ b/lib/stdlib/doc/src/dict.xml @@ -29,12 +29,13 @@ B dict - Key-Value Dictionary + Key-value dictionary. -

Dict implements a Key - Value dictionary. +

This module provides 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 +

This module provides the same interface as the + orddict(3) module. + 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 (==).

@@ -43,211 +44,241 @@ -

Dictionary as returned by new/0.

 +

Dictionary as returned by + new/0.

+ + - Append a value to keys in a dictionary + Append a value to keys in a dictionary. -

This function appends a new Value to the current list +

Appends a new Value to the current list of values associated with Key.

+

See also section Notes.

 + - Append new values to keys in a dictionary + Append new values to keys in a dictionary. -

This function appends a list of values ValList to +

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.

+

See also section Notes.

 + - Erase a key from a dictionary + Erase a key from a dictionary. -

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

+

Erases all items with a given key from a dictionary.

 + - Look-up values in a dictionary + Look up values in a 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 +

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

+

See also section Notes.

 + - Return all keys in a dictionary + Return all keys in a dictionary. -

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

+

Returns a list of all keys in dictionary Dict.

 + - Choose elements which satisfy a predicate + Select elements that satisfy a predicate.

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

+ Dict1 for which + Pred(Key, Value) is + true.

 + - Search for a key in a dictionary + Search for a key in a 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.

+

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

+

See also section Notes.

 + - Fold a function over a dictionary + Fold a function over a dictionary.

Calls Fun on successive keys and values of - Dict together with an extra argument Acc + dictionary 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 dict is empty. The evaluation order is + accumulator that is passed to the next call. Acc0 + is returned if the dictionary is empty. The evaluation order is undefined.

 + - Convert a list of pairs to a dictionary + Convert a list of pairs to a dictionary. -

This function converts the Key - Value list - List to a dictionary.

+

Converts the Key-Value list + List to dictionary Dict.

 + + + + Return true if the dictionary is empty. + +

Returns true if dictionary Dict has no + elements, otherwise false.

+ + + - Test if a key is in a dictionary + Test if a key is in a dictionary. -

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

+

Tests if Key is contained in + dictionary Dict.

 + - Map a function over a dictionary + Map a function over a dictionary. -

map calls Fun on successive keys and values - of Dict1 to return a new value for each key. - The evaluation order is undefined.

+

Calls Fun on successive keys and values + of dictionary Dict1 to return a new value for + each key. The evaluation order is undefined.

 + - Merge two dictionaries + Merge two dictionaries. -

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:

+

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, Fun is called with the + key and both values to return a new value. + merge can be defined as follows, but is faster:

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.

 + - Create a dictionary + Create a dictionary. -

This function creates a new dictionary.

+

Creates a new dictionary.

 + - Return the number of elements in a dictionary + Return the number of elements in a dictionary. -

Returns the number of elements in a Dict.

- - - - - Return true if the dictionary is empty - -

Returns true if Dict has no elements, false otherwise.

+

Returns the number of elements in dictionary + Dict.

 + - Store a value in a dictionary + Store a value in a dictionary. -

This function stores a Key - Value pair in a - dictionary. If the Key already exists in Dict1, +

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

 + - Convert a dictionary to a list of pairs + Convert a dictionary to a list of pairs. -

This function converts the dictionary to a list - representation.

+

Converts dictionary Dict to a list representation.

 + - Update a value in a dictionary + Update a value in a dictionary. -

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

Updates 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 a value in a dictionary + Update a value in a dictionary. -

Update 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:

+

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

append(Key, Val, D) -> update(Key, fun (Old) -> Old ++ [Val] end, [Val], D). + - Increment a value in a dictionary + Increment a value in a 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:

+

Adds Increment to the value associated with + Key and stores this value. + If Key is not present in the dictionary, + Increment is stored as the first value.

+

This can be defined as follows, but is faster:

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

Functions append and append_list are included + so that keyed values can be stored in a list accumulator, for example:

 > D0 = dict:new(),
@@ -256,19 +287,18 @@ update_counter(Key, Incr, D) ->
   D3 = dict:append(files, f2, D2),
   D4 = dict:append(files, f3, D3),
   dict:fetch(files, D4).
-[f1,f2,f3]
+[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.

+ the result.

+

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

See Also -

gb_trees(3), - orddict(3)

+

gb_trees(3), + orddict(3)

-- cgit v1.2.3