Debian Codegraph @

llvm-project/clang-tools-extra/docs/clang-tidy/checks/cppcoreguidelines/narrowing-conversions.rst

raw
1 .. title:: clang-tidy - cppcoreguidelines-narrowing-conversions
2
3 cppcoreguidelines-narrowing-conversions
4 =======================================
5
6 Checks for silent narrowing conversions, e.g: ``int i = 0; i += 0.1;``. While
7 the issue is obvious in this former example, it might not be so in the
8 following: ``void MyClass::f(double d) { int_member_ += d; }``.
9
10 This rule is part of the "Expressions and statements" profile of the C++ Core
11 Guidelines, corresponding to rule ES.46. See
12
13 https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#es46-avoid-lossy-narrowing-truncating-arithmetic-conversions.
14
15 We enforce only part of the guideline, more specifically, we flag narrowing conversions from:
16 - an integer to a narrower integer (e.g. ``char`` to ``unsigned char``)
17 if WarnOnIntegerNarrowingConversion Option is set,
18 - an integer to a narrower floating-point (e.g. ``uint64_t`` to ``float``)
19 if WarnOnIntegerToFloatingPointNarrowingConversion Option is set,
20 - a floating-point to an integer (e.g. ``double`` to ``int``),
21 - a floating-point to a narrower floating-point (e.g. ``double`` to ``float``)
22 if WarnOnFloatingPointNarrowingConversion Option is set.
23
24 This check will flag:
25 - All narrowing conversions that are not marked by an explicit cast (c-style or
26 ``static_cast``). For example: ``int i = 0; i += 0.1;``,
27 ``void f(int); f(0.1);``,
28 - All applications of binary operators with a narrowing conversions.
29 For example: ``int i; i+= 0.1;``.
30
31
32 Options
33 -------
34
35 .. option:: WarnOnIntegerNarrowingConversion
36
37 When `true`, the check will warn on narrowing integer conversion
38 (e.g. ``int`` to ``size_t``). `true` by default.
39
40 .. option:: WarnOnIntegerToFloatingPointNarrowingConversion
41
42 When `true`, the check will warn on narrowing integer to floating-point
43 conversion (e.g. ``size_t`` to ``double``). `true` by default.
44
45 .. option:: WarnOnFloatingPointNarrowingConversion
46
47 When `true`, the check will warn on narrowing floating point conversion
48 (e.g. ``double`` to ``float``). `true` by default.
49
50 .. option:: WarnWithinTemplateInstantiation
51
52 When `true`, the check will warn on narrowing conversions within template
53 instantiations. `false` by default.
54
55 .. option:: WarnOnEquivalentBitWidth
56
57 When `true`, the check will warn on narrowing conversions that arise from
58 casting between types of equivalent bit width. (e.g.
59 `int n = uint(0);` or `long long n = double(0);`) `true` by default.
60
61 .. option:: IgnoreConversionFromTypes
62
63 Narrowing conversions from any type in this semicolon-separated list will be
64 ignored. This may be useful to weed out commonly occurring, but less commonly
65 problematic assignments such as `int n = std::vector<char>().size();` or
66 `int n = std::difference(it1, it2);`. The default list is empty, but one
67 suggested list for a legacy codebase would be
68 `size_t;ptrdiff_t;size_type;difference_type`.
69
70 .. option:: PedanticMode
71
72 When `true`, the check will warn on assigning a floating point constant
73 to an integer value even if the floating point value is exactly
74 representable in the destination type (e.g. ``int i = 1.0;``).
75 `false` by default.
76
77 FAQ
78 ---
79
80 - What does "narrowing conversion from 'int' to 'float'" mean?
81
82 An IEEE754 Floating Point number can represent all integer values in the range
83 [-2^PrecisionBits, 2^PrecisionBits] where PrecisionBits is the number of bits in
84 the mantissa.
85
86 For ``float`` this would be [-2^23, 2^23], where ``int`` can represent values in
87 the range [-2^31, 2^31-1].
88
89 - What does "implementation-defined" mean?
90
91 You may have encountered messages like "narrowing conversion from 'unsigned int'
92 to signed type 'int' is implementation-defined".
93 The C/C++ standard does not mandate two's complement for signed integers, and so
94 the compiler is free to define what the semantics are for converting an unsigned
95 integer to signed integer. Clang's implementation uses the two's complement
96 format.