Skip to content

Commit

Permalink
[std] Remove problematic 'requires' phrases from notes.
Browse files Browse the repository at this point in the history
Only specific phrases involving the word "required" are problematic,
namely when they appear to establish a normative requirement. They
have been reworded, often by replacing "is required" with "needs",
sometimes with slightly larger edits.
  • Loading branch information
jensmaurer authored and tkoeppe committed Jan 5, 2024
1 parent f6692f2 commit e9c3253
Show file tree
Hide file tree
Showing 12 changed files with 36 additions and 41 deletions.
2 changes: 1 addition & 1 deletion source/basic.tex
Original file line number Diff line number Diff line change
Expand Up @@ -6538,7 +6538,7 @@
the implementation ensures that the thread will eventually make progress for as
long as it has not terminated.
\begin{note}
This is required regardless of whether or not other threads of execution (if any)
This is regardless of whether or not other threads of execution (if any)
have been or are making progress. To eventually fulfill this requirement means that
this will happen in an unspecified but finite amount of time.
\end{note}
Expand Down
2 changes: 1 addition & 1 deletion source/classes.tex
Original file line number Diff line number Diff line change
Expand Up @@ -1330,7 +1330,7 @@
\indextext{constructor!implicitly invoked}%
A default constructor is implicitly invoked to initialize
a class object when no initializer is specified\iref{dcl.init.general}.
Such a default constructor is required to be accessible\iref{class.access}.
Such a default constructor needs to be accessible\iref{class.access}.
\end{note}

\pnum
Expand Down
4 changes: 2 additions & 2 deletions source/containers.tex
Original file line number Diff line number Diff line change
Expand Up @@ -2719,7 +2719,7 @@
and \tcode{mapped_type}.
\begin{note}
For example, in some cases \tcode{key_type} and \tcode{mapped_type}
are required to be \oldconcept{CopyAssignable} even though the associated
need to be \oldconcept{CopyAssignable} even though the associated
\tcode{value_type}, \tcode{pair<const key_type, mapped_type>}, is not
\oldconcept{CopyAssignable}.
\end{note}
Expand Down Expand Up @@ -4217,7 +4217,7 @@
apply instead to \tcode{key_type} and \tcode{mapped_type}.
\begin{note}
For example, \tcode{key_type} and \tcode{mapped_type}
are sometimes required to be \oldconcept{CopyAssignable}
sometimes need to be \oldconcept{CopyAssignable}
even though the associated \tcode{value_type},
\tcode{pair<const key_type, mapped_type>},
is not \oldconcept{CopyAssignable}.
Expand Down
13 changes: 6 additions & 7 deletions source/declarations.tex
Original file line number Diff line number Diff line change
Expand Up @@ -1268,10 +1268,10 @@
\indextext{\idxcode{volatile}!implementation-defined}%
\begin{note}
\tcode{volatile} is a hint to the implementation to avoid aggressive
optimization involving the object because the value of the object might
be changed by means undetectable by an implementation.
Furthermore, for some implementations, \tcode{volatile} might indicate that
special hardware instructions are required to access the object.
optimization involving the object because it is possible for the value of the object
to change by means undetectable by an implementation.
Furthermore, for some implementations, \tcode{volatile} can indicate that
special hardware instructions are needed to access the object.
See~\ref{intro.execution} for detailed semantics. In general, the
semantics of \tcode{volatile} are intended to be the same in \Cpp{} as
they are in C.
Expand Down Expand Up @@ -5394,8 +5394,7 @@
\begin{note}
As specified above, brace elision cannot apply to
subaggregates with no elements; an
\grammarterm{initializer-clause} for the entire subobject is
required.
\grammarterm{initializer-clause} for the entire subobject is needed.
\end{note}

