tensorstore::Array - TensorStore

#include "tensorstore/array.h"

template <typename ElementTagType,
          DimensionIndex Rank = dynamic_rank,
          ArrayOriginKind OriginKind = zero_origin,
          ContainerKind LayoutContainerKind = container>
class tensorstore::Array;

Represents a pointer to an in-memory multi-dimensional array with an arbitrary strided layout.

This class template has several parameters:

The ownership semantics for the array data are specified using the ElementTagType template parameter: ElementTagType may be an Element type to obtain an unowned view of the array data, or may be Shared<Element>, where Element is an element type, for shared ownership of the array data.
The Element type may either be specified at compile time, or may be void or const void to indicate a dynamic element type determined at run time. Unlike a normal void*, in this case the actual dynamic type is stored as operations that depend on the type are dispatched at run time.
The rank may be specified at compile time using the Rank template parameter, or at run time by specifying a Rank of dynamic_rank.
The domain of the array may either have an implicit all-zero origin vector, by specifying an OriginKind of zero_origin, or may support an arbitrary origin vector, by specifying an OriginKind of offset_origin.
The strided layout of the array may either be owned with value semantics (by specifying a LayoutContainerKind of container) or referenced with unowned view semantics (by specifying a LayoutContainerKind of view).

Instances of this class template may be more conveniently specified using the convenience aliases {Shared,}{Offset,}Array{View,}.

Logically, this class pairs an ElementPointer with a strided Layout.

Template Parameters:¶

typename ElementTagType¶: Must satisfy IsElementTag. Either T or Shared<T>, where T satisfies IsElementType<T>.
DimensionIndex Rank = dynamic_rank ¶: The compile-time rank of the array, dynamic_rank if the rank is to be specified at run time, if LayoutContainerKind == view, dynamic_rank(n) for n >= 0 to indicate a rank specified at run time with inline layout storage for ranks k <= n.
ArrayOriginKind OriginKind = zero_origin ¶: Equal to zero_origin or offset_origin.
ContainerKind LayoutContainerKind = container ¶: Equal to container or view.

Types¶

using ElementTag = ElementTagType;: Element tag type of the array.

using Layout = StridedLayout<Rank, OriginKind, LayoutContainerKind>;: Strided layout type used by the array.

using MaybeConstIndex = typename Layout::MaybeConstIndex;: Element type of the span returned by the non-const shape and byte_strides methods.

using MaybeConstOriginIndex = typename Layout::MaybeConstOriginIndex;: Element type of the span returned by the non-const origin method.

using ElementPointer = ElementPointer<ElementTagType>;: Element pointer type.

using Element = typename ElementPointer::Element;: Element type of the array, may be const qualified.

using DataType = dtype_t<Element>;: Static or dynamic data type of the array.

using Pointer = typename ElementPointer::Pointer;: Stored data pointer, either Element* or std::shared_ptr<Element>.

using RawPointer = Element*;: Raw data pointer type.

using value_type = std::remove_cv_t<Element>;: Unqualified element type.

using index_type = Index;: Array index type.

using RankType = typename Layout::RankType;: Static or dynamic rank representation type.

using RebindRank<OtherRank> = Array<ElementTag, OtherRank, OriginKind, LayoutContainerKind>;: Alias that evaluates to an Array type with the static_rank rebound.

using RebindElement<OtherElement> = Array<typename ElementTagTraits<ElementTag>::template rebind< OtherElement>, Rank, OriginKind, LayoutContainerKind>;: Alias that evaluates to an Array type with the specified Element type rebound.

Data members¶

constexpr const DimensionIndex static_rank = RankConstraint::FromInlineRank(Rank);: Rank of the array, or dynamic_rank if specified at run time.

constexpr const ArrayOriginKind array_origin_kind = OriginKind;: Origin kind of the array.

constexpr const ContainerKind layout_container_kind = LayoutContainerKind;: Specified whether the Layout is stored by value or by reference.

Constructors¶

Array();: Default constructs both the element_pointer and the layout.

Array(SourcePointer element_pointer);: Constructs a rank-0 array from an implicitly convertible element_pointer.

explicit(...) Array(SourcePointer element_pointer, SourceLayout&& layout);: Constructs an array from a convertible element_pointer and layout.

