[mdspan.accessor] - C++23 → Trunk

Files changed (1) hide show

tmp/tmpdj7oaaex/{from.md → to.md} +146 -1

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

@@ -8,11 +8,11 @@ of such objects and an index.
 A range of indices [0, N) is an *accessible range* of a given data
 handle and an accessor if, for each i in the range, the accessor
 policy’s `access` function produces a valid reference to an object.
-In subclause [[mdspan.accessor.reqmts]],
 - `A` denotes an accessor policy.
 - `a` denotes a value of type `A` or `const A`.
 - `p` denotes a value of type `A::data_handle_type` or
   `const A::data_handle_type`. \[*Note 1*: The type
@@ -152,5 +152,150 @@ constexpr reference access(data_handle_type p, size_t i) const noexcept;
 constexpr data_handle_type offset(data_handle_type p, size_t i) const noexcept;
 ```
 *Effects:* Equivalent to: `return p + i;`

 A range of indices [0, N) is an *accessible range* of a given data
 handle and an accessor if, for each i in the range, the accessor
 policy’s `access` function produces a valid reference to an object.
+In [[mdspan.accessor.reqmts]],
 - `A` denotes an accessor policy.
 - `a` denotes a value of type `A` or `const A`.
 - `p` denotes a value of type `A::data_handle_type` or
   `const A::data_handle_type`. \[*Note 1*: The type
 constexpr data_handle_type offset(data_handle_type p, size_t i) const noexcept;
 ```
 *Effects:* Equivalent to: `return p + i;`
+##### Class template `aligned_accessor` <a id="mdspan.accessor.aligned">[[mdspan.accessor.aligned]]</a>
+###### Overview <a id="mdspan.accessor.aligned.overview">[[mdspan.accessor.aligned.overview]]</a>
+``` cpp
+namespace std {
+  template<class ElementType, size_t ByteAlignment>
+  struct aligned_accessor {
+    using offset_policy = default_accessor<ElementType>;
+    using element_type = ElementType;
+    using reference = ElementType&;
+    using data_handle_type = ElementType*;
+    static constexpr size_t byte_alignment = ByteAlignment;
+    constexpr aligned_accessor() noexcept = default;
+    template<class OtherElementType, size_t OtherByteAlignment>
+      constexpr aligned_accessor(
+        aligned_accessor<OtherElementType, OtherByteAlignment>) noexcept;
+    template<class OtherElementType>
+      constexpr explicit aligned_accessor(default_accessor<OtherElementType>) noexcept;
+    template<class OtherElementType>
+      constexpr operator default_accessor<OtherElementType>() const noexcept;
+    constexpr reference access(data_handle_type p, size_t i) const noexcept;
+    constexpr typename offset_policy::data_handle_type offset(
+      data_handle_type p, size_t i) const noexcept;
+  };
+}
+```
+*Mandates:*
+- `byte_alignment` is a power of two, and
+- `byte_alignment >= alignof(ElementType)` is `true`.
+`aligned_accessor` meets the accessor policy requirements.
+`ElementType` is required to be a complete object type that is neither
+an abstract class type nor an array type.
+Each specialization of `aligned_accessor` is a trivially copyable type
+that models `semiregular`.
+\[`0`, n) is an accessible range for an object `p` of type
+`data_handle_type` and an object of type `aligned_accessor` if and only
+if
+- \[`p`, `p + `n) is a valid range, and,
+- if n is greater than zero, then
+  `is_sufficiently_aligned<byte_alignment>(p)` is `true`.
+[*Example 1*:
+The following function `compute` uses `is_sufficiently_aligned` to check
+whether a given `mdspan` with `default_accessor` has a data handle with
+sufficient alignment to be used with
+`aligned_accessor<float, 4 * sizeof(float)>`. If so, the function
+dispatches to a function `compute_using_fourfold_overalignment` that
+requires fourfold over-alignment of arrays, but can therefore use
+hardware-specific instructions, such as four-wide SIMD (Single
+Instruction Multiple Data) instructions. Otherwise, `compute` dispatches
+to a possibly less optimized function
+`compute_without_requiring_overalignment` that has no over-alignment
+requirement.
+``` cpp
+void compute_using_fourfold_overalignment(
+  mdspan<float, dims<1>, layout_right, aligned_accessor<float, 4 * alignof(float)>> x);
+void compute_without_requiring_overalignment(
+  mdspan<float, dims<1>, layout_right> x);
+void compute(mdspan<float, dims<1>> x) {
+  constexpr auto byte_alignment = 4 * sizeof(float);
+  auto accessor = aligned_accessor<float, byte_alignment>{};
+  auto x_handle = x.data_handle();
+  if (is_sufficiently_aligned<byte_alignment>(x_handle)) {
+    compute_using_fourfold_overalignment(mdspan{x_handle, x.mapping(), accessor});
+  } else {
+    compute_without_requiring_overalignment(x);
+  }
+}
+```
+— *end example*]
+###### Members <a id="mdspan.accessor.aligned.members">[[mdspan.accessor.aligned.members]]</a>
+``` cpp
+template<class OtherElementType, size_t OtherByteAlignment>
+  constexpr aligned_accessor(aligned_accessor<OtherElementType, OtherByteAlignment>) noexcept;
+```
+*Constraints:*
+- `is_convertible_v<OtherElementType(*)[], element_type(*)[]>` is
+  `true`.
+- `OtherByteAlignment >= byte_alignment` is `true`.
+*Effects:* None.
+``` cpp
+template<class OtherElementType>
+  constexpr explicit aligned_accessor(default_accessor<OtherElementType>) noexcept;
+```
+*Constraints:*
+`is_convertible_v<OtherElementType(*)[], element_type(*)[]>` is `true`.
+*Effects:* None.
+``` cpp
+constexpr reference access(data_handle_type p, size_t i) const noexcept;
+```
+*Preconditions:* \[`0`, `i + 1`) is an accessible range for `p` and
+`*this`.
+*Effects:* Equivalent to: `return assume_aligned<byte_alignment>(p)[i];`
+``` cpp
+template<class OtherElementType>
+  constexpr operator default_accessor<OtherElementType>() const noexcept;
+```
+*Constraints:*
+`is_convertible_v<element_type(*)[], OtherElementType(*)[]>` is `true`.
+*Effects:* Equivalent to: `return {};`
+``` cpp
+constexpr typename offset_policy::data_handle_type
+  offset(data_handle_type p, size_t i) const noexcept;
+```
+*Preconditions:* \[`0`, `i + 1`) is an accessible range for `p` and
+`*this`.
+*Effects:* Equivalent to:
+`return assume_aligned<byte_alignment>(p) + i;`

Diff to HTML by rtfpessoa