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

   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.