Source locations within string literals.
Copyright (C) 2016-2025 Free Software Foundation, Inc.
This file is part of GCC.
GCC is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free
Software Foundation; either version 3, or (at your option) any later
version.
GCC is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
for more details.
You should have received a copy of the GNU General Public License
along with GCC; see the file COPYING3. If not see
<http://www.gnu.org/licenses/>.
The substring_loc class encapsulates information on the source location
of a range of characters within a STRING_CST.
If needed by a diagnostic, the actual location_t of the substring_loc
can be calculated by calling its get_location method. This calls a
langhook, since this is inherently frontend-specific. For the C family
of frontends, it calls back into libcpp to reparse the strings. This
gets the location information "on demand", rather than storing the
location information in the initial lex for every string. Thus the
substring_loc can also be thought of as a deferred call into libcpp,
to allow the non-trivial work of reparsing the string to be delayed
until we actually need it (to emit a diagnostic for a particular range
of characters).
substring_loc::get_location returns NULL if it succeeds, or an
error message if it fails. Error messages are intended for GCC
developers (to help debugging) rather than for end-users.
The easiest way to use a substring_loc is via the format_warning_* APIs,
which gracefully handle failure of substring_loc::get_location by using
the location of the string as a whole if substring-information is
unavailable.