#include "tensorstore/index_space/index_transform.h"
template <DimensionIndex InputRank,
          DimensionIndex OutputRank,
          ContainerKind CKind>
class tensorstore::IndexTransform;

Transform from an input index space to an output index space.

Template Parameters:
DimensionIndex InputRank

Compile-time rank of input space, or dynamic_rank (the default) to indicate a run-time rank.

DimensionIndex OutputRank

Compile-time rank of output space, or dynamic_rank (the default) to indicate a run-time rank.

ContainerKind CKind

If equal to container (the default), this object owns a shared reference to the (immutable) transform. If equal to view, this object represents an unowned view of a transform. Copy constructing a container index transform from an existing container or view index transform only incurs the cost of an atomic reference count increment.

Data members

constexpr const DimensionIndex static_rank = InputRank;
constexpr const DimensionIndex static_input_rank = InputRank;

Static input rank, or dynamic_rank if the input rank is determined at run time.

constexpr const DimensionIndex static_output_rank = OutputRank;

Static output rank, or dynamic_rank if the input rank is determined at run time.

constexpr const ContainerKind container_kind = CKind;

Specifies whether this owns an index transform (container), or merely holds an unowned reference to one (view).

Constructors

constexpr IndexTransform();

Constructs a null index transform.

IndexTransform(const IndexTransform<SourceInputRank,
                                    SourceOutputRank,
                                    SourceCKind>& other);
IndexTransform(
    IndexTransform<SourceInputRank, SourceOutputRank, SourceCKind>&&
        other);

Construct from a compatible existing index transform.

explicit IndexTransform(unchecked_t,
                        const IndexTransform<SourceInputRank,
                                             SourceOutputRank,
                                             SourceCKind>& other);
explicit IndexTransform(
    unchecked_t,
    IndexTransform<SourceInputRank, SourceOutputRank, SourceCKind>&&
        other);

Unchecked conversion from a potentially compatible existing index transform.

Methods

IndexTransform&
operator=(const IndexTransform<SourceInputRank,
                               SourceOutputRank,
                               SourceCKind>& other) noexcept;
IndexTransform& operator=(
    IndexTransform<SourceInputRank, SourceOutputRank, SourceCKind>&&
        other) noexcept;

Assign from a compatible existing index transform.

absl::Status
TransformIndices(span<const Index, InputRank> input_indices,
                 span<Index, OutputRank> output_indices) const;

Computes the output_indices corresponding to the given input_indices.

IndexTransform<InputRank, OutputRank> Transpose() const&;
IndexTransform<InputRank, OutputRank> Transpose() &&;

Returns a new transform with the input dimension order reversed.

IndexTransform<InputRank, OutputRank>
Transpose(span<const DimensionIndex, InputRank> permutation) const&;
IndexTransform<InputRank, OutputRank>
Transpose(span<const DimensionIndex, InputRank> permutation) &&;

Returns a new transform with the input dimension order permuted.

IndexTransform<InputRank, OutputRank> TransposeOutput() const&;
IndexTransform<InputRank, OutputRank> TransposeOutput() &&;

Returns a new transform with the output dimension order reversed.

IndexTransform<InputRank, OutputRank> TransposeOutput(
    span<const DimensionIndex, OutputRank> permutation) const&;
IndexTransform<InputRank, OutputRank> TransposeOutput(
    span<const DimensionIndex, OutputRank> permutation) &&;

Returns a new transform with the output dimension order permuted.

Result<IndexTransform<InputRank, NewOutputRank>> operator()(
    const IndexTransform<OutputRank, NewOutputRank, OtherCKind>&
        other) const;

Returns ComposeTransforms(other, *this).

auto operator()(Target&& target) const;

Enables IndexTransform to be be applied to TransformedArray, TensorStore, and other types that support ApplyIndexTransform.

Accessors

explicit constexpr operator bool() const;
constexpr bool valid() const;

Returns true if this is not a null transform.

StaticOrDynamicRank<InputRank> input_rank() const;

Returns the input rank.

StaticOrDynamicRank<OutputRank> output_rank() const;

Returns the output rank.

span<const Index, InputRank> input_origin() const;

Returns the array of inclusive lower bounds for the input dimensions.

span<const Index, InputRank> input_shape() const;

Returns the array of extents for the input dimensions.

