From f2e057fca98f4cfa67037c746a76e60d54ff4870 Mon Sep 17 00:00:00 2001 From: Jens Maurer Date: Mon, 18 Dec 2023 17:22:30 +0100 Subject: [PATCH] [std] Remove problematic 'requires' phrases from notes. 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. --- source/basic.tex | 2 +- source/classes.tex | 2 +- source/containers.tex | 4 ++-- source/declarations.tex | 15 +++++++-------- source/expressions.tex | 10 +++++----- source/intro.tex | 7 +++---- source/iostreams.tex | 8 ++++---- source/lex.tex | 5 ++--- source/lib-intro.tex | 10 +++++----- source/templates.tex | 17 +++++++---------- source/threads.tex | 4 ++-- source/time.tex | 2 +- source/utilities.tex | 2 +- 13 files changed, 41 insertions(+), 47 deletions(-) diff --git a/source/basic.tex b/source/basic.tex index 547fa4caf68..d1c77475075 100644 --- a/source/basic.tex +++ b/source/basic.tex @@ -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} diff --git a/source/classes.tex b/source/classes.tex index 65231de79a8..932b19a3115 100644 --- a/source/classes.tex +++ b/source/classes.tex @@ -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 diff --git a/source/containers.tex b/source/containers.tex index 3644b979167..5ff8465de78 100644 --- a/source/containers.tex +++ b/source/containers.tex @@ -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}, is not \oldconcept{CopyAssignable}. \end{note} @@ -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}, is not \oldconcept{CopyAssignable}. diff --git a/source/declarations.tex b/source/declarations.tex index 709ee00a69f..298a54d4175 100644 --- a/source/declarations.tex +++ b/source/declarations.tex @@ -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. @@ -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} @@ -6084,7 +6083,7 @@ corresponding element of the initializer list, and the \tcode{std::initializer_list} 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, @@ -7996,7 +7995,7 @@ \pnum \begin{note} Since destructors do not have names, a -\grammarterm{using-declaration} cannot refer to a +\grammarterm{using-declaration} is not able to refer to a destructor for a base class. \end{note} If a constructor or assignment operator brought from a base class into a derived class diff --git a/source/expressions.tex b/source/expressions.tex index e4c80eef646..0e071e43d8b 100644 --- a/source/expressions.tex +++ b/source/expressions.tex @@ -1394,7 +1394,7 @@ overload resolution is performed to select a unique function\iref{over.match,over.over}. \begin{note} -A program cannot refer to a function +A program is not able to refer to a function with a trailing \grammarterm{requires-clause} whose \grammarterm{constraint-expression} is not satisfied, because such functions are never selected by overload resolution. @@ -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} @@ -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} @@ -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 @@ -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 diff --git a/source/intro.tex b/source/intro.tex index a4fff15300c..d7192b6289a 100644 --- a/source/intro.tex +++ b/source/intro.tex @@ -11,10 +11,9 @@ requirement appear at various places within this document. \pnum -\Cpp{} is a general purpose programming language based on the C -programming language as described in \IsoC{}. -\Cpp{} provides many facilities -beyond those provided by C, including additional data types, +\Cpp{} is a general purpose programming language based on \IsoC{}. +\Cpp{} provides many facilities beyond those provided by \IsoC{}, +including additional data types, classes, templates, exceptions, namespaces, operator overloading, function name overloading, references, free store management operators, and additional library facilities.% diff --git a/source/iostreams.tex b/source/iostreams.tex index 39833d60d37..5ad9e6b2a1e 100644 --- a/source/iostreams.tex +++ b/source/iostreams.tex @@ -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 @@ -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 @@ -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} diff --git a/source/lex.tex b/source/lex.tex index 41d0e4702d1..cd23d400138 100644 --- a/source/lex.tex +++ b/source/lex.tex @@ -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|)} @@ -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} diff --git a/source/lib-intro.tex b/source/lib-intro.tex index 0594db60395..79cfa240c5b 100644 --- a/source/lib-intro.tex +++ b/source/lib-intro.tex @@ -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. @@ -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 @@ -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} diff --git a/source/templates.tex b/source/templates.tex index 048add70e24..29cb6360bda 100644 --- a/source/templates.tex +++ b/source/templates.tex @@ -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 T var = {}; @@ -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"? @@ -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 @@ -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 @@ -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. diff --git a/source/threads.tex b/source/threads.tex index c906079668c..923f60ec624 100644 --- a/source/threads.tex +++ b/source/threads.tex @@ -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} diff --git a/source/time.tex b/source/time.tex index 7fa74b7d306..39cf4579b00 100644 --- a/source/time.tex +++ b/source/time.tex @@ -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 diff --git a/source/utilities.tex b/source/utilities.tex index 4546698fb51..c62cf5d6e37 100644 --- a/source/utilities.tex +++ b/source/utilities.tex @@ -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}