cppdraft_translate/cppdraft/mdspan/accessor.md

[mdspan.accessor]

23 Containers library [containers]

23.7 Views [views]

23.7.3 Multidimensional access [views.multidim]

23.7.3.5 Accessor policy [mdspan.accessor]

23.7.3.5.1 General [mdspan.accessor.general]

1

#

An accessor policy defines types and operations by which a reference to a single object is created from an abstract data handle to a number of such objects and an index.

2

#

A range of indices [0,N) is an accessible range of a given data handle and an accessor if, for each i in the range, the accessor policy's access function produces a valid reference to an object.

3

#

In [mdspan.accessor.reqmts],

• (3.1)

  A denotes an accessor policy.

• (3.2)

  a denotes a value of type A or const A.

• (3.3)

  p denotes a value of type A​::​data_handle_type or const A​::​data_handle_type. [Note 1: The type A​::​data_handle_type need not be dereferenceable. — end note]

• (3.4)

  n, i, and j each denote values of type size_t.

23.7.3.5.2 Requirements [mdspan.accessor.reqmts]

1

#

A type A meets the accessor policy requirements if

• (1.1)

A models copyable,

• (1.2)

is_nothrow_move_constructible_v is true,

• (1.3)

is_nothrow_move_assignable_v is true,

• (1.4)

is_nothrow_swappable_v is true, and

• (1.5)

the following types and expressions are well-formed and have the specified semantics.

🔗

typename A::element_type

2

#

Result: A complete object type that is not an abstract class type.

🔗

typename A::data_handle_type

3

#

Result: A type that models copyable, and for which is_nothrow_move_constructible_v<A​::​data_handle_type> is true,is_nothrow_move_assignable_v<A​::​data_handle_type> is true, andis_nothrow_swappable_v<A​::​data_handle_type> is true.

[Note 1:

The type of data_handle_type need not be element_type*.

— end note]

🔗

typename A::reference

4

#

Result: A type that modelscommon_reference_with<A​::​reference&&, A​::​element_type&>.

[Note 2:

The type of reference need not be element_type&.

— end note]

🔗

typename A::offset_policy

5

#

Result: A type OP such that:

• (5.1)

OP meets the accessor policy requirements,

• (5.2)

constructible_from<OP, const A&> is modeled, and

• (5.3)

is_same_v<typename OP​::​element_type, typename A​::​element_type> is true.

🔗

a.access(p, i)

6

#

Result: A​::​reference

7

#

Remarks: The expression is equality preserving.

8

#

[Note 3:

Concrete accessor policies can impose preconditions for their access function.

However, they might not.

For example, an accessor wherep is span<A​::​element_type, dynamic_extent> andaccess(p, i) returns p[i % p.size()] does not need to impose a precondition on i.

— end note]

🔗

a.offset(p, i)

9

#

Result: A​::​offset_policy​::​data_handle_type

10

#

Returns: q such that for b being A​::​offset_policy(a), and any integer n for which [0, n) is an accessible range of p and a:

• (10.1)

[0,n−i) is an accessible range of q and b; and

• (10.2)

b.access(q, j) provides access to the same element as a.access(p, i + j), for every j in the range [0,n−i).

11

#

Remarks: The expression is equality-preserving.

23.7.3.5.3 Class template default_accessor [mdspan.accessor.default]

23.7.3.5.3.1 Overview [mdspan.accessor.default.overview]

namespace std {templatestruct default_accessor {using offset_policy = default_accessor; using element_type = ElementType; using reference = ElementType&; using data_handle_type = ElementType*; constexpr default_accessor() noexcept = default; templateconstexpr default_accessor(default_accessor) noexcept; constexpr reference access(data_handle_type p, size_t i) const noexcept; constexpr data_handle_type offset(data_handle_type p, size_t i) const noexcept; };}

1

#

default_accessor meets the accessor policy requirements.

2

#

ElementType is required to be a complete object type that is neither an abstract class type nor an array type.

3

#

Each specialization of default_accessor is a trivially copyable type that models semiregular.

4

#

[0,n) is an accessible range for an object p of type data_handle_type and an object of type default_accessor if and only if [p, p + n) is a valid range.

23.7.3.5.3.2 Members [mdspan.accessor.default.members]

🔗

template<class OtherElementType> constexpr default_accessor(default_accessor<OtherElementType>) noexcept {}

1

#

Constraints: is_convertible_v<OtherElementType()[], element_type()[]> is true.

🔗

constexpr reference access(data_handle_type p, size_t i) const noexcept;

2

#

Effects: Equivalent to: return p[i];

