[mdspan.layout.stride] - C++20 → C++23

Files changed (1) hide show

tmp/tmpa6ea6qiq/{from.md → to.md} +273 -0

tmp/tmpa6ea6qiq/{from.md → to.md} RENAMED Viewed

	@@ -0,0 +1,273 @@

+##### Class template `layout_stride::mapping` <a id="mdspan.layout.stride">[[mdspan.layout.stride]]</a>
+###### Overview <a id="mdspan.layout.stride.overview">[[mdspan.layout.stride.overview]]</a>
+`layout_stride` provides a layout mapping where the strides are
+user-defined.
+``` cpp
+namespace std {
+  template<class Extents>
+  class 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 only
+  public:
+    // [mdspan.layout.stride.cons], constructors
+    constexpr mapping() noexcept;
+    constexpr mapping(const mapping&) noexcept = default;
+    template<class OtherIndexType>
+      constexpr mapping(const extents_type&, span<OtherIndexType, rank_>) noexcept;
+    template<class OtherIndexType>
+      constexpr mapping(const extents_type&, const array<OtherIndexType, rank_>&) noexcept;
+    template<class StridedLayoutMapping>
+      constexpr explicit(see below) mapping(const StridedLayoutMapping&) noexcept;
+    constexpr mapping& operator=(const mapping&) noexcept = default;
+    // [mdspan.layout.stride.obs], observers
+    constexpr 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]; }
+    template<class OtherMapping>
+      friend constexpr bool operator==(const mapping&, const OtherMapping&) noexcept;
+  private:
+    extents_type extents_{};                    // exposition only
+    array<index_type, rank_> strides_{};        // exposition only
+  };
+}
+```
+If `Extents` is not a specialization of `extents`, then the program is
+ill-formed.
+`layout_stride::mapping<E>` is a trivially copyable type that models
+`regular` for each `E`.
+*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`.
+###### Exposition-only helpers <a id="mdspan.layout.stride.expo">[[mdspan.layout.stride.expo]]</a>
+Let `REQUIRED-SPAN-SIZE(e, strides)` be:
+- `1`, if `e.rank() == 0` is `true`,
+- otherwise `0`, if the size of the multidimensional index space `e` is
+  0,
+- otherwise `1` plus the sum of products of `(e.extent(r) - 1)` and
+  `strides[r]` for all r in the range [0, `e.rank()`).
+Let `OFFSET(m)` be:
+- `m()`, if `e.rank() == 0` is `true`,
+- otherwise `0`, if the size of the multidimensional index space `e` is
+  0,
+- otherwise `m(z...)` for a pack of integers `z` that is a
+  multidimensional index in `m.extents()` and each element of `z` equals
+  0.
+Let *`is-extents`* be the exposition-only variable template defined as
+follows:
+``` cpp
+template<class T>
+  constexpr bool is-extents = false;                              // exposition only
+template<class IndexType, size_t... Args>
+  constexpr bool is-extents<extents<IndexType, Args...>> = true;  // exposition only
+```
+Let `layout-mapping-alike` be the exposition-only concept defined as
+follows:
+``` cpp
+template<class M>
+concept layout-mapping-alike = requires {                         // exposition only
+  requires is-extents<typename M::extents_type>;
+  { M::is_always_strided() } -> same_as<bool>;
+  { M::is_always_exhaustive() } -> same_as<bool>;
+  { M::is_always_unique() } -> same_as<bool>;
+  bool_constant<M::is_always_strided()>::value;
+  bool_constant<M::is_always_exhaustive()>::value;
+  bool_constant<M::is_always_unique()>::value;
+};
+```
+[*Note 2*: This concept checks that the functions
+`M::is_always_strided()`, `M::is_always_exhaustive()`, and
+`M::is_always_unique()` exist, are constant expressions, and have a
+return type of `bool`. — *end note*]
+###### Constructors <a id="mdspan.layout.stride.cons">[[mdspan.layout.stride.cons]]</a>
+``` cpp
+constexpr mapping() noexcept;
+```
+*Preconditions:*
+`layout_right::mapping<extents_type>().required_span_size()` is
+representable as a value of type `index_type` [[basic.fundamental]].
+*Effects:* Direct-non-list-initializes *extents\_* with
+`extents_type()`, and for all d in the range \[`0`, *`rank_`*),
+direct-non-list-initializes *`strides_`*`[`d`]` with
+`layout_right::mapping<extents_type>().stride(`d`)`.
+``` cpp
+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;
+```
+*Constraints:*
+- `is_convertible_v<const OtherIndexType&, index_type>` is `true`, and
+- `is_nothrow_constructible_v<index_type, const OtherIndexType&>` is
+  `true`.
+*Preconditions:*
+- `s[`i`] > 0` is `true` for all i in the range [0, rank_).
+- *`REQUIRED-SPAN-SIZE`*`(e, s)` is representable as a value of type
+  `index_type` [[basic.fundamental]].
+- If *rank\_* is greater than 0, then there exists a permutation P of
+  the integers in the range [0, rank_), such that
+  `s[`pᵢ`] >= s[`pᵢ₋₁`] * e.extent(p`ᵢ₋₁`)` is `true` for all i in the
+  range [1, rank_), where pᵢ is the iᵗʰ element of P. \[*Note 3*: For
+  `layout_stride`, this condition is necessary and sufficient for
+  `is_unique()` to be `true`. — *end note*]
+*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`])`.
+``` cpp
+template<class StridedLayoutMapping>
+  constexpr explicit(see below)
+    mapping(const StridedLayoutMapping& other) noexcept;
+```
+*Constraints:*
+- `layout-mapping-alike<StridedLayoutMapping>` is satisfied.
+- `is_constructible_v<extents_type, typename StridedLayoutMapping::extents_type>`
+  is
+  `true`.
+- `StridedLayoutMapping::is_always_unique()` is `true`.
+- `StridedLayoutMapping::is_always_strided()` is `true`.
+*Preconditions:*
+- `StridedLayoutMapping` meets the layout mapping
+  requirements [[mdspan.layout.policy.reqmts]],
+- `other.stride(`r`) > 0` is `true` for every rank index r of
+  `extents()`,
+- `other.required_span_size()` is representable as a value of type
+  `index_type` [[basic.fundamental]], and
+- *`OFFSET`*`(other) == 0` is `true`.
+*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`)`.
+Remarks: The expression inside `explicit` is equivalent to:
+``` cpp
+!(is_convertible_v<typename StridedLayoutMapping::extents_type, extents_type> &&
+  (is-mapping-of<layout_left, LayoutStrideMapping> ||
+   is-mapping-of<layout_right, LayoutStrideMapping> ||
+   is-mapping-of<layout_stride, LayoutStrideMapping>))
+```
+###### Observers <a id="mdspan.layout.stride.obs">[[mdspan.layout.stride.obs]]</a>
+``` cpp
+constexpr index_type required_span_size() const noexcept;
+```
+*Returns:* *`REQUIRED-SPAN-SIZE`*`(extents(), `*`strides_`*`)`.
+``` cpp
+template<class... Indices>
+  constexpr index_type operator()(Indices... i) const noexcept;
+```
+*Constraints:*
+- `sizeof...(Indices) == `*`rank_`* is `true`,
+- `(is_convertible_v<Indices, index_type> && ...)` is `true`, and
+- `(is_nothrow_constructible_v<index_type, Indices> && ...)` is `true`.
+*Preconditions:* `extents_type::`*`index-cast`*`(i)` is a
+multidimensional index in *extents\_*[[mdspan.overview]].
+*Effects:* Let `P` be a parameter pack such that
+``` cpp
+is_same_v<index_sequence_for<Indices...>, index_sequence<P...>>
+```
+is `true`. Equivalent to:
+``` cpp
+return ((static_cast<index_type>(i) * stride(P)) + ... + 0);
+```
+``` cpp
+constexpr bool is_exhaustive() const noexcept;
+```
+*Returns:*
+- `true` if *rank\_* is 0.
+- Otherwise, `true` if there is a permutation P of the integers in the
+  range [0, rank_) such that `stride(`p₀`)` equals 1, and `stride(`pᵢ`)`
+  equals `stride(`pᵢ₋₁`) * extents().extent(`pᵢ₋₁`)` for i in the range
+  [1, rank_), where pᵢ is the iᵗʰ element of P.
+- Otherwise, `false`.
+``` cpp
+template<class OtherMapping>
+  friend constexpr bool operator==(const mapping& x, const OtherMapping& y) noexcept;
+```
+*Constraints:*
+- `layout-mapping-alike<OtherMapping>` is satisfied.
+- *`rank_`*` == OtherMapping::extents_type::rank()` is `true`.
+- `OtherMapping::is_always_strided()` is `true`.
+*Preconditions:* `OtherMapping` meets the layout mapping
+requirements [[mdspan.layout.policy.reqmts]].
+*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`.

Diff to HTML by rtfpessoa