24 Containers library [containers]

24.7 Views [views]

24.7.3 Multidimensional access [views.multidim]

24.7.3.7 submdspan [mdspan.submdspan]

24.7.3.7.1 Overview [mdspan.submdspan.overview]

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 subclause [mdspan.submdspan] that takes a parameter pack named slices as an argument:

(2.1)
let index_type be
- (2.1.1)
  M::index_type if the function is a member of a class M,
- (2.1.2)
  otherwise, remove_reference_t<decltype(src)>::index_type if the function has a parameter named src,
- (2.1.3)
  otherwise, the same type as the function's template argument IndexType;
(2.2)
let rank be the number of elements in slices;
(2.3)
let $s_{k}$ be the $k^{th}$ element of slices;
(2.4)
let $S_{k}$ be the type of $s_{k}$ ; and
(2.5)
let map-rank be an array<size_t, rank> such that for each k in the range [0, rank), map-rank[k] equals:
- (2.5.1)
  dynamic_extent if $S_{k}$ models convertible_to<index_type>,
- (2.5.2)
  otherwise, the number of types $S_{j}$ with $j < k$ that do not model convertible_to<index_type>.

24.7.3.7.2 strided_slice [mdspan.submdspan.strided.slice]

strided_slice represents a set of extent regularly spaced integer indices.

The indices start at offset, and increase by increments of stride.

🔗

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]

24.7.3.7.3 submdspan_mapping_result [mdspan.submdspan.submdspan.mapping.result]

Specializations of submdspan_mapping_result are returned by overloads of submdspan_mapping.

🔗

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]).

24.7.3.7.4 Exposition-only helpers [mdspan.submdspan.helpers]

🔗

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

ϕ_{k}

denote the following value:

(2.1)
$s_{k}$ if $S_{k}$ models convertible_to<IndexType>;
(2.2)
otherwise, get<0>( $s_{k}$ ) if $S_{k}$ models index-pair-like<IndexType>;
(2.3)
otherwise, de-ice( $s_{k}$ .offset) if $S_{k}$ is a specialization of strided_slice;
(2.4)
otherwise, 0.

Preconditions:

ϕ_{k}

is representable as a value of type IndexType.

