Skip to content

Commit d7fe087

Browse files
jensmaurerzygoloid
jensmaurer
authored and
zygoloid
committed
P1208R6 Adopt source_location for C++20
 - Changed stable name to [support.srcloc]. - Added cross-references. - Changed "description" environment showing result values to a table
1 parent d3506cf commit d7fe087

File tree

2 files changed

+214
-1
lines changed

2 files changed

+214
-1
lines changed

‎source/lib-intro.tex

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1214,12 +1214,13 @@
12141214
\tcode{<semaphore>} \\
12151215
\tcode{<set>} \\
12161216
\tcode{<shared_mutex>} \\
1217+
\tcode{<source_location>} \\
12171218
\tcode{<span>} \\
12181219
\tcode{<sstream>} \\
12191220
\tcode{<stack>} \\
12201221
\tcode{<stdexcept>} \\
1221-
\tcode{<stop_token>} \\
12221222
\columnbreak
1223+
\tcode{<stop_token>} \\
12231224
\tcode{<streambuf>} \\
12241225
\tcode{<string>} \\
12251226
\tcode{<string_view>} \\
@@ -1467,6 +1468,7 @@
14671468
\ref{support.start.term} & Start and termination & \tcode{<cstdlib>} \\ \rowsep
14681469
\ref{support.dynamic} & Dynamic memory management & \tcode{<new>} \\ \rowsep
14691470
\ref{support.rtti} & Type identification & \tcode{<typeinfo>} \\ \rowsep
1471+
\ref{support.srcloc} & Source location & \tcode{<source_location>} \\ \rowsep
14701472
\ref{support.exception} & Exception handling & \tcode{<exception>} \\ \rowsep
14711473
\ref{support.initlist} & Initializer lists & \tcode{<initializer_list>} \\ \rowsep
14721474
\ref{support.coroutine} & Coroutines support & \tcode{<coroutine>} \\ \rowsep

‎source/support.tex

Lines changed: 211 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@
3030
\ref{support.start.term} & Start and termination & \tcode{<cstdlib>} \\ \rowsep
3131
\ref{support.dynamic} & Dynamic memory management & \tcode{<new>} \\ \rowsep
3232
\ref{support.rtti} & Type identification & \tcode{<typeinfo>} \\ \rowsep
33+
\ref{support.srcloc} & Source location & \tcode{<source_location>} \\ \rowsep
3334
\ref{support.exception} & Exception handling & \tcode{<exception>} \\ \rowsep
3435
\ref{support.initlist} & Initializer lists & \tcode{<initializer_list>} \\ \rowsep
3536
\ref{cmp} & Comparisons & \tcode{<compare>} \\ \rowsep
@@ -712,6 +713,8 @@
712713
\tcode{<memory>} \\ \rowsep
713714
\defnlibxname{cpp_lib_shared_timed_mutex} & \tcode{201402L} &
714715
\tcode{<shared_mutex>} \\ \rowsep
716+
\defnlibxname{cpp_lib_source_location} & \tcode{201907L} &
717+
\tcode{<source_location>} \\ \rowsep
715718
\defnlibxname{cpp_lib_spaceship} & \tcode{201907L} &
716719
\tcode{<compare>} \\ \rowsep
717720
\defnlibxname{cpp_lib_string_udls} & \tcode{201304L} &
@@ -3178,6 +3181,214 @@
31783181
An \impldef{return value of \tcode{bad_typeid::what}} \ntbs{}.
31793182
\end{itemdescr}
31803183

