Debian Codegraph @

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

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