[mdspan.layout.rightpad] - C++23 → Trunk

Files changed (1) hide show

tmp/tmpfnro412u/{from.md → to.md} +449 -0

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

	@@ -0,0 +1,449 @@

+##### Class template `layout_right_padded::mapping` <a id="mdspan.layout.rightpad">[[mdspan.layout.rightpad]]</a>
+###### Overview <a id="mdspan.layout.rightpad.overview">[[mdspan.layout.rightpad.overview]]</a>
+`layout_right_padded` provides a layout mapping that behaves like
+`layout_right::mapping`, except that the padding stride
+`stride(extents_type::rank() - 2)` can be greater than or equal to
+`extents_type::extent(extents_type::rank() - 1)`.
+``` cpp
+namespace std {
+  template<size_t PaddingValue>
+  template<class Extents>
+  class layout_right_padded<PaddingValue>::mapping {
+  public:
+    static constexpr size_t padding_value = PaddingValue;
+    using extents_type = Extents;
+    using index_type = extents_type::index_type;
+    using size_type = extents_type::size_type;
+    using rank_type = extents_type::rank_type;
+    using layout_type = layout_right_padded<PaddingValue>;
+  private:
+    static constexpr size_t rank_ = extents_type::rank();    // exposition only
+    static constexpr size_t last-static-extent =             // exposition only
+      extents_type::static_extent(rank_ - 1);
+    // [mdspan.layout.rightpad.expo], exposition-only members
+    static constexpr size_t static-padding-stride = see below; // exposition only
+  public:
+    // [mdspan.layout.rightpad.cons], constructors
+    constexpr mapping() noexcept : mapping(extents_type{}) {}
+    constexpr mapping(const mapping&) noexcept = default;
+    constexpr mapping(const extents_type&);
+    template<class OtherIndexType>
+      constexpr mapping(const extents_type&, OtherIndexType);
+    template<class OtherExtents>
+      constexpr explicit(!is_convertible_v<OtherExtents, extents_type>)
+        mapping(const layout_right::mapping<OtherExtents>&);
+    template<class OtherExtents>
+      constexpr explicit(rank_ > 0)
+        mapping(const layout_stride::mapping<OtherExtents>&);
+    template<class LayoutRightPaddedMapping>
+      constexpr explicit(see below)
+        mapping(const LayoutRightPaddedMapping&);
+    template<class LayoutLeftPaddedMapping>
+      constexpr explicit(see below)
+        mapping(const LayoutLeftPaddedMapping&) noexcept;
+    constexpr mapping& operator=(const mapping&) noexcept = default;
+    // [mdspan.layout.rightpad.obs], observers
+    constexpr const extents_type& extents() const noexcept { return extents_; }
+    constexpr array<index_type, rank_> strides() const noexcept;
+    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;
+    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) const noexcept;
+    template<class LayoutRightPaddedMapping>
+      friend constexpr bool operator==(const mapping&, const LayoutRightPaddedMapping&) noexcept;
+  private:
+    // [mdspan.layout.rightpad.expo], exposition-only members
+    index_type stride-rm2 = static-padding-stride;                         // exposition only
+    extents_type extents_{};                                               // exposition only
+    // [mdspan.sub.map], submdspan mapping specialization
+    template<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...);
+    }
+  };
+}
+```
+If `Extents` is not a specialization of `extents`, then the program is
+ill-formed.
+`layout_right_padded::mapping<E>` is a trivially copyable type that
+models `regular` for each `E`.
+Throughout [[mdspan.layout.rightpad]], let `P_rank` be the following
+size *`rank_`* parameter pack of `size_`t values:
+- the empty parameter pack, if *`rank_`* equals zero;
+- otherwise, `0zu`, if *`rank_`* equals one;
+- otherwise, the parameter pack `0zu`, `1zu`, …, `rank_- 1`.
+*Mandates:*
+- If `rank_dynamic() == 0` is `true`, then the size of the
+  multidimensional index space `Extents()` is representable as a value
+  of type `index_type`.
+- `padding_value` is representable as a value of type `index_type`.
+- If
+  - *`rank_`* is greater than one,
+  - `padding_value` does not equal `dynamic_extent`, and
+  - *`last-static-extent`* does not equal `dynamic_extent`,
+  then `LEAST-MULTIPLE-AT-LEAST(padding_value, last-static-extent)` is
+  representable as a value of type `size_t`, and is representable as a
+  value of type `index_type`.
+- If
+  - *`rank_`* is greater than one,
+  - `padding_value` does not equal `dynamic_extent`, and
+  - `extents_type::static_extent(k)` does not equal `dynamic_extent` for
+    all k in the range \[`0`, *`rank_`*),
+  then the product of
+  `LEAST-MULTIPLE-AT-LEAST(padding_value, ext.static_extent(rank_ - 1))`
+  and all values `ext.static_extent(k)` with k in the range of \[`0`,
+  *`rank_`*` - 1`) is representable as a value of type `size_t`, and is
+  representable as a value of type `index_type`.
+###### Exposition-only members <a id="mdspan.layout.rightpad.expo">[[mdspan.layout.rightpad.expo]]</a>
+``` cpp
+static constexpr size_t static-padding-stride = see below;
+```
+The value is
+- `0`, if *rank\_* equals zero or one;
+- otherwise, `dynamic_extent`, if `padding_value` or
+  *last-static-extent* equals `dynamic_extent`;
+- otherwise, the `size_t` value which is
+  *`LEAST-MULTIPLE-AT-LEAST`*`(padding_value, `*`last-static-extent`*`)`.
+``` cpp
+index_type stride-rm2 = static-padding-stride;
+```
+*Recommended practice:* Implementations should not store this value if
+*static-padding-stride* is not `dynamic_extent`.
+[*Note 11*: Using `extents<index_type, `*`static-padding-stride`*`>`
+instead of `index_type` as the type of *stride-rm2* would achieve
+this. — *end note*]
+###### Constructors <a id="mdspan.layout.rightpad.cons">[[mdspan.layout.rightpad.cons]]</a>
+``` cpp
+constexpr mapping(const extents_type& ext);
+```
+*Preconditions:*
+- The size of the multidimensional index space `ext` is representable as
+  a value of type `index_type`.
+- If *rank\_* is greater than one and `padding_value` does not equal
+  `dynamic_extent`, then
+  *`LEAST-MULTIPLE-AT-LEAST`*`(padding_value, ext.extent(`*`rank_`*` - 1))`
+  is representable as a value of type *index_type*.
+- If *rank\_* is greater than one and `padding_value` does not equal
+  `dynamic_extent`, then the product of
+  *`LEAST-MULTIPLE-AT-LEAST`*`(padding_value, ext.extent(`*`rank_`*` - 1))`
+  and all values `ext.extent(`k`)` with k in the range of \[`0`,
+  *`rank_`*` - 1`) is representable as a value of type `index_type`.
+*Effects:*
+- Direct-non-list-initializes *extents\_* with `ext`; and
+- if *rank\_* is greater than one, direct-non-list-initializes
+  *stride-rm2*
+  - with `ext.extent(`*`rank_`*` - 1)` if `padding_value` is
+    `dynamic_extent`,
+  - otherwise with
+    *`LEAST-MULTIPLE-AT-LEAST`*`(padding_value, ext.extent(`*`rank_`*` - 1))`.
+``` cpp
+template<class OtherIndexType>
+constexpr mapping(const extents_type& ext, OtherIndexType pad);
+```
+*Constraints:*
+- `is_convertible_v<OtherIndexType, index_type>` is `true`.
+- `is_nothrow_constructible_v<index_type, OtherIndexType>` is `true`.
+*Preconditions:*
+- `pad` is representable as a value of type `index_type`.
+- `extents_type::`*`index-cast`*`(pad)` is greater than zero.
+- If *rank\_* is greater than one, then
+  *`LEAST-MULTIPLE-AT-LEAST`*`(pad, ext.extent(`*`rank_`*` - 1))` is
+  representable as a value of type `index_type`.
+- If *rank\_* is greater than one, then the product of
+  *`LEAST-MULTIPLE-AT-LEAST`*`(pad, ext.extent(`*`rank_`*` - 1))` and
+  all values `ext.extent(`k`)` with k in the range of \[`0`,
+  *`rank_`*` - 1`) is representable as a value of type `index_type`.
+- If `padding_value` is not equal to `dynamic_extent`, `padding_value`
+  equals `extents_type::`*`index-cast`*`(pad)`.
+*Effects:* Direct-non-list-initializes *extents\_* with `ext`, and if
+*rank\_* is greater than one, direct-non-list-initializes *stride-rm2*
+with *`LEAST-MULTIPLE-AT-LEAST`*`(pad, ext.extent(`*`rank_`*` - 1))`.
+``` cpp
+template<class OtherExtents>
+  constexpr explicit(!is_convertible_v<OtherExtents, extents_type>)
+    mapping(const layout_right::mapping<OtherExtents>& other);
+```
+*Constraints:* `is_constructible_v<extents_type, OtherExtents>` is
+`true`.
+*Mandates:* If `OtherExtents::rank()` is greater than 1, then
+``` cpp
+(static-padding-stride == dynamic_extent) ||
+(OtherExtents::static_extent(rank_ - 1) == dynamic_extent) ||
+(static-padding-stride == OtherExtents::static_extent(rank_ - 1))
+```
+is `true`.
+*Preconditions:*
+- If *`rank_`*` > 1` is `true` and `padding_value == dynamic_extent` is
+  `false`, then `other.stride( `*`rank_`*` - 2)` equals
+  ``` cpp
+  LEAST-MULTIPLE-AT-LEAST(padding_value,
+                          extents_type::index-cast(other.extents().extent(rank_ - 1)))
+  ```
+  and
+- `other.required_span_size()` is representable as a value of type
+  `index_type`.
+*Effects:* Equivalent to `mapping(other.extents())`.
+``` cpp
+template<class OtherExtents>
+  constexpr explicit(rank_ > 0)
+    mapping(const layout_stride::mapping<OtherExtents>& other);
+```
+*Constraints:* `is_constructible_v<extents_type, OtherExtents>` is
+`true`.
+*Preconditions:*
+- If *rank\_* is greater than 1 and `padding_value` does not equal
+  `dynamic_extent`, then `other.stride(`*`rank_`*` - 2)` equals
+  ``` cpp
+  LEAST-MULTIPLE-AT-LEAST(padding_value,
+                          extents_type::index-cast(other.extents().extent(rank_ - 1)))
+  ```
+- If *rank\_* is greater than 0, then other.stride(*rank\_* - 1) equals
+  1.
+- If *rank\_* is greater than 2, then for all r in the range \[`0`,
+  *`rank_`*` - 2`), `other.stride(`r`)` equals
+  ``` cpp
+  (other.extents().rev-prod-of-extents(r) / other.extents().extent(rank_ - 1)) *
+    other.stride(rank_ - 2)
+  ```
+- `other.required_span_size()` is representable as a value of type
+  `index_type`.
+*Effects:*
+- Direct-non-list-initializes *extents\_* with `other.extents()`; and
+- if *rank\_* is greater than one, direct-non-list-initializes
+  *stride-rm2* with `other.stride(`*`rank_`*` - 2)`.
+``` cpp
+template<class LayoutRightPaddedMapping>
+  constexpr explicit(see below)
+    mapping(const LayoutRightPaddedMapping& other);
+```
+*Constraints:*
+- *`is-layout-right-padded-mapping-of`*`<LayoutRightPaddedMapping>` is
+  `true`.
+- `is_constructible_v<extents_type, typename LayoutRightPaddedMapping::extents_- type>`
+  is `true`.
+*Mandates:* If *rank\_* is greater than 1, then
+``` cpp
+padding_value == dynamic_extent ||
+LayoutRightPaddedMapping::padding_value == dynamic_extent ||
+padding_value == LayoutRightPaddedMapping::padding_value
+```
+is `true`.
+*Preconditions:*
+- If *rank\_* is greater than 1 and `padding_value` does not equal
+  `dynamic_extent`, then `other.stride(`*`rank_`*` - 2)` equals
+  ``` cpp
+  LEAST-MULTIPLE-AT-LEAST(padding_value,
+                          extents_type::index-cast(other.extent(rank_ - 1)))
+  ```
+- `other.required_span_size()` is representable as a value of type
+  `index_type`.
+*Effects:*
+- Direct-non-list-initializes *extents\_* with `other.extents()`; and
+- if *rank\_* is greater than one, direct-non-list-initializes
+  *stride-rm2* with `other.stride(rank_ - 2)`.
+*Remarks:* The expression inside `explicit` is equivalent to:
+``` cpp
+rank_ > 1 &&
+(padding_value != dynamic_extent ||
+ LayoutRightPaddedMapping::padding_value == dynamic_extent)
+```
+``` cpp
+template<class LayoutLeftPaddedMapping>
+  constexpr explicit(see below)
+    mapping(const LayoutLeftPaddedMapping& other) noexcept;
+```
+*Constraints:*
+- *`is-layout-left-padded-mapping-of`*`<LayoutLeftPaddedMapping>` is
+  `true` or *`is-mapping-of`*`<layout_left, LayoutLeftPaddedMapping>` is
+  `true`.
+- *rank\_* equals zero or one.
+- `is_constructible_v<extents_type, typename LayoutLeftPaddedMapping::extents_type>`
+  is `true`.
+*Preconditions:* `other.required_span_size()` is representable as a
+value of type `index_type`.
+*Effects:* Direct-non-list-initializes *extents\_* with
+`other.extents()`.
+*Remarks:* The expression inside `explicit` is equivalent to:
+``` cpp
+!is_convertible_v<typename LayoutLeftPaddedMapping::extents_type, extents_type>
+```
+[*Note 12*: Neither the input mapping nor the mapping to be constructed
+uses the padding stride in the rank-0 or rank-1 case, so the padding
+stride affects neither the constraints nor the
+preconditions. — *end note*]
+###### Observers <a id="mdspan.layout.rightpad.obs">[[mdspan.layout.rightpad.obs]]</a>
+``` cpp
+constexpr array<index_type, rank_> strides() const noexcept;
+```
+*Returns:* `array<index_type, `*`rank_`*`>(``stride(P_rank)...``)`.
+``` cpp
+constexpr index_type required_span_size() const noexcept;
+```
+*Returns:* `0` if the multidimensional index space *extents\_* is empty,
+otherwise
+`(*this)(`*`extents_`*`.extent(P_rank) - index_type(1)...) + 1`.
+``` cpp
+template<class... Indices>
+constexpr size_t operator()(Indices... idxs) const noexcept;
+```
+*Constraints:*
+- `sizeof...(Indices) == `*`rank_`* is `true`.
+- `(is_convertible_v<Indices, index_type> && ...)` is `true`.
+- `(is_nothrow_constructible_v<index_type, Indices> && ...)` is `true`.
+*Preconditions:* `extents_type::`*`index-cast`*`(idxs)` is a
+multidimensional index in `extents()` [[mdspan.overview]].
+*Returns:*
+`((static_cast<index_type>(idxs) * stride(P_rank)) + ... + 0)`.
+``` cpp
+static constexpr bool is_always_exhaustive() noexcept;
+```
+*Returns:*
+- If *rank\_* equals zero or one, then `true`;
+- otherwise, if neither *static-padding-stride* nor *last-static-extent*
+  equal `dynamic_extent`, then
+  *`static-padding-stride`*` == `*`last-static-extent`*;
+- otherwise, `false`.
+``` cpp
+constexpr bool is_exhaustive() const noexcept;
+```
+*Returns:* `true` if *rank\_* equals zero or one; otherwise,
+``` cpp
+extents_.extent(rank_ - 1) == stride(rank_ - 2)
+```
+``` cpp
+constexpr index_type stride(rank_type r) const noexcept;
+```
+*Preconditions:* `r` is smaller than *rank\_*.
+*Returns:*
+- If `r` equals *`rank_`*` - 1`: `1`;
+- otherwise, if `r` equals *`rank_`*` - 2`: *stride-rm2*;
+- otherwise, the product of *stride-rm2* and all values
+  `extents_.extent(`k`)` with k in the range of \[`r + 1`,
+  *`rank_`*` - 1`).
+``` cpp
+template<class LayoutRightPaddedMapping>
+  friend constexpr bool operator==(const mapping& x, const LayoutRightPaddedMapping& y) noexcept;
+```
+*Constraints:*
+- *`is-layout-right-padded-mapping-of`*`<LayoutRightPaddedMapping>` is
+  `true`.
+- `LayoutRightPaddedMapping::extents_type::rank() == `*`rank_`* is
+  `true`.
+*Returns:* `true` if `x.extents() == y.extents()` is `true` and
+*`rank_`*` < 2 || x.stride(`*`rank_`*` - 2) == y.stride(`*`rank_`*` - 2)`
+is `true`. Otherwise, `false`.

Diff to HTML by rtfpessoa