Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[lib] Replace 'Notes:' elements with regular [ Note: ... -- end note] #1160

Merged
merged 1 commit into from
Feb 4, 2017
Merged

[lib] Replace 'Notes:' elements with regular [ Note: ... -- end note] #1160

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
8 changes: 6 additions & 2 deletions source/algorithms.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1573,8 +1573,10 @@
If \tcode{f} returns a result, the result is ignored.

\pnum
\realnotes Does not return a copy of its \tcode{Function} parameter, since
\begin{note}
Does not return a copy of its \tcode{Function} parameter, since
parallelization may not permit efficient state accumulation.
\end{note}
\end{itemdescr}

\indexlibrary{\idxcode{for_each_n}}%
Expand Down Expand Up @@ -2871,10 +2873,12 @@
applications of the corresponding predicate.

\pnum
\realnote each element in the range \range{ret}{last}, where \tcode{ret} is
\begin{note}
Each element in the range \range{ret}{last}, where \tcode{ret} is
the returned value, has a valid but unspecified state, because the algorithms
can eliminate elements by moving from elements that were originally
in that range.
\end{note}
\end{itemdescr}

\indexlibrary{\idxcode{remove_copy}}%
Expand Down
8 changes: 4 additions & 4 deletions source/atomics.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1497,11 +1497,11 @@
signal handler executed in the same thread.

\pnum
\realnote \tcode{atomic_signal_fence} can be used to specify the order in which actions
\begin{note}
\tcode{atomic_signal_fence} can be used to specify the order in which actions
performed by the thread become visible to the signal handler.

\pnum
\realnote compiler optimizations and reorderings of loads and stores are inhibited in
Compiler optimizations and reorderings of loads and stores are inhibited in
the same way as with \tcode{atomic_thread_fence}, but the hardware fence instructions
that \tcode{atomic_thread_fence} would have inserted are not emitted.
\end{note}
\end{itemdescr}
17 changes: 8 additions & 9 deletions source/containers.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -272,13 +272,13 @@

\end{libreqtab5}

Notes: the algorithm
\tcode{equal()}
is defined in Clause~\ref{algorithms}.
Those entries marked ``(Note A)'' or ``(Note B)''
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This second sentence is normative, and should not be within the note.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed.

have linear complexity for \tcode{array} and have constant complexity
for all other standard containers.

\begin{note}
The algorithm \tcode{equal()} is defined in Clause~\ref{algorithms}.
\end{note}

\pnum
The member function \tcode{size()} returns the number of elements in the container.
The number of elements is defined by the rules of
Expand Down Expand Up @@ -3230,15 +3230,14 @@

\begin{itemdescr}
\pnum
\effects As if by \tcode{swap_ranges(begin(), end(), y.begin())}.
\effects Equivalent to \tcode{swap_ranges(begin(), end(), y.begin())}.

\pnum
\throws Nothing unless one of the element-wise swap calls throws an exception.

\pnum
\realnote Unlike the \tcode{swap} function for other containers, \tcode{array::swap}
\begin{note}
Unlike the \tcode{swap} function for other containers, \tcode{array::swap}
takes linear time, may exit via an exception, and does not cause iterators to
become associated with the other container.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Where are these properties normatively stated?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All I have is Note A and Note B in [container.requirements.general] after the table.

Suggestion: This says "As if by swap_ranges" for the effects. Let's change that to "Equivalent to" and we get all the missing pieces for free, and can leave the note as a note.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(The updated version adds the "Equivalent to" a few lines earlier.)

\end{note}
\end{itemdescr}

\rSec3[array.zero]{Zero sized arrays}
Expand Down
4 changes: 3 additions & 1 deletion source/iostreams.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2083,9 +2083,11 @@
\end{enumerate}

\pnum
\realnote The second pass through the callback pairs permits a copied \tcode{pword}
\begin{note}
The second pass through the callback pairs permits a copied \tcode{pword}
value to be zeroed, or to have its referent deep copied or reference counted, or to have
other special action taken.
\end{note}

\pnum
\postconditions
Expand Down
3 changes: 1 addition & 2 deletions source/lib-intro.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -488,7 +488,6 @@
\item \complexity the time and/or space complexity of the function
\item \remarks additional semantic constraints on the function
\item \errors the error conditions for error codes reported by the function
\item \realnotes non-normative comments about the function
\end{itemize}

