User Defined Literals

As a general goal, we want our code to be descriptive. In the very first lesson, we discussed the importance of having descriptive identifiers - which include variables and function names. A variable called Health is more descriptive than one called x.

The idea of custom types takes that idea further. Types like Distance and Temperature are inherently more descriptive than types like int and float.

In this lesson, we’ll see how we can even make values more descriptive. In the following code, it’s clear we’re adding a value of 3 to a variable called Distance:

1Distance += 3;
2

But three what? Three centimeters? Three meters? Three kilometers?

With user-defined literals, we can be more expressive:

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

Behind the scenes, these literals are calling functions that we can define to meet our specific requirements. Let's see how we can set this up

Examples of User-Defined Literals

Some examples of user-defined literals could be:

• 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

Creating User-Defined Literals

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
3int operator""_meters(unsigned long long x){
4  std::cout << "Used _meters with arg: " << x;
5  return x;
6}
7
8int main(){
9  3_meters;
10}
11

1Used _meters with arg: 3
2

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 literals like 3_meters, the name of the function will be operator""_meters

For literals like 3.14_radians, the name of the function will be operator""_radians

For literals like "192.128.0.1"_ip, the name of the function will be operator""_ip

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
• Characters - char
• Strings - const char*

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

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

1Called _ip with a string of size: 11
2

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

There are additional options for so-called 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

Use Case: Conversions

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 if we need to deal with properties such as weights, currencies, or distances:

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){ return D; }
20
21float operator""_km(long double D){
22  return D * 1000;
23}
24
25int main(){
26  float Distance{3.0_m};
27
28  std::cout << "Distance: " << Distance <<
29    " meters";
30
31  Distance += 2.0_ft;
32  std::cout << "\nDistance: " << Distance <<
33    " meters";
34}
35

1Distance: 3 meters
2Distance: 3.60976 meters
3

User-Defined Literals in a Namespace

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}
8
9

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

Returning Custom Types from User-Defined Literals

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{static_cast<float>(D)};
19}
20
21Distance operator""_kilometers(long double D){
22  return Distance{static_cast<float>(D * 1000)};
23}
24
25Distance operator""_miles(long double D){
26  return Distance{static_cast<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}
34

14.2 meters
2400 meters
3160.9 meters
4

Negative Numbers and Precedence

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

1-0.1_miles
2

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{static_cast<float>(D * 1609)};
17}
18
19int main(){
20  std::cout << (-0.1_miles).Value << " meters";
21}
22

1Negating!
2-160.9 meters
3

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. A Temperature class would need a little more thought to ensure conversions between Fahrenheit and Celsius or Kelvin are respectful of this unusual order of operations.

Advice: Don’t Overuse User-Defined Literals

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

For example, we could construct a Character with a user-defined literal:

1"Legolas"_character;
2

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

1"Legolas,Elf,100"_character
2

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

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

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.