rec_env

Abstract environments, supporting self-referential bindings and automatic new-key generation.

Abstract environments, supporting self-referential bindings and automatic new-key generation.

Types

environment() = [mapping(), ...]

Functions

empty() -> environment()

Returns an empty environment.

is_empty(Env::environment()) -> boolean()

Returns true if the environment is empty, otherwise false.

size(Env::environment()) -> integer()

Returns the number of entries in an environment.

is_defined(Key, Env) -> boolean()

  • Key = term()
  • Env = environment()

Returns true if Key is bound in the environment, otherwise false.

keys(Env::environment()) -> [term()]

Returns the ordered list of all keys in the environment.

to_list(Env) -> [{Key, Value}]

  • Env = environment()
  • Key = term()
  • Value = term()

Returns an ordered list of {Key, Value} pairs for all keys in Env. Value is the same as that returned by get/2.

bind(Key, Value, Env) -> environment()

  • Key = term()
  • Value = term()
  • Env = environment()

Make a nonrecursive entry. This binds Key to Value. If the key already existed in the environment, the old entry is replaced.

bind_list(Ks::Keys, Vs::Values, Env) -> environment()

  • Keys = [term()]
  • Values = [term()]
  • Env = environment()

Make N nonrecursive entries. This binds each key in Keys to the corresponding value in Values. If some key already existed in the environment, the previous entry is replaced. If Keys does not have the same length as Values, an exception is generated.

delete(Key, Env) -> environment()

  • Key = term()
  • Env = environment()

Delete an entry. This removes Key from the environment.

bind_recursive(Ks::Keys, Vs::Values, F::Fun, Env) -> NewEnv

  • Keys = [term()]
  • Values = [term()]
  • Fun = (Value, Env) -> term()
  • Env = environment()
  • NewEnv = environment()

Make N recursive entries. This binds each key in Keys to the value of Fun(Value, NewEnv) for the corresponding Value. If Keys does not have the same length as Values, an exception is generated. If some key already existed in the environment, the old entry is replaced.

Note: the function Fun is evaluated each time one of the stored keys is looked up, but only then.

Examples: 

     NewEnv = bind_recursive([foo, bar], [1, 2],
 	                      fun (V, E) -> V end,
 	                      Env)

This does nothing interesting; get(foo, NewEnv) yields 1 and get(bar, NewEnv) yields 2, but there is more overhead than if the bind_list/3 function had been used. 

     NewEnv = bind_recursive([foo, bar], [1, 2],
                             fun (V, E) -> {V, E} end,
                             Env)

Here, however, get(foo, NewEnv) will yield {1, NewEnv} and get(bar, NewEnv) will yield {2, NewEnv}, i.e., the environment NewEnv contains recursive bindings.

lookup(Key, Env) -> error | {ok, Value}

  • Key = term()
  • Env = environment()
  • Value = term()

Returns {ok, Value} if Key is bound to Value in Env, and error otherwise.

get(Key, Env) -> Value

  • Key = term()
  • Env = environment()
  • Value = term()

Returns the value that Key is bound to in Env. Throws {undefined, Key} if the key does not exist in Env.

new_key(Env::environment()) -> integer()

Returns an integer which is not already used as key in the environment. New integers are generated using an algorithm which tries to keep the values randomly distributed within a reasonably small range relative to the number of entries in the environment.

This function uses the Erlang standard library module random to generate new keys.

Note that only the new key is returned; the environment itself is not updated by this function.

new_key(F::Function, Env) -> term()

  • Function = (integer()) -> term()
  • Env = environment()

Returns a term which is not already used as key in the environment. The term is generated by applying Function to an integer generated as in new_key/1.

Note that only the generated term is returned; the environment itself is not updated by this function.

new_keys(N, Env) -> [integer()]

  • N = integer()
  • Env = environment()

Returns a list of N distinct integers that are not already used as keys in the environment. See new_key/1 for details.

new_keys(N, F::Function, Env) -> [term()]

  • N = integer()
  • Function = (integer()) -> term()
  • Env = environment()

Returns a list of N distinct terms that are not already used as keys in the environment. See new_key/3 for details.

Richard Carlsson [email protected]