| 1 |
.. title:: clang-tidy - modernize-use-std-print |
| 2 |
|
| 3 |
modernize-use-std-print |
| 4 |
======================= |
| 5 |
|
| 6 |
Converts calls to ``printf``, ``fprintf``, ``absl::PrintF`` and |
| 7 |
``absl::FPrintf`` to equivalent calls to C++23's ``std::print`` or |
| 8 |
``std::println`` as appropriate, modifying the format string appropriately. |
| 9 |
The replaced and replacement functions can be customised by configuration |
| 10 |
options. Each argument that is the result of a call to ``std::string::c_str()`` and |
| 11 |
``std::string::data()`` will have that now-unnecessary call removed in a |
| 12 |
similar manner to the `readability-redundant-string-cstr` check. |
| 13 |
|
| 14 |
In other words, it turns lines like: |
| 15 |
|
| 16 |
.. code-block:: c++ |
| 17 |
|
| 18 |
fprintf(stderr, "The %s is %3d\n", description.c_str(), value); |
| 19 |
|
| 20 |
into: |
| 21 |
|
| 22 |
.. code-block:: c++ |
| 23 |
|
| 24 |
std::println(stderr, "The {} is {:3}", description, value); |
| 25 |
|
| 26 |
If the `ReplacementPrintFunction` or `ReplacementPrintlnFunction` options |
| 27 |
are left, or assigned to their default values then this check is only |
| 28 |
enabled with `-std=c++23` or later. |
| 29 |
|
| 30 |
The check doesn't do a bad job, but it's not perfect. In particular: |
| 31 |
|
| 32 |
- It assumes that the format string is correct for the arguments. If you |
| 33 |
get any warnings when compiling with `-Wformat` then misbehaviour is |
| 34 |
possible. |
| 35 |
|
| 36 |
- At the point that the check runs, the AST contains a single |
| 37 |
``StringLiteral`` for the format string and any macro expansion, token |
| 38 |
pasting, adjacent string literal concatenation and escaping has been |
| 39 |
handled. Although it's possible for the check to automatically put the |
| 40 |
escapes back, they may not be exactly as they were written (e.g. |
| 41 |
``"\x0a"`` will become ``"\n"`` and ``"ab" "cd"`` will become |
| 42 |
``"abcd"``.) This is helpful since it means that the ``PRIx`` macros from |
| 43 |
``<inttypes.h>`` are removed correctly. |
| 44 |
|
| 45 |
- It supports field widths, precision, positional arguments, leading zeros, |
| 46 |
leading ``+``, alignment and alternative forms. |
| 47 |
|
| 48 |
- Use of any unsupported flags or specifiers will cause the entire |
| 49 |
statement to be left alone and a warning to be emitted. Particular |
| 50 |
unsupported features are: |
| 51 |
|
| 52 |
- The ``%'`` flag for thousands separators. |
| 53 |
|
| 54 |
- The glibc extension ``%m``. |
| 55 |
|
| 56 |
- ``printf`` and similar functions return the number of characters printed. |
| 57 |
``std::print`` does not. This means that any invocations that use the |
| 58 |
return value will not be converted. Unfortunately this currently includes |
| 59 |
explicitly-casting to ``void``. Deficiencies in this check mean that any |
| 60 |
invocations inside ``GCC`` compound statements cannot be converted even |
| 61 |
if the resulting value is not used. |
| 62 |
|
| 63 |
If conversion would be incomplete or unsafe then the entire invocation will |
| 64 |
be left unchanged. |
| 65 |
|
| 66 |
If the call is deemed suitable for conversion then: |
| 67 |
|
| 68 |
- ``printf``, ``fprintf``, ``absl::PrintF``, ``absl::FPrintF`` and any |
| 69 |
functions specified by the `PrintfLikeFunctions` option or |
| 70 |
`FprintfLikeFunctions` are replaced with the function specified by the |
| 71 |
`ReplacementPrintlnFunction` option if the format string ends with ``\n`` |
| 72 |
or `ReplacementPrintFunction` otherwise. |
| 73 |
- the format string is rewritten to use the ``std::formatter`` language. If |
| 74 |
a ``\n`` is found at the end of the format string not preceded by ``r`` |
| 75 |
then it is removed and `ReplacementPrintlnFunction` is used rather than |
| 76 |
`ReplacementPrintFunction`. |
| 77 |
- any arguments that corresponded to ``%p`` specifiers that |
| 78 |
``std::formatter`` wouldn't accept are wrapped in a ``static_cast`` |
| 79 |
to ``const void *``. |
| 80 |
- any arguments that corresponded to ``%s`` specifiers where the argument |
| 81 |
is of ``signed char`` or ``unsigned char`` type are wrapped in a |
| 82 |
``reinterpret_cast<const char *>``. |
| 83 |
- any arguments where the format string and the parameter differ in |
| 84 |
signedness will be wrapped in an appropriate ``static_cast`` if `StrictMode` |
| 85 |
is enabled. |
| 86 |
- any arguments that end in a call to ``std::string::c_str()`` or |
| 87 |
``std::string::data()`` will have that call removed. |
| 88 |
|
| 89 |
Options |
| 90 |
------- |
| 91 |
|
| 92 |
.. option:: StrictMode |
| 93 |
|
| 94 |
When `true`, the check will add casts when converting from variadic |
| 95 |
functions like ``printf`` and printing signed or unsigned integer types |
| 96 |
(including fixed-width integer types from ``<cstdint>``, ``ptrdiff_t``, |
| 97 |
``size_t`` and ``ssize_t``) as the opposite signedness to ensure that |
| 98 |
the output matches that of ``printf``. This does not apply when |
| 99 |
converting from non-variadic functions such as ``absl::PrintF`` and |
| 100 |
``fmt::printf``. For example, with `StrictMode` enabled: |
| 101 |
|
| 102 |
.. code-block:: c++ |
| 103 |
|
| 104 |
int i = -42; |
| 105 |
unsigned int u = 0xffffffff; |
| 106 |
printf("%d %u\n", i, u); |
| 107 |
|
| 108 |
would be converted to: |
| 109 |
|
| 110 |
.. code-block:: c++ |
| 111 |
|
| 112 |
std::print("{} {}\n", static_cast<unsigned int>(i), static_cast<int>(u)); |
| 113 |
|
| 114 |
to ensure that the output will continue to be the unsigned representation |
| 115 |
of `-42` and the signed representation of `0xffffffff` (often |
| 116 |
`4294967254` and `-1` respectively.) When `false` (which is the default), |
| 117 |
these casts will not be added which may cause a change in the output. |
| 118 |
|
| 119 |
.. option:: PrintfLikeFunctions |
| 120 |
|
| 121 |
A semicolon-separated list of (fully qualified) function names to |
| 122 |
replace, with the requirement that the first parameter contains the |
| 123 |
printf-style format string and the arguments to be formatted follow |
| 124 |
immediately afterwards. If neither this option nor |
| 125 |
`FprintfLikeFunctions` are set then the default value for this option |
| 126 |
is `printf; absl::PrintF`, otherwise it is empty. |
| 127 |
|
| 128 |
|
| 129 |
.. option:: FprintfLikeFunctions |
| 130 |
|
| 131 |
A semicolon-separated list of (fully qualified) function names to |
| 132 |
replace, with the requirement that the first parameter is retained, the |
| 133 |
second parameter contains the printf-style format string and the |
| 134 |
arguments to be formatted follow immediately afterwards. If neither this |
| 135 |
option nor `PrintfLikeFunctions` are set then the default value for |
| 136 |
this option is `fprintf; absl::FPrintF`, otherwise it is empty. |
| 137 |
|
| 138 |
.. option:: ReplacementPrintFunction |
| 139 |
|
| 140 |
The function that will be used to replace ``printf``, ``fprintf`` etc. |
| 141 |
during conversion rather than the default ``std::print`` when the |
| 142 |
originalformat string does not end with ``\n``. It is expected that the |
| 143 |
function provides an interface that is compatible with ``std::print``. A |
| 144 |
suitable candidate would be ``fmt::print``. |
| 145 |
|
| 146 |
.. option:: ReplacementPrintlnFunction |
| 147 |
|
| 148 |
The function that will be used to replace ``printf``, ``fprintf`` etc. |
| 149 |
during conversion rather than the default ``std::println`` when the |
| 150 |
original format string ends with ``\n``. It is expected that the |
| 151 |
function provides an interface that is compatible with ``std::println``. |
| 152 |
A suitable candidate would be ``fmt::println``. |
| 153 |
|
| 154 |
.. option:: PrintHeader |
| 155 |
|
| 156 |
The header that must be included for the declaration of |
| 157 |
`ReplacementPrintFunction` so that a ``#include`` directive can be |
| 158 |
added if required. If `ReplacementPrintFunction` is ``std::print`` |
| 159 |
then this option will default to ``<print>``, otherwise this option will |
| 160 |
default to nothing and no ``#include`` directive will be added. |