命名空间
变体
操作

用户定义文字 (从 C++11 开始)

来自 cppreference.com
< cpp‎ | 语言
 
 
C++ 语言
 
 

允许通过定义用户定义的后缀,将整数、浮点数、字符和字符串文字生成用户定义类型的对象。

内容

[编辑] 语法

用户定义文字是以下任何形式的表达式

十进制文字 ud-后缀 (1)
八进制文字 ud-后缀 (2)
十六进制文字 ud-后缀 (3)
二进制文字 ud-后缀 (4)
小数部分 指数部分 (可选) ud-后缀 (5)
数字序列 指数部分 ud-后缀 (6)
字符文字 ud-后缀 (7)
字符串文字 ud-后缀 (8)
1-4) 用户定义的整数文字,例如 12_km
5-6) 用户定义的浮点文字,例如 0.5_Pa
7) 用户定义的字符文字,例如 'c'_X
8) 用户定义的字符串文字,例如 "abd"_Lu"xyz"_M
十进制文字 - 整数文字 中相同,一个非零十进制数字后跟零个或多个十进制数字
八进制文字 - 整数文字 中相同,一个零后跟零个或多个八进制数字
十六进制文字 - 整数文字 中相同,0x0X 后跟一个或多个十六进制数字
二进制文字 - 整数文字 中相同,0b0B 后跟一个或多个二进制数字
数字序列 - 浮点文字 中相同,一个十进制数字序列
小数部分 - 浮点文字 中相同,要么是 数字序列 后面跟着一个点 (123.),要么是一个可选的 数字序列 后面跟着一个点和另一个 数字序列 (1.0.12)
指数部分 - 浮点文字 中相同,字母 e 或字母 E 后面跟着可选的符号,后面跟着 数字序列
字符文字 - 字符文字 中相同
字符串文字 - 字符串文字 中相同,包括原始字符串文字
ud 后缀 - 一个标识符,由一个 *文字运算符* 或 *文字运算符模板* 声明引入(见 下文

整数浮点 数字序列中,在任意两个数字之间允许使用可选的间隔符 '

(自 C++14 起)

如果一个标记匹配用户定义的文字语法和常规文字语法,则假定它是一个常规文字(即,不可能重载 123LL 中的 LL)。

当编译器遇到带有 ud 后缀 X 的用户定义文字时,它会执行 非限定名称查找,查找名为 operator""X 的函数。如果查找没有找到声明,程序将不合法。否则,

1) 对于用户定义的整数文字,
a) 如果重载集包括一个具有参数类型 unsigned long long 的文字运算符,则用户定义的文字表达式将被视为函数调用 operator ""X(n ULL),其中 n 是没有 ud 后缀 的文字;
b) 否则,重载集必须包含以下两者之一,但不能同时包含两者:原始文字运算符或数值文字运算符模板。如果重载集包含原始文字运算符,则用户定义的文字表达式将被视为函数调用 operator""X("n ")
c) 否则,如果重载集包含数值文字运算符模板,则用户定义的文字表达式将被视为函数调用 operator""X<'c1 ', 'c2 ', 'c3 '..., 'ck '>(),其中 c1..ckn 的各个字符,并且它们都来自 基本字符集
2) 对于用户定义的浮点文字,
a) 如果重载集包括一个具有参数类型 long double 的文字运算符,则用户定义的文字表达式将被视为函数调用 operator ""X(f  L),其中 f 是没有 ud 后缀 的文字;
b) 否则,重载集必须包含以下两者之一,但不能同时包含两者:原始文字运算符或数值文字运算符模板。如果重载集包含原始文字运算符,则用户定义的文字表达式将被视为函数调用 operator ""X("f  ")
c) 否则,如果重载集包含数值文字运算符模板,则用户定义的文字表达式将被视为函数调用 operator""X<'c1 ', 'c2 ', 'c3 '..., 'ck '>(),其中 c1..ckf 的各个字符,并且它们都来自 基本字符集
3) 对于用户定义的字符串文字,令 str 为没有 ud 后缀 的文字
a) 如果重载集包含一个字符串文字运算符模板,其非类型模板参数对于 str 来说是一个合法的模板参数,则用户定义的文字表达式将被视为函数调用 operator ""X<str>()
(自 C++20 起)
b) 否则,用户定义的文字表达式将被视为函数调用 operator ""X (str, len),其中 len 是字符串文字的长度,不包括终止空字符。
4) 对于用户定义的字符文字,用户定义的文字表达式将被视为函数调用 operator ""X(ch),其中 ch 是没有 ud 后缀 的文字。
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 中发生字符串文字连接时,用户定义的字符串文字也会连接,并且它们的 ud 后缀 在连接的目的上被忽略,但所有连接文字上只能出现一个后缀。

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)
}

