Skip to content

feat: migrate cpp/language/exceptions #90

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
momo773510 wants to merge 9 commits into
base: main
Choose a base branch
from
Open

feat: migrate cpp/language/exceptions #90

Show file tree
Hide file tree
Changes from 7 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
95a439b
update preprocessor documentation
momo773510 Dec 3, 2025
a69c304
feat: migrate cpp/templates cpp/exceptions from cppref
momo773510 Dec 5, 2025
db6d7de
Merge branch 'main' of https://github.com/momo773510/cppdoc into add_doc
momo773510 Dec 5, 2025
b16f791
fix preprocessor doc
momo773510 Dec 5, 2025
7ae7a98
Merge remote-tracking branch 'upstream/main'
momo773510 Dec 22, 2025
c240cb3
Merge remote-tracking branch 'upstream/main'
momo773510 Dec 23, 2025
1ff7121
feat: migrate cpp/language/exceptions
momo773510 Dec 25, 2025
a2fd034
fixed broken indentation
momo773510 Dec 30, 2025
65d656b
Fix formatting of exception handling details
momo773510 Jan 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion src/content/docs/cpp/language/exceptions.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
---
title: Exceptions
title: Overview
sidebar:
order: 1
---

import { Decl, DeclDoc } from "@components/decl-doc";
Expand Down
328 changes: 328 additions & 0 deletions src/content/docs/cpp/language/exceptions/catch.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,328 @@
---
title: Handling exceptions
sidebar:
order: 4
---

import { Decl, DeclDoc } from "@components/decl-doc";
import { Desc, DescList, DocLink } from '@components/index';
import { Revision, RevisionBlock } from "@components/revision";
import { DR, DRList } from "@components/defect-report";
import { ParamDoc, ParamDocList } from "@components/param-doc";

An <DocLink dest="/cpp/language/exceptions">exception</DocLink> can be handled by a handler.

### Handler

<DeclDoc id={1}>
<Decl slot="decl">
```cpp cxx-mark
catch ( /*$s:attr*//*$opt*/ /*$s:type-specifier-seq*/ /*$s:declarator*/ ) /*$s:compound-statement*/
```
</Decl>
A handler with a named parameter.
</DeclDoc>
<DeclDoc id={2}>
<Decl slot="decl">
```cpp cxx-mark
catch ( /*$s:attr*//*$opt*/ /*$s:type-specifier-seq*/ /*$s:abstract-declarator*//*$opt*/ ) /*$s:compound-statement*/
```
</Decl>
A handler with an unnamed parameter.
</DeclDoc>
<DeclDoc id={3}>
<Decl slot="decl">
```cpp cxx-mark
catch ( ... ) /*$s:compound-statement*/
```
</Decl>
A handler matching all kinds of exceptions.
</DeclDoc>

<ParamDocList>
<ParamDoc name="attr">
<Revision since="C++11"></Revision> any number of <DocLink dest="/cpp/language/attributes">attributes</DocLink>, applies to the parameter
</ParamDoc>
<ParamDoc name="type-specifier-seq">
part of a formal parameter declaration, same as in a function <DocLink dest="/cpp/language/functions/function#Parameter_list">parameter list</DocLink>
</ParamDoc>
<ParamDoc name="declarator">
part of a parameter declaration, same as in a function <DocLink dest="/cpp/language/functions/function#Parameter_list">parameter list</DocLink>
</ParamDoc>
<ParamDoc name="abstract-declarator">
part of an unnamed parameter declaration, same as in function <DocLink dest="/cpp/language/functions/function#Parameter_list">parameter list</DocLink>
</ParamDoc>
<ParamDoc name="compound-statement">
a <DocLink dest="/cpp/language/statements#Compound_statements">compound statement</DocLink>
</ParamDoc>
</ParamDocList>

The parameter declaration in a handler describes the type(s) of exceptions that can cause that handler to be entered.

If the parameter is declared to have one of the following types, the program is ill-formed:

- an <DocLink dest="/cpp/language/basic_concepts/definition#Incomplete_type">incomplete type</DocLink>
- an <DocLink dest="/cpp/language/classes#Abstract_classes">abstract class type</DocLink>
- an <DocLink dest="/cpp/language/reference#Rvalue_reference"><Revision since="C++11">rvalue reference type</Revision></DocLink>
- a pointer to an incomplete type other than (possibly cv-qualified) `void`
- an lvalue reference to an incomplete type

If the parameter is declared to have type “array of `T`” or function type `T`, the type is adjusted to “pointer to `T`”.

A handler with parameter type `T` can be abbreviated as “a handler of type `T`”.

### Matching exceptions

Each `try` block associates with a number of handlers, these handlers form a handler sequence. When an exception is thrown from a `try` block, the handlers in the sequence are tried in order of appearance to match the exception.