3184+
\rSec1[support.srcloc]{Class \tcode{source_location}}
3185+
3186+
The header \tcode{<source_location>} defines the class \tcode{source_location} that provides a means to obtain source location information.
3187+
3188+
\rSec2[source_location.syn]{Header \tcode{<source_location>} synopsis}
3189+
\indexhdr{source_location}%
3190+
\indexlibrary{\idxcode{source_location}}%
3191+
3192+
\begin{codeblock}
3193+
namespace std {
3194+
struct source_location {
3195+
// source location construction
3196+
static consteval source_location current() noexcept;
3197+
constexpr source_location() noexcept;
3198+
3199+
// source location field access
3200+
constexpr uint_least32_t line() const noexcept;
3201+
constexpr uint_least32_t column() const noexcept;
3202+
constexpr const char* file_name() const noexcept;
3203+
constexpr const char* function_name() const noexcept;
3204+
3205+
private:
3206+
uint_least32_t line_; // \expos
3207+
uint_least32_t column_; // \expos
3208+
const char* file_name_; // \expos
3209+
const char* function_name_; // \expos
3210+
};
3211+
}
3212+
\end{codeblock}
3213+
3214+
\pnum
3215+
The type \tcode{source_location} meets the
3216+
\oldconcept{DefaultConstructible},
3217+
\oldconcept{CopyConstructible},
3218+
\oldconcept{Copy\-Assignable}, and
3219+
\oldconcept{Destructible}
3220+
requirements\iref{utility.arg.requirements}.
3221+
Lvalues of type \tcode{source_location}
3222+
are swappable\iref{swappable.requirements}.
3223+
All of the following conditions are \tcode{true}:
3224+
\begin{itemize}
3225+
\item \tcode{is_nothrow_move_constructible_v<source_location>}
3226+
\item \tcode{is_nothrow_move_assignable_v<source_location>}
3227+
\item \tcode{is_nothrow_swappable_v<source_location>}
3228+
\end{itemize}
3229+
\begin{note}
3230+
The intent of \tcode{source_location} is
3231+
to have a small size and efficient copying.
3232+
\end{note}
3233+
3234+
\pnum
3235+
The data members \tcode{file_name_} and \tcode{function_name_}
3236+
always each refer to an \ntbs{}.
3237+
3238+
\pnum
3239+
The copy/move constructors and the copy/move assignment operators of
3240+
\tcode{source_location} meet the following postconditions:
3241+
Given two objects \tcode{lhs} and \tcode{rhs} of type \tcode{source_location},
3242+
where \tcode{lhs} is a copy/move result of \tcode{rhs}, and
3243+
where \tcode{rhs_p} is a value denoting the state of \tcode{rhs}
3244+
before the corresponding copy/move operation,
3245+
then each of the following conditions is \tcode{true}:
3246+
\begin{itemize}
3247+
\item \tcode{strcmp(lhs.file_name(), rhs_p.file_name()) == 0}
3248+
\item \tcode{strcmp(lhs.function_name(), rhs_p.function_name()) == 0}
3249+
\item \tcode{lhs.line() == rhs_p.line()}
3250+
\item \tcode{lhs.column() == rhs_p.column()}
3251+
\end{itemize}
3252+
3253+
\rSec2[support.srcloc.cons]{Creation}
3254+
3255+
\begin{itemdecl}
3256+
static consteval source_location current() noexcept;
3257+
\end{itemdecl}
3258+
\begin{itemdescr}
3259+
\pnum
3260+
\returns
3261+
\begin{itemize}
3262+
\item
3263+
When invoked by a function call
3264+
whose \grammarterm{postfix-expression} is
3265+
a (possibly parenthesized) \grammarterm{id-expression} naming \tcode{current},
3266+
returns a \tcode{source_location} with an implementation-defined value.
3267+
The value should be affected by \tcode{\#line}\iref{cpp.line}
3268+
in the same manner as for \mname{LINE} and \mname{FILE}.
3269+
The values of the exposition-only data members
3270+
of the returned \tcode{source_location} object
3271+
are indicated in \tref{support.srcloc.current}.
3272+
3273+
\begin{libefftabvalue}
3274+
{Value of object returned by \tcode{current}}
3275+
{support.srcloc.current}
3276+
\tcode{line_} &
3277+
A presumed line number\iref{cpp.predefined}.
3278+
Line numbers are presumed to be 1-indexed;
3279+
however, an implementation is encouraged to use 0
3280+
when the line number is unknown. \\ \rowsep
3281+
\tcode{column_} &
3282+
An implementation-defined value denoting
3283+
some offset from the start of the line denoted by \tcode{line_}.
3284+
Column numbers are presumed to be 1-indexed;
3285+
however, an implementation is encouraged to use 0
3286+
when the column number is unknown. \\ \rowsep
3287+
\tcode{file_name_} &
3288+
A presumed name of the current source file\iref{cpp.predefined} as an \ntbs{}.
3289+
\\ \rowsep
3290+
\tcode{function_name_} &
3291+
A name of the current function
3292+
such as in \mname{func}\iref{dcl.fct.def.general} if any,
3293+
an empty string otherwise. \\
3294+
\end{libefftabvalue}
3295+
3296+
\item
3297+
Otherwise, when invoked in some other way, returns a
3298+
\tcode{source_location} whose data members are initialized
3299+
with valid but unspecified values.
3300+
\end{itemize}
3301+
3302+
\pnum
3303+
\remarks
3304+
When a \grammarterm{brace-or-equal-initializer}
3305+
is used to initialize a non-static data member,
3306+
any calls to \tcode{current} should correspond to the location
3307+
of the constructor or aggregate initialization that initializes the member.
3308+
3309+
\pnum
3310+
\begin{note}
3311+
When used as a default argument\iref{dcl.fct.default},
3312+
the value of the \tcode{source_location} will be
3313+
the location of the call to \tcode{current} at the call site.
3314+
\end{note}
3315+
\end{itemdescr}
3316+
3317+
\pnum
3318+
\begin{example}
3319+
\begin{codeblock}
3320+
struct s {
3321+
source_location member = source_location::current();
3322+
int other_member;
3323+
s(source_location loc = source_location::current())
3324+
: member(loc) // values of \tcode{member} will be from call-site
3325+
{}
3326+
s(int blather) : // values of \tcode{member} should be hereabouts
3327+
other_member(blather)
3328+
{}
3329+
s(double) // values of \tcode{member} should be hereabouts
3330+
{}
3331+
};
3332+
void f(source_location a = source_location::current()) {
3333+
source_location b = source_location::current(); // values in \tcode{b} represent this line
3334+
}
3335+
3336+
void g() {
3337+
f(); // \tcode{f}'s first argument corresponds to this line of code
3338+
3339+
source_location c = source_location::current();
3340+
f(c); // \tcode{f}'s first argument gets the same values as \tcode{c}, above
3341+
}
3342+
\end{codeblock}
3343+
\end{example}
3344+
3345+
\begin{itemdecl}
3346+
constexpr source_location() noexcept;
3347+
\end{itemdecl}
3348+
\begin{itemdescr}
3349+
3350+
\pnum
3351+
\Fundesc{Effects}
3352+
The data members are initialized with valid but unspecified values.
3353+
\end{itemdescr}
3354+
3355+
\rSec2[support.srcloc.access]{Field access}
3356+
3357+
\begin{itemdecl}
3358+
constexpr uint_least32_t line() const noexcept;
3359+
\end{itemdecl}
3360+
\begin{itemdescr}
3361+
\pnum
3362+
\returns \tcode{line_}.
3363+
\end{itemdescr}
3364+
3365+
\begin{itemdecl}
3366+
constexpr uint_least32_t column() const noexcept;
3367+
\end{itemdecl}
3368+
\begin{itemdescr}
3369+
\pnum
3370+
\returns
3371+
\tcode{column_}.
3372+
\end{itemdescr}
3373+
3374+
\begin{itemdecl}
3375+
constexpr const char* file_name() const noexcept;
3376+
\end{itemdecl}
3377+
\begin{itemdescr}
3378+
\pnum
3379+
\returns
3380+
\tcode{file_name_}.
3381+
\end{itemdescr}
3382+
3383+
\begin{itemdecl}
3384+
constexpr const char* function_name() const noexcept;
3385+
\end{itemdecl}
3386+
\begin{itemdescr}
3387+
\pnum
3388+
\returns
3389+
\tcode{function_name_}.
3390+
\end{itemdescr}
3391+
31813392
\rSec1[support.exception]{Exception handling}
31823393

31833394
\pnum

0 commit comments

Comments
 (0)