🔗

constexpr data_handle_type offset(data_handle_type p, size_t i) const noexcept;

3

#

Effects: Equivalent to: return p + i;

23.7.3.5.4 Class template aligned_accessor [mdspan.accessor.aligned]

23.7.3.5.4.1 Overview [mdspan.accessor.aligned.overview]

namespace std {template<class ElementType, size_t ByteAlignment>struct aligned_accessor {using offset_policy = default_accessor; using element_type = ElementType; using reference = ElementType&; using data_handle_type = ElementType*; static constexpr size_t byte_alignment = ByteAlignment; constexpr aligned_accessor() noexcept = default; template<class OtherElementType, size_t OtherByteAlignment>constexpr aligned_accessor( aligned_accessor<OtherElementType, OtherByteAlignment>) noexcept; templateconstexpr explicit aligned_accessor(default_accessor) noexcept; templateconstexpr operator default_accessor() const noexcept; constexpr reference access(data_handle_type p, size_t i) const noexcept; constexpr typename offset_policy::data_handle_type offset( data_handle_type p, size_t i) const noexcept; };}

1

#

Mandates:

• (1.1)

byte_alignment is a power of two, and

• (1.2)

byte_alignment >= alignof(ElementType) is true.

2

#

aligned_accessor meets the accessor policy requirements.

3

#

ElementType is required to be a complete object type that is neither an abstract class type nor an array type.

4

#

Each specialization of aligned_accessor is a trivially copyable type that models semiregular.

5

#

[0, n) is an accessible range for an object p of type data_handle_type and an object of type aligned_accessor if and only if

• (5.1)

[p, p + n) is a valid range, and,

• (5.2)

if n is greater than zero, then is_sufficiently_aligned<byte_alignment>(p) is true.

6

#

[Example 1:

The following function compute uses is_sufficiently_aligned to check whether a given mdspan with default_accessor has a data handle with sufficient alignment to be used with aligned_accessor<float, 4 * sizeof(float)>.

If so, the function dispatches to a function compute_using_fourfold_overalignment that requires fourfold over-alignment of arrays, but can therefore use hardware-specific instructions, such as four-wide SIMD (Single Instruction Multiple Data) instructions.

Otherwise, compute dispatches to a possibly less optimized function compute_without_requiring_overalignment that has no over-alignment requirement.

void compute_using_fourfold_overalignment( std::mdspan<float, std::dims<1>, std::layout_right, std::aligned_accessor<float, 4 * alignof(float)>> x);

void compute_without_requiring_overalignment( std::mdspan<float, std::dims<1>, std::layout_right> x);

void compute(std::mdspan<float, std::dims<1>> x) {constexpr auto byte_alignment = 4 * sizeof(float); auto accessor = std::aligned_accessor<float, byte_alignment>{}; auto x_handle = x.data_handle(); if (std::is_sufficiently_aligned<byte_alignment>(x_handle)) { compute_using_fourfold_overalignment(std::mdspan{x_handle, x.mapping(), accessor}); } else { compute_without_requiring_overalignment(x); }} — end example]

23.7.3.5.4.2 Members [mdspan.accessor.aligned.members]

🔗

template<class OtherElementType, size_t OtherByteAlignment> constexpr aligned_accessor(aligned_accessor<OtherElementType, OtherByteAlignment>) noexcept;

1

#

Constraints:

• (1.1)

  is_convertible_v<OtherElementType()[], element_type()[]> is true.

• (1.2)

  OtherByteAlignment >= byte_alignment is true.

2

#

Effects: None.

🔗

template<class OtherElementType> constexpr explicit aligned_accessor(default_accessor<OtherElementType>) noexcept;

3

#

Constraints: is_convertible_v<OtherElementType()[], element_type()[]> is true.

4

#

Effects: None.

🔗

constexpr reference access(data_handle_type p, size_t i) const noexcept;

5

#

Preconditions: [0, i + 1) is an accessible range for p and *this.

6

#

Effects: Equivalent to: return assume_aligned<byte_alignment>(p)[i];

🔗

template<class OtherElementType> constexpr operator default_accessor<OtherElementType>() const noexcept;

7

#

Constraints: is_convertible_v<element_type()[], OtherElementType()[]> is true.

8

#

Effects: Equivalent to: return {};

🔗

constexpr typename offset_policy::data_handle_type offset(data_handle_type p, size_t i) const noexcept;

9

#

Preconditions: [0, i + 1) is an accessible range for p and *this.

10

#

Effects: Equivalent to: return assume_aligned<byte_alignment>(p) + i;