[lex.ext]

# 5 Lexical conventions [[lex]](./#lex)

## 5.13 Literals [[lex.literal]](lex.literal#lex.ext)

### 5.13.9 User-defined literals [lex.ext]

[user-defined-literal:](#nt:user-defined-literal "5.13.9 User-defined literals [lex.ext]")  
[*user-defined-integer-literal*](#nt:user-defined-integer-literal "5.13.9 User-defined literals [lex.ext]")  
[*user-defined-floating-point-literal*](#nt:user-defined-floating-point-literal "5.13.9 User-defined literals [lex.ext]")  
[*user-defined-string-literal*](#nt:user-defined-string-literal "5.13.9 User-defined literals [lex.ext]")  
[*user-defined-character-literal*](#nt:user-defined-character-literal "5.13.9 User-defined literals [lex.ext]")

[user-defined-integer-literal:](#nt:user-defined-integer-literal "5.13.9 User-defined literals [lex.ext]")  
[*decimal-literal*](lex.icon#nt:decimal-literal "5.13.2 Integer literals [lex.icon]") [*ud-suffix*](#nt:ud-suffix "5.13.9 User-defined literals [lex.ext]")  
[*octal-literal*](lex.icon#nt:octal-literal "5.13.2 Integer literals [lex.icon]") [*ud-suffix*](#nt:ud-suffix "5.13.9 User-defined literals [lex.ext]")  
[*hexadecimal-literal*](lex.icon#nt:hexadecimal-literal "5.13.2 Integer literals [lex.icon]") [*ud-suffix*](#nt:ud-suffix "5.13.9 User-defined literals [lex.ext]")  
[*binary-literal*](lex.icon#nt:binary-literal "5.13.2 Integer literals [lex.icon]") [*ud-suffix*](#nt:ud-suffix "5.13.9 User-defined literals [lex.ext]")

[user-defined-floating-point-literal:](#nt:user-defined-floating-point-literal "5.13.9 User-defined literals [lex.ext]")  
[*fractional-constant*](lex.fcon#nt:fractional-constant "5.13.4 Floating-point literals [lex.fcon]") [*exponent-part*](lex.fcon#nt:exponent-part "5.13.4 Floating-point literals [lex.fcon]")opt [*ud-suffix*](#nt:ud-suffix "5.13.9 User-defined literals [lex.ext]")  
[*digit-sequence*](lex.fcon#nt:digit-sequence "5.13.4 Floating-point literals [lex.fcon]") [*exponent-part*](lex.fcon#nt:exponent-part "5.13.4 Floating-point literals [lex.fcon]") [*ud-suffix*](#nt:ud-suffix "5.13.9 User-defined literals [lex.ext]")  
[*hexadecimal-prefix*](lex.icon#nt:hexadecimal-prefix "5.13.2 Integer literals [lex.icon]") [*hexadecimal-fractional-constant*](lex.fcon#nt:hexadecimal-fractional-constant "5.13.4 Floating-point literals [lex.fcon]") [*binary-exponent-part*](lex.fcon#nt:binary-exponent-part "5.13.4 Floating-point literals [lex.fcon]") [*ud-suffix*](#nt:ud-suffix "5.13.9 User-defined literals [lex.ext]")  
[*hexadecimal-prefix*](lex.icon#nt:hexadecimal-prefix "5.13.2 Integer literals [lex.icon]") [*hexadecimal-digit-sequence*](lex.icon#nt:hexadecimal-digit-sequence "5.13.2 Integer literals [lex.icon]") [*binary-exponent-part*](lex.fcon#nt:binary-exponent-part "5.13.4 Floating-point literals [lex.fcon]") [*ud-suffix*](#nt:ud-suffix "5.13.9 User-defined literals [lex.ext]")

[user-defined-string-literal:](#nt:user-defined-string-literal "5.13.9 User-defined literals [lex.ext]")  
[*string-literal*](lex.string#nt:string-literal "5.13.5 String literals [lex.string]") [*ud-suffix*](#nt:ud-suffix "5.13.9 User-defined literals [lex.ext]")

[user-defined-character-literal:](#nt:user-defined-character-literal "5.13.9 User-defined literals [lex.ext]")  
[*character-literal*](lex.ccon#nt:character-literal "5.13.3 Character literals [lex.ccon]") [*ud-suffix*](#nt:ud-suffix "5.13.9 User-defined literals [lex.ext]")

[ud-suffix:](#nt:ud-suffix "5.13.9 User-defined literals [lex.ext]")  
[*identifier*](lex.name#nt:identifier "5.11 Identifiers [lex.name]")

[1](#1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/lex.tex#L2203)

If a token matches both [*user-defined-literal*](#nt:user-defined-literal "5.13.9 User-defined literals [lex.ext]") and another [*literal*](lex.literal.kinds#nt:literal "5.13.1 Kinds of literals [lex.literal.kinds]") kind, it
is treated as the latter[.](#1.sentence-1)

[*Example [1](#example-1)*:

123_km is a [*user-defined-literal*](#nt:user-defined-literal "5.13.9 User-defined literals [lex.ext]"), but 12LL is an[*integer-literal*](lex.icon#nt:integer-literal "5.13.2 Integer literals [lex.icon]")[.](#1.sentence-2)

— *end example*]

The syntactic non-terminal preceding the [*ud-suffix*](#nt:ud-suffix "5.13.9 User-defined literals [lex.ext]") in a[*user-defined-literal*](#nt:user-defined-literal "5.13.9 User-defined literals [lex.ext]") is taken to be the longest sequence of
characters that could match that non-terminal[.](#1.sentence-3)

[2](#2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/lex.tex#L2215)

A [*user-defined-literal*](#nt:user-defined-literal "5.13.9 User-defined literals [lex.ext]") is treated as a call to a literal operator or
literal operator template ([[over.literal]](over.literal "12.6 User-defined literals"))[.](#2.sentence-1)

To determine the form of this call for
a given [*user-defined-literal*](#nt:user-defined-literal "5.13.9 User-defined literals [lex.ext]") *L* with [*ud-suffix*](#nt:ud-suffix "5.13.9 User-defined literals [lex.ext]") *X*,
first let *S* be the set of declarations
found by unqualified lookup for the [*literal-operator-id*](over.literal#nt:literal-operator-id "12.6 User-defined literals [over.literal]") whose literal suffix identifier is *X* ([[basic.lookup.unqual]](basic.lookup.unqual "6.5.3 Unqualified name lookup"))[.](#2.sentence-2)

*S* shall not be empty[.](#2.sentence-3)

[3](#3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/lex.tex#L2226)

If *L* is a [*user-defined-integer-literal*](#nt:user-defined-integer-literal "5.13.9 User-defined literals [lex.ext]"), let *n* be the literal
without its [*ud-suffix*](#nt:ud-suffix "5.13.9 User-defined literals [lex.ext]")[.](#3.sentence-1)

If *S* contains a literal operator with
parameter type unsigned long long, the literal *L* is treated as a call of
the formoperator ""*X*(*n*ULL)

Otherwise, *S* shall contain a raw literal operator
or a numeric literal operator template ([[over.literal]](over.literal "12.6 User-defined literals")) but not both[.](#3.sentence-3)

If *S* contains a raw literal operator,
the literal *L* is treated as a call of the formoperator ""*X*("*n*")

Otherwise (*S* contains a numeric literal operator template),*L* is treated as a call of the formoperator ""*X*<'c1', 'c2', ... 'ck'>() where *n* is the source character sequence c1c2...ck[.](#3.sentence-5)

[*Note [1](#note-1)*:

The sequencec1c2...ck can only contain characters from the basic character set[.](#3.sentence-6)

— *end note*]

[4](#4)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/lex.tex#L2252)

If *L* is a [*user-defined-floating-point-literal*](#nt:user-defined-floating-point-literal "5.13.9 User-defined literals [lex.ext]"), let *f* be the
literal without its [*ud-suffix*](#nt:ud-suffix "5.13.9 User-defined literals [lex.ext]")[.](#4.sentence-1)

If *S* contains a literal operator
with parameter type long double, the literal *L* is treated as a call of
the formoperator ""*X*(*f*L)

Otherwise, *S* shall contain a raw literal operator
or a numeric literal operator template ([[over.literal]](over.literal "12.6 User-defined literals")) but not both[.](#4.sentence-3)

If *S* contains a raw literal operator,
the [*literal*](lex.literal.kinds#nt:literal "5.13.1 Kinds of literals [lex.literal.kinds]") *L* is treated as a call of the formoperator ""*X*("*f*")

Otherwise (*S* contains a numeric literal operator template),*L* is treated as a call of the formoperator ""*X*<'c1', 'c2', ... 'ck'>() where *f* is the source character sequence c1c2...ck[.](#4.sentence-5)

[*Note [2](#note-2)*:

The sequencec1c2...ck can only contain characters from the basic character set[.](#4.sentence-6)

— *end note*]

[5](#5)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/lex.tex#L2278)

If *L* is a [*user-defined-string-literal*](#nt:user-defined-string-literal "5.13.9 User-defined literals [lex.ext]"),
let *str* be the literal without its [*ud-suffix*](#nt:ud-suffix "5.13.9 User-defined literals [lex.ext]") and let *len* be the number of code units in *str* (i.e., its length excluding the terminating null character)[.](#5.sentence-1)

If *S* contains a literal operator template with
a constant template parameter for which *str* is
a well-formed [*template-argument*](temp.names#nt:template-argument "13.3 Names of template specializations [temp.names]"),
the literal *L* is treated as a call of the formoperator ""*X*<*str*>()

Otherwise, the literal *L* is treated as a call of the formoperator ""*X*(*str*, *len*)

[6](#6)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/lex.tex#L2295)

If *L* is a [*user-defined-character-literal*](#nt:user-defined-character-literal "5.13.9 User-defined literals [lex.ext]"), let *ch* be the
literal without its [*ud-suffix*](#nt:ud-suffix "5.13.9 User-defined literals [lex.ext]")[.](#6.sentence-1)

*S* shall contain a [literal operator](over.literal#def:literal,operator "12.6 User-defined literals [over.literal]") whose only parameter has
the type of *ch* and the
literal *L* is treated as a call
of the formoperator ""*X*(*ch*)

[7](#7)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/lex.tex#L2306)

[*Example [2](#example-2)*: long double operator ""_w(long double);
std::string operator ""_w(const char16_t*, std::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} — *end example*]

[8](#8)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/lex.tex#L2321)

In translation phase 6 ([[lex.phases]](lex.phases "5.2 Phases of translation")), adjacent [*string-literal*](lex.string#nt:string-literal "5.13.5 String literals [lex.string]")*s* are concatenated and[*user-defined-string-literal*](#nt:user-defined-string-literal "5.13.9 User-defined literals [lex.ext]")*s* are considered [*string-literal*](lex.string#nt:string-literal "5.13.5 String literals [lex.string]")*s* for that
purpose[.](#8.sentence-1)

During concatenation, [*ud-suffix*](#nt:ud-suffix "5.13.9 User-defined literals [lex.ext]")es are removed and ignored and
the concatenation process occurs as described in [[lex.string]](lex.string "5.13.5 String literals")[.](#8.sentence-2)

At the end of phase
6, if a [*string-literal*](lex.string#nt:string-literal "5.13.5 String literals [lex.string]") is the result of a concatenation involving at least one[*user-defined-string-literal*](#nt:user-defined-string-literal "5.13.9 User-defined literals [lex.ext]"), all the participating[*user-defined-string-literal*](#nt:user-defined-string-literal "5.13.9 User-defined literals [lex.ext]")*s* shall have the same [*ud-suffix*](#nt:ud-suffix "5.13.9 User-defined literals [lex.ext]") and that suffix is applied to the result of the concatenation[.](#8.sentence-3)

[9](#9)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/lex.tex#L2331)

[*Example [3](#example-3)*: int main() {L"A" "B" "C"_x; // OK, same as L"ABC"_x"P"_x "Q" "R"_y; // error: two different [*ud-suffix*](#nt:ud-suffix "5.13.9 User-defined literals [lex.ext]")es} — *end example*]