#include "tensorstore/index_space/dim_expression.h"
template <typename IndexVectorArray>
auto tensorstore::DimExpression<Op...>::IndexVectorArraySlice(
    const IndexVectorArray& index_vector_array,
    DimensionIndex vector_dimension = -1) const;

Jointly slices the selected dimensions using the specified array of index vectors.

Given k selected_dimensions, an index_vector_array of rank n + 1 with index_vector_array.size(vector_dimension) == k, and an existing_transform with input rank m, the new index transform maps input vectors of size m + n - k to:

existing_transform(
    interleave(
        input[n:], selected_dimensions,
        {index_vector_array(
             interleave(input[:n], {vector_dimension}, i))
         for 0 <= i < k}))

The selected dimensions are removed from the new index space, and the dimensions of the index vector array, other than vector_dimension, are added as the first dimensions of the new index space with origins of 0 and empty labels. The new dimension selection corresponds to these added dimensions; they can be labeled and reordered relative to the existing dimensions by chaining the Label and MoveTo methods.

In cases where the indices are already arranged as an array of index vectors, this method provides a more convenient interface than the more general IndexArraySlice method (which requires separate arrays to be specified for each selected dimension).

For example:

Dims(0, 2).IndexVectorArraySlice(
    MakeArray<Index>({{{1, 7}, {2, 8}, {3, 9}},
                      {{4, 0}, {5, 1}, {6, 2}}}),
    -1)

is equivalent to:

Dims(0, 2).IndexArraySlice(MakeArray<Index>({{1, 2, 3}, {4, 5, 6}}),
                           MakeArray<Index>({{7, 8, 9}, {0, 1, 2}}))

and has the following effects:

Before

After

Dimension selection

{0, 2}

{0, 1}

Input domain

[0, 6], [2, 5], [0, 9]

[0, 1], [0, 2], [2, 5]

Labels

{"x", "y", "z"}

{"", "", "y"}

Equivalent input indices

{1, y, 7}

{0, 0, y}

Equivalent input indices

{2, y, 8}

{0, 1, y}

Equivalent input indices

{3, y, 9}

{0, 2, y}

Equivalent input indices

{6, y, 2}

{1, 2, y}

Equivalent input indices

{v(a,b,0), y, v(a,b,1)}

{a, b, y}

where y is any index in [2, 5], a is any index in [0, 1], b is any index in [0, 2], and:

v = MakeArray<Index>({{{1, 7}, {2, 8}, {3, 9}},
                      {{4, 0}, {5, 1}, {6, 2}}})
Requires:

IndexVectorArray satisfies IsIndexArray and has a non-zero rank.

Parameters:
const IndexVectorArray &index_vector_array

The array of index vectors used to index the selected dimension. The new transform may share ownership of the supplied index vector array. The array should not be modified after being passed to this function. The index values contained in the array may be bounds-checked lazily.

DimensionIndex vector_dimension = -1

Optional. The dimension of index_vector_array that corresponds to the vector of selected dimensions. May be a negative value, as supported by NormalizeDimensionIndex. If not specified, defaults to the last dimension. The other dimensions of index_vector_array correspond to new input dimensions.

Error absl::StatusCode::kInvalidArgument:

if index_vector_array.rank() is not equal to the number of selected dimensions.

Error absl::StatusCode::kInvalidArgument:

if vector_dimension is invalid.

Error absl::StatusCode::kInvalidArgument:

if the extent of the dimension of index_vector_array indicated by vector_dimension is not equal to the number of selected dimensions.

Error absl::StatusCode::kOutOfRange:

if an out-of-bounds index is detected.

Error absl::StatusCode::kInvalidArgument:

if integer overflow occurs when computing the resultant transform.