用户自定义字面量 (自 C++11 起)

 

C++

编译器支持

独立式和宿主式

语言

标准库

标准库头文件

具名要求

特性测试宏 (C++20)

语言支持库

概念库 (C++20)

诊断库

内存管理库

元编程库 (C++11)

通用工具库

容器库

迭代器库

范围库 (C++20)

算法库

字符串库

文本处理库

数值库

日期和时间库

输入/输出库

文件系统库 (C++17)

并发支持库 (C++11)

执行控制库 (C++26)

技术规范

符号索引

外部库

 

C++ 语言

通用主题
预处理器 注释	关键字 转义序列
流程控制
条件执行语句
if	switch
迭代语句（循环）
for 范围 for (C++11)	while do-while
跳转语句
continue - break	goto - return
函数
函数声明
Lambda 函数表达式
inline 说明符
动态异常规范 (直到 C++17*)
noexcept 说明符 (C++11)
异常
throw 表达式 try 块	catch 处理程序
命名空间
命名空间声明	命名空间别名
类型
基本类型 枚举类型 函数类型	类/结构体类型 联合体类型
说明符
const/volatile decltype (C++11) auto (C++11)	constexpr (C++11) consteval (C++20) constinit (C++20)
存储期说明符
初始化
默认初始化 值初始化 零初始化 复制初始化 直接初始化	聚合初始化 列表初始化 (C++11)   常量初始化 引用初始化

表达式
值类别 求值顺序	运算符 运算符优先级
替用表示
字面量
布尔 - 整型 - 浮点
字符 - 字符串 - nullptr (C++11)
用户自定义 (C++11)
工具
属性 (C++11)
类型
typedef 声明
类型别名声明 (C++11)
转型
隐式转换 static_cast const_cast	显式转换 dynamic_cast reinterpret_cast
内存分配
new 表达式	delete 表达式
类
类声明 构造函数 this 指针	访问说明符 friend 说明符
类特有函数属性
虚函数 override 说明符 (C++11)   final 说明符 (C++11)	explicit (C++11) static
特殊成员函数
默认构造函数 复制构造函数 移动构造函数 (C++11)	复制赋值 移动赋值 (C++11) 析构函数
模板
类模板 函数模板	模板特化 形参包 (C++11)
杂项
内联汇编	C++ 历史

 

表达式

通用
值类别 求值顺序 常量表达式 主表达式	Lambda 表达式 (C++11) Requires 表达式 (C++20) 形参包索引表达式 (C++26) 潜在求值表达式
字面量
整数字面量 浮点字面量 布尔字面量 字符字面量	转义序列 字符串字面量 空指针字面量 (C++11) 用户自定义字面量 (C++11)
运算符
赋值运算符 递增和递减 算术运算符 逻辑运算符 比较运算符 成员访问运算符 其他运算符 new-表达式 delete-表达式 throw 表达式	alignof sizeof sizeof... (C++11) typeid noexcept (C++11) 折叠表达式 (C++17) 运算符的替用表示 优先级与结合性 运算符重载 默认比较 (C++20)
转换
隐式转换 显式转换 常用算术转换     用户自定义转换	const_cast static_cast dynamic_cast reinterpret_cast

 

允许通过定义用户自定义后缀，使整型、浮点型、字符及字符串字面量产出用户定义类型的对象。

语法

用户自定义字面量是下列形式的表达式之一

十进制字面量 用户定义后缀	(1)
八进制字面量 用户定义后缀	(2)
十六进制字面量 用户定义后缀	(3)
二进制字面量 用户定义后缀	(4)
小数常量 指数部分(可选) 用户定义后缀	(5)
数字序列 指数部分 用户定义后缀	(6)
字符字面量 用户定义后缀	(7)
字符串字面量 用户定义后缀	(8)

1-4) 用户自定义整数字面量，例如 12_km

5-6) 用户自定义浮点字面量，例如 0.5_Pa

7) 用户自定义字符字面量，例如 'c'_X

8) 用户自定义字符串字面量，例如 "abd"_L 或 u"xyz"_M