span<const std::string, InputRank> input_labels() const;

Returns the array of labels for the input dimensions.

IndexDomainView<InputRank> input_domain() const;
IndexDomainView<InputRank> domain() const&;
IndexDomain<InputRank, CKind> domain() &&;

Returns the input domain.

DimensionSet implicit_lower_bounds() const;

Returns a bit-vector indicating for each input dimension whether the lower bound is implicit rather than explicit.

DimensionSet implicit_upper_bounds() const;

Returns a bit-vector indicating for each input dimension whether the upper bound is implicit.

OutputIndexMapRange<InputRank, OutputRank> output_index_maps() const;

Returns a range representing the output index maps.

OutputIndexMapRef<InputRank>
output_index_map(DimensionIndex output_dim) const;

Returns the output index map for a given output_dim.

Friend functions

friend bool
operator==(const IndexTransform& a,
           const IndexTransform<InputRankB, OutputRankB, CKindB>& b);
friend bool
operator!=(const IndexTransform& a,
           const IndexTransform<InputRankB, OutputRankB, CKindB>& b);

Checks if two index transforms have identical representations.

friend PipelineResultType<IndexTransform&&, Func>
operator|(IndexTransform transform, Func&& func);

“Pipeline” operator.

friend std::ostream&
operator<<(std::ostream& os, const IndexTransform& transform);

Prints a string representation of an index space transform.

friend Result<
    IndexTransform<RankConstraint::And(InputRank, OtherRank),
                   OutputRank>>
ApplyIndexTransform(BoxView<OtherRank> box, IndexTransform transform);

Restricts the domain of an index transform by a box of the same rank.

class tensorstore::OutputIndexMapRef<InputRank>;

Represents a const unowned view of an output index map for an index transform, which specifies the how the index for a given output dimension is computed from the input indices.

class tensorstore::OutputIndexMapRange<InputRank, OutputRank, CKind>;

Represents a const range view of the output index maps for an index transform.

using tensorstore::IndexTransformView<InputRank, OutputRank> =
    IndexTransform<InputRank, OutputRank, view>;

Unowned view of an index transform.

constexpr bool tensorstore::IsIndexTransform<T>;

Bool-valued metafunction that evaluates to true if T is an instance of IndexTransform.

Result<IndexTransform<RankA, RankC>> tensorstore::ComposeTransforms(
    const IndexTransform<RankB, RankC, CKindA>& b_to_c,
    const IndexTransform<RankA, RankB, CKindB>& a_to_b);

Composes two index transforms.

Result<IndexTransform<>>
tensorstore::ComposeOptionalTransforms(IndexTransform<> b_to_c,
                                       IndexTransform<> a_to_b);

Composes two index transforms, which may be null.

BoxView<InputRank> tensorstore::GetBoxDomainOf(
    const IndexTransform<InputRank, OutputRank, CKind>& transform);

Implements the HasBoxDomain concept for IndexTransform.

Result<IndexTransform<Rank, Rank>> tensorstore::InverseTransform(
    const IndexTransform<Rank, Rank, CKind>& transform);

Returns the inverse transform if one exists.

absl::Status tensorstore::ValidateIndexArrayBounds(
    IndexInterval bounds,
    ArrayView<const Index, dynamic_rank, offset_origin> index_array);

Checks that bounds.Contains(index) for all values of index in index_array.

Result<bool>
tensorstore::GetOutputRange(IndexTransformView<> transform,
                            MutableBoxView<> output_range);

Computes a hyperrectangle bound on the output range of transform.

absl::Status tensorstore::PropagateInputDomainResizeToOutput(
    IndexTransformView<> transform,
    span<const Index> requested_input_inclusive_min,
    span<const Index> requested_input_exclusive_max,
    bool can_resize_tied_bounds,
    span<Index> output_inclusive_min_constraint,
    span<Index> output_exclusive_max_constraint,
    span<Index> new_output_inclusive_min,
    span<Index> new_output_exclusive_max,
    bool* is_noop);

Propagates a resize request on the input domain to the output space.

IndexTransform<InputRank, OutputRank>
tensorstore::WithImplicitDimensions(
    IndexTransform<InputRank, OutputRank, CKind> transform,
    DimensionSet implicit_lower_bounds,
    DimensionSet implicit_upper_bounds);

