Allows integer, floating-point, character, and string literals to produce objects of user-defined type by defining a user-defined suffix.

[edit]Syntax

A user-defined literal is an expression of any of the following forms

If a token matches a user-defined literal syntax and a regular literal syntax, it is assumed to be a regular literal (that is, it's impossible to overloadLL in123LL).

When the compiler encounters a user-defined literal withud-suffixX, it performsunqualified name lookup, looking for a function with the nameoperator""X. If the lookup does not find a declaration, the program is ill-formed. Otherwise,

longdouble operator""_w(longdouble);std::string operator""_w(constchar16_t*, size_t);unsigned    operator""_w(constchar*); 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}

When string literal concatenation takes place intranslation phase 6, user-defined string literals are concatenated as well, and theirud-suffixes are ignored for the purpose of concatenation, except that only one suffix may appear on all concatenated literals:

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]Literal operators

The function called by a user-defined literal is known asliteral operator (or, if it's a template,literal operator template). It is declared just like any otherfunction orfunction template at namespace scope (it may also be a friend function, an explicit instantiation or specialization of a function template, or introduced by a using-declaration), except for the following restrictions:

The name of this function can have one of the two forms:

ud-suffix must begin with the underscore_: the suffixes that do not begin with the underscore are reserved for the literal operators provided by the standard library. It cannot contain double underscores__ as well: such suffixes are also reserved.

If the literal operator is a template, it must have an empty parameter list and can have only one template parameter, which must be a constant template parameter pack with element typechar (in which case it is known as anumeric literal operator template):

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

struct A{constexpr A(constchar*);}; template<A a>A operator""_a();

Only the following parameter lists are allowed on literal operators:

Default arguments are not allowed.

Clanguage linkage is not allowed.

Other than the restrictions above, literal operators and literal operator templates are normal functions (and function templates), they can be declared inline or constexpr, they may have internal or external linkage, they can be called explicitly, their addresses can be taken, etc.

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

[edit]Notes

Since the introduction of user-defined literals, the code that usesformat macro constants for fixed-width integer types with no space after the preceding string literal became invalid:std::printf("%"PRId64"\n",INT64_MIN); has to be replaced bystd::printf("%"PRId64"\n",INT64_MIN);.

Due tomaximal munch, user-defined integer and floating point literals ending inp,P,(since C++17)e andE, when followed by the operators+ or-, must be separated from the operator with whitespace or parentheses in the source:

longdouble operator""_E(longdouble);longdouble operator""_a(longdouble);int operator""_p(unsignedlonglong); auto x=1.0_E+2.0;// errorauto y=1.0_a+2.0;// OKauto z=1.0_E+2.0;// OKauto q=(1.0_E)+2.0;// OKauto w=1_p+2;// errorauto u=1_p+2;// OK

Same applies to dot operator following an integer or floating-point user-defined literal:

#include <chrono> usingnamespace std::literals; auto a= 4s.count();// Errorauto b= 4s .count();// OKauto c=(4s).count();// OK

Otherwise, a single invalid preprocessing number token (e.g.,1.0_E+2.0 or4s.count) is formed, which causes compilation to fail.

[edit]Keywords

operator

[edit]Examples

#include <algorithm>#include <cstddef>#include <iostream>#include <numbers>#include <string> // used as conversion from degrees (input param) to radians (returned output)constexprlongdouble operator""_deg_to_rad(longdouble deg){longdouble radians= deg*std::numbers::pi_v<longdouble>/180;return radians;} // used with custom typestruct mytype{unsignedlonglong m;}; constexpr mytype operator""_mytype(unsignedlonglong n){return mytype{n};} // used for side-effectsvoid operator""_print(constchar* str){std::cout<< str<<'\n';} #if __cpp_nontype_template_args < 201911 std::string operator""_x2(constchar* str,std::size_t){returnstd::string{str}+ str;} #else // C++20 string literal operator template template<std::size_t N>struct DoubleString{char p[N+ N-1]{}; constexpr DoubleString(charconst(&pp)[N]){        std::ranges::copy(pp, p);        std::ranges::copy(pp, p+ N-1);}}; template<DoubleString A>constexprauto 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.5707961230x123ABCabcabc

[edit]Standard library

The following literal operators are defined in the standard library:

[edit]Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

• In other languages

• Deutsch
• Español
• Français
• Italiano
• 日本語
• Português
• Русский
• 中文