P0738R2 I Stream, You Stream, We All Stream for istream_iterator

Fixes #2697.

Author: CaseyCarter

source/iterators.tex

@@ -5569,51 +5569,9 @@
 
 \pnum
 \indexlibrary{\idxcode{istream_iterator}}%
-The class template
-\tcode{istream_iterator}
-is an input iterator\iref{input.iterators} that
-reads (using
-\tcode{operator>>})
-successive elements from the input stream for which it was constructed.
-After it is constructed, and every time
-\tcode{++}
-is used, the iterator reads and stores a value of
-\tcode{T}.
-If the iterator fails to read and store a value of \tcode{T}
-(\tcode{fail()}
-on the stream returns
-\tcode{true}),
-the iterator becomes equal to the
-\term{end-of-stream}
-iterator value.
-The constructor with no arguments
-\tcode{istream_iterator()}
-always constructs
-an end-of-stream input iterator object, which is the only legitimate iterator to be used
-for the end condition.
-The result of
-\tcode{operator*}
-on an end-of-stream iterator is not defined.
-For any other iterator value a
-\tcode{const T\&}
-is returned.
-The result of
-\tcode{operator->}
-on an end-of-stream iterator is not defined.
-For any other iterator value a
-\tcode{const T*}
-is returned.
-The behavior of a program that applies \tcode{operator++()} to an end-of-stream
-iterator is undefined.
-It is impossible to store things into istream iterators.
-The type \tcode{T} shall satisfy the \oldconcept{DefaultConstructible},
-\oldconcept{CopyConstructible}, and \oldconcept{CopyAssignable} requirements.
-
-\pnum
-Two end-of-stream iterators are always equal.
-An end-of-stream iterator is not
-equal to a non-end-of-stream iterator.
-Two non-end-of-stream iterators are equal when they are constructed from the same stream.
+The class template \tcode{istream_iterator}
+is an input iterator\iref{input.iterators} that reads successive elements
+from the input stream for which it was constructed.
 
 \begin{codeblock}
 namespace std {
@@ -5654,6 +5612,10 @@
 }
 \end{codeblock}
 
+\pnum
+The type \tcode{T} shall meet the \oldconcept{DefaultConstructible},
+\oldconcept{CopyConstructible}, and \oldconcept{CopyAssignable} requirements.
+
 \rSec3[istream.iterator.cons]{Constructors and destructor}
 
 \indexlibrary{\idxcode{istream_iterator}!constructor}%
@@ -5665,12 +5627,16 @@
 \begin{itemdescr}
 \pnum
 \effects
-Constructs the end-of-stream iterator.
-If \tcode{is_trivially_default_constructible_v<T>} is \tcode{true},
-then these constructors are constexpr constructors.
+Constructs the end-of-stream iterator, value-initializing \tcode{value}.
 
 \pnum
-\ensures \tcode{in_stream == nullptr}.
+\ensures \tcode{in_stream == nullptr} is \tcode{true}.
+
+\pnum
+\remarks
+If the initializer \tcode{T()} in the declaration \tcode{auto x = T();}
+is a constant initializer\iref{expr.const},
+then these constructors are \tcode{constexpr} constructors.
 \end{itemdescr}
 
 
@@ -5682,12 +5648,9 @@
 \begin{itemdescr}
 \pnum
 \effects
-Initializes \tcode{in_stream} with \tcode{addressof(s)}.
-\tcode{value} may be initialized during
-construction or the first time it is referenced.
-
-\pnum
-\ensures \tcode{in_stream == addressof(s)}.
+Initializes \tcode{in_stream} with \tcode{addressof(s)},
+value-initializes \tcode{value},
+and then calls \tcode{operator++()}.
 \end{itemdescr}
 
 
@@ -5700,11 +5663,14 @@
 \pnum
 \effects
 Constructs a copy of \tcode{x}.
-If \tcode{is_trivially_copy_constructible_v<T>} is \tcode{true},
-then this constructor is a trivial copy constructor.
 
 \pnum
-\ensures \tcode{in_stream == x.in_stream}.
+\ensures \tcode{in_stream == x.in_stream} is \tcode{true}.
+
+\pnum
+\remarks
+If \tcode{is_trivially_copy_constructible_v<T>} is \tcode{true},
+then this constructor is trivial.
 \end{itemdescr}
 
 \indexlibrary{\idxcode{istream_iterator}!destructor}%
@@ -5714,8 +5680,7 @@
 
 \begin{itemdescr}
 \pnum
-\effects
-The iterator is destroyed.
+\remarks
 If \tcode{is_trivially_destructible_v<T>} is \tcode{true},
 then this destructor is trivial.
 \end{itemdescr}
@@ -5728,6 +5693,10 @@
 \end{itemdecl}
 
 \begin{itemdescr}
+\pnum
+\expects
+\tcode{in_stream != nullptr} is \tcode{true}.
+
 \pnum
 \returns
 \tcode{value}.
@@ -5739,9 +5708,13 @@
 \end{itemdecl}
 
 \begin{itemdescr}
+\pnum
+\expects
+\tcode{in_stream != nullptr} is \tcode{true}.
+
 \pnum
 \returns
-\tcode{addressof(operator*())}.
+\tcode{addressof(value)}.
 \end{itemdescr}
 
 \indexlibrarymember{operator++}{istream_iterator}%
@@ -5751,11 +5724,15 @@
 
 \begin{itemdescr}
 \pnum
-\requires \tcode{in_stream != nullptr}.
+\expects
+\tcode{in_stream != nullptr} is \tcode{true}.
 
 \pnum
-\effects
-As if by: \tcode{*in_stream >> value;}
+\effects Equivalent to:
+\begin{codeblock}
+if (!(*in_stream >> value))
+  in_stream = nullptr;
+\end{codeblock}
 
 \pnum
 \returns
@@ -5769,14 +5746,10 @@
 
 \begin{itemdescr}
 \pnum
-\requires \tcode{in_stream != nullptr}.
-
-\pnum
-\effects
-As if by:
+\effects Equivalent to:
 \begin{codeblock}
 istream_iterator tmp = *this;
-*in_stream >> value;
+++*this;
 return tmp;
 \end{codeblock}
 \end{itemdescr}