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

Files changed (1) hide show

tmp/tmpqlvqd31s/{from.md → to.md} +910 -0

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

	@@ -0,0 +1,910 @@

+#### `submdspan` <a id="mdspan.sub">[[mdspan.sub]]</a>
+##### Overview <a id="mdspan.sub.overview">[[mdspan.sub.overview]]</a>
+The `submdspan` facilities create a new `mdspan` viewing a subset of
+elements of an existing input `mdspan`. The subset viewed by the created
+`mdspan` is determined by the `SliceSpecifier` arguments.
+For each function defined in [[mdspan.sub]] that takes a parameter pack
+named `slices` as an argument:
+- let `index_type` be
+  - `M::index_type` if the function is a member of a class `M`,
+  - otherwise, `remove_reference_t<decltype(src)>::index_type` if the
+    function has a parameter named `src`,
+  - otherwise, the same type as the function’s template argument
+    `IndexType`;
+- let `rank` be the number of elements in `slices`;
+- let sₖ be the kᵗʰ element of `slices`;
+- let Sₖ be the type of sₖ; and
+- let `map-rank` be an `array<size_t, rank>` such that for each k in the
+  range \[`0`, `rank`), `map-rank[k]` equals:
+  - `dynamic_extent` if Sₖ models `convertible_to<index_type>`,
+  - otherwise, the number of types Sⱼ with j < k that do not model
+    `convertible_to<index_type>`.
+##### `strided_slice` <a id="mdspan.sub.strided.slice">[[mdspan.sub.strided.slice]]</a>
+`strided_slice` represents a set of `extent` regularly spaced integer
+indices. The indices start at `offset`, and increase by increments of
+`stride`.
+``` cpp
+namespace std {
+  template<class OffsetType, class ExtentType, class StrideType>
+  struct strided_slice {
+    using offset_type = OffsetType;
+    using extent_type = ExtentType;
+    using stride_type = StrideType;
+    [[no_unique_address]] offset_type offset{};
+    [[no_unique_address]] extent_type extent{};
+    [[no_unique_address]] stride_type stride{};
+  };
+}
+```
+`strided_slice` has the data members and special members specified
+above. It has no base classes or members other than those specified.
+*Mandates:* `OffsetType`, `ExtentType`, and `StrideType` are signed or
+unsigned integer types, or model `integral-constant-like`.
+[*Note 1*:
+`strided_slice{.offset = 1, .extent = 10, .stride = 3}`
+indicates the indices `1`, `4`, `7`, and `10`. Indices are selected from
+the half-open interval \[`1`, `1 + 10`).
+— *end note*]
+##### `submdspan_mapping_result` <a id="mdspan.sub.map.result">[[mdspan.sub.map.result]]</a>
+Specializations of `submdspan_mapping_result` are returned by overloads
+of `submdspan_mapping`.
+``` cpp
+namespace std {
+  template<class LayoutMapping>
+  struct submdspan_mapping_result {
+    [[no_unique_address]] LayoutMapping mapping = LayoutMapping();
+    size_t offset{};
+  };
+}
+```
+`submdspan_mapping_result` has the data members and special members
+specified above. It has no base classes or members other than those
+specified.
+`LayoutMapping` shall meet the layout mapping requirements
+[[mdspan.layout.policy.reqmts]].
+##### Exposition-only helpers <a id="mdspan.sub.helpers">[[mdspan.sub.helpers]]</a>
+``` cpp
+template<class T>
+  constexpr T de-ice(T val) { return val; }
+template<integral-constant-like T>
+  constexpr auto de-ice(T) { return T::value; }
+template<class IndexType, size_t k, class... SliceSpecifiers>
+  constexpr IndexType first_(SliceSpecifiers... slices);
+```
+*Mandates:* `IndexType` is a signed or unsigned integer type.
+Let φₖ denote the following value:
+- sₖ if Sₖ models `convertible_to<IndexType>`;
+- otherwise, `get<0>(`sₖ`)` if Sₖ models `index-pair-like<IndexType>`;
+- otherwise, *`de-ice`*`(`sₖ`.offset)` if Sₖ is a specialization of
+  `strided_slice`;
+- otherwise, `0`.
+*Preconditions:* φₖ is representable as a value of type `IndexType`.
+*Returns:* `extents<IndexType>::`*`index-cast`*`(`φₖ`)`.
+``` cpp
+template<size_t k, class Extents, class... SliceSpecifiers>
+  constexpr auto last_(const Extents& src, SliceSpecifiers... slices);
+```
+*Mandates:* `Extents` is a specialization of `extents`.
+Let `index_type` be `typename Extents::index_type`.
+Let λₖ denote the following value:
+- *`de-ice`*`(`sₖ`) + 1` if Sₖ models `convertible_to<index_type>`;
+  otherwise
+- `get<1>(`sₖ`)` if Sₖ models `index-pair-like<index_type>`; otherwise
+- *`de-ice`*`(`sₖ`.offset)` `+` *`de-ice`*`(`sₖ`.extent)` if Sₖ is a
+  specialization of `strided_slice`; otherwise
+- `src.extent(k)`.
+*Preconditions:* λₖ is representable as a value of type `index_type`.
+*Returns:* `Extents::`*`index-cast`*`(`λₖ`)`.
+``` cpp
+template<class IndexType, size_t N, class... SliceSpecifiers>
+  constexpr array<IndexType, sizeof...(SliceSpecifiers)>
+    src-indices(const array<IndexType, N>& indices, SliceSpecifiers... slices);
+```
+*Mandates:* `IndexType` is a signed or unsigned integer type.
+*Returns:* An `array<IndexType, sizeof...(SliceSpecifiers)> src_idx`
+such that for each k in the range \[`0`, `sizeof...(SliceSpecifiers)`),
+`src_idx[`k`]` equals
+- *`first_`*`<IndexType, `k`>(slices...)` for each k where
+  *`map-rank`*`[`k`]` equals `dynamic_extent`,
+- otherwise, *`first_`*`<IndexType, `k`>(slices...)` `+`
+  `indices[`*`map-rank`*`[`k`]]`.
+##### `submdspan_extents` function <a id="mdspan.sub.extents">[[mdspan.sub.extents]]</a>
+``` cpp
+template<class IndexType, size_t... Extents, class... SliceSpecifiers>
+  constexpr auto submdspan_extents(const extents<IndexType, Extents...>& src,
+                                   SliceSpecifiers... slices);
+```
+*Constraints:* `sizeof...(slices)` equals `sizeof...(Extents)`.
+*Mandates:* For each rank index k of `src.extents()`, exactly one of the
+following is true:
+- Sₖ models `convertible_to<IndexType>`,
+- Sₖ models `index-pair-like<IndexType>`,
+- `is_convertible_v<`Sₖ`, full_extent_t>` is `true`, or
+- Sₖ is a specialization of `strided_slice`.
+*Preconditions:* For each rank index k of `src.extents()`, all of the
+following are `true`:
+- if Sₖ is a specialization of `strided_slice`
+  - `$s_k$.extent` = 0, or
+  - `$s_k$.stride` > 0
+- $0 \le \texttt{\textit{first_}<IndexType, $k$>(slices...)}$
+  $\le \texttt{\textit{last_}<$k$>(src, slices...)}$ ≤ `src.extent($k$)`
+Let `SubExtents` be a specialization of `extents` such that:
+- `SubExtents::rank()` equals the number of k such that Sₖ does not
+  model `convertible_to<IndexType>`; and
+- for each rank index k of `Extents` such that
+  *`map-rank`*`[`k`] != dynamic_extent` is `true`,
+  `SubExtents::static_extent(`*`map-rank`*`[`k`])` equals:
+  - `Extents::static_extent(`k`)` if
+    `is_convertible_v<`Sₖ`, full_extent_t>` is `true`; otherwise
+  - *`de-ice`*`(tuple_element_t<1, `Sₖ`>()) -`
+    *`de-ice`*`(tuple_element_t<0, `Sₖ`>())` if Sₖ models
+    `index-pair-like<IndexType>`, and both `tuple_element_t<0, `Sₖ`>`
+    and `tuple_element_t<1, `Sₖ`>` model `integral-constant-like`;
+    otherwise
+  - `0`, if Sₖ is a specialization of `strided_slice`, whose
+    `extent_type` models *`integral-constant-like`*, for which
+    `extent_type()` equals zero; otherwise
+  - `1 + (`*`de-ice`*`(`Sₖ`::extent_type()) - 1) /`
+    *`de-ice`*`(`Sₖ`::stride_type())`, if Sₖ is a specialization of
+    `strided_slice` whose `extent_type` and `stride_type` model
+    *`integral-constant-like`*;
+  - otherwise, `dynamic_extent`.
+*Returns:* A value `ext` of type `SubExtents` such that for each k for
+which *`map-rank`*`[`k`] != dynamic_extent` is `true`,
+`ext.extent(`*`map-rank`*`[`k`])` equals:
+- sₖ`.extent == 0 ? 0 : 1 + (`*`de-ice`*`(`sₖ`.extent) - 1) / `*`de-ice`*`(`sₖ`.stride)`
+  if Sₖ is a specialization of `strided_slice`,
+- otherwise,
+  *`last_`*`<`k`>(src, slices...) - `*`first_`*`<IndexType, `k`>(slices...)`.
+##### Specializations of `submdspan_mapping` <a id="mdspan.sub.map">[[mdspan.sub.map]]</a>
+###### Common <a id="mdspan.sub.map.common">[[mdspan.sub.map.common]]</a>
+The following elements apply to all functions in [[mdspan.sub.map]].
+*Constraints:* `sizeof...(slices)` equals `extents_type::rank()`.
+*Mandates:* For each rank index k of `extents()`, exactly one of the
+following is true:
+- Sₖ models `convertible_to<index_type>`,
+- Sₖ models `index-pair-like<index_type>`,
+- `is_convertible_v<Sₖ, full_extent_t>` is `true`, or
+- Sₖ is a specialization of `strided_slice`.
+*Preconditions:* For each rank index k of `extents()`, all of the
+following are `true`:
+- if Sₖ is a specialization of `strided_slice`, `sₖ.extent` is equal to
+  zero or `sₖ.stride` is greater than zero; and
+- $0            \leq \tcode{\exposid{first_}<index_type, $k$>(slices...)} \\
+  \hphantom{0 } \leq \tcode{\exposid{last_}<$k$>(extents(), slices...)} \\
+  \hphantom{0 } \leq \tcode{extents().extent($k$)}$
+Let `sub_ext` be the result of `submdspan_extents(extents(), slices...)`
+and let `SubExtents` be `decltype(sub_ext)`.
+Let `sub_strides` be an
+`array<SubExtents::index_type, SubExtents::rank()>` such that for each
+rank index k of `extents()` for which `map-rank[k]` is not
+`dynamic_extent`, `sub_strides[map-rank[k]]` equals:
+- `stride(k) * de-ice(sₖ.stride)` if Sₖ is a specialization of
+  `strided_slice` and `sₖ.stride < sₖ.extent` is `true`;
+- otherwise, `stride(k)`.
+Let `P` be a parameter pack such that
+`is_same_v<make_index_sequence<rank()>, index_sequence<P...>>` is
+`true`.
+If `first_<index_type, k>(slices...)` equals `extents().extent(k)` for
+any rank index k of `extents()`, then let `offset` be a value of type
+`size_t` equal to `(*this).required_span_size()`. Otherwise, let
+`offset` be a value of type `size_t` equal to
+`(*this)(first_<index_type, P>(slices...)...)`.
+Given a layout mapping type `M`, a type `S` is a *unit-stride slice for
+`M`* if
+- `S` is a specialization of `strided_slice` where `S::stride_type`
+  models `integral-constant-like` and `S::stride_type::value` equals
+  `1`,
+- `S` models `index-pair-like<M::index_type>`, or
+- `is_convertible_v<S, full_extent_t>` is `true`.
+###### `layout_left` specialization of `submdspan_mapping` <a id="mdspan.sub.map.left">[[mdspan.sub.map.left]]</a>
+``` cpp
+template<class Extents>
+template<class... SliceSpecifiers>
+constexpr auto layout_left::mapping<Extents>::submdspan-mapping-impl(
+      SliceSpecifiers... slices) const -> see below;
+```
+*Returns:*
+- `submdspan_mapping_result{*this, 0}`, if `Extents::rank() == 0` is
+  `true`;
+- otherwise,
+  `submdspan_mapping_result{layout_left::mapping(sub_ext), offset}`, if
+  `SubExtents::rank() == 0` is `true`;
+- otherwise,
+  `submdspan_mapping_result{layout_left::mapping(sub_ext), offset}`, if
+  - for each k in the range \[`0`, `SubExtents::rank() - 1)`),
+    `is_convertible_v<`Sₖ`, full_extent_t>` is `true`; and
+  - for k equal to `SubExtents::rank() - 1`, Sₖ is a unit-stride slice
+    for `mapping`;
+  \[*Note 2*: If the above conditions are true, all Sₖ with k larger
+  than `SubExtents::rank() - 1` are convertible to
+  `index_type`. — *end note*]
+- otherwise,
+  ``` cpp
+  submdspan_mapping_result{layout_left_padded<S_static>::mapping(sub_ext, stride(u + 1)),
+                           offset}
+  ```
+  if for a value u for which u+1 is the smallest value p larger than
+  zero for which Sₚ is a unit-stride slice for `mapping`, the following
+  conditions are met:
+  - S₀ is a unit-stride slice for `mapping`; and
+  - for each k in the range \[u` + 1`, u` + SubExtents::rank() - 1`),
+    `is_convertible_v<`Sₖ`, full_extent_t>` is `true`; and
+  - for k equal to u` + SubExtents::rank() - 1`, Sₖ is a unit-stride
+    slice for `mapping`;
+  and where `S_static` is:
+  - `dynamic_extent`, if `static_extent(`k`)` is `dynamic_extent` for
+    any k in the range \[`0`, u` + 1`),
+  - otherwise, the product of all values `static_extent(`k`)` for k in
+    the range \[`0`, u` + 1`);
+- otherwise,
+  ``` cpp
+  submdspan_mapping_result{layout_stride::mapping(sub_ext, sub_strides), offset}
+  ```
+###### `layout_right` specialization of `submdspan_mapping` <a id="mdspan.sub.map.right">[[mdspan.sub.map.right]]</a>
+``` cpp
+template<class Extents>
+template<class... SliceSpecifiers>
+constexpr auto layout_right::mapping<Extents>::submdspan-mapping-impl(
+      SliceSpecifiers... slices) const -> see below;
+```
+*Returns:*
+- `submdspan_mapping_result{*this, 0}`, if `Extents::rank() == 0` is
+  `true`;
+- otherwise,
+  `submdspan_mapping_result{layout_right::mapping(sub_ext), offset}`, if
+  `SubExtents::rank() == 0` is `true`;
+- otherwise,
+  `submdspan_mapping_result{layout_right::mapping(sub_ext), offset}`, if
+  - for each k in the range \[*`rank_`*` - SubExtents::rank() + 1`,
+    *`rank_`*), `is_convertible_v<`Sₖ`, full_extent_t>` is `true`; and
+  - for k equal to *rank\_* - `SubExtents::rank()`, Sₖ is a unit-stride
+    slice for `mapping`;
+  \[*Note 3*: If the above conditions are true, all Sₖ with
+  $k < \texttt{\textit{rank_} - SubExtents::rank()}$ are convertible to
+  `index_type`. — *end note*]
+- otherwise,
+  ``` cpp
+  submdspan_mapping_result{layout_right_padded<S_static>::mapping(sub_ext,
+                               stride(rank_ - u - 2)), offset}
+  ```
+  if for a value u for which rank_ - u - 2 is the largest value p
+  smaller than *`rank_`*` - 1` for which Sₚ is a unit-stride slice for
+  `mapping`, the following conditions are met:
+  - for k equal to *`rank_`*` - 1`, Sₖ is a unit-stride slice for
+    `mapping`; and
+  - for each k in the range
+    \[*`rank_`*` - SubExtents::rank() - `u` + 1`,
+    *`rank_`*` - `u` - 1`), `is_convertible_v<`Sₖ`, full_extent_t>` is
+    `true`; and
+  - for k equal to *`rank_`*` - SubExtents::rank() - `u, Sₖ is a
+    unit-stride slice for `mapping`;
+  and where `S_static` is:
+  - `dynamic_extent`, if `static_extent(`k`)` is `dynamic_extent` for
+    any k in the range \[*`rank_`*` - `u` - 1`, *`rank_`*),
+  - otherwise, the product of all values `static_extent(`k`)` for k in
+    the range \[*`rank_`*` - `u` - 1`, *`rank_`*);
+- otherwise,
+  ``` cpp
+  submdspan_mapping_result{layout_stride::mapping(sub_ext, sub_strides), offset}
+  ```
+###### `layout_stride` specialization of `submdspan_mapping` <a id="mdspan.sub.map.stride">[[mdspan.sub.map.stride]]</a>
+``` cpp
+template<class Extents>
+template<class... SliceSpecifiers>
+constexpr auto layout_stride::mapping<Extents>::submdspan-mapping-impl(
+      SliceSpecifiers... slices) const -> see below;
+```
+*Returns:*
+- `submdspan_mapping_result{*this, 0}`, if `Extents::rank() == 0` is
+  `true`;
+- otherwise,
+  ``` cpp
+  submdspan_mapping_result{layout_stride::mapping(sub_ext, sub_strides), offset}
+  ```
+###### `layout_left_padded` specialization of `submdspan_mapping` <a id="mdspan.sub.map.leftpad">[[mdspan.sub.map.leftpad]]</a>
+``` cpp
+template<class Extents>
+template<class... SliceSpecifiers>
+constexpr auto layout_left_padded::mapping<Extents>::submdspan-mapping-impl(
+    SliceSpecifiers... slices) const -> see below;
+```
+*Returns:*
+- `submdspan_mapping_result{*this, 0}`, if `Extents::rank() == 0` is
+  `true`;
+- otherwise,
+  `submdspan_mapping_result{layout_left::mapping(sub_ext), offset}`, if
+  *`rank_`*` == 1` is `true` or `SubExtents::rank() == 0` is `true`;
+- otherwise,
+  `submdspan_mapping_result{layout_left::mapping(sub_ext), offset}`, if
+  - `SubExtents::rank() == 1` is `true` and
+  - S₀ is a unit-stride slice for `mapping`;
+- otherwise,
+  ``` cpp
+  submdspan_mapping_result{layout_left_padded<S_static>::mapping(sub_ext, stride(u + 1)),
+                           offset}
+  ```
+  if for a value u for which u` + 1` is the smallest value p larger than
+  zero for which Sₚ is a unit-stride slice for `mapping`, the following
+  conditions are met:
+  - S₀ is a unit-stride slice for `mapping`; and
+  - for each k in the range \[u` + 1`, u` + SubExtents::rank() - 1`),
+    `is_convertible_v<`Sₖ`, full_extent_t>` is `true`; and
+  - for k equal to u` + SubExtents::rank() - 1`, Sₖ is a unit-stride
+    slice for `mapping`;
+  where `S_static` is:
+  - `dynamic_extent`, if *static-padding-stride* is `dynamic_extent` or
+    `static_extent(`k`)` is `dynamic_extent` for any k in the range
+    \[`1`, u` + 1`),
+  - otherwise, the product of *static-padding-stride* and all values
+    `static_extent(`k`)` for k in the range \[`1`, u` + 1`);
+- otherwise,
+  ``` cpp
+  submdspan_mapping_result{layout_stride::mapping(sub_ext, sub_strides), offset}
+  ```
+###### `layout_right_padded` specialization of `submdspan_mapping` <a id="mdspan.sub.map.rightpad">[[mdspan.sub.map.rightpad]]</a>
+``` cpp
+template<class Extents>
+template<class... SliceSpecifiers>
+constexpr auto layout_right_padded::mapping<Extents>::submdspan-mapping-impl(
+    SliceSpecifiers... slices) const -> see below;
+```
+*Returns:*
+- `submdspan_mapping_result{*this, 0}`, if *`rank_`*` == 0` is `true`;
+- otherwise,
+  `submdspan_mapping_result{layout_right::mapping(sub_ext), offset}`, if
+  *`rank_`*` == 1` is `true` or `SubExtents::rank() == 0` is `true`;
+- otherwise,
+  `submdspan_mapping_result{layout_right::mapping(sub_ext), offset}`, if
+  - `SubExtents::rank() == 1` is `true` and
+  - for k equal to *`rank_`*` - 1`, Sₖ is a unit-stride slice for
+    `mapping`;
+- otherwise,
+  ``` cpp
+  submdspan_mapping_result{layout_right_padded<S_static>::mapping(sub_ext,
+                               stride(rank_ - u - 2)), offset}
+  ```
+  if for a value u for which *`rank_`*` - `u` - 2` is the largest value
+  p smaller than *`rank_`*` - 1` for which Sₚ is a unit-stride slice for
+  `mapping`, the following conditions are met:
+  - for k equal to *`rank_`*` - 1`, Sₖ is a unit-stride slice for
+    `mapping`; and
+  - for each k in the range
+    \[*`rank_`*` - SubExtents::rank() - `u` + 1`,
+    *`rank_`*` - `u` - 1)`), `is_convertible_v<`Sₖ`, full_extent_t>` is
+    `true`; and
+  - for k equal to *`rank_`*` - SubExtents::rank() - `u, Sₖ is a
+    unit-stride slice for `mapping`;
+  and where `S_static` is:
+  - `dynamic_extent` if *static-padding-stride* is `dynamic_extent` or
+    for any k in the range \[*`rank_`*` - `u` - 1`, *`rank_`*` - 1`)
+    `static_extent(`k`)` is `dynamic_extent`,
+  - otherwise, the product of *static-padding-stride* and all values
+    `static_extent(`k`)` with k in the range \[*`rank_`*` - `u` - 1`,
+    *`rank_`*` - 1`);
+- otherwise,
+  ``` cpp
+  submdspan_mapping_result{layout_stride::mapping(sub_ext, sub_strides), offset}
+  ```
+##### `submdspan` function template <a id="mdspan.sub.sub">[[mdspan.sub.sub]]</a>
+``` cpp
+template<class ElementType, class Extents, class LayoutPolicy,
+         class AccessorPolicy, class... SliceSpecifiers>
+  constexpr auto submdspan(
+    const mdspan<ElementType, Extents, LayoutPolicy, AccessorPolicy>& src,
+    SliceSpecifiers... slices) -> see below;
+```
+Let `index_type` be `typename Extents::index_type`.
+Let `sub_map_offset` be the result of
+`submdspan_mapping(src.mapping(), slices...)`.
+[*Note 1*: This invocation of `submdspan_mapping` selects a function
+call via overload resolution on a candidate set that includes the lookup
+set found by argument-dependent
+lookup [[basic.lookup.argdep]]. — *end note*]
+*Constraints:*
+- `sizeof...(slices)` equals `Extents::rank()`, and
+- the expression `submdspan_mapping(src.mapping(), slices...)` is
+  well-formed when treated as an unevaluated operand.
+*Mandates:*
+- `decltype(submdspan_mapping(src.mapping(), slices...))` is a
+  specialization of `submd-span_mapping_result`.
+- `is_same_v<remove_cvref_t<decltype(sub_map_offset.mapping.extents())>,`
+  `decltype(submdspan_extents(src.mapping(), slices...))>` is `true`.
+- For each rank index k of `src.extents()`, exactly one of the following
+  is true:
+  - Sₖ models `convertible_to<index_type>`,
+  - Sₖ models `index-pair-like<index_type>`,
+  - `is_convertible_v<`Sₖ`, full_extent_t>` is `true`, or
+  - Sₖ is a specialization of `strided_slice`.
+*Preconditions:*
+- For each rank index k of `src.extents()`, all of the following are
+  `true`:
+  - if Sₖ is a specialization of `strided_slice`
+    - `$s_k$.extent` = 0, or
+    - `$s_k$.stride` > 0
+  - $0 \le \texttt{\textit{first_}<index_type, $k$>(slices...)}$
+    $\le \texttt{\textit{last_}<$k$>(src.extents(), slices...)}$
+    ≤ `{}src.extent($k$)`
+- `sub_map_offset.mapping.extents() == submdspan_extents(src.mapping(), slices...)`
+  is `true`; and
+- for each integer pack `I` which is a multidimensional index in
+  `sub_map_offset.mapping.extents()`,
+  ``` cpp
+  sub_map_offset.mapping(I...) + sub_map_offset.offset ==
+    src.mapping()(src-indices(array{I...}, slices...))
+  ```
+  is `true`.
+[*Note 2*: These conditions ensure that the mapping returned by
+`submdspan_mapping` matches the algorithmically expected index-mapping
+given the slice specifiers. — *end note*]
+*Effects:* Equivalent to:
+``` cpp
+auto sub_map_result = submdspan_mapping(src.mapping(), slices...);
+return mdspan(src.accessor().offset(src.data_handle(), sub_map_result.offset),
+              sub_map_result.mapping,
+              typename AccessorPolicy::offset_policy(src.accessor()));
+```
+[*Example 1*:
+Given a rank-3 `mdspan grid3d` representing a three-dimensional grid of
+regularly spaced points in a rectangular prism, the function
+`zero_surface` sets all elements on the surface of the 3-dimensional
+shape to zero. It does so by reusing a function `zero_2d` that takes a
+rank-2 `mdspan`.
+``` cpp
+// zero out all elements in an mdspan
+template<class T, class E, class L, class A>
+void zero_2d(mdspan<T, E, L, A> a) {
+  static_assert(a.rank() == 2);
+  for (int i = 0; i < a.extent(0); i++)
+    for (int j = 0; j < a.extent(1); j++)
+      a[i, j] = 0;
+}
+// zero out just the surface
+template<class T, class E, class L, class A>
+void zero_surface(mdspan<T, E, L, A> grid3d) {
+  static_assert(grid3d.rank() == 3);
+  zero_2d(submdspan(grid3d, 0, full_extent, full_extent));
+  zero_2d(submdspan(grid3d, full_extent, 0, full_extent));
+  zero_2d(submdspan(grid3d, full_extent, full_extent, 0));
+  zero_2d(submdspan(grid3d, grid3d.extent(0) - 1, full_extent, full_extent));
+  zero_2d(submdspan(grid3d, full_extent, grid3d.extent(1) - 1, full_extent));
+  zero_2d(submdspan(grid3d, full_extent, full_extent, grid3d.extent(2) - 1));
+}
+```
+— *end example*]
+<!-- Link reference definitions -->
+[alg.equal]: algorithms.md#alg.equal
+[alg.sorting]: algorithms.md#alg.sorting
+[algorithm.stable]: library.md#algorithm.stable
+[algorithms]: algorithms.md#algorithms
+[algorithms.requirements]: algorithms.md#algorithms.requirements
+[allocator.requirements]: library.md#allocator.requirements
+[allocator.requirements.completeness]: library.md#allocator.requirements.completeness
+[allocator.traits.members]: mem.md#allocator.traits.members
+[allocator.uses.construction]: mem.md#allocator.uses.construction
+[array]: #array
+[array.cons]: #array.cons
+[array.creation]: #array.creation
+[array.members]: #array.members
+[array.overview]: #array.overview
+[array.special]: #array.special
+[array.syn]: #array.syn
+[array.tuple]: #array.tuple
+[array.zero]: #array.zero
+[associative]: #associative
+[associative.general]: #associative.general
+[associative.map.syn]: #associative.map.syn
+[associative.reqmts]: #associative.reqmts
+[associative.reqmts.except]: #associative.reqmts.except
+[associative.reqmts.general]: #associative.reqmts.general
+[associative.set.syn]: #associative.set.syn
+[basic.fundamental]: basic.md#basic.fundamental
+[basic.lookup.argdep]: basic.md#basic.lookup.argdep
+[basic.string]: strings.md#basic.string
+[class.copy.ctor]: class.md#class.copy.ctor
+[class.default.ctor]: class.md#class.default.ctor
+[class.dtor]: class.md#class.dtor
+[container.adaptors]: #container.adaptors
+[container.adaptors.format]: #container.adaptors.format
+[container.adaptors.general]: #container.adaptors.general
+[container.alloc.reqmts]: #container.alloc.reqmts
+[container.insert.return]: #container.insert.return
+[container.intro.reqmts]: #container.intro.reqmts
+[container.node]: #container.node
+[container.node.compat]: #container.node.compat
+[container.node.cons]: #container.node.cons
+[container.node.dtor]: #container.node.dtor
+[container.node.modifiers]: #container.node.modifiers
+[container.node.observers]: #container.node.observers
+[container.node.overview]: #container.node.overview
+[container.opt.reqmts]: #container.opt.reqmts
+[container.reqmts]: #container.reqmts
+[container.requirements]: #container.requirements
+[container.requirements.dataraces]: #container.requirements.dataraces
+[container.requirements.general]: #container.requirements.general
+[container.requirements.pre]: #container.requirements.pre
+[container.rev.reqmts]: #container.rev.reqmts
+[containers]: #containers
+[containers.general]: #containers.general
+[containers.summary]: #containers.summary
+[dcl.init.aggr]: dcl.md#dcl.init.aggr
+[defns.valid]: intro.md#defns.valid
+[deque]: #deque
+[deque.capacity]: #deque.capacity
+[deque.cons]: #deque.cons
+[deque.erasure]: #deque.erasure
+[deque.modifiers]: #deque.modifiers
+[deque.overview]: #deque.overview
+[deque.syn]: #deque.syn
+[expr.const]: expr.md#expr.const
+[flat.map]: #flat.map
+[flat.map.access]: #flat.map.access
+[flat.map.capacity]: #flat.map.capacity
+[flat.map.cons]: #flat.map.cons
+[flat.map.cons.alloc]: #flat.map.cons.alloc
+[flat.map.defn]: #flat.map.defn
+[flat.map.erasure]: #flat.map.erasure
+[flat.map.modifiers]: #flat.map.modifiers
+[flat.map.overview]: #flat.map.overview
+[flat.map.syn]: #flat.map.syn
+[flat.multimap]: #flat.multimap
+[flat.multimap.cons]: #flat.multimap.cons
+[flat.multimap.cons.alloc]: #flat.multimap.cons.alloc
+[flat.multimap.defn]: #flat.multimap.defn
+[flat.multimap.erasure]: #flat.multimap.erasure
+[flat.multimap.overview]: #flat.multimap.overview
+[flat.multiset]: #flat.multiset
+[flat.multiset.cons]: #flat.multiset.cons
+[flat.multiset.cons.alloc]: #flat.multiset.cons.alloc
+[flat.multiset.defn]: #flat.multiset.defn
+[flat.multiset.erasure]: #flat.multiset.erasure
+[flat.multiset.modifiers]: #flat.multiset.modifiers
+[flat.multiset.overview]: #flat.multiset.overview
+[flat.set]: #flat.set
+[flat.set.cons]: #flat.set.cons
+[flat.set.cons.alloc]: #flat.set.cons.alloc
+[flat.set.defn]: #flat.set.defn
+[flat.set.erasure]: #flat.set.erasure
+[flat.set.modifiers]: #flat.set.modifiers
+[flat.set.overview]: #flat.set.overview
+[flat.set.syn]: #flat.set.syn
+[forward.iterators]: iterators.md#forward.iterators
+[forward.list]: #forward.list
+[forward.list.access]: #forward.list.access
+[forward.list.cons]: #forward.list.cons
+[forward.list.erasure]: #forward.list.erasure
+[forward.list.iter]: #forward.list.iter
+[forward.list.modifiers]: #forward.list.modifiers
+[forward.list.ops]: #forward.list.ops
+[forward.list.overview]: #forward.list.overview
+[forward.list.syn]: #forward.list.syn
+[hash.requirements]: library.md#hash.requirements
+[hive]: #hive
+[hive.capacity]: #hive.capacity
+[hive.cons]: #hive.cons
+[hive.erasure]: #hive.erasure
+[hive.modifiers]: #hive.modifiers
+[hive.operations]: #hive.operations
+[hive.overview]: #hive.overview
+[hive.syn]: #hive.syn
+[inplace.vector]: #inplace.vector
+[inplace.vector.capacity]: #inplace.vector.capacity
+[inplace.vector.cons]: #inplace.vector.cons
+[inplace.vector.data]: #inplace.vector.data
+[inplace.vector.erasure]: #inplace.vector.erasure
+[inplace.vector.modifiers]: #inplace.vector.modifiers
+[inplace.vector.overview]: #inplace.vector.overview
+[inplace.vector.syn]: #inplace.vector.syn
+[iterator.concept.contiguous]: iterators.md#iterator.concept.contiguous
+[iterator.concept.random.access]: iterators.md#iterator.concept.random.access
+[iterator.requirements]: iterators.md#iterator.requirements
+[iterator.requirements.general]: iterators.md#iterator.requirements.general
+[list]: #list
+[list.capacity]: #list.capacity
+[list.cons]: #list.cons
+[list.erasure]: #list.erasure
+[list.modifiers]: #list.modifiers
+[list.ops]: #list.ops
+[list.overview]: #list.overview
+[list.syn]: #list.syn
+[map]: #map
+[map.access]: #map.access
+[map.cons]: #map.cons
+[map.erasure]: #map.erasure
+[map.modifiers]: #map.modifiers
+[map.overview]: #map.overview
+[mdspan.accessor]: #mdspan.accessor
+[mdspan.accessor.aligned]: #mdspan.accessor.aligned
+[mdspan.accessor.aligned.members]: #mdspan.accessor.aligned.members
+[mdspan.accessor.aligned.overview]: #mdspan.accessor.aligned.overview
+[mdspan.accessor.default]: #mdspan.accessor.default
+[mdspan.accessor.default.members]: #mdspan.accessor.default.members
+[mdspan.accessor.default.overview]: #mdspan.accessor.default.overview
+[mdspan.accessor.general]: #mdspan.accessor.general
+[mdspan.accessor.reqmts]: #mdspan.accessor.reqmts
+[mdspan.extents]: #mdspan.extents
+[mdspan.extents.cmp]: #mdspan.extents.cmp
+[mdspan.extents.cons]: #mdspan.extents.cons
+[mdspan.extents.dextents]: #mdspan.extents.dextents
+[mdspan.extents.dims]: #mdspan.extents.dims
+[mdspan.extents.expo]: #mdspan.extents.expo
+[mdspan.extents.obs]: #mdspan.extents.obs
+[mdspan.extents.overview]: #mdspan.extents.overview
+[mdspan.layout]: #mdspan.layout
+[mdspan.layout.general]: #mdspan.layout.general
+[mdspan.layout.left]: #mdspan.layout.left
+[mdspan.layout.left.cons]: #mdspan.layout.left.cons
+[mdspan.layout.left.obs]: #mdspan.layout.left.obs
+[mdspan.layout.left.overview]: #mdspan.layout.left.overview
+[mdspan.layout.leftpad]: #mdspan.layout.leftpad
+[mdspan.layout.leftpad.cons]: #mdspan.layout.leftpad.cons
+[mdspan.layout.leftpad.expo]: #mdspan.layout.leftpad.expo
+[mdspan.layout.leftpad.obs]: #mdspan.layout.leftpad.obs
+[mdspan.layout.leftpad.overview]: #mdspan.layout.leftpad.overview
+[mdspan.layout.policy.overview]: #mdspan.layout.policy.overview
+[mdspan.layout.policy.reqmts]: #mdspan.layout.policy.reqmts
+[mdspan.layout.reqmts]: #mdspan.layout.reqmts
+[mdspan.layout.right]: #mdspan.layout.right
+[mdspan.layout.right.cons]: #mdspan.layout.right.cons
+[mdspan.layout.right.obs]: #mdspan.layout.right.obs
+[mdspan.layout.right.overview]: #mdspan.layout.right.overview
+[mdspan.layout.rightpad]: #mdspan.layout.rightpad
+[mdspan.layout.rightpad.cons]: #mdspan.layout.rightpad.cons
+[mdspan.layout.rightpad.expo]: #mdspan.layout.rightpad.expo
+[mdspan.layout.rightpad.obs]: #mdspan.layout.rightpad.obs
+[mdspan.layout.rightpad.overview]: #mdspan.layout.rightpad.overview
+[mdspan.layout.stride]: #mdspan.layout.stride
+[mdspan.layout.stride.cons]: #mdspan.layout.stride.cons
+[mdspan.layout.stride.expo]: #mdspan.layout.stride.expo
+[mdspan.layout.stride.obs]: #mdspan.layout.stride.obs
+[mdspan.layout.stride.overview]: #mdspan.layout.stride.overview
+[mdspan.mdspan]: #mdspan.mdspan
+[mdspan.mdspan.cons]: #mdspan.mdspan.cons
+[mdspan.mdspan.members]: #mdspan.mdspan.members
+[mdspan.mdspan.overview]: #mdspan.mdspan.overview
+[mdspan.overview]: #mdspan.overview
+[mdspan.sub]: #mdspan.sub
+[mdspan.sub.extents]: #mdspan.sub.extents
+[mdspan.sub.helpers]: #mdspan.sub.helpers
+[mdspan.sub.map]: #mdspan.sub.map
+[mdspan.sub.map.common]: #mdspan.sub.map.common
+[mdspan.sub.map.left]: #mdspan.sub.map.left
+[mdspan.sub.map.leftpad]: #mdspan.sub.map.leftpad
+[mdspan.sub.map.result]: #mdspan.sub.map.result
+[mdspan.sub.map.right]: #mdspan.sub.map.right
+[mdspan.sub.map.rightpad]: #mdspan.sub.map.rightpad
+[mdspan.sub.map.stride]: #mdspan.sub.map.stride
+[mdspan.sub.overview]: #mdspan.sub.overview
+[mdspan.sub.strided.slice]: #mdspan.sub.strided.slice
+[mdspan.sub.sub]: #mdspan.sub.sub
+[mdspan.syn]: #mdspan.syn
+[multimap]: #multimap
+[multimap.cons]: #multimap.cons
+[multimap.erasure]: #multimap.erasure
+[multimap.modifiers]: #multimap.modifiers
+[multimap.overview]: #multimap.overview
+[multiset]: #multiset
+[multiset.cons]: #multiset.cons
+[multiset.erasure]: #multiset.erasure
+[multiset.overview]: #multiset.overview
+[priority.queue]: #priority.queue
+[priqueue.cons]: #priqueue.cons
+[priqueue.cons.alloc]: #priqueue.cons.alloc
+[priqueue.members]: #priqueue.members
+[priqueue.overview]: #priqueue.overview
+[priqueue.special]: #priqueue.special
+[queue]: #queue
+[queue.cons]: #queue.cons
+[queue.cons.alloc]: #queue.cons.alloc
+[queue.defn]: #queue.defn
+[queue.mod]: #queue.mod
+[queue.ops]: #queue.ops
+[queue.special]: #queue.special
+[queue.syn]: #queue.syn
+[random.access.iterators]: iterators.md#random.access.iterators
+[re.results]: text.md#re.results
+[res.on.data.races]: library.md#res.on.data.races
+[sequence.reqmts]: #sequence.reqmts
+[sequences]: #sequences
+[sequences.general]: #sequences.general
+[set]: #set
+[set.cons]: #set.cons
+[set.erasure]: #set.erasure
+[set.modifiers]: #set.modifiers
+[set.overview]: #set.overview
+[span.cons]: #span.cons
+[span.deduct]: #span.deduct
+[span.elem]: #span.elem
+[span.iterators]: #span.iterators
+[span.objectrep]: #span.objectrep
+[span.obs]: #span.obs
+[span.overview]: #span.overview
+[span.sub]: #span.sub
+[span.syn]: #span.syn
+[stack]: #stack
+[stack.cons]: #stack.cons
+[stack.cons.alloc]: #stack.cons.alloc
+[stack.defn]: #stack.defn
+[stack.general]: #stack.general
+[stack.mod]: #stack.mod
+[stack.ops]: #stack.ops
+[stack.special]: #stack.special
+[stack.syn]: #stack.syn
+[stacktrace.basic]: diagnostics.md#stacktrace.basic
+[strings]: strings.md#strings
+[swappable.requirements]: library.md#swappable.requirements
+[temp.deduct]: temp.md#temp.deduct
+[temp.type]: temp.md#temp.type
+[term.structural.type]: temp.md#term.structural.type
+[term.trivially.copyable.type]: basic.md#term.trivially.copyable.type
+[unord]: #unord
+[unord.general]: #unord.general
+[unord.hash]: utilities.md#unord.hash
+[unord.map]: #unord.map
+[unord.map.cnstr]: #unord.map.cnstr
+[unord.map.elem]: #unord.map.elem
+[unord.map.erasure]: #unord.map.erasure
+[unord.map.modifiers]: #unord.map.modifiers
+[unord.map.overview]: #unord.map.overview
+[unord.map.syn]: #unord.map.syn
+[unord.multimap]: #unord.multimap
+[unord.multimap.cnstr]: #unord.multimap.cnstr
+[unord.multimap.erasure]: #unord.multimap.erasure
+[unord.multimap.modifiers]: #unord.multimap.modifiers
+[unord.multimap.overview]: #unord.multimap.overview
+[unord.multiset]: #unord.multiset
+[unord.multiset.cnstr]: #unord.multiset.cnstr
+[unord.multiset.erasure]: #unord.multiset.erasure
+[unord.multiset.overview]: #unord.multiset.overview
+[unord.req]: #unord.req
+[unord.req.except]: #unord.req.except
+[unord.req.general]: #unord.req.general
+[unord.set]: #unord.set
+[unord.set.cnstr]: #unord.set.cnstr
+[unord.set.erasure]: #unord.set.erasure
+[unord.set.modifiers]: #unord.set.modifiers
+[unord.set.overview]: #unord.set.overview
+[unord.set.syn]: #unord.set.syn
+[vector]: #vector
+[vector.bool]: #vector.bool
+[vector.bool.fmt]: #vector.bool.fmt
+[vector.bool.pspc]: #vector.bool.pspc
+[vector.capacity]: #vector.capacity
+[vector.cons]: #vector.cons
+[vector.data]: #vector.data
+[vector.erasure]: #vector.erasure
+[vector.modifiers]: #vector.modifiers
+[vector.overview]: #vector.overview
+[vector.syn]: #vector.syn
+[views]: #views
+[views.contiguous]: #views.contiguous
+[views.general]: #views.general
+[views.multidim]: #views.multidim
+[views.span]: #views.span
+[^1]: Equality comparison is a refinement of partitioning if no two
+    objects that compare equal fall into different partitions.
+[^2]: These member functions are only provided by containers whose
+    iterators are random access iterators.
+[^3]: As specified in  [[allocator.requirements]], the requirements in
+    this Clause apply only to lists whose allocators compare equal.
+[^4]: `reserve()` uses `Allocator::allocate()` which can throw an
+    appropriate exception.

Diff to HTML by rtfpessoa