Returns a copy of transform with implicit_lower_bounds and implicit_upper_bounds set to the specified values.

Identity transform

IndexTransform<Rank, Rank> tensorstore::IdentityTransform(
    StaticOrDynamicRank<Rank> rank = StaticRank<Rank>());
IndexTransform<> tensorstore::IdentityTransform(DimensionIndex rank);

Returns an identity transform of the specified rank.

IndexTransform<BoxType::static_rank, BoxType::static_rank>
tensorstore::IdentityTransform(const BoxType& domain);

Returns an identity transform over the specified box.

IndexTransform<Rank, Rank> tensorstore::IdentityTransform(
    const std::string_view (&labels)[Rank]);
auto tensorstore::IdentityTransform(const Labels& labels);

Returns an identity transform with the specified dimension labels.

IndexTransform<InputRank, InputRank>
tensorstore::IdentityTransformLike(
    const IndexTransform<InputRank, OutputRank, CKind>& transform);

Returns an identity transform over the input domain of an existing transform.

IndexTransform<Rank, Rank> tensorstore::IdentityTransform(
    const IndexDomain<Rank, CKind>& domain);

Returns an identity transform over the specified index domain.

IndexTransform<Array::static_rank, Array::static_rank>
tensorstore::IdentityTransformLike(const Array& array);

Returns an identity transform over the input domain of an array.

auto tensorstore::IdentityTransform(const Shape& shape);
IndexTransform<Rank, Rank>
tensorstore::IdentityTransform(const Index (&shape)[Rank]);

Returns an identity transform with an origin of 0 and the specified shape.

Bounds propagation

absl::Status tensorstore::PropagateBounds(
    std::type_identity_t<BoxView<OutputRank>> b_domain,
    DimensionSet b_implicit_lower_bounds,
    DimensionSet b_implicit_upper_bounds,
    const IndexTransform<InputRank, OutputRank, CKind> a_to_b,
    std::type_identity_t<MutableBoxView<InputRank>> a_domain,
    DimensionSet& a_implicit_lower_bounds,
    DimensionSet& a_implicit_upper_bounds);
absl::Status tensorstore::PropagateBounds(
    std::type_identity_t<BoxView<OutputRank>> b_domain,
    DimensionSet b_implicit_lower_bounds,
    DimensionSet b_implicit_upper_bounds,
    const IndexTransform<InputRank, OutputRank, CKind> a_to_b,
    std::type_identity_t<MutableBoxView<InputRank>> a_domain);

Propagates bounds on an output index space b back to each input dimension input_dim of the input index space a as follows:

absl::Status tensorstore::PropagateExplicitBounds(
    std::type_identity_t<BoxView<OutputRank>> b_domain,
    const IndexTransform<InputRank, OutputRank, CKind> a_to_b,
    std::type_identity_t<MutableBoxView<InputRank>> a_domain);

Equivalent to PropagateBounds, except that b_implicit_lower_bounds and b_implicit_upper_bounds are assumed to be all false.

Result<IndexTransform<InputRank, OutputRank>>
tensorstore::PropagateBoundsToTransform(
    std::type_identity_t<BoxView<OutputRank>> b_domain,
    DimensionSet b_implicit_lower_bounds,
    DimensionSet b_implicit_upper_bounds,
    IndexTransform<InputRank, OutputRank, CKind> a_to_b);
Result<IndexTransform<InputRank, OutputRank>>
tensorstore::PropagateBoundsToTransform(
    std::type_identity_t<IndexDomainView<OutputRank>> b_domain,
    IndexTransform<InputRank, OutputRank, CKind> a_to_b);

Returns a new transform that represents the same mapping as a_to_b but may have a reduced input domain:

Result<IndexTransform<InputRank, OutputRank>>
tensorstore::PropagateExplicitBoundsToTransform(
    std::type_identity_t<BoxView<OutputRank>> b_domain,
    IndexTransform<InputRank, OutputRank, CKind> a_to_b);

Same as PropagateBoundsToTransform, except that PropagateBoundsToTransform::b_implicit_lower_bounds and PropagateBoundsToTransform::b_implicit_upper_bounds assumed to be all false, with the effect that IndexTransform::implicit_lower_bounds and IndexTransform::implicit_upper_bounds of the returned transform are all false.