Skip to content

Commit 011be33

Browse files
burblebeetkoeppe
authored andcommitted
P3540R3 #embed offset parameter
Editorial note: * [cpp.embed.gen] added the words "the value" before two long mathematical expressions, both for ease of reading and to make the lines fit better.
1 parent 0891e81 commit 011be33

1 file changed

Lines changed: 83 additions & 15 deletions

File tree

‎source/preprocessor.tex‎

Lines changed: 83 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -146,6 +146,7 @@
146146
\begin{bnf}
147147
\nontermdef{embed-standard-parameter}\br
148148
\terminal{limit} \terminal{(} pp-balanced-token-seq \terminal{)}\br
149+
\terminal{offset} \terminal{(} pp-balanced-token-seq \terminal{)}\br
149150
\terminal{prefix} \terminal{(} \opt{pp-balanced-token-seq} \terminal{)}\br
150151
\terminal{suffix} \terminal{(} \opt{pp-balanced-token-seq} \terminal{)}\br
151152
\terminal{if_empty} \terminal{(} \opt{pp-balanced-token-seq} \terminal{)}
@@ -915,16 +916,25 @@
915916
\libmacro{CHAR_BIT}, the program is ill-formed.
916917
Let \defn{implementation-resource-count} be
917918
implementation-resource-width divided by \libmacro{CHAR_BIT}.
918-
Every resource also has a \defn{resource-count}, which is
919+
Every resource has a \defn{resource-offset}, which is
919920

920921
\begin{itemize}
921922
\item
922-
the value as computed from the optionally-provided \tcode{limit}
923-
\grammarterm{embed-parameter}\iref{cpp.embed.param.limit}, if present;
923+
the value as computed from the optionally-provided \tcode{offset}
924+
\grammarterm{embed-parameter}\iref{cpp.embed.param.offset}, if present;
924925
\item
925-
otherwise, the implementation-resource-count.
926+
otherwise, \tcode{0}.
926927
\end{itemize}
928+
Every resource also has a \defn{resource-count}, which is
927929

930+
\begin{itemize}
931+
\item
932+
the value $\max(\min(\text{limit-value}, \text{implementation-resource-count} - \text{resource-offset}), 0)$
933+
if the \tcode{limit} \grammarterm{embed-parameter}\iref{cpp.embed.param.limit} is present,
934+
where the value computed from the \tcode{limit} \grammarterm{embed-parameter} is \defn{limit-value};
935+
\item
936+
otherwise, the value $\max(\text{implementation-resource-count} - \text{resource-offset}, 0)$.
937+
\end{itemize}
928938
A resource is empty if the resource-count is zero.
929939

930940
\pnum
@@ -941,11 +951,15 @@
941951
parameters\iref{cpp.embed.param}.
942952

943953
\pnum
944-
The integer literals in the comma-separated list correspond to
945-
resource-count consecutive calls to \tcode{std::fgetc}\iref{cstdio.syn}
946-
from the resource, as a binary file.
947-
If any call to \tcode{std::fgetc} returns \tcode{EOF}, the program is
948-
ill-formed.
954+
First,
955+
resource-offset calls to \tcode{std::fgetc}
956+
from the resource as a binary file
957+
have their result discarded and ignored.
958+
Next,
959+
resource-count consecutive calls to \tcode{std::fgetc}
960+
produce the elements of the comma-separated list of integer literals, in order.
961+
If any of the resource-count calls to \tcode{std::fgetc} returns \tcode{EOF},
962+
the program is ill-formed.
949963

