3.2.1   Template arguments

template <typename DataType, typename... Properties> class mdspan

DataType

Requires: Is a non-array type denoting the element type of the array.

Properties...

Effects: The domain index space rank, static extents, and identification of dynamic extents is determined from the extents member of the property pack. The domain to codomain mapping is determined by the remaining members of the property pack

3.2.2   Fundamental Types

[Note: If std::is_const<element_type> then references to codomain members are const. Extensions to access properties may cause reference to become a proxy type. --end note]

[Note: Integral types for dimensions and indexing are signed integers to avoid casting unsigned-to-signed for loop bounds and improve opportunities for optimizing loops. --end note]

3.2.3   Domain Observers

The multi-index domain space is the Cartesian product of the extents: [0..extent(0)) X [0..extent(1)) X ... X [0..extent(rank()-1)). Each extent may be statically (at compile time) or dynamically (at runtime) specified.

static constexpr int rank();

Returns: Rank of the multi-index domain.

static constexpr int rank_dynamic();

Returns: number of extents that are dynamic.

static constexpr index_type static_extent(int r);

Requires: 0 <= r

Returns: If 0 <= r < rank() the statically specified extent. A statically declared extent of dynamic_extent denotes that the extent is dynamic. If rank() <= r then static_extent(r) == 1.

constexpr index_type extent(int r) const ;

Requires: 0 <= r

Returns: If 0 <= r < rank() the extent of coordinate r. If rank() <= r then extent(r) == 1.

constexpr index_type size() const ;

Returns: product of extent(r) where 0 <= r < rank().

Given mdspan x then:

int d = 0 ;
index_type s = 1 ;
for ( int i = 0 ; i < x.rank() ; ++i ) {
  if ( x.static_extent(i) == std::dynamic_extent ) { ++d ; }
  s *= x.extent(i);
}
assert( d == x.rank_dynamic() );
assert( s == x.size() );

3.2.4   Codomain Observers

Not all members of the codomain may be accessible through the layout mapping; i.e., the range of the mapping is contained within the codomain but may not be equal to the codomain.

constexpr std::span<element_type> span() const ;

Returns: An std::span for the codomain.

Requires:

• rank_dynamic() <= sizeof...(DynamicExtents)
• is_integral_type_v<IndexType>...
• Denote the ith coordinate of DynamicExtents... as denoted as DynamicExtents[ith] then:
• 0 <= DynamicExtents[ith] for 0 <= ith < rank_dynanic()
• 1 == DynamicExtents[ith] for rank_dynamic() < ith

Returns: The minimum size of the codomain to support the multi-index domain defined by the merging of DynamicExents with StaticExtents.

Requires:

• rank_dynamic() <= N
• is_integral_type_v<IndexType>...
• 0 <= DynamicExtents[ith] for 0 <= ith < rank_dynanic()
• 1 == DynamicExtents[ith] for rank_dynamic() < ith

Returns: The minimum size of the codomain to support the multi-index domain defined by the merging of DynamicExents with StaticExtents.

3.2.5   Constructors, assignments, destructor

constexpr mdspan();

Effect: Construct a null mdspan with codomain span() == std::span<element_type>() and extent(r) == 0 for all dynamic extents.

Requires: Given using V = mdspan<DataType,Properties...> and using U = mdspan<UType,UProperties...> then

is_assignable<V::pointer,U::pointer> ,

V::rank() == U::rank() ,

V::static_extent(r) == U::static_extent(r) or V::static_extent(r) == std::dynamic_extent for 0 <= r < V::rank() ,

compatibility of layout mapping

Effect: * this has equal domain, equal codomain, and equivalent mapping.

Requires:

• sizeof...(DynamicExtents) == rank_dynamic()
• is_integral_type_v<IndexType>...
• The ith coordinate of DynamicExtents..., denoted as DynamicExtents[ith], is 0 <= DynamicExtents[ith].
• The span of elements denoted by [ ptr , ptr + required_span_size(DynamicExtents...) ), shall be a valid contiguous span of elements.

Effects: This wrapping constructor constructs * this with domain's dynamic extents equal to DynamicExtents... and codomain equal to std::span<element_type>( ptr , required_span_size(DynamicExtents...) )

Requires:

• N == rank_dynamic()
• is_integral_type_v<IndexType>...
• 0 <= DynamicExtents[ith]
• The span of elements denoted by [ ptr , ptr + required_span_size(DynamicExtents) ), shall be a valid contiguous span of elements.

