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