#include "tensorstore/index_space/index_transform_builder.h"
template <DimensionIndex InputRank = dynamic_rank,
          DimensionIndex OutputRank = dynamic_rank>
class tensorstore::IndexTransformBuilder;

Builder class for creating an IndexTransform by explicitly specifying the input space and the output index maps.

This is intended as a low-level interface for creating an IndexTransform. In most cases, using a dimension expression (see dim_expression.h) is likely to be much more convenient.

The input and output ranks may be specified either at compile time, as template arguments, or at run time, as constructor arguments.

To use this class, call (a subset of) the setter methods input_origin, input_shape, input_exclusive_max, input_inclusive_max implicit_lower_bounds, implicit_upper_bounds, input_labels, output_map, output_constant, output_single_input_dimension, output_index_array to specify the input space and the output index maps. For convenience, all of these setter methods return a reference to *this and can be chained.

The input_origin, input_shape, input_inclusive_max, input_exclusive_max, and input_labels methods can be called with vectors specifying values for all of the input dimensions (and override the values specified by any prior call). The input_shape, input_exclusive_max, and input_inclusive_max methods all set the upper bound of the input domain, and override any previous value. In most cases each of these methods should be called at most once, and only one of input_shape, input_inclusive_max, and input_exclusive_max should be called.

The output_map, output_constant, output_single_input_dimension, and output_index_array methods specify the output index map for just the single output dimension specified by the first argument, output_dim (and override the output index map specified by any prior call to a output_* method with the same output_dim). In most cases, at most one of the output_* methods should be called for each output dimension.

Default values:

After calling the setter methods, call Finalize() to obtain a Result<IndexTransform<InputRank, OutputRank>>. Finalize must be called at most once, and either returns a valid index transform, or an error if an invalid input domain or output index map was specified.

Examples

IndexTransform<3, 2> t = IndexTransformBuilder<3, 2>()
    .input_origin({1, 2, 3})
    .input_inclusive_max({5, 7, 9})
    .output_single_input_dimension(0, 1, 2, 0)
    .output_constant(1, 5)
    .Finalize()
    .value();

Creates an index transform from an rank-3 input domain [1, 5], [2, 7], [3, 9] to a rank 2 output space, where output[0] = 1 + 2 * input[0] and output[1] = 5. Both the input and output ranks are specified at compile time.

IndexTransform<> t = IndexTransformBuilder<>(3, 2)
    .input_origin({1, 2, 3})
    .input_exclusive_max({6, 8, 10})
    .output_single_input_dimension(0, 1, 2, 0)
    .output_constant(1, 5)
    .Finalize()
    .value();

Same as previous example, except that both the input and output ranks are specified at run time, and the upper bound of the input domain is specified using the input_exclusive_max method.

IndexTransform<3, 2> t = IndexTransformBuilder<3, 2>()
    .input_origin({1, 2, 3})
    .input_shape({5, 6, 3})
    .input_labels({"a", "b", "x"})
    .output_single_input_dimension(0, 1, 2, 0)
    .output_index_array(1, 0, 1, MakeArray<Index>({{{5, 10, 13}}}))
    .Finalize()
    .value();

Creates an index transform from a rank-3 input domain "a": [1, 5], "b": [2, 7], "x": [3, 5] to a rank 2 output space, where output[0] = 1 + 2 * input[0] and output[1] = {5, 10, 13}[input[2] - 3]. Both the input and output ranks are specified at compile time.

Note

Invalid arguments specified to IndexTransformBuilder are handled in two different ways. Calling input_origin, input_shape, input_inclusive_max, input_exclusive_max, or input_labels with a sequence of length not equal to input_rank(), and calling output_* with an invalid output_dim are fatal errors. Specifying an invalid input domain or invalid output index map is not a fatal error; the Finalize method will simply return an error Result if the invalid input domain or output index map has not been overridden with a valid one prior to the call to Finalize.

Constructors

IndexTransformBuilder(std::nullptr_t);

Constructs an invalid IndexTransformBuilder.

IndexTransformBuilder(DimensionIndex input_rank,
                      
DimensionIndex output_rank);
IndexTransformBuilder(
    
std::integral_constant<DimensionIndex, IRank> input_rank = {},
    
std::integral_constant<DimensionIndex, ORank> output_rank = {});
IndexTransformBuilder(
    
DimensionIndex input_rank,
    
std::integral_constant<DimensionIndex, ORank> output_rank = {});

Constructs a valid IndexTransformBuilder with the specified input and output ranks.

Methods

bool valid() const;

Returns true if this is a valid, initialized builder.

StaticOrDynamicRank<InputRank> input_rank() const;

