[std] Move implementation recommendations to outside notes

and prefix them with "Recommended practice"

Partially addresses ISO/CS 017 (C++20 DIS)

Author: jensmaurer

source/atomics.tex

@@ -636,12 +636,15 @@
 block\iref{intro.progress}.
 
 \pnum
-Operations that are lock-free should also be address-free.
-\begin{note}
+\recommended
+Operations that are lock-free should also be address-free%
+\footnote{
 That is,
 atomic operations on the same memory location via two different addresses will
-communicate atomically. The implementation should not depend on any
-per-process state. This restriction enables communication  by memory that is
+communicate atomically.}.
+The implementation of these operations should not depend on any per-process state.
+\begin{note}
+This restriction enables communication by memory that is
 mapped into a process more than once and by memory that is shared between two
 processes.
 \end{note}

source/basic.tex

@@ -6243,10 +6243,10 @@
     by repeatedly stealing a cache line
     for unrelated purposes
     between load-locked and store-conditional instructions.
-    Implementations should ensure
-    that such effects cannot indefinitely delay progress
+    For implementations that follow this recommendation and
+    ensure that such effects cannot indefinitely delay progress
     under expected operating conditions,
-    and that such anomalies
+    such anomalies
     can therefore safely be ignored by programmers.
     Outside this document,
     this property is sometimes termed lock-free.
@@ -6663,9 +6663,10 @@
 even if it is not itself odr-used~(\ref{basic.def.odr}, \ref{basic.stc.static}).}
 It is \impldef{threads and program points at which deferred dynamic initialization is performed}
 in which threads and at which points in the program such deferred dynamic initialization occurs.
-\begin{note}
-Such points should be chosen in a way that allows the programmer to avoid deadlocks.
-\end{note}
+
+\recommended
+An implementation should choose such points in a way
+that allows the programmer to avoid deadlocks.
 \begin{example}
 \begin{codeblock}
 // - File 1 -

source/expressions.tex

@@ -7271,14 +7271,16 @@
 \end{example}
 
 \pnum
+\recommended
+Implementations should provide consistent results of floating-point evaluations,
+irrespective of whether the evaluation is performed
+during translation or during program execution.
 \begin{note}
 Since this document
 imposes no restrictions on the accuracy of floating-point operations, it is unspecified whether the
 evaluation of a floating-point expression during translation yields the same result as the
 evaluation of the same expression (or the same operations on the same values) during program
-execution.\footnote{Nonetheless, implementations should provide consistent results,
-irrespective of whether the evaluation was performed during translation and/or during program
-execution.}
+execution.
 \begin{example}
 \begin{codeblock}
 bool f() {

source/future.tex

@@ -570,7 +570,7 @@
 \begin{itemize}
 \item
 \tcode{allocated}, set when a dynamic array object has been
-allocated, and hence should be freed by the destructor for the
+allocated, and hence will be freed by the destructor for the
 \tcode{strstreambuf} object;
 \item
 \tcode{constant}, set when the array object has

source/iostreams.tex

@@ -430,8 +430,7 @@
 The objects are constructed and the associations are established at some
 time prior to or during the first time an object of class
 \tcode{ios_base::Init} is constructed, and in any case before the body
-of \tcode{main}\iref{basic.start.main} begins execution.\footnote{If it is possible for them to do so, implementations should
-initialize the objects earlier than required.}
+of \tcode{main}\iref{basic.start.main} begins execution.
 The objects are not destroyed during program execution.\footnote{Constructors and destructors for objects with
 static storage duration can
 access these objects to read input from
@@ -441,6 +440,13 @@
 or
 \tcode{stderr}.
 }
+
+\pnum
+\recommended
+If it is possible for them to do so, implementations should
+initialize the objects earlier than required.
+
+\pnum
 The results of including \libheader{iostream} in a translation unit shall be as if
 \libheader{iostream} defined an instance of \tcode{ios_base::Init} with static
 storage duration.
@@ -13707,10 +13713,10 @@
   \impldef{interpretation of the path character sequence with format \tcode{path::auto_format}}.
   The implementation may inspect the content of the character sequence to
   determine the format.
-  \begin{note}
+
+  \recommended
   For POSIX-based systems, native and generic formats are equivalent
   and the character sequence should always be interpreted in the same way.
-  \end{note}
 \\
 \end{floattable}
 

source/iterators.tex

@@ -1431,11 +1431,15 @@
 \end{itemize}
 
 \pnum
+\recommended
+The implementaton of an algorithm on a weakly incrementable type
+should never attempt to pass through the same incrementable value twice;
+such an algorithm should be a single-pass algorithm.
 \begin{note}
 For \libconcept{weakly_incrementable} types, \tcode{a} equals \tcode{b} does not imply that \tcode{++a}
 equals \tcode{++b}. (Equality does not guarantee the substitution property or referential
-transparency.) Algorithms on weakly incrementable types should never attempt to pass
-through the same incrementable value twice. They should be single-pass algorithms. These algorithms
+transparency.)
+Such algorithms
 can be used with istreams as the source of the input data through the \tcode{istream_iterator} class
 template.
 \end{note}
