Namespaces
Variants
Actions

Source file inclusion

From cppreference.com
 
C++
 
C++ language
General topics
Flow control
Conditional execution statements
if
Iteration statements (loops)
for
range-for (C++11)
Jump statements
Functions
Function declaration
Lambda function expression
inline specifier
Dynamic exception specifications (until C++17*)
noexcept specifier (C++11)
Exceptions
Namespaces
Types
Specifiers
const/volatile
decltype (C++11)
auto (C++11)
constexpr (C++11)
consteval (C++20)
constinit (C++20)
Storage duration specifiers
Initialization
Expressions
Alternative representations
Literals
Boolean - Integer - Floating-point
Character - String - nullptr (C++11)
User-defined (C++11)
Utilities
Attributes (C++11)
Types
typedef declaration
Type alias declaration (C++11)
Casts
Memory allocation
Classes
Class-specific function properties
explicit (C++11)
static

Special member functions
Templates
Miscellaneous
 
Preprocessor
 

Includes other source file into current source file at the line immediately after the directive.

Contents

[edit] Syntax

#include < h-char-sequence > new-line (1)
#include " q-char-sequence " new-line (2)
#include pp-tokens new-line (3)
__has_include ( " q-char-sequence " )
__has_include ( < h-char-sequence > ) 		(4) (since C++17)
__has_include ( string-literal )
__has_include ( < h-pp-tokens > ) 		(5) (since C++17)
1) Searches for a header identified uniquely by h-char-sequence and replaces the directive by the entire contents of the header.
2) Searches for a source file identified by q-char-sequence and replaces the directive by the entire contents of the source file. It may fallback to (1) and treat q-char-sequence as a header identifier.
3) If neither (1) nor (2) is matched, pp-tokens will undergo macro replacement. The directive after replacement will be tried to match with (1) or (2) again.
4) Checks whether a header or source file is available for inclusion.
5) If (4) is not matched, h-pp-tokens will undergo macro replacement. The directive after replacement will be tried to match with (4) again.
new-line - The new-line character
h-char-sequence - A sequence of one or more h-char s, where the appearance of any of the following is conditionally-supported with implementation-defined semantics:
  • the character '
  • the character "
  • the character \
  • the character sequence //
  • the character sequence /*
h-char - Any member of the source character set(until C++23)translation character set(since C++23) except new-line and >
q-char-sequence - A sequence of one or more q-char s, where the appearance of any of the following is conditionally-supported with implementation-defined semantics:
  • the character '
  • the character \
  • the character sequence //
  • the character sequence /*
q-char - Any member of the source character set(until C++23)translation character set(since C++23) except new-line and "
pp-tokens - A sequence of one or more preprocessing tokens
string-literal - A string literal
h-pp-tokens - A sequence of one or more preprocessing tokens except >

[edit] Explanation

1) Searches a sequence of places for a header identified uniquely by h-char-sequence , and causes the replacement of that directive by the entire contents of the header. How the places are specified or the header identified is implementation-defined.
2) Causes the replacement of that directive by the entire contents of the source file identified by q-char-sequence . The named source file is searched for in an implementation-defined manner.
If this search is not supported, or if the search fails, the directive is reprocessed as if it reads syntax (1) with the identical contained sequence (including > characters, if any) from the original directive.
3) The preprocessing tokens after include in the directive are processed just as in normal text (i.e., each identifier currently defined as a macro name is replaced by its replacement list of preprocessing tokens).
If the directive resulting after all replacements does not match one of the two previous forms, the behavior is undefined.
The method by which a sequence of preprocessing tokens between a < and a > preprocessing token pair or a pair of " characters is combined into a single header name preprocessing token is implementation-defined.
4) The header or source file identified by h-char-sequence or q-char-sequence is searched for as if that preprocessing token sequence were the pp-tokens in syntax (3), except that no further macro expansion is performed.
  • If such a directive would not satisfy the syntactic requirements of an #include directive, the program is ill-formed.
  • Otherwise, the __has_include expression evaluates to 1 if the search for the source file succeeds, and to ​0​ if the search fails.
5) This form is considered only if syntax (4) does not match, in which case the preprocessing tokens are processed just as in normal text.

If the header identified by the header-name (i.e., < h-char-sequence > or " q-char-sequence ") denotes an importable header, it is implementation-defined whether the #include preprocessing directive is instead replaced by an import directive of the form

import header-name ; new-line

(since C++20)

__has_include can be expanded in the expression of #if and #elif. It is treated as a defined macro by #ifdef,