| 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. |