[std] Rephrase notes giving advice to the programmer.

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

Author: jensmaurer

source/algorithms.tex

@@ -203,10 +203,11 @@
 \pnum
 \begin{note}
 Unless otherwise specified, algorithms that take function objects as arguments
-are permitted to copy those function objects freely.
-Programmers for whom object identity is important should consider
-using a wrapper class that points to a noncopied implementation object
-such as \tcode{reference_wrapper<T>}\iref{refwrap}, or some equivalent solution.
+can copy those function objects freely.
+If object identity is important,
+a wrapper class that points to a noncopied implementation object
+such as \tcode{reference_wrapper<T>}\iref{refwrap}, or some equivalent solution,
+can be used.
 \end{note}
 
 \pnum
@@ -390,11 +391,11 @@
 \begin{note}
 This implies that user-supplied function objects cannot rely on
 object identity of arguments for such input sequences.
-Users for whom the object identity of the arguments to these function objects
-is important should consider using a wrapping iterator
+If object identity of the arguments to these function objects
+is important, a wrapping iterator
 that returns a non-copied implementation object
-such as \tcode{reference_wrapper<T>}\iref{refwrap}
-or some equivalent solution.
+such as \tcode{reference_wrapper<T>}\iref{refwrap},
+or some equivalent solution, can be used.
 \end{note}
 
 \pnum

source/containers.tex

@@ -773,18 +773,16 @@
 \pnum
 \begin{note}
 The sequence containers
-offer the programmer different complexity trade-offs and should be used
-accordingly.
+offer the programmer different complexity trade-offs.
 \tcode{vector}
-is the type of sequence container that should be used by default.
+is the sequence container that can be used by default.
 \tcode{array}
-should be used when the container has a fixed size known during translation.
+has a fixed size known during translation.
 \tcode{list} or \tcode{forward_list}
-should be used when there are frequent insertions and deletions from the
+supports frequent insertions and deletions from the
 middle of the sequence.
 \tcode{deque}
-is the data structure of choice
-when most insertions and deletions take place at the beginning or at the
+supports efficient insertions and deletions taking place at the beginning or at the
 end of the sequence.
 When choosing a container, remember \tcode{vector} is best;
 leave a comment to explain if you choose from the rest!

source/diagnostics.tex

@@ -843,9 +843,9 @@
 \begin{note}
 \tcode{error_category} objects are
 passed by reference, and two such objects
-are equal if they have the same address. This means that applications using
-custom \tcode{error_category} types should create a single object of each
-such type.
+are equal if they have the same address.
+If there is more than a single object of a custom \tcode{error_category} type,
+such equality comparisons can spuriously fail.
 \end{note}
 
 \indexlibraryglobal{error_category}%

source/exceptions.tex

@@ -355,8 +355,8 @@
 \end{codeblock}
 \end{example}
 \begin{note}
-\setlength{\emergencystretch}{1em}
-Consequently, destructors should generally catch exceptions and not let them propa\-gate.
+If a destructor directly invoked by stack unwinding exits via an exception,
+\tcode{std::terminate} is invoked.
 \end{note}
 
 

source/iostreams.tex

@@ -11994,7 +11994,7 @@
       the ASCII control characters (0x00 -- 0x1F) in filenames.
 \end{example}
 \begin{note}
-For wide portability, users may wish to limit \grammarterm{filename}
+Wider portability can be achieved by limiting \grammarterm{filename}
 characters to the POSIX Portable Filename Character Set: \\
 \tcode{A B C D E F G H I J K L M N O P Q R S T U V W X Y Z} \\
 \tcode{a b c d e f g h i j k l m n o p q r s t u v w x y z} \\
@@ -14622,11 +14622,11 @@
 
 \pnum
 \begin{note}
-Programs performing directory iteration may wish to test if the
-path obtained by dereferencing a directory iterator actually exists. It could be
-a symbolic link to a non-existent file. Programs recursively
-walking directory trees for purposes of removing and renaming entries may wish
-to avoid following symbolic links.
+A path obtained by dereferencing a directory iterator might not actually exist;
+it could be a symbolic link to a non-existent file.
+Recursively walking directory trees
+for purposes of removing and renaming entries
+might invalidate symbolic links that are being followed.
 \end{note}
 
 \pnum
@@ -15147,9 +15147,9 @@
 \pnum
 \begin{note}
 Because hardware failures, network failures, file system races\iref{fs.race.behavior},
