4.20 Analysing and Constructing Terms

[ISO]functor(?Term, ?Name, ?Arity)

True when Term is a term with functor Name/Arity. If Term is a variable it is unified with a new term whose arguments are all different variables (such a term is called a skeleton). If Term is atomic, Arity will be unified with the integer 0, and Name will be unified with Term. Raises instantiation_error() if Term is unbound and Name/Arity is insufficiently instantiated.

[ISO]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.^{65The instantiation pattern (-, +, ?) is an extension to `standard' Prolog. Some systems provide genarg/3 that covers this pattern.} The predicate arg/3 fails silently if Arg = 0 or Arg > arity and raises the exception domain_error(not_less_than_zero, Arg) if Arg < 0.

[ISO]?Term =.. ?List

List is a list whose head is the functor of Term and the remaining arguments are the arguments of the term. Either side of the predicate 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, +Start, -End, +Options)

As numbervars/3, but providing the following options:

functor_name(+Atom)

Name of the functor to use instead of $VAR.

attvar(+Action)

What to do if an attributed variable is encountered. Options are skip, which causes numbervars/3 to ignore the attributed variable, bind which causes it to thread it as a normal variable and assign the next '$VAR'(N) term to it, or (default) error which raises a type_error exception.^{66This behaviour was decided after a long discussion between David Reitter, Richard O'Keefe, Bart Demoen and Tom Schrijvers.}

singletons(+Bool)

If true (default false), numbervars/4 does singleton detection. Singleton variables are unified with '$VAR'('_'), causing them to be printed as _ by write_term/2 using the numbervars option. This option is exploited by portray_clause/2 and write_canonical/2.^{bugCurrently this option is ignored for cyclic terms.}

var_number(@Term, -VarNumber)

True if Term is numbered by numbervars/3 and VarNumber is the number given to this variable. This predicate avoids the need for unification with '$VAR'(X) and opens the path for replacing this valid Prolog term by an internal representation that has no textual equivalent.

[ISO]term_variables(+Term, -List)

Unify List with a list of variables, each sharing with a unique variable of Term.^{67This predicate used to be called free_variables/2 . The name term_variables/2 is more widely used. The old predicate is still available from the library library(backcomp).} The variables in List are ordered in order of appearance traversing Term depth-first and left-to-right. See also term_variables/3. For example:

?- term_variables(a(X, b(Y, X), Z), L).
L = [X, Y, Z].

term_variables(+Term, -List, ?Tail)

Difference list version of term_variables/2. That is, Tail is the tail of the variable list List.

[ISO]copy_term(+In, -Out)

Create a version of In with renamed (fresh) variables and unify it to Out. Attributed variables (see section 6.1) have their attributes copied. The implementation of copy_term/2 can deal with infinite trees (cyclic terms). As pure Prolog cannot distinguish a ground term from another ground term with exactly the same structure, ground sub-terms are shared between In and Out. Sharing ground terms does affect setarg/3. SWI-Prolog provides duplicate_term/2 to create a true copy of a term.

4.20.1 Non-logical operations on terms

Prolog is not able to modify instantiated parts of a term. Lacking that capability makes the language much safer, but unfortunately there are problems that suffer severely in terms of time and/or memory usage. Always try hard to avoid the use of these primitives, but they can be a good alternative to using dynamic predicates. See also section 6.3, discussing the use of global variables.

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. See also nb_setarg/3.

This predicate may be used for destructive assignment to terms, using them as an 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 noncopying of terms. A good practice to improve somewhat on this situation is to make sure that terms whose arguments are subject to setarg/3 have one unused and unshared variable in addition to the used arguments. This variable avoids unwanted sharing in, e.g., copy_term/2, and causes the term to be considered as non-ground.

nb_setarg(+Arg, +Term, +Value)

Assigns the Arg-th argument of the compound term Term with the given Value as setarg/3, but on backtracking the assignment is not reversed. If Value is not atomic, it is duplicated using duplicate_term/2. This predicate uses the same technique as nb_setval/2. We therefore refer to the description of nb_setval/2 for details on non-backtrackable assignment of terms. This predicate is compatible with GNU-Prolog setarg(A,T,V,false), removing the type restriction on Value. See also nb_linkarg/3. Below is an example for counting the number of solutions of a goal. Note that this implementation is thread-safe, reentrant and capable of handling exceptions. Realising these features with a traditional implementation based on assert/retract or flag/3 is much more complicated.

:- meta_predicate
        succeeds_n_times(0, -).

succeeds_n_times(Goal, Times) :-
        Counter = counter(0),
        (   Goal,
            arg(1, Counter, N0),
            N is N0 + 1,
            nb_setarg(1, Counter, N),
            fail
        ;   arg(1, Counter, Times)
        ).

nb_linkarg(+Arg, +Term, +Value)

As nb_setarg/3, but like nb_linkval/2 it does not duplicate Value. Use with extreme care and consult the documentation of nb_linkval/2 before use.

duplicate_term(+In, -Out)

Version of copy_term/2 that also copies ground terms and therefore ensures that destructive modification using setarg/3 does not affect the copy. See also nb_setval/2, nb_linkval/2, nb_setarg/3 and nb_linkarg/3.

[semidet]same_term(@T1, @T2)

True if T1 and T2 are equivalent and will remain equivalent, even if setarg/3 is used on either of them. This means T1 and T2 are the same variable, equivalent atomic data or a compound term allocated at the same address.