From cd923c18f8513309ab7c424dd223097196cb1a75 Mon Sep 17 00:00:00 2001 From: Dawn Perchik Date: Fri, 19 Jun 2026 21:33:18 -0700 Subject: [PATCH] P3540R3 #embed offset parameter --- source/preprocessor.tex | 121 +++++++++++++++++++++++++++++++++++----- 1 file changed, 106 insertions(+), 15 deletions(-) diff --git a/source/preprocessor.tex b/source/preprocessor.tex index 0bfb7f194f..bdcbcd8970 100644 --- a/source/preprocessor.tex +++ b/source/preprocessor.tex @@ -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{)} @@ -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. @@ -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 @@ -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 +}; + +constexpr const unsigned char offset_arr[] = { + // the same hypothetical resource capable of expanding + // to four or more elements +#embed offset(2) +}; + +constexpr const unsigned char offset_limit_arr[] = { + // the same hypothetical resource capable of expanding + // to four or more elements +#embed 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 @@ -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[] = { @@ -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{} +that has an implementation-resource-count of \tcode{1}, +the following directives: + +\begin{codeblock} +#embed 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}% @@ -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