User Defined Literals

1Distance += 3;

1Distance += 3_meters;
2Distance += 4_kilometers;
3Distance += 5_miles;

Some examples of user-defined literals include:

• 3_meters
• 3.14_radians
• "192.128.0.1"_ip

They all follow the same pattern - they have 3 components, in order:

• A value, e.g. 3, 3.14, or "192.128.0.1"
• An underscore, _
• A name, e.g. meters, radians, or ip

User-defined literals are, in effect, another way to call a function that we define.

The function that will be invoked by the 3_meters literal will have this syntax:

1#include <iostream>
2
3void operator""_meters(unsigned long long x){
4  std::cout << "Used _meters with arg: " << x;
5}
6
7int main(){
8  3_meters;
9}

1Used _meters with arg: 3

Let's break down the various components of this function.

Function Name

The name begins with operator"", followed by an underscore, and then the name we want to use for the literal. For example:

• 3_meters will invoke a function called operator""_meters
• 3.14_radians will invoke a function called operator""_radians
• "192.168.0.1"_ip will invoke a function called operator""_ip
• 'C'_grade will invoke a function called operator""_grade

Function Parameter Type

The value we have before the _ of the literal will be passed to the function as an argument. The only values we can support are specific types of integers, floating point numbers, characters, or strings. The types are:

• Integers - unsigned long long int
• Floats - long double
• Strings - const char*
• Characters - char

With const char* literals, we can include a second function parameter, which receives the length of the string:

1#include <iostream>
2
3void operator""_ip(const char* x, size_t size) {
4  std::cout << "Called _ip with a string"
5    " of size: " << size;
6}
7
8int main() {
9  "192.168.0.1"_ip;
10}

1Called _ip with a string of size: 11

Even though the integer must be unsigned, we can still use the negation operator -. We'll discuss this later in this lesson.

There are additional options for wide characters and wide strings. We'll discuss wide characters and strings in the next chapter.

Function Return Type and Body

We are free to return any type from our user-defined literal functions, including custom types

Similarly, we are free to implement the function body in whatever way we want

The most common use case for user-defined literals is to handle conversions. We already saw examples of this in the chrono literals, which gave us time-based literals like 3d, 5h, and 20min.

We can implement similar literals in our code - for example, we could implement literals to give us a descriptive syntax for weights, currencies, or distances.

The following example demonstrates literals for converting distances to meters:

1#include <iostream>
2
3float operator""_mm(long double D){
4  return D / 1000;
5}
6
7float operator""_cm(long double D){
8  return D / 100;
9}
10
11float operator""_in(long double D){
12  return D / 39.37;
13}
14
15float operator""_ft(long double D){
16  return D / 3.28;
17}
18
19float operator""_m(long double D){
20  return D;
21}
22
23float operator""_km(long double D){
24  return D * 1000;
25}
26
27int main(){
28  float Distance{3.0_m};
29
30  std::cout << "Distance: " << Distance <<
31    " meters";
32
33  Distance += 2.0_ft;
34  std::cout << "\nDistance: " << Distance <<
35    " meters";
36}

1Distance: 3 meters
2Distance: 3.60976 meters

Literals are typically defined in an external file, which is globally available across our project. As part of this, it's often sensible to wrap them in a namespace, to prevent naming conflicts:

1namespace distance_literals{
2  float operator""_mm(long double D){
3    return D / 1000;
4  }
5
6  // ...
7}

We can then implement a using namespace statement anywhere we need to use our literals:

1int main(){
2  using namespace distance_literals;
3  float Distance{3.0_mm};
4}

We are not restricted to returning built-in types from our literals. We can return any type we want. The following examples return a custom Distance type, which has overloaded the << operator:

1#include <iostream>
2
3class Distance {
4public:
5  Distance(float Value) : Value{Value}{}
6  float Value;
7};
8
9std::ostream& operator<<(
10  std::ostream& Stream,
11  Distance D
12){
13  Stream << D.Value << " meters\n";
14  return Stream;
15}
16
17Distance operator""_meters(long double D){
18  return Distance{float(D)};
19}
20
21Distance operator""_kilometers(long double D){
22  return Distance{float(D * 1000)};
23}
24
25Distance operator""_miles(long double D){
26  return Distance{float(D * 1609)};
27}
28
29int main(){
30  std::cout << 4.2_meters;
31  std::cout << 0.4_kilometers;
32  std::cout << 0.1_miles;
33}

14.2 meters
2400 meters
3160.9 meters

Even though the values passed to our literal functions must be positive, we can still use the - operator:

1-0.1_miles

However, it's important to understand what is going on here. The - operator has lower precedence than the user-defined literal.

That means that our literal function is called with the positive value. Then, the negation operator is applied to the value that is returned from that function:

1#include <iostream>
2
3class Distance {
4public:
5  Distance(float Value) : Value{Value}{}
6
7  Distance operator-(){
8    std::cout << "Negating\n";
9    return Distance{-Value};
10  }
11
12  float Value;
13};
14
15Distance operator""_miles(long double D){
16  return Distance{float(D * 1609)};
17}
18
19int main(){
20  std::cout << (-0.1_miles).Value << " meters";
21}

1Negating
2-160.9 meters

This has a few implications. Most notably, it means the type returned must support the unary - operator. But also, we need to be mindful of the order of operations, particularly when dealing with conversions.

This order of operations still returns the correct values for distances, for example, but it would not work for temperatures. 10 degrees Celsius is 50 degrees Fahrenheit, but -10 degrees Celsius is not -50 degrees Fahrenheit.

Therefore, our hypothetical temperature implementation would need a little more thought to ensure conversions are respectful of this order of operations.

When we first learn about user-defined literals, many are tempted to overuse them. The ability to define our syntax to match our exact needs is tempting, but it can be overused.

For example, we could construct a custom Player object with a user-defined literal:

1"Legolas"_player;

We could even allow multiple arguments in a string, and then parse them out within our function or class:

1"Legolas,Elf,100"_player;

But, just because we can do something, doesn't mean we should. Techniques like this don't save many keystrokes and are less clear than calling a constructor the regular way:

1Player{"Legolas"};
2Player{"Legolas", Race::Elf, 100};

This way also provides more help from our tooling. As soon as our IDE recognizes what class we're constructing, it can jump in and assist us by telling us what arguments we need. And, if we get it wrong, the compiler will throw an error at the exact location where we're passing an invalid argument.

User-defined literals are a powerful way to make our code more expressive, but in almost all programs, we should be highly selective in where we deploy them.

User-defined literals enhance code expressiveness and readability, enabling us to create more intuitive APIs.

Key Learnings

• The syntax and structure of user-defined literals, including the use of the underscore and the naming conventions enforced by the C++ standard.
• How to create user-defined literals using the operator"" syntax, and the specific argument types supported, most notably unsigned long long, long double, char, and const char*.
• The importance of using the underscore in user-defined literals to avoid conflicts, differentiating them from standard library literals.
• Like any function, user-defined literals can return values by specifying a return type in the signature and using the return statement within the body.
• The common use case of user-defined literals for unit conversions, such as distances and currencies.
• The practice of defining user-defined literals within namespaces to prevent naming conflicts and enhance code organization.
• The consideration of operator precedence, especially in the context of negative numbers, and how it impacts the behavior and implementation of user-defined literals.
• The caution against overuse of user-defined literals to maintain code readability and leverage the benefits of tooling support and compiler checks.