\pnum
Expand All @@ -497,7 +496,7 @@
interpreted as follows. If \tcode{F}'s semantics specifies a \requires element, then
that requirement is logically imposed prior to the \techterm{equivalent-to} semantics.
Next, the semantics of the code sequence are determined by the \requires, \effects,
\sync, \postconditions, \returns, \throws, \complexity, \remarks, \errors, and \realnotes
\sync, \postconditions, \returns, \throws, \complexity, \remarks, and \errors
specified for the function invocations contained in the code sequence. The value
returned from \tcode{F} is specified by \tcode{F}'s \returns element, or if \tcode{F}
has no \returns element, a non-\tcode{void} return from \tcode{F} is specified by the
Expand Down
2 changes: 0 additions & 2 deletions source/macros.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -217,8 +217,6 @@
\newcommand{\default}{\Fundesc{Default behavior}}
\newcommand{\complexity}{\Fundesc{Complexity}}
\newcommand{\remarks}{\Fundesc{Remarks}}
\newcommand{\realnote}{\Fundesc{Note}}
\newcommand{\realnotes}{\Fundesc{Notes}}
\newcommand{\errors}{\Fundesc{Error conditions}}
\newcommand{\sync}{\Fundesc{Synchronization}}
\newcommand{\implimits}{\Fundesc{Implementation limits}}
Expand Down
23 changes: 15 additions & 8 deletions source/numerics.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -912,12 +912,13 @@
\end{codeblock}

\pnum
\realnote In a locale in which comma is used as a decimal point character, the
\begin{note}
In a locale in which comma is used as a decimal point character, the
use of comma as a field separator can be ambiguous. Inserting
\tcode{showpoint} into the output stream forces all outputs to
show an explicit decimal point character; as a result, all inserted sequences of
complex numbers can be extracted unambiguously.

\end{note}
\end{itemdescr}

\rSec2[complex.value.ops]{\tcode{complex} value operations}
Expand Down Expand Up @@ -8938,11 +8939,12 @@
\bigoh{\tcode{last - first}} applications of \tcode{binary_op}.

\pnum
\realnotes
\begin{note}
The difference between \tcode{reduce} and \tcode{accumulate} is that
\tcode{reduce} applies \tcode{binary_op} in an unspecified order, which yields
a nondeterministic result for non-associative or non-commutative
\tcode{binary_op} such as floating-point addition.
\end{note}
\end{itemdescr}

\rSec2[transform.reduce]{Transform reduce}
Expand Down Expand Up @@ -8975,8 +8977,9 @@
\tcode{binary_op}.

\pnum
\realnotes
\begin{note}
\tcode{transform_reduce} does not apply \tcode{unary_op} to \tcode{init}.
\end{note}
\end{itemdescr}

\rSec2[inner.product]{Inner product}
Expand Down Expand Up @@ -9174,11 +9177,12 @@
\tcode{result} may be equal to \tcode{first}.

\pnum
\realnotes
\begin{note}
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 nondeterministic.
\end{note}
\end{itemdescr}

\rSec2[inclusive.scan]{Inclusive scan}
Expand Down Expand Up @@ -9272,11 +9276,12 @@
\tcode{result} may be equal to \tcode{first}.

\pnum
\realnotes
\begin{note}
The difference between \tcode{exclusive_scan} and \tcode{inclusive_scan} is
that \tcode{inclusive_scan} includes the \tcode{i}th input element in the
\tcode{i}th sum. If \tcode{binary_op} is not mathematically associative, the
behavior of \tcode{inclusive_scan} may be nondeterministic.
\end{note}
\end{itemdescr}

\rSec2[transform.exclusive.scan]{Transform exclusive scan}
Expand Down Expand Up @@ -9328,13 +9333,14 @@
\tcode{result} may be equal to \tcode{first}.

\pnum
\realnotes
\begin{note}
The difference between \tcode{transform_exclusive_scan} and
\tcode{transform_inclusive_scan} is that \tcode{transform_exclusive_scan}
excludes the ith input element from the ith sum. If \tcode{binary_op} is not
mathematically associative, the behavior of \tcode{transform_exclusive_scan}
may be nondeterministic. \tcode{transform_exclusive_scan} does not apply
\tcode{unary_op} to \tcode{init}.
\end{note}
\end{itemdescr}

\rSec2[transform.inclusive.scan]{Transform inclusive scan}
Expand Down Expand Up @@ -9408,13 +9414,14 @@
\tcode{result} may be equal to \tcode{first}.

\pnum
\realnotes
\begin{note}
The difference between \tcode{transform_exclusive_scan} and
\tcode{transform_inclusive_scan} is that \tcode{transform_inclusive_scan}
includes the ith input element in the ith sum. If \tcode{binary_op} is not
mathematically associative, the behavior of \tcode{transform_inclusive_scan}
may be nondeterministic. \tcode{transform_inclusive_scan} does not apply
\tcode{unary_op} to \tcode{init}.
\end{note}
\end{itemdescr}

