.. title:: clang-tidy - bugprone-exception-escape

bugprone-exception-escape
=========================

Finds functions which may throw an exception directly or indirectly, but they
should not. The functions which should not throw exceptions are the following:

* Destructors
* Move constructors
* Move assignment operators
* The ``main()`` functions
* ``swap()`` functions
* ``iter_swap()`` functions
* ``iter_move()`` functions
* Functions marked with ``throw()`` or ``noexcept``
* Other functions given as option

A destructor throwing an exception may result in undefined behavior, resource
leaks or unexpected termination of the program. Throwing move constructor or
move assignment also may result in undefined behavior or resource leak. The
``swap()`` operations expected to be non throwing most of the cases and they
are always possible to implement in a non throwing way. Non throwing ``swap()``
operations are also used to create move operations. A throwing ``main()``
function also results in unexpected termination.

Functions declared explicitly with ``noexcept(false)`` or ``throw(exception)``
will be excluded from the analysis, as even though it is not recommended for
functions like ``swap()``, ``main()``, move constructors, move assignment
operators and destructors, it is a clear indication of the developer's
intention and should be respected. To check if these special functions are
marked as potentially throwing, the check
:doc:`bugprone-unsafe-to-allow-exceptions <unsafe-to-allow-exceptions>` can be
used.

WARNING! This check may be expensive on large source files.

Options
-------

.. option:: CheckDestructors

   When `true`, destructors are analyzed to not throw exceptions.
   Default value is `true`.

.. option:: CheckMoveMemberFunctions

   When `true`, move constructors and move assignment operators are analyzed
   to not throw exceptions. Default value is `true`.

.. option:: CheckMain

   When `true`, the ``main()`` function is analyzed to not throw exceptions.
   Default value is `true`.

.. option:: CheckNothrowFunctions

   When `true`, functions marked with ``noexcept`` or ``throw()`` exception
   specifications are analyzed to not throw exceptions. Default value is `true`.

.. option:: CheckedSwapFunctions

   Comma-separated list of swap function names which should not throw exceptions.
   Default value is `swap,iter_swap,iter_move`.

.. option:: FunctionsThatShouldNotThrow

   Comma separated list containing function names which should not throw. An
   example value for this parameter can be ``WinMain`` which adds function
   ``WinMain()`` in the Windows API to the list of the functions which should
   not throw. Default value is an empty string.

.. option:: IgnoredExceptions

   Comma separated list containing type names which are not counted as thrown
   exceptions in the check. Default value is an empty string.

.. option:: TreatFunctionsWithoutSpecificationAsThrowing

   Determines which functions are considered as throwing if they do not have
   an explicit exception specification. It can be set to the following values:

   - `None`
      The check will consider functions without an explicit exception
      specification as throwing only if they have a visible definition which
      can be deduced to throw.
   - `OnlyUndefined`
      The check will consider functions with only a declaration available and
      no visible definition as throwing.
   - `All`
      The check will consider all functions without an explicit exception
      specification (such as ``noexcept``) as throwing, even if they have a
      visible definition and do not contain any throwing statements.

   Default value is `None`.