From Jason Turner

[cpp.embed.param]

C++23 → Trunk 4.4 KB 163 lines
Current Draft | LaTeX Source
Archived: C++23
Markdown: C++23 | Trunk
Explore in Adventure Game

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmpga9kcqrc/{from.md → to.md} +160 -0
tmp/tmpga9kcqrc/{from.md → to.md} RENAMED
@@ -0,0 +1,160 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ ### Embed parameters <a id="cpp.embed.param">[[cpp.embed.param]]</a>
2
+
3
+ #### limit parameter <a id="cpp.embed.param.limit">[[cpp.embed.param.limit]]</a>
4
+
5
+ An *embed-parameter* of the form `limit (` *pp-balanced-token-seq* `)`
6
+ specifies the maximum possible number of elements in the comma-delimited
7
+ list. It shall appear at most once in the *embed-parameter-seq*. The
8
+ preprocessing token `defined` shall not appear in the
9
+ *pp-balanced-token-seq*.
10
+
11
+ The *pp-balanced-token-seq* is evaluated as a *constant-expression*
12
+ using the rules as described in conditional inclusion [[cpp.cond]], but
13
+ without being processed as in normal text an additional time.
14
+
15
+ [*Example 1*:
16
+
17
+ ``` cpp
18
+ #undef DATA_LIMIT
19
+ #if __has_embed(<data.dat> limit(DATA_LIMIT))
20
+ #endif
21
+ ```
22
+
23
+ is equivalent to:
24
+
25
+ ``` cpp
26
+ #if __has_embed(<data.dat> limit(0))
27
+ #endif
28
+ ```
29
+
30
+ — *end example*]
31
+
32
+ [*Example 2*:
33
+
34
+ ``` cpp
35
+ #embed <data.dat> limit(__has_include("a.h"))
36
+
37
+ #if __has_embed(<data.dat> limit(__has_include("a.h")))
38
+ // ill-formed: __has_include[cpp.cond] cannot appear here
39
+ #endif
40
+ ```
41
+
42
+ — *end example*]
43
+
44
+ The *constant-expression* shall be an integral constant expression whose
45
+ value is greater than or equal to zero. The resource-count
46
+ [[cpp.embed.gen]] becomes implementation-resource-count, if the value of
47
+ the *constant-expression* is greater than implementation-resource-count;
48
+ otherwise, the value of the *constant-expression*.
49
+
50
+ [*Example 3*:
51
+
52
+ ``` cpp
53
+ constexpr unsigned char sound_signature[] = {
54
+ // a hypothetical resource capable of expanding to four or more elements
55
+ #embed <sdk/jump.wav> limit(2+2)
56
+ };
57
+
58
+ static_assert(sizeof(sound_signature) == 4); // OK
59
+ ```
60
+
61
+ — *end example*]
62
+
63
+ #### prefix parameter <a id="cpp.embed.param.prefix">[[cpp.embed.param.prefix]]</a>
64
+
65
+ An *embed-parameter* of the form
66
+
67
+ ``` bnf
68
+ 'prefix (' pp-balanced-token-seqₒₚₜ ')'
69
+ ```
70
+
71
+ shall appear at most once in the *embed-parameter-seq*.
72
+
73
+ If the resource is empty, this *embed-parameter* is ignored. Otherwise,
74
+ the *pp-balanced-token-seq* is placed immediately before the
75
+ comma-delimited list of integral literals.
76
+
77
+ #### suffix parameter <a id="cpp.embed.param.suffix">[[cpp.embed.param.suffix]]</a>
78
+
79
+ An *embed-parameter* of the form
80
+
81
+ ``` bnf
82
+ 'suffix (' pp-balanced-token-seqₒₚₜ ')'
83
+ ```
84
+
85
+ shall appear at most once in the *embed-parameter-seq*.
86
+
87
+ If the resource is empty, this *embed-parameter* is ignored. Otherwise,
88
+ the *pp-balanced-token-seq* is placed immediately after the
89
+ comma-delimited list of the integral constant expressions.
90
+
91
+ [*Example 1*:
92
+
93
+ ``` cpp
94
+ constexpr unsigned char whl[] = {
95
+ #embed "ches.glsl" \
96
+ prefix(0xEF, 0xBB, 0xBF, ) /* a sequence of bytes */ \
97
+ suffix(,)
98
+ 0
99
+ };
100
+ // always null-terminated, contains the sequence if not empty
101
+ constexpr bool is_empty = sizeof(whl) == 1 && whl[0] == '\0';
102
+ constexpr bool is_not_empty = sizeof(whl) >= 4
103
+ && whl[sizeof(whl) - 1] == '\0'
104
+ && whl[0] == '\xEF' && whl[1] == '\xBB' && whl[2] == '\xBF';
105
+ static_assert(is_empty || is_not_empty);
106
+ ```
107
+
108
+ — *end example*]
109
+
110
+ #### `if_empty` parameter <a id="cpp.embed.param.if.empty">[[cpp.embed.param.if.empty]]</a>
111
+
112
+ An embed-parameter of the form
113
+
114
+ ``` bnf
115
+ 'if_empty (' pp-balanced-token-seqₒₚₜ ')'
116
+ ```
117
+
118
+ shall appear at most once in the *embed-parameter-seq*.
119
+
120
+ If the resource is not empty, this *embed-parameter* is ignored.
121
+ Otherwise, the `#embed` directive is replaced by the
122
+ *pp-balanced-token-seq*.
123
+
124
+ [*Example 1*:
125
+
126
+ `limit(0)` affects when a resource is considered empty. Therefore, the
127
+ following program:
128
+
129
+ ``` cpp
130
+ #embed </owo/uwurandom> \
131
+ if_empty(42203) limit(0)
132
+ ```
133
+
134
+ expands to
135
+
136
+ ``` cpp
137
+ 42203
138
+ ```
139
+
140
+ — *end example*]
141
+
142
+ [*Example 2*:
143
+
144
+ This resource is considered empty due to the `limit(0)`
145
+ *embed-parameter*, always, including in `__has_embed` clauses.
146
+
147
+ ``` cpp
148
+ int infinity_zero () {
149
+ #if __has_embed(</owo/uwurandom> limit(0) prefix(some tokens)) == __STDC_EMBED_EMPTY__
150
+ // if </owo/uwurandom> exists, this conditional inclusion branch is taken and the function returns 0.
151
+ return 0;
152
+ #else
153
+ // otherwise, the resource does not exist
154
+ #error "The resource does not exist"
155
+ #endif
156
+ }
157
+ ```
158
+
159
+ — *end example*]
160
+