24 Containers library [containers]

24.7 Views [views]

24.7.3 Multidimensional access [views.multidim]

24.7.3.6 Class template mdspan [mdspan.mdspan]

24.7.3.6.1 Overview [mdspan.mdspan.overview]

mdspan is a view of a multidimensional array of elements.
namespace std { template<class ElementType, class Extents, class LayoutPolicy = layout_right, class AccessorPolicy = default_accessor<ElementType>> class mdspan { public: using extents_type = Extents; using layout_type = LayoutPolicy; using accessor_type = AccessorPolicy; using mapping_type = typename layout_type::template mapping<extents_type>; using element_type = ElementType; using value_type = remove_cv_t<element_type>; using index_type = typename extents_type::index_type; using size_type = typename extents_type::size_type; using rank_type = typename extents_type::rank_type; using data_handle_type = typename accessor_type::data_handle_type; using reference = typename accessor_type::reference; static constexpr rank_type rank() noexcept { return extents_type::rank(); } static constexpr rank_type rank_dynamic() noexcept { return extents_type::rank_dynamic(); } static constexpr size_t static_extent(rank_type r) noexcept { return extents_type::static_extent(r); } constexpr index_type extent(rank_type r) const noexcept { return extents().extent(r); } // [mdspan.mdspan.cons], constructors constexpr mdspan(); constexpr mdspan(const mdspan& rhs) = default; constexpr mdspan(mdspan&& rhs) = default; template<class... OtherIndexTypes> constexpr explicit mdspan(data_handle_type ptr, OtherIndexTypes... exts); template<class OtherIndexType, size_t N> constexpr explicit(N != rank_dynamic()) mdspan(data_handle_type p, span<OtherIndexType, N> exts); template<class OtherIndexType, size_t N> constexpr explicit(N != rank_dynamic()) mdspan(data_handle_type p, const array<OtherIndexType, N>& exts); constexpr mdspan(data_handle_type p, const extents_type& ext); constexpr mdspan(data_handle_type p, const mapping_type& m); constexpr mdspan(data_handle_type p, const mapping_type& m, const accessor_type& a); template<class OtherElementType, class OtherExtents, class OtherLayoutPolicy, class OtherAccessorPolicy> constexpr explicit(see below) mdspan(const mdspan<OtherElementType, OtherExtents, OtherLayoutPolicy, OtherAccessorPolicy>& other); constexpr mdspan& operator=(const mdspan& rhs) = default; constexpr mdspan& operator=(mdspan&& rhs) = default; // [mdspan.mdspan.members], members template<class... OtherIndexTypes> constexpr reference operator[](OtherIndexTypes... indices) const; template<class OtherIndexType> constexpr reference operator[](span<OtherIndexType, rank()> indices) const; template<class OtherIndexType> constexpr reference operator[](const array<OtherIndexType, rank()>& indices) const; constexpr size_type size() const noexcept; [[nodiscard]] constexpr bool empty() const noexcept; friend constexpr void swap(mdspan& x, mdspan& y) noexcept; constexpr const extents_type& extents() const noexcept { return map_.extents(); } constexpr const data_handle_type& data_handle() const noexcept { return ptr_; } constexpr const mapping_type& mapping() const noexcept { return map_; } constexpr const accessor_type& accessor() const noexcept { return acc_; } static constexpr bool is_always_unique() { return mapping_type::is_always_unique(); } static constexpr bool is_always_exhaustive() { return mapping_type::is_always_exhaustive(); } static constexpr bool is_always_strided() { return mapping_type::is_always_strided(); } constexpr bool is_unique() const { return map_.is_unique(); } constexpr bool is_exhaustive() const { return map_.is_exhaustive(); } constexpr bool is_strided() const { return map_.is_strided(); } constexpr index_type stride(rank_type r) const { return map_.stride(r); } private: accessor_type acc_; // exposition only mapping_type map_; // exposition only data_handle_type ptr_; // exposition only }; template<class CArray> requires (is_array_v<CArray> && rank_v<CArray> == 1) mdspan(CArray&) -> mdspan<remove_all_extents_t<CArray>, extents<size_t, extent_v<CArray, 0>>>; template<class Pointer> requires (is_pointer_v<remove_reference_t<Pointer>>) mdspan(Pointer&&) -> mdspan<remove_pointer_t<remove_reference_t<Pointer>>, extents<size_t>>; template<class ElementType, class... Integrals> requires ((is_convertible_v<Integrals, size_t> && ...) && sizeof...(Integrals) > 0) explicit mdspan(ElementType*, Integrals...) -> mdspan<ElementType, dextents<size_t, sizeof...(Integrals)>>; template<class ElementType, class OtherIndexType, size_t N> mdspan(ElementType*, span<OtherIndexType, N>) -> mdspan<ElementType, dextents<size_t, N>>; template<class ElementType, class OtherIndexType, size_t N> mdspan(ElementType*, const array<OtherIndexType, N>&) -> mdspan<ElementType, dextents<size_t, N>>; template<class ElementType, class IndexType, size_t... ExtentsPack> mdspan(ElementType*, const extents<IndexType, ExtentsPack...>&) -> mdspan<ElementType, extents<IndexType, ExtentsPack...>>; template<class ElementType, class MappingType> mdspan(ElementType*, const MappingType&) -> mdspan<ElementType, typename MappingType::extents_type, typename MappingType::layout_type>; template<class MappingType, class AccessorType> mdspan(const typename AccessorType::data_handle_type&, const MappingType&, const AccessorType&) -> mdspan<typename AccessorType::element_type, typename MappingType::extents_type, typename MappingType::layout_type, AccessorType>; }
Mandates:
  • ElementType is a complete object type that is neither an abstract class type nor an array type,
  • Extents is a specialization of extents, and
  • is_same_v<ElementType, typename AccessorPolicy​::​element_type> is true.
LayoutPolicy shall meet the layout mapping policy requirements ([mdspan.layout.policy.reqmts]), and AccessorPolicy shall meet the accessor policy requirements ([mdspan.accessor.reqmts]).
Each specialization MDS of mdspan models copyable and
  • is_nothrow_move_constructible_v<MDS> is true,
  • is_nothrow_move_assignable_v<MDS> is true, and
  • is_nothrow_swappable_v<MDS> is true.
A specialization of mdspan is a trivially copyable type if its accessor_type, mapping_type, and data_handle_type are trivially copyable types.

24.7.3.6.2 Constructors [mdspan.mdspan.cons]

constexpr mdspan();
Constraints:
  • rank_dynamic() > 0 is true.
  • is_default_constructible_v<data_handle_type> is true.
  • is_default_constructible_v<mapping_type> is true.
  • is_default_constructible_v<accessor_type> is true.
Preconditions: [0, map_.required_span_size()) is an accessible range of ptr_ and acc_ for the values of map_ and acc_ after the invocation of this constructor.
Effects: Value-initializes ptr_, map_, and acc_.
template<class... OtherIndexTypes> constexpr explicit mdspan(data_handle_type p, OtherIndexTypes... exts);
Let N be sizeof...(OtherIndexTypes).
Constraints:
  • (is_convertible_v<OtherIndexTypes, index_type> && ...) is true,
  • (is_nothrow_constructible<index_type, OtherIndexTypes> && ...) is true,
  • N == rank() || N == rank_dynamic() is true,
  • is_constructible_v<mapping_type, extents_type> is true, and
  • is_default_constructible_v<accessor_type> is true.
Preconditions: [0, map_.required_span_size()) is an accessible range of p and acc_ for the values of map_ and acc_ after the invocation of this constructor.
Effects:
  • Direct-non-list-initializes ptr_ with std​::​move(p),
  • direct-non-list-initializes map_ with extents_type(static_cast<index_type>(std​::​move(exts​))...), and
  • value-initializes acc_.
template<class OtherIndexType, size_t N> constexpr explicit(N != rank_dynamic()) mdspan(data_handle_type p, span<OtherIndexType, N> exts); template<class OtherIndexType, size_t N> constexpr explicit(N != rank_dynamic()) mdspan(data_handle_type p, const array<OtherIndexType, N>& exts);
Constraints:
  • is_convertible_v<const OtherIndexType&, index_type> is true,
  • is_nothrow_constructible_v<index_type, const OtherIndexType&> is true,
  • N == rank() || N == rank_dynamic() is true,
  • is_constructible_v<mapping_type, extents_type> is true, and
  • is_default_constructible_v<accessor_type> is true.
Preconditions: [0, map_.required_span_size()) is an accessible range of p and acc_ for the values of map_ and acc_ after the invocation of this constructor.
Effects:
  • Direct-non-list-initializes ptr_ with std​::​move(p),
  • direct-non-list-initializes map_ with extents_type(exts), and
  • value-initializes acc_.
constexpr mdspan(data_handle_type p, const extents_type& ext);
Constraints:
  • is_constructible_v<mapping_type, const extents_type&> is true, and
  • is_default_constructible_v<accessor_type> is true.
Preconditions: [0, map_.required_span_size()) is an accessible range of p and acc_ for the values of map_ and acc_ after the invocation of this constructor.
Effects:
  • Direct-non-list-initializes ptr_ with std​::​move(p),
  • direct-non-list-initializes map_ with ext, and
  • value-initializes acc_.
constexpr mdspan(data_handle_type p, const mapping_type& m);
Constraints: is_default_constructible_v<accessor_type> is true.
Preconditions: [0, m.required_span_size()) is an accessible range of p and acc_ for the value of acc_ after the invocation of this constructor.
Effects:
  • Direct-non-list-initializes ptr_ with std​::​move(p),
  • direct-non-list-initializes map_ with m, and
  • value-initializes acc_.
constexpr mdspan(data_handle_type p, const mapping_type& m, const accessor_type& a);
Preconditions: [0, m.required_span_size()) is an accessible range of p and a.
Effects:
  • Direct-non-list-initializes ptr_ with std​::​move(p),
  • direct-non-list-initializes map_ with m, and
  • direct-non-list-initializes acc_ with a.
template<class OtherElementType, class OtherExtents, class OtherLayoutPolicy, class OtherAccessor> constexpr explicit(see below) mdspan(const mdspan<OtherElementType, OtherExtents, OtherLayoutPolicy, OtherAccessor>& other);
Constraints:
  • is_constructible_v<mapping_type, const OtherLayoutPolicy​::​template mapping<Oth-
    erExtents>&>
    is true, and
  • is_constructible_v<accessor_type, const OtherAccessor&> is true.
Mandates:
  • is_constructible_v<data_handle_type, const OtherAccessor​::​data_handle_type&> is
    true, and
  • is_constructible_v<extents_type, OtherExtents> is true.
Preconditions:
  • For each rank index r of extents_type, static_extent(r) == dynamic_extent || static_extent(r) == other.extent(r) is true.
  • [0, map_.required_span_size()) is an accessible range of ptr_ and acc_ for values of ptr_, map_, and acc_ after the invocation of this constructor.
Effects:
  • Direct-non-list-initializes ptr_ with other.ptr_,
  • direct-non-list-initializes map_ with other.map_, and
  • direct-non-list-initializes acc_ with other.acc_.
Remarks: The expression inside explicit is equivalent to: !is_convertible_v<const OtherLayoutPolicy::template mapping<OtherExtents>&, mapping_type> || !is_convertible_v<const OtherAccessor&, accessor_type>

24.7.3.6.3 Members [mdspan.mdspan.members]

template<class... OtherIndexTypes> constexpr reference operator[](OtherIndexTypes... indices) const;
Constraints:
  • (is_convertible_v<OtherIndexTypes, index_type> && ...) is true,
  • (is_nothrow_constructible_v<index_type, OtherIndexTypes> && ...) is true, and
  • sizeof...(OtherIndexTypes) == rank() is true.
Let I be extents_type​::​index-cast(std​::​move(indices)).
Preconditions: I is a multidimensional index in extents().
[Note 1: 
This implies that map_(I) < map_.required_span_size() is true.
— end note]
Effects: Equivalent to: return acc_.access(ptr_, map_(static_cast<index_type>(std::move(indices))...));
template<class OtherIndexType> constexpr reference operator[](span<OtherIndexType, rank()> indices) const; template<class OtherIndexType> constexpr reference operator[](const array<OtherIndexType, rank()>& indices) const;
Constraints:
  • is_convertible_v<const OtherIndexType&, index_type> is true, and
  • is_nothrow_constructible_v<index_type, const OtherIndexType&> is true.
Effects: Let P be a parameter pack such that is_same_v<make_index_sequence<rank()>, index_sequence<P...>> is true.
Equivalent to: return operator[](extents_type::index-cast(as_const(indices[P]))...);
constexpr size_type size() const noexcept;
Preconditions: The size of the multidimensional index space extents() is representable as a value of type size_type ([basic.fundamental]).
Returns: extents().fwd-prod-of-extents(rank()).
[[nodiscard]] constexpr bool empty() const noexcept;
Returns: true if the size of the multidimensional index space extents() is 0, otherwise false.
friend constexpr void swap(mdspan& x, mdspan& y) noexcept;
Effects: Equivalent to: swap(x.ptr_, y.ptr_); swap(x.map_, y.map_); swap(x.acc_, y.acc_);