[ Non-logical Variables, Arrays, Bags, Shelves and Stores | Reference Manual | Alphabetic Index ]

swapref(+Name, -OldValue, ?NewValue)

Get and set the value of the named reference.
Name
Atom (name of a reference).
OldValue
Output variable.
NewValue
Prolog term.

Description

If Name is the name of a (previously declared) reference, its old value will be unified with OldValue, and the reference changed to refer to NewValue.

This is a combination of getref/2 and setref/2, behaving like 

        swapref(Name, OldValue, NewValue) :-
            getref(Name, OldValue),
            setref(Name, NewValue).
Note that NewValue can be instantiated (or further instantiated) _after_ the reference has been set to refer to it. Therefore it is possible to use OldValue in the construction of NewValue.

Modes and Determinism

Modules

This predicate is sensitive to its module context (tool predicate, see @/2).

Exceptions

(4) instantiation fault
Name is uninstantiated
(5) type error
Name is not an atom.
(45) named object does not exist
Name has not been declared as a reference.

Examples

% Example: a backtrackable counter

    :- local reference(ctr, 0).
    incref(Name) :-
        swapref(Name, Old, New),
        New is Old+1.

    ?- incref(ctr), incref(ctr), getref(ctr, C).
    C = 2
    Yes (0.00s cpu)

    ?- incref(ctr), incref(ctr), fail ; getref(ctr, C).
    C = 0
    Yes (0.00s cpu)


% Example: a backtrackable term stack

    :- local reference(stack, []).
    push(Name, X) :- swapref(Name, Xs, [X|Xs]).
    pop(Name, X)  :- swapref(Name, [X|Xs], Xs).
    top(Name, X)  :- getref(Name, [X|_]).

    ?- push(stack, a), push(stack, b), getref(stack, Xs).
    Xs = [b, a]
    Yes (0.00s cpu)

    ?- push(stack, a), push(stack, b), pop(stack, X), getref(stack, Xs).
    X = b
    Xs = [a]
    Yes (0.00s cpu)

    ?- (push(stack, a) ; push(stack, b)), getref(stack, Xs).
    Xs = [a]
    Yes (0.00s cpu, solution 1, maybe more)
    Xs = [b]
    Yes (0.00s cpu, solution 2)

See Also

reference / 2, getref / 2, setref / 2