From 4111d66cd641729ad2f1750a681a554641caf736 Mon Sep 17 00:00:00 2001
From: Alisdair Meredith <alisdairm@me.com>
Date: Fri, 18 Nov 2016 10:51:53 -0500
Subject: [PATCH] [numeric] Order elements correctly

This is the analog to ballot comment JP-21, ordering the
Requires/Effects/Returns clauses correctly through clause
26.  A couple of re-orderings are deliberately skipped,
due to a dependency in the wording, introducing terms in
the out-of-order elements.
---
 source/numerics.tex | 229 ++++++++++++++++++++++----------------------
 1 file changed, 115 insertions(+), 114 deletions(-)

diff --git a/source/numerics.tex b/source/numerics.tex
index f3ead4adcc..da6a828428 100644
--- a/source/numerics.tex
+++ b/source/numerics.tex
@@ -724,13 +724,13 @@
 \end{itemdecl}
 
 \begin{itemdescr}
-\pnum
-\remarks
-unary operator.
-
 \pnum
 \returns
 \tcode{complex<T>(lhs)}.
+
+\pnum
+\remarks
+unary operator.
 \end{itemdescr}
 
 \begin{codeblock}
@@ -752,13 +752,13 @@
 \end{itemdecl}
 
 \begin{itemdescr}
-\pnum
-\remarks
-unary operator.
-
 \pnum
 \returns
 \tcode{complex<T>(-lhs.real(),-lhs.imag())}.
+
+\pnum
+\remarks
+unary operator.
 \end{itemdescr}
 
 \indexlibrarymember{operator-}{complex}%
@@ -847,6 +847,11 @@
 \end{itemdecl}
 
 \begin{itemdescr}
+\pnum
+\requires
+The input values shall be convertible to
+\tcode{T}.
+
 \pnum
 \effects
 Extracts a complex number \tcode{x} of the form:
@@ -861,10 +866,6 @@
 is the imaginary part~(\ref{istream.formatted}).
 
 \pnum
-\requires
-The input values shall be convertible to
-\tcode{T}.
-
 If bad input is encountered, calls
 \tcode{is.setstate(ios_base::failbit)}
 (which may throw
@@ -1155,15 +1156,15 @@
 \end{itemdecl}
 
 \begin{itemdescr}
-\pnum
-\remarks
-The branch cuts are along the negative real axis.
-
 \pnum
 \returns
 The complex natural (base-$e$) logarithm of \tcode{x}. For all \tcode{x},
 \tcode{imag(log(x))} lies in the interval \crange{$-\pi$}{$\pi$}, and
 when \tcode{x} is a negative real number, \tcode{imag(log(x))} is $\pi$.
+
+\pnum
+\remarks
+The branch cuts are along the negative real axis.
 \end{itemdescr}
 
 \indexlibrary{\idxcode{log10}!\idxcode{complex}}%
@@ -1172,14 +1173,14 @@
 \end{itemdecl}
 
 \begin{itemdescr}
-\pnum
-\remarks
-The branch cuts are along the negative real axis.
-
 \pnum
 \returns
 The complex common (base-$10$) logarithm of \tcode{x}, defined as
 \tcode{log(x) / log(10)}.
+
+\pnum
+\remarks
+The branch cuts are along the negative real axis.
 \end{itemdescr}
 
 \indexlibrary{\idxcode{pow}!\idxcode{complex}}%
@@ -1190,10 +1191,6 @@
 \end{itemdecl}
 
 \begin{itemdescr}
-\pnum
-\remarks
-The branch cuts are along the negative real axis.
-
 \pnum
 \returns
 The complex power of base \tcode{x} raised to the \tcode{y}$^\text{th}$ power,
@@ -1202,6 +1199,10 @@
 The value returned for
 \tcode{pow(0, 0)}
 is \impldef{value of \tcode{pow(0,0)}}.
+
+\pnum
+\remarks
+The branch cuts are along the negative real axis.
 \end{itemdescr}
 
 \indexlibrary{\idxcode{sin}!\idxcode{complex}}%
@@ -1232,16 +1233,16 @@
 \end{itemdecl}
 
 \begin{itemdescr}
-\pnum
-\remarks
-The branch cuts are along the negative real axis.
-
 \pnum
 \returns
 The complex square root of \tcode{x}, in the range of the right
 half-plane.
 If the argument is a negative real number, the
 value returned lies on the positive imaginary axis.
+
+\pnum
+\remarks
+The branch cuts are along the negative real axis.
 \end{itemdescr}
 
 \indexlibrary{\idxcode{tan}!\idxcode{complex}}%
@@ -8838,6 +8839,15 @@
 \end{itemdecl}
 
 \begin{itemdescr}
+\pnum
+\requires
+\tcode{T} shall meet the requirements of \tcode{CopyConstructible} (Table~\ref{tab:copyconstructible})
+and \tcode{CopyAssignable} (Table~\ref{tab:copyassignable}) types.
+In the range
+\crange{first}{last},
+\tcode{binary_op}
+shall neither modify elements nor invalidate iterators or subranges.\footnote{The use of fully closed ranges is intentional.}
+
 \pnum
 \effects
 Computes its result by initializing the accumulator
@@ -8855,15 +8865,6 @@
 is similar to the APL reduction operator and Common Lisp reduce function, but
 it avoids the difficulty of defining the result of reduction on an empty
 sequence by always requiring an initial value.}
