Skip to content

feat: migrate cpp/templates and cpp/exceptions from cppref #61

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 4 commits into
base: main
Choose a base branch
from
Open

feat: migrate cpp/templates and cpp/exceptions from cppref #61

Changes from 1 commit
Commits
Show all changes
4 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
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
Next Next commit
update preprocessor documentation
  • Loading branch information
@momo773510
momo773510 committed Dec 3, 2025
commit 95a439b30f9780f0ba9783b2885eadc3201bcd03
74 changes: 74 additions & 0 deletions src/content/docs/cpp/language/preprocessor.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
---
title: preprocessor
cppdoc:
keys: ["cpp.lang.main"]
---

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.

## Directives

The preprocessing directives control the behavior of the preprocessor. Each directive occupies one line and has the following format:

* 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 non-standard 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>

Preprocessing directives must not come from macro expansion.

```cpp
#define EMPTY
EMPTY # include <file.h> // not a preprocessing directive
```

## Capabilities

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>).

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 a *non-standard* extension.
* **<DocLink src="/cpp/preprocessor/line">file name and line information</DocLink>** available to the preprocessor (controlled by directive `#line`).

## Defect reports

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

<DRList>
<DR kind="cwg" id={2001} std="C++98">
<Fragment slot="behavior-published">
the behavior of using non-standard-defined directives was not clear
</Fragment>
<Fragment slot="correct-behavior">
made conditionally-supported
</Fragment>
</DR>
</DRList>

## See also

<DescList>
<Desc>
<DocLink slot="item" src="/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>
</Desc>
<Desc>
<DocLink slot="item" src="/c/preprocessor">C documentation</DocLink> for <span>preprocessor</span>
</Desc>
</DescList>