-and many other kinds of errors occur frequently in file system operations, users should be aware
-that any filesystem operation function, no matter how apparently innocuous, may encounter
-an error; see~\ref{fs.err.report}.
+and many other kinds of errors occur frequently in file system operations,
+any filesystem operation function, no matter how apparently innocuous,
+can encounter an error; see~\ref{fs.err.report}.
 \end{note}
 
 \rSec3[fs.op.absolute]{Absolute}
@@ -15640,7 +15640,9 @@
 \pnum
 \begin{note}
 Some operating systems require symlink creation to
-  identify that the link is to a directory. Portable code should use \tcode{create_directory_symlink()} to create directory symlinks rather than \tcode{create_symlink()}
+identify that the link is to a directory.
+Thus, \tcode{create_symlink()} (instead of \tcode{create_directory_symlink()})
+cannot be used reliably to create directory symlinks.
 \end{note}
 
 \pnum

source/lib-intro.tex

@@ -3049,13 +3049,6 @@
 Objects constructed by the standard library that may hold a user-supplied pointer value
 or an integer of type \tcode{std::intptr_t} shall store such values in a traceable
 pointer location\iref{basic.stc.dynamic.safety}.
-\begin{note}
-Other libraries are
-strongly encouraged to do the same, since not doing so may result in accidental use of
-pointers that are not safely derived. Libraries that store pointers outside the user's
-address space should make it appear that they are stored and retrieved from a traceable
-pointer location.
-\end{note}
 
 \rSec3[value.error.codes]{Value of error codes}
 

source/preprocessor.tex

@@ -711,11 +711,12 @@
 
 \pnum
 \begin{note}
-Although an implementation can provide a mechanism for making arbitrary
-source files available to the \tcode{< >} search, in general
-programmers should use the \tcode{< >} form for headers provided
-with the implementation, and the \tcode{" "} form for sources
-outside the control of the implementation. For instance:
+An implementation can provide a mechanism for making arbitrary
+source files available to the \tcode{< >} search.
+However, using the \tcode{< >} form for headers provided
+with the implementation and the \tcode{" "} form for sources
+outside the control of the implementation
+achieves wider portability. For instance:
 
 \begin{codeblock}
 #include <stdio.h>

source/strings.tex

@@ -3947,7 +3947,7 @@
 \pnum
 \begin{note}
 The library provides implicit conversions from \tcode{const charT*} and \tcode{std::basic_string<charT, ...>} to \tcode{std::basic_string_view<charT, ...>} so that user code can accept just \tcode{std::basic_string_view<charT>} as a non-templated parameter wherever a sequence of characters is expected.
-User-defined types should define their own implicit conversions to \tcode{std::basic_string_view} in order to interoperate with these functions.
+User-defined types can define their own implicit conversions to \tcode{std::basic_string_view} in order to interoperate with these functions.
 \end{note}
 
 \rSec2[string.view.synop]{Header \tcode{<string_view>} synopsis}

source/support.tex

@@ -1985,7 +1985,7 @@
 A function registered via \tcode{at_quick_exit}
 is invoked by the thread that calls \tcode{quick_exit},
 which can be a different thread
-than the one that registered it, so registered functions should not rely on the identity
+than the one that registered it, so registered functions cannot rely on the identity
 of objects with thread storage duration.
 \end{note}
 After calling registered functions, \tcode{quick_exit} shall call \tcode{_Exit(status)}.

source/threads.tex

@@ -2024,7 +2024,7 @@
 \begin{note}
 Construction and
 destruction of an object of a mutex type need not be thread-safe; other
-synchronization should be used to ensure that mutex objects are initialized
+synchronization can be used to ensure that mutex objects are initialized
 and visible to other threads.
 \end{note}
 
@@ -4240,11 +4240,8 @@
 
 \pnum
 \begin{note}
-The supplied lock will be held until the thread exits, and care
-should be taken to ensure that this does not cause deadlock due to lock
-ordering issues. After calling \tcode{notify_all_at_thread_exit} it is
-recommended that the thread should be exited as soon as possible, and
-that no blocking or time-consuming tasks are run on that thread.
+The supplied lock is held until the thread exits,
+which might cause deadlock due to lock ordering issues.
 \end{note}
 
 \pnum
@@ -4332,7 +4329,7 @@
 wait.
 This relaxes the usual rules, which would have required all wait calls to happen before
 destruction. Only the notification to unblock the wait needs to happen before destruction.