十进制字面量	-	与 整数字面量 中相同，一个非零十进制数字后随零或更多十进制数字
八进制字面量	-	与 整数字面量 中相同，一个零后随零或更多八进制数字
十六进制字面量	-	与 整数字面量 中相同，0x 或 0X 后随一或更多十六进制数字
二进制字面量	-	与 整数字面量 中相同，0b 或 0B 后随一或更多二进制数字
数字序列	-	与 浮点字面量 中相同，十进制数字的序列
小数常量	-	与 浮点字面量 中相同，要么是一个后随点号 (123.) 的 数字序列，要么是一个可选的 数字序列 后随点号和另一个 数字序列 (1.0 或 .12)
指数部分	-	与 浮点字面量 中相同，字母 e 或字母 E 后随可选的符号，后随 数字序列
字符字面量	-	与 字符字面量 中相同
字符串字面量	-	与 字符串字面量 中相同，包含原始字符串字面量
用户定义后缀	-	一个标识符，由字面量运算符或字面量运算符模板声明引入（见下文 字面量运算符）

在 整型 和 浮点 数字序列中，可选分隔符 ' 允许在任意两个数字之间。

(自 C++14 起)

如果记号同时匹配用户自定义字面量语法和常规字面量语法，则假定它是常规字面量（即，不可能重载 123LL 中的 LL）。

当编译器遇到带有 用户定义后缀 X 的用户自定义字面量时，它执行非限定名查找，查找名为 operator""X 的函数。如果查找未找到声明，则程序是非良构的。否则，

1) 对于用户自定义整数字面量，

a) 如果重载集包含带有形参类型 unsigned long long 的字面量运算符，则用户自定义字面量表达式被视为函数调用 operator ""X(nULL)，其中 n 是不带 用户定义后缀 的字面量；

b) 否则，重载集必须包含原始字面量运算符或数值字面量运算符模板之一，但不能两者都包含。如果重载集包含原始字面量运算符，则用户自定义字面量表达式被视为函数调用 operator""X("n")；

c) 否则，如果重载集包含数值字面量运算符模板，则用户自定义字面量表达式被视为函数调用 operator""X<'c1', 'c2', 'c3'..., 'ck'>()，其中 c1..ck 是 n 的各个字符，且所有字符均来自 基本字符集。

2) 对于用户自定义浮点字面量，

a) 如果重载集包含带有形参类型 long double 的字面量运算符，则用户自定义字面量表达式被视为函数调用 operator ""X(fL)，其中 f 是不带 用户定义后缀 的字面量；

b) 否则，重载集必须包含原始字面量运算符或数值字面量运算符模板之一，但不能两者都包含。如果重载集包含原始字面量运算符，则用户自定义字面量表达式被视为函数调用 operator ""X("f")；

c) 否则，如果重载集包含数值字面量运算符模板，则用户自定义字面量表达式被视为函数调用 operator""X<'c1', 'c2', 'c3'..., 'ck'>()，其中 c1..ck 是 f 的各个字符，且所有字符均来自 基本字符集。

3) 对于用户自定义字符串字面量，设 str 为不带 用户定义后缀 的字面量

a) 如果重载集包含字符串字面量运算符模板，该模板带有非类型模板形参，且 str 是合式的模板实参，则用户自定义字面量表达式被视为函数调用 operator ""X<str>()；

(自 C++20 起)

b) 否则，用户自定义字面量表达式被视为函数调用 operator ""X (str, len)，其中 len 是字符串字面量的长度，不包含终止空字符。

4) 对于用户自定义字符字面量，用户自定义字面量表达式被视为函数调用 operator ""X(ch)，其中 ch 是不带 用户定义后缀 的字面量。

long double operator ""_w(long double);
std::string operator ""_w(const char16_t*, size_t);
unsigned    operator ""_w(const char*);
 
int main()
{
    1.2_w;    // calls operator ""_w(1.2L)
    u"one"_w; // calls operator ""_w(u"one", 3)
    12_w;     // calls operator ""_w("12")
    "two"_w;  // error: no applicable literal operator
}

当字符串字面量串联发生在翻译阶段 6 时，用户自定义字符串字面量也会被串联，并且它们的 用户定义后缀 在串联时被忽略，但所有串联的字面量中只能出现一个后缀

