N2962
__supports_literal

1. Changelog

1.1. Revision 0 - April 12^th, 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 (U)INTMAX_WIDTH.

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 intmax_t 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 (_BitInt(...), [N2946]) and one for the bit-specific integer types ([N2889]) - are trying to divorce intmax_t 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 intmax_t. The feature is a __supports_literal preprocessor directive, which returns a positive integer for recognized constant/literal token sequence, and 0 otherwise.

3. Design

__supports_literal is a preprocessor macro function that is usable in #if preprocessor directives and produces an integer constant expression. It takes a pp-tokens sequence and determines whether or not the given sequence resolves to a literal. The return values are as follows:

• 0, 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);

• 1, which means the token sequence resolves to a recognized standard or extended integer literal;

• 2, which means the token sequence resolves to a recognized bit-precise integer literal;

• 3, which means the token sequence resolves to a recognized standard or extended floating point literal;

• 4, which means the token sequence resolves to a recognized character literal; and,

• 5, which means the token sequence resolves to a recognized string literal.

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 -std=gnu11 instead of -std=c11. 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 32.h, where h 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 intmax_t 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 inclusion

Syntax

…

has-include-expression:

__has_include ( header-name )

__has_include ( header-name-tokens )

supports-literal-expression:

__supports_literal ( pp-tokens )

…

Constraints

The 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 0, 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, the types types with a width that are greater than or equal to intmax_t and uintmax_t defined in the header <stdint.h>.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 #if or #elif directive) is implementation-defined.

…

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 Practice

For has_c_attribute expressions, an implementation which recognizes a given implementation-defined attribute should replace the expression with a pp-number of the form yyyymm. The value should change value whenever a significant change is made to the attribute’s semantics.

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 xxxx000, where "xxxx" provides meaningful information to the end-user. Some meaningful values may be:

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 BITINT_MAXWIDTH but nonetheless supported by the implementation’s preprocessor directives or constant expression engine.
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.

183)Thus, on an implementation where INT_MAX is 0x7FFF and UINT_MAX is 0xFFFF, the constant 0x8000 is signed and positive within an #if expression even though it would be unsigned in translation phase 7. Integer constants which require a greater width than the minimum required 64-bit long long and unsigned long long may be checked using supports_literal expressions before being used.

…

FN0)For example, an implementation-defined extension which provides for a string literal that ignores escape sequences as "R"raw(merp"baa)raw", when used in a supports-literal expression, may produce an integer constant with a value of 5000. An implementation-defined extension which provides for 16-bit binary floating point as 32.5h, when used in a supports-literal expression, may produce an integer constant with a value of 3000.