Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
dict(3)			   Erlang Module Definition		       dict(3)

NAME
       dict - Key-Value	Dictionary

DESCRIPTION
       Dict  implements	a Key -	Value dictionary. The representation of	a dic-
       tionary 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 differ-
       ent if they do not match	(=:=), orddict considers two keys as different
       if and only if they do not compare equal	(==).

DATA TYPES
       dict(Key, Value)

	      Dictionary as returned by	new/0.

       dict()

	      dict() is	equivalent to dict(term(), term()).

EXPORTS
       append(Key, Value, Dict1) -> Dict2

	      Types:

		 Dict1 = Dict2 = dict(Key, Value)

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

       append_list(Key,	ValList, Dict1)	-> Dict2

	      Types:

		 Dict1 = Dict2 = dict(Key, Value)
		 ValList = [Value]

	      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

	      Types:

		 Dict1 = Dict2 = dict(Key, Value)

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

       fetch(Key, Dict)	-> Value

	      Types:

		 Dict =	dict(Key, Value)

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

       fetch_keys(Dict)	-> Keys

	      Types:

		 Dict =	dict(Key, Value	:: term())
		 Keys =	[Key]

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

       filter(Pred, Dict1) -> Dict2

	      Types:

		 Pred =	fun((Key, Value) -> boolean())
		 Dict1 = Dict2 = dict(Key, Value)

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

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

	      Types:

		 Dict =	dict(Key, Value)

	      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

	      Types:

		 Fun = fun((Key, Value,	AccIn) -> AccOut)
		 Dict =	dict(Key, Value)
		 Acc0 =	Acc1 = AccIn = AccOut =	Acc

	      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 re-
	      turned if	the dict is empty. The evaluation order	is undefined.

       from_list(List) -> Dict

	      Types:

		 Dict =	dict(Key, Value)
		 List =	[{Key, Value}]

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

       is_key(Key, Dict) -> boolean()

	      Types:

		 Dict =	dict(Key, Value	:: term())

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

       map(Fun,	Dict1) -> Dict2

	      Types:

		 Fun = fun((Key, Value1) -> Value2)
		 Dict1 = dict(Key, Value1)
		 Dict2 = dict(Key, Value2)

	      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

	      Types:

		 Fun = fun((Key, Value1, Value2) -> Value)
		 Dict1 = dict(Key, Value1)
		 Dict2 = dict(Key, Value2)
		 Dict3 = dict(Key, Value)

	      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  dictio-
	      naries 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() ->	dict()

	      This function creates a new dictionary.

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

	      Types:

		 Dict =	dict()

	      Returns the number of elements in	a Dict.

       is_empty(Dict) -> boolean()

	      Types:

		 Dict =	dict()

	      Returns true if Dict has no elements, false otherwise.

       store(Key, Value, Dict1)	-> Dict2

	      Types:

		 Dict1 = Dict2 = dict(Key, 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

	      Types:

		 Dict =	dict(Key, Value)
		 List =	[{Key, Value}]

	      This function converts the dictionary to a list representation.

       update(Key, Fun,	Dict1) -> Dict2

	      Types:

		 Dict1 = Dict2 = dict(Key, Value)
		 Fun = fun((Value1 :: Value) ->	Value2 :: Value)

	      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.

       update(Key, Fun,	Initial, Dict1)	-> Dict2

	      Types:

		 Dict1 = Dict2 = dict(Key, Value)
		 Fun = fun((Value1 :: Value) ->	Value2 :: Value)
		 Initial = Value

	      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:

	      append(Key, Val, D) ->
		  update(Key, fun (Old)	-> Old ++ [Val]	end, [Val], D).

       update_counter(Key, Increment, Dict1) ->	Dict2

	      Types:

		 Dict1 = Dict2 = dict(Key, Value)
		 Increment = number()

	      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 dic-
       tionary,	otherwise find.

SEE ALSO
       gb_trees(3), orddict(3)

Ericsson AB			  stdlib 2.4			       dict(3)

NAME | DESCRIPTION | DATA TYPES | EXPORTS | NOTES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=dict&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help