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:
  • 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 be the element of slices;
  • let be the type of ; and
  • let map-rank be an array<size_t, rank> such that for each k in the range [0, rank), map-rank[k] equals:

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 denote the following value:
Preconditions: is representable as a value of type IndexType.
Returns: extents<IndexType>​::​index-cast().
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() + 1 if models convertible_to<index_type>; otherwise
  • get<1>() if models index-pair-like<index_type>; otherwise
  • de-ice(.offset) + de-ice(.extent) if is a specialization of strided_slice; otherwise
  • src.extent(k).
Preconditions: is representable as a value of type index_type.
Returns: Extents​::​index-cast().
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]].

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:
Preconditions: For each rank index k of src.extents(), all of the following are true:
  • if is a specialization of strided_slice
  • 0  ≤ first_<IndexType, k>(slices...)  ≤ 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 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<, full_extent_t> is true; otherwise
    • de-ice(tuple_element_t<1, >()) - de-ice(tuple_element_t<0, >()) if models index-pair-like<IndexType>, and both tuple_element_t<0, > and tuple_element_t<1, > model integral-constant-like; otherwise
    • 0, if is a specialization of strided_slice, whose extent_type models integral-constant-like, for which extent_type() equals zero; otherwise
    • 1 + (de-ice(​::​extent_type()) - 1) / de-ice(​::​stride_type()), if 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:
  • .extent == 0 ? 0 : 1 + (de-ice(.extent) - 1) / de-ice(.stride) if is a specialization of strided_slice,
  • 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:
Preconditions: For each rank index k of extents(), all of the following are true:
  • if is a specialization of strided_slice
  • 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:
  • stride(k) * de-ice(.stride) if is a specialization of strided_slice and .stride < .extent;
  • 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:
  • submdspan_mapping_result{*this, 0}, if Extents​::​rank() == 0 is true;
  • otherwise, submdspan_mapping_result{layout_left​::​mapping(sub_ext), offset}, if
    • layout_type is layout_left; and
    • for each k in the range [0, SubExtents​::​rank() - 1)), is_convertible_v<, full_extent_t> is true; and
    • for k equal to SubExtents​::​rank() - 1, models index-pair-like<index_type> or is_convertible_v<, full_extent_t> is true;
    [Note 1: 
    If the above conditions are true, all with k larger than SubExtents​::​rank() - 1 are convertible to index_type.
    — end note]
  • otherwise, submdspan_mapping_result{layout_right​::​mapping(sub_ext), offset}, if
    • layout_type is layout_right; and
    • for each k in the range [Extents​::​rank() - SubExtents​::​rank() + 1, Extents​::​rank()), is_convertible_v<, full_extent_t> is true; and
    • for k equal to Extents​::​rank() - SubExtents​::​rank(), models index-pair-like<index_type> or is_convertible_v<, full_extent_t> is true;
    [Note 2: 
    If the above conditions are true, all with are convertible to index_type.
    — end note]
  • 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:
  • 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:
Preconditions:
  • For each rank index k of src.extents(), all of the following are true:
    • if is a specialization of strided_slice
    • 0  ≤ first_<index_type, k>(slices...)  ≤ 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(), 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]