#include <substring-locations.h>

Collaboration diagram for format_string_diagnostic_t:

Public Member Functions
	format_string_diagnostic_t (const substring_loc &fmt_loc, const range_label fmt_label, location_t param_loc, const range_label param_label, const char *corrected_substring)

bool	emit_warning_va (int opt, const char gmsgid, va_list ap) const ATTRIBUTE_GCC_DIAG(3

bool bool	emit_warning_n_va (int opt, unsigned HOST_WIDE_INT n, const char singular_gmsgid, const char plural_gmsgid, va_list *ap) const ATTRIBUTE_GCC_DIAG(4

bool bool	ATTRIBUTE_GCC_DIAG (5, 0)

bool	emit_warning (int opt, const char *gmsgid,...) const ATTRIBUTE_GCC_DIAG(3

bool bool	emit_warning_n (int opt, unsigned HOST_WIDE_INT n, const char singular_gmsgid, const char plural_gmsgid,...) const ATTRIBUTE_GCC_DIAG(4

bool bool	ATTRIBUTE_GCC_DIAG (5, 6)

Private Attributes
const substring_loc &	m_fmt_loc

const range_label *	m_fmt_label

location_t	m_param_loc

const range_label *	m_param_label

const char *	m_corrected_substring

Detailed Description

A bundle of state for emitting a diagnostic relating to a format string.

Constructor & Destructor Documentation

◆ format_string_diagnostic_t()

format_string_diagnostic_t::format_string_diagnostic_t	(	const substring_loc &	fmt_loc,
		const range_label *	fmt_label,
		location_t	param_loc,
		const range_label *	param_label,
		const char *	corrected_substring )

Source locations within string literals.
   Copyright (C) 2016-2024 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/>.

format_string_diagnostic_t's ctor, giving information for use by
  the emit_warning* member functions, as follows:

  They attempt to obtain precise location information within a string
  literal from FMT_LOC.

  Case 1: if substring location is available, and is within the range of
  the format string itself, the primary location of the
  diagnostic is the substring range obtained from FMT_LOC, with the
  caret at the *end* of the substring range.

  For example:

    test.c:90:10: warning: problem with '%i' here [-Wformat=]
    printf ("hello %i", msg);
                   ~^

  Case 2: if the substring location is available, but is not within
  the range of the format string, the primary location is that of the
  format string, and a note is emitted showing the substring location.

  For example:
    test.c:90:10: warning: problem with '%i' here [-Wformat=]
    printf("hello " INT_FMT " world", msg);
           ^~~~~~~~~~~~~~~~~~~~~~~~~
    test.c:19: note: format string is defined here
    #define INT_FMT "%i"
                     ~^

  Case 3: if precise substring information is unavailable, the primary
  location is that of the whole string passed to FMT_LOC's constructor.
  For example:

    test.c:90:10: warning: problem with '%i' here [-Wformat=]
    printf(fmt, msg);
           ^~~

  For each of cases 1-3, if param_loc is not UNKNOWN_LOCATION, then it is used
  as a secondary range within the warning.  For example, here it
  is used with case 1:

    test.c:90:16: warning: '%s' here but arg 2 has 'long' type [-Wformat=]
    printf ("foo %s bar", long_i + long_j);
                 ~^       ~~~~~~~~~~~~~~~

  and here with case 2:

    test.c:90:16: warning: '%s' here but arg 2 has 'long' type [-Wformat=]
    printf ("foo " STR_FMT " bar", long_i + long_j);
            ^~~~~~~~~~~~~~~~~~~~~  ~~~~~~~~~~~~~~~
    test.c:89:16: note: format string is defined here
    #define STR_FMT "%s"
                     ~^

  and with case 3:

    test.c:90:10: warning: '%i' here, but arg 2 is "const char *' [-Wformat=]
    printf(fmt, msg);
           ^~~  ~~~

  If non-NULL, then FMT_LABEL will be used to label the location within the
  string for cases 1 and 2; if non-NULL, then PARAM_LABEL will be used to label
  the parameter.  For example with case 1:

   test.c:90:16: warning: '%s' here but arg 2 has 'long' type [-Wformat=]
    printf ("foo %s bar", long_i + long_j);
                 ~^       ~~~~~~~~~~~~~~~
                                 |
                                 int

  and with case 2:

    test.c:90:10: warning: problem with '%i' here [-Wformat=]
    printf("hello " INT_FMT " world", msg);
           ^~~~~~~~~~~~~~~~~~~~~~~~~
    test.c:19: note: format string is defined here
    #define INT_FMT "%i"
                     ~^
                      |
                      int

  If CORRECTED_SUBSTRING is non-NULL, use it for cases 1 and 2 to provide
  a fix-it hint, suggesting that it should replace the text within the
  substring range.  For example:

    test.c:90:10: warning: problem with '%i' here [-Wformat=]
    printf ("hello %i", msg);
                   ~^
                   %s

Member Function Documentation

◆ ATTRIBUTE_GCC_DIAG() [1/2]

bool bool format_string_diagnostic_t::ATTRIBUTE_GCC_DIAG	(	5	,
		0	)

◆ ATTRIBUTE_GCC_DIAG() [2/2]

bool bool format_string_diagnostic_t::ATTRIBUTE_GCC_DIAG	(	5	,
		6	)

◆ emit_warning()

bool format_string_diagnostic_t::emit_warning	(	int	opt,
		const char *	gmsgid,
			... ) const

Variadic version of the above (singular only).

References ap, emit_warning_va(), and ggc_alloc().

◆ emit_warning_n()

bool format_string_diagnostic_t::emit_warning_n	(	int	opt,
		unsigned HOST_WIDE_INT	n,
		const char *	singular_gmsgid,
		const char *	plural_gmsgid,
			... ) const

Variadic version of the above (singular vs plural).

References ap, emit_warning_n_va(), and ggc_alloc().

◆ emit_warning_n_va()

bool format_string_diagnostic_t::emit_warning_n_va	(	int	opt,
		unsigned HOST_WIDE_INT	n,
		const char *	singular_gmsgid,
		const char *	plural_gmsgid,
		va_list *	ap ) const

Emit a warning governed by option OPT, using SINGULAR_GMSGID as the
format string (or if PLURAL_GMSGID is different from SINGULAR_GMSGID,
using SINGULAR_GMSGID, PLURAL_GMSGID and N as arguments to ngettext)
and AP as its arguments.

Return true if a warning was emitted, false otherwise.

References ap, diagnostic_report_diagnostic(), diagnostic_set_info(), diagnostic_set_info_translated(), substring_loc::get_fmt_string_loc(), substring_loc::get_location(), ggc_alloc(), global_dc, inform(), line_table, m_corrected_substring, m_fmt_label, m_fmt_loc, m_param_label, m_param_loc, ngettext, NULL, ULONG_MAX, and UNKNOWN_LOCATION.