Array(SourcePointer element_pointer, const Shape& shape, ContiguousLayoutOrder order = c_order);
Array(SourcePointer element_pointer, const Index (&shape)[ShapeRank], ContiguousLayoutOrder order = c_order);: Constructs an array with a contiguous layout from an implicitly convertible element_pointer and shape.

Array(SourcePointer element_pointer, BoxView<static_rank> domain, ContiguousLayoutOrder order = c_order);: Constructs an array with a contiguous layout from an implicitly convertible element_pointer and domain.

explicit(...) Array(const Array<E, R, O, C>& other);
explicit(...) Array(Array<E, R, O, C>&& other);: Converts from a compatible existing array.

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

Methods¶

Array& operator=(Other&& other);: Copy assigns from a compatible existing array.

bool valid() const;: Returns true if data() != nullptr.

Element* data() const;: Returns a raw pointer to the element of the array at the zero index vector.

const Pointer& pointer() const;
Pointer& pointer();: Returns a reference to the stored pointer.

DataType dtype() const;: Returns the element representation type.

const ElementPointer& element_pointer() const&;
ElementPointer& element_pointer() &;
ElementPointer&& element_pointer() &&;: Returns a reference to the element pointer.

ByteStridedPointer<Element> byte_strided_pointer() const;: Returns the base address of the array data as a ByteStridedPointer.

ByteStridedPointer<Element> byte_strided_origin_pointer() const;: Returns the base address of the array data as a ByteStridedPointer.

constexpr RankType rank() const;: Returns the rank of the array.

constexpr span<const Index, static_rank> origin() const;
span<MaybeConstOriginIndex, static_rank> origin();: Returns the origin vector of size rank().

constexpr span<const Index, static_rank> shape() const;
span<MaybeConstIndex, static_rank> shape();: Returns the shape vector of size rank().

constexpr span<const Index, static_rank> byte_strides() const;
span<MaybeConstIndex, static_rank> byte_strides();: Returns the byte strides vector of size rank().

Index num_elements() const;: Returns the total number of element, equal to the product of the elements in shape().

BoxView<static_rank> domain() const;: Returns the domain of the array.

const Layout& layout() const&;
Layout& layout() &;
Layout&& layout() &&;: Returns a reference to the layout.

Element& operator()(IndexType... index) const;: Returns a reference to the element at the specified indices.

ArrayView<Element, RankConstraint::Subtract(static_rank, 1), array_origin_kind> operator[](Index index) const;: Returns a reference to the sub-array obtained by subscripting the first dimension.

ArrayView<Element, SubArrayStaticRank<static_rank, Indices>, array_origin_kind> operator[](const Indices& indices) const;: Returns a reference to the sub-array obtained by subscripting the first std::size(indices) dimensions.

ArrayView<Element, static_rank, OriginKind> array_view() const;: Returns an ArrayView that represents the same array.

SharedArrayView<Element, static_rank, OriginKind> shared_array_view() const;: Returns a SharedArrayView that represents the same array.

const SharedArray<Element, Rank, OriginKind>& shared_array() const;: Returns a SharedArray that represents the same array.

PipelineResultType<const Array&, Func> operator|(Func&& func) const&;
PipelineResultType<Array&&, Func> operator|(Func&& func) &&;: “Pipeline” operator.

Indexing¶

Element& operator()(const Indices& indices) const;: Returns a reference to the element at the specified indices.

Friend functions¶

friend std::ostream& operator<<(std::ostream& os, const Array& array);: Prints the array to an std::ostream.

friend bool operator!=(const Array& a, const Array<ElementTagB, RankB, OriginKindB, CKindB>& b);: Returns !(a == b).

Comparison¶

friend bool operator==(const Array& a, const Array<ElementTagB, RankB, OriginKindB, CKindB>& b);: Compares the contents of two arrays for equality.

enum class tensorstore::ArrayOriginKind;

Specifies whether array indices start at zero, or at an arbitrary origin vector.

using tensorstore::
    SharedArray<Element, Rank, OriginKind, LayoutContainerKind> =
        Array<Shared<Element>, Rank, OriginKind, LayoutContainerKind>;

Convenience alias for an in-memory multi-dimensional array with an arbitrary strided layout with optional shared ownership semantics.

using tensorstore::SharedOffsetArray<Element,
                                     Rank,
                                     LayoutContainerKind> =
    Array<Shared<Element>, Rank, offset_origin, LayoutContainerKind>;

Same as SharedArray but supports an arbitrary Array::origin vector.

