protocol

# dictionaryp

> Dictionary protocol.

author:
  `Paulo Moura`
version:
  `2.0`
date:
  `2010/2/26`

compilation flags:
  `static`

(no dependencies on other files)

## Public interface

### as_dictionary/2

> Converts a list of key-value pairs to a dictionary.

compilation flags:
  `static`
template:
  `as_dictionary(Pairs,Dictionary)`
mode – number of proofs:
  `as_dictionary(@list(pairs),-dictionary) – one`

### as_list/2

> Converts a dictionary to a ordered list of key-value pairs.

compilation flags:
  `static`
template:
  `as_list(Dictionary,Pairs)`
mode – number of proofs:
  `as_list(@dictionary,-list(pairs)) – one`

### clone/3

> Clones a dictionary using the same keys but with all values unbound and returning a list of all the pairs in the new clone.

compilation flags:
  `static`
template:
  `clone(Dictionary,Clone,ClonePairs)`
mode – number of proofs:
  `clone(+tree,-tree,-list(pairs)) – one`

### clone/4

> Clones a dictionary using the same keys but with all values unbound and returning the list of all pairs in the dictionary and in the clone.

compilation flags:
  `static`
template:
  `clone(Dictionary,Pairs,Clone,ClonePairs)`
mode – number of proofs:
  `clone(+tree,-list(pairs),-tree,-list(pairs)) – one`

### insert/4

> Inserts a Key-Value pair into a dictionary, returning the updated dictionary. When the key already exists, the associated value is updated.

compilation flags:
  `static`
template:
  `insert(OldDictionary,Key,Value,NewDictionary)`
mode – number of proofs:
  `insert(+dictionary,+ground,@term,-dictionary) – one`

### delete/4

> Deletes a matching Key-Value pair from a dictionary, returning the updated dictionary.

compilation flags:
  `static`
template:
  `delete(OldDictionary,Key,Value,NewDictionary)`
mode – number of proofs:
  `delete(+dictionary,@ground,?term,-dictionary) – zero_or_one`

### update/4

> Updates the value associated with Key in a dictionary, returning the updated dictionary. Fails if it cannot find the key.

compilation flags:
  `static`
template:
  `update(OldDictionary,Key,NewValue,NewDictionary)`
mode – number of proofs:
  `update(+dictionary,@ground,+term,-dictionary) – zero_or_one`

### update/5

> Updates the value associated with Key in a dictionary, returning the updated dictionary. Fails if it cannot find the key or if the existing value does not match OldValue.

compilation flags:
  `static`
template:
  `update(OldDictionary,Key,OldValue,NewValue,NewDictionary)`
mode – number of proofs:
  `update(+dictionary,@ground,?term,+term,-dictionary) – zero_or_one`

### empty/1

> True if the dictionary is empty.

compilation flags:
  `static`
template:
  `empty(Dictionary)`
mode – number of proofs:
  `empty(@dictionary) – zero_or_one`

### lookup/3

> Lookups a matching Key-Value pair from a dictionary.

compilation flags:
  `static`
template:
  `lookup(Key,Value,Dictionary)`
mode – number of proofs:
  `lookup(+ground,?term,@dictionary) – zero_or_one`
  `lookup(-ground,?term,@dictionary) – zero_or_more`

### previous/4

> Returns the previous pair in a dictionary given a key.

compilation flags:
  `static`
template:
  `previous(Dictionary,Key,Previous,Value)`
mode – number of proofs:
  `previous(+dictionary,+key,-key,-value) – zero_or_one`

### next/4

> Returns the next pair in a dictionary given a key.

compilation flags:
  `static`
template:
  `next(Dictionary,Key,Next,Value)`
mode – number of proofs:
  `next(+dictionary,+key,-key,-value) – zero_or_one`

### min/3

> Returns the pair with the minimum key in a dictionary. Fails if the dictionary is empty.

compilation flags:
  `static`
template:
  `min(Dictionary,Key,Value)`
mode – number of proofs:
  `min(+dictionary,-key,-value) – zero_or_one`

### max/3

> Returns the pair with the maximum key in a dictionary. Fails if the dictionary is empty.

compilation flags:
  `static`
template:
  `max(Dictionary,Key,Value)`
mode – number of proofs:
  `max(+dictionary,-key,-value) – zero_or_one`

### delete_min/4

> Deletes the pair with the minimum key from a dictionary, returning the deleted pair and the updated dictionary.

compilation flags:
  `static`
template:
  `delete_min(OldDictionary,Key,Value,NewDictionary)`
mode – number of proofs:
  `delete_min(+dictionary,-key,-value,-dictionary) – zero_or_one`

### delete_max/4

> Deletes the pair with the maximum key from a dictionary, returning the deleted pair and the updated dictionary.

compilation flags:
  `static`
template:
  `delete_max(OldDictionary,Key,Value,NewDictionary)`
mode – number of proofs:
  `delete_max(+dictionary,-key,-value,-dictionary) – zero_or_one`

### keys/2

> Returns a list with all dictionary keys.

compilation flags:
  `static`
template:
  `keys(Dictionary,List)`
mode – number of proofs:
  `keys(@dictionary,-list) – one`

### map/2

> Maps a closure over each dictionary key-value pair. Fails if the mapped closure attempts to modify the keys.

compilation flags:
  `static`
template:
  `map(Closure,Dictionary)`
meta-predicate template:
  `map(1,*)`
mode – number of proofs:
  `map(@callable,+dictionary) – zero_or_more`

### map/3

> Maps a closure over each dictionary key-value pair, returning the new dictionary. Fails if the mapped closure attempts to modify the keys.

compilation flags:
  `static`
template:
  `map(Closure,OldDictionary,NewDictionary)`
meta-predicate template:
  `map(2,*,*)`
mode – number of proofs:
  `map(@callable,+dictionary,-dictionary) – zero_or_more`

### apply/4

> Applies a closure to a specific key-value pair, returning the new dictionary. Fails if the key cannot be found or if the mapped closure attempts to modify the key.

compilation flags:
  `static`
template:
  `apply(Closure,OldDictionary,Key,NewDictionary)`
meta-predicate template:
  `apply(2,*,*,*)`
mode – number of proofs:
  `apply(+callable,+dictionary,+key,-dictionary) – zero_or_one`

### size/2

> Number of dictionary entries.

compilation flags:
  `static`
template:
  `size(Dictionary,Size)`
mode – number of proofs:
  `size(@dictionary,?integer) – zero_or_one`

## Protected interface

(none)

## Private predicates

(none)

## Operators

### (none)

## Remarks

### (none)