String Literal Macros

Macros
#define	_S
	Creates a static ASCII string literal (STR_LEN0, runtime strlen). Prefer _SL() on hot paths when targeting GCC/Clang.
#define	_SU
	Creates a static UTF-8 string literal (STR_LEN0, runtime strlen). Prefer _SLU() on hot paths when targeting GCC/Clang.
#define	_SO
	Creates a static string literal with other/unknown encoding (STR_LEN0, runtime strlen). Prefer _SLO() on hot paths when targeting GCC/Clang.
#define	STR_CONST(name, s)   _STR_CONST8(name, 0xE1u, s)
	Declare a named ASCII string constant with a compile-time length (STR_LEN8, < 255 bytes).
#define	STR_CONSTU(name, s)   _STR_CONST8(name, 0xA1u, s)
	Declare a named UTF-8 string constant with a compile-time length (STR_LEN8, < 255 bytes).
#define	STR_CONSTO(name, s)   _STR_CONST8(name, 0x81u, s)
#define	STR_CONSTL(name, s)   _STR_CONST16(name, 0xE2u, s)
	Declare a named ASCII string constant with a compile-time length (STR_LEN16, < 65535 bytes).
#define	STR_CONSTUL(name, s)   _STR_CONST16(name, 0xA2u, s)
	Declare a named UTF-8 string constant with a compile-time length (STR_LEN16, < 65535 bytes).
#define	STR_CONSTOL(name, s)   _STR_CONST16(name, 0x82u, s)
#define	STR_CONSTR(name, s)   _STR_CONSTR8(name, 0xE1u, s)
#define	STR_CONSTRU(name, s)   _STR_CONSTR8(name, 0xA1u, s)
#define	STR_CONSTRO(name, s)   _STR_CONSTR8(name, 0x81u, s)
#define	STR_CONSTRL(name, s)   _STR_CONSTR16(name, 0xE2u, s)
#define	STR_CONSTRUL(name, s)   _STR_CONSTR16(name, 0xA2u, s)
#define	STR_CONSTROL(name, s)   _STR_CONSTR16(name, 0x82u, s)
#define	_SR(name)   ((strref)&_cx_sc_##name)
#define	_SL(s)
	Inline ASCII string literal with compile-time embedded length (STR_LEN8). Content must be < 200 bytes; use _SLL() for longer strings.
#define	_SLU(s)
	Inline UTF-8 string literal with compile-time embedded length (STR_LEN8). Content must be < 200 bytes; use _SLUL() for longer strings.
#define	_SLO(s)
	Inline other-encoding string literal with compile-time embedded length (STR_LEN8). Content must be < 200 bytes; use _SLOL() for longer strings.
#define	_SLL(s)
	Inline ASCII string literal with compile-time embedded length (STR_LEN16). For strings 200–65534 bytes; use _SL() for shorter strings.
#define	_SLUL(s)
	Inline UTF-8 string literal with compile-time embedded length (STR_LEN16).
#define	_SLOL(s)
	Inline other-encoding string literal with compile-time embedded length (STR_LEN16).

Detailed Description

Three families of macros for creating CX strings from C string literals. All produce static read-only strings that require no initialization and no cleanup — modification automatically triggers a copy-on-write.

Because these live in static storage for the life of the program, the library references them directly and never copies them. This is what distinguishes them from a runtime C string cast to strref, whose lifetime is unknown and which is therefore copied by anything that retains it.

Simple prefix macros (_S, _SU, _SO) — portable, all platforms:

Prepend a 2-byte CX header to a string literal. The string length is not stored in the header and is computed at runtime via strlen() on first use. These are the simplest form and are appropriate for most usage:

string s1 = _S"Hello";           // ASCII literal
string s2 = _SU"Hello 世界";      // UTF-8 literal
strDup(&s1, _S"World");          // Can use in any string function

Inline expression macros (_SL, _SLU, _SLO / _SLL, _SLUL, _SLOL):

Drop-in replacements for _S that embed the length as a compile-time constant, eliminating the runtime strlen(). On GCC/Clang these expand to a static struct (STR_LEN8 or STR_LEN16). On MSVC they silently fall back to _S behavior (STR_LEN0); correctness is preserved, the length optimization is simply not applied. Prefer these over _S on hot paths when targeting GCC/Clang.

The short forms (_SL, _SLU, _SLO) enforce content < 200 bytes at compile time on GCC/Clang — use the long forms (_SLL, _SLUL, _SLOL) for larger strings:

