Merge 2019-02 LWG Motion 17

P1024R3 Usability Enhancements for std::span

Fixes #2708.

Author: zygoloid

source/containers.tex

@@ -10292,6 +10292,18 @@
   template<class ElementType, size_t Extent>
     span<byte, Extent == dynamic_extent ? dynamic_extent : sizeof(ElementType) * Extent>
       as_writable_bytes(span<ElementType, Extent> s) noexcept;
+
+  // \ref{span.tuple}, tuple interface
+  template<class T> class tuple_size;
+  template<size_t I, class T> class tuple_element;
+  template<class ElementType, size_t Extent>
+    struct tuple_size<span<ElementType, Extent>>;
+  template<class ElementType>
+    struct tuple_size<span<ElementType, dynamic_extent>>;       // not defined
+  template<size_t I, class ElementType, size_t Extent>
+    struct tuple_element<I, span<ElementType, Extent>>;
+  template<size_t I, class ElementType, size_t Extent>
+    constexpr ElementType& get(span<ElementType, Extent>) noexcept;
 }
 \end{codeblock}
 
@@ -10377,11 +10389,12 @@
     // \ref{span.obs}, observers
     constexpr index_type size() const noexcept;
     constexpr index_type size_bytes() const noexcept;
-    constexpr bool empty() const noexcept;
+    [[nodiscard]] constexpr bool empty() const noexcept;
 
     // \ref{span.elem}, element access
     constexpr reference operator[](index_type idx) const;
-    constexpr reference operator()(index_type idx) const;
+    constexpr reference front() const;
+    constexpr reference back() const;
     constexpr pointer data() const noexcept;
 
     // \ref{span.iterators}, iterator support
@@ -10425,6 +10438,7 @@
 \begin{itemdecl}
 constexpr span() noexcept;
 \end{itemdecl}
+
 \begin{itemdescr}
 \pnum
 \constraints
@@ -10439,6 +10453,7 @@
 \begin{itemdecl}
 constexpr span(pointer ptr, index_type count);
 \end{itemdecl}
+
 \begin{itemdescr}
 \pnum
 \expects \range{ptr}{ptr + count} is a valid range.
@@ -10462,6 +10477,7 @@
 \begin{itemdecl}
 constexpr span(pointer first, pointer last);
 \end{itemdecl}
+
 \begin{itemdescr}
 \pnum
 \expects
@@ -10488,6 +10504,7 @@
 template<size_t N> constexpr span(array<value_type, N>& arr) noexcept;
 template<size_t N> constexpr span(const array<value_type, N>& arr) noexcept;
 \end{itemdecl}
+
 \begin{itemdescr}
 \pnum
 \constraints
@@ -10510,6 +10527,7 @@
 template<class Container> constexpr span(Container& cont);
 template<class Container> constexpr span(const Container& cont);
 \end{itemdecl}
+
 \begin{itemdescr}
 \pnum
 \constraints
@@ -10543,6 +10561,7 @@
 \begin{itemdecl}
 constexpr span(const span& other) noexcept = default;
 \end{itemdecl}
+
 \begin{itemdescr}
 \pnum
 \ensures
@@ -10554,6 +10573,7 @@
 template<class OtherElementType, size_t OtherExtent>
   constexpr span(const span<OtherElementType, OtherExtent>& s) noexcept;
 \end{itemdecl}
+
 \begin{itemdescr}
 \pnum
 \constraints
@@ -10576,6 +10596,7 @@
 \begin{itemdecl}
 constexpr span& operator=(const span& other) noexcept = default;
 \end{itemdecl}
+
 \begin{itemdescr}
 \pnum
 \ensures
@@ -10588,6 +10609,7 @@
 \begin{itemdecl}
 template<size_t Count> constexpr span<element_type, Count> first() const;
 \end{itemdecl}
+
 \begin{itemdescr}
 \pnum
 \expects
@@ -10602,6 +10624,7 @@
 \begin{itemdecl}
 template<size_t Count> constexpr span<element_type, Count> last() const;
 \end{itemdecl}
+
 \begin{itemdescr}
 \pnum
 \expects
