std::nested_exception

 

C++

Compiler support

Freestanding and hosted

Language

Standard library

Standard library headers

Named requirements

Feature test macros(C++20)

Language support library

Concepts library(C++20)

Diagnostics library

Memory management library

Metaprogramming library(C++11)

General utilities library

Containers library

Iterators library

Ranges library(C++20)

Algorithms library

Strings library

Text processing library

Numerics library

Date and time library

Input/output library

Filesystem library(C++17)

Concurrency support library(C++11)

Execution control library(C++26)

Technical specifications

Symbols index

External libraries

 

Diagnostics library

Exception handling exception uncaught_exceptionuncaught_exceptions (until C++20*)  (C++17) exception_ptr (C++11) make_exception_ptr (C++11) current_exception (C++11) rethrow_exception (C++11) nested_exception (C++11) throw_with_nested (C++11) rethrow_if_nested (C++11) Exception handling failures terminate terminate_handler get_terminate (C++11) set_terminate bad_exception unexpected (until C++17*) unexpected_handler (until C++17*) get_unexpected (until C++17*) set_unexpected (until C++17*) Error numbers Error codes errno Assertions assert

Exception categories logic_error invalid_argument domain_error length_error out_of_range runtime_error range_error overflow_error underflow_error tx_exception (TM TS) System error error_category (C++11) generic_category (C++11) system_category (C++11) error_condition (C++11) errc (C++11) error_code (C++11) system_error (C++11) Stacktrace stacktrace_entry (C++23) basic_stacktrace (C++23) Debugging support is_debugger_present (C++26) breakpoint_if_debugging (C++26) breakpoint (C++26)

 

Defined in header <exception>
class nested_exception;		(since C++11)

std::nested_exception is a polymorphic mixin class which can capture and store the current exception, making it possible to nest exceptions of arbitrary types within each other.

All member functions of std::nested_exception are constexpr.

(since C++26)

Member functions

(constructor)	constructs a nested_exception (public member function)
(destructor) [virtual]	destructs a nested exception (virtual public member function)
operator=	replaces the contents of a nested_exception (public member function)
rethrow_nested	throws the stored exception (public member function)
nested_ptr	obtains a pointer to the stored exception (public member function)

Non-member functions

throw_with_nested (C++11)	throws its argument with std::nested_exception mixed in (function template)
rethrow_if_nested (C++11)	throws the exception from a std::nested_exception (function template)

Notes

Feature-test macro	Value	Std	Feature
__cpp_lib_constexpr_exceptions	202411L	(C++26)	constexpr for exception types

Example

Demonstrates construction and recursion through a nested exception object.

Run this code

#include <exception>#include <fstream>#include <iostream>#include <stdexcept>#include <string>   // prints the explanatory string of an exception. If the exception is nested,// recurses to print the explanatory string of the exception it holdsvoid print_exception(conststd::exception& e, int level =0){std::cerr<<std::string(level, ' ')<<"exception: "<< e.what()<<'\n';try{std::rethrow_if_nested(e);}catch(conststd::exception& nestedException){ print_exception(nestedException, level +1);}catch(...){}}   // sample function that catches an exception and wraps it in a nested exceptionvoid open_file(conststd::string& s){try{std::ifstream file(s); file.exceptions(std::ios_base::failbit);}catch(...){std::throw_with_nested(std::runtime_error("Couldn't open "+ s));}}   // sample function that catches an exception and wraps it in a nested exceptionvoid run(){try{ open_file("nonexistent.file");}catch(...){std::throw_with_nested(std::runtime_error("run() failed"));}}   // runs the sample function above and prints the caught exceptionint main(){try{ run();}catch(conststd::exception& e){ print_exception(e);}}

Possible output:

exception: run() failed exception: Couldn't open nonexistent.file exception: basic_ios::clear

See also

exception_ptr (C++11)	shared pointer type for handling exception objects (typedef)
throw_with_nested (C++11)	throws its argument with std::nested_exception mixed in (function template)
rethrow_if_nested (C++11)	throws the exception from a std::nested_exception (function template)