A handler is a match for an <DocLink dest="/cpp/language/exceptions/throwing_exceptions#Exception_object">exception object</DocLink> of type `E` if any of the following conditions is satisfied:

- The handler is of type “possibly cv-qualified `T`” or “lvalue reference to possibly cv-qualified `T`”, and any of the following conditions is satisfied:
- `E` and `T` are the same type (ignoring the top-level cv-qualifiers).
- `T` is an unambiguous public base class of `E`.
- The handler is of type “possibly cv-qualified `T`” or `const T&` where `T` is a pointer or pointer-to-member type, and any of the following conditions is satisfied:
- `E` is a pointer or pointer-to-member type that can be converted to `T` by at least one of the following conversions:
- A <DocLink dest="/cpp/language/implicit_cast#Pointer_conversions">standard pointer conversion</DocLink> not involving conversions to pointers to private or protected or ambiguous classes.
- <Revision since="C++17">A <DocLink dest="/cpp/language/implicit_cast#Function_pointer_conversions">function pointer conversion.</DocLink></Revision>
- A <DocLink dest="/cpp/language/implicit_cast#Qualification_conversions">qualification conversion</DocLink>.
- <Revision since="C++11">`E` is <DocLink dest="/cpp/types/nullptr_t">std::nullptr_t</DocLink>.</Revision>

The `catch (...)` handler matches exceptions of any type. If present, it can only be the last handler in a handler sequence. This handler may be used to ensure that no uncaught exceptions can possibly escape from a function that offers <DocLink dest="/cpp/language/exceptions">nothrow exception guarantee</DocLink>.

```cpp
try
{
f();
}
catch (const std::overflow_error& e)
{} // this executes if f() throws std::overflow_error (same type rule)
catch (const std::runtime_error& e)
{} // this executes if f() throws std::underflow_error (base class rule)
catch (const std::exception& e)
{} // this executes if f() throws std::logic_error (base class rule)
catch (...)
{} // this executes if f() throws std::string or int or any other unrelated type
```

If no match is found among the handlers for a `try` block, the search for a matching handler continues in a dynamically surrounding `try` block<Revision since="C++11"> of the same thread</Revision>.

If no matching handler is found, <DocLink dest="/cpp/error/terminate">std::terminate</DocLink> is invoked; whether or not the stack is <DocLink dest="/cpp/language/exceptions/throwing_exceptions#Stack_unwinding">unwound</DocLink> before this invocation of <DocLink dest="/cpp/error/terminate">std::terminate</DocLink> is implementation-defined.

### Handling exceptions

When an exception is thrown, control is transferred to the nearest handler with a matching type; “nearest” means the handler for which the compound statement or the member initializer list (if present) following the `try` keyword was most recently entered by the thread of control and not yet exited.

#### Initializing the handler parameter

The parameter declared in the parameter list (if any), of type “possibly cv-qualified `T`” or “lvalue reference to possibly cv-qualified `T`”, is initialized from the <DocLink dest="/cpp/language/exceptions/throwing_exceptions#Exception_object">exception object</DocLink>, of type `E`, as follows:

- If `T` is a base class of `E`, the parameter is <DocLink dest="/cpp/language/copy_initialization">copy-initialized</DocLink> from an lvalue of type `T` designating the corresponding base class subobject of the exception object.
- Otherwise, the parameter is copy-initialized from an lvalue of type `E` designating the exception object.

The lifetime of the parameter ends when the handler exits, after the destruction of any objects with automatic <DocLink dest="/cpp/language/storage_duration">storage duration</DocLink> initialized within the handler.

When the parameter is declared as an object, any changes to that object will not affect the exception object.

When the parameter is declared as a reference to an object, any changes to the referenced object are changes to the exception object and will have effect should that object be rethrown.

#### Activating the handler

A handler is considered _active_ when initialization is complete for the parameter (if any) of the handler.

Also, an implicit handler is considered active when <DocLink dest="/cpp/error/terminate">std::terminate</DocLink> is entered due to a throw.

A handler is no longer considered active when the handler exits.

The exception with the most recently activated handler that is still active is called the _currently handled exception_. Such an exception can be <DocLink dest="/cpp/language/exceptions/throwing_exceptions#throw_expressions">rethrown</DocLink>.

### Control flow

The `compound-statement` of a handler is a <DocLink dest="/cpp/language/statements#Control-flow-limited_statements">control-flow-limited statement</DocLink>:

```cpp
void f()
{
goto label; // error
try
{
goto label; // error
}
catch (...)
{
goto label: // OK
label: ;
}
}
```

### Notes

<DocLink dest="/cpp/language/exceptions/throwing_exceptions#Stack_unwinding">Stack unwinding</DocLink> occurs while control is transferring to a handler. When a handler becomes active, stack unwinding is already completed.

The exception thrown by the `throw` expression `throw 0` does not match a handler of pointer or pointer-to-member type.

