9.9 Building and Dismantling Terms

The built-in predicate (=..)/2 is a clear way of building terms and taking them apart. However, it is almost never the most efficient way. functor/3 and arg/3 are generally much more efficient, though less direct. The best blend of efficiency and clarity is to write a clearly-named predicate that implements the desired operation and to use functor/3 and arg/3 in that predicate.

Here is an actual example. The task is to reimplement the built-in predicate (==)/2. The first variant uses (=..)/2 (this symbol is pronounced “univ” for historical reasons). Some Prolog textbooks recommend code similar to this.

ident_univ(X, Y) :-
        var(X),                 % If X is a variable,
        !,
        var(Y),                 % so must Y be, and
        samevar(X, Y).          % they must be the same.
ident_univ(X, Y) :-             % If X is not a variable,
        nonvar(Y),              % neither may Y be;
        X =.. [F|L],            % they must have the
        Y =.. [F|M],            % same function symbol F
        ident_list(L, M).       % and identical arguments

ident_list([], []).
ident_list([H1|T1], [H2|T2]) :-
        ident_univ(H1, H2),
        ident_list(T1, T2).

samevar(29, Y) :-               % If binding X to 29
        var(Y),                 % leaves Y unbound,
        !,                      % they were not the same
        fail.                   % variable.
samevar(_, _).                  % Otherwise they were.

This code performs the function intended; however, every time it touches a non-variable term of arity N, it constructs a list with N+1 elements, and if the two terms are identical, then these lists are reclaimed only when backtracked over or garbage collected.

Better code uses functor/3 and arg/3.

ident_farg(X, Y) :-
        (   var(X) ->           % If X is a variable,
                var(Y),         % so must Y be, and
                samevar(X, Y)   % they must be the same;
        ;   nonvar(Y),          % otherwise Y must be nonvar
            functor(X, F, N),   % The principal functors of X
            functor(Y, F, N),   % and Y must be identical,
            ident_farg(N, X, Y) % including the last N args.
        ).

ident_farg(0, _, _) :- !.
ident_farg(N, X, Y) :-          % The last N arguments are
        arg(N, X, Xn),          % identical
        arg(N, Y, Yn),          % if the Nth arguments
        ident_farg(Xn, Yn),     % are identical,
        M is N-1,               % and the last N-1 arguments
        ident_farg(M, X, Y).    % are also identical.

This approach to walking through terms using functor/3 and arg/3 avoids the construction of useless lists.

The pattern shown in the example, in which a predicate of arity K calls an auxiliary predicate of the same name of arity K+1 (the additional argument denoting the number of items remaining to process), is very common. It is not necessary to use the same name for this auxiliary predicate, but this convention is generally less prone to confusion.

In order to simply find out the principal function symbol of a term, use

| ?- the_term_is(Term),
|    functor(Term, FunctionSymbol, _).

The use of (=..)/2, as in

| ?- the_term_is(Term),
|    Term =.. [FunctionSymbol|_].

is wasteful, and should generally be avoided. The same remark applies if the arity of a term is desired.

(=..)/2 should not be used to locate a particular argument of some term. For example, instead of

Term =.. [_F,_,ArgTwo|_]

you should write

arg(2, Term, ArgTwo)

It is generally easier to get the explicit number “2” right than to write the correct number of anonymous variables in the call to (=..)/2. Other people reading the program will find the call to arg/3 a much clearer expression of the program’s intent. The program will also be more efficient. Even if several arguments of a term must be located, it is clearer and more efficient to write

arg(1, Term, First),
arg(3, Term, Third),
arg(4, Term, Fourth)

than to write

Term =.. [_,First,_,Third,Fourth|_]

Finally, (=..)/2 should not be used when the functor of the term to be operated on is known (that is, when both the function symbol and the arity are known). For example, to make a new term with the same function symbol and first arguments as another term, but one additional argument, the obvious solution might seem to be to write something like the following:

add_date(OldItem, Date, NewItem) :-
        OldItem =.. [item,Type,Ship,Serial],
        NewItem =.. [item,Type,Ship,Serial,Date].

However, this could be expressed more clearly and more efficiently as

add_date(OldItem, Date, NewItem) :-
        OldItem = item(Type,Ship,Serial),
        NewItem = item(Type,Ship,Serial,Date).

or even

add_date(item(Type,Ship,Serial), 
         Date, 
         item(Type,Ship,Serial,Date)
        ).