cppdraft_translate/cppdraft/cpp/embed/param.md

[cpp.embed.param]

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 formlimit ( 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 thepp-balanced-token-seq.

2

#

The pp-balanced-token-seq is evaluated as aconstant-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 theconstant-expression is greater than implementation-resource-count; otherwise, the value of theconstant-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-seqopt )

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

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 emptyconstexpr 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-seqopt )

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 thepp-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 to42203

— 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]