#embed is a preprocessor directive to includeresources.

[edit]Syntax

[edit]Explanation

[edit]Resources

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"

[edit]Embedding resources

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"};

[edit]Embed parameters

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:

[edit]limit parameter

An 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:

• If the value of the constant expression is greater than implementation-resource-count, the resource-count is still the implementation-resource-count.
• Otherwise, the resource-count becomes the value of the constant expression.

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

[edit]prefix parameter

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

[edit]suffix parameter

An 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);

[edit]if_empty parameter

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

[edit]Notes

[edit]Example

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);}

[edit]References

[edit]See also

• Source file inclusion

• In other languages

• العربية
• Deutsch
• Español
• Français
• Italiano
• 日本語
• Polski
• Português
• Русский
• 中文