1. Changelog
1.1. Revision 0 - April 12th, 2022
-
Initial release! 🎉
2. Introduction and Motivation
Users did not have a way to adequately query support of specific kinds of literals or the maximum integer their processor could handle without triggering constraint violations for handling tokens in the preprocessor. It was only in the upcoming C23 Standard that users received a way to check whether or not an integer constant they wrote was valid by checking the width of that value against
.
This, however, still leaves other problems out in the open.
There are implementations with special floating point, string, and other kinds of literals built in as extensions to the language. They cannot be adequately captured by the standard and thus leaves users to fall back to using special compiler-specific preprocessor macros to gate usage so as not to produce errors. Worse, the integer problem ties the Application Binary Interface problems of
to all literals made by the implementation, typically limiting them to 64-bit maximum values for their literals. This has becoming an increasingly difficult problem, and many proposals - including one for bit-precise integer types (
, [N2946]) and one for the bit-specific integer types ([N2889]) - are trying to divorce
from certain types so they can be larger than the type.
While these are all good movements in the right direction, we propose a more fundamental fix that can be applied to more cases and allow for easier future growth in the space of literals, while simultaneously improving the situation around integer-based literals related to
. The feature is a
preprocessor directive, which returns a positive integer for recognized constant/literal token sequence, and
otherwise.
3. Design
is a preprocessor macro function that is usable in
preprocessor directives and produces an integer constant expression. It takes a
s sequence and determines whether or not the given sequence resolves to a literal. The return values are as follows:
-
, which means the token sequence does not resolve to any kind of literal, or is a recognized literal that exceeds the limitations of the literal type (e.g., a too-large integer literal);0 -
, which means the token sequence resolves to a recognized standard or extended integer literal;1 -
, which means the token sequence resolves to a recognized bit-precise integer literal;2 -
, which means the token sequence resolves to a recognized standard or extended floating point literal;3 -
, which means the token sequence resolves to a recognized character literal; and,4 -
, which means the token sequence resolves to a recognized string literal.5
This allows an implementation to properly advertise support for various constructs as provided by their implementation. For example, the GNU Compiler Collection (GCC) supports "raw string literals" (see: [raw-string-literals]), but only with
instead of
. Therefore, it can be detected by writing:
#if __supports_literal(R"meow(🐈😸😹😺😻)meow") // Supports the raw string literal syntax #else // Does NOT support raw string literal syntax #endif
A more concrete example of this are types which extend the typical preprocessor syntax beyond just larger integer support or similar. For example, shading languages like HLSL and GLSL have built-in support for providing floating constants as a 16-bit type named "half" with the syntax
, where
is the floating point suffix here. Some implementations simply support 128-bit integers natively in their compilers as well, but often cannot give support for it in the preprocessor due to the limitations of
and the ABI problems which surround upgrading the type. Finally, there are extensions to write decimal floating point types directly as floating point constants as well.
This syntax enables software engineers hoping to write robust C code to check for the support for all of these things and act accordingly, allowing for a consistent way to enable constants of types outside of what is currently blessed by the C Standard and already in use with many existing implementations and direct derivatives of C.
4. Wording
Wording is relative to [N2731].
4.1. Modify 6.10.1 Conditional inclusion with new syntax, a __supports_literal expression, and new Recommended Practice
6.10.1 Conditional inclusionSyntax…has-include-expression:
__has_include ( header-name )
__has_include ( header-name-tokens )
supports-literal-expression:
__supports_literal ( pp-tokens )
…
ConstraintsThe expression that controls conditional inclusion shall be an integer constant expression except that: identifiers (including those lexically identical to keywords) are interpreted as described below182) and it may contain zero or more defined macro expressions, has_include expressions, supports_literal expressions, and/or has_c_attribute expressions as unary operator expressions.Each supports_literal expression is replaced by a nonzero pp-number matching the form of an integer constant if the implementation supports the given sequence of tokens. The value of the replacement pp-number integer constant for supported token sequences is:
— 1 if the token sequence is a valid standard or extended integer constant;
— 2 if the token sequence is a valid bit-precise integer constant;
— 3 if the token sequence is a standard or extended floating constant;
— 4 if the token sequence is a character constant;
— 5 if the token sequence is a string literal;
— or, an integer constant greater than or equal to 1000 in value if the token sequence for any other implementation-defined constant.FN0)
Otherwise, the value of the replacement pp-number integer constant shall be zero. The pp-tokens shall match the form of the associated constant or literal when the replacement is a non-zero pp-number.
…Prior to evaluation, macro invocations in the list of preprocessing tokens that will become the controlling constant expression are replaced (except for those macro names modified by the defined unary operator), just as in normal text. If the token defined is generated as a result of this replacement process or use of the defined unary operator does not match one of the two specified forms prior to macro replacement, the behavior is undefined. After all replacements due to macro expansion and evaluations of defined macro expressions, has_include expressions, supports_literal expressions, and has_c_attribute expressions have been performed, all remaining identifiers (including those lexically identical to keywords) are replaced with the pp-number, and then each preprocessing token is converted into a token. The resulting tokens compose the controlling constant expression which is evaluated according to the rules of 6.6. For the purposes of this token conversion and evaluation, all signed integer types and all unsigned integer types act as if they have the same representation as, respectively,
0 the typestypes with a width that are greater than or equal toand
intmax_t defined in the header
uintmax_t .183) This includes interpreting character constants, which may involve converting escape sequences into execution character set members. Whether the numeric value for these character constants matches the value obtained when an identical character constant occurs in an expression (other than within a
< stdint . h > or
#if directive) is implementation-defined.
#elif …EXAMPLE This demonstrates a way to check for very large integer literals and, if supported, use it as the type for a large integer type.#if __supports_literal(340282366920938463463374607431768211455) // use potential implementation-defined large literal type #define SUPPORTS_LONG_LITERAL 1 typedef typeof ( 340282366920938463463374607431768211455 ) long_literal_t ; #else #define SUPPORTS_LONG_LITERAL 0 // no big literal type #endif Recommended PracticeFor has_c_attribute expressions, an implementation which recognizes a given implementation-defined attribute should replace the expression with a pp-number of the form. The value should change value whenever a significant change is made to the attribute’s semantics.
yyyymm For supports_literal expressions, an implementation which recognizes a given implementation-defined constant or literal should replace the expression with a pp-number of the form, where "xxxx" provides meaningful information to the end-user. Some meaningful values may be:
xxxx000
Value Suggested Meaning 1000 Implementation-defined integer constants, e.g. for flexible, unlimited precision integer constants and similar integer constants. 2000 Implementation-defined bit-precise integer constants, e.g. those potentially beyond the width of but nonetheless supported by the implementation’s preprocessor directives or constant expression engine.
BITINT_MAXWIDTH 3000 Implementation-defined floating constants, e.g. for Decimal floating point (Annex H) and similar floating point constants. 4000 Implementation-defined character constants, e.g. character constants which imbue a given encoding.. 5000 Implementation-defined string literals, e.g. for different formats of string literals which treat escape sequences or provide translation-time format substitution information.