[ Non-logical Variables, Arrays, Bags, Shelves and Stores | Reference Manual | Alphabetic Index ]

setval(++ElemSpec, ?Value)

Sets the value of a non-logical variable or array element to the value Value.
ElemSpec
Atom (non-logical variable) or fully instantiated compound term with positive integer arguments (array element specification).
Value
Prolog term.

Description

If ElemSpec is the name of a visible non-logical variable, its value gets set to a copy of the term value. If there was no variable visible from the context module, a local non-logical variable is created and its value is set. The value of a non-logical variable can be overwritten any number of times with any data type, including a free variable. Values of non-logical variables are copies of the original term and persist across failures.

If ElemSpec is a compound term, it must specify a visible array element: all its argument must be non negative integers smaller than the bounds specified with array/1 or array/2. If the array has been created with array/2, then Value is restricted to the type given in the declaration; otherwise Value can have any type, including a free variable. Its value can be overwritten any number of times. Values of non-logical arrays are copies of the original term and persist across failures.

Deprecated functionality: If ElemSpec is the name of a visible reference, its value will be set to the term value. Please use setref/2 for this purpose.

Modes and Determinism

Modules

This predicate is sensitive to its module context (tool predicate, see @/2).

Exceptions

(4) instantiation fault
ElemSpec is not ground
(4) instantiation fault
ElemSpec is of an array of type integer, float or byte and Value is not instantiated
(5) type error
the type of Value is not of the declared type of ElemSpec.
(5) type error
ElemSpec is a structure whose arguments are not all integers.
(5) type error
ElemSpec is neither an atom nor a ground structure.
(6) out of range
Array index in ElemSpec is out of bounds.
(41) array or global variable does not exist
ElemSpec is an element of an array which does not exist.

Examples

Success:
      local(array(a(4,3))),
          setval(a(0,0), 2),
          setval(a(1,2), "string"),
          % overwrite a(0,0) (= 2) with a free variable
          setval(a(0,0), X).
      local(array(a(4), float)),
          setval(a(0), 2.0),
          setval(a(3), -19.6).
      setval(i, 4).
      setval(j, 4),
           setval(j, "string data").

Error:
      setval(A, 2.0).            (Error 4).
      setval(a(V), 2.0).         (Error 4).
      setval(a(1.0), 2).         (Error 5).
      setval("b(0)", 2.0).       (Error 5).
      local(array(a(4))),
          setval(a(-2), 2).      (Error 6).
      local(array(a(9), integer)),
          setval(a(9), 4).       (Error 6).
      setval(no_array(1), 2.0).  (Error 41).

See Also

getval / 2, decval / 1, incval / 1, setref / 2, erase_array / 1, array / 1, array / 2, variable / 1