[ library(lists_of_structures) | Reference Manual | Alphabetic Index ]
# terms_functor(?Structs, ?Length, ?Name, ?Arity)

All list elements have the given functor or atomic value
*Structs*
- List of terms, or variable
*Length*
- Integer or variable
*Name*
- Atomic or variable
*Arity*
- Integer or variable

## Description

Succeeds if Structs is a list of length Length, whose elements all
have the same functor Name/Arity. Operationally, this can be used
to either generate a list with of this form, or to check whether an
existing list corresponds to it.

This is (modulo nondeterminism) similar to

( foreach(S,Structs), count(_,1,Length), param(Name,Arity) do
functor(S,Name,Arity)
)

Note that (like in the underlying functor/3 predicate), if Arity is
zero, Name can be any atomic term (including number or string).

### Modes and Determinism

- terms_functor(-, +, +, +) is det
- terms_functor(-, -, +, +) is multi
- terms_functor(+, -, -, -) is semidet
- terms_functor(-, +, -, -) is erroneous

### Fail Conditions

Not all list elements have the same functor, or the list is not of the given length
### Exceptions

*(4) instantiation fault *
- Arguments are insufficiently instantiated
*(5) type error *
- Name is not atomic
*(5) type error *
- Arity is not an integer
*(5) type error *
- Arity is greater than 0 and Name is not an atom
*(6) out of range *
- Arity is negative

## Examples

% fill a list with structure skeletons
?- terms_functor(Ss, 3, f, 2).
Ss = [f(_275,_276), f(_278,_279), f(_281,_282)]
Yes (0.00s cpu)
% check whether all elements have same toplevel functor
?- terms_functor([f(a),f(b)], L, F, A).
L = 2
F = f
A = 1
Yes (0.00s cpu)
% complete a list acccording to a prototype
?- terms_functor([f(a)|Ss], 4, _, _).
Ss = [f(_190), f(_194), f(_198)]
Yes (0.00s cpu)
% fill a list with an atomic term (arity 0)
?- terms_functor(Ss, 3, 99, 0).
Ss = [99, 99, 99]
Yes (0.00s cpu)

## See Also

functor / 3, lists : length / 2