[mdspan.extents] (original) (raw)

23 Containers library [containers]

23.7 Views [views]

23.7.3 Multidimensional access [views.multidim]

23.7.3.3 Class template extents [mdspan.extents]

23.7.3.3.1 Overview [mdspan.extents.overview]

The class template extents represents a multidimensional index space of rank equal to sizeof...(Extents).

In ([views]),extents is used synonymously with multidimensional index space.

namespace std { template<class IndexType, size_t... Extents> class extents { public: using index_type = IndexType;using size_type = make_unsigned_t<index_type>;using rank_type = size_t;static constexpr rank_type rank() noexcept { return sizeof...(Extents); } static constexpr rank_type rank_dynamic() noexcept { return dynamic-index(rank()); } static constexpr size_t static_extent(rank_type) noexcept;constexpr index_type extent(rank_type) const noexcept;constexpr extents() noexcept = default;template<class OtherIndexType, size_t... OtherExtents> constexpr explicit(see below) extents(const extents<OtherIndexType, OtherExtents...>&) noexcept;template<class... OtherIndexTypes> constexpr explicit extents(OtherIndexTypes...) noexcept;template<class OtherIndexType, size_t N> constexpr explicit(N != rank_dynamic()) extents(span<OtherIndexType, N>) noexcept;template<class OtherIndexType, size_t N> constexpr explicit(N != rank_dynamic()) extents(const array<OtherIndexType, N>&) noexcept;template<class OtherIndexType, size_t... OtherExtents> friend constexpr bool operator==(const extents&,const extents<OtherIndexType, OtherExtents...>&) noexcept;constexpr size_t fwd-prod-of-extents(rank_type) const noexcept; constexpr size_t rev-prod-of-extents(rank_type) const noexcept; template<class OtherIndexType> static constexpr auto index-cast(OtherIndexType&&) noexcept; private: static constexpr rank_type dynamic-index(rank_type) noexcept; static constexpr rank_type dynamic-index-inv(rank_type) noexcept; array<index_type, rank_dynamic()> dynamic-extents{}; };template<class... Integrals> explicit extents(Integrals...) -> see below;}

Mandates:

• IndexType is a signed or unsigned integer type, and
• each element of Extents is either equal to dynamic_extent, or is representable as a value of type IndexType.

Each specialization of extents models regular and is trivially copyable.

Let be the element of Extents.

is a dynamic extent if it is equal to dynamic_extent, otherwise is a static extent.

Let be the value of _dynamic-extents_[dynamic-index(r)]if is a dynamic extent, otherwise .

The interval of the multidimensional index space represented by an extents object is .

23.7.3.3.2 Exposition-only helpers [mdspan.extents.expo]

static constexpr rank_type _dynamic-index_(rank_type i) noexcept;

Preconditions: i <= rank() is true.

Returns: The number of with for which is a dynamic extent.

static constexpr rank_type _dynamic-index-inv_(rank_type i) noexcept;

Preconditions: i < rank_dynamic() is true.

Returns: The minimum value of rsuch that dynamic-index(r + 1) == i + 1 is true.

constexpr size_t _fwd-prod-of-extents_(rank_type i) const noexcept;

Preconditions: i <= rank() is true.

Returns: If i > 0 is true, the product of extent(k) for all k in the range [0, i), otherwise 1.

constexpr size_t _rev-prod-of-extents_(rank_type i) const noexcept;

Preconditions: i < rank() is true.

Returns: If i + 1 < rank() is true, the product of extent(k)for all k in the range [i + 1, rank()), otherwise 1.

template<class OtherIndexType> static constexpr auto _index-cast_(OtherIndexType&& i) noexcept;

Effects:

• If OtherIndexType is an integral type other than bool, then equivalent to return i;,
• otherwise, equivalent to return static_cast<index_type>(i);.

[Note 1:

This function will always return an integral type other than bool.

Since this function's call sites are constrained on convertibility of OtherIndexType to index_type, integer-class types can use the static_cast branch without loss of precision.

— _end note_]

23.7.3.3.3 Constructors [mdspan.extents.cons]

template<class OtherIndexType, size_t... OtherExtents> constexpr explicit(_see below_) extents(const extents<OtherIndexType, OtherExtents...>& other) noexcept;

