15 Preprocessing directives [cpp]

15.4 Resource inclusion [cpp.embed]

15.4.1 General [cpp.embed.gen]

1
#
A preprocessing directive of the form
# embed < h-char-sequence > pp-tokens new-line
searches a sequence of implementation-defined places for a resource identified uniquely by the specified sequence between the < and > delimiters.
How the places are specified or the resource identified is implementation-defined.
2
#
A preprocessing directive of the form
# embed " q-char-sequence " pp-tokens new-line
searches for a resource identified by the specified sequence between the " delimiters.
The named resource 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 read
# embed < h-char-sequence > pp-tokens new-line
with the identical contained sequence (including > characters, if any) from the original directive.
3
#
Recommended practice: A mechanism similar to, but distinct from, the implementation-defined search paths used for #include ([cpp.include]) is encouraged.
4
#
Either form of the #embed directive processes the pp-tokens, if present, just as in normal text.
The pp-tokens shall then have the form embed-parameter-seq.
5
#
A resource is a source of data accessible from the translation environment.
A resource has an implementation-resource-width, which is the implementation-defined size in bits of the resource.
If the implementation-resource-width is not an integral multiple of CHAR_BIT, the program is ill-formed.
Let implementation-resource-count be implementation-resource-width divided by CHAR_BIT.
Every resource also has a resource-count, which is
A resource is empty if the resource-count is zero.
6
#
[Example 1: // ill-formed if the implementation-resource-width is 6 bits #embed "6_bits.bin" — end example]
7
#
The #embed directive is replaced by a comma-delimited list of integer literals of type int, unless otherwise modified by embed parameters ([cpp.embed.param]).
8
#
The integer literals in the comma-delimited list correspond to resource-count consecutive calls to std​::​fgetc ([cstdio.syn]) from the resource, as a binary file.
If any call to std​::​fgetc returns EOF, the program is ill-formed.
9
#
Recommended practice: The value of each integer literal should closely represent the bit stream of the resource unmodified.
This can require an implementation to consider potential differences between translation and execution environments, as well as any other applicable sources of mismatch.
[Example 2: #include <cstring> #include <cstddef> #include <fstream> #include <vector> #include <cassert> int main() { // If the file is the same as the resource in the translation environment, no assert in this program should fail. constexpr unsigned char d[] = { #embed <data.dat> }; const std::vector<unsigned char> vec_d = { #embed <data.dat> }; constexpr std::size_t expected_size = sizeof(d); // same file in execution environment as was embedded std::ifstream f_source("data.dat", std::ios::binary | std::ios::in); unsigned char 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); } — end example]
[Example 3: 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 s { double a, b, c; struct { double e, f, g; } x; double h, i, j; }; s x = { // well-formed if the directive produces nine or fewer values #embed "s.dat" }; — end example]
10
#
A preprocessing directive of the form
# embed pp-tokens new-line
(that does not match one of the two previous forms) is permitted.
The preprocessing tokens after 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).
The directive resulting after all replacements of the third form shall match one of the two previous forms.
[Note 1: 
Adjacent string-literals are not concatenated into a single string-literal (see the translation phases in ([lex.phases])); thus, an expansion that results in two string-literals is an invalid directive.
— end note]
Any further processing as in normal text described for the two previous forms is not performed.
[Note 2: 
That is, processing as in normal text happens once and only once for the entire directive.
— end note]
[Example 4: 
If the directive matches the third form, the whole directive is replaced.
If the directive matches the first two forms, everything after the name is replaced.
#define prefix(ARG) suffix(ARG) #define THE_ADDITION "teehee" #define THE_RESOURCE ":3c" #embed ":3c" prefix(THE_ADDITION) #embed THE_RESOURCE prefix(THE_ADDITION)
is equivalent to:
#embed ":3c" suffix("teehee") #embed ":3c" suffix("teehee") — end example]
11
#
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 resource name preprocessing token is implementation-defined.