Skip to content

P1024R3 Usability Enhancements for std::span #2719

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Mar 15, 2019
Merged

P1024R3 Usability Enhancements for std::span #2719

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
121 changes: 116 additions & 5 deletions source/containers.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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}

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -10425,6 +10438,7 @@
\begin{itemdecl}
constexpr span() noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
Expand All @@ -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.
Expand All @@ -10462,6 +10477,7 @@
\begin{itemdecl}
constexpr span(pointer first, pointer last);
\end{itemdecl}

\begin{itemdescr}
\pnum
\expects
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -10543,6 +10561,7 @@
\begin{itemdecl}
constexpr span(const span& other) noexcept = default;
\end{itemdecl}

\begin{itemdescr}
\pnum
\ensures
Expand All @@ -10554,6 +10573,7 @@
template<class OtherElementType, size_t OtherExtent>
constexpr span(const span<OtherElementType, OtherExtent>& s) noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\constraints
Expand All @@ -10576,6 +10596,7 @@
\begin{itemdecl}
constexpr span& operator=(const span& other) noexcept = default;
\end{itemdecl}

\begin{itemdescr}
\pnum
\ensures
Expand All @@ -10588,6 +10609,7 @@
\begin{itemdecl}
template<size_t Count> constexpr span<element_type, Count> first() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\expects
Expand All @@ -10602,6 +10624,7 @@
\begin{itemdecl}
template<size_t Count> constexpr span<element_type, Count> last() const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\expects
Expand All @@ -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
Expand Down Expand Up @@ -10647,6 +10671,7 @@
\begin{itemdecl}
constexpr span<element_type, dynamic_extent> first(index_type count) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\expects
Expand All @@ -10661,6 +10686,7 @@
\begin{itemdecl}
constexpr span<element_type, dynamic_extent> last(index_type count) const;
\end{itemdecl}

\begin{itemdescr}
\pnum
\expects
Expand All @@ -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
Expand All @@ -10698,6 +10725,7 @@
\begin{itemdecl}
constexpr index_type size() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Expand All @@ -10708,6 +10736,7 @@
\begin{itemdecl}
constexpr index_type size_bytes() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -10758,6 +10818,7 @@
\begin{itemdecl}
constexpr iterator begin() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
Expand All @@ -10770,6 +10831,7 @@
\begin{itemdecl}
constexpr iterator end() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
Expand All @@ -10780,6 +10842,7 @@
\begin{itemdecl}
constexpr reverse_iterator rbegin() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Expand All @@ -10790,6 +10853,7 @@
\begin{itemdecl}
constexpr reverse_iterator rend() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
Expand All @@ -10800,6 +10864,7 @@
\begin{itemdecl}
constexpr const_iterator cbegin() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
Expand All @@ -10812,6 +10877,7 @@
\begin{itemdecl}
constexpr const_iterator cend() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\returns
Expand All @@ -10822,6 +10888,7 @@
\begin{itemdecl}
constexpr const_reverse_iterator crbegin() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Expand All @@ -10832,6 +10899,7 @@
\begin{itemdecl}
constexpr const_reverse_iterator crend() const noexcept;
\end{itemdecl}

\begin{itemdescr}
\pnum
\effects
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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}
6 changes: 4 additions & 2 deletions source/utilities.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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}

Expand Down Expand Up @@ -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}

Expand Down