diff --git a/source/lib-intro.tex b/source/lib-intro.tex index 29eacd4316..eff21d116c 100644 --- a/source/lib-intro.tex +++ b/source/lib-intro.tex @@ -1214,12 +1214,13 @@ \tcode{} \\ \tcode{} \\ \tcode{} \\ +\tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ -\tcode{} \\ \columnbreak +\tcode{} \\ \tcode{} \\ \tcode{} \\ \tcode{} \\ @@ -1467,6 +1468,7 @@ \ref{support.start.term} & Start and termination & \tcode{} \\ \rowsep \ref{support.dynamic} & Dynamic memory management & \tcode{} \\ \rowsep \ref{support.rtti} & Type identification & \tcode{} \\ \rowsep +\ref{support.srcloc} & Source location & \tcode{} \\ \rowsep \ref{support.exception} & Exception handling & \tcode{} \\ \rowsep \ref{support.initlist} & Initializer lists & \tcode{} \\ \rowsep \ref{support.coroutine} & Coroutines support & \tcode{} \\ \rowsep diff --git a/source/support.tex b/source/support.tex index 7e3a76cac7..56e3c7b9d3 100644 --- a/source/support.tex +++ b/source/support.tex @@ -30,6 +30,7 @@ \ref{support.start.term} & Start and termination & \tcode{} \\ \rowsep \ref{support.dynamic} & Dynamic memory management & \tcode{} \\ \rowsep \ref{support.rtti} & Type identification & \tcode{} \\ \rowsep +\ref{support.srcloc} & Source location & \tcode{} \\ \rowsep \ref{support.exception} & Exception handling & \tcode{} \\ \rowsep \ref{support.initlist} & Initializer lists & \tcode{} \\ \rowsep \ref{cmp} & Comparisons & \tcode{} \\ \rowsep @@ -712,6 +713,8 @@ \tcode{} \\ \rowsep \defnlibxname{cpp_lib_shared_timed_mutex} & \tcode{201402L} & \tcode{} \\ \rowsep +\defnlibxname{cpp_lib_source_location} & \tcode{201907L} & + \tcode{} \\ \rowsep \defnlibxname{cpp_lib_spaceship} & \tcode{201907L} & \tcode{} \\ \rowsep \defnlibxname{cpp_lib_string_udls} & \tcode{201304L} & @@ -3178,6 +3181,214 @@ An \impldef{return value of \tcode{bad_typeid::what}} \ntbs{}. \end{itemdescr} +\rSec1[support.srcloc]{Class \tcode{source_location}} + +The header \tcode{} defines the class \tcode{source_location} that provides a means to obtain source location information. + +\rSec2[source_location.syn]{Header \tcode{} synopsis} +\indexhdr{source_location}% +\indexlibrary{\idxcode{source_location}}% + +\begin{codeblock} +namespace std { + struct source_location { + // source location construction + static consteval source_location current() noexcept; + constexpr source_location() noexcept; + + // source location field access + constexpr uint_least32_t line() const noexcept; + constexpr uint_least32_t column() const noexcept; + constexpr const char* file_name() const noexcept; + constexpr const char* function_name() const noexcept; + + private: + uint_least32_t line_; // \expos + uint_least32_t column_; // \expos + const char* file_name_; // \expos + const char* function_name_; // \expos + }; +} +\end{codeblock} + +\pnum +The type \tcode{source_location} meets the +\oldconcept{DefaultConstructible}, +\oldconcept{CopyConstructible}, +\oldconcept{Copy\-Assignable}, and +\oldconcept{Destructible} +requirements\iref{utility.arg.requirements}. +Lvalues of type \tcode{source_location} +are swappable\iref{swappable.requirements}. +All of the following conditions are \tcode{true}: +\begin{itemize} +\item \tcode{is_nothrow_move_constructible_v} +\item \tcode{is_nothrow_move_assignable_v} +\item \tcode{is_nothrow_swappable_v} +\end{itemize} +\begin{note} +The intent of \tcode{source_location} is +to have a small size and efficient copying. +\end{note} + +\pnum +The data members \tcode{file_name_} and \tcode{function_name_} +always each refer to an \ntbs{}. + +\pnum +The copy/move constructors and the copy/move assignment operators of +\tcode{source_location} meet the following postconditions: +Given two objects \tcode{lhs} and \tcode{rhs} of type \tcode{source_location}, +where \tcode{lhs} is a copy/move result of \tcode{rhs}, and +where \tcode{rhs_p} is a value denoting the state of \tcode{rhs} +before the corresponding copy/move operation, +then each of the following conditions is \tcode{true}: +\begin{itemize} +\item \tcode{strcmp(lhs.file_name(), rhs_p.file_name()) == 0} +\item \tcode{strcmp(lhs.function_name(), rhs_p.function_name()) == 0} +\item \tcode{lhs.line() == rhs_p.line()} +\item \tcode{lhs.column() == rhs_p.column()} +\end{itemize} + +\rSec2[support.srcloc.cons]{Creation} + +\begin{itemdecl} +static consteval source_location current() noexcept; +\end{itemdecl} +\begin{itemdescr} +\pnum +\returns +\begin{itemize} +\item + When invoked by a function call + whose \grammarterm{postfix-expression} is + a (possibly parenthesized) \grammarterm{id-expression} naming \tcode{current}, + returns a \tcode{source_location} with an implementation-defined value. + The value should be affected by \tcode{\#line}\iref{cpp.line} + in the same manner as for \mname{LINE} and \mname{FILE}. + The values of the exposition-only data members + of the returned \tcode{source_location} object + are indicated in \tref{support.srcloc.current}. + +\begin{libefftabvalue} + {Value of object returned by \tcode{current}} + {support.srcloc.current} +\tcode{line_} & + A presumed line number\iref{cpp.predefined}. + Line numbers are presumed to be 1-indexed; + however, an implementation is encouraged to use 0 + when the line number is unknown. \\ \rowsep +\tcode{column_} & + An implementation-defined value denoting + some offset from the start of the line denoted by \tcode{line_}. + Column numbers are presumed to be 1-indexed; + however, an implementation is encouraged to use 0 + when the column number is unknown. \\ \rowsep +\tcode{file_name_} & + A presumed name of the current source file\iref{cpp.predefined} as an \ntbs{}. + \\ \rowsep +\tcode{function_name_} & + A name of the current function + such as in \mname{func}\iref{dcl.fct.def.general} if any, + an empty string otherwise. \\ +\end{libefftabvalue} + +\item + Otherwise, when invoked in some other way, returns a + \tcode{source_location} whose data members are initialized + with valid but unspecified values. +\end{itemize} + +\pnum +\remarks +When a default member initializer +is used to initialize a non-static data member, +any calls to \tcode{current} should correspond to the location +of the constructor or aggregate initialization that initializes the member. + +\pnum +\begin{note} +When used as a default argument\iref{dcl.fct.default}, +the value of the \tcode{source_location} will be +the location of the call to \tcode{current} at the call site. +\end{note} +\end{itemdescr} + +\pnum +\begin{example} +\begin{codeblock} +struct s { + source_location member = source_location::current(); + int other_member; + s(source_location loc = source_location::current()) + : member(loc) // values of \tcode{member} refer to the location of the calling function\iref{dcl.fct.default} + {} + s(int blather) : // values of \tcode{member} refer to this location + other_member(blather) + {} + s(double) // values of \tcode{member} refer to this location + {} +}; +void f(source_location a = source_location::current()) { + source_location b = source_location::current(); // values in \tcode{b} refer to this line +} + +void g() { + f(); // \tcode{f}'s first argument corresponds to this line of code + + source_location c = source_location::current(); + f(c); // \tcode{f}'s first argument gets the same values as \tcode{c}, above +} +\end{codeblock} +\end{example} + +\begin{itemdecl} +constexpr source_location() noexcept; +\end{itemdecl} +\begin{itemdescr} + +\pnum +\Fundesc{Effects} +The data members are initialized with valid but unspecified values. +\end{itemdescr} + +\rSec2[support.srcloc.access]{Field access} + +\begin{itemdecl} +constexpr uint_least32_t line() const noexcept; +\end{itemdecl} +\begin{itemdescr} +\pnum +\returns \tcode{line_}. +\end{itemdescr} + +\begin{itemdecl} +constexpr uint_least32_t column() const noexcept; +\end{itemdecl} +\begin{itemdescr} +\pnum +\returns +\tcode{column_}. +\end{itemdescr} + +\begin{itemdecl} +constexpr const char* file_name() const noexcept; +\end{itemdecl} +\begin{itemdescr} +\pnum +\returns +\tcode{file_name_}. +\end{itemdescr} + +\begin{itemdecl} +constexpr const char* function_name() const noexcept; +\end{itemdecl} +\begin{itemdescr} +\pnum +\returns +\tcode{function_name_}. +\end{itemdescr} + \rSec1[support.exception]{Exception handling} \pnum