[ Term Manipulation | The ECLiPSe Built-In Predicates | 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.

### Modes and Determinism

- functor(+, -, -) is det
- functor(-, +, +) is det

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

=.. / 2, arg / 3