[cpp.embed.param] # 15 Preprocessing directives [[cpp]](./#cpp) ## 15.4 Resource inclusion [[cpp.embed]](cpp.embed#param) ### 15.4.2 Embed parameters [cpp.embed.param] #### [15.4.2.1](#limit) limit parameter [[cpp.embed.param.limit]](cpp.embed.param.limit) [1](#limit-1) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/preprocessor.tex#L1063) An [*embed-parameter*](cpp.pre#nt:embed-parameter "15.1 Preamble [cpp.pre]") of the formlimit ( [*pp-balanced-token-seq*](cpp.pre#nt:pp-balanced-token-seq "15.1 Preamble [cpp.pre]") ) specifies the maximum possible number of elements in the comma-delimited list[.](#limit-1.sentence-1) It shall appear at most once in the [*embed-parameter-seq*](cpp.pre#nt:embed-parameter-seq "15.1 Preamble [cpp.pre]")[.](#limit-1.sentence-2) The preprocessing token defined shall not appear in the[*pp-balanced-token-seq*](cpp.pre#nt:pp-balanced-token-seq "15.1 Preamble [cpp.pre]")[.](#limit-1.sentence-3) [2](#limit-2) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/preprocessor.tex#L1072) The [*pp-balanced-token-seq*](cpp.pre#nt:pp-balanced-token-seq "15.1 Preamble [cpp.pre]") is evaluated as a[*constant-expression*](expr.const#nt:constant-expression "7.7 Constant expressions [expr.const]") using the rules as described in conditional inclusion ([[cpp.cond]](cpp.cond "15.2 Conditional inclusion")), but without being processed as in normal text an additional time[.](#limit-2.sentence-1) [*Example [1](#limit-example-1)*: #undef DATA_LIMIT#if __has_embed( limit(DATA_LIMIT))#endif is equivalent to: #if __has_embed( limit(0))#endif — *end example*] [*Example [2](#limit-example-2)*: #embed limit(__has_include("a.h"))#if __has_embed( limit(__has_include("a.h")))// ill-formed: __has_include ([[cpp.cond]](cpp.cond "15.2 Conditional inclusion")) cannot appear here#endif — *end example*] [3](#limit-3) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/preprocessor.tex#L1103) The [*constant-expression*](expr.const#nt:constant-expression "7.7 Constant expressions [expr.const]") shall be an integral constant expression whose value is greater than or equal to zero[.](#limit-3.sentence-1) The resource-count ([[cpp.embed.gen]](cpp.embed.gen "15.4.1 General")) becomes implementation-resource-count, if the value of the[*constant-expression*](expr.const#nt:constant-expression "7.7 Constant expressions [expr.const]") is greater than implementation-resource-count; otherwise, the value of the[*constant-expression*](expr.const#nt:constant-expression "7.7 Constant expressions [expr.const]")[.](#limit-3.sentence-2) [*Example [3](#limit-example-3)*: constexpr unsigned char sound_signature[] = {// a hypothetical resource capable of expanding to four or more elements#embed limit(2+2)}; static_assert(sizeof(sound_signature) == 4); // OK — *end example*] #### [15.4.2.2](#prefix) prefix parameter [[cpp.embed.param.prefix]](cpp.embed.param.prefix) [1](#prefix-1) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/preprocessor.tex#L1123) An [*embed-parameter*](cpp.pre#nt:embed-parameter "15.1 Preamble [cpp.pre]") of the form prefix ( [*pp-balanced-token-seq*](cpp.pre#nt:pp-balanced-token-seq "15.1 Preamble [cpp.pre]")opt ) shall appear at most once in the [*embed-parameter-seq*](cpp.pre#nt:embed-parameter-seq "15.1 Preamble [cpp.pre]")[.](#prefix-1.sentence-1) [2](#prefix-2) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/preprocessor.tex#L1130) If the resource is empty, this [*embed-parameter*](cpp.pre#nt:embed-parameter "15.1 Preamble [cpp.pre]") is ignored[.](#prefix-2.sentence-1) Otherwise, the [*pp-balanced-token-seq*](cpp.pre#nt:pp-balanced-token-seq "15.1 Preamble [cpp.pre]") is placed immediately before the comma-delimited list of integral literals[.](#prefix-2.sentence-2) #### [15.4.2.3](#suffix) suffix parameter [[cpp.embed.param.suffix]](cpp.embed.param.suffix) [1](#suffix-1) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/preprocessor.tex#L1136) An [*embed-parameter*](cpp.pre#nt:embed-parameter "15.1 Preamble [cpp.pre]") of the form suffix ( [*pp-balanced-token-seq*](cpp.pre#nt:pp-balanced-token-seq "15.1 Preamble [cpp.pre]")opt ) shall appear at most once in the [*embed-parameter-seq*](cpp.pre#nt:embed-parameter-seq "15.1 Preamble [cpp.pre]")[.](#suffix-1.sentence-1) [2](#suffix-2) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/preprocessor.tex#L1143) If the resource is empty, this [*embed-parameter*](cpp.pre#nt:embed-parameter "15.1 Preamble [cpp.pre]") is ignored[.](#suffix-2.sentence-1) Otherwise, the [*pp-balanced-token-seq*](cpp.pre#nt:pp-balanced-token-seq "15.1 Preamble [cpp.pre]") is placed immediately after the comma-delimited list of the integral constant expressions[.](#suffix-2.sentence-2) [*Example [1](#suffix-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) if_empty parameter [[cpp.embed.param.if.empty]](cpp.embed.param.if.empty) [1](#if.empty-1) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/preprocessor.tex#L1166) An embed-parameter of the form if_empty ( [*pp-balanced-token-seq*](cpp.pre#nt:pp-balanced-token-seq "15.1 Preamble [cpp.pre]")opt ) shall appear at most once in the [*embed-parameter-seq*](cpp.pre#nt:embed-parameter-seq "15.1 Preamble [cpp.pre]")[.](#if.empty-1.sentence-1) [2](#if.empty-2) [#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/preprocessor.tex#L1173) If the resource is not empty, this [*embed-parameter*](cpp.pre#nt:embed-parameter "15.1 Preamble [cpp.pre]") is ignored[.](#if.empty-2.sentence-1) Otherwise, the #embed directive is replaced by the[*pp-balanced-token-seq*](cpp.pre#nt:pp-balanced-token-seq "15.1 Preamble [cpp.pre]")[.](#if.empty-2.sentence-2) [*Example [1](#if.empty-example-1)*: limit(0) affects when a resource is considered empty[.](#if.empty-2.sentence-3) Therefore, the following program: #embed \ if_empty(42203) limit(0) expands to42203 — *end example*] [*Example [2](#if.empty-example-2)*: This resource is considered empty due to the limit(0) [*embed-parameter*](cpp.pre#nt:embed-parameter "15.1 Preamble [cpp.pre]"), always, including in __has_embed clauses[.](#if.empty-2.sentence-6) int infinity_zero () {#if __has_embed( limit(0) prefix(some tokens)) == __STDC_EMBED_EMPTY__ // if 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*]