From 229d0d8ca88bc344bed89e46541b325c1d267996 Mon Sep 17 00:00:00 2001 From: Hans Bolinder Date: Fri, 6 May 2011 15:58:09 +0200 Subject: r Use Erlang specs and types for documentation --- lib/stdlib/doc/src/dict.xml | 212 ++++++++++++++------------------------------ 1 file changed, 65 insertions(+), 147 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 0cc76e0c78..b01acd02bf 100644 --- a/lib/stdlib/doc/src/dict.xml +++ b/lib/stdlib/doc/src/dict.xml @@ -39,174 +39,120 @@ they do not compare equal (==).

-
- DATA TYPES - -dictionary() - as returned by new/0 -
+ + + dict() +

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.

- +

This function appends a new Value to the current list + of values associated with Key.

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

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.

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

+

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.

+

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

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.

+

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.

+

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

map calls Fun on successive keys and values + of Dict1 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 +

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

merge(Fun, D1, D2) -> @@ -217,75 +163,52 @@ merge(Fun, D1, D2) -> - 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.

+

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.

+

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 a value in a dictionary by calling Fun on +

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

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

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:

@@ -294,17 +217,12 @@ append(Key, 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 +

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:

-- cgit v1.2.3