[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

@@ -634,12 +634,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 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

@@ -6233,20 +6233,12 @@
   When one or more lock-free executions run concurrently,
   at least one should complete.
   \begin{note}
-    It is difficult for some implementations
-    to provide absolute guarantees to this effect,
-    since repeated and particularly inopportune interference
-    from other threads
-    could prevent forward progress,
-    e.g.,
-    by repeatedly stealing a cache line
+    That means programmers can safely ignore anomalies
+    caused by repeated and particularly inopportune interference
+    from other threads, for example 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
-    under expected operating conditions,
-    and that such anomalies
-    can therefore safely be ignored by programmers.
+    between load-locked and store-conditional instructions,
+    which could otherwise indefinitely delay progress.
     Outside this document,
     this property is sometimes termed lock-free.
   \end{note}
@@ -6663,9 +6655,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

@@ -7264,14 +7264,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 to be freed by the destructor for the
 \tcode{strstreambuf} object;
 \item
 \tcode{constant}, set when the array object has

source/iostreams.tex

@@ -11147,8 +11147,8 @@
 \pnum
 \begin{note}
 The member functions of the provided stream buffer
-might be called from \tcode{emit()} while a lock is held.
-Care should be taken to ensure that this does not result in deadlock.
+can called from \tcode{emit()} while a lock is held,
+which might result in a deadlock.
 \end{note}
 
 \pnum
@@ -13719,10 +13719,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}
 \\\rowsep
 \end{floattable}
 

source/iterators.tex

@@ -1435,11 +1435,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}
@@ -1667,10 +1671,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}}
 
@@ -2013,18 +2017,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}
@@ -2074,13 +2075,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

@@ -1666,11 +1666,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

@@ -992,8 +992,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

@@ -5409,8 +5409,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}

source/threads.tex

@@ -126,10 +126,10 @@
 An implementation returns from such a timeout at any point from the time specified above to
 the time it would return from a steady-clock relative timeout on the difference between $C_t$
 and the time point of the call to the \tcode{_until} function.
-\begin{note}
+
+\recommended
 Implementations
 should decrease the duration of the wait when the clock is adjusted forwards.
-\end{note}
 
 \pnum
 \begin{note}
@@ -6449,10 +6449,9 @@
 \begin{note}
 It is valid to move from a future object for which \tcode{valid() == false}.
 \end{note}
-\begin{note}
+\recommended
 Implementations should detect this case and throw an object of type
 \tcode{future_error} with an error condition of \tcode{future_errc::no_state}.
-\end{note}
 
 \indexlibraryglobal{future}%
 \begin{codeblock}
@@ -6749,10 +6748,9 @@
 It is valid to copy or move from a \tcode{shared_future}
 object for which \tcode{valid()} is \tcode{false}.
 \end{note}
-\begin{note}
+\recommended
 Implementations should detect this case and throw an object of type
 \tcode{future_error} with an error condition of \tcode{future_errc::no_state}.
-\end{note}
 
 \indexlibraryglobal{shared_future}%
 \begin{codeblock}
@@ -7144,12 +7142,12 @@
 deferred function in the thread that called the waiting function.
 Once evaluation of \tcode{invoke(std::move(g), std::move(xyz))} begins, the function is no longer
 considered deferred.
-\begin{note}
+
+\recommended
 If this policy is specified together with other policies, such as when using a
 \tcode{policy} value of \tcode{launch::async | launch::deferred}, implementations should defer
 invocation or the selection of the policy when no more concurrency can be effectively
 exploited.
-\end{note}
 
 \item
 If no value is set in the launch policy, or a value is set that is neither specified

source/utilities.tex

@@ -7463,7 +7463,7 @@
 live until the corresponding \tcode{undeclare_no_pointers()} call.
 \begin{note}
 In a garbage-collecting implementation, the fact that a region in an object is
-registered with \tcode{declare_no_pointers()} should not prevent the object from
+registered with \tcode{declare_no_pointers()} does not prevent the object from
 being collected.
 \end{note}
 
@@ -15164,12 +15164,13 @@
 a specialization of \tcode{reference_wrapper} or
 a function pointer. Otherwise, may throw \tcode{bad_alloc}
 or any exception thrown by the copy constructor of the stored callable object.
-\begin{note}
+
+\pnum
+\recommended
 Implementations should avoid the use of
 dynamically allocated memory for small callable objects, for example, where
 \tcode{f}'s target is an object holding only a pointer or reference
 to an object and a member function pointer.
-\end{note}
 \end{itemdescr}
 
 \indexlibraryctor{function}%
@@ -15186,12 +15187,11 @@
 \tcode{f} is in a valid state with an unspecified value.
 
 \pnum
-\begin{note}
+\recommended
 Implementations should avoid the use of
 dynamically allocated memory for small callable objects, for example,
 where \tcode{f}'s target is an object holding only a pointer or reference
 to an object and a member function pointer.
-\end{note}
 \end{itemdescr}
 
 \indexlibraryctor{function}%
@@ -15222,19 +15222,20 @@
 \pnum
 Otherwise, \tcode{*this} targets a copy of \tcode{f}
 initialized with \tcode{std::move(f)}.
-\begin{note}
-Implementations should avoid the use of
-dynamically allocated memory for small callable objects, for example,
-where \tcode{f} is an object holding only a pointer or
-reference to an object and a member function pointer.
-\end{note}
 
 \pnum
 \throws
 Nothing if \tcode{f} is
 a specialization of \tcode{reference_wrapper} or
 a function pointer. Otherwise, may throw \tcode{bad_alloc}
 or any exception thrown by \tcode{F}'s copy or move constructor.
+
+\pnum
+\recommended
+Implementations should avoid the use of
+dynamically allocated memory for small callable objects, for example,
+where \tcode{f} is an object holding only a pointer or
+reference to an object and a member function pointer.
 \end{itemdescr}