strDup(&s, _SL("hello"));                   // STR_LEN8 on GCC/Clang
strDup(&s, _SLL("a 200+ byte string..."));  // STR_LEN16 on GCC/Clang

Named constants (STR_CONST / STR_CONSTL families) — portable, all platforms:

Declares a named strref backed by a static struct with a compile-time embedded length. Works on all platforms. Use at file scope or as static locals when the same string is referenced in multiple places:

STR_CONST(kError, "Something went wrong");    // ASCII, STR_LEN8, < 255 bytes
STR_CONSTU(kGreeting, "Héllo");               // UTF-8, STR_LEN8
STR_CONSTL(kTemplate, "... long string ..."); // ASCII, STR_LEN16, < 65535 bytes

Struct initializers (STR_CONSTR + _SR) — portable, all platforms:

Using a strref variable from STR_CONST in a static struct or array initializer is not portable across all compilers. Use STR_CONSTR to declare the backing constant and _SR() to reference it in the initializer:

STR_CONSTR(kLabel, "item label");
 
static const ItemInfo info = {
    .name = _SR(kLabel),
};

Header byte quick reference:

Family	Encoding	Length class	hdr byte
_S / _SL	ASCII+UTF-8	STR_LEN0 / LEN8	0xE0 / 0xE1
_SU / _SLU	UTF-8	STR_LEN0 / LEN8	0xA0 / 0xA1
_SO / _SLO	other	STR_LEN0 / LEN8	0x80 / 0x81
_SLL	ASCII+UTF-8	STR_LEN16	0xE2
_SLUL	UTF-8	STR_LEN16	0xA2
_SLOL	other	STR_LEN16	0x82

Macro Definition Documentation

_SR

#define _SR

(

name

)

((strref)&_cx_sc_##name)

strref _SR(name);

Produce a portable strref initializer expression from a constant declared with STR_CONSTR.

Use this to initialize strref fields in static struct or array literals. A STR_CONST variable cannot be used there portably — STR_CONSTR + _SR() is the correct alternative. If a constant already declared with STR_CONST is also needed in an initializer, _SR() works with it too, avoiding a duplicate declaration.

Parameters

name	The name passed to STR_CONSTR (or STR_CONSTRU, STR_CONSTRL, etc.), or to STR_CONST

Definition at line 187 of file strliteral.h.

STR_CONSTO

#define STR_CONSTO	(		name,
			s
	)		_STR_CONST8(name, 0x81u, s)

Declare a named other-encoding string constant with a compile-time length (STR_LEN8, < 255 bytes).

Definition at line 148 of file strliteral.h.

STR_CONSTOL

#define STR_CONSTOL	(		name,
			s
	)		_STR_CONST16(name, 0x82u, s)

Declare a named other-encoding string constant with a compile-time length (STR_LEN16, < 65535 bytes).

Definition at line 155 of file strliteral.h.

STR_CONSTR

#define STR_CONSTR	(		name,
			s
	)		_STR_CONSTR8(name, 0xE1u, s)

Declare a named ASCII string constant for use with _SR() in static initializers (STR_LEN8, < 255 bytes).

Definition at line 159 of file strliteral.h.

STR_CONSTRL

#define STR_CONSTRL	(		name,
			s
	)		_STR_CONSTR16(name, 0xE2u, s)

Declare a named ASCII string constant for use with _SR() in static initializers (STR_LEN16, < 65535 bytes).

Definition at line 168 of file strliteral.h.

STR_CONSTRO

#define STR_CONSTRO	(		name,
			s
	)		_STR_CONSTR8(name, 0x81u, s)

Declare a named other-encoding string constant for use with _SR() in static initializers (STR_LEN8, < 255 bytes).

Definition at line 165 of file strliteral.h.

STR_CONSTROL

#define STR_CONSTROL	(		name,
			s
	)		_STR_CONSTR16(name, 0x82u, s)

Declare a named other-encoding string constant for use with _SR() in static initializers (STR_LEN16, < 65535 bytes).

Definition at line 174 of file strliteral.h.

STR_CONSTRU

#define STR_CONSTRU	(		name,
			s
	)		_STR_CONSTR8(name, 0xA1u, s)

Declare a named UTF-8 string constant for use with _SR() in static initializers (STR_LEN8, < 255 bytes).

Definition at line 162 of file strliteral.h.

STR_CONSTRUL

#define STR_CONSTRUL	(		name,
			s
	)		_STR_CONSTR16(name, 0xA2u, s)

Declare a named UTF-8 string constant for use with _SR() in static initializers (STR_LEN16, < 65535 bytes).

Definition at line 171 of file strliteral.h.