User-defined literals (since C++11)

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

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 overload LL in 123LL).

When the compiler encounters a user-defined literal with ud-suffix X, it performs unqualified name lookup, looking for a function with the name operator "" X. If the lookup does not find a declaration, the program is ill-formed. Otherwise,

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
}

When string literal concatenation takes place in translation phase 6, user-defined string literals are concatenated as well, and their ud-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)
}

Literal operators

The function called by a user-defined literal is known as literal operator (or, if it's a template, literal operator template). It is declared just like any other function or function 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:

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 non-type template parameter pack with element type char (in which case it is known as a numeric literal operator template).

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

struct A { A(const char *); auto operator<=>(const A&) const = default; };
 
template<A a> A operator ""_a();

Only the following parameter lists are allowed on literal operators :

Default arguments are not allowed.

C language 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.

void operator "" _km(long double); // OK, will be called for 1.0_km
std::string operator "" _i18n(const char*, std::size_t); // OK
template <char...> double operator "" _π(); // OK
float operator ""_e(const char*); // OK
 
float operator ""Z(const char*); // error: suffix must begin with underscore
double operator"" _Z(long double); // error: all names that begin with underscore
                                   // followed by uppercase letter are reserved
double operator""_Z(long double); // OK: even though _Z is reserved ""_Z is allowed

Notes

Since the introduction of user-defined literals, the code that uses format 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 by std::printf("%" PRId64"\n",INT64_MIN);

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

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

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

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

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

Examples

#include <iostream>
 
// used as conversion
constexpr long double operator"" _deg ( long double deg )
{
    return deg * 3.14159265358979323846264L / 180;
}
 
// 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;
}
 
int main(){
    double x = 90.0_deg;
    std::cout << std::fixed << x << '\n';
    mytype y = 123_mytype;
    std::cout << y.m << '\n';
    0x123ABC_print;
}

1.570796
123
0x123ABC

Standard library

The following literal operators are defined in the standard library.