@@ -10617,6 +10640,7 @@
 template<size_t Offset, size_t Count = dynamic_extent>
   constexpr span<element_type, @\seebelow@> subspan() const;
 \end{itemdecl}
+
 \begin{itemdescr}
 \pnum
 \expects
@@ -10647,6 +10671,7 @@
 \begin{itemdecl}
 constexpr span<element_type, dynamic_extent> first(index_type count) const;
 \end{itemdecl}
+
 \begin{itemdescr}
 \pnum
 \expects
@@ -10661,6 +10686,7 @@
 \begin{itemdecl}
 constexpr span<element_type, dynamic_extent> last(index_type count) const;
 \end{itemdecl}
+
 \begin{itemdescr}
 \pnum
 \expects
@@ -10676,6 +10702,7 @@
 constexpr span<element_type, dynamic_extent> subspan(
   index_type offset, index_type count = dynamic_extent) const;
 \end{itemdecl}
+
 \begin{itemdescr}
 \pnum
 \expects
@@ -10698,6 +10725,7 @@
 \begin{itemdecl}
 constexpr index_type size() const noexcept;
 \end{itemdecl}
+
 \begin{itemdescr}
 \pnum
 \effects
@@ -10708,6 +10736,7 @@
 \begin{itemdecl}
 constexpr index_type size_bytes() const noexcept;
 \end{itemdecl}
+
 \begin{itemdescr}
 \pnum
 \effects
@@ -10716,8 +10745,9 @@
 
 \indexlibrarymember{span}{empty}%
 \begin{itemdecl}
-constexpr bool empty() const noexcept;
+[[nodiscard]] constexpr bool empty() const noexcept;
 \end{itemdecl}
+
 \begin{itemdescr}
 \pnum
 \effects
@@ -10727,11 +10757,10 @@
 \rSec3[span.elem]{Element access}
 
 \indexlibrary{\idxcode{operator[]}!\idxcode{span}}%
-\indexlibrary{\idxcode{operator()}!\idxcode{span}}%
 \begin{itemdecl}
 constexpr reference operator[](index_type idx) const;
-constexpr reference operator()(index_type idx) const;
 \end{itemdecl}
+
 \begin{itemdescr}
 \pnum
 \expects
@@ -10742,10 +10771,41 @@
 Equivalent to: \tcode{return *(data() + idx);}
 \end{itemdescr}
 
+\indexlibrarymember{span}{front}%
+\begin{itemdecl}
+constexpr reference front() const;
+\end{itemdecl}
+
+\begin{itemdescr}
+\pnum
+\expects
+\tcode{empty()} is \tcode{false}.
+
+\pnum
+\effects
+Equivalent to: \tcode{return *data();}
+\end{itemdescr}
+
+\indexlibrarymember{span}{back}%
+\begin{itemdecl}
+constexpr reference back() const;
+\end{itemdecl}
+
+\begin{itemdescr}
+\pnum
+\expects
+\tcode{empty()} is \tcode{false}.
+
+\pnum
+\effects
+Equivalent to: \tcode{return *(data() + (size() - 1));}
+\end{itemdescr}
+
 \indexlibrarymember{span}{data}%
 \begin{itemdecl}
 constexpr pointer data() const noexcept;
 \end{itemdecl}
+
 \begin{itemdescr}
 \pnum
 \effects
@@ -10758,6 +10818,7 @@
 \begin{itemdecl}
 constexpr iterator begin() const noexcept;
 \end{itemdecl}
+
 \begin{itemdescr}
 \pnum
 \returns
@@ -10770,6 +10831,7 @@
 \begin{itemdecl}
 constexpr iterator end() const noexcept;
 \end{itemdecl}
+
 \begin{itemdescr}
 \pnum
 \returns
@@ -10780,6 +10842,7 @@
 \begin{itemdecl}
 constexpr reverse_iterator rbegin() const noexcept;
 \end{itemdecl}
+
 \begin{itemdescr}
 \pnum
 \effects
@@ -10790,6 +10853,7 @@
 \begin{itemdecl}
 constexpr reverse_iterator rend() const noexcept;
 \end{itemdecl}