-The user should take care to ensure that no threads wait on \tcode{*this} once the destructor has
+Undefined behavior ensues if a thread waits on \tcode{*this} once the destructor has
 been started, especially when the waiting threads are calling the wait functions in a loop or
 using the overloads of \tcode{wait}, \tcode{wait_for}, or \tcode{wait_until} that take a predicate.
 \end{note}
@@ -4689,8 +4686,8 @@
 All of the standard
 mutex types meet this requirement. If a \tcode{Lock} type other than one of the
 standard mutex types or a \tcode{unique_lock} wrapper for a standard mutex type
-is used with \tcode{condition_variable_any}, the user should ensure that any
-necessary synchronization is in place with respect to the predicate associated
+is used with \tcode{condition_variable_any}, any
+necessary synchronization is assumed to be in place with respect to the predicate associated
 with the \tcode{condition_variable_any} instance.
 \end{note}
 
@@ -4774,7 +4771,7 @@
 wait.
 This relaxes the usual rules, which would have required all wait calls to happen before
 destruction. Only the notification to unblock the wait needs to happen before destruction.
-The user should take care to ensure that no threads wait on \tcode{*this} once the destructor has
+Undefined behavior ensues if a thread waits on \tcode{*this} once the destructor has
 been started, especially when the waiting threads are calling the wait functions in a loop or
 using the overloads of \tcode{wait}, \tcode{wait_for}, or \tcode{wait_until} that take a predicate.
 \end{note}
@@ -6924,7 +6921,7 @@
 \pnum
 \begin{note}
 Access to a value object stored in the shared state is
-unsynchronized, so programmers should apply only those operations on \tcode{R} that do not
+unsynchronized, so operations on \tcode{R} might
 introduce a data race\iref{intro.multithread}.
 \end{note}
 
@@ -7161,8 +7158,7 @@
 to the shared state created by this call to \tcode{async}.
 \begin{note}
 If a future obtained from \tcode{async} is moved outside the local scope,
-other code that uses the future should be aware that the future's destructor can
-block for the shared state to become ready.
+the future's destructor can block for the shared state to become ready.
 \end{note}
 
 \pnum

source/utilities.tex

@@ -7352,7 +7352,7 @@
 
 \pnum
 \begin{note}
-This function should be the inverse of \tcode{pointer_to}.
+This function is intended to be the inverse of \tcode{pointer_to}.
 If defined, it customizes the behavior of
 the non-member function
 \tcode{to_address}\iref{pointer.conversion}.
@@ -7442,10 +7442,10 @@
 
 \pnum
 \begin{note}
-It is expected that calls to \tcode{declare_reachable(p)} will consume
+It is expected that calls to \tcode{declare_reachable(p)} consume
 a small amount of memory in addition to that occupied by the referenced object until the
-matching call to \tcode{undeclare_reachable(p)} is encountered. Long running programs
-should arrange that calls are matched.
+matching call to \tcode{undeclare_reachable(p)} is encountered.
+Thus, long-running programs where calls are not matched can exhibit a memory leak.
 \end{note}
 \end{itemdescr}
 
@@ -8371,11 +8371,7 @@
 derived, at the expense of providing far fewer garbage collection and leak
 detection options for \tcode{malloc()}-allocated objects. It also allows
 \tcode{malloc()} to be implemented with a separate allocation arena, bypassing
-the normal \tcode{declare_reachable()} implementation. The above functions
-should never intentionally be used as a replacement for
-\tcode{declare_reachable()}, and newly written code is strongly encouraged to
-treat memory allocated with these functions as though it were allocated with
-\tcode{operator new}.
+the normal \tcode{declare_reachable()} implementation.
 \end{note}
 
 \pnum
@@ -9949,9 +9945,9 @@
 
 \pnum
 \begin{note}
-To avoid the possibility of a dangling pointer, the
-user of this constructor should ensure that \tcode{p} remains valid at
-least until the ownership group of \tcode{r} is destroyed.
+Use of this constructor leads to a dangling pointer
+unless \tcode{p} remains valid
+at least until the ownership group of \tcode{r} is destroyed.
 \end{note}
 
 \pnum
@@ -10325,8 +10321,8 @@
 \pnum
 \begin{note}
 When multiple threads
-can affect the return value of \tcode{use_count()},
-the result should be treated as approximate.
+might affect the return value of \tcode{use_count()},
+the result is approximate.
 In particular, \tcode{use_count() == 1} does not imply that accesses through
 a previously destroyed \tcode{shared_ptr} have in any sense completed.
 \end{note}