Skip to content

[CWG 2026-06-20] P3540R3 #embed offset parameter #9152

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
burblebee wants to merge 1 commit into
base: main
Choose a base branch
from
+106 −15
Open

[CWG 2026-06-20] P3540R3 #embed offset parameter #9152

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
121 changes: 106 additions & 15 deletions source/preprocessor.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -146,6 +146,7 @@
\begin{bnf}
\nontermdef{embed-standard-parameter}\br
\terminal{limit} \terminal{(} pp-balanced-token-seq \terminal{)}\br
\terminal{offset} \terminal{(} pp-balanced-token-seq \terminal{)}\br
\terminal{prefix} \terminal{(} \opt{pp-balanced-token-seq} \terminal{)}\br
\terminal{suffix} \terminal{(} \opt{pp-balanced-token-seq} \terminal{)}\br
\terminal{if_empty} \terminal{(} \opt{pp-balanced-token-seq} \terminal{)}
Expand Down Expand Up @@ -906,22 +907,44 @@
\grammarterm{embed-parameter-seq}.

\pnum
%%FIXME: Are we defining "resource" here?
A resource is a source of data accessible from the translation environment.
%%FIXME: Should "implementation-resource-width" really be a defined term?
A resource has an \defn{implementation-resource-width}, which is the
\impldef{size in bits of a resource}
size in bits of the resource.
If the implementation-resource-width is not an integral multiple of
\libmacro{CHAR_BIT}, the program is ill-formed.
%%FIXME: Should "implementation-resource-count" really be a defined term?
Let \defn{implementation-resource-count} be
implementation-resource-width divided by \libmacro{CHAR_BIT}.
Every resource has a \defn{resource-offset}, which is

\begin{itemize}
\item
the value as computed from the optionally-provided \tcode{offset}
\grammarterm{embed-parameter}\iref{cpp.embed.param.offset}, if present;
\item
otherwise, \tcode{0}.
\end{itemize}
Every resource also has a \defn{resource-count}, which is

\begin{itemize}
\item
the value as computed from the optionally-provided \tcode{limit}
\grammarterm{embed-parameter}\iref{cpp.embed.param.limit}, if present;
%%FIXME: Where did "value" come from? Or is "limit-value" supposed to be a thing?
%%FIXME: "implementation-resource-count" and "resource-offset" are defined terms, not values.
$max(min( \tcode{limit - value}, \tcode{implementation-resource-count - resource-offset}), 0)$
%%FIXME: What's "the limit /embed-parameter/"?
if the \tcode{limit}
\grammarterm{embed-parameter}\iref{cpp.embed.param.limit}
is present,
where the value computed
from the \tcode{limit} \grammarterm{embed-parameter}
is \tcode{limit - value};
\item
otherwise, the implementation-resource-count.
%%FIXME: "implementation-resource-count" and "resource-offset" are defined terms, not values.
otherwise,
$max( \tcode{implementation-resource-count - resource-offset}, 0)$.
\end{itemize}

A resource is empty if the resource-count is zero.
Expand All @@ -939,12 +962,22 @@
literals of type \tcode{int}, unless otherwise modified by embed
parameters\iref{cpp.embed.param}.

\pnum
The integer literals in the comma-separated list correspond to
resource-count consecutive calls to \tcode{std::fgetc}\iref{cstdio.syn}
from the resource, as a binary file.
If any call to \tcode{std::fgetc} returns \tcode{EOF}, the program is
ill-formed.
%%FIXME: Rewrite this paragraph, the subjects aren't clear.
%%FIXME: E.g. is "calls" a noun or verb? Maybe employ placeholders?
\pnum
First,
%%FIXME: resource-offset is not a function - how can it call anything?
resource-offset calls to \tcode{std::fgetc}
%%FIXME: "the resource"? what "resource"?
from the resource as a binary file
%%FIXME: "have" and "they"? what's the plural subject?
have their result discarded and ignored.
Next,
%%FIXME: "resource-count consecutive calls"?!? Did we mean "resource-count's"?
resource-count consecutive calls to \tcode{std::fgetc}
produce the elements of the comma-separated list of integer literals, in order.
If any of the resource-count calls to \tcode{std::fgetc} returns \tcode{EOF},
the program is ill-formed.

