protocol

# `nested_dictionary_protocol`

Nested dictionary protocol.

Availability:
`logtalk_load(nested_dictionaries(loader))`
Author: Paul Brown and Paulo Moura
Version: 0:1:1
Date: 2026-06-14
Compilation flags:
`static`
Dependencies:
(none)
Remarks:
(none)
Inherited public predicates:
(none)

## Public predicates

### `new/1`

Create an empty (nested) dictionary.

Compilation flags:
`static`
Template:
`new(Dictionary)`
Mode and number of proofs:
`new(--dictionary)` - `one`

### `empty/1`

True iff the dictionary is empty.

Compilation flags:
`static`
Template:
`empty(Dictionary)`
Mode and number of proofs:
`empty(@dictionary)` - `zero_or_one`

### `as_nested_dictionary/2`

Creates a (nested) dictionary term from a curly-brackted term representation.

Compilation flags:
`static`
Template:
`as_nested_dictionary(Term,Dictionary)`
Mode and number of proofs:
`as_nested_dictionary(++term,--dictionary)` - `one_or_error`
Exceptions:
`Term` is a variable:
`instantiation_error`
`Term` is neither a variable nor a valid curly-bracketed term representation:
`type_error(curly_bracketed_term,Term)`
`Dictionary` is instantiated:
`uninstantiation_error(Dictionary)`

### `as_curly_bracketed/2`

Creates a a curly-brackted term representation from a (nested) dictionary.

Compilation flags:
`static`
Template:
`as_curly_bracketed(Dictionary,Term)`
Mode and number of proofs:
`as_curly_bracketed(+dictionary,--term)` - `one_or_error`
Exceptions:
`Dictionary` is a variable or contains a variable leaf value that cannot be represented:
`instantiation_error`
`Term` is instantiated:
`uninstantiation_error(Term)`

### `lookup_in/3`

Lookup a chain of keys in a nested dictionary. Unifies `Value` with `Dictionary` when `Keys` is the empty list.

Compilation flags:
`static`
Template:
`lookup_in(Keys,Value,Dictionary)`
Mode and number of proofs:
`lookup_in(++list(ground),?term,+dictionary)` - `zero_or_more`

### `update_in/4`

Updates the value found by traversing through the nested keys.

Compilation flags:
`static`
Template:
`update_in(OldDictionary,Keys,Value,NewDictionary)`
Mode and number of proofs:
`update_in(+dictionary,++list(ground),++term,--dictionary)` - `zero_or_one`

### `update_in/5`

Updates the value found by traversing through the nested keys, only succeeding if the value found after traversal matches the old value.

Compilation flags:
`static`
Template:
`update_in(OldDictionary,Keys,OldValue,NewValue,NewDictionary)`
Mode and number of proofs:
`update_in(+dictionary,++list(ground),?term,++term,--dictionary)` - `zero_or_one`

### `insert_in/4`

Inserts a key-value pair into a dictionary by traversing through the nested keys. When the key already exists, the associated value is updated.

Compilation flags:
`static`
Template:
`insert_in(OldDictionary,Keys,Value,NewDictionary)`
Mode and number of proofs:
`insert_in(+dictionary,++list(ground),++term,--dictionary)` - `zero_or_one`

### `delete_in/4`

Deletes a matching key-value pair from a dictionary by traversing through the nested keys, returning the updated dictionary.

Compilation flags:
`static`
Template:
`delete_in(OldDictionary,Keys,Value,NewDictionary)`
Mode and number of proofs:
`delete_in(+dictionary,++list(ground),?term,--dictionary)` - `zero_or_one`

## Protected predicates

(none)

## Private predicates

(none)

## Operators

(none)

See also

navltree, nbintree, nrbtree