-
#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_maximplicit_lower_bounds,implicit_upper_bounds,input_labels,output_map,output_constant,output_single_input_dimension,output_index_arrayto specify the input space and the output index maps. For convenience, all of these setter methods return a reference to*thisand can be chained.The
input_origin,input_shape,input_inclusive_max,input_exclusive_max, andinput_labelsmethods can be called with vectors specifying values for all of the input dimensions (and override the values specified by any prior call). Theinput_shape,input_exclusive_max, andinput_inclusive_maxmethods 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 ofinput_shape,input_inclusive_max, andinput_exclusive_maxshould be called.The
output_map,output_constant,output_single_input_dimension, andoutput_index_arraymethods 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 aoutput_*method with the sameoutput_dim). In most cases, at most one of theoutput_*methods should be called for each output dimension.Default values:
If neither
input_originnorinput_shapeis called, the default origin is-kInfIndex, equivalent toinput_origin({-kInfIndex, ...}). Ifinput_shapeis called butinput_originis not called, the default origin is0.The default inclusive_max is
+kInfSize, equivalent toinput_inclusive_max({kInfIndex, ...}).The default label is
""for all input dimensions, equivalent toinput_labels({"", ...}).If neither
input_origin,input_shape, norimplicit_lower_boundsis called, the lower bounds are marked “implicit”, equivalent toimplicit_lower_bounds(1, ...). Otherwise, ifinput_originorinput_shapeis called butimplicit_lower_boundsis not called, the lower bounds are marked “explicit”, equivalent toimplicit_lower_bounds(0, ...). Refer to the documentation of theIndexTransformclass for details on the meaning of implicit vs. explicit.If none of
input_shape,input_inclusive_max,input_exclusive_max, orimplicit_upper_boundsare called, the upper bounds are marked “implicit”, equivalent toimplicit_upper_bounds(1, ...). Ifinput_shape,input_inclusive_max, orinput_exclusive_maxis called butimplicit_upper_boundsis not called, the upper bounds are marked “explicit”, equivalent toimplicit_upper_bounds(0, ...).If
input_labelsis not called, all dimensions are unlabeled (assigned empty labels).The default output index map is a constant output index map with an offset of
0, equivalent tooutput_constant(output_dim, 0).
After calling the setter methods, call
Finalize()to obtain aResult<IndexTransform<InputRank, OutputRank>>.Finalizemust 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, whereoutput[0] = 1 + 2 * input[0]andoutput[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_maxmethod.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, whereoutput[0] = 1 + 2 * input[0]andoutput[1] = {5, 10, 13}[input[2] - 3]. Both the input and output ranks are specified at compile time.Note
Invalid arguments specified to
IndexTransformBuilderare handled in two different ways. Callinginput_origin,input_shape,input_inclusive_max,input_exclusive_max, orinput_labelswith a sequence of length not equal toinput_rank(), and callingoutput_*with an invalidoutput_dimare fatal errors. Specifying an invalid input domain or invalid output index map is not a fatal error; theFinalizemethod will simply return an errorResultif the invalid input domain or output index map has not been overridden with a valid one prior to the call toFinalize.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
IndexTransformBuilderwith the specified input and output ranks.
Methods¶
- bool valid() const;
Returns
trueif 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_originvector, and marks theinput_originas having been set.
- IndexTransformBuilder& input_origin(const Indices& indices);
- IndexTransformBuilder& input_origin(const Index (&indices)[N]);
Sets the
input_originvector to the specified value.
- span<Index, InputRank> input_shape();
Returns the mutable
input_shapevector, 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_shapevector to the specified value. Specify a value ofkInfSizeto indicate an unbounded (infinite) upper bound.
- span<Index, InputRank> input_exclusive_max();
Returns the mutable
input_exclusive_maxvector, 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 + 1to indicate an unbounded (infinite) upper bound.
- span<Index, InputRank> input_inclusive_max();
Returns the mutable
input_inclusive_maxvector, 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
kInfIndexto 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_boundsbox, 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_labelsvector.
- IndexTransformBuilder& input_labels(const Labels& labels);
-
IndexTransformBuilder&
input_labels(const std::string_view (&labels)[N]); Sets the
input_labelsvector to the specified value.
- DimensionSet& implicit_lower_bounds();
Returns the mutable
implicit_lower_boundsbit 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_boundsbit-vector to the specified value.
- DimensionSet& implicit_upper_bounds();
Returns the mutable
implicit_upper_boundsbit 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_boundsbit-vector to the specified value.
-
IndexTransformBuilder&
output_map(DimensionIndex output_dim,
OutputIndexMapRef<OtherInputRank> map); Sets the output index map for output dimension
output_dimto a copy ofmapfrom an existing index transform.
-
IndexTransformBuilder&
output_constant(DimensionIndex output_dim, Index offset); Sets the output index map for output dimension
output_dimto aOutputIndexMethod::constantmap with the specifiedoffset.
-
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_dimto aOutputIndexMethod::single_input_dimensionmap with the specifiedoffset,stride, andinput_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_dimto anOutputIndexMethod::arraymap with the specifiedoffset,stride,index_array, and optionalindex_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 fromoutput_maps.
- Result<IndexTransform<InputRank, OutputRank>> Finalize();
Validates and returns the specified index transform.