
subscript(+Term, ++Subscript, -Elem)

   Accesses the subterm Elem of Term, as specified by Subscript

Arguments
   Term                Compound term (possibly nested), string, or external data handle.
   Subscript           A list of integers, ranges or integer arithmetic expressions.
   Elem                Prolog term.

Type
   Term Manipulation

Description
Extracting sub-terms or array elements
   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. In the basic case, the indices are expressions
   that evaluate to positive integers.  These integers are then used to
   extract the corresponding sub-term of Term, e.g. an index list of
   [3,2] would extract the 2nd argument of the 3rd argument of Term.

   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.

   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)

   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.

Extracting sub-arrays
    If Subscript contains a range expression of the form From..To,
    then this results in the retrieval of the sub-array of elements with the
    indices from From to To.  A sub-array is always a term with functor []/N.

    The special shorthand * is equivalent to 1..Arity and
    stands for all elements in the corresponding dimension.  For instance,
    Mat[*,3] extracts the whole 3rd column of a matrix Mat.

    If Subscript contains multiple such range expressions, a nested sub-array
    is retrieved.

Operation on strings and handles
   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).



Modes and Determinism
   subscript(+, ++, -) is det

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

Exceptions
     4 --- Term or Subscript are not sufficiently instantiated.
     5 --- Term not compound or Subscript not integer list.
     6 --- Subscript out of range.

Examples
   
    ?- subscript(s(t(a,b),t(c,d),t(e,f)), [3,2], X).
    X = f
    yes.

    ?- Vector = v(11,12,13,14,15), X is Vector[4].
    X = 14
    yes.

    ?- Matrix = m(r(1,2,3),r(4,5,6),r(7,8,9)), X is Matrix[2,1].
    X = 4
    yes.

    ?- Matrix = m(r(1,2,3),r(4,5,6),r(7,8,9)), Row is Matrix[2].
    Row = r(4, 5, 6)
    yes.

    ?- Vector = [](11,12,13,14,15), X is Vector[2..4], Y is Vector[3..3].
    X = [](12, 13, 14)
    Y = [](13)
    yes.

    ?- Matrix = []([](1,2,3), [](4,5,6), [](7,8,9)), 
	 subscript(Matrix, [2,1..3], Row2),
	 subscript(Matrix, [1..3,2], Col2),
	 subscript(Matrix, [2..3,1..2], Sub).
    Row2 = [](4, 5, 6)
    Col2 = [](2, 5, 8)
    Sub = []([](4, 5), [](7, 8))
    yes.

    ?- Matrix = []([](1,2,3), [](4,5,6), [](7,8,9)), 
	 subscript(Matrix, [2,*], Row2),
	 subscript(Matrix, [*,2], Col2).
    Row2 = [](4, 5, 6)
    Col2 = [](2, 5, 8)
    yes.


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