Returns the input rank. :pre: valid() == true

StaticOrDynamicRank<OutputRank> output_rank() const;

Returns the output rank. :pre: valid() == true

span<Index, InputRank> input_origin();

Returns the mutable input_origin vector, and marks the input_origin as having been set.

IndexTransformBuilder& input_origin(const Indices& indices);
IndexTransformBuilder& input_origin(const Index (&indices)[N]);

Sets the input_origin vector to the specified value.

span<Index, InputRank> input_shape();

Returns the mutable input_shape vector, and marks the upper bound as having been set.

IndexTransformBuilder& input_shape(const Indices& indices);
IndexTransformBuilder& input_shape(const Index (&indices)[N]);

Sets the input_shape vector to the specified value. Specify a value of kInfSize to indicate an unbounded (infinite) upper bound.

span<Index, InputRank> input_exclusive_max();

Returns the mutable input_exclusive_max vector, and marks the upper bound as having been set.

IndexTransformBuilder& input_exclusive_max(const Indices& indices);
IndexTransformBuilder& input_exclusive_max(const Index (&indices)[N]);

Specifies the exclusive upper bounds of the input domain. Specify a value of kInfIndex + 1 to indicate an unbounded (infinite) upper bound.

span<Index, InputRank> input_inclusive_max();

Returns the mutable input_inclusive_max vector, and marks the upper bound as having been set.

IndexTransformBuilder& input_inclusive_max(const Indices& indices);
IndexTransformBuilder& input_inclusive_max(const Index (&indices)[N]);

Specifies the inclusive upper bounds of the input domain. Specify a value of kInfIndex to indicate an unbounded (infinite) upper bound.

IndexTransformBuilder& input_bounds(const BoxLike& box);

Specifies the lower and upper bounds of the input domain.

MutableBoxView<InputRank> input_bounds();

Returns the mutable input_bounds box, and marks the lower and upper bounds as having been set.

IndexTransformBuilder&
input_domain(IndexDomainView<InputRank> domain);

Specifies the input domain.

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

Returns the mutable input_labels vector.

IndexTransformBuilder& input_labels(const Labels& labels);
IndexTransformBuilder&
input_labels(const std::string_view (&labels)[N]);

Sets the input_labels vector to the specified value.

DimensionSet& implicit_lower_bounds();

Returns the mutable implicit_lower_bounds bit vector, and marks it as having been set.

IndexTransformBuilder& implicit_lower_bounds(DimensionSet x);
IndexTransformBuilder& implicit_lower_bounds(const bool (&x)[N]);

Sets the implicit_lower_bounds bit-vector to the specified value.

DimensionSet& implicit_upper_bounds();

Returns the mutable implicit_upper_bounds bit vector, and marks it as having been set.

IndexTransformBuilder& implicit_upper_bounds(DimensionSet x);
IndexTransformBuilder& implicit_upper_bounds(const bool (&x)[N]);

Sets the implicit_upper_bounds bit-vector to the specified value.

IndexTransformBuilder&
output_map(DimensionIndex output_dim,
           
OutputIndexMapRef<OtherInputRank> map);

Sets the output index map for output dimension output_dim to a copy of map from an existing index transform.

IndexTransformBuilder&
output_constant(DimensionIndex output_dim, Index offset);

Sets the output index map for output dimension output_dim to a OutputIndexMethod::constant map with the specified offset.

IndexTransformBuilder&
output_single_input_dimension(DimensionIndex output_dim,
                              
Index offset,
                              
Index stride,
                              
DimensionIndex input_dim);
IndexTransformBuilder&
output_single_input_dimension(DimensionIndex output_dim,
                              
DimensionIndex input_dim);

Sets the output index map for output dimension output_dim to a OutputIndexMethod::single_input_dimension map with the specified offset, stride, and input_dim.

IndexTransformBuilder& output_index_array(
    
DimensionIndex output_dim,
    
Index offset,
    
Index stride,
    
const SharedArrayView<const Index, dynamic_rank, offset_origin>&
        index_array
,
    
Result<IndexInterval> index_range = IndexInterval());

Sets the output index map for output dimension output_dim to an OutputIndexMethod::array map with the specified offset, stride, index_array, and optional index_range.

IndexTransformBuilder& output_identity_transform();

Sets the first min(input_rank(), output_rank()) output dimensions to identity map to input dimensions.

IndexTransformBuilder& output_maps(
    
OutputIndexMapRange<OtherInputRank, OtherOutputRank> output_maps);

Copies the first min(output_rank(), output_maps.size()) output maps from output_maps.

Result<IndexTransform<InputRank, OutputRank>> Finalize();

Validates and returns the specified index transform.