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]

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 preprocessing token defined shall not appear in the pp-balanced-token-seq .

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]

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]

An embed-parameter of the form

prefix ( pp-balanced-token-seq )

shall appear at most once in the embed-parameter-seq .

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]

An embed-parameter of the form

suffix ( pp-balanced-token-seq )

shall appear at most once in the embed-parameter-seq .

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]

An embed-parameter of the form

if_empty ( pp-balanced-token-seq )

shall appear at most once in the embed-parameter-seq .

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]