Returns: extents<IndexType>::index-cast(

ϕ_{k}

🔗

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

λ_{k}

denote the following value:

(7.1)
de-ice( $s_{k}$ ) + 1 if $S_{k}$ models convertible_to<index_type>; otherwise
(7.2)
get<1>( $s_{k}$ ) if $S_{k}$ models index-pair-like<index_type>; otherwise
(7.3)
de-ice( $s_{k}$ .offset) + de-ice( $s_{k}$ .extent) if $S_{k}$ is a specialization of strided_slice; otherwise
(7.4)
src.extent(k).

Preconditions:

λ_{k}

is representable as a value of type index_type.

Returns: Extents::index-cast(

λ_{k}

🔗

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

(11.1)
first_<IndexType, k>(slices...) for each k where map-rank[k] equals dynamic_extent,
(11.2)
otherwise, first_<IndexType, k>(slices...) + indices[map-rank[k]].

24.7.3.7.5 submdspan_extents function [mdspan.submdspan.extents]

🔗

template<class IndexType, class... Extents, class... SliceSpecifiers>
  constexpr auto submdspan_extents(const extents<IndexType, Extents...>& src,
                                   SliceSpecifiers... slices);

Constraints: sizeof...(slices) equals Extents::rank().

Mandates: For each rank index k of src.extents(), exactly one of the following is true:

(2.1)
$S_{k}$ models convertible_to<IndexType>,
(2.2)
$S_{k}$ models index-pair-like<IndexType>,
(2.3)
is_convertible_v< $S_{k}$ , full_extent_t> is true, or
(2.4)
$S_{k}$ is a specialization of strided_slice.

Preconditions: For each rank index k of src.extents(), all of the following are true:

(3.1)
if $S_{k}$ is a specialization of strided_slice
- (3.1.1)
  $s_{k} .extent = 0$ , or
- (3.1.2)
  $s_{k} .stride > 0$
(3.2)
0 ≤ first_<IndexType, k>(slices...) ≤ last_<k>(src, slices...) ≤ src.extent(k)

Let SubExtents be a specialization of extents such that:

(4.1)
SubExtents::rank() equals the number of k such that $S_{k}$ does not model convertible_to<IndexType>; and
(4.2)
for each rank index k of Extents such that map-rank[k] != dynamic_extent is true, SubExtents::static_extent(map-rank[k]) equals:
- (4.2.1)
  Extents::static_extent(k) if is_convertible_v< $S_{k}$ , full_extent_t> is true; otherwise
- (4.2.2)
  de-ice(tuple_element_t<1, $S_{k}$ >()) - de-ice(tuple_element_t<0, $S_{k}$ >()) if $S_{k}$ models index-pair-like<IndexType>, and both tuple_element_t<0, $S_{k}$ > and tuple_element_t<1, $S_{k}$ > model integral-constant-like; otherwise
- (4.2.3)
  0, if $S_{k}$ is a specialization of strided_slice, whose extent_type models integral-constant-like, for which extent_type() equals zero; otherwise
- (4.2.4)
  1 + (de-ice( $S_{k}$ ::extent_type()) - 1) / de-ice( $S_{k}$ ::stride_type()), if $S_{k}$ is a specialization of strided_slice whose extent_type and stride_type model integral-constant-like;
- (4.2.5)
  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:

(5.1)
$s_{k}$ .extent == 0 ? 0 : 1 + (de-ice( $s_{k}$ .extent) - 1) / de-ice( $s_{k}$ .stride) if $S_{k}$ is a specialization of strided_slice,
(5.2)
otherwise, last_<k>(src, slices...) - first_<IndexType, k>(slices...).

24.7.3.7.6 Layout specializations of submdspan_mapping [mdspan.submdspan.mapping]

🔗

template<class Extents>
  template<class... SliceSpecifiers>
    constexpr auto layout_left::mapping<Extents>::submdspan-mapping-impl(   // exposition only
      SliceSpecifiers... slices) const -> see below;

template<class Extents>
  template<class... SliceSpecifiers>
    constexpr auto layout_right::mapping<Extents>::submdspan-mapping-impl(  // exposition only
      SliceSpecifiers... slices) const -> see below;

template<class Extents>
  template<class... SliceSpecifiers>
    constexpr auto layout_stride::mapping<Extents>::submdspan-mapping-impl( // exposition only
      SliceSpecifiers... slices) const -> see below;

Let index_type be typename Extents::index_type.

Constraints: sizeof...(slices) equals Extents::rank().

Mandates: For each rank index k of extents(), exactly one of the following is true:

(3.1)
$S_{k}$ models convertible_to<index_type>,
(3.2)
$S_{k}$ models index-pair-like<index_type>,
(3.3)
is_convertible_v< $S_{k}$ , full_extent_t> is true, or
(3.4)
$S_{k}$ is a specialization of strided_slice.

Preconditions: For each rank index k of extents(), all of the following are true:

(4.1)
if $S_{k}$ is a specialization of strided_slice
- (4.1.1)
  $s_{k} .extent = 0$ , or
- (4.1.2)
  $s_{k} .stride > 0$
(4.2)
0 ≤ first_<index_type, k>(slices...)
0 ≤ last_<k>(extents(), slices...)
0 ≤ 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:

(6.1)
stride(k) * de-ice( $s_{k}$ .stride) if $S_{k}$ is a specialization of strided_slice and $s_{k}$ .stride < $s_{k}$ .extent;
(6.2)
otherwise, stride(k).

Let P be a parameter pack such that is_same_v<make_index_sequence<rank()>, index_sequence<
P...>> is true.

Let offset be a value of type size_t equal to (*this)(first_<index_type, P>(slices...)...).

Returns:

(9.1)
submdspan_mapping_result{*this, 0}, if Extents::rank() == 0 is true;
(9.2)
otherwise, submdspan_mapping_result{layout_left::mapping(sub_ext), offset}, if
- (9.2.1)
  layout_type is layout_left; and
- (9.2.2)
  for each k in the range [0, SubExtents::rank() - 1)), is_convertible_v< $S_{k}$ , full_extent_t> is true; and
- (9.2.3)
  for k equal to SubExtents::rank() - 1, $S_{k}$ models index-pair-like<index_type> or is_convertible_v< $S_{k}$ , full_extent_t> is true;
[Note 1:
If the above conditions are true, all $S_{k}$ with k larger than SubExtents::rank() - 1 are convertible to index_type.
— end note]
(9.3)
otherwise, submdspan_mapping_result{layout_right::mapping(sub_ext), offset}, if
- (9.3.1)
  layout_type is layout_right; and
- (9.3.2)
  for each k in the range [Extents::rank() - SubExtents::rank() + 1, Extents::rank()), is_convertible_v< $S_{k}$ , full_extent_t> is true; and
- (9.3.3)
  for k equal to Extents::rank() - SubExtents::rank(), $S_{k}$ models index-pair-like<index_type> or is_convertible_v< $S_{k}$ , full_extent_t> is true;
[Note 2:
If the above conditions are true, all $S_{k}$ with $k < Extents::rank() - SubExtents::rank()$ are convertible to index_type.
— end note]
(9.4)
otherwise, submdspan_mapping_result{layout_stride::mapping(sub_ext, sub_strides),
offset}.

24.7.3.7.7 submdspan function template [mdspan.submdspan.submdspan]

🔗

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:

(3.1)
sizeof...(slices) equals Extents::rank(), and
(3.2)
the expression submdspan_mapping(src.mapping(), slices...) is well-formed when treated as an unevaluated operand.

Mandates:

(4.1)
decltype(submdspan_mapping(src.mapping(), slices...)) is a specialization of submd-
span_mapping_result.
(4.2)
is_same_v<remove_cvref_t<decltype(sub_map_offset.mapping.extents())>, decltype(
submdspan_extents(src.mapping(), slices...))> is true.
(4.3)
For each rank index k of src.extents(), exactly one of the following is true:
- (4.3.1)
  $S_{k}$ models convertible_to<index_type>,
- (4.3.2)
  $S_{k}$ models index-pair-like<index_type>,
- (4.3.3)
  is_convertible_v< $S_{k}$ , full_extent_t> is true, or
- (4.3.4)
  $S_{k}$ is a specialization of strided_slice.

Preconditions:

(5.1)
For each rank index k of src.extents(), all of the following are true:
- (5.1.1)
  if $S_{k}$ is a specialization of strided_slice
  - (5.1.1.1)
    $s_{k} .extent = 0$ , or
  - (5.1.1.2)
    $s_{k} .stride > 0$
- (5.1.2)
  0 ≤ first_<index_type, k>(slices...) ≤ last_<k>(src.extents(), slices...) ≤
  src.extent(k)
(5.2)
sub_map_offset.mapping.extents() == submdspan_extents(src.mapping(), slices...)
is true; and
(5.3)
for each integer pack I which is a multidimensional index in sub_map_offset.mapping.extents(), 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: auto sub_map_offset = submdspan_mapping(src.mapping(), slices...); return mdspan(src.accessor().offset(src.data(), sub_map_offset.offset), sub_map_offset.mapping, 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.

// 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]