- <Revision since="C++11">`throw nullptr` can be used instead to throw a null pointer that matches such handlers.</Revision>

<DocLink dest="/cpp/language/exceptions/throwing_exceptions#Exception_object">Exception objects</DocLink> can never have array or function types, therefore a handler of reference to array or function type is never a match for any exception object.

It is possible to write handlers that can never be executed, for example by placing a handler for a final derived class after a handler for a corresponding unambiguous public base class:

```cpp
try
{
f();
}
catch (const std::exception& e)
{} // will be executed if f() throws std::runtime_error
catch (const std::runtime_error& e)
{} // dead code!
```

Many implementations overly extend the resolution of <DocLink dest="https://cplusplus.github.io/CWG/issues/388.html">CWG issue 388</DocLink> to handlers of reference to non-const pointer types:

```cpp
int i;
try
{
try
{
throw static_cast<float*>(nullptr);
}
catch (void*& pv)
{
pv = &i;
throw;
}
}
catch (const float* pf)
{
assert(pf == nullptr); // should pass, but fails on MSVC and Clang
}
```

### Keywords

- <DocLink dest="/cpp/keyword/catch">`catch`</DocLink>

### Example

The following example demonstrates several usage cases of the handlers:

```cpp
#include <iostream>
#include <vector>

int main()
{
try
{
std::cout << "Throwing an integer exception...\n";
throw 42;
}
catch (int i)
{
std::cout << " the integer exception was caught, with value: " << i << '\n';
}

try
{
std::cout << "Creating a vector of size 5... \n";
std::vector<int> v(5);
std::cout << "Accessing the 11th element of the vector...\n";
std::cout << v.at(10); // vector::at() throws std::out_of_range
}
catch (const std::exception& e) // caught by reference to base
{
std::cout << " a standard exception was caught, with message: '"
<< e.what() << "'\n";
}
}
```

Possible output:

```text
Throwing an integer exception...
the integer exception was caught, with value: 42
Creating a vector of size 5...
Accessing the 11th element of the vector...
a standard exception was caught, with message: 'out_of_range'
```

### Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

<DRList>
<DR kind="cwg" id={98} std="C++98">
<Fragment slot="behavior-published">
a `switch` statement can transfer control into a handler
</Fragment>
<Fragment slot="correct-behavior">
prohibited
</Fragment>
</DR>
<DR kind="cwg" id={210} std="C++98">
<Fragment slot="behavior-published">
`throw` expressions were matched against the handlers
</Fragment>
<Fragment slot="correct-behavior">
exception objects are matched against the handlers
</Fragment>
</DR>
<DR kind="cwg" id={388} std="C++98">
<Fragment slot="behavior-published">
an exception of pointer or pointer to member type could not be matched by a const reference to a different type
</Fragment>
<Fragment slot="correct-behavior">
made matchable when convertible
</Fragment>
</DR>
<DR kind="cwg" id={1166} std="C++98">
<Fragment slot="behavior-published">
the behavior was unspecified when a handler whose type is a reference to an abstract class type is matched
</Fragment>
<Fragment slot="correct-behavior">
abstract class types are not allowed for handlers
</Fragment>
</DR>
<DR kind="cwg" id={1769} std="C++98">
<Fragment slot="behavior-published">
when the type of the handler is a base of the type of the exception object, a converting constructor might be used for the initialization of the handler parameter
</Fragment>
<Fragment slot="correct-behavior">
the parameter is copy-initialized from the corresponding base class subobject of the exception object
</Fragment>
</DR>
<DR kind="cwg" id={2093} std="C++98">
<Fragment slot="behavior-published">
an exception object of pointer to object type could not match a handler of pointer to object type through qualification conversion
</Fragment>
<Fragment slot="correct-behavior">
allowed
</Fragment>
</DR>
</DRList>

### References

- C++23 standard (ISO/IEC 14882:2024):
- 14.4 Handling an exception [except.handle]
- C++20 standard (ISO/IEC 14882:2020):
- 14.4 Handling an exception [except.handle]
- C++17 standard (ISO/IEC 14882:2017):
- 18.3 Handling an exception [except.handle]
- C++14 standard (ISO/IEC 14882:2014):
- 15.3 Handling an exception [except.handle]
- C++11 standard (ISO/IEC 14882:2011):
- 15.3 Handling an exception [except.handle]
- C++03 standard (ISO/IEC 14882:2003):
- 15.3 Handling an exception [except.handle]
- C++98 standard (ISO/IEC 14882:1998):
- 15.3 Handling an exception [except.handle]

### See also

- <DocLink dest="/cpp/language/exceptions/try">`try` block</DocLink>
- <DocLink dest="/cpp/language/exceptions/throw">Throwing exceptions</DocLink>
- <DocLink dest="/cpp/error">Exception handling</DocLink>
Loading