15 Preprocessing directives [cpp]

15.4 Resource inclusion [cpp.embed]

15.4.2 Embed parameters [cpp.embed.param]

15.4.2.1 limit parameter [cpp.embed.param.limit]

1
#
An embed-parameter of the form limit ( pp-balanced-token-seq ) specifies the maximum possible number of elements in the comma-delimited list.
It shall appear at most once in the embed-parameter-seq.
The token defined shall not appear in the constant-expression.
2
#
The pp-balanced-token-seq is evaluated as a constant-expression using the rules as described in conditional inclusion ([cpp.cond]), but without being processed as in normal text an additional time.
[Example 1: #undef DATA_LIMIT #if __has_embed(<data.dat> limit(DATA_LIMIT)) #endif
is equivalent to:
#if __has_embed(<data.dat> limit(0)) #endif — end example]
[Example 2: #embed <data.dat> limit(__has_include("a.h")) #if __has_embed(<data.dat> limit(__has_include("a.h"))) // ill-formed: __has_include ([cpp.cond]) cannot appear here #endif — end example]
3
#
The constant-expression shall be an integral constant expression whose value is greater than or equal to zero.
The resource-count ([cpp.embed.gen]) becomes implementation-resource-count, if the value of the constant-expression is greater than implementation-resource-count; otherwise, the value of the constant-expression.
[Example 3: constexpr unsigned char 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); // OK — end example]

15.4.2.2 prefix parameter [cpp.embed.param.prefix]

1
#
An embed-parameter of the form
prefix ( pp-balanced-token-seq )
shall appear at most once in the embed-parameter-seq.
2
#
If the resource is empty, this embed-parameter is ignored.
Otherwise, the pp-balanced-token-seq is placed immediately before the comma-delimited list of integral literals.

15.4.2.3 suffix parameter [cpp.embed.param.suffix]

1
#
An embed-parameter of the form
suffix ( pp-balanced-token-seq )
shall appear at most once in the embed-parameter-seq.
2
#
If the resource is empty, this embed-parameter is ignored.
Otherwise, the pp-balanced-token-seq is placed immediately after the comma-delimited list of the integral constant expressions.
[Example 1: constexpr unsigned char whl[] = { #embed "ches.glsl" \ prefix(0xEF, 0xBB, 0xBF, ) /* a sequence of bytes */ \ suffix(,) 0 }; // always null-terminated, contains the sequence if not empty constexpr bool is_empty = sizeof(whl) == 1 && whl[0] == '\0'; constexpr bool 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); — end example]

15.4.2.4 if_empty parameter [cpp.embed.param.if.empty]

1
#
An embed-parameter of the form
if_empty ( pp-balanced-token-seq )
shall appear at most once in the embed-parameter-seq.
2
#
If the resource is not empty, this embed-parameter is ignored.
Otherwise, the #embed directive is replaced by the pp-balanced-token-seq.
[Example 1: 
limit(0) affects when a resource is considered empty.
Therefore, the following program:
#embed </owo/uwurandom> \ if_empty(42203) limit(0) expands to 42203
— end example]
[Example 2: 
This resource is considered empty due to the limit(0) embed-parameter, always, including in __has_embed clauses.
int infinity_zero () { #if __has_embed(</owo/uwurandom> limit(0) prefix(some tokens)) == __STDC_EMBED_EMPTY__ // if </owo/uwurandom> exists, this conditional inclusion branch is taken and the function returns 0. return 0; #else // otherwise, the resource does not exist #error "The resource does not exist" #endif } — end example]