950964
\pnum
951965
\recommended The value of each integer literal should closely represent
@@ -1102,11 +1116,6 @@
11021116
\pnum
11031117
The \grammarterm{constant-expression} shall be an integral constant expression
11041118
whose value is greater than or equal to zero.
1105-
The resource-count\iref{cpp.embed.gen} becomes
1106-
implementation-resource-count, if the value of the
1107-
\grammarterm{constant-expression} is greater than
1108-
implementation-resource-count; otherwise, the value of the
1109-
\grammarterm{constant-expression}.
11101119
\begin{example}
11111120
\begin{codeblock}
11121121
constexpr unsigned char sound_signature[] = {
@@ -1118,7 +1127,51 @@
11181127
\end{codeblock}
11191128
\end{example}
11201129

1130+
\rSec3[cpp.embed.param.offset]{offset parameter}
1131+
1132+
\pnum
1133+
An \grammarterm{embed-parameter} of the form
1134+
\tcode{offset (} \grammarterm{pp-balanced-token-seq} \tcode{)}
1135+
denotes the number of elements to be skipped from the resource.
1136+
It shall appear at most once in the \grammarterm{embed-parameter-seq}.
1137+
1138+
\pnum
1139+
The \grammarterm{pp-balanced-token-seq}
1140+
is evaluated as a \grammarterm{constant-expression}
1141+
using the rules as described in conditional inclusion\iref{cpp.cond},
1142+
but without being processed as in normal text an additional time.
1143+
1144+
\pnum
1145+
The \grammarterm{constant-expression}
1146+
shall be an integral constant expression
1147+
whose value is greater than or equal to zero.
1148+
1149+
\pnum
1150+
\begin{example}
1151+
\begin{codeblock}
1152+
constexpr const unsigned char arr[] = {
1153+
// a hypothetical resource capable of expanding to four or more elements
1154+
#embed <sdk/jump.wav>
1155+
};
1156+
1157+
constexpr const unsigned char offset_arr[] = {
1158+
// the same hypothetical resource capable of expanding to four or more elements
1159+
#embed <sdk/jump.wav> offset(2)
1160+
};
1161+
1162+
constexpr const unsigned char offset_limit_arr[] = {
1163+
// the same hypothetical resource capable of expanding to four or more elements
1164+
#embed <sdk/jump.wav> offset(1) limit(1)
1165+
};
1166+
1167+
static_assert(arr[2] == offset_arr[0]); // OK
1168+
static_assert(arr[3] == offset_arr[1]); // OK
1169+
static_assert(arr[1] == offset_limit_arr[0]); // OK
1170+
\end{codeblock}
1171+
\end{example}
1172+
11211173
\rSec3[cpp.embed.param.prefix]{prefix parameter}
1174+
11221175
\pnum
11231176
An \grammarterm{embed-parameter} of the form
11241177
\begin{ncsimplebnf}
@@ -1132,6 +1185,7 @@
11321185
before the comma-delimited list of integral literals.
11331186

11341187
\rSec3[cpp.embed.param.suffix]{suffix parameter}
1188+
11351189
\pnum
11361190
An \grammarterm{embed-parameter} of the form
11371191
\begin{ncsimplebnf}
@@ -1162,6 +1216,7 @@
11621216
\end{example}
11631217

11641218
\rSec3[cpp.embed.param.if.empty]{\tcode{if_empty} parameter}
1219+
11651220
\pnum
11661221
An embed-parameter of the form
11671222
\begin{ncsimplebnf}
@@ -1205,6 +1260,19 @@
12051260
\end{codeblock}
12061261
\end{example}
12071262

1263+
\begin{example}
1264+
Given a resource \tcode{<single_byte>}
1265+
that has an implementation-resource-count of \tcode{1},
1266+
the following directives:
1267+
\begin{codeblock}
1268+
#embed <single_byte> offset(1) if_empty(42203)
1269+
\end{codeblock}
1270+
are replaced with:
1271+
\begin{codeblock}
1272+
42203
1273+
\end{codeblock}
1274+
\end{example}
1275+
12081276
\rSec1[cpp.module]{Module directive}
12091277
\indextext{preprocessing directive!module}%
12101278

@@ -2389,7 +2457,7 @@
23892457
\defnxname{cpp_nsdmi} & \tcode{200809L} \\ \rowsep
23902458
\defnxname{cpp_pack_indexing} & \tcode{202606L} \\ \rowsep
23912459
\defnxname{cpp_placeholder_variables} & \tcode{202306L} \\ \rowsep
2392-
\defnxname{cpp_pp_embed} & \tcode{202502L} \\ \rowsep
2460+
\defnxname{cpp_pp_embed} & \tcode{202606L} \\ \rowsep
23932461
\defnxname{cpp_range_based_for} & \tcode{202211L} \\ \rowsep
23942462
\defnxname{cpp_raw_strings} & \tcode{200710L} \\ \rowsep
23952463
\defnxname{cpp_ref_qualifiers} & \tcode{200710L} \\ \rowsep

0 commit comments

Comments
 (0)