#include <jem/base/Slice.h>

The Array class provides overloaded subscript and function-call operators that can be used to select regular, rectangular sections of an array. These so-called slice operators return an Array object that points to a sub-set of the data block pointed to by the Array object on which the slice operators are invoked. Because the returned array shares its data with the original array, all modifications to the returned array will be visible in the original one.

The slice operators must be called with a set of Slice objects – created by calling the global slice() function – that specify which indices should be selected in a particular dimension. For instance, if a is a three-dimensional array, then the expression

a( ALL, slice(2,5), slice(BEGIN,3) )

selects all indices in the first dimension; the indices (2,3,4) in the second dimension; and the indices (0,1,2) in the third dimension. The result of this expresion is therefore a three-dimensional Array object with shape (a.size(0),3,3).

A slice operator can also be called with a mix of Slice objects and integers. In this case the operator will return an Array object that has a lower rank than the Array object on which the operator is invoked. For instance, the expression

a( ALL, 2, slice(BEGIN,3) )

selects all indices in the first dimension; the single index 2 in the second dimension; and the indices (0,1,2) in the third dimension. The result of this expression is therefore a two-dimensional array with shape (a.size(0),3).

Here are some more examples:

Array<int,3>  a ( 10, 10, 10 );
Array<int,2>  b (      5,  2 );
Array<int>    c (          5 );
Array<int>    d (          2 );
// init a, b, c, d ...
b = a( slice(ALL,2), slice(8,END), 5 );
c = b( ALL, 1 );
d = c[ slice(1,END,2) ];

After execution of this code fragment, the following expressions will be true for all valid indices (i,j):

b(i,j) == a(2 * i, 8 + j, 5 );
c[i]   == b(i,1);
d[i]   == c[1 + 2 * i];

Note that the function call operator is used for multi-dimensional arrays and that the subscript operator is used for one-dimensional arrays.

See also: slice(), Slice