Debian Codegraph @

clang-tools-extra/docs/clang-tidy/checks/modernize/use-std-format.rst

raw
1 .. title:: clang-tidy - modernize-use-std-format
2
3 modernize-use-std-format
4 ========================
5
6 Converts calls to ``absl::StrFormat``, or other functions via
7 configuration options, to C++20's ``std::format``, or another function
8 via a configuration option, modifying the format string appropriately and
9 removing now-unnecessary calls to ``std::string::c_str()`` and
10 ``std::string::data()``.
11
12 For example, it turns lines like
13
14 .. code-block:: c++
15
16 return absl::StrFormat("The %s is %3d", description.c_str(), value);
17
18 into:
19
20 .. code-block:: c++
21
22 return std::format("The {} is {:3}", description, value);
23
24 The check uses the same format-string-conversion algorithm as
25 `modernize-use-std-print <../modernize/use-std-print.html>`_ and its
26 shortcomings are described in the documentation for that check.
27
28 Options
29 -------
30
31 .. option:: StrictMode
32
33 When `true`, the check will add casts when converting from variadic
34 functions and printing signed or unsigned integer types (including
35 fixed-width integer types from ``<cstdint>``, ``ptrdiff_t``, ``size_t``
36 and ``ssize_t``) as the opposite signedness to ensure that the output
37 would matches that of a simple wrapper for ``std::sprintf`` that
38 accepted a C-style variable argument list. For example, with
39 `StrictMode` enabled,
40
41 .. code-block:: c++
42
43 extern std::string strprintf(const char *format, ...);
44 int i = -42;
45 unsigned int u = 0xffffffff;
46 return strprintf("%d %u\n", i, u);
47
48 would be converted to
49
50 .. code-block:: c++
51
52 return std::format("{} {}\n", static_cast<unsigned int>(i), static_cast<int>(u));
53
54 to ensure that the output will continue to be the unsigned representation
55 of -42 and the signed representation of 0xffffffff (often 4294967254
56 and -1 respectively). When `false` (which is the default), these casts
57 will not be added which may cause a change in the output. Note that this
58 option makes no difference for the default value of
59 `StrFormatLikeFunctions` since ``absl::StrFormat`` takes a function
60 parameter pack and is not a variadic function.
61
62 .. option:: StrFormatLikeFunctions
63
64 A semicolon-separated list of (fully qualified) function names to
65 replace, with the requirement that the first parameter contains the
66 printf-style format string and the arguments to be formatted follow
67 immediately afterwards. The default value for this option is
68 `absl::StrFormat`.
69
70 .. option:: ReplacementFormatFunction
71
72 The function that will be used to replace the function set by the
73 `StrFormatLikeFunctions` option rather than the default
74 `std::format`. It is expected that the function provides an interface
75 that is compatible with ``std::format``. A suitable candidate would be
76 `fmt::format`.
77
78 .. option:: FormatHeader
79
80 The header that must be included for the declaration of
81 `ReplacementFormatFunction` so that a ``#include`` directive can be added if
82 required. If `ReplacementFormatFunction` is `std::format` then this option will
83 default to ``<format>``, otherwise this option will default to nothing
84 and no ``#include`` directive will be added.