#include "tensorstore/index_space/dim_expression.h"
template <typename... Op>
class tensorstore::DimExpression;

A DimExpression represents an ordered “selection” of dimensions of an index space and a sequence of “operations” to apply to those dimensions.

Logically, each operation is a function that maps an index transform and an ordered subset of dimension indices to a new index transform and a new ordered subset of dimension indices. The returned dimension indices correspond to the dimensions created or modified by the operation, excluding any dimensions that were deleted.

When a DimExpression is applied to an index transform, the dimensions in the “selection”, which may have been specified by label or in other indirect ways, are resolved to an actual ordered subset of dimension indices, and passed along with the index transform as a parameter to the first operation in the sequence. Subsequent operations, if any, are called using the modified index transform and modified dimension subset returned by the prior operation in the sequence.

A DimExpression with an empty sequence of operations is created by calling Dims, AllDims, or DimRange. A new DimExpression that extends the sequence of operations of an existing DimExpression is created by calling member functions, e.g. IndexSlice, IndexArraySlice, ClosedInterval, TranslateBy, TranslateTo, MoveTo, Label, Diagonal, etc.

Warning

A DimExpression may hold references to temporary values, in which case it must not be used after evaluation of the complete expression in which those temporaries were created. For example:

Dims(std::string("x"), std::string("y")).IndexSlice({1, 2})

refers to data owned by two temporary std::string values and a temporary array containing {1, 2}, and it is therefore unsafe to store the resulting DimExpression object in a variable that outlives the complete expression in which it was created, as in the following unsafe code:

auto do_not_use =
  Dims(std::string("x"), std::string("y")).IndexSlice({1, 2});

The behavior of some operations is specified in terms of an interleave function. Given a list a of length n, a list indices of k unique indices in the range [0, n + k), and a list b of length k, interleave(a, indices, b) is defined to be the list c of length length(a) + length(b) with c[j] = b[i] if j = indices[i], and c[j] = a[j - Count(indices < j)] if j not in indices.

Methods

auto TranslateBy(const Offsets& offsets) const;

Translates (shifts) the domains of the selected input dimensions by the specified offsets vector; the output range remains the same.

auto TranslateBackwardBy(const Offsets& offsets) const;

Translates (shifts) the domains of the selected input dimensions backwards by the specified offsets vector; the output range remains the same.

auto TranslateTo(const Origins& origins) const;

Translates the domain of the selected input dimensions to the specified origin vector without affecting the output range.

auto IndexSlice(const Indices& indices) const;

Extracts a single-index slice of the selected dimensions using the specified index vector.

auto BoxSlice(const BoxType& box) const;

Extracts a box from the selected dimensions.

auto TranslateBoxSlice(const BoxType& box) const;

Extracts a box from the selected dimensions, and translates its origin to 0.

auto ClosedInterval(const Start& start,
                    const Stop& stop,
                    const Strides& strides = 1) const;

Extracts a closed interval from the selected dimensions with optional striding.

auto HalfOpenInterval(const Start& start,
                      const Stop& stop,
                      const Strides& strides = 1) const;

Extracts a half-open interval from the selected dimensions with optional striding.

auto SizedInterval(const Start& start,
                   const Size& size,
                   const Strides& strides = 1) const;

Extracts a sized interval from the selected dimensions with optional striding.

auto TranslateClosedInterval(const Start& start,
                             const Stop& stop,
                             const Strides& strides = 1) const;

Equivalent to ClosedInterval(start, stop, strides).TranslateTo(0).

auto TranslateHalfOpenInterval(const Start& start,
                               const Stop& stop,
                               const Strides& strides = 1) const;

Equivalent to HalfOpenInterval(start, stop, strides).TranslateTo(0).

auto TranslateSizedInterval(const Start& start,
                            const Size& size,
                            const Strides& strides = 1) const;

Equivalent to SizedInterval(start, size, strides).TranslateTo(0).