int main()
{
    L"A" "B" "C"_x;  // OK: same as L"ABC"_x
    "P"_x "Q" "R"_y; // error: two different ud-suffixes (_x and _y)
}

字面量运算符

由用户自定义字面量调用的函数被称为字面量运算符（或者，如果是模板，则称为字面量运算符模板）。它像任何其他函数或函数模板一样在命名空间作用域声明（它也可以是友元函数、函数模板的显式实例化或特化，或由 using 声明引入），但以下限制除外

此函数的名称可以具有以下两种形式之一

operator "" 标识符	(1)	（已弃用）
operator 用户定义字符串字面量	(2)

标识符	-	用作将调用此函数的用户自定义字面量的 用户定义后缀 的标识符
用户定义字符串字面量	-	字符序列 "" 后跟字符序列（不带空格），该字符序列将成为 用户定义后缀

1) 声明字面量运算符。

2) 声明字面量运算符。此语法使得可以使用语言关键字和保留标识符作为 用户定义后缀，例如，来自头文件 <complex> 的 operator ""if。

用户定义后缀 必须以下划线 _ 开头：不以下划线开头的后缀保留供标准库提供的字面量运算符使用。它也不能包含双下划线 __：此类后缀也保留。

如果字面量运算符是模板，则它必须具有空形参列表，并且只能有一个模板形参，该形参必须是元素类型为 char 的非类型模板形参包（在这种情况下，它被称为数值字面量运算符模板）

template<char...>
double operator ""_x();

或类类型的非类型模板形参（在这种情况下，它被称为字符串字面量运算符模板） struct A { constexpr A(const char*); };   template<A a> A operator ""_a();

(自 C++20 起)

字面量运算符只允许以下形参列表

( const char* )	(1)
( unsigned long long int )	(2)
( long double )	(3)
( char )	(4)
( wchar_t )	(5)
( char8_t )	(6)	(自 C++20 起)
( char16_t )	(7)
( char32_t )	(8)
( const char*, std::size_t )	(9)
( const wchar_t*, std::size_t )	(10)
( const char8_t*, std::size_t )	(11)	(自 C++20 起)
( const char16_t*, std::size_t )	(12)
( const char32_t*, std::size_t )	(13)

1) 带有此形参列表的字面量运算符是原始字面量运算符，用作整型和浮点用户自定义字面量的后备 (fallback) （见上文）

2) 带有这些形参列表的字面量运算符是用户自定义整数字面量的首选字面量运算符

3) 带有这些形参列表的字面量运算符是用户自定义浮点字面量的首选字面量运算符

4-8) 带有这些形参列表的字面量运算符由用户自定义字符字面量调用

9-13) 带有这些形参列表的字面量运算符由用户自定义字符串字面量调用

默认实参是不允许的。

C 语言连接是不允许的。

除了上述限制外，字面量运算符和字面量运算符模板是普通函数（和函数模板），它们可以声明为 inline 或 constexpr，它们可以具有内部或外部链接，它们可以显式调用，可以获取它们的地址，等等。

运行此代码

#include <string>
 
void        operator ""_km(long double); // OK, will be called for 1.0_km
void        operator "" _km(long double); // same as above, deprecated
std::string operator ""_i18n(const char*, std::size_t); // OK
 
template<char...>
double operator ""_pi(); // OK
float  operator ""_e(const char*); // OK
 
// error: suffix must begin with underscore
float operator ""Z(const char*);
 
// error: all names that begin with underscore followed by uppercase
// letter are reserved (NOTE: a space between "" and _).
double operator"" _Z(long double);
 
// OK. NOTE: no space between "" and _.
double operator""_Z(long double);
 
// OK: literal operators can be overloaded
double operator ""_Z(const char* args);
 
int main() {}

注解

自从引入用户自定义字面量以来，使用固定宽度整数类型的格式宏常量且在前面的字符串字面量后没有空格的代码变得无效：std::printf("%"PRId64"\n",INT64_MIN); 必须替换为 std::printf("%" PRId64"\n",INT64_MIN);。

由于最大匹配原则，以 p、P、(自 C++17 起) e 和 E 结尾的用户自定义整型和浮点字面量，当后跟运算符 + 或 - 时，必须在源代码中与运算符用空格或括号分隔