using tensorstore::SharedArrayView<Element, Rank, OriginKind> =
    Array<Shared<Element>, Rank, OriginKind, view>;

Convenience alias for a reference to an in-memory multi-dimensional array with an arbitrary strided layout and optional shared ownership semantics.

using tensorstore::SharedOffsetArrayView<Element, Rank> =
    Array<Shared<Element>, Rank, offset_origin, view>;

Same as SharedArrayView but supports an arbitrary Array::origin vector.

using tensorstore::ArrayView<Element, Rank, OriginKind> =
    Array<Element, Rank, OriginKind, view>;

Convenience alias for an unowned reference to an in-memory multi-dimensional array with an arbitrary strided layout.

using tensorstore::OffsetArrayView<Element, Rank> =
    Array<Element, Rank, offset_origin, view>;

Same as ArrayView but supports an arbitrary Array::origin vector.

constexpr bool tensorstore::IsArrayExplicitlyConvertible<
    SourceElement,
    SourceRank,
    SourceOriginKind,
    DestElement,
    DestRank,
    DestOriginKind> =
    IsElementTypeExplicitlyConvertible<SourceElement, DestElement> &&
    RankConstraint::EqualOrUnspecified(SourceRank, DestRank) &&
    IsArrayOriginKindConvertible(SourceOriginKind, DestOriginKind);

Bool-valued metafunction that determines whether a (SourceElement, SourceRank, SourceOriginKind) tuple is potentially convertible to a (DestElement, DestRank, DestOriginKind) tuple, based on IsElementTypeExplicitlyConvertible, RankConstraint::EqualOrUnspecified and IsArrayOriginKindConvertible.

constexpr bool tensorstore::IsArray<T>;

Bool-valued metafunction that is true if T is an instance of Array.

constexpr DimensionIndex
tensorstore::SubArrayStaticRank<Rank, Indices>;

Metafunction that computes the static rank of the sub-array obtained by indexing an array of the given Rank with an index vector of type Indices.

Array<
    typename ElementTagTraits<ElementTag>::Element,
    SubArrayStaticRank<RankConstraint::FromInlineRank(Rank), Indices>,
    OriginKind,
    LayoutCKind>
tensorstore::SubArray(
    const Array<ElementTag, Rank, OriginKind, SourceCKind>& array,
    const Indices& indices);

SharedArray<
    Element,
    SubArrayStaticRank<RankConstraint::FromInlineRank(Rank), Indices>,
    OriginKind,
    LayoutCKind>
tensorstore::SharedSubArray(
    const SharedArray<Element, Rank, OriginKind, SourceCKind>& array,
    const Indices& indices);

Returns a reference to the sub-array obtained by subscripting the first tensorstore::span(indices).size() dimensions of array.

Result<Array<typename std::remove_cvref_t<A>::ElementTag,
             std::remove_cvref_t<A>::static_rank,
             TargetOriginKind,
             LayoutContainerKind>>
tensorstore::ArrayOriginCast(A&& array);

Array<typename std::remove_cvref_t<A>::ElementTag,
      std::remove_cvref_t<A>::static_rank,
      TargetOriginKind,
      LayoutContainerKind>
tensorstore::ArrayOriginCast(A&& array);

Converts an array to the specified origin kind.

SharedArray<Element, Rank, OriginKind, LayoutCKind>
tensorstore::UnownedToShared(
    Array<Element, Rank, OriginKind, LayoutCKind> array);

SharedArray<Element, Rank, OriginKind, LayoutCKind>
tensorstore::UnownedToShared(
    const std::shared_ptr<T>& owned,
    Array<Element, Rank, OriginKind, LayoutCKind> array);

SharedArray<Element, Rank, OriginKind, LayoutCKind>
tensorstore::UnownedToShared(
    SharedArray<Element, Rank, OriginKind, LayoutCKind> array);

Converts an arbitrary array to a SharedArray.

void tensorstore::InitializeArray(
    const ArrayView<void, dynamic_rank, offset_origin>& array);

Assigns all elements of an array to the result of value initialization.

SharedElementPointer<Element> tensorstore::AllocateArrayElementsLike(
    const StridedLayout<Rank, OriginKind, CKind>& layout,
    Index* byte_strides,
    IterationConstraints constraints,
    ElementInitialization initialization = default_init,
    dtype_t<Element> dtype = dtype_v<Element>);

Allocates an array data buffer with a layout similar to an existing strided layout.

