This predicate is true if Term is a compound term with a functor that is equal to the value of Name and an arity equal to value of Arity, if Term is atomic then must Name be equal to the value of Term and Arity must be 0.
The predicate functor/3 can be used to retrieve the functor and arity (=number of arguments) of a (compound) term, but it can also be used to compose a new compound term with a specified functor and arity. If functor/3 is used to compose a compound term then mode specification is functor(-Term, +Name, +Arity).
see also: arg/3 copy_term/2 freeze/2 get_term/2 melt/3 number vars/3 =../2
| Examples | |
| functor(foo(aa, X), Y, Z). | succeeds with Y=foo, Z=2 |
| functor(X, foo, 3). | succeeds X=foo(_, _, _) |
| functor(X, 1.5, 0). | succeeds with X=1.5 |
| functor(foo(a), foo, 2). | fails because arity is not 2 |
| functor(testfoo(a), foo, 1). | fails because functor is not foo |
| Exceptions | |
| term and Name are both variables | an instantiation_error exception is thrown |
| term and Arity are both variables | an instantiation_error exception is thrown |
| term is a variable and Name is neither a variable nor an atomic term | a type_error(atomic, Name) is thrown |
| term is a variable and Arity is neither a variable nor an integer | a type_error(integer, Arity) is thrown |
| term is a variable, Name is a number and Arity is not 0 | a type_error(atom, Name) is thrown |
| term is a variable and Arity is an integer greater than the maximum arity | a representation_error(max_arity) is thrown |
| term is a variable and Arity is an integer that is less than zero | a domain_error(not_less_than_zero, Arity is thrown |