-
-\pnum
-\requires
-\tcode{T} shall meet the requirements of \tcode{CopyConstructible} (Table~\ref{tab:copyconstructible})
-and \tcode{CopyAssignable} (Table~\ref{tab:copyassignable}) types.
-In the range
-\crange{first}{last},
-\tcode{binary_op}
-shall neither modify elements nor invalidate iterators or subranges.\footnote{The use of fully closed ranges is intentional.}
 \end{itemdescr}
 
 \rSec2[reduce]{Reduce}
@@ -8944,15 +8945,15 @@
 \end{itemdecl}
 
 \begin{itemdescr}
-\pnum
-\returns
-\tcode{\textit{GENERALIZED_SUM}(binary_op, init, *i, ...)} for every \tcode{i} in \range{first}{last}.
-
 \pnum
 \requires
 \tcode{binary_op} shall neither invalidate iterators or subranges, nor modify
 elements in the range \range{first}{last}.
 
+\pnum
+\returns
+\tcode{\textit{GENERALIZED_SUM}(binary_op, init, *i, ...)} for every \tcode{i} in \range{first}{last}.
+
 \pnum
 \complexity
 \bigoh{\tcode{last - first}} applications of \tcode{binary_op}.
@@ -8980,15 +8981,15 @@
 \end{itemdecl}
 
 \begin{itemdescr}
-\pnum
-\returns
-\tcode{\textit{GENERALIZED_SUM}(binary_op, init, unary_op(*i), ...)} for every \tcode{i} in \range{first}{last}.
-
 \pnum
 \requires
 Neither \tcode{unary_op} nor \tcode{binary_op} shall invalidate subranges, or
 modify elements in the range \range{first}{last}.
 
+\pnum
+\returns
+\tcode{\textit{GENERALIZED_SUM}(binary_op, init, unary_op(*i), ...)} for every \tcode{i} in \range{first}{last}.
+
 \pnum
 \complexity
 \bigoh{\tcode{last - first}} applications each of \tcode{unary_op} and
@@ -9027,6 +9028,19 @@
 \end{itemdecl}
 
 \begin{itemdescr}
+\pnum
+\requires
+\tcode{T} shall meet the requirements of \tcode{CopyConstructible} (Table~\ref{tab:copyconstructible})
+and \tcode{CopyAssignable} (Table~\ref{tab:copyassignable}) types.
+In the ranges
+\crange{first1}{last1}
+and
+\crange{first2}{first2 + (last1 - first1)}
+\tcode{binary_op1}
+and
+\tcode{binary_op2}
+shall neither modify elements nor invalidate iterators or subranges.\footnote{The use of fully closed ranges is intentional.}
+
 \pnum
 \effects
 Computes its result by initializing the accumulator
@@ -9045,19 +9059,6 @@
 in the range
 \range{first2}{first2 + (last1 - first1)}
 in order.
