orddict(3)



orddict(3erl)              Erlang Module Definition              orddict(3erl)

NAME
       orddict - Key-value dictionary as ordered list.

DESCRIPTION
       This  module provides a Key-Value dictionary. An orddict is a represen-
       tation of a dictionary, where a list of pairs is used to store the keys
       and  values.  The list is ordered after the keys in the Erlang term or-
       der.

       This module provides the same interface as the  dict(3erl)  module  but
       with  a  defined representation. One difference is that while dict con-
       siders 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 (==).

DATA TYPES
       orddict(Key, Value) = [{Key, Value}]

              Dictionary as returned by new/0.

       orddict() = orddict(term(), term())

EXPORTS
       append(Key, Value, Orddict1) -> Orddict2

              Types:

                 Orddict1 = Orddict2 = orddict(Key, Value)

              Appends a new Value to the current  list  of  values  associated
              with Key. An exception is generated if the initial value associ-
              ated with Key is not a list of values.

              See also section Notes.

       append_list(Key, ValList, Orddict1) -> Orddict2

              Types:

                 ValList = [Value]
                 Orddict1 = Orddict2 = orddict(Key, Value)

              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(Key, Orddict1) -> Orddict2

              Types:

                 Orddict1 = Orddict2 = orddict(Key, Value)

              Erases all items with a specified key from a dictionary.

       fetch(Key, Orddict) -> Value

              Types:

                 Orddict = orddict(Key, Value)

              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.

       fetch_keys(Orddict) -> Keys

              Types:

                 Orddict = orddict(Key, Value :: term())
                 Keys = [Key]

              Returns a list of all keys in a dictionary.

       take(Key, Orddict) -> {Value, Orddict1} | error

              Types:

                 Orddict = Orddict1 = orddict(Key, Value)
                 Key = Value = term()

              This function returns value from dictionary and  new  dictionary
              without  this  value. Returns error if the key is not present in
              the dictionary.

       filter(Pred, Orddict1) -> Orddict2

              Types:

                 Pred = fun((Key, Value) -> boolean())
                 Orddict1 = Orddict2 = orddict(Key, Value)

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

       find(Key, Orddict) -> {ok, Value} | error

              Types:

                 Orddict = orddict(Key, Value)

              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(Fun, Acc0, Orddict) -> Acc1

              Types:

                 Fun = fun((Key, Value, AccIn) -> AccOut)
                 Orddict = orddict(Key, Value)
                 Acc0 = Acc1 = AccIn = AccOut = Acc

              Calls Fun on successive keys and values of Orddict together with
              an extra argument Acc (short for accumulator). Fun must return a
              new  accumulator  that  is  passed to the next call. Acc0 is re-
              turned if the list is empty.

       from_list(List) -> Orddict

              Types:

                 List = [{Key, Value}]
                 Orddict = orddict(Key, Value)

              Converts the Key-Value list List to a dictionary.

       is_empty(Orddict) -> boolean()

              Types:

                 Orddict = orddict()

              Returns true if Orddict has no elements, otherwise false.

       is_key(Key, Orddict) -> boolean()

              Types:

                 Orddict = orddict(Key, Value :: term())

              Tests if Key is contained in dictionary Orddict.

       map(Fun, Orddict1) -> Orddict2

              Types:

                 Fun = fun((Key, Value1) -> Value2)
                 Orddict1 = orddict(Key, Value1)
                 Orddict2 = orddict(Key, Value2)

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

       merge(Fun, Orddict1, Orddict2) -> Orddict3

              Types:

                 Fun = fun((Key, Value1, Value2) -> Value)
                 Orddict1 = orddict(Key, Value1)
                 Orddict2 = orddict(Key, Value2)
                 Orddict3 = orddict(Key, Value)

              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 dictio-
              naries, 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).

       new() -> orddict()

              Creates a new dictionary.

       size(Orddict) -> integer() >= 0

              Types:

                 Orddict = orddict()

              Returns the number of elements in an Orddict.

       store(Key, Value, Orddict1) -> Orddict2

              Types:

                 Orddict1 = Orddict2 = orddict(Key, Value)

              Stores  a Key-Value pair in a dictionary. If the Key already ex-
              ists in Orddict1, the associated value is replaced by Value.

       to_list(Orddict) -> List

              Types:

                 Orddict = orddict(Key, Value)
                 List = [{Key, Value}]

              Converts a dictionary to a list representation.

       update(Key, Fun, Orddict1) -> Orddict2

              Types:

                 Fun = fun((Value1 :: Value) -> Value2 :: Value)
                 Orddict1 = Orddict2 = orddict(Key, Value)

              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(Key, Fun, Initial, Orddict1) -> Orddict2

              Types:

                 Initial = Value
                 Fun = fun((Value1 :: Value) -> Value2 :: Value)
                 Orddict1 = Orddict2 = orddict(Key, Value)

              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, Ini-
              tial 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).

       update_counter(Key, Increment, Orddict1) -> Orddict2

              Types:

                 Orddict1 = Orddict2 = orddict(Key, Value)
                 Increment = number()

              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 can be defined as follows, but is faster:

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

NOTES
       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(),
         D1 = orddict:store(files, [], D0),
         D2 = orddict:append(files, f1, D1),
         D3 = orddict:append(files, f2, D2),
         D4 = orddict:append(files, f3, D3),
         orddict: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.

       Function fetch/2 is to be used if the key is known to be in the dictio-
       nary, otherwise function find/2.

SEE ALSO
       dict(3erl), gb_trees(3erl)

Ericsson AB                       stdlib 3.13                    orddict(3erl)

Man(1) output converted with man2html
list of all man pages