bool tensorstore::ArraysHaveSameShapes(const Array0& array0,
                                       const Array&... array);

Checks that all array arguments have the same shape.

bool tensorstore::IterateOverArrays(Func&& func,
                                    IterationConstraints constraints,
                                    const Array&... array);

Iterates over one array or jointly iterates over multiple arrays.

BoxView<Rank> tensorstore::GetBoxDomainOf(
    const Array<PointerType, Rank, OriginKind, LayoutContainerKind>&
        array);

Implements the HasBoxDomain concept for Array.

bool tensorstore::AreArraysEqual(
    const Array<ElementTagA, RankA, OKindA, CKindA>& a,
    const Array<ElementTagB, RankB, OKindB, CKindB>& b,
    EqualityComparisonKind kind = EqualityComparisonKind::equal);

bool tensorstore::AreArraysIdenticallyEqual(
    const Array<ElementTagA, RankA, OKindA, CKindA>& a,
    const Array<ElementTagB, RankB, OKindB, CKindB>& b);

Compares two arrays for equality.

bool tensorstore::IsContiguousLayout(
    const Array<ElementTag, Rank, OriginKind, LayoutCKind>& array,
    ContiguousLayoutOrder order);

Checks if array has a contiguous layout with the specified order.

Index tensorstore::GetByteExtent(
    const Array<ElementTag, Rank, OriginKind, LayoutCKind>& array);

Returns minimum number of contiguous bytes into which the array fits.

auto tensorstore::ApplyIndexTransform(Expr&& expr, T&& t);

Applies a function that operates on an IndexTransform to a strided (non-transformed) array. The result is always a TransformedArray.

ArrayView<std::remove_reference_t<Element>, 0>
tensorstore::MakeScalarArrayView(Element&& x);

Returns a rank-0 array that points to (but does not copy) the specified value.

SharedArray<Element, 0>
tensorstore::MakeScalarArray(const Element& x);

Returns a rank-0 array containing a copy of the specified value.

auto tensorstore::MakeArrayView(Source&& source);

Returns a rank-1 array that references (but does not copy) the specified span-compatible array/container.

ArrayView<Element, 1>
tensorstore::MakeArrayView(Element (&array)[N0]);

ArrayView<const Element, 1>
tensorstore::MakeArrayView(const Element (&array)[N0]);

ArrayView<Element, 2>
tensorstore::MakeArrayView(Element (&array)[N0][N1]);

ArrayView<const Element, 2>
tensorstore::MakeArrayView(const Element (&array)[N0][N1]);

Returns an ArrayView that points to the specified C array.

SharedArray<Element, 1> tensorstore::MakeArray(Element (&array)[N0]);

SharedArray<Element, 1>
tensorstore::MakeArray(const Element (&array)[N0]);

SharedArray<Element, 2>
tensorstore::MakeArray(Element (&array)[N0][N1]);

SharedArray<Element, 2>
tensorstore::MakeArray(const Element (&array)[N0][N1]);

Returns a SharedArray containing a copy of the specified C array.

ArrayView<Element, 1, offset_origin>
tensorstore::MakeOffsetArrayView(span<const Index, 1> origin,
                                 Element (&array)[N0]);

ArrayView<const Element, 1, offset_origin>
tensorstore::MakeOffsetArrayView(span<const Index, 1> origin,
                                 const Element (&array)[N0]);

ArrayView<Element, 2, offset_origin>
tensorstore::MakeOffsetArrayView(span<const Index, 2> origin,
                                 Element (&array)[N0][N1]);

ArrayView<const Element, 2, offset_origin>
tensorstore::MakeOffsetArrayView(span<const Index, 2> origin,
                                 const Element (&array)[N0][N1]);

Returns an ArrayView that points to the specified C array.

SharedArray<Element, 1, offset_origin>
tensorstore::MakeOffsetArray(span<const Index, 1> origin,
                             Element (&array)[N0]);

SharedArray<Element, 1, offset_origin>
tensorstore::MakeOffsetArray(span<const Index, 1> origin,
                             const Element (&array)[N0]);

SharedArray<Element, 2, offset_origin>
tensorstore::MakeOffsetArray(span<const Index, 2> origin,
                             Element (&array)[N0][N1]);

SharedArray<Element, 2, offset_origin>
tensorstore::MakeOffsetArray(span<const Index, 2> origin,
                             const Element (&array)[N0][N1]);

