Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
2 changes: 1 addition & 1 deletion migrate/PROMPT.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ You are a professional C++ documentation writer. You are now migrating cpprefere
3. For links, take the URL part, remove `/w/` and the latter part `.html`, and then wrap it with `DocLink`. For example:
If the current path is: `/w/cpp/language/basics.html`
Link: `<a href="declarations.html" title="cpp/language/declarations">declarations</a>`
You should, based on the current link, change it to: `<DocLink src="/cpp/language/declarations">declarations</DocLink>`
You should, based on the current link, change it to: `<DocLink dest="/cpp/language/declarations">declarations</DocLink>`
4. Currently available components:
```mdx
{{LLM_DOCS}}
Expand Down
24 changes: 12 additions & 12 deletions src/content/docs/cpp/language/exceptions.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -13,20 +13,20 @@ import { FeatureTestMacro, FeatureTestMacroValue } from "@components/feature-tes

Exception handling provides a way of transferring control and information from some point in the execution of a program to a handler associated with a point previously passed by the execution (in other words, exception handling transfers control up the call stack).

Evaluating a <DocLink src="cpp/language/throw.html#throw_expressions">`throw` expression</DocLink> will throw an exception. Exceptions can also be thrown in <DocLink src="cpp/language/throw.html#throw_expressions">other contexts</DocLink>.
Evaluating a <DocLink dest="cpp/language/throw.html#throw_expressions">`throw` expression</DocLink> will throw an exception. Exceptions can also be thrown in <DocLink dest="cpp/language/throw.html#throw_expressions">other contexts</DocLink>.

In order for an exception to be caught, the `throw` expression has to be inside a <DocLink src="cpp/language/try">`try` block</DocLink>, and the `try` block has to contain a <DocLink src="cpp/language/catch">handler</DocLink> that matches the type of the exception object.
In order for an exception to be caught, the `throw` expression has to be inside a <DocLink dest="cpp/language/try">`try` block</DocLink>, and the `try` block has to contain a <DocLink dest="cpp/language/catch">handler</DocLink> that matches the type of the exception object.

When declaring a function, the following specification(s) may be provided to limit the types of the exceptions a function may throw:

- <Revision since="C++17"><DocLink src="cpp/language/cpp/language/except_spec">dynamic exception specifications</DocLink></Revision>
- <Revision since="C++11"><DocLink src="cpp/language/cpp/language/noexcept_spec">noexcept specifications</DocLink></Revision>
- <Revision since="C++17"><DocLink dest="cpp/language/cpp/language/except_spec">dynamic exception specifications</DocLink></Revision>
- <Revision since="C++11"><DocLink dest="cpp/language/cpp/language/noexcept_spec">noexcept specifications</DocLink></Revision>

Errors that arise during exception handling are handled by <DocLink src="cpp/error/terminate">`std::terminate`</DocLink> and <Revision since="C++17"><DocLink src="cpp/error/unexpected">`std::unexpected`</DocLink></Revision>.
Errors that arise during exception handling are handled by <DocLink dest="cpp/error/terminate">`std::terminate`</DocLink> and <Revision since="C++17"><DocLink dest="cpp/error/unexpected">`std::unexpected`</DocLink></Revision>.

## Usage

While `throw` expression can be used to transfer control to an arbitrary block of code up the execution stack, for arbitrary reasons (similar to <DocLink src="cpp/utility/program/longjmp">`std::longjmp`</DocLink>), its intended usage is error handling.
While `throw` expression can be used to transfer control to an arbitrary block of code up the execution stack, for arbitrary reasons (similar to <DocLink dest="cpp/utility/program/longjmp">`std::longjmp`</DocLink>), its intended usage is error handling.

### Error handling

Expand All @@ -36,24 +36,24 @@ Throwing an exception is used to signal errors from functions, where "errors" ar
2. Failures to meet the preconditions of another function that must be called.
3. (for non-private member functions) Failures to (re)establish a class invariant.

In particular, this implies that the failures of constructors (see also <DocLink src="cpp/language/raii">RAII</DocLink>) and most operators should be reported by throwing exceptions.
In particular, this implies that the failures of constructors (see also <DocLink dest="cpp/language/raii">RAII</DocLink>) and most operators should be reported by throwing exceptions.

In addition, so-called *wide contract* functions use exceptions to indicate unacceptable inputs, for example, <DocLink src="cpp/string/basic_string/at">`std::basic_string::at`</DocLink> has no preconditions, but throws an exception to indicate index out of range.
In addition, so-called *wide contract* functions use exceptions to indicate unacceptable inputs, for example, <DocLink dest="cpp/string/basic_string/at">`std::basic_string::at`</DocLink> has no preconditions, but throws an exception to indicate index out of range.

### Exception safety

After the error condition is reported by a function, additional guarantees may be provided with regards to the state of the program. The following four levels of exception guarantee are generally recognized[^4] [^5] [^6], which are strict supersets of each other:

1. *Nothrow (or nofail) exception guarantee* — the function never throws exceptions. Nothrow (errors are reported by other means or concealed) is expected of <DocLink src="cpp/language/destructor">destructors</DocLink> and other functions that may be called during stack unwinding. <Revision since="C++11">The <DocLink src="cpp/language/destructor">destructors</DocLink> are <DocLink src="cpp/language/noexcept">`noexcept`</DocLink> by default.</Revision> Nofail (the function always succeeds) is expected of swaps, <DocLink src="cpp/language/move_constructor">move constructors</DocLink>, and other functions used by those that provide strong exception guarantee.
2. *Strong exception guarantee* — If the function throws an exception, the state of the program is rolled back to the state just before the function call (for example, <DocLink src="cpp/container/vector/push_back">`std::vector::push_back`</DocLink>).
1. *Nothrow (or nofail) exception guarantee* — the function never throws exceptions. Nothrow (errors are reported by other means or concealed) is expected of <DocLink dest="cpp/language/destructor">destructors</DocLink> and other functions that may be called during stack unwinding. <Revision since="C++11">The <DocLink dest="cpp/language/destructor">destructors</DocLink> are <DocLink dest="cpp/language/noexcept">`noexcept`</DocLink> by default.</Revision> Nofail (the function always succeeds) is expected of swaps, <DocLink dest="cpp/language/move_constructor">move constructors</DocLink>, and other functions used by those that provide strong exception guarantee.
2. *Strong exception guarantee* — If the function throws an exception, the state of the program is rolled back to the state just before the function call (for example, <DocLink dest="cpp/container/vector/push_back">`std::vector::push_back`</DocLink>).
3. *Basic exception guarantee* — If the function throws an exception, the program is in a valid state. No resources are leaked, and all objects' invariants are intact.
4. *No exception guarantee* — If the function throws an exception, the program may not be in a valid state: resource leaks, memory corruption, or other invariant-destroying errors may have occurred.

Generic components may, in addition, offer *exception-neutral guarantee*: if an exception is thrown from a template parameter (e.g. from the `Compare` function object of <DocLink src="cpp/algorithm/sort">`std::sort`</DocLink> or from the constructor of `T` in <DocLink src="cpp/memory/shared_ptr/make_shared">`std::make_shared`</DocLink>), it is propagated, unchanged, to the caller.
Generic components may, in addition, offer *exception-neutral guarantee*: if an exception is thrown from a template parameter (e.g. from the `Compare` function object of <DocLink dest="cpp/algorithm/sort">`std::sort`</DocLink> or from the constructor of `T` in <DocLink dest="cpp/memory/shared_ptr/make_shared">`std::make_shared`</DocLink>), it is propagated, unchanged, to the caller.

## Exception objects

While objects of any complete type and cv pointers to `void` may be thrown as exception objects, all standard library functions throw unnamed objects by value, and the types of those objects are derived (directly or indirectly) from <DocLink src="cpp/error/exception">`std::exception`</DocLink>. User-defined exceptions usually follow this pattern.[^7] [^8] [^9]
While objects of any complete type and cv pointers to `void` may be thrown as exception objects, all standard library functions throw unnamed objects by value, and the types of those objects are derived (directly or indirectly) from <DocLink dest="cpp/error/exception">`std::exception`</DocLink>. User-defined exceptions usually follow this pattern.[^7] [^8] [^9]

To avoid unnecessary copying of the exception object and object slicing, the best practice for handlers is to catch by reference.[^10] [^11] [^12] [^13]

Expand Down
24 changes: 12 additions & 12 deletions src/content/docs/cpp/language/preprocessor.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ import { Desc, DescList, DocLink } from '@components/index';
import { Revision, RevisionBlock } from "@components/revision";
import { DR, DRList } from "@components/defect-report";

The preprocessor is executed at <DocLink src="/cpp/language/translation_phases" anchor="Phase_4">translation phase 4</DocLink>, before the compilation. The result of preprocessing is a single file which is then passed to the actual compiler.
The preprocessor is executed at <DocLink dest="/cpp/language/translation_phases" anchor="Phase_4">translation phase 4</DocLink>, before the compilation. The result of preprocessing is a single file which is then passed to the actual compiler.

## Directives

Expand All @@ -17,11 +17,11 @@ The preprocessing directives control the behavior of the preprocessor. Each dire
* the `#` character.
* a sequence of:
* a standard-defined directive name (listed [below](#Capabilities)) followed by the corresponding arguments, or
* one or more <DocLink src="/cpp/language/translation_phases" anchor="Phase_3">preprocessing tokens</DocLink> where the beginning token is not a standard-defined directive name, in this case the directive is conditionally-supported with implementation-defined semantics <Revision until="C++23">(e.g. a common extension is the directive `#warning` which emits a user-defined message during compilation)</Revision>, or
* one or more <DocLink dest="/cpp/language/translation_phases" anchor="Phase_3">preprocessing tokens</DocLink> where the beginning token is not a standard-defined directive name, in this case the directive is conditionally-supported with implementation-defined semantics <Revision until="C++23">(e.g. a common extension is the directive `#warning` which emits a user-defined message during compilation)</Revision>, or
* nothing, in this case the directive has no effect.
* a line break.

<Revision since="C++20">The <DocLink src="/cpp/language/modules">module and import directives</DocLink> are also preprocessing directives.</Revision>
<Revision since="C++20">The <DocLink dest="/cpp/language/modules">module and import directives</DocLink> are also preprocessing directives.</Revision>

Preprocessing directives must not come from macro expansion.

Expand All @@ -34,15 +34,15 @@ EMPTY # include <file.h> // not a preprocessing directive

The preprocessor has the source file translation capabilities:

* **<DocLink src="/cpp/preprocessor/conditional">conditionally</DocLink>** compile parts of source file (controlled by directive `#if`, `#ifdef`, `#ifndef`, `#else`, <Revision since="C++23">`#elif`, `#elifdef`, `#elifndef`</Revision>, and `#endif`).
* **<DocLink src="/cpp/preprocessor/replace">replace</DocLink>** text macros while possibly concatenating or quoting identifiers (controlled by directives `#define` and `#undef`, and operators `#` and `##`).
* **<DocLink src="/cpp/preprocessor/include">include</DocLink>** other files (controlled by directive `#include` <Revision since="C++23">and checked with `__has_include` </Revision>).
* cause an **<DocLink src="/cpp/preprocessor/error">error</DocLink>** <Revision since="C++17">or **<DocLink src="/cpp/preprocessor/error">warning</DocLink>** </Revision> (controlled by directive `#error` <Revision since="C++23">or `#warning` respectively</Revision>).
* **<DocLink dest="/cpp/preprocessor/conditional">conditionally</DocLink>** compile parts of source file (controlled by directive `#if`, `#ifdef`, `#ifndef`, `#else`, <Revision since="C++23">`#elif`, `#elifdef`, `#elifndef`</Revision>, and `#endif`).
* **<DocLink dest="/cpp/preprocessor/replace">replace</DocLink>** text macros while possibly concatenating or quoting identifiers (controlled by directives `#define` and `#undef`, and operators `#` and `##`).
* **<DocLink dest="/cpp/preprocessor/include">include</DocLink>** other files (controlled by directive `#include` <Revision since="C++23">and checked with `__has_include` </Revision>).
* cause an **<DocLink dest="/cpp/preprocessor/error">error</DocLink>** <Revision since="C++17">or **<DocLink dest="/cpp/preprocessor/error">warning</DocLink>** </Revision> (controlled by directive `#error` <Revision since="C++23">or `#warning` respectively</Revision>).

The following aspects of the preprocessor can be controlled:

* **<DocLink src="/cpp/preprocessor/impl">implementation-defined</DocLink>** behavior (controlled by directive `#pragma` <Revision since="C++11">and operator `_Pragma` </Revision>). In addition, some compilers support (to varying degrees) the operator `__pragma` as an extension.
* **<DocLink src="/cpp/preprocessor/line">file name and line information</DocLink>** available to the preprocessor (controlled by directive `#line`).
* **<DocLink dest="/cpp/preprocessor/impl">implementation-defined</DocLink>** behavior (controlled by directive `#pragma` <Revision since="C++11">and operator `_Pragma` </Revision>). In addition, some compilers support (to varying degrees) the operator `__pragma` as an extension.
* **<DocLink dest="/cpp/preprocessor/line">file name and line information</DocLink>** available to the preprocessor (controlled by directive `#line`).

## Defect reports

Expand All @@ -63,12 +63,12 @@ The following behavior-changing defect reports were applied retroactively to pre

<DescList>
<Desc>
<DocLink slot="item" src="/cpp/preprocessor/replace" anchor="Predefined_macros">C++ documentation</DocLink> for <span>Predefined Macro Symbols</span>
<DocLink slot="item" dest="/cpp/preprocessor/replace" anchor="Predefined_macros">C++ documentation</DocLink> for <span>Predefined Macro Symbols</span>
</Desc>
<Desc>
<DocLink slot="item" src="/cpp/symbol_index/macro">C++ documentation</DocLink> for <span>Macro Symbol Index</span>
<DocLink slot="item" dest="/cpp/symbol_index/macro">C++ documentation</DocLink> for <span>Macro Symbol Index</span>
</Desc>
<Desc>
<DocLink slot="item" src="/c/preprocessor">C documentation</DocLink> for <span>preprocessor</span>
<DocLink slot="item" dest="/c/preprocessor">C documentation</DocLink> for <span>preprocessor</span>
</Desc>
</DescList>
Loading