\rSec2[adjacent.difference]{Adjacent difference}
Expand Down
3 changes: 2 additions & 1 deletion source/support.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2530,7 +2530,7 @@
or (possibly cv-qualified) \tcode{void}.

\pnum
\realnotes
\begin{note}
If a new object is created
in storage occupied by an existing object of the same type,
a pointer to the original object
Expand All @@ -2539,6 +2539,7 @@
in the latter cases,
this function can be used to obtain a usable pointer to the new object.
See~\ref{basic.life}.
\end{note}

\pnum
\begin{example}
Expand Down
24 changes: 18 additions & 6 deletions source/threads.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2838,18 +2838,22 @@
all objects with thread storage duration associated with the current thread.

\pnum
\realnote The supplied lock will be held until the thread exits, and care
\begin{note}
The supplied lock will be held until the thread exits, and care
must 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.
\end{note}

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Use two separate notes here? Generally I'd like to avoid \pnums within a note.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok.

\pnum
\realnote It is the user's responsibility to ensure that waiting threads
\begin{note}
It is the user's responsibility to ensure that waiting threads
do not erroneously assume that the thread has finished if they experience
spurious wakeups. This typically requires that the condition being waited
for is satisfied while holding the lock on \tcode{lk}, and that this lock
is not released and reacquired prior to calling \tcode{notify_all_at_thread_exit}.
\end{note}
\end{itemdescr}

\rSec2[thread.condition.condvar]{Class \tcode{condition_variable}}
Expand Down Expand Up @@ -3347,9 +3351,11 @@

\begin{itemdescr}
\pnum
\realnote if any of the \tcode{wait} functions exits via an exception, it is
\begin{note}
If any of the \tcode{wait} functions exits via an exception, it is
unspecified whether the \tcode{Lock} is held. One can use a \tcode{Lock} type
that allows to query that, such as the \tcode{unique_lock} wrapper.
\end{note}

\pnum
\effects
Expand Down Expand Up @@ -4248,8 +4254,10 @@

\begin{itemdescr}
\pnum
\realnote as described above, the template and its two required specializations differ only in
\begin{note}
As described above, the template and its two required specializations differ only in
the return type and return value of the member function \tcode{get}.
\end{note}

\pnum
\effects
Expand Down Expand Up @@ -4554,13 +4562,17 @@

\begin{itemdescr}
\pnum
\realnote as described above, the template and its two required specializations differ only in
\begin{note}
As described above, the template and its two required specializations differ only in
the return type and return value of the member function \tcode{get}.
\end{note}

\pnum
\realnote access to a value object stored in the shared state is
\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
introduce a data race~(\ref{intro.multithread}).
\end{note}

\pnum
\effects \tcode{wait()}{s} until the shared state is ready, then retrieves the
Expand Down
16 changes: 12 additions & 4 deletions source/utilities.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2090,9 +2090,11 @@
each group $e_i$ in order.

\pnum
\realnote An implementation may support additional types in the parameter
\begin{note}
An implementation may support additional types in the parameter
pack \tcode{Tuples} that support the \tcode{tuple}-like protocol, such as
\tcode{pair} and \tcode{array}.
\end{note}
\end{itemdescr}

\rSec3[tuple.apply]{Calling a function with a \tcode{tuple} of arguments}
Expand Down Expand Up @@ -8765,7 +8767,9 @@
\returns \tcode{get()}.

\pnum
\realnote use typically requires that \tcode{T} be a complete type.
\begin{note}
The use of this function typically requires that \tcode{T} be a complete type.
\end{note}
\end{itemdescr}

\indexlibrarymember{get}{unique_ptr}%
Expand Down Expand Up @@ -11117,8 +11121,9 @@
Nothing.

\pnum
\realnotes
\begin{note}
This constructor provides an implicit conversion from \tcode{memory_resource*}.
\end{note}
\end{itemdescr}

\indexlibrary{\idxcode{polymorphic_allocator}!constructor}%
Expand Down Expand Up @@ -18120,11 +18125,14 @@
\end{codeblock}
\end{itemize}

\realnotes This function does not use any implicit conversions; all conversions
\pnum
\begin{note}
This function does not use any implicit conversions; all conversions
are done with \tcode{static_cast}. It avoids multiplications and divisions when
it is known at compile time that one or more arguments is 1. Intermediate
computations are carried out in the widest representation and only converted to
the destination representation at the final step.
\end{note}
\end{itemdescr}

\indexlibrarymember{floor}{duration}%
Expand Down