Returns a SharedArray containing a copy of the specified C array.

auto tensorstore::AllocateArray(
    const Extents& extents,
    ContiguousLayoutOrder layout_order = ContiguousLayoutOrder::c,
    ElementInitialization initialization = default_init,
    dtype_t<Element> dtype = dtype_v<Element>);

SharedArray<Element, BoxType::static_rank, offset_origin>
tensorstore::AllocateArray(
    const BoxType& domain,
    ContiguousLayoutOrder layout_order = ContiguousLayoutOrder::c,
    ElementInitialization initialization = default_init,
    dtype_t<Element> dtype = dtype_v<Element>);

Allocates a contiguous array of the specified shape/domain and type.

SharedArray<Element, Rank, OriginKind> tensorstore::AllocateArrayLike(
    const StridedLayout<Rank, OriginKind, CKind>& layout,
    IterationConstraints constraints = c_order,
    ElementInitialization initialization = default_init,
    dtype_t<Element> dtype = dtype_v<Element>);

Allocates an array with a layout similar to an existing strided layout.

void tensorstore::CopyArray(const Source& source, const Dest& dest);

Copies the contents of source to dest.

absl::Status tensorstore::CopyConvertedArray(const Source& source,
                                             const Dest& dest);

Copies the contents of source to dest, with optional data type conversion.

SharedArray<std::remove_cv_t<typename ElementTagTraits<E>::Element>,
            R,
            O>
tensorstore::MakeCopy(const Array<E, R, O, C>& source,
                      IterationConstraints constraints = {
                          c_order, include_repeated_elements});

Returns a copy of the contents of an array.

Result<SharedArray<TargetElement, R, O>> tensorstore::MakeCopy(
    const Array<E, R, O, C>& source,
    IterationConstraints constraints = {c_order,
                                        include_repeated_elements},
    dtype_t<TargetElement> target_dtype = dtype_v<TargetElement>);

Result<SharedArray<void, R, O>>
tensorstore::MakeCopy(const Array<E, R, O, C>& source,
                      IterationConstraints constraints,
                      DataType target_dtype);

Returns a copy of the contents of an array, with the data type converted.

struct tensorstore::ArrayFormatOptions;

Specifies options for formatting an array.

void tensorstore::AppendToString(
    std::string* result,
    const ArrayView<const void, dynamic_rank, offset_origin>& array,
    const ArrayFormatOptions& options =
        ArrayFormatOptions::Default());

Appends a string representation of array to *result.

std::string tensorstore::ToString(
    const ArrayView<const void, dynamic_rank, offset_origin>& array,
    const ArrayFormatOptions& options =
        ArrayFormatOptions::Default());

Returns a string representation of array (same representation as AppendToString).

Result<Array<ElementTag, dynamic_rank, zero_origin>>
tensorstore::BroadcastArray(
    const Array<ElementTag, Rank, zero_origin, CKind>& source,
    span<const Index> target_shape);

Result<Array<ElementTag, dynamic_rank, offset_origin>>
tensorstore::BroadcastArray(
    const Array<ElementTag, Rank, OriginKind, CKind>& source,
    BoxView<> target_domain);

Broadcasts source to target_shape.

Array<ElementTag> tensorstore::UnbroadcastArray(
    const Array<ElementTag, Rank, OriginKind, CKind>& source);

Converts zero-stride dimensions (with non-zero size) to have an extent of 1, removes leading singleton dimensions, and translates the origin to 0.

Array<ElementTag, (Rank < 0 ? dynamic_rank(kMaxRank) : Rank)>
tensorstore::UnbroadcastArrayPreserveRank(
    const Array<ElementTag, Rank, OriginKind, CKind>& source);

Converts zero-stride dimensions (with non-zero size) to have an extent of 1, and translates the origin to 0.

bool tensorstore::IsBroadcastScalar(
    const Array<ElementTag, Rank, OriginKind, LayoutCKind>& array);

Checks if array has at most a single distinct element.

Types¶

Data members¶

Constructors¶

Methods¶

Indexing¶

Friend functions¶

Comparison¶

Creation functions¶

Copy functions¶

Formatting¶

Broadcasting¶

Types¶

Data members¶

Constructors¶

Methods¶

Indexing¶

Friend functions¶

Comparison¶

Related Types¶

Related Constants¶

Related Functions¶

Creation functions¶

Copy functions¶

Formatting¶

Broadcasting¶