Effects: This wrapping constructor constructs * this with domain's dynamic extents equal to DynamicExtents[ith]. and codomain equal to std::span<element_type>( ptr , required_span_size(DynamicExtents) )

Requires:

• sizeof...(DynamicExtents) == rank_dynamic()
• is_integral_type_v<IndexType>...
• The ith coordinate of DynamicExtents..., denoted as DynamicExtents[ith], is 0 <= DynamicExtents[ith]
• required_span_size(DynamicExtents...) <= s.size()

Effects: This wrapping constructor constructs * this with domain's dynamic extents equal to DynamicExtents... and codomain equal to std::span<element_type>( ptr , required_span_size(DynamicExtents...) )

Requires:

• N == rank_dynamic()
• is_integral_type_v<IndexType>...
• 0 <= DynamicExtents[ith]
• required_span_size(DynamicExtents) <= s.size()

Effects: This wrapping constructor constructs * this with domain's dynamic extents equal to DynamicExtents[ith] and codomain equal to std::span<element_type>( ptr , required_span_size(DynamicExtents[ith]) )

3.2.6   Mapping domain multi-index to access elements in the codomain

reference operator[]( index_type index ) const noexcept

Requires: rank() == 1 and 0 <= i < extent(0)

Returns: A reference to the element mapped to by index.

Requires: indices is a multi-index in the domain:

• rank() <= sizeof...(IndexType)
• The ith coordinate of indices..., denoted as indices[ith], is in the domain: 0 <= indices[ith] < extent(ith).
• [Note: Because extent(ith) == 1 for rank() <= ith then extra zero-value indices are valid. --end note]

Returns: A reference to the element mapped to by indices....

Remark: Optimization of the mapping operator is a critical feature of the multidimensional array implementation. Recommended optimizations include:

• Rank-specific overloads to better enable optimization of the member access operator.
• Inlining of a constexpr multi-index mapping expression that is not included in an optimizer's inlining budget.
• Compile-time evaluation statically determined portions of multi-index mapping expression.

Requires: indices is a multi-index in the domain:

• rank() <= N
• 0 <= indices[ith] < extent(ith).
• [Note: Because extent(ith) == 1 for rank() <= ith then extra zero-value indices are valid. --end note]

Returns: A reference to the element mapped to by indices....

Remark: Optimization of the mapping operator is a critical feature of the multidimensional array implementation. Recommended optimizations include:

• Rank-specific overloads to better enable optimization of the member access operator.
• Inlining of a constexpr multi-index mapping expression that is not included in an optimizer's inlining budget.
• Compile-time evaluation statically determined portions of multi-index mapping expression.

3.2.7   Mapping Observers

using layout = /* implmentation deduces from Properties... */ ;

Identification of the layout mapping. If Properties... does not include a layout property then layout is layout_right denoting the traditional C/C++ mapping.

A layout mapping is unique if each multi-index in the domain is mapped to a unique member in the codomain.

A layout mapping is contiguous if the codomain elements accessed through the layout mapping form a contiguous span.

A layout mapping that is both unique and contiguous is bijective and has size() == span().size().

