[ Term Manipulation | Reference Manual | Alphabetic Index ]
# subscript(+Term, ++Subscript, -Elem)

Accesses the subterm Elem of Term, as specified by Subscript
*Term*
- Compound term (possibly nested), string, or external data handle.
*Subscript*
- A list of integers, ranges or integer arithmetic expressions.
*Elem*
- Prolog term.

## Description

If term is a compound term, e.g. a vector represented as a structure,
or a matrix represented as a structure of structures and so on, then
subscript/3 provides access to the term's components.
Subscript is a list of (sub)structure argument indices describing
which element to access.
The indices can be either an integer expression or a range in the form
Lower..Upper where Lower and Upper are integer expressions. The
expressions are evaluated and the corresponding components (or the
components in the range specified) accessed.

If Term is a string, Subscript must be a list of the form [Index], and
Elem is obtained via string_code(Index, Term, Elem).

If Term is an external data handle, Subscript must be a list of the form
[Index], and Elem is obtained via xget(Term, Index, Elem).

The main use for this predicate is to provide array syntax in arithmetic
expressions. Consider the arithmetic expression

X is Mat[I,J] + 1

which the ECLiPSe parser parses as
X is subscript(Mat,[I,J]) + 1

and the arithmetic evaluation mechanism turns that into
subscript(Mat,[I,J],T), +(T,1,X)

If Subscript contains a range of the form From..To, then
this results in the retrieval of a list of elements with
the indices from From to To.
NOTE: subscript/3 implements a superset of the functionality of arg/3.
So arg/3 is likely to be faster than subscript/3 in cases where they
implement the same functionality, i.e. structure argument lookup or
one/multi-dimensional array element lookup.

### Modes and Determinism

- subscript(+, ++, -) is det

### Modules

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

*(4) instantiation fault *
- Term or Subscript are not sufficiently instantiated.
*(5) type error *
- Term not compound or Subscript not integer list.
*(6) out of range *
- Subscript out of range.

## Examples

[eclipse 6]: subscript(s(t(a,b),t(c,d),t(e,f)), [3,2], X).
X = f
yes.
[eclipse 11]: Vector = v(12,13,14,15), X is Vector[3].
X = 14
Vector = v(12, 13, 14, 15)
yes.
[eclipse 12]: Matrix = m(r(1,2,3),r(4,5,6),r(7,8,9)), X is Matrix[2,1].
X = 4
Matrix = m(r(1, 2, 3), r(4, 5, 6), r(7, 8, 9))
yes.
[eclipse 18]: Matrix = m(r(1,2,3),r(4,5,6),r(7,8,9)), Row is Matrix[2].
Row = r(4, 5, 6)
Matrix = m(r(1, 2, 3), r(4, 5, 6), r(7, 8, 9))
yes.
[eclipse 5]: Matrix = m(r(1,2,3),r(4,5,6),r(7,8,9)),
subscript(Matrix, [2,1..3], Row),
subscript(Matrix, [1..3,2], Col),
subscript(Matrix, [2..3,1..2], Sub).
Matrix = m(r(1, 2, 3), r(4, 5, 6), r(7, 8, 9))
Row = [4, 5, 6]
Col = [2, 5, 8]
Sub = [[4, 5], [7, 8]]
yes.

## See Also

arg / 3, dim / 2, string_code / 3, xget / 3, array_flat / 3