23 Containers library [containers]

23.7 Views [views]

23.7.3 Multidimensional access [views.multidim]

23.7.3.6 Class template mdspan [mdspan.mdspan]

23.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; 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, extents<size_t, maybe-static-ext<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:

(2.1)
ElementType is a complete object type that is neither an abstract class type nor an array type,
(2.2)
Extents is a specialization of extents, and
(2.3)
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

(4.1)
is_nothrow_move_constructible_v<MDS> is true,
(4.2)
is_nothrow_move_assignable_v<MDS> is true, and
(4.3)
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.

23.7.3.6.2 Constructors [mdspan.mdspan.cons]

🔗

constexpr mdspan();

Constraints:

(1.1)
rank_dynamic() > 0 is true.
(1.2)
is_default_constructible_v<data_handle_type> is true.
(1.3)
is_default_constructible_v<mapping_type> is true.
(1.4)
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:

(5.1)
(is_convertible_v<OtherIndexTypes, index_type> && ...) is true,
(5.2)
(is_nothrow_constructible<index_type, OtherIndexTypes> && ...) is true,
(5.3)
N == rank() || N == rank_dynamic() is true,
(5.4)
is_constructible_v<mapping_type, extents_type> is true, and
(5.5)
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:

(7.1)
Direct-non-list-initializes ptr_ with std::move(p),
(7.2)
direct-non-list-initializes map_ with extents_type(static_cast<index_type>(std::move(exts))...), and
(7.3)
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:

(8.1)
is_convertible_v<const OtherIndexType&, index_type> is true,
(8.2)
is_nothrow_constructible_v<index_type, const OtherIndexType&> is true,
(8.3)
N == rank() || N == rank_dynamic() is true,
(8.4)
is_constructible_v<mapping_type, extents_type> is true, and
(8.5)
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:

(10.1)
Direct-non-list-initializes ptr_ with std::move(p),
(10.2)
direct-non-list-initializes map_ with extents_type(exts), and
(10.3)
value-initializes acc_.

🔗

constexpr mdspan(data_handle_type p, const extents_type& ext);

Constraints:

(11.1)
is_constructible_v<mapping_type, const extents_type&> is true, and
(11.2)
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:

(13.1)
Direct-non-list-initializes ptr_ with std::move(p),
(13.2)
direct-non-list-initializes map_ with ext, and
(13.3)
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:

(16.1)
Direct-non-list-initializes ptr_ with std::move(p),
(16.2)
direct-non-list-initializes map_ with m, and
(16.3)
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:

(18.1)
Direct-non-list-initializes ptr_ with std::move(p),
(18.2)
direct-non-list-initializes map_ with m, and
(18.3)
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:

(19.1)
is_constructible_v<mapping_type, const OtherLayoutPolicy::template mapping<Oth-
erExtents>&> is true, and
(19.2)
is_constructible_v<accessor_type, const OtherAccessor&> is true.

Mandates:

(20.1)
is_constructible_v<data_handle_type, const OtherAccessor::data_handle_type&> is
true, and
(20.2)
is_constructible_v<extents_type, OtherExtents> is true.

Preconditions:

(21.1)
For each rank index r of extents_type, static_extent(r) == dynamic_extent || static_extent(r) == other.extent(r) is true.
(21.2)
[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:

(22.1)
Direct-non-list-initializes ptr_ with other.ptr_,
(22.2)
direct-non-list-initializes map_ with other.map_, and
(22.3)
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>

23.7.3.6.3 Members [mdspan.mdspan.members]

🔗

template<class... OtherIndexTypes>
  constexpr reference operator[](OtherIndexTypes... indices) const;

Constraints:

(1.1)
(is_convertible_v<OtherIndexTypes, index_type> && ...) is true,
(1.2)
(is_nothrow_constructible_v<index_type, OtherIndexTypes> && ...) is true, and
(1.3)
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:

(5.1)
is_convertible_v<const OtherIndexType&, index_type> is true, and
(5.2)
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()).

🔗

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_);