auto IndexArraySlice(const IndexArray&... index_arrays) const;
auto IndexArraySlice(
    span<const SharedArrayView<const Index>> index_arrays) const;

Jointly slices the selected dimensions using index arrays.

auto IndexVectorArraySlice(
    const IndexVectorArray& index_vector_array,
    DimensionIndex vector_dimension = -1) const;

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

auto OuterIndexArraySlice(const IndexArray&... index_arrays) const;
auto OuterIndexArraySlice(
    span<const SharedArrayView<const Index>> index_arrays) const;

Independently slices the selected dimensions using index arrays.

auto Label(const Labels& labels) const;
auto Label(const L&... labels) const;

Sets (or changes) the labels of the selected dimensions.

auto MoveTo(DimensionIndex target) const;

Transposes the input dimensions such that the selected dimensions are consecutive starting or ending at the specified target position.

auto MoveToFront() const;

Equivalent to MoveTo(0).

auto MoveToBack() const;

Equivalent to MoveTo(-1).

auto Diagonal() const;

Extracts the diagonal of the selected dimensions.

auto AddNew() const;

Adds new inert input dimensions that have no effect on the output indices.

auto Transpose() const;

Transposes the input dimensions such that the selected dimensions are consecutive.

auto Transpose(const TargetDimensions& target_dimensions) const;

Transposes the input dimensions such that the selected dimensions have the specified indices. Dimensions not in the selection retain their relative order and fill in the dimension indices not in target_dimensions.

auto MarkBoundsExplicit(bool lower = true, bool upper = true) const;

Marks the lower and/or upper bounds of the selected dimensions as explicit.

auto UnsafeMarkBoundsImplicit(bool lower = true,
                              bool upper = true) const;

Marks the lower and/or upper bounds of the selected dimensions as implicit.

auto Stride(const Strides& strides) const;

Strides the domains of the selected input dimensions by the specified strides vector.

auto operator()(
    IndexTransform<InputRank, OutputRank, CKind> transform,
    DimensionIndexBuffer* selection_output =
        &internal::GetLValue(DimensionIndexBuffer())) const;

Applies this DimExpression to the specified index transform.

auto operator()(
    IndexDomain<Rank, CKind> domain,
    DimensionIndexBuffer* selection_output =
        &internal::GetLValue(DimensionIndexBuffer())) const;

Applies this DimExpression to the specified index domain.

auto operator()(Transformable&& transformable) const;

Applies this DimExpression to an object with an associated index space that supports ApplyIndexTransform.

absl::Status Resolve(const IndexDomain<Rank, CKind>& domain,
                     DimensionIndexBuffer* selection_output) const;

Resolves a dimension selection to dimension indices.

type tensorstore::DimensionIndexBuffer;

Specifies a sequence of DimensionIndex values.

class tensorstore::DimensionIdentifier;

Specifies a dimension of an index space by index or by label.

struct tensorstore::DimRangeSpec;

Represents a range of dimension indices.

using tensorstore::DynamicDimSpec =
    std::variant<DimensionIndex, std::string, DimRangeSpec>;

Specifies a dimension by index or label or a range of dimensions.

struct tensorstore::IsIndexVectorOrScalar<T>;

A type T satisfies the IsIndexVectorOrScalar concept if it is either:

auto tensorstore::Dims(const Dimensions& dimensions);
auto tensorstore::Dims(const DimensionId&... dimensions);

Starts a DimExpression with the specified dimensions selected (and no operations).

auto tensorstore::DimRange(
    DimensionIndex inclusive_start,
    std::optional<DimensionIndex> exclusive_stop = std::nullopt,
    const DimensionIndex step = 1);

Starts a DimExpression with a range of dimensions.

auto tensorstore::DynamicDims(
    const DynamicDimSpec (&dimensions)[Rank]);

Starts a DimExpression with a variable number of dimensions.

auto tensorstore::AllDims();

Starts a DimExpression with all dimensions selected (and no operations).