clang-tools-extra/docs/clang-tidy/checks/misc-throw-by-value-catch-by-reference.rst

   1 .. title:: clang-tidy - misc-throw-by-value-catch-by-reference
   2
   3 misc-throw-by-value-catch-by-reference
   4 ======================================
   5
   6 `cert-err09-cpp` redirects here as an alias for this check.
   7 `cert-err61-cpp` redirects here as an alias for this check.
   8
   9 Finds violations of the rule "Throw by value, catch by reference" presented for
  10 example in "C++ Coding Standards" by H. Sutter and A. Alexandrescu, as well as
  11 the CERT C++ Coding Standard rule `ERR61-CPP. Catch exceptions by lvalue reference
  12 <https://wiki.sei.cmu.edu/confluence/display/cplusplus/ERR61-CPP.+Catch+exceptions+by+lvalue+reference>`_.
  13
  14
  15 Exceptions:
  16   * Throwing string literals will not be flagged despite being a pointer. They
  17     are not susceptible to slicing and the usage of string literals is
  18     idiomatic.
  19   * Catching character pointers (``char``, ``wchar_t``, unicode character types)
  20     will not be flagged to allow catching sting literals.
  21   * Moved named values will not be flagged as not throwing an anonymous
  22     temporary. In this case we can be sure that the user knows that the object
  23     can't be accessed outside catch blocks handling the error.
  24   * Throwing function parameters will not be flagged as not throwing an
  25     anonymous temporary. This allows helper functions for throwing.
  26   * Re-throwing caught exception variables will not be flagged as not throwing
  27     an anonymous temporary. Although this can usually be done by just writing
  28     ``throw;`` it happens often enough in real code.
  29
  30 Options
  31 -------
  32
  33 .. option:: CheckThrowTemporaries
  34
  35    Triggers detection of violations of the CERT recommendation ERR09-CPP. Throw
  36    anonymous temporaries.
  37    Default is `true`.
  38
  39 .. option:: WarnOnLargeObject
  40
  41    Also warns for any large, trivial object caught by value. Catching a large
  42    object by value is not dangerous but affects the performance negatively. The
  43    maximum size of an object allowed to be caught without warning can be set
  44    using the `MaxSize` option.
  45    Default is `false`.
  46
  47 .. option:: MaxSize
  48
  49    Determines the maximum size of an object allowed to be caught without
  50    warning. Only applicable if :option:`WarnOnLargeObject` is set to `true`. If
  51    the option is set by the user to `std::numeric_limits<uint64_t>::max()` then
  52    it reverts to the default value.
  53    Default is the size of `size_t`.