General topics | ||||||||||||||||
Flow control | ||||||||||||||||
Conditional execution statements | ||||||||||||||||
Iteration statements (loops) | ||||||||||||||||
Jump statements | ||||||||||||||||
Functions | ||||||||||||||||
Function declaration | ||||||||||||||||
Lambda function expression | ||||||||||||||||
inline specifier | ||||||||||||||||
Dynamic exception specifications(until C++17*) | ||||||||||||||||
noexcept specifier(C++11) | ||||||||||||||||
Exceptions | ||||||||||||||||
Namespaces | ||||||||||||||||
Types | ||||||||||||||||
Specifiers | ||||||||||||||||
| ||||||||||||||||
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 | ||||||||||||||||
| ||||||||||||||||
Special member functions | ||||||||||||||||
Templates | ||||||||||||||||
Miscellaneous | ||||||||||||||||
(C++23)(C++23) | ||||
(C++17) | ||||
(C++23) | ||||
(C++11) | ||||
#embed (C++26) |
#embed is a preprocessor directive to includeresources.
Contents |
#embed < h-char-sequence> pp-tokensnew-line | (1) | ||||||||
#embed " q-char-sequence" pp-tokensnew-line | (2) | ||||||||
#embed pp-tokensnew-line | (3) | ||||||||
__has_embed ( balanced-pp-tokens) | (4) | ||||||||
new-line | - | The new-line character |
h-char-sequence | - | A sequence of one or moreh-char s (see#include ) |
q-char-sequence | - | A sequence of one or moreq-char s (see#include ) |
pp-tokens | - | A sequence of one or morepreprocessing tokens |
balanced-pp-tokens | - | A sequence of one or more preprocessing tokens, where all(,[ and{ are properly closed |
embed
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).__has_embed
expression evaluates to__STDC_EMBED_FOUND__ if the resource is not empty, and to__STDC_EMBED_EMPTY__ if the resource is empty.__has_embed
expression evaluates to__STDC_EMBED_NOT_FOUND__.Aresource is a source of data accessible from the translation environment. A resource has animplementation-resource-width , which is the implementation-defined size in bits of the resource. If the implementation-resource-width is not an integral multiple ofCHAR_BIT, the program is ill-formed.
Letimplementation-resource-count be implementation-resource-width divided byCHAR_BIT. Every resource also has aresource-count , which is the implementation-resource-count, unless thelimit
embed parameter is provided.
A resource isempty if the resource-count is zero.
// ill-formed if the implementation-resource-width is 6 bits#embed "6_bits.bin"
Unless otherwise modified, the#embed directive is replaced by a comma-delimited list ofinteger literals of typeint.
The integer literals in the comma-delimited list correspond to resource-count consecutive calls tostd::fgetc from the resource, as a binary file. If any call tostd::fgetc returnsEOF, the program is ill-formed.
int i={#embed "i.dat"};// well-formed if i.dat produces a single value int i2=#embed "i.dat";// also well-formed if i.dat produces a single value struct T{double a, b, c;struct{double e, f, g;} x;double h, i, j;};T x={// well-formed if the directive produces nine or fewer values#embed "s.dat"};
Ifpp-tokens is present in syntax(1) or syntax(2), it is processed just as in normal text. The processedpp-tokens should form a sequence ofembed parameters , otherwise the program is ill-formed. Embed parameters have the following syntax:
limit ( balanced-pp-tokens) | (1) | ||||||||
prefix ( balanced-pp-tokens (optional)) | (2) | ||||||||
suffix ( balanced-pp-tokens (optional)) | (3) | ||||||||
if_empty ( balanced-pp-tokens (optional)) | (4) | ||||||||
identifier:: identifier | (5) | ||||||||
identifier:: identifier( balanced-pp-tokens (optional)) | (6) | ||||||||
limit
parameterAn embed parameter of the formlimit
(
balanced-pp-tokens)
can only appear at most once in each#embed directive.
balanced-pp-tokens are processed just as in normal text to form aconstant expression, butdefined
,__has_include
,__has_cpp_attribute
and__has_embed
expressions are not evaluated.
The constant expression must be anintegral constant expression whose value is greater than or equal to zero:
constexprunsignedchar sound_signature[]={// a hypothetical resource capable of expanding to four or more elements#embed <sdk/jump.wav> limit(2 + 2)}; static_assert(sizeof(sound_signature)==4); // equivalent to #embed <data.dat> limit(10)#define DATA_LIMIT 10#embed <data.dat> limit(DATA_LIMIT) // ill-formed#embed <data.dat> limit(__has_include("a.h"))
prefix
parameterAn embed parameter of the formprefix
(
balanced-pp-tokens (optional))
can only appear at most once in each#embed directive.
If the resource is empty, this embed parameter is ignored. Otherwise,balanced-pp-tokens is placed immediately before the comma-delimited list of integral literals.
suffix
parameterAn embed parameter of the formsuffix
(
balanced-pp-tokens (optional))
can only appear at most once in each#embed directive.
If the resource is empty, this embed parameter is ignored. Otherwise,balanced-pp-tokens is placed immediately after the comma-delimited list of integral literals.
constexprunsignedchar whl[]={#embed "chess.glsl" \ prefix(0xEF, 0xBB, 0xBF, ) /∗ a sequence of bytes ∗/ \ suffix(,)0}; // always null-terminated, contains the sequence if not empty constexprbool is_empty= sizeof(whl)==1&& whl[0]=='\0'; constexprbool is_not_empty= sizeof(whl)>=4&& whl[sizeof(whl)-1]=='\0'&& whl[0]=='\xEF'&& whl[1]=='\xBB'&& whl[2]=='\xBF'; static_assert(is_empty|| is_not_empty);
if_empty
parameterAn embed parameter of the formif_empty
(
balanced-pp-tokens (optional))
can only appear at most once in each#embed directive.
If the resource isnot empty, this embed parameter is ignored. Otherwise, the#embed directive is replaced bybalanced-pp-tokens.
// always expands to 42203 regardless of the content of /owo/uwurandom#embed </owo/uwurandom> if_empty(42203) limit(0)
Feature-test macro | Value | Std | Feature |
---|---|---|---|
__cpp_pp_embed | 202502L | (C++26) | The#embed directive |
Demonstrate the effect of#embed. Ifdata.dat
can be embedded as a resource in the translation environment, no assert in this program should fail.
#include <cassert>#include <cstddef>#include <cstring>#include <fstream>#include <vector> int main(){constexprunsignedchar d[]{#embed <data.dat>}; conststd::vector<unsignedchar> vec_d{#embed <data.dat>}; constexprstd::size_t expected_size= sizeof(d);// same file in execution environment as was embeddedstd::ifstream f_source("data.dat",std::ios_base::binary|std::ios_base::in);unsignedchar runtime_d[expected_size]; char* ifstream_ptr=reinterpret_cast<char*>(runtime_d);assert(!f_source.read(ifstream_ptr, expected_size)); std::size_t ifstream_size= f_source.gcount();assert(ifstream_size== expected_size); int is_same=std::memcmp(&d[0], ifstream_ptr, ifstream_size);assert(is_same==0); int is_same_vec=std::memcmp(vec_d.data(), ifstream_ptr, ifstream_size);assert(is_same_vec==0);}
C documentation forBinary resource inclusion(since C23) |