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/orddict.xml | 220 +++++++++++++++++++++++------------------ 1 file changed, 124 insertions(+), 96 deletions(-) (limited to 'lib/stdlib/doc/src/orddict.xml') diff --git a/lib/stdlib/doc/src/orddict.xml b/lib/stdlib/doc/src/orddict.xml index 950f688735..076b06fc38 100644 --- a/lib/stdlib/doc/src/orddict.xml +++ b/lib/stdlib/doc/src/orddict.xml @@ -24,33 +24,35 @@ orddict Robert Virding - nobody + - nobody - no + + 2007-04-16 B - orddict.sgml + orddict.xml orddict - Key-Value Dictionary as Ordered List + Key-value dictionary as ordered list. -

Orddict implements a Key - Value dictionary. +

This module provides a Key-Value dictionary. An orddict 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.

-

This module provides exactly the same interface as the module - dict but with a defined representation. One difference is + +

This module provides the same interface as the + dict(3) module + but with a defined representation. One difference is that while dict considers two keys as different if they do not match (=:=), this module considers two keys as - different if and only if they do not compare equal - (==).

+ different if and only if they do not compare equal (==).

 -

Dictionary as returned by new/0.

 +

Dictionary as returned by + new/0.

 @@ -60,202 +62,229 @@ - 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 - of values associated with Key. An exception is - generated if the initial value associated with Key is - not a list of values.

+

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.

+

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 - the current list of values associated with Key. An - exception is generated if the initial value associated with +

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 specified 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 Orddict. fetch assumes that - the Key is present in the dictionary and an exception +

Returns the value associated with Key + in dictionary Orddict. This function assumes that + the Key is present in the dictionary. 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 a dictionary.

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

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

+

Orddict2 is a dictionary of all keys and values + in Orddict1 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 a dictionary. 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 Orddict 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.

+ accumulator that is passed to the next call. Acc0 + is returned if the list is empty.

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

This function converts the Key - Value list +

Converts the Key-Value list List to a dictionary.

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

Returns true if Orddict 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 Orddict.

+

Tests if Key is contained in + dictionary Orddict.

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

map calls Fun on successive keys and values - of Orddict1 to return a new value for each key.

+

Calls Fun on successive keys and values of + Orddict1 tvo return a new value for each key.

 + - Merge two dictionaries + Merge two dictionaries. -

merge merges two dictionaries, Orddict1 and - Orddict2, 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, Orddict1 and + Orddict2, 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/3 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 an ordered dictionary + Return the number of elements in an ordered dictionary. +

Returns the number of elements in an Orddict.

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

Returns true if Orddict has no elements, false otherwise.

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

Stores a Key-Value pair in a + dictionary. If the Key already exists in + Orddict1, 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 a dictionary 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 follows:

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 +

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

-

This could be defined as:

+

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/3 and append_list/3 are included + so that keyed values can be stored in a list accumulator, for example:

 > D0 = orddict:new(),
@@ -264,19 +293,18 @@ update_counter(Key, Incr, D) ->
   D3 = orddict:append(files, f2, D2),
   D4 = orddict:append(files, f3, D3),
   orddict: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/2 is to be used if the key is known to + be in the dictionary, otherwise function find/2.

See Also -

dict(3), - gb_trees(3)

+

dict(3), + gb_trees(3)

-- cgit v1.2.3