-
-\pnum
-\requires
-\tcode{T} shall meet the requirements of \tcode{CopyConstructible} (Table~\ref{tab:copyconstructible})
-and \tcode{CopyAssignable} (Table~\ref{tab:copyassignable}) types.
-In the ranges
-\crange{first1}{last1}
-and
-\crange{first2}{first2 + (last1 - first1)}
-\tcode{binary_op1}
-and
-\tcode{binary_op2}
-shall neither modify elements nor invalidate iterators or subranges.\footnote{The use of fully closed ranges is intentional.}
 \end{itemdescr}
 
 \rSec2[partial.sum]{Partial sum}
@@ -9075,6 +9076,20 @@
 \end{itemdecl}
 
 \begin{itemdescr}
+\pnum
+\requires
+\tcode{InputIterator}'s value type shall be constructible from the type of \tcode{*first}.
+The result of the expression \tcode{acc + *i} or \tcode{binary_op(acc, *i)} shall be
+implicitly convertible to \tcode{InputIterator}'s value type. \tcode{acc}
+shall be writable~(\ref{iterator.requirements.general}) to the \tcode{result} output iterator.
+In the ranges
+\crange{first}{last}
+and
+\mbox{\crange{result}{result + (last - first)}}
+\tcode{binary_op}
+shall neither modify elements nor invalidate iterators or subranges.\footnote{The use of fully closed ranges is intentional.
+}
+
 \pnum
 \effects For a non-empty range,
 the function creates an accumulator \tcode{acc} whose type is \tcode{InputIterator}'s
@@ -9094,20 +9109,6 @@
 applications of
 the binary operation.
 
-\pnum
-\requires
-\tcode{InputIterator}'s value type shall be constructible from the type of \tcode{*first}.
-The result of the expression \tcode{acc + *i} or \tcode{binary_op(acc, *i)} shall be
-implicitly convertible to \tcode{InputIterator}'s value type. \tcode{acc}
-shall be writable~(\ref{iterator.requirements.general}) to the \tcode{result} output iterator.
-In the ranges
-\crange{first}{last}
-and
-\mbox{\crange{result}{result + (last - first)}}
-\tcode{binary_op}
-shall neither modify elements nor invalidate iterators or subranges.\footnote{The use of fully closed ranges is intentional.
-}
-
 \pnum
 \remarks
 \tcode{result}
@@ -9165,6 +9166,12 @@
 \end{itemdecl}
 
 \begin{itemdescr}
+\pnum
+\requires
+\tcode{binary_op} shall neither invalidate iterators or subranges, nor modify
+elements in the
+ranges \range{first}{last} or \range{result}{result + (last - first)}.
+
 \pnum
 \effects
 Assigns through each iterator \tcode{i} in \range{result}{result + (last - first)} the value of
@@ -9175,26 +9182,20 @@
 \returns
 The end of the resulting range beginning at \tcode{result}.
 
-\pnum
-\requires
-\tcode{binary_op} shall neither invalidate iterators or subranges, nor modify
-elements in the
-ranges \range{first}{last} or \range{result}{result + (last - first)}.
-
 \pnum
 \complexity
 \bigoh{\tcode{last - first}} applications of \tcode{binary_op}.
 
+\pnum
+\remarks
+\tcode{result} may be equal to \tcode{first}.
+
 \pnum
 \realnotes
 The difference between \tcode{exclusive_scan} and \tcode{inclusive_scan} is
 that \tcode{exclusive_scan} excludes the \tcode{i}th input element from the
 \tcode{i}th sum. If \tcode{binary_op} is not mathematically associative, the
 behavior of \tcode{exclusive_scan} may be non-deterministic.
-
-\pnum
-\remarks
-\tcode{result} may be equal to \tcode{first}.
 \end{itemdescr}
 
 \rSec2[inclusive.scan]{Inclusive scan}
@@ -9255,6 +9256,12 @@
 \end{itemdecl}
 
 \begin{itemdescr}
+\pnum
+\requires
+\tcode{binary_op} shall not invalidate iterators or subranges, nor modify
+elements in the ranges \range{first}{last} or
+\range{result}{result + (last - first)}.
+
 \pnum
 \effects
 Assigns through each iterator \tcode{i} in \range{result}{result + (last - first)} the value of
@@ -9272,12 +9279,6 @@
 \returns
 The end of the resulting range beginning at \tcode{result}.
 