\pnum
\recommended The value of each integer literal should closely represent
Expand Down Expand Up @@ -1056,6 +1089,53 @@

\rSec2[cpp.embed.param]{Embed parameters}

\rSec3[cpp.embed.param.offset]{offset parameter}

\pnum
An \grammarterm{embed-parameter} of the form
\tcode{offset (} \grammarterm{pp-balanced-token-seq} \tcode{)}
denotes the number of elements to be skipped from the resource.
It shall appear at most once in the \grammarterm{embed-parameter-seq}.

\pnum
The \grammarterm{pp-balanced-token-seq}
is evaluated as a \grammarterm{constant-expression}
using the rules as described in conditional inclusion\iref{cpp.cond},
%%FIXME: "as in *normal* text"? "... an additional time"?
but without being processed as in normal text an additional time.

\pnum
The \grammarterm{constant-expression}
shall be an integral constant expression
whose value is greater than or equal to zero.

\pnum
\begin{example}
\begin{codeblock}
constexpr const unsigned char arr[] = {
// a hypothetical resource capable of expanding to
// four or more elements
#embed <sdk/jump.wav>
};

constexpr const unsigned char offset_arr[] = {
// the same hypothetical resource capable of expanding
// to four or more elements
#embed <sdk/jump.wav> offset(2)
};

constexpr const unsigned char offset_limit_arr[] = {
// the same hypothetical resource capable of expanding
// to four or more elements
#embed <sdk/jump.wav> offset(1) limit(1)
};

static_assert(arr[2] == offset_arr[0]); // OK
static_assert(arr[3] == offset_arr[1]); // OK
static_assert(arr[1] == offset_limit_arr[0]); // OK
\end{codeblock}
\end{example}

\rSec3[cpp.embed.param.limit]{limit parameter}

\pnum
Expand Down Expand Up @@ -1101,11 +1181,6 @@
\pnum
The \grammarterm{constant-expression} shall be an integral constant expression
whose value is greater than or equal to zero.
The resource-count\iref{cpp.embed.gen} becomes
implementation-resource-count, if the value of the
\grammarterm{constant-expression} is greater than
implementation-resource-count; otherwise, the value of the
\grammarterm{constant-expression}.
\begin{example}
\begin{codeblock}
constexpr unsigned char sound_signature[] = {
Expand Down Expand Up @@ -1204,6 +1279,22 @@
\end{codeblock}
\end{example}

%%FIXME: We say "the following directives" but there's only 1 in the example.
\begin{example}
Given a resource \tcode{<single_byte>}
that has an implementation-resource-count of \tcode{1},
the following directives:

\begin{codeblock}
#embed <single_byte> offset(1) if_empty(42203)
\end{codeblock}

are replaced with:
\begin{codeblock}
42203
\end{codeblock}
\end{example}

\rSec1[cpp.module]{Module directive}
\indextext{preprocessing directive!module}%

Expand Down Expand Up @@ -2428,7 +2519,7 @@
\defnxname{cpp_nsdmi} & \tcode{200809L} \\ \rowsep
\defnxname{cpp_pack_indexing} & \tcode{202311L} \\ \rowsep
\defnxname{cpp_placeholder_variables} & \tcode{202306L} \\ \rowsep
\defnxname{cpp_pp_embed} & \tcode{202502L} \\ \rowsep
\defnxname{cpp_pp_embed} & \tcode{202606L} \\ \rowsep
\defnxname{cpp_range_based_for} & \tcode{202211L} \\ \rowsep
\defnxname{cpp_raw_strings} & \tcode{200710L} \\ \rowsep
\defnxname{cpp_ref_qualifiers} & \tcode{200710L} \\ \rowsep
Expand Down
Loading