\begin{example}
Expand Down Expand Up @@ -6084,7 +6083,7 @@
corresponding element of the initializer list, and the
\tcode{std::initializer_list<E>} object is constructed to refer to that array.
\begin{note}
A constructor or conversion function selected for the copy is required to be
A constructor or conversion function selected for the copy needs to be
accessible\iref{class.access} in the context of the initializer list.
\end{note}
If a narrowing conversion is required to initialize any of the elements,
Expand Down
8 changes: 4 additions & 4 deletions source/expressions.tex
Original file line number Diff line number Diff line change
Expand Up @@ -1412,7 +1412,7 @@
\end{codeblock}
In each case, the constraints of \tcode{f} are not satisfied.
In the declaration of \tcode{p2},
those constraints are required to be satisfied
those constraints need to be satisfied
even though
\tcode{f} is an unevaluated operand\iref{term.unevaluated.operand}.
\end{example}
Expand Down Expand Up @@ -2182,7 +2182,7 @@
if the function call operator template specialization is an immediate function.
\begin{note}
This will result in the implicit instantiation of the generic lambda's body.
The instantiated generic lambda's return type and parameter types are required to match
The instantiated generic lambda's return type and parameter types need to match
the return type and parameter types of the pointer to function.
\end{note}
\begin{example}
Expand Down Expand Up @@ -3404,7 +3404,7 @@
A function can change the values of its non-const parameters, but these
changes cannot affect the values of the arguments except where a
parameter is of a reference type\iref{dcl.ref}; if the reference is to
a const-qualified type, \keyword{const_cast} is required to be used to
a const-qualified type, \keyword{const_cast} needs to be used to
cast away the constness in order to modify the argument's value. Where a
parameter is of \keyword{const} reference type a temporary object is
introduced if
Expand Down Expand Up @@ -5378,7 +5378,7 @@
and the deallocation function's name is
\tcode{\keyword{operator} \keyword{delete}[]}.
\begin{note}
An implementation is required to provide default definitions for the global
An implementation is expected to provide default definitions for the global
allocation
functions\iref{basic.stc.dynamic,new.delete.single,new.delete.array}.
A \Cpp{} program can provide alternative definitions of
Expand Down
8 changes: 4 additions & 4 deletions source/iostreams.tex
Original file line number Diff line number Diff line change
Expand Up @@ -918,7 +918,7 @@
to class \tcode{ios_base::failure} shown in this subclause.
\begin{note}
When \tcode{ios_base::failure} is a synonym for another type,
that type is required to provide a nested type \tcode{failure}
that type needs to provide a nested type \tcode{failure}
to emulate the injected-class-name.
\end{note}
The class
Expand Down Expand Up @@ -14384,7 +14384,7 @@
\effects
Each \grammarterm{directory-separator}
of the pathname in the generic format
is converted to \grammarterm{preferred-separator}.
is converted to \grammarterm{preferred-separator}.

\pnum
\returns
Expand Down Expand Up @@ -15161,8 +15161,8 @@
\item The \grammarterm{root-name} element, if present.
\item The \grammarterm{root-directory} element, if present.
\begin{note}
The generic format is required to ensure lexicographical
comparison works correctly.
It is possible that the use of the generic format is needed
to ensure correct lexicographical comparison.
\end{note}
\item Each successive \grammarterm{filename} element, if present.
\item An empty element, if a trailing non-root \grammarterm{directory-separator}
Expand Down
5 changes: 2 additions & 3 deletions source/lex.tex
Original file line number Diff line number Diff line change
Expand Up @@ -665,8 +665,7 @@
(collectively, ``whitespace''), as described below, are ignored except
as they serve to separate tokens.
\begin{note}
Some whitespace is
required to separate otherwise adjacent identifiers, keywords, numeric
Whitespace can separate otherwise adjacent identifiers, keywords, numeric
literals, and alternative tokens containing alphabetic characters.
\end{note}
\indextext{token|)}
Expand Down Expand Up @@ -1851,7 +1850,7 @@

\pnum
\begin{note}
The characters \tcode{'('} and \tcode{')'} are permitted in a
The characters \tcode{'('} and \tcode{')'} can appear in a
\grammarterm{raw-string}. Thus, \tcode{R"delimiter((a|b))delimiter"} is equivalent to
\tcode{"(a|b)"}.
\end{note}
Expand Down
10 changes: 5 additions & 5 deletions source/lib-intro.tex
Original file line number Diff line number Diff line change
Expand Up @@ -1289,16 +1289,16 @@
Names which are defined as macros in C shall be defined as macros in the \Cpp{}
standard library, even if C grants license for implementation as functions.
\begin{note}
The names defined as macros in C include the following:
The names defined as macros in \IsoC{} include the following:
\tcode{assert}, \tcode{offsetof}, \tcode{setjmp}, \tcode{va_arg},
\tcode{va_end}, and \tcode{va_start}.
\end{note}

\pnum
Names that are defined as functions in C shall be defined as functions in the
Names that are defined as functions in \IsoC{} shall be defined as functions in the
\Cpp{} standard library.
\begin{footnote}
This disallows the practice, allowed in C, of
This disallows the practice, allowed in \IsoC{}, of
providing a masking macro in addition to the function prototype. The only way to
achieve equivalent inline behavior in \Cpp{} is to provide a definition as an
extern inline function.
Expand All @@ -1320,7 +1320,7 @@
\tcode{".h"} headers dump all their names into the global namespace, whereas the
newer forms keep their names in namespace \tcode{std}. Therefore, the newer
forms are the preferred forms for all uses except for \Cpp{} programs which are
intended to be strictly compatible with C.
intended to be strictly compatible with \IsoC{}.
\end{footnote}

