[ 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