cppdraft_translate/cppdraft/mdspan/layout/stride.md

[mdspan.layout.stride]

23 Containers library [containers]

23.7 Views [views]

23.7.3 Multidimensional access [views.multidim]

23.7.3.4 Layout mapping [mdspan.layout]

23.7.3.4.7 Class template layout_stride​::​mapping [mdspan.layout.stride]

23.7.3.4.7.1 Overview [mdspan.layout.stride.overview]

1

#

layout_stride provides a layout mapping where the strides are user-defined.

namespace std {templateclass layout_stride::mapping {public:using extents_type = Extents; 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 layout_type = layout_stride; private:static constexpr rank_type rank_ = extents_type::rank(); // exposition onlypublic:// [mdspan.layout.stride.cons], constructorsconstexpr mapping() noexcept; constexpr mapping(const mapping&) noexcept = default; templateconstexpr mapping(const extents_type&, span<OtherIndexType, rank_>) noexcept; templateconstexpr mapping(const extents_type&, const array<OtherIndexType, rank_>&) noexcept; templateconstexpr explicit(see below) mapping(const StridedLayoutMapping&) noexcept; constexpr mapping& operator=(const mapping&) noexcept = default; // [mdspan.layout.stride.obs], observersconstexpr const extents_type& extents() const noexcept { return extents_; }constexpr array<index_type, rank_> strides() const noexcept { return strides_; }constexpr index_type required_span_size() const noexcept; template<class... Indices>constexpr index_type operator()(Indices...) const noexcept; static constexpr bool is_always_unique() noexcept { return true; }static constexpr bool is_always_exhaustive() noexcept { return false; }static constexpr bool is_always_strided() noexcept { return true; }static constexpr bool is_unique() noexcept { return true; }constexpr bool is_exhaustive() const noexcept; static constexpr bool is_strided() noexcept { return true; }constexpr index_type stride(rank_type i) const noexcept { return strides_[i]; }templatefriend constexpr bool operator==(const mapping&, const OtherMapping&) noexcept; private: extents_type extents_{}; // exposition only array<index_type, rank_> strides_{}; // exposition only// [mdspan.sub.map], submdspan mapping specializationtemplate<class... SliceSpecifiers>constexpr auto submdspan-mapping-impl(SliceSpecifiers...) const // exposition only-> see below; template<class... SliceSpecifiers>friend constexpr auto submdspan_mapping(const mapping& src, SliceSpecifiers... slices) {return src.submdspan-mapping-impl(slices...); }};}

2

#

If Extents is not a specialization of extents, then the program is ill-formed.

3

#

layout_stride​::​mapping is a trivially copyable type that models regular for each E.

4

#

Mandates: If Extents​::​rank_dynamic() == 0 is true, then the size of the multidimensional index space Extents() is representable as a value of type typename Extents​::​index_type.

23.7.3.4.7.2 Exposition-only helpers [mdspan.layout.stride.expo]

1

#

Let REQUIRED-SPAN-SIZE(e, strides) be:

• (1.1)

1, if e.rank() == 0 is true,

• (1.2)

otherwise 0, if the size of the multidimensional index space e is 0,

• (1.3)

otherwise 1 plus the sum of products of(e.extent(r) - 1) andextents_type::index-cast(strides[r]) for all r in the range [0, e.rank()).

2

#

Let OFFSET(m) be:

• (2.1)

m(), if e.rank() == 0 is true,

• (2.2)

otherwise 0, if the size of the multidimensional index space e is 0,

• (2.3)

otherwise m(z...) for a pack of integers z that is a multidimensional index in m.extents() and each element of z equals 0.

3

#

Let is-extents be the exposition-only variable template defined as follows:templateconstexpr bool is-extents = false; // exposition onlytemplate<class IndexType, size_t... Args>constexpr bool is-extents<extents<IndexType, Args...>> = true; // exposition only

4

#

Let layout-mapping-alike be the exposition-only concept defined as follows:templateconcept layout-mapping-alike = requires { // exposition onlyrequires is-extents; { M::is_always_strided() } -> same_as; { M::is_always_exhaustive() } -> same_as; { M::is_always_unique() } -> same_as; bool_constant<M::is_always_strided()>::value; bool_constant<M::is_always_exhaustive()>::value; bool_constant<M::is_always_unique()>::value;};

[Note 1:

This concept checks that the functionsM​::​is_always_strided(),M​::​is_always_exhaustive(), andM​::​is_always_unique() exist, are constant expressions, and have a return type of bool.

— end note]

23.7.3.4.7.3 Constructors [mdspan.layout.stride.cons]

🔗

constexpr mapping() noexcept;

1

#

Preconditions: layout_right​::​mapping<extents_type>().required_span_size() is representable as a value of type index_type ([basic.fundamental]).

2

#

Effects: Direct-non-list-initializes extents_ with extents_type(), and for all d in the range [0, rank_), direct-non-list-initializes strides_[d] withlayout_right​::​mapping<extents_type>().stride(d).

🔗

template<class OtherIndexType> constexpr mapping(const extents_type& e, span<OtherIndexType, rank_> s) noexcept; template<class OtherIndexType> constexpr mapping(const extents_type& e, const array<OtherIndexType, rank_>& s) noexcept;

3

#

Constraints:

• (3.1)

is_convertible_v<const OtherIndexType&, index_type> is true, and

• (3.2)

is_nothrow_constructible_v<index_type, const OtherIndexType&> is true.

4

#

Preconditions:

• (4.1)

  The result of converting s[i] to index_type is greater than 0 for all i in the range [0, rank_).

• (4.2)

  REQUIRED-SPAN-SIZE(e, s) is representable as a value of type index_type ([basic.fundamental]).

• (4.3)

  If rank_ is greater than 0, then there exists a permutation P of the integers in the range [0, rank_), such that s[pi] >= s[pi−1] * e.extent(pi−1) is true for all i in the range [1, rank_), where pi is the ith element of P. [Note 1: For layout_stride, this condition is necessary and sufficient for is_unique() to be true. — end note]

5

#

Effects: Direct-non-list-initializes extents_ with e, and for all d in the range [0, rank_), direct-non-list-initializes strides_[d] with as_const(s[d]).

🔗

template<class StridedLayoutMapping> constexpr explicit(see below) mapping(const StridedLayoutMapping& other) noexcept;

6

#

Constraints:

• (6.1)

  layout-mapping-alike is satisfied.

• (6.2)

  is_constructible_v<extents_type, typename StridedLayoutMapping​::​extents_type> is
  true.

• (6.3)

  StridedLayoutMapping​::​is_always_unique() is true.

• (6.4)

  StridedLayoutMapping​::​is_always_strided() is true.

7

#

Preconditions:

• (7.1)

StridedLayoutMapping meets the layout mapping requirements ([mdspan.layout.reqmts]),

• (7.2)

other.stride(r) > 0 is true for every rank index r of extents(),

• (7.3)

other.required_span_size() is representable as a value of type index_type ([basic.fundamental]), and

• (7.4)

OFFSET(other) == 0 is true.

8

#

Effects: Direct-non-list-initializes extents_ with other.extents(), and for all d in the range [0, rank_), direct-non-list-initializes strides_[d] with other.stride(d).

9

#

Remarks: The expression inside explicit is equivalent to:!(is_convertible_v<typename StridedLayoutMapping::extents_type, extents_type> &&(is-mapping-of<layout_left, StridedLayoutMapping> ||is-mapping-of<layout_right, StridedLayoutMapping> ||is-layout-left-padded-mapping-of ||is-layout-right-padded-mapping-of ||is-mapping-of<layout_stride, StridedLayoutMapping>))

23.7.3.4.7.4 Observers [mdspan.layout.stride.obs]

🔗

constexpr index_type required_span_size() const noexcept;

1

#

Returns: REQUIRED-SPAN-SIZE(extents(), strides_).

🔗

template<class... Indices> constexpr index_type operator()(Indices... i) const noexcept;

2

#

Constraints:

• (2.1)

sizeof...(Indices) == rank_ is true,

• (2.2)

(is_convertible_v<Indices, index_type> && ...) is true, and

• (2.3)

(is_nothrow_constructible_v<index_type, Indices> && ...) is true.

3

#

Preconditions: extents_type​::​index-cast(i) is a multidimensional index in extents_ ([mdspan.overview]).

4

#

Effects: Let P be a parameter pack such thatis_same_v<index_sequence_for<Indices...>, index_sequence<P...>> is true.

Equivalent to:return ((static_cast<index_type>(i) * stride(P)) + ... + 0);

🔗

constexpr bool is_exhaustive() const noexcept;

5

#

Returns:

• (5.1)

  true if rank_ is 0.

• (5.2)

  Otherwise, true if there is a permutation P of the integers in the range [0, rank_) such that stride(p0) equals 1, andstride(pi) equals stride(pi−1) * extents().extent(pi−1) for i in the range [1, rank_), where pi is the ith element of P.

• (5.3)

  Otherwise, false.

🔗

template<class OtherMapping> friend constexpr bool operator==(const mapping& x, const OtherMapping& y) noexcept;

6

#

Constraints:

• (6.1)

  layout-mapping-alike is satisfied.

• (6.2)

  rank_ == OtherMapping​::​extents_type​::​rank() is true.

• (6.3)

  OtherMapping​::​is_always_strided() is true.

7

#

Preconditions: OtherMapping meets the layout mapping requirements ([mdspan.layout.policy.reqmts]).

8

#

Returns: true if x.extents() == y.extents() is true,OFFSET(y) == 0 is true, and each of x.stride(r) == y.stride(r) is true for r in the range [0, x.extents().rank()).

Otherwise, false.