Term processing

### 7.4 Term processing

- `functor/3`
- `arg/3`
- `(=..)/2` - univ
- `copy_term/2`
- `setarg/4`, `setarg/3`

#### 7.4.1 `functor/3`

Templates

  `functor(+nonvar, ?atomic, ?integer)
  functor(-nonvar, +atomic, +integer)`

Description

`functor(Term, Name, Arity)` succeeds if the principal functor of `Term` is `Name` and its arity is `Arity`. This predicate can be used in two ways:

- `Term` is not a variable: extract the name (an atom or a number if `Term` is a number) and the arity of `Term` (if `Term` is atomic `Arity` = 0).
- `Term` is a variable: unify `Term` with a general term whose principal functor is given by `Name` and arity is given by `Arity`.

Errors

`Term` and `Name` are both variables |  | `instantiation_error`
`Term` and `Arity` are both variables |  | `instantiation_error`
`Term` is a variable and `Name` is neither a variable nor an atomic term |  | `type_error(atomic, Name)`
`Term` is a variable and `Arity` is neither a variable nor an integer |  | `type_error(integer, Arity)`
`Term` is a variable, `Name` is a constant but not an atom and `Arity` is an integer > 0 |  | `type_error(atom, Name)`
`Term` is a variable and `Arity` is an integer > `max_arity` flag (section 7.22.1) |  | `representation_error(max_arity)`
`Term` is a variable and `Arity` is an integer < 0 |  | `domain_error(not_less_than_zero, Arity)`

Portability

ISO predicate.

#### 7.4.2 `arg/3`

Templates

  `arg(+integer, +compound_term, ?term)`

Description

`arg(N, Term, Arg)` succeeds if the `N`th argument of `Term` is `Arg`.

Errors

`N` is a variable |  | `instantiation_error`
`Term` is a variable |  | `instantiation_error`
`N` is neither a variable nor an integer |  | `type_error(integer, N)`
`Term` is neither a variable nor a compound term |  | `type_error(compound, Term)`
`N` is an integer < 0 |  | `domain_error(not_less_than_zero, N)`

Portability

ISO predicate.

#### 7.4.3 `(=..)/2` - univ

Templates

  `=..(+nonvar, ?list)
  =..(-nonvar, +list)`

Description

`Term =.. List` succeeds if `List` is a list whose head is the atom corresponding to the principal functor of `Term` and whose tail is a list of the arguments of `Term`.

`=..` is a predefined infix operator (section 7.14.10).

Errors

`Term` is a variable and `List` is a partial list |  | `instantiation_error`
`List` is neither a partial list nor a list |  | `type_error(list, List)`
`Term` is a variable and `List` is a list whose head is a variable |  | `instantiation_error`
`List` is a list whose head `H` is neither an atom nor a variable and whose tail is not the empty list |  | `type_error(atom, H)`
`List` is a list whose head `H` is a compound term and whose tail is the empty list |  | `type_error(atomic, H)`
`Term` is a variable and `List` is the empty list |  | `domain_error(non_empty_list, [])`
`Term` is a variable and the tail of `List` has a length > `max_arity` flag (section 7.22.1) |  | `representation_error(max_arity)`

Portability

ISO predicate.

#### 7.4.4 `copy_term/2`

Templates

  `copy_term(?term, ?term)`

Description

`copy_term(Term1, Term2)` succeeds if `Term2` unifies with a term `T` which is a renamed copy of `Term1`.

Errors

None.

Portability

ISO predicate.

#### 7.4.5 `setarg/4`, `setarg/3`

Templates

  `setarg(+integer, +compound_term, +term, +boolean)
  setarg(+integer, +compound_term, +term)`

Description

`setarg(N, Term, NewValue, Undo)` replaces destructively the `N`th argument of `Term` with `NewValue`. This assignment is undone on backtracking if `Undo` = `true`. This should only used if there is no further use of the old value of the replaced argument. If `Undo` = `false` then `NewValue` must be either an atom or an integer.

`setarg(N, Term, NewValue)` is equivalent to `setarg(N, Term, NewValue, true)`.

Errors

`N` is a variable |  | `instantiation_error`
`N` is neither a variable nor an integer |  | `type_error(integer, N)`
`N` is an integer < 0 |  | `domain_error(not_less_than_zero, N)`
`Term` is a variable |  | `instantiation_error`
`Term` is neither a variable nor a compound term |  | `type_error(compound, Term)`
`NewValue` is neither an atom nor an integer and `Undo` = `false` |  | `type_error(atomic, NewValue)`
`Undo` is a variable |  | `instantiation_error`
`Undo` is neither a variable nor a boolean |  | `type_error(boolean, Undo)`

Portability

GNU Prolog predicate.

Copyright (C) 1999-2009 Daniel Diaz Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved. More about the copyright