\pnum
Expand Down Expand Up @@ -1455,7 +1455,7 @@
It is unspecified to which module a declaration in the standard library
is attached.
\begin{note}
Implementations are required to ensure that mixing
Conforming implementations ensure that mixing
\tcode{\#include} and \tcode{import} does not result in
conflicting attachments\iref{basic.link}.
\end{note}
Expand Down
17 changes: 7 additions & 10 deletions source/templates.tex
Original file line number Diff line number Diff line change
Expand Up @@ -6317,7 +6317,7 @@
into the templated function, variable, or class
are two declarations of the same entity.
\begin{note}
These declarations are required to have matching types as specified in~\ref{basic.link}, except as specified in~\ref{except.spec}.
These declarations need to have matching types as specified in~\ref{basic.link}, except as specified in~\ref{except.spec}.
\begin{example}
\begin{codeblock}
template<typename T> T var = {};
Expand Down Expand Up @@ -6367,7 +6367,7 @@

\pnum
\begin{note}
An explicit instantiation of a constrained template is required
An explicit instantiation of a constrained template needs
to satisfy that template's associated constraints\iref{temp.constr.decl}.
The satisfaction of constraints is determined
% FIXME: What is a "template name"? Does this mean "simple-template-id"?
Expand Down Expand Up @@ -6514,10 +6514,9 @@
An explicit specialization does not introduce a name\iref{basic.scope.scope}.
A declaration of a function template, class template, or variable template being explicitly
specialized shall be reachable from the declaration of
the explicit
specialization.
the explicit specialization.
\begin{note}
A declaration, but not a definition of the template is required.
A declaration, but not a definition of the template is needed.
\end{note}
The definition of a class or class template shall be reachable from the
declaration of an explicit specialization for a member template of the class
Expand Down Expand Up @@ -6708,7 +6707,7 @@

\pnum
\begin{note}
An explicit specialization of a constrained template is required
An explicit specialization of a constrained template needs
to satisfy that template's associated constraints\iref{temp.constr.decl}.
The satisfaction of constraints is determined
when forming the template name of an explicit specialization
Expand Down Expand Up @@ -7305,10 +7304,8 @@
invalid type or expression is one that would be ill-formed, with a diagnostic
required, if written in the same context using the substituted arguments.
\begin{note}
If no
diagnostic is required, the program is still ill-formed. Access checking is done
as part of the substitution
process.
If no diagnostic is required, the program is still ill-formed.
Access checking is done as part of the substitution process.
\end{note}
Invalid types and expressions can result in a deduction failure
only in the immediate context of the deduction substitution loci.
Expand Down
4 changes: 2 additions & 2 deletions source/threads.tex
Original file line number Diff line number Diff line change
Expand Up @@ -6305,8 +6305,8 @@
\begin{note}
After a thread \tcode{A} has called \tcode{unlock()}, releasing a mutex, it is possible for another
thread \tcode{B} to lock the same mutex, observe that it is no longer in use, unlock it, and
destroy it, before thread \tcode{A} appears to have returned from its unlock call. Implementations
are required to handle such scenarios correctly, as long as thread \tcode{A} doesn't access the
destroy it, before thread \tcode{A} appears to have returned from its unlock call. Conforming implementations
handle such scenarios correctly, as long as thread \tcode{A} does not access the
mutex after the unlock call returns. These cases typically occur when a reference-counted object
contains a mutex that is used to protect the reference count.
\end{note}
Expand Down
2 changes: 1 addition & 1 deletion source/time.tex
Original file line number Diff line number Diff line change
Expand Up @@ -7923,7 +7923,7 @@
@\tcode{\placeholder{day}}@/@\tcode{\placeholder{month}}@/@\tcode{\placeholder{year}}@
\end{codeblock}

Anywhere a \tcode{\placeholder{day}} is required, any of the following can also be specified:
Anywhere a \tcode{\placeholder{day}} is needed, any of the following can also be specified:

\begin{codeblock}
last
Expand Down
2 changes: 1 addition & 1 deletion source/utilities.tex
Original file line number Diff line number Diff line change
Expand Up @@ -3002,7 +3002,7 @@
(or \tcode{u$_{\mathrm{tail}}$}) to be constructed. It might not
even be possible, as \tcode{t} and \tcode{u} are not required to be copy
constructible. Also, all comparison operator functions are short circuited;
they do not perform element accesses beyond what is required to determine the
they do not perform element accesses beyond what is needed to determine the
result of the comparison.
\end{note}

Expand Down

0 comments on commit e9c3253

Please sign in to comment.