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.