5.4.2.1 Destructive assignment in dicts

This section describes the destructive update operations defined on dicts. These actions can only update keys and not add or remove keys. If the requested key does not exist the predicate raises existence_error(key, Key, Dict). Note the additional argument.

Destructive assignment is a non-logical operation and should be used with care because the system may copy or share identical Prolog terms at any time. Some of this behaviour can be avoided by adding an additional unbound value to the dict. This prevents unwanted sharing and ensures that copy_term/2 actually copies the dict. This pitfall is demonstrated in the example below:

?- A = a{a:1}, copy_term(A,B), b_set_dict(a, A, 2).
A = B, B = a{a:2}.

?- A = a{a:1,dummy:_}, copy_term(A,B), b_set_dict(a, A, 2).
A = a{a:2, dummy:_G3195},
B = a{a:1, dummy:_G3391}.

[det]b_set_dict(+Key, !Dict, +Value)

Destructively update the value associated with Key in Dict to Value. The update is trailed and undone on backtracking. This predicate raises an existence error if Key does not appear in Dict. The update semantics are equivalent to setarg/3 and b_setval/2.

[det]nb_set_dict(+Key, !Dict, +Value)

Destructively update the value associated with Key in Dict to a copy of Value. The update is not undone on backtracking. This predicate raises an existence error if Key does not appear in Dict. The update semantics are equivalent to nb_setarg/3 and nb_setval/2.

[det]nb_link_dict(+Key, !Dict, +Value)

Destructively update the value associated with Key in Dict to Value. The update is not undone on backtracking. This predicate raises an existence error if Key does not appear in Dict. The update semantics are equivalent to nb_linkarg/3 and nb_linkval/2. Use with extreme care and consult the documentation of nb_linkval/2 before use.