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