tensorstore::Box - TensorStore

#include "tensorstore/box.h"

template <DimensionIndex Rank = dynamic_rank> class tensorstore::Box;

Value type representing an n-dimensional hyperrectangle.

Hyperrectangles logically correspond to a cartesian product of IndexInterval objects, and are represented as an origin vector and a shape vector, which is equivalent to the “sized” index interval representation: the components of the origin vector correspond to IndexInterval::inclusive_min values, while the components of the shape vector correspond to the IndexInterval::size values (not to IndexInterval::exclusive_max values).

Several related class templates are provided:

Box<Rank> has value semantics (owns its origin and shape vectors) and is mutable. This type stores a hyperrectangle and manages the storage.
BoxView<Rank> represents a const view that behaves similarly to std::string_view: logically it points to existing origin and shape vectors (of type tensorstore::span<const Index, Rank>). Like std::string_view, assignment is shallow and merely reassigns its origin and shape pointers, but comparison is deep. This type is useful as an input parameter type for a function.
MutableBoxView<Rank> (an alias for BoxView<Rank, true>) represents a mutable view: it points to existing origin and shape vectors (of type tensorstore::span<Index, Rank>). Like BoxView<Rank>, assignment is shallow but comparison is deep. The BoxView::DeepAssign method may be used for deep assignment (modifies the contents of the referenced origin and shape vectors). This type is useful as an output or input/output parameter type for a function.

These types are useful for specifying hyperrectangular sub-regions, and in particular can be used to represent the domains of arrays, index transforms, and tensor stores.

Note

Like other facilities within the TensorStore library, the rank of the index space may be specified either at compile time using the Rank template parameter, or at run time by specifying a Rank of dynamic_rank.

Example usage:

void Intersect(BoxView<> a, BoxView<> b, MutableBoxView<> out) {
  const DimensionIndex rank = a.rank();
  assert(b.rank() == rank && out.rank() == rank);
  for (DimensionIndex i = 0; i < rank; ++i) {
    out[i] = Intersect(a[i], b[i]);
  }
}

const Index a_origin[] = {1, 2};
const Index a_shape[] = {3, 4};
auto b = Box({2,1}, {2, 2});
Index c_origin[2], c_shape[2];

// Assigns `c_origin` and `c_shape` to the intersection of
// `(a_origin,a_shape)` and `b`.
Intersect(BoxView(a_origin, a_shape), b,
          BoxView(c_origin, c_shape));

// Assigns `d` to the intersection of `(a_origin,a_shape)` and `b`.
Box d(2);
Intersect(BoxView(a_origin, a_shape), b, d);

Template Parameters:¶

DimensionIndex Rank = dynamic_rank ¶: If non-negative, specifies the number of dimensions at compile time. If equal to dynamic_rank(inline_size), or dynamic_rank (equivalent to specifying inline_size==0), the number of dimensions will be specified at run time. If the number of dimensions is not greater than inline_size, no heap allocation is necessary.

Data members¶

constexpr const DimensionIndex static_rank = (Rank < 0) ? dynamic_rank : Rank;: Compile-time rank, or dynamic_rank if the rank is specified at run time.

Types¶

using RankType = StaticOrDynamicRank<Rank>;: Type that represents the static or dynamic rank.

Constructors¶

Box();: Constructs a rank-0 box (if static_rank == dynamic_rank), or otherwise an unbounded box of rank static_rank.

explicit Box(RankType rank);: Constructs an unbounded box of the specified rank.

explicit Box(OriginVec origin, ShapeVec shape);
explicit Box(const Index (&origin)[N], const Index (&shape)[N]);: Constructs from an origin array and shape array.

explicit Box(RankType rank, OriginT* origin, ShapeT* shape);: Constructs from a rank, an origin base pointer, and a shape base pointer.

explicit Box(const ShapeVec& shape);
explicit Box(const Index (&shape)[N]);: Constructs from a shape vector.

explicit Box(const BoxType& other);: Constructs from another Box-like type with a compatible rank.

