[ 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

- swapref(+, -, ?) is det

### 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