Constraints:

• sizeof...(OtherExtents) == rank() is true.
• ((OtherExtents == dynamic_extent || Extents == dynamic_extent || OtherExtents ==
  Extents) && ...) is true.

Preconditions:

• other.extent(r) equals for each r for which is a static extent, and
• either
  • sizeof...(OtherExtents) is zero, or
  • other.extent(r) is representable as a value of type index_type for every rank index r of other.

Postconditions: *this == other is true.

Remarks: The expression inside explicit is equivalent to:(((Extents != dynamic_extent) && (OtherExtents == dynamic_extent)) || ... ) || (numeric_limits<index_type>::max() < numeric_limits<OtherIndexType>::max())

template<class... OtherIndexTypes> constexpr explicit extents(OtherIndexTypes... exts) noexcept;

Let N be sizeof...(OtherIndexTypes), and let exts_arr bearray<index_type, N>{static_cast<
index_type>(std​::​move(exts))...}.

Constraints:

• (is_convertible_v<OtherIndexTypes, index_type> && ...) is true,
• (is_nothrow_constructible_v<index_type, OtherIndexTypes> && ...) is true, and
• N == rank_dynamic() || N == rank() is true.
  [Note 1:
  One can construct extents from just dynamic extents, which are all the values getting stored, or from all the extents with a precondition.
  — _end note_]

Preconditions:

• If N != rank_dynamic() is true,exts_arr[r] equals for each r for which is a static extent, and
• either
  • sizeof...(exts) == 0 is true, or
  • each element of exts is representable as a nonnegative value of type index_type.

Postconditions: *this == extents(exts_arr) is true.

template<class OtherIndexType, size_t N> constexpr explicit(N != rank_dynamic()) extents(span<OtherIndexType, N> exts) noexcept;template<class OtherIndexType, size_t N> constexpr explicit(N != rank_dynamic()) extents(const array<OtherIndexType, N>& exts) noexcept;

Constraints:

• is_convertible_v<const OtherIndexType&, index_type> is true,
• is_nothrow_constructible_v<index_type, const OtherIndexType&> is true, and
• N == rank_dynamic() || N == rank() is true.

Preconditions:

• If N != rank_dynamic() is true,exts[r] equals for each r for which is a static extent, and
• either
  • N is zero, or
  • exts[r] is representable as a nonnegative value of type index_type for every rank index r.

Effects:

• If N equals rank_dynamic(), for all d in the range [0, rank_dynamic()), direct-non-list-initializes _dynamic-extents_[d]with as_const(exts[d]).
• Otherwise, for all d in the range [0, rank_dynamic()), direct-non-list-initializes _dynamic-extents_[d]with as_const(exts[dynamic-index-inv(d)]).

template<class... Integrals> explicit extents(Integrals...) -> _see below_;

Constraints: (is_convertible_v<Integrals, size_t> && ...) is true.

23.7.3.3.4 Observers of the multidimensional index space [mdspan.extents.obs]

static constexpr size_t static_extent(rank_type i) noexcept;

Preconditions: i < rank() is true.

constexpr index_type extent(rank_type i) const noexcept;

Preconditions: i < rank() is true.

23.7.3.3.5 Comparison operators [mdspan.extents.cmp]

template<class OtherIndexType, size_t... OtherExtents> friend constexpr bool operator==(const extents& lhs,const extents<OtherIndexType, OtherExtents...>& rhs) noexcept;

Returns: true if lhs.rank() equals rhs.rank() and if lhs.extent(r) equals rhs.extent(r)for every rank index r of rhs, otherwise false.

23.7.3.3.6 Alias template dextents [mdspan.extents.dextents]

template<class IndexType, size_t Rank> using dextents = _see below_;

Result: A type E that is a specialization of extentssuch that E​::​rank() == Rank && E​::​rank() == E​::​rank_dynamic() is true, andE​::​index_type denotes IndexType.

23.7.3.3.7 Alias template dims [mdspan.extents.dims]

template<size_t Rank, class IndexType = size_t> using dims = _see below_;

Result: A type E that is a specialization of extentssuch that E​::​rank() == Rank && E​::​rank() == E​::​rank_dynamic() is true, andE​::​index_type denotes IndexType.