A strided layout has constant striding between multi-index coordinates. Let A be an mdspan and indices_V... and indices_U... be multi-indices in the domain space such that all coordinates are equal except for the ith coordinate where indices_V[ith] = indices_U[ith] + 1. Then stride(ith) = distance(& A(indices_V...) - & A( indices_U... ) is constant for all coordinates.

Requires: is_strided().

Returns: When r < rank() the distance between members when the index of coordinate r is incremented by one, otherwise 0.

3.2.8   Mapping Observers - Alternative

The mapping observers could be provided instead through a mapping type and object.

template <typename DataType, typename... Properties>
class mdspan {
public:

  using layout  = /* extracted from Properties... */ ;
  using mapping = /* implementation defined */ ;

  const mapping & map() const noexcept ;

  struct mapping /* for exposition */ {

    using index_type = ptrdiff_t ;

    // observers of domain:

    static constexpr int rank() noexcept;
    static constexpr int rank_dynamic() noexcept;

    static constexpr index_type static_extent(int) noexcept;

    constexpr index_type extent(int) const noexcept;

    constexpr index_type size() const noexcept;

    // observers of the codomain: [0..span_size())

    constexpr index_type span_size() const noexcept;

    // observers of the mapping from domain to codomain

    static constexpr bool is_always_unique     = /* deduced */ ;
    static constexpr bool is_always_contiguous = /* deduced */ ;
    static constexpr bool is_always_strided    = /* deduced */ ;

    constexpr bool is_unique() const noexcept;
    constexpr bool is_contiguous() const noexcept;
    constexpr bool is_strided() noexcept;

    constexpr index_type stride(int) const ;
  };
};

3.4.1   Slice Specifier with Static Extent

The proposed initializer_list, pair, tuple, and array slice specifier types define dynamic extents. When the all slice specifier references a static extent then the subspan's corresponding extent should be static as well. When the extent of a slice specifier is statically known there should be a slice specifier type to explicitly express this knowledge. Such a static extent slice specifier type is to-be-done.

3.5.1   Predefined, Standard Layouts

The layout_right property denotes the C/C++ standard multidimensional array index mapping where the right-most extent is stride one and strides increase right-to-left as the product of extents.

The layout_left property denotes the FORTRAN standard multidimensional array index mapping where the left-most extent is stride one and strides increase left-to-right as the product of extents.

The layout_stride property denotes a multidimensional array index mapping with arbitrary strides for each extent. This is the layout for subarrays that are not contiguous.

The three standard layouts have the following layout mapping traits.

layout_right ; i.e., the C/C++ standard layout

is_always_unique == true

is_always_contiguous == true

is_always_strided == true

When 0 < rank() then stride(rank()-1) == 1 .

When 1 < rank() then stride(r-1) = stride(r) * extent(r) for 0 < r < rank() ..

For rank-two arrays (a.k.a., matrices) this is also known as row major layout.

layout_left ; i.e., the FORTRAN standard layout

is_always_unique == true

is_always_contiguous == true

is_always_strided == true

When 0 < rank() then stride(0) == 1 .

When 1 < rank() then stride(r) = stride(r-1) * extent(r-1) for 0 < r < rank() ..

For rank-two arrays (a.k.a., matrices) this is also known as column major layout.

layout_stride ; i.e., an arbitrary strided layout

is_always_unique == false

is_always_contiguous == false

is_always_strided == true

3.5.2   Concept for Extensible Layout Mapping

A layout class conforms to the following interface such that an mdspan can compose the layout mapping with its mdspan codomain member reference generation.

class layout_concept /* exposition only */ {
public:

  template< ptrdiff_t ... StaticExtents >
  class mapping {
  public:

    // domain types

    using index_type = ptrdiff_t ;

    // constructors, copy, assignment, and destructor

    ~mapping() noexcept = default ;
    constexpr mapping() noexcept = default ;
    constexpr mapping(mapping const&) noexcept = default ;
    mapping& operator=(mapping const&) noexcept = default ;

    // observers of domain

    static constexpr int rank() noexcept;
    static constexpr int rank_dynamic() noexcept;

    static constexpr index_type static_extent(int) noexcept;

    constexpr index_type extent(int) const noexcept;

    constexpr index_type size() const noexcept;

    // observers of the codomain: [0..span_size())

    constexpr index_type span_size() const noexcept;

    // observers of the mapping from domain to codomain

    static constexpr bool is_always_unique     = /* deduced */ ;
    static constexpr bool is_always_contiguous = /* deduced */ ;
    static constexpr bool is_always_strided    = /* deduced */ ;

    constexpr bool is_unique() const noexcept;
    constexpr bool is_contiguous() const noexcept;
    constexpr bool is_strided() noexcept;

    constexpr index_type stride(int) const noexcept;

    // mapping domain index to access codomain element

    template< class ... IndexType >
    constexpr index_type operator()( IndexType ... indices ) const noexcept;
  };
};

template< ptrdiff_t ... StaticExtents > class mapping

Requires: Let StaticExtents[ith] be the ith member of the pack. StaticExtents[ith] == std::dynamic_extent or 0 <= StaticExtents[ith].

Effects: Defines the domain index space where rank() == sizeof...(StaticExtents) and each StaticExtents[ith] == std::dynamic_extent denotes that ith extent coordinate is a dynamic extent.

constexpr mapping();

Effects: If static_extent(i) != std::dynamic_extent then extent(i) == static_extent(i) otherwise extent(i) == 0.

Constructors, assignment operators, and destructor requires and effects correspond to the corresponding members of mdspan .

Domain, codomain, and mapping observers requires and effects correspond to the corresponding members of mdspan .

Requires: rank() == sizeof...(indices) and 0 <= indices[ith] < extent(ith).

Returns: Layout mapping of indices... to codomain.