-\pnum
-\requires
-\tcode{binary_op} shall not invalidate iterators or subranges, nor modify
-elements in the ranges \range{first}{last} or \range{result}{result + (last -
-first)}.
-
 \pnum
 \complexity
 \bigoh{\tcode{last - first}} applications of \tcode{binary_op}.
@@ -9316,6 +9317,13 @@
 \end{itemdecl}
 
 \begin{itemdescr}
+\pnum
+\requires
+Neither \tcode{unary_op} nor \tcode{binary_op} shall invalidate iterators or
+subranges, or modify elements in the ranges
+\range{first}{last} or
+\range{result}{result + (last - first)}.
+
 \pnum
 \effects
 Assigns through each iterator \tcode{i} in \range{result}{result + (last - first)} the value of
@@ -9326,13 +9334,6 @@
 \returns
 The end of the resulting range beginning at \tcode{result}.
 
-\pnum
-\requires
-Neither \tcode{unary_op} nor \tcode{binary_op} shall invalidate iterators or
-subranges, or modify elements in the ranges
-\range{first}{last} or
-\range{result}{result + (last - first)}.
-
 \pnum
 \complexity
 \bigoh{\tcode{last - first}} applications each of \tcode{unary_op} and
@@ -9390,6 +9391,12 @@
 \end{itemdecl}
 
 \begin{itemdescr}
+\pnum
+\requires
+Neither \tcode{unary_op} nor \tcode{binary_op} shall invalidate iterators or
+subranges, or modify elements in the ranges \range{first}{last} or
+\range{result}{result + (last - first)}.
+
 \pnum
 \effects
 Assigns through each iterator \tcode{i} in \range{result}{result + (last - first)} the value of
@@ -9407,12 +9414,6 @@
 \returns
 The end of the resulting range beginning at \tcode{result}.
 
-\pnum
-\requires
-Neither \tcode{unary_op} nor \tcode{binary_op} shall invalidate iterators or
-subranges, or modify elements in the ranges \range{first}{last} or
-\range{result}{result + (last - first)}.
-
 \pnum
 \complexity
 \bigoh{\tcode{last - first}} applications each of \tcode{unary_op} and
@@ -9460,15 +9461,6 @@
 \end{itemdecl}
 
 \begin{itemdescr}
-\pnum
-\effects For a non-empty range,
-the function creates an accumulator \tcode{acc} whose type is \tcode{InputIterator}'s
-value type, initializes it with \tcode{*first},
-and assigns the result to \tcode{*result}. For every iterator \tcode{i} in \range{first + 1}{last}
-in order, creates an object \tcode{val} whose type is \tcode{InputIterator}'s value type, initializes it
-with \tcode{*i}, computes \tcode{val - acc} or \tcode{binary_op(val, acc)}, assigns the result
-to \tcode{*(result + (i - first))}, and move assigns from \tcode{val} to \tcode{acc}.
-
 \pnum
 \requires
 \tcode{InputIterator}'s value type shall be \tcode{MoveAssignable} (Table~\ref{tab:moveassignable})
@@ -9484,10 +9476,13 @@
 subranges.\footnote{The use of fully closed ranges is intentional.}
 
 \pnum
-\remarks
-\tcode{result}
-may be equal to
-\tcode{first}.
+\effects For a non-empty range,
+the function creates an accumulator \tcode{acc} whose type is \tcode{InputIterator}'s
+value type, initializes it with \tcode{*first},
+and assigns the result to \tcode{*result}. For every iterator \tcode{i} in \range{first + 1}{last}
+in order, creates an object \tcode{val} whose type is \tcode{InputIterator}'s value type, initializes it
+with \tcode{*i}, computes \tcode{val - acc} or \tcode{binary_op(val, acc)}, assigns the result
+to \tcode{*(result + (i - first))}, and move assigns from \tcode{val} to \tcode{acc}.
 
 \pnum
 \returns
@@ -9499,6 +9494,12 @@
 \tcode{(last - first) - 1}
 applications of
 the binary operation.
+
+\pnum
+\remarks
+\tcode{result}
+may be equal to
+\tcode{first}.
 \end{itemdescr}
 
 \rSec2[numeric.iota]{Iota}