# C++ named requirements: LayoutMapping (since C++23)

> C++ Atlas: `cppatlas.com/w/cpp/named_req/LayoutMapping` | Source: https://en.cppreference.com/w/cpp/named_req/LayoutMapping | Domain: Named Requirements

LayoutMapping controls the mapping of a multidimensional index to a one-dimensional offset to data handle in std::mdspan.

## Official Specification Summary (cppreference)

*LayoutMapping* controls the mapping of a multidimensional index to a one-dimensional offset to data handle in `std::mdspan`.

### Requirements

A type `M` satisfies *LayoutMapping* if it models `copyable` and `equality_comparable`, and the following are `true`:

- `std::is_nothrow_move_constructible_v<M>`
- `std::is_nothrow_move_assignable_v<M>`
- `std::is_nothrow_swappable_v<M>`

And, given the following types and values, the expressions shown in the table below are valid and have the indicated semantics:

#### Legend

**Type — Definition**

- `M`: a layout mapping class

**Value — Definition**

- `m`: a value of type (possibly const-qualified) `M`
- `i`, `j`: packs of (possibly const-qualified) integers that are multidimensional indices in `m.extents()`
- `r`: a (possibly const-qualified) rank index of `typename M​::​extents_type`
- `d_r`: a pack of (possibly const-qualified) integers for which `sizeof...(d_r) == M​::​extents_type​::​rank()` is `true`, the element at rank index `r` is equal to `1`, and all other elements are equal to `​0​`

#### Member types

| Name | Type | Requirements |
| --- | --- | --- |
| `M::extents_type` | Specialization of class template `std::extents` |   |
| `M::index_type` | `typename M::extents_type::index_type` |   |
| `M::rank_type` | `typename M::extents_type::rank_type` |   |
| `M::layout_type` | Layout mapping policy `MP` where `typename MP::template mapping<E>` is `M` for some extents type `E` | *LayoutMappingPolicy* for which `M` is mapping type of `MP` |

#### Member functions and operators

| Expression | Return type | Semantics |
| --- | --- | --- |
| `m.extents()` | `const typename M​::​extents_type&` | Returns constant reference to associated multidimensional index space |
| `m(i...)` | `typename M​::​index_type` | - Returns a nonnegative integer `o` such that `o < std::numeric_limits<typename M​::​index_type>​::​max()` and `o <= std::numeric_limits<std::size_t>​::​max()` are both `true`. - Such expression is equivalent to `m(static_cast<typename M::index_type>(i)...)`. |
| `m.required_span_size()` | `typename M​::​index_type` | - Returns `1` plus the maximum value of `m(i...)` for all `i` if the size of the multidimensional index space `m.extents()` is not 0. - Otherwise, returns `​0​`. |
| `m.is_unique()` | `bool` | Returns `true` only if for every `i` and `j` where `(i != j \|\|...)` is `true`, `m(i...) != m(j...)` is `true`. [note 1] |
| `m.is_exhaustive()` | `bool` | Returns `true` only if for all `k` in the range `[​0​,` `m.required_span_size())`, there exists an `i` such that `m(i...)` equals `k`. [note 2] |
| `m.is_strided()` | `bool` | Returns `true` only if for every rank index `r` of `m.extents()`, there exists an integer `s_r` such that, for all `i` where `(i + d_r)` is a multidimensional index in `m.extents()`, `m((i + d_r)...) - m(i...)` equals `s_r`. [note 3] |
| `m.stride(r)` | `typename M​::​index_type` | - The precondition is that `m.is_strided()` is `true`. - Returns a stride `s_r` at rank index `r` as defined in `m.is_strided()` above. |
| `M::is_always_unique()` | `bool` | - Returns `true` only if `m.is_unique()` is `true` for all possible objects `m` of type `M`. [note 4] - The return value is always a constant expression. |
| `M::is_always_exhaustive()` | `bool` | - Returns `true` only if `m.is_exhaustive()` is `true` for all possible objects `m` of type `M`. [note 5] - The return value is always a constant expression. |
| `M::is_always_strided()` | `bool` | - Returns `true` only if `m.is_strided()` is `true` for all possible objects `m` of type `M`. [note 6] - The return value is always a constant expression. |

1. ↑ A mapping can return `false` even if the condition is met. For certain layouts, it is possibly not feasible to determine efficiently whether the layout is unique.
2. ↑ Same as above, but in the case of exhaustive layouts.
3. ↑ Same as above, but in the case of strided layouts.
4. ↑ A mapping can return `false` even if the condition is met. For certain layout mappings, it is possibly not feasible to determine whether every instance is unique.
5. ↑ Same as above, but in the case of exhaustive instances.
6. ↑ Same as above, but in the case of strided instances.

### Concept

For the constraints uses under `std::layout_stride::mapping`, the following exposition-only concept is defined.

```cpp
template< class M >
concept /*layout-mapping-alike*/ = requires
{
    requires /*is-extents*/<typename M::extents_type>;
    { M::is_always_strided() }    -> std::same_as<bool>;
    { M::is_always_exhaustive() } -> std::same_as<bool>;
    { M::is_always_unique() }     -> std::same_as<bool>;
    std::bool_constant<M::is_always_strided()>::value;
    std::bool_constant<M::is_always_exhaustive()>::value;
    std::bool_constant<M::is_always_unique()>::value;
}; // (exposition only*)
```

Defines the minimal usability constraints of the *LayoutMapping* requirement. This concept checks that the predicate mapping trait functions above exist, are constant expressions, and have a return type of `bool`.

`/*is-extents*/<E>` is `true` if and only if `E` is a specialization of `std::extents`.

### Standard library

The following standard library types satisfy *LayoutMapping* requirements:

- `mapping`: a layout mapping of `layout_left` (public member class template of `std::layout_left`)
- `mapping`: a layout mapping of `layout_right` (public member class template of `std::layout_right`)
- `mapping`: a layout mapping of `layout_stride` (public member class template of `std::layout_stride`)
- `mapping`: a layout mapping of `layout_left_padded` (public member class template of `std::layout_left_padded<PaddingValue>`)
- `mapping`: a layout mapping of `layout_right_padded` (public member class template of `std::layout_right_padded<PaddingValue>`)

### See also

- [*LayoutMappingPolicy*](https://en.cppreference.com/w/cpp/named_req/LayoutMappingPolicy)

---
Attribution: content from https://en.cppreference.com/w/cpp/named_req/LayoutMapping (cppreference.com), licensed under CC-BY-SA 3.0 and GFDL. Modified: converted to markdown, study notes added. Offline snapshot of 9 February 2025.