P3383R3 mdspan.at()

Fixes #7951
Fixes cplusplus/papers#2040

Author: AlisdairM

source/containers.tex

@@ -21034,7 +21034,7 @@
 
 \indexheader{mdspan}%
 \begin{codeblock}
-// all freestanding
+// mostly freestanding
 namespace std {
   // \ref{mdspan.extents}, class template \tcode{extents}
   template<class IndexType, size_t... Extents>
@@ -21068,7 +21068,7 @@
   // \ref{mdspan.mdspan}, class template \tcode{mdspan}
   template<class ElementType, class Extents, class LayoutPolicy = layout_right,
            class AccessorPolicy = default_accessor<ElementType>>
-    class mdspan;
+    class mdspan;                                                           // partially freestanding
 
   // \ref{mdspan.sub}, \tcode{submdspan} creation
   template<class OffsetType, class LengthType, class StrideType>
@@ -24691,6 +24691,13 @@
     template<class OtherIndexType>
       constexpr reference operator[](const array<OtherIndexType, rank()>& indices) const;
 
+    template<class... OtherIndexTypes>
+      constexpr reference at(OtherIndexTypes... indices) const;                   // freestanding-deleted
+    template<class OtherIndexType>
+      constexpr reference at(span<OtherIndexType, rank()> indices) const;         // freestanding-deleted
+    template<class OtherIndexType>
+      constexpr reference at(const array<OtherIndexType, rank()>& indices) const; // freestanding-deleted
+
     constexpr size_type size() const noexcept;
     constexpr bool empty() const noexcept;
 
@@ -25139,6 +25146,67 @@
 \end{codeblock}
 \end{itemdescr}
 
+\indexlibrarymember{at}{mdspan}%
+\begin{itemdecl}
+template<class... OtherIndexTypes>
+  constexpr reference at(OtherIndexTypes... indices) const;
+\end{itemdecl}
+
+\begin{itemdescr}
+\pnum
+\constraints
+\begin{itemize}
+\item
+\tcode{(is_convertible_v<OtherIndexTypes, index_type> \&\& ...)} is \tcode{true},
+\item
+\tcode{(is_nothrow_constructible_v<index_type, OtherIndexTypes> \&\& ...)} is \tcode{true}, and
+\item
+\tcode{sizeof...(OtherIndexTypes) == rank()}  is \tcode{true}.
+\end{itemize}
+
+\pnum
+Let \tcode{I} be \tcode{extents_type::\exposid{index-cast}(std::move(indices))}.
+
+\pnum
+\returns
+\tcode{(*this)[I...]}.
+
+\pnum
+\throws
+\tcode{out_of_range} if \tcode{I} is not a multidimensional index in \tcode{extents()}.
+\end{itemdescr}
+
+\indexlibrarymember{at}{mdspan}%
+\begin{itemdecl}
+template<class OtherIndexType>
+  constexpr reference at(span<OtherIndexType, rank()> indices) const;
+template<class OtherIndexType>
+  constexpr reference at(const array<OtherIndexType, rank()>& indices) const;
+\end{itemdecl}
+
+\begin{itemdescr}
+\pnum
+\constraints
+\begin{itemize}
+\item
+\tcode{is_convertible_v<const OtherIndexType\&, index_type>} is \tcode{true}, and
+\item
+\tcode{is_nothrow_constructible_v<index_type, const OtherIndexType\&>} is \tcode{true}.
+\end{itemize}
+
+\pnum
+\effects
+Let \tcode{P} be a parameter pack such that
+\begin{codeblock}
+is_same_v<make_index_sequence<rank()>, index_sequence<P...>>
+\end{codeblock}
+is \tcode{true}.
+Equivalent to:
+\begin{codeblock}
+return at(extents_type::@\exposid{index-cast}@(as_const(indices[P]))...);
+\end{codeblock}
+\end{itemdescr}
+
 \indexlibrarymember{size}{mdspan}%
 \begin{itemdecl}
 constexpr size_type size() const noexcept;