long double operator""_E(long double);
long double operator""_a(long double);
int operator""_p(unsigned long long);
 
auto x = 1.0_E+2.0;   // error
auto y = 1.0_a+2.0;   // OK
auto z = 1.0_E +2.0;  // OK
auto q = (1.0_E)+2.0; // OK
auto w = 1_p+2;       // error
auto u = 1_p +2;      // OK

点运算符后跟整型或浮点型用户自定义字面量的情况也相同

#include <chrono>
 
using namespace std::literals;
 
auto a = 4s.count();   // Error
auto b = 4s .count();  // OK
auto c = (4s).count(); // OK

否则，会形成单个无效的预处理数字记号（例如，1.0_E+2.0 或 4s.count），这会导致编译失败。

特性测试宏	值	Std	特性
__cpp_user_defined_literals	200809L	(C++11)	用户自定义字面量

关键字

operator

示例

运行此代码

#include <algorithm>
#include <cstddef>
#include <iostream>
#include <numbers>
#include <string>
 
// used as conversion from degrees (input param) to radians (returned output)
constexpr long double operator""_deg_to_rad(long double deg)
{
    long double radians = deg * std::numbers::pi_v<long double> / 180;
    return radians;
}
 
// used with custom type
struct mytype
{
    unsigned long long m;
};
 
constexpr mytype operator""_mytype(unsigned long long n)
{
    return mytype{n};
}
 
// used for side-effects
void operator""_print(const char* str)
{
    std::cout << str << '\n';
}
 
#if __cpp_nontype_template_args < 201911
 
std::string operator""_x2 (const char* str, std::size_t)
{
    return std::string{str} + str;
}
 
#else // C++20 string literal operator template
 
template<std::size_t N>
struct DoubleString
{
    char p[N + N - 1]{};
 
    constexpr DoubleString(char const(&pp)[N])
    {
        std::ranges::copy(pp, p);
        std::ranges::copy(pp, p + N - 1);
    }
};
 
template<DoubleString A>
constexpr auto operator""_x2()
{
    return A.p;
}
 
#endif // C++20
 
int main()
{
    double x_rad = 90.0_deg_to_rad;
    std::cout << std::fixed << x_rad << '\n';
 
    mytype y = 123_mytype;
    std::cout << y.m << '\n';
 
    0x123ABC_print;
    std::cout << "abc"_x2 << '\n';
}

输出

1.570796
123
0x123ABC
abcabc

标准库

以下字面量运算符在标准库中定义

定义于内联命名空间 std::literals::complex_literals
operator""ifoperator""ioperator""il (C++14)	表示纯虚数的 std::complex 字面量 (函数)
定义于内联命名空间 std::literals::chrono_literals
operator""h (C++14)	表示小时的 std::chrono::duration 字面量 (函数)
operator""min (C++14)	表示分钟的 std::chrono::duration 字面量 (函数)
operator""s (C++14)	表示秒的 std::chrono::duration 字面量 (函数)
operator""ms (C++14)	表示毫秒的 std::chrono::duration 字面量 (函数)
operator""us (C++14)	表示微秒的 std::chrono::duration 字面量 (函数)
operator""ns (C++14)	表示纳秒的 std::chrono::duration 字面量 (函数)
operator""y (C++20)	表示特定年份的 std::chrono::year 字面量 (函数)
operator""d (C++20)	表示月份中某日的 std::chrono::day 字面量 (函数)
定义于内联命名空间 std::literals::string_literals
operator""s (C++14)	将字符数组字面量转换为 basic_string (函数)
定义于内联命名空间 std::literals::string_view_literals
operator""sv (C++17)	创建字符数组字面量的字符串视图 (函数)

缺陷报告

以下行为变更缺陷报告被追溯应用于先前发布的 C++ 标准。

DR	应用于	已发布行为	正确行为
CWG 1473	C++11	"" 和 用户定义后缀 之间的空格在 字面量运算符的声明中是必需的	改为可选
CWG 1479	C++11	字面量运算符可以有默认参数	已禁止
CWG 2521	C++11	operator"" _Bq 是不合法的 (无需诊断 要求) 因为它使用了保留标识符 _Bq	废弃了字面量运算符语法 在 "" 和 ud-后缀 之间存在空格 的情况