explicit Box(unchecked_t, const BoxType& other);: Unchecked conversion.

explicit Box(unchecked_t, Box&& other);: Unchecked conversion.

Methods¶

Box& operator=(const BoxType& other);: Assigns from another Box-like type with a compatible rank.

RankType rank() const;: Returns the rank of the box.

IndexInterval operator[](DimensionIndex i) const;
IndexIntervalRef operator[](DimensionIndex i);: Returns a copy/reference to the index interval for dimension i.

auto operator()(Transformable&& transformable) const;: Slices a type with an index domain a box.

Accessors¶

span<const Index, static_rank> origin() const;
span<Index, static_rank> origin();: Returns the origin array of length rank().

span<const Index, static_rank> shape() const;
span<Index, static_rank> shape();: Returns the shape array of length rank().

Index num_elements() const;: Returns the product of the extents.

bool is_empty() const;: Returns true if num_elements() == 0.

Assignment¶

void set_rank(RankType rank);: Resets *this to an unbounded box of the specified rank.

void Fill(IndexInterval interval = {});: Fills origin() with interval.inclusive_min() and shape with interval.size().

Friend functions¶

friend std::ostream& operator<<(std::ostream& os, const Box& box);: Prints to an std::ostream.

T tensorstore::ProductOfExtents(span<T, Extent> s);: Computes the product of the elements of the given span.

BoxView<RankConstraint::FromInlineRank(Rank)> tensorstore::GetBoxDomainOf(const Box<Rank>& box);
BoxView<Rank> tensorstore::GetBoxDomainOf(const BoxView<Rank, Mutable>& box);: Implements the HasBoxDomain concept for Box and BoxView.

bool tensorstore::IsFinite(const BoxType& box);: Returns true if all dimensions of box have finite bounds.

bool tensorstore::Contains(const BoxType& box, const Indices& indices);
bool tensorstore::Contains(const BoxType& box, const Index (&indices)[IndicesRank]);: Returns true if the index vector indices is contained within the box, i.e. its length is equal to the rank of the box and each component indices[i] is contained within box[i].

bool tensorstore::Contains(const OuterBox& outer, const InnerBox& inner);: Returns true if inner is a subset of outer.

bool tensorstore::ContainsPartial(const BoxType& box, const Indices& indices);
bool tensorstore::ContainsPartial( const BoxType& box, const Index (&indices)[IndicesRank]);: Returns true if the partial index vector indices is contained within the box, i.e. its length is less than or equal to the rank of the box and each component indices[i] is contained within box[i].

BoxView<dynamic_rank, IsMutableBoxLike<BoxType>> tensorstore::SubBoxView(BoxType&& box, DimensionIndex begin = 0, DimensionIndex end = -1);: Returns a view of the sub-box corresponding to the specified dimension range.

constexpr bool tensorstore::IsBoxLike<T>;: Metafunction that evaluates to true if, and only if, T is an optionally cvref-qualified Box or BoxView instance.

constexpr bool tensorstore::IsMutableBoxLike<T>;: Metafunction that evaluates to true if, and only if, T is an optionally ref-qualified non-const Box or MutableBoxView instance.

constexpr bool tensorstore::IsBoxLikeImplicitlyConvertibleToRank<T, Rank>;: Metafunction that evaluates to true if, and only if, T is a Box-like type with Box::static_rank implicitly convertible to Rank.

constexpr bool tensorstore::IsBoxLikeExplicitlyConvertibleToRank<T, Rank>;: Metafunction that evaluates to true if, and only if, T is a Box-like type with Box::static_rank explicitly convertible to Rank.

constexpr bool tensorstore::HasBoxDomain<T>;: Metafunction that is specialized to return true for types T for which tensorstore::GetBoxDomainOf when called with a parameter of type const T& returns a Box-like type.

class tensorstore::BoxView<Rank, Mutable>;: Represents an unowned view of a Rank-dimensional hyperrectangle.

using tensorstore::MutableBoxView<Rank> = BoxView<Rank, true>;: Mutable view of a Box.