## `indexval` -- indexed access to arrays and tables without evaluation

#### Introduction

`indexval(`x, i`)` and `indexval(`x, i1, i2, ...`)` yields the entry of `x` corresponding to the indices `i` and `i1, i2, ...`, respectively, without evaluation.

#### Call(s)

`indexval(x, i)`
`indexval(x, i1, i2, ...)`

#### Parameters

`x` | - | essentially a table or an array, however, also allowed: a list, a finite set, an expression sequence, or a character string
`i, i1, i2, ...` | - | indices. For most ``containers'' `x`, indices must be integers. If `x` is a table, arbitrary MuPAD objects can be used as indices.

#### Returns

the entry of `x` corresponding to the index. When `x` is a table or an array, the returned entry is not evaluated again.

### Overloadable:

`x`

#### Related Functions

`:=`, `_assign`, `_index`, `array`, `contains`, `DOM_ARRAY`, `DOM_LIST`, `DOM_SET`, `DOM_STRING`, `DOM_TABLE`, `op`, `table`

#### Details

- The three calls `indexval(`x, i`)`, `_index(x, i)`, and `x[i]` all return the element of index `i` in the array or table `x`. In contrast to `_index` and the equivalent index operator `[ ]`, however, `indexval` returns the corresponding entry without evaluating it. This is sometimes desirable for efficiency reasons.

- The arguments `i` or i1, i2... must be a valid indices of `x`, otherwise an error message is printed (see example 3). When several indices i1, i2... are given, they are interpreted as a higher-dimensional index (see example 4).

- The first argument `x` may also be a list, a set, a string, or an expression sequence. However, in these cases `indexval` behaves exactly like `_index` and the index operator `[ ]`: it returns the evaluation of the corresponding element. In particular, `indexval` does not flatten its first argument.

- For all other basic domains, `indexval` behaves exactly like `_index`: either an error occurs, or a symbolic `indexval` call is returned (see example 3).

- `indexval` does not work with matrices in the current version. However, the function `_index` return an entry of a matrix unevaluated.

- `indexval` is a function of the system kernel.

#### Example 1

`indexval` works with tables:

    >> T := table("1" = a, Be = b, `+` = a + b):
       a := 1: b := 2:
       indexval(T, Be), indexval(T, "1"), indexval(T, `+`)

                                    b, a, a + b

In contrast `_index` evaluates returned entries:

    >> _index(T, Be), _index(T, "1"), _index(T, `+`)

                                      2, 1, 3

The next input line has the same meaning as the last:

    >> T[Be], T["1"], T[`+`]

                                      2, 1, 3

`indexval` works with arrays, too. The behavior is the same, but the indices must be positive integers:

    >> delete a, b:
       A := array(1..2, 1..2, [[a, a + b], [a - b, b]]):
       a := 1: b := 2:
       indexval(A, 2, 2), indexval(A, 1, 1), indexval(A, 1, 2)

                                    b, a, a + b

    >> _index(A, 2, 2), _index(A, 1, 1), _index(A, 1, 2)

                                      2, 1, 3

    >> A[2, 2], A[1, 1], A[1, 2]

                                      2, 1, 3

    >> delete A, T, a, b:

#### Example 2

However, there is no difference between `indexval` and `_index` for all other valid objects, e.g., lists:

    >> delete a, b:
       L := [a, b, 2]:
       b := 5:
       L[2], _index(L, 2), indexval(L, 2), op(L, 2)

                                    5, 5, 5, 5

Similarly, there is no difference when the first argument is an expression sequence (which is not flattened by `indexval`):

    >> delete a, b: S := a, b, 2:
       b := 5:
       S[2], _index(S, 2), indexval(S, 2), op(S, 2)

                                    5, 5, 5, 5

    >> delete L, S, a, b:

#### Example 3

If the second argument is not a valid index, an error occurs:

    >> A := array(1..2, 1..2, [[a, b], [a, b]]):
       indexval(A, 3)

          Error: Index dimension mismatch [array]

    >> indexval(A, 1, 0)

          Error: Illegal argument [array]

    >> indexval("12345", 5)

          Error: Invalid index [string]

However, the result of `indexval` can also be a symbolic `indexval` call:

    >> T := table(1 = a, 2 = b):
       indexval(T, 3)

                                  indexval(T, 3)

    >> delete X, i:
       indexval(X, i)

                                  indexval(X, i)

    >> delete A, T:

#### Example 4

For arrays the number of indices must be equal to the number of dimensions of the array:

    >> A := array(1..2, 1..2, [[a, b], [a, b]]):
       a := 1: b := 2:
       indexval(A, 1, 2), indexval(A, 2, 1)

                                       b, a

Otherwise an error occurs:

    >> indexval(A, 1)

          Error: Index dimension mismatch [array]

Tables can have expression sequences as indices, too:

    >> delete a, b:
       T := table((1, 1) = a, (2, 2) = b):
       a := 1: b := 2:
       indexval(T, 1, 1), indexval(T, 2, 2)

                                       a, b

    >> delete A, T, a, b:

#### Changes

- no changes

Do you have questions or comments?
Copyright © SciFace Software GmbH & Co. KG 2000