[ Term Manipulation | Reference Manual | Alphabetic Index ]

functor(?Term, ?Functor, ?Arity)

Succeeds if the compound term Term has functor Functor and arity Arity or if Term and Functor are atomic and equal, and Arity is 0.
Term
Prolog term.
Functor
Atomic term or variable.
Arity
Positive integer or variable.

Description

If Term is instantiated, its functor is unified with Functor and its arity with Arity.

If Term is not instantiated, it is bound to a term with functor Functor and arity Arity.

This predicate regards atomic terms (number, atom or string) as terms with arity 0 and functor equal to the term.

To query only the arity of a term, arity/2 can be used instead of functor/3.

Modes and Determinism

Exceptions

(4) instantiation fault
Term and either (or both) of Functor and Arity are uninstantiated (non-coroutine mode only).
(5) type error
Arity is neither a variable nor an integer.
(5) type error
Functor is neither a variable nor an atomic term.
(6) out of range
Arity is a negative integer.

Examples

   Success:
   functor(f(1,2),f,2).
   functor(f(1,2),F,A).  (gives F=f, A=2).
   functor(T,f,3).       (gives T=f(_g50, _g52, _g54)).
   functor(T,.,2).       (gives T=[_g48 | _g50]).
   functor([],F,A).      (gives F=[], A=0).
   functor("s",F,A).     (gives F="s", A=0).
   Fail:
   functor(f(1,2),f,3).
   functor("compound(g)",compound,1).
   functor(f(1,2),"f",2).
   Error:
   functor(T,F,A).                    (Error 4).
   functor("f",[f],X).                (Error 5).
   functor(X,[a],Y).                  (Error 5).
   functor(f(1,2),f,-1).              (Error 6).



See Also

arity / 2, =.. / 2, arg / 3