@@ -1663,10 +1667,10 @@
 \end{codeblock}
 
 \pnum
-\begin{note}
-Algorithms on output iterators should never attempt to pass through the same iterator twice.
-They should be single-pass algorithms.
-\end{note}
+\recommended
+The implementation of an algorithm on output iterators
+should never attempt to pass through the same iterator twice;
+such an algorithm should be a single-pass algorithm.
 
 \rSec3[iterator.concept.forward]{Concept \cname{forward_iterator}}
 
@@ -2009,18 +2013,15 @@
 \end{libreqtab4b}
 
 \pnum
+\recommended
+The implementation of an algorithm on input iterators
+should never attempt to pass through the same iterator twice;
+such an algorithm should be a single pass algorithm.
 \begin{note}
-For input iterators,
-\tcode{a == b}
-does not imply
-\tcode{++a == ++b}.
+For input iterators, \tcode{a == b} does not imply \tcode{++a == ++b}.
 (Equality does not guarantee the substitution property or referential transparency.)
-Algorithms on input iterators should never attempt to pass through the same iterator twice.
-They should be
-\term{single pass}
-algorithms.
 Value type \tcode{T} is not required to be a \oldconcept{CopyAssignable} type (\tref{cpp17.copyassignable}).
-These algorithms can be used with istreams as the source of the input data through the
+Such an algorithm can be used with istreams as the source of the input data through the
 \tcode{istream_iterator}
 class template.
 \end{note}
@@ -2070,13 +2071,14 @@
 \end{libreqtab4b}
 
 \pnum
+\recommended
+The implementation of an algorithm on output iterators
+should never attempt to pass through the same iterator twice;
+such an algorithm should be a single-pass algorithm.
 \begin{note}
-The only valid use of an
-\tcode{operator*}
+The only valid use of an \tcode{operator*}
 is on the left side of the assignment statement.
 Assignment through the same value of the iterator happens only once.
-Algorithms on output iterators should never attempt to pass through the same iterator twice.
-They should be single-pass algorithms.
 Equality and inequality might not be defined.
 \end{note}
 

source/lib-intro.tex

@@ -1668,11 +1668,9 @@
 Thus all evaluations of the expression \tcode{h(k)} with the
   same value for \tcode{k} yield the same result for a given execution of the program.
   \end{note}
-\begin{note}
-For two different
+  For two different
   values \tcode{t1} and \tcode{t2}, the probability that \tcode{h(t1)} and \tcode{h(t2)}
   compare equal should be very small, approaching \tcode{1.0 / numeric_limits<size_t>::max()}.
-  \end{note}
 \\ \rowsep
 \tcode{h(u)}      &
   \tcode{size_t}  &

source/locales.tex

@@ -3448,11 +3448,12 @@
 on any other string for which
 \tcode{do_compare()}
 returns 0 (equal) when passed the two strings.
-\begin{note}
+
+\pnum
+\recommended
 The probability that the result equals that for another string which does
 not compare equal should be very small, approaching
 \tcode{(1.0/numeric_limits<unsigned long>::max())}.
-\end{note}
 \end{itemdescr}
 
 \rSec3[locale.collate.byname]{Class template \tcode{collate_byname}}

source/ranges.tex

@@ -1017,8 +1017,7 @@
 \tcode{ranges::begin} and \tcode{ranges::end}.
 Since \tcode{ranges::begin} is not required to be equality-preserving
 when the return type does not model \libconcept{forward_iterator}, repeated calls
-might not return equal values or might not be well-defined;
-\tcode{ranges::begin} should be called at most once for such a range.
+might not return equal values or might not be well-defined.
 \end{note}
 \end{itemdescr}
 

source/support.tex

@@ -5396,8 +5396,8 @@
 \pnum
 \begin{note}
 The types \tcode{suspend_never} and \tcode{suspend_always} can be used
-to indicate that an \grammarterm{await-expression} should either never
-suspend or always suspend, and in either case not produce a value.
+to indicate that an \grammarterm{await-expression} either never
+suspends or always suspends, and in either case does not produce a value.
 \end{note}
 
 \rSec1[support.runtime]{Other runtime support}