87 lines · plain
1.. title:: clang-tidy - modernize-use-std-format2 3modernize-use-std-format4========================5 6Converts calls to ``absl::StrFormat``, or other functions via7configuration options, to C++20's ``std::format``, or another function8via a configuration option, modifying the format string appropriately and9removing now-unnecessary calls to ``std::string::c_str()`` and10``std::string::data()``.11 12For example, it turns lines like13 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 as25:doc:`modernize-use-std-print <../modernize/use-std-print>` and its26shortcomings and behaviour in combination with macros are described in the27documentation for that check.28 29Options30-------31 32.. option:: StrictMode33 34 When `true`, the check will add casts when converting from variadic35 functions and printing signed or unsigned integer types (including36 fixed-width integer types from ``<cstdint>``, ``ptrdiff_t``, ``size_t``37 and ``ssize_t``) as the opposite signedness to ensure that the output38 would matches that of a simple wrapper for ``std::sprintf`` that39 accepted a C-style variable argument list. For example, with40 `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 to50 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 representation56 of -42 and the signed representation of 0xffffffff (often 429496725457 and -1 respectively). When `false` (which is the default), these casts58 will not be added which may cause a change in the output. Note that this59 option makes no difference for the default value of60 `StrFormatLikeFunctions` since ``absl::StrFormat`` takes a function61 parameter pack and is not a variadic function.62 63.. option:: StrFormatLikeFunctions64 65 A semicolon-separated list of regular expressions matching the66 (fully qualified) names of functions to replace, with the requirement that67 the first parameter contains the printf-style format string and the68 arguments to be formatted follow immediately afterwards. Qualified member69 function names are supported, but the replacement function name must be70 unqualified. The default value is `absl::StrFormat`.71 72.. option:: ReplacementFormatFunction73 74 The function that will be used to replace the function set by the75 `StrFormatLikeFunctions` option rather than the default76 `std::format`. It is expected that the function provides an interface77 that is compatible with ``std::format``. A suitable candidate would be78 `fmt::format`.79 80.. option:: FormatHeader81 82 The header that must be included for the declaration of83 `ReplacementFormatFunction` so that a ``#include`` directive can be added if84 required. If `ReplacementFormatFunction` is `std::format` then this option will85 default to ``<format>``, otherwise this option will default to nothing86 and no ``#include`` directive will be added.87