[edit] 文字运算符

由用户定义文字调用的函数被称为 *文字运算符*(或者,如果它是一个模板,则称为 *文字运算符模板*)。它像任何其他 函数函数模板 一样在命名空间作用域内声明(它也可以是友元函数、函数模板的显式实例化或特化,或由 using 声明引入),但有以下限制

此函数的名称可以采用以下两种形式之一

operator "" 标识符 (1) (已弃用)
operator 用户定义的字符串文字 (2)
标识符 - 用于作为 ud 后缀标识符,用于调用此函数的用户定义文字
用户定义的字符串文字 - 字符序列 "" 后面跟着,没有空格,成为 ud 后缀 的字符序列
1) 声明一个文字运算符。
2) 声明一个文字运算符。此语法使得可以将语言关键字和 保留标识符 用作 ud 后缀,例如,来自头文件 <complex>operator ""if

ud 后缀 必须以下划线 _ 开头:不以下划线开头的后缀保留用于标准库提供的文字运算符。它也不能包含双下划线 __:此类后缀也已保留。

如果文字运算符是一个模板,它必须具有空参数列表,并且只能有一个模板参数,该参数必须是一个非类型模板参数包,其元素类型为 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) 带有此参数列表的文字运算符是 *原始文字运算符*,用作整数和浮点数用户定义文字的回退(参见上文)。
2) 带有这些参数列表的文字运算符是用户定义整数文字的首选文字运算符。
3) 带有这些参数列表的文字运算符是用户定义浮点数文字的首选文字运算符。
4-8) 带有这些参数列表的文字运算符由用户定义的字符文字调用。
9-13) 带有这些参数列表的文字运算符由用户定义的字符串文字调用。

默认参数 不允许。

C 语言链接 不允许。

除了上述限制之外,文字运算符和文字运算符模板是正常的函数(和函数模板),它们可以声明为内联或 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 起) eE 结尾,当后面跟着运算符 +- 时,必须在源代码中使用空格或括号与运算符隔开。

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.04s.count),导致编译失败。

功能测试宏 Std 功能
__cpp_user_defined_literals 200809L (C++11) 用户定义文字

[编辑] 关键字

运算符

[编辑] 示例

#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 中定义
表示纯虚数的 std::complex 文字。
(函数) [编辑]
在内联命名空间 std::literals::chrono_literals 中定义
表示小时的 std::chrono::duration 文字。
(函数) [编辑]
表示分钟的 std::chrono::duration 文字。
(函数) [编辑]
表示秒的 std::chrono::duration 文字。
(函数) [编辑]
表示毫秒的 std::chrono::duration 文字。
(函数) [编辑]
表示微秒的 std::chrono::duration 文字。
(函数) [编辑]
表示纳秒的 std::chrono::duration 文字。
(函数) [编辑]
表示特定年份的 std::chrono::year 文字。
(函数) [编辑]
表示一个月中的某一天的 std::chrono::day 文字。
(函数) [编辑]
在内联命名空间 std::literals::string_literals 中定义
将字符数组文字转换为 basic_string
(函数) [编辑]
在内联命名空间 std::literals::string_view_literals 中定义
创建字符数组文字的字符串视图。
(函数) [编辑]

[编辑] 缺陷报告

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

DR 应用于 已发布的行为 正确行为
CWG 1473 C++11 ""ud-suffix 之间的空格是
文字运算符声明中所需的
可选的
CWG 1479 C++11 文字运算符可以具有默认参数 禁止的
CWG 2521 C++11 operator"" _Bq 形成错误(没有诊断
需要)因为它使用保留标识符 _Bq
弃用文字运算符语法
""ud-suffix 之间的空格