17 Language support library [support]

17.9 Exception handling [support.exception]

17.9.7 nested_­exception [except.nested]

namespace std {
  class nested_exception {
  public:
    nested_exception() noexcept;
    nested_exception(const nested_exception&) noexcept = default;
    nested_exception& operator=(const nested_exception&) noexcept = default;
    virtual ~nested_exception() = default;

    // access functions
    [[noreturn]] void rethrow_nested() const;
    exception_ptr nested_ptr() const noexcept;
  };

  template<class T> [[noreturn]] void throw_with_nested(T&& t);
  template<class E> void rethrow_if_nested(const E& e);
}
1
#
The class nested_­exception is designed for use as a mixin through multiple inheritance.
It captures the currently handled exception and stores it for later use.
2
#
[ Note
:
nested_­exception has a virtual destructor to make it a polymorphic class.
Its presence can be tested for with dynamic_­cast.
— end note
 ]
🔗
nested_exception() noexcept;
3
#
Effects: The constructor calls current_­exception() and stores the returned value.
🔗
[[noreturn]] void rethrow_nested() const;
4
#
Effects: If nested_­ptr() returns a null pointer, the function calls the function std​::​terminate.
Otherwise, it throws the stored exception captured by *this.
🔗
exception_ptr nested_ptr() const noexcept;
5
#
Returns: The stored exception captured by this nested_­exception object.
🔗
template<class T> [[noreturn]] void throw_with_nested(T&& t);
6
#
Let U be decay_­t<T>.
7
#
Preconditions: U meets the Cpp17CopyConstructible requirements.
8
#
Throws: If is_­class_­v<U> && !is_­final_­v<U> && !is_­base_­of_­v<nested_­exception, U> is true, an exception of unspecified type that is publicly derived from both U and nested_­exception and constructed from std​::​forward<T>(t), otherwise std​::​forward<T>(t).
🔗
template<class E> void rethrow_if_nested(const E& e);
9
#
Effects: If E is not a polymorphic class type, or if nested_­exception is an inaccessible or ambiguous base class of E, there is no effect.
Otherwise, performs: 
if (auto p = dynamic_cast<const nested_exception*>(addressof(e)))
  p->rethrow_nested();