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

Files changed (1) hide show

tmp/tmp7u66q1mx/{from.md → to.md} +439 -0

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

	@@ -0,0 +1,439 @@

+##### Class template `layout_left_padded::mapping` <a id="mdspan.layout.leftpad">[[mdspan.layout.leftpad]]</a>
+###### Overview <a id="mdspan.layout.leftpad.overview">[[mdspan.layout.leftpad.overview]]</a>
+`layout_left_padded` provides a layout mapping that behaves like
+`layout_left::mapping`, except that the padding stride `stride(1)` can
+be greater than or equal to `extent(0)`.
+``` cpp
+namespace std {
+  template<size_t PaddingValue>
+  template<class Extents>
+  class layout_left_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_left_padded<PaddingValue>;
+  private:
+    static constexpr size_t rank_ = extents_type::rank();         // exposition only
+    static constexpr size_t first-static-extent =                 // exposition only
+      extents_type::static_extent(0);
+    // [mdspan.layout.leftpad.expo], exposition-only members
+    static constexpr size_t static-padding-stride = see below;  // exposition only
+  public:
+    // [mdspan.layout.leftpad.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_left::mapping<OtherExtents>&);
+    template<class OtherExtents>
+      constexpr explicit(extents_type::rank() > 0)
+        mapping(const layout_stride::mapping<OtherExtents>&);
+    template<class LayoutLeftPaddedMapping>
+      constexpr explicit(see below)
+        mapping(const LayoutLeftPaddedMapping&);
+    template<class LayoutRightPaddedMapping>
+      constexpr explicit(see below)
+        mapping(const LayoutRightPaddedMapping&) noexcept;
+    constexpr mapping& operator=(const mapping&) noexcept = default;
+    // [mdspan.layout.leftpad.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 LayoutLeftPaddedMapping>
+      friend constexpr bool operator==(const mapping&, const LayoutLeftPaddedMapping&) noexcept;
+  private:
+    // [mdspan.layout.leftpad.expo], exposition-only members
+    index_type stride-1 = 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_left_padded::mapping<E>` is a trivially copyable type that
+models `regular` for each `E`.
+Throughout [[mdspan.layout.leftpad]], 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
+  - *`first-static-extent`* does not equal `dynamic_extent`,
+  then `LEAST-MULTIPLE-AT-LEAST(padding_value, first-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`, `extents_type::rank()`),
+  then the product of
+  `LEAST-MULTIPLE-AT-LEAST(padding_value, ext.static_extent(0))` and all
+  values `ext.static_extent(k)` with k in the range of \[`1`, *`rank_`*)
+  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.leftpad.expo">[[mdspan.layout.leftpad.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
+  *first-static-extent* equals `dynamic_extent`;
+- otherwise, the `size_t` value which is
+  *`LEAST-MULTIPLE-AT-LEAST`*`(padding_value, `*`first-static-extent`*`)`.
+``` cpp
+index_type stride-1 = static-padding-stride;
+```
+*Recommended practice:* Implementations should not store this value if
+*static-padding-stride* is not `dynamic_extent`.
+[*Note 9*: Using `extents<index_type, `*`static-padding-stride`*`>`
+instead of `index_type` as the type of *stride-1* would achieve
+this. — *end note*]
+###### Constructors <a id="mdspan.layout.leftpad.cons">[[mdspan.layout.leftpad.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(0))` 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(0))` and all
+  values `ext.extent(`k`)` with k in the range of \[`1`, *`rank_`*) 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-1*
+  - with `ext.extent(0)` if padding_value is `dynamic_extent`,
+  - otherwise with
+    *`LEAST-MULTIPLE-AT-LEAST`*`(padding_value, ext.extent(0))`.
+``` 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(0))` 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(0))` and all values
+  `ext.extent(`k`)` with k in the range of \[`1`, *`rank_`*) 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-1*
+with *`LEAST-MULTIPLE-AT-LEAST`*`(pad, ext.extent(0))`.
+``` cpp
+template<class OtherExtents>
+  constexpr explicit(!is_convertible_v<OtherExtents, extents_type>)
+    mapping(const layout_left::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(0) == dynamic_extent) ||
+(static-padding-stride == OtherExtents::static_extent(0))
+```
+is `true`.
+*Preconditions:*
+- If `extents_type::rank() > 1` is `true` and `padding_value` ==
+  `dynamic_extent` is `false`, then `other.stride(1)` equals
+  ``` cpp
+  LEAST-MULTIPLE-AT-LEAST(padding_value,
+                          extents_type::index-cast(other.extents().extent(0)))
+  ```
+  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(1)` equals
+  ``` cpp
+  LEAST-MULTIPLE-AT-LEAST(padding_value,
+                          extents_type::index-cast(other.extents().extent(0)))
+  ```
+- If *rank\_* is greater than 0, then `other.stride(0)` equals 1.
+- If *rank\_* is greater than 2, then for all r in the range \[`2`,
+  *`rank_`*), `other.stride(r)` equals
+  ``` cpp
+  (other.extents().fwd-prod-of-extents(r) / other.extents().extent(0)) * other.stride(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-1* with `other.stride(1)`.
+``` cpp
+template<class LayoutLeftPaddedMapping>
+  constexpr explicit(see below)
+    mapping(const LayoutLeftPaddedMapping& other);
+```
+*Constraints:*
+- *`is-layout-left-padded-mapping-of`*`<LayoutLeftPaddedMapping>` is
+  `true`.
+- `is_constructible_v<extents_type, typename LayoutLeftPaddedMapping::extents_type>`
+  is `true`.
+*Mandates:* If *rank\_* is greater than 1, then
+``` cpp
+padding_value == dynamic_extent ||
+LayoutLeftPaddedMapping::padding_value == dynamic_extent ||
+padding_value == LayoutLeftPaddedMapping::padding_value
+```
+is `true`.
+*Preconditions:*
+- If *rank\_* is greater than 1 and `padding_value` does not equal
+  `dynamic_extent`, then `other.stride(1)` equals
+  ``` cpp
+  LEAST-MULTIPLE-AT-LEAST(padding_value,
+                          extents_type::index-cast(other.extent(0)))
+  ```
+- `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-1* with `other.stride(1)`.
+*Remarks:* The expression inside `explicit` is equivalent to:
+``` cpp
+rank_> 1 &&
+(padding_value != dynamic_extent ||
+ LayoutLeftPaddedMapping::padding_value == dynamic_extent)
+```
+``` cpp
+template<class LayoutRightPaddedMapping>
+  constexpr explicit(see below)
+    mapping(const LayoutRightPaddedMapping& other) noexcept;
+```
+*Constraints:*
+- *`is-layout-right-padded-mapping-of`*`<LayoutRightPaddedMapping>` is
+  `true` or *`is-mapping-of`*`<layout_right, LayoutRightPaddedMapping>`
+  is `true`.
+- *rank\_* equals zero or one.
+- `is_constructible_v<extents_type, typename LayoutRightPaddedMapping::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 LayoutRightPaddedMapping::extents_type, extents_type>
+```
+[*Note 10*: 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 does not affect either the constraints or the
+preconditions. — *end note*]
+###### Observers <a id="mdspan.layout.leftpad.obs">[[mdspan.layout.leftpad.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
+  *first-static-extent* equal `dynamic_extent`, then
+  *`static-padding-stride`*` == `*`first-static-extent`*;
+- otherwise, `false`.
+``` cpp
+constexpr bool is_exhaustive() const noexcept;
+```
+*Returns:* `true` if *rank\_* equals zero or one; otherwise,
+`extents_.extent(0) == stride(1)`.
+``` cpp
+constexpr index_type stride(rank_type r) const noexcept;
+```
+*Preconditions:* `r` is smaller than *rank\_*.
+*Returns:*
+- If `r` equals zero: 1;
+- otherwise, if `r` equals one: *stride-1*;
+- otherwise, the product of *stride-1* and all values
+  `extents_.extent(`k`)` with k in the range \[`1`, `r`).
+``` cpp
+template<class LayoutLeftPaddedMapping>
+  friend constexpr bool operator==(const mapping& x, const LayoutLeftPaddedMapping& y) noexcept;
+```
+*Constraints:*
+- *`is-layout-left-padded-mapping-of`*`<LayoutLeftPaddedMapping>` is
+  `true`.
+- `LayoutLeftPaddedMapping::extents_type::rank() == rank_` is `true`.
+*Returns:* `true` if `x.extents() == y.extents()` is `true` and
+*`rank_`*` < 2 || x.stride(1) == y. stride(1)` is `true`. Otherwise,
+`false`.

Diff to HTML by rtfpessoa