4.20 Analysing and Constructing Terms

functor(?Term, ?Functor, ?Arity)

Succeeds if Term is a term with functor Functor and arity Arity. If Term is a variable it is unified with a new term holding only variables. functor/3 silently fails on instantiation faults (33) If Term is an atom or number, Functor will be unified with Term and arity will be unified with the integer 0 (zero).

arg(?Arg, ?Term, ?Value)

Term should be instantiated to a term, Arg to an integer between 1 and the arity of Term. Value is unified with the Arg-th argument of Term. Arg may also be unbound. In this case Value will be unified with the successive arguments of the term. On successful unification, Arg is unified with the argument number. Backtracking yields alternative solutions. (34) The predicate arg/3 fails silently if Arg = 0 or Arg > arity and raises the exception domain_error(not_less_then_zero, Arg) if Arg < 0.

setarg(+Arg, +Term, +Value)

Extra-logical predicate. Assigns the Arg-th argument of the compound term Term with the given Value. The assignment is undone if backtracking brings the state back into a position before the setarg/3 call.

This predicate may be used for destructive assignment to terms, using them as and extra-logical storage bin. Always try hard to avoid the use of setarg/3 as it is not supported by many Prolog systems and one has to be very careful about unexpected copying as well as unexpected not copying of terms.

?Term =.. ?List

List is a list which head is the functor of Term and the remaining arguments are the arguments of the term. Each of the arguments may be a variable, but not both. This predicate is called `Univ'. Examples:

?- foo(hello, X) =.. List. List = [foo, hello, X] ?- Term =.. [baz, foo(1)] Term = baz(foo(1))

numbervars(+Term, +Start, -End)

Unify the free variables of Term with a term $VAR(N), where N is the number of the variable. Counting starts at Start. End is unified with the number that should be given to the next variable. Example:

?- numbervars(foo(A, B, A), 0, End). A = '$VAR'(0) B = '$VAR'(1) End = 2

See also the numbervars option to write_term/3 and numbervars/4.

numbervars(+Term, +FunctionSymbol, +Start, -End)

As numbervars/3, but instead of using the fixed $VAR the function symbol is determined by extra FunctionSymbol argument.

free_variables(+Term, -List)

Unify List with a list of variables, each sharing with a unique variable of Term. For example:

?- free_variables(a(X, b(Y, X), Z), L). L = [G367, G366, G371] X = G367 Y = G366 Z = G371

copy_term(+In, -Out)

Make a copy of term In and unify the result with Out. Ground parts of In are shared by Out. Provided In and Out have no sharing variables before this call they will have no sharing variables afterwards. copy_term/2 is semantically equivalent to:

copy_term(In, Out) :- recorda(copy_key, In, Ref), recorded(copy_key, Out, Ref), erase(Ref).

Note that as copy_term/2 does not create copies for ground terms setarg/3 affects both the copy and original.