function
<exception>

std::throw_with_nested

[[noreturn]] template <class T>  void throw_with_nested (T&& e);
Throw with nested
Throws an exception that combines both the currently handled exception and e.

The currently handled exception becomes the nested exception and e the outer exception.

The type of the exception thrown is publicly derived both from T and from the currently handled exception (the latter as the nested_exception component).

If T is a reference type, the type from which it inherits is the non-reference type to which T refers, which shall be copy constructible.

If no exception is currently being handled by a catch block, the nested excepetion is a null exception_ptr.

Parameters

e
An object or reference of a non-union class not derived from nested_exception.

Return value

none (the function never returns).

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
// throw_with_nested/rethrow_if_nested example
#include <iostream>       // std::cerr
#include <exception>      // std::exception, std::throw_with_nested, std::rethrow_if_nested
#include <stdexcept>      // std::logic_error

// recursively print exception whats:
void print_what (const std::exception& e) {
  std::cerr << e.what() << '\n';
  try {
    std::rethrow_if_nested(e);
  } catch (const std::exception& nested) {
    std::cerr << "nested: ";
    print_what(nested);
  }
}

// throws an exception nested in another:
void throw_nested() {
  try {
    throw std::logic_error ("first");
  } catch (const std::exception& e) {
    std::throw_with_nested(std::logic_error("second"));
  }
}

int main () {
  try {
    throw_nested();
  } catch (std::exception& e) {
    print_what(e);
  }

  return 0;
}

Output:

second
nested: first


Exception safety

Throws an exception.

If the argument is not of the proper type (as described above), the call causes undefined behavior.

See also