[ Term Manipulation | The ECLiPSe Built-In Predicates | Reference Manual | Alphabetic Index ]

# setarg(+N, +Term, ?Arg)

Destructively replaces the Nth argument of the compound term Term with the term Arg.

N
  Integer not greater than the arity of Term, or a list of integers.
Term
  Compound term or external data handle.
Arg
  Prolog term.

## Description

Destructively replaces the Nth argument of the compound term Term with the term Arg. The assignment is undone on backtracking.

The use of this built-in is strongly discouraged, due to its non-logical behaviour! It is provided only to enable the implementation of certain low-level operations that could otherwise not be provided with the same efficiency. Surprising side effects can occur when you don't know exactly what you are doing. In particular, it must be assured by the programmer that the old argument value is not needed any longer and that the old argument was not aliased to some other location. The old value should also not be a variable.

If N is a list of integers and Term is a nested structure, then Arg is the subterm of Term described by this list of integers. E.g. setarg([2,1,3], Term, Arg) is the same as arg(2, Term, T1), arg(1, T1, T2), setarg(3, T2, Arg).

### Modes and Determinism

- setarg(+, +, ?) is det

### Exceptions

(4) instantiation fault
  Either N or Term (or both) is not instantiated.
(5) type error
  N is instantiated, but not to an integer.
(5) type error
  Term is instantiated, but not to a compound term.
(6) out of range
  N is an integer less than 1 or greater than the arity of Term.

## Examples

    Success:
          [eclipse]: T = s(a, b, c), setarg(2, T, hello).
          T = s(a, hello, c)
          yes.
          [eclipse]: T = s(a, b, c), ( setarg(2, T, hello) ; true ).
          T = s(a, hello, c)     More? (;)
          T = s(a, b, c)
          yes.
    Unpredictable result:
        [eclipse 10]: S=s(A), T=t(A), setarg(1, T, b).
        S = s(A)  or  S = s(b)
        A = b     or  A = A
        T = t(b)

## See Also

arg / 3, xset / 3