+
 \begin{itemdescr}
 \pnum
 \returns
@@ -10800,6 +10864,7 @@
 \begin{itemdecl}
 constexpr const_iterator cbegin() const noexcept;
 \end{itemdecl}
+
 \begin{itemdescr}
 \pnum
 \returns
@@ -10812,6 +10877,7 @@
 \begin{itemdecl}
 constexpr const_iterator cend() const noexcept;
 \end{itemdecl}
+
 \begin{itemdescr}
 \pnum
 \returns
@@ -10822,6 +10888,7 @@
 \begin{itemdecl}
 constexpr const_reverse_iterator crbegin() const noexcept;
 \end{itemdecl}
+
 \begin{itemdescr}
 \pnum
 \effects
@@ -10832,6 +10899,7 @@
 \begin{itemdecl}
 constexpr const_reverse_iterator crend() const noexcept;
 \end{itemdecl}
+
 \begin{itemdescr}
 \pnum
 \effects
@@ -10847,6 +10915,7 @@
   span<const byte, Extent == dynamic_extent ? dynamic_extent : sizeof(ElementType) * Extent>
     as_bytes(span<ElementType, Extent> s) noexcept;
 \end{itemdecl}
+
 \begin{itemdescr}
 \pnum
 \effects
@@ -10859,6 +10928,7 @@
   span<byte, Extent == dynamic_extent ? dynamic_extent : sizeof(ElementType) * Extent>
     as_writable_bytes(span<ElementType, Extent> s) noexcept;
 \end{itemdecl}
+
 \begin{itemdescr}
 \pnum
 \constraints
@@ -10868,3 +10938,44 @@
 \effects
 Equivalent to: \tcode{return \{reinterpret_cast<byte*>(s.data()), s.size_bytes()\};}
 \end{itemdescr}
+
+\rSec3[span.tuple]{Tuple interface}
+
+\indexlibrary{\idxcode{tuple_size}}%
+\begin{itemdecl}
+template<class ElementType, size_t Extent>
+  struct tuple_size<span<ElementType, Extent>>
+    : integral_constant<size_t, Extent> { };
+\end{itemdecl}
+
+\indexlibrary{\idxcode{tuple_element}}%
+\begin{itemdecl}
+tuple_element<I, span<ElementType, Extent>>::type
+\end{itemdecl}
+
+\begin{itemdescr}
+\pnum
+\mandates
+\tcode{Extent != dynamic_extent \&\& I < Extent} is \tcode{true}.
+
+\pnum
+\cvalue
+The type \tcode{ElementType}.
+\end{itemdescr}
+
+\indexlibrary{\idxcode{get}}%
+\begin{itemdecl}
+template<size_t I, class ElementType, size_t Extent>
+  constexpr ElementType& get(span<ElementType, Extent> s) noexcept;
+\end{itemdecl}
+
+\begin{itemdescr}
+\pnum
+\mandates
+\tcode{Extent != dynamic_extent \&\& I < Extent} is \tcode{true}.
+
+\pnum
+\returns
+A reference to the $\tcode{I}^\text{th}$ element of \tcode{s},
+where indexing is zero-based.
+\end{itemdescr}

source/utilities.tex

@@ -1850,7 +1850,8 @@
 \pnum
 In addition to being available via inclusion of the \tcode{<tuple>} header,
 the three templates are available
-when any of the headers \tcode{<array>}, \tcode{<ranges>}, or \tcode{<utility>}
+when any of the headers
+\tcode{<array>}, \tcode{<ranges>}, \tcode{<span>}, or \tcode{<utility>}
 are included.
 \end{itemdescr}
 
@@ -1880,7 +1881,8 @@
 \pnum
 In addition to being available via inclusion of the \tcode{<tuple>} header,
 the three templates are available
-when any of the headers \tcode{<array>}, \tcode{<ranges>}, or \tcode{<utility>}
+when any of the headers
+\tcode{<array>}, \tcode{<ranges>}, \tcode{<span>}, or \tcode{<utility>}
 are included.
 \end{itemdescr}