Throughout this chapter, we've been learning about exceptions. Exceptions allow a function to signal an error and immediately transfer control to an error handler, potentially far up the call stack.

However, exceptions come with their own set of trade-offs and, in some projects, are disabled entirely. This means it's important to be aware of some alternative approaches that we may want to use instead.

In C++23, the standard library introduced std::expected, a type specifically designed to formalize the "errors-as-values" pattern. This lets a function return either a successful result or an error, making the possibility of failure an explicit and unignorable part of the function's contract.

In this lesson, we'll explore why you might choose this errors-as-values pattern over exceptions, and how std::expected implements it.

Problems with Exceptions

Exceptions are a cornerstone of error handling in C++, but they have notable drawbacks:

Performance Overhead

Throwing and catching exceptions can be computationally expensive, particularly in performance-critical applications.

While modern C++ implementations minimize overhead when exceptions are not thrown, the cost is significant when they are, potentially impacting performance in tight loops or real-time systems

Complex Control Flow

Exceptions introduce non-local control flow, making it harder to predict where an error might be caught. This can complicate debugging and maintenance, as the code path jumps unexpectedly.

Restricted Environments

Some environments, such as embedded systems or real-time applications, prohibit exceptions due to resource constraints or the need for predictable execution. This necessitates alternative error-handling mechanisms.

Unclear Error Sources

Without explicit documentation, it's often unclear which exceptions a function might throw, leading to potential oversight in error handling.

Errors as Values

The main alternative to exceptions is a design pattern commonly called errors-as-values. Here, we just treat represent errors like we would any other value, such as an int. This method makes error handling explicit and local, which can keep things simple.

Returning Errors

Commonly, the errors-as-values approach involves returning error information as part of a function's return value. We've already seen a notable example of this: our main() function returns an exit code explaining why our program ended.

Returning 0 signals that our program exited normally, whilst any other returned value represents an error:

1int main() {
2  // ...
3  
4  // This is a value representing an error
5  return 1;
6}

We can replicate this same pattern in any function we might define:

1// Returns 0 if successful, or an error code otherwise
2int PerformTask() {
3  return 0;
4}

Then, if we document this behaviour such that anyone using our function is aware what this return value represents, they can check for errors and react as appropriate:

1if (PerformTask() != 0) {
2  // Something went wrong...
3}

A natural extension of this pattern is to attach further semantic meaning to which integer is returned, thereby allowing us to report different types of errors:

1// Returns 0 if successful, or an error code otherwise
2// Error Codes:
3// 1: Network Error
4// 2: Memory Error
5int PerformTask() {
6  if (NetworkUnavailable) return 1;
7  if (OutOfMemory) return 2;
8  // Do work...
9  return 0;
10}

However, using our return value for error-reporting has an obvious problem: what if also want the function to return a result when it succeeds in its task?

In some cases, we can work around this. For example, if our function would normally return a pointer, we can return a nullptr to indicate failure. If it's expected to return a positive number, returning 0 or a negative value can indicate an error.

However, there will be many other cases where there is no obvious return value that doesn't conflict with what could be a valid result. For example, a division function can return any number, so there's no direct way to signal an error using this technique:

1int Divide(int a, int b) {
2  if (b == 0) return 0;
3  return a / b;
4}

1// This is valid and will return 0
2Divide(0, 5);
3
4// This is invalid but will also return 0
5Divide(5, 0);

Returning Complex Types

The main way we solve this is by returning a more complex type that can contain both the result of the operation, and whether or not that action was successful.

For example, we might introduce a DivisionResult type, or just use something like a std::pair:

1struct DivisionResult {
2  int Result;
3  bool wasSuccessful;
4};
5
6DivisionResult Divide(int a, int b) {
7  if (b == 0) return {0, false};
8  return {a / b, true};
9}
10
11// Alternatively:
12std::pair<int, bool> Divide(int a, int b) {
13  if (b == 0) return {0, false};
14  return {a / b, true};
15}

1auto[Result, wasSuccessful]{Divide(0, 5)};

In C++23, std::expected was added to the standard library, which is a template type designed for this exact purpose.

Out Parameters

An alternative way to have a function "return" multiple things is to have it accept a non-const reference or pointer.

This pattern is sometimes called an output parameter or an "out parameter".

Below, our Divide() function returns a bool representing whether it was successful, and updates an int& that the caller provides with the result:

1bool Divide(int a, int b, int& Result) {
2  if (b == 0) return false;
3  Result = a / b;
4  return true;
5}

1int Result;
2if (Divide(10, 2, Result)) {
3  // Division was successful and Result
4  // has been updated to be 5
5}

There can be scenarios where this design is reasonable, but it generally makes the function less intuitive.

Using `std::expected`

C++23 introduces std::expected, a new standard type for error handling, inspired by functional programming and other languages. This has two main advantages over a custom type:

std::expected has already implemented functions and operators that are useful in this error-handling context. We'll cover them throughout this lesson
As a standard library utility, many developers will already know how it works. They don't need to examine some custom type (like DivisionResult) to understand how to use our function.

std::expected is a template with two template parameters:

The type of value that is used in the expected scenario (ie, when no error occurs)
The type we want to use to represent an error

So, a std::expected<T, E> always contains exactly one of two possibilities: the expected result of type T or an unexpected error of type E.

Let's update our Divide() function to return a std::expected<int, std::string>.

1#include <expected> 
2#include <string>
3
4using DivisionResult =
5  std::expected<int, std::string>;
6  
7DivisionResult Divide(int a, int b) {
8  // We'll implement this in the next section
9}

Conceptually, this means that Divide() will return an integer if it was successful but, if there was an error, it will return a string explaining why.

Handling Success

To handle the successful scenario, we can just return an integer in the normal way:

1#include <expected>
2#include <string>
3
4using DivisionResult =
5  std::expected<int, std::string>;
6  
7DivisionResult Divide(int a, int b) {
8  if (b == 0) {
9    // We'll handle the error state in
10    // the next section
11  }
12  return a / b;
13}

This works is because std::expected<T, E> has a constructor that accepts a T, making the happy path very simple to set up.

Handling Errors using `std::unexpected`

When something goes wrong, we need to return a std::expected in the error state. To do this, we can use the std::unexpected<ErrorType>() template.

In our Divide() example, the error type is a std::string, so we return a std::expected<std::string>:

1#include <expected>
2#include <string>
3
4using DivisionResult =
5  std::expected<int, std::string>;
6  
7DivisionResult Divide(int a, int b) {
8  if (b == 0) {
9    return std::unexpected<std::string>{     
10      "Cannot divide by zero" 
11    };                      
12  }
13  return a / b;
14}

In most cases, we can use class-template argument deduction (CTAD) to simplify this:

1#include <expected>
2#include <string>
3
4using DivisionResult =
5  std::expected<int, std::string>;
6  
7DivisionResult Divide(int a, int b) {
8  if (b == 0) {
9    return std::unexpected<std::string>{
10    return std::unexpected{
11      "Cannot divide by zero"
12    };
13  }
14  return a / b;
15}

Using the Same Value and Error Type

Behind the scenes, std::unexpected ensures our std::expected is created in the error state, regardless of what type we're using to represent errors.

One of the implications of this is that we can use the same type for both our values and errors. Below, our Divide() function continues to return an int in the happy case, but also uses an int in the unhappy case:

1#include <expected>
2
3using DivisionResult = std::expected<int, int>;
4  
5DivisionResult Divide(int a, int b) {
6  if (b == 0) {
7    return std::unexpected{0};
8  }
9  return a / b;
10}

This works because std::expected{SomeInt} and std::unexpected{SomeInt} return different values.

Checking for Success or Error

A std::expected provides multiple ways to check whether it contains a value or an error.

Using `has_value()`

The has_value() method returns true if the std::expected holds a T (i.e., the operation succeeded), or false if it holds an E ((i.e., the operation failed):

1#include <expected>
2#include <iostream>
3#include <string>
4
5using DivisionResult =
6  std::expected<int, std::string>;
7  
8DivisionResult Divide(int, int) {/*...*/}
17
18int main() {
19  DivisionResult ResultA{Divide(0, 5)};
20  if (ResultA.has_value()) {
21    std::cout << "0 / 5 Succeeded\n";
22  }
23
24  DivisionResult ResultB{Divide(5, 0)};
25  if (ResultB.has_value()) {
26    // Do stuff...
27  } else {
28    std::cout << "5 / 0 Failed\n";
29  }
30}

10 / 5 Succeeded
25 / 0 Failed

Using `operator bool`

There is a convenient conversion to bool, which is true when a value is present and false when it's an error. This allows a more succinct check:

1#include <expected>
2#include <iostream>
3#include <string>
4
5using DivisionResult =
6  std::expected<int, std::string>;
7  
8DivisionResult Divide(int, int) {/*...*/}
17
18int main() {
19  DivisionResult ResultA{Divide(0, 5)};
20  if (ResultA) {
21    std::cout << "0 / 5 Succeeded\n";
22  } else {
23    std::cout << "5 / 0 Failed\n";
24  }
25}

10 / 5 Succeeded

Preview

Unions

Behind the scenes, the std::expected template uses a union. Unions allow us to store one of multiple different data types within the same memory address. In the following example, our Number variable can store either a float, an int, or a double.

1#include <iostream>
2
3union Number {
4  int i;
5  float f;
6  double d;
7};
8
9int main() {
10  Number Value;
11
12  // Update value to store an int:
13  Value.i = 42;
14  std::cout << Value.i << '\n';
15
16  // And now a double:
17  Value.d = 9.8;
18  std::cout << Value.d;
19}

142
29.8

This example probably looks very similar to how we'd use a struct with three members - an int, a float, and a double. The key difference of a union is that it only store one of those values at any given time - not all three.

Behind the scenes, our i, f, and d members all point to the same memory address, and our Value variable's overall size is matches the size of the largest data type in our union (which is double, in this example)

By default, C++ unions do not keep track which type they are currently storing. This design maximises performance, but makes unions quite dangerous to use.

If we expected our value to currently contain an int, but it was actually a double, the compiler cannot detect our mistake - we just have a bug:

1#include <iostream>
2
3union Number {
4  int i;
5  float f;
6  double d;
7};
8
9int main() {
10  Number Value;
11  
12  Value.d = 9.8;
13  
14  // Union is currently storing a double,
15  // but this code thinks it's an int
16  std::cout << Value.i; 
17}

1-1717986918

In the std::expected<T, E> case, the union stores either a T or an E.

Additionally, std::expected<T, E> introduces a layer of safety by storing an additional variable to keep track of what type is currently stored in the union - that is, whether it is currently storing a T or an E. This internal value is what makes the has_value() method and the bool conversion work as expected.

This design pattern of combining a union with an additional variable to remember what type it's currently storing is sometimes called a tagged union, a discriminated union, or a variant.

We cover unions and the standard library's implementation of generic variants in a dedicated lesson later in the course:

Accessing the Value

After confirming our std::expected has a value using the has_value() or bool conversion, there are a few ways we can access that value:

`value()`

The value() method returns the value stored in the std::expected.

In almost all scenarios, we should only use this method if we're sure the std::expected contains a value. Therefore, it will typically be used within a conditional block:

1#include <expected>
2#include <iostream>
3#include <string>
4
5using DivisionResult =
6  std::expected<int, std::string>;
7
8DivisionResult Divide(int, int) {/*...*/}
17
18int main() {
19  DivisionResult Result{Divide(10, 2)};
20  if (Result) {
21    std::cout << "10 / 2 Succeeded: "
22      << Result.value(); 
23  }
24}

110 / 2 Succeeded: 5

The value() method throws an exception if the std::expected was in the error state. We cover this exception in a later section.

`value_or()`

In many cases when working with std::expected, the value_or() method gives us an elegant way to implement our logic, removing the need for conditional checks.

If a std::expected contains a value, value_or() will return that value. Otherwise, it will return the value we passed as an argument.

Below, Result will use the value from our Divide() function if the division was successful, or the value 1 otherwise:

1#include <expected>
2#include <iostream>
3#include <string>
4
5using DivisionResult =
6  std::expected<int, std::string>;
7
8DivisionResult Divide(int, int) {/*...*/}
17
18int main() {
19  int Result{Divide(10, 0).value_or(1)};
20  std::cout << "Using Value: " << Result;
21}

`operator*`

The * operator is a succinct alternative to the value() method:

1#include <expected>
2#include <iostream>
3#include <string>
4
5using DivisionResult =
6  std::expected<int, std::string>;
7
8DivisionResult Divide(int, int) {/*...*/}
17
18int main() {
19  DivisionResult Result{Divide(10, 2)};
20  if (Result) {
21    std::cout << "10 / 2 Succeeded: "
22      << *Result; 
23  }
24}

Unlike value(), the * operator's behaviour is undefined if our std::expected does not contain a value. Therefore, we should only use the * operator when we're sure it will work.

`operator->`

If the std::expected contains a more complex object, we can combine the value() method (or the * operator) with the member access operator . using ->:

1#include <expected>
2#include <iostream>
3#include <string>
4
5struct Player {
6  std::string Name{"Anna"};
7};
8
9std::expected<Player, int> GetPlayer() {
10  return Player{};
11}
12
13int main() {
14  // Using class-template argument deduction
15  // Full type: std::expected<Player, int>
16  std::expected PlayerOne{GetPlayer()};
17
18  if (PlayerOne) {
19    std::cout << "Hello " << PlayerOne->Name;
20  }
21}

1Hello Anna

The -> operator's behavior is also undefined if the std::expected does not contain a value.

Accessing the Error Using `error()`

We can access an error value held by a std::expected using the error() function. We should only use this if we're sure the std::expected is holding an error, so this is generally going to be used within a conditional block:

1#include <expected>
2#include <iostream>
3#include <string>
4
5using DivisionResult =
6  std::expected<int, std::string>;
7
8DivisionResult Divide(int, int) {/*...*/}
17
18int main() {
19  DivisionResult Result{Divide(10, 0)};
20  if (Result) {
21    // ...
22  } else {
23    std::cout << "10 / 0 Failed: "
24      << Result.error();
25  }
26}

110 / 0 Failed: Cannot divide by zero

The `error_or()` Function

The value_or() function's less useful sibling error_or() is also available. If the std::expected is in the error state, it will return the error value. Otherwise, it will return the value we passed as an argument to error_or():

1#include <expected>
2#include <iostream>
3#include <string>
4
5using DivisionResult =
6  std::expected<int, std::string>;
7
8DivisionResult Divide(int, int) {/*...*/}
18
19int main() {
20  DivisionResult ResultA{Divide(10, 2)};
21  std::cout << "Division Outcome: "
22    << ResultA.error_or("Success");
23
24  DivisionResult ResultB{Divide(10, 0)};
25  std::cout << "\nDivision Outcome: "
26    << ResultB.error_or("Success");
27}

1Division Outcome: Success
2Division Outcome: Cannot divide by zero

Recommendation

Error Types

We're representing errors using strings for simplicity in these examples but, in the real world, strings are rarely a good type for errors. The main reason for this is that it makes distinguishing between different error categories inefficient and prone to bugs.

Strings are slow to compare and, if we update the wording on our string, our logic will break without any compilation error to warn us:

1#include <expected>
2#include <string>
3
4std::expected<int, std::string> PerformTask() {
5  bool NetworkAvailable{false};
6  bool MemoryAvailable{true};
7  if (!NetworkAvailable) {
8    return std::unexpected{"Network Unavailable"};
9  }
10  if (!MemoryAvailable) {
11    return std::unexpected{"Out of Memory"};
12  }
13
14  // Do work...
15
16  return 42;
17}
18
19int main() {
20  std::expected Result{PerformTask()};
21  if (!Result) {
22    // Wording mismatch - this is never true
23    if (Result.error() == "Network Down") {
24      // Try to reconnect...
25    }
26  }
27}

For simple cases, an enum is generally more appropriate:

1#include <expected>
2#include <string>
3
4enum ErrorType{NetworkDown, OutOfMemory};
5std::expected<int, ErrorType> PerformTask() {
6  bool NetworkAvailable{false};
7  bool MemoryAvailable{true};
8  if (!NetworkAvailable) {
9    return std::unexpected{NetworkDown};
10  }
11  if (!MemoryAvailable) {
12    return std::unexpected{OutOfMemory};
13  }
14
15  // Do work...
16
17  return 42;
18}
19
20int main() {
21  std::expected Result{PerformTask()};
22  if (!Result) {
23    if (Result.error() == NetworkDown) {
24      // Try to reconnect...
25    }
26  }
27}

In complex cases, we can introduce dedicated error types that contains whatever information we think might be useful to the caller:

1#include <expected>
2#include <iostream>
3#include <string>
4
5enum ErrorType{NetworkDown, OutOfMemory};
6struct TaskError {
7  ErrorType Category;
8  std::string Reason;
9};
10
11std::expected<int, TaskError> PerformTask() {
12  bool NetworkAvailable{false};
13  bool MemoryAvailable{true};
14  if (!NetworkAvailable) {
15    return std::unexpected<TaskError>{{
16      NetworkDown, "Dog chewed the cable"
17    }};
18  }
19  if (!MemoryAvailable) {
20    return std::unexpected<TaskError>{{
21      OutOfMemory, "Computer sucks"
22    }};
23  }
24
25  // Do work...
26
27  return 42;
28}
29
30int main() {
31  std::expected Result{PerformTask()};
32  if (!Result) {
33    auto [Category, Reason]{Result.error()};
34    if (Category == NetworkDown) {
35      std::cout << "Network is down: " << Reason;
36      // Try to reconnect...
37    }
38  }
39}

1Network is down: Dog chewed the cable

Equality Comparisons

The std::expected type also implements the basic equality operator, ==, in several different forms.

The most useful form of this involves comparing a std::expected to an expected value - ie, comparing a std::expected<T, E> to a T:

1#include <expected>
2#include <iostream>
3#include <string>
4
5using DivisionResult =
6  std::expected<int, std::string>;
7
8DivisionResult Divide(int, int) {/*...*/}
17
18int main() {
19  DivisionResult ResultA{Divide(10, 2)};
20  if (ResultA == 5) {  
21    std::cout << "That's a 5\n";
22  }
23}

1That's a 5

We can use the same technique to directly check for specific errors by constructing a std::unexpected:

1#include <expected>
2#include <iostream>
3
4enum ErrorType { NetworkDown, OutOfMemory };
5
6std::expected<int, ErrorType> PerformTask() {/*...*/}
21
22int main() {
23  std::expected Result{PerformTask()};
24  if (Result == std::unexpected{NetworkDown}) {
25    std::cout << "Network error!";
26  }
27}

1Network error!

We can also use the != operator in the expected way:

1#include <expected>
2#include <iostream>
3
4enum ErrorType { NetworkDown, OutOfMemory };
5
6std::expected<int, ErrorType> PerformTask() {
7  bool NetworkAvailable{false};
8  bool MemoryAvailable{true};
9  if (!NetworkAvailable) {
10    return std::unexpected{NetworkDown};
11  }
12  if (!MemoryAvailable) {
13    return std::unexpected{OutOfMemory};
14  }
15
16  // Do work...
17
18  return 42;
19}
20
21int main() {
22  std::expected Result{PerformTask()};
23  if (Result != 42) {
24    std::cout << "It's not 42\n";
25  }
26
27  if (Result != std::unexpected{OutOfMemory}) {
28    std::cout << "Memory seems fine";
29  }
30}

1It's not 42
2Memory seems fine

Preview

Expression Rewriting

Technically, std::expected does not implement the != operator. It uses a capability added in C++20 called expression rewriting.

The idea is that an expression using the != instruction can be rewritten using the == operator to return a bool, and then the ! operator to invert that bool.

In other words, A != B can be rewritten as !(A == B) and, from C++20, compilers now do this automatically.

We can see this in action below:

1#include <iostream>
2
3struct MyType {
4  int Value;
5
6  bool operator==(const MyType& Other) const {
7    return Value == Other.Value;
8  }
9
10  // We don't have the != operator...
11  bool operator!=(const MyType& Other) const {
12    return Value != Other.Value;
13  }
14};
15
16int main() {
17  // ... but this works anyway
18  if (MyType{1} != MyType{2}) {
19    std::cout << "Those are not the same";
20  }
21}

1Those are not the same

We cover in a dedicated lesson later in the course.

Monadic Operations

The std::expected type comes with a set of monadic utility functions that allow chaining operations in a style that is popular from functional programming languages.

For example, we'll commonly want to perform some follow up action if our operation was successful - that is, if our std::expected is in the successful state.

Rather than implementing a verbose if check, we could use the and_then() method, providing the function we want to use as an argument.

Using `and_then()`

If the std::expected is in an error state, and_then() will simply return it. However, if it contains an expected value, our function will be invoked with the std::expected as an argument.

The function we provide should have two specific properties:

Our function should not modify the argument - as such, it can either receive it by value (ie, a copy) or by const reference
Monadic operations are designed to be "chainable" (which we'll see soon) so it should also return the std::expected for follow-up operations

The following program logs our division result if it was successful:

1#include <iostream>
2#include <expected>
3
4using DivisionResult =
5  std::expected<int, std::string>;
6
7DivisionResult Divide(int, int) {/*...*/}
16
17DivisionResult Log(const DivisionResult& x) {
18  std::cout << "Value: " << x.value() << '\n';
19  return x;
20}
21
22int main() {
23  // This will succeed and log:
24  Divide(10, 5).and_then(Log);
25  
26  // This will not:
27  Divide(10, 0).and_then(Log);
28}

1Value: 2

Using `or_else()`

The or_else() function is essentially the opposite of and_then(). We provide it with a function to be invoked if our std::expected is in the error state. Our function will be called with the error object, which is a std::string in our DivisionResult example.

Below, we add an and_then() invocation to our chain to set a fallback value if our division failed:

1#include <iostream>
2#include <expected>
3
4using DivisionResult =
5  std::expected<int, std::string>;
6
7DivisionResult Divide(int, int) {/*...*/}
16
17DivisionResult Log(DivisionResult) {/*...*/}
22
23DivisionResult GetDefaultValue(
24  const std::string& E
25) {
26  std::cout << E << " - Using Default Value\n";
27  
28  // Our return type is DivisionResult, so this is
29  // equivalent to return DivisionResult{1}
30  return 1;
31}
32
33int main() {
34  Divide(2, 0)
35    .or_else(GetDefaultValue)
36    .and_then(Log);
37}

1Cannot divide by zero - Using Default Value
2Value: 1

Using `transform()`

The transform() function can be used to modify the expected value, if the std::expected is in the successful state. It will call the function we provided, passing the current value as an argument, and updates the std::expected with the value we return.

Below, we use this to increment the value returned by our Divide() function, or the value returned by GetDefaultValue() if division failed:

1#include <expected>
2#include <iostream>
3
4using DivisionResult =
5  std::expected<int, std::string>;
6
7DivisionResult Divide(int, int) {/*...*/}
15
16DivisionResult Log(DivisionResult) {/*...*/}
21
22DivisionResult GetDefaultValue(std::string) {/*...*/}
28
29int Increment(int x) {
30  std::cout << "Incrementing\n";
31  return ++x;
32}
33
34int main() {
35  Divide(2, 0)
36    .or_else(GetDefaultValue)
37    .and_then(Log)
38    .transform(Increment)
39    .and_then(Log);
40}

1Cannot divide by zero - Using Default Value
2Value: 1
3Incrementing
4Value: 2

Using `transform_error()`

Finally, we have transform_error(). If our std::expected is in the error state, the function we provide will be invoked with that error as an argument. The return value will be used to update the error within the std::expected.

Below, we use this to modify our error string with an "Error: " prefix and a line break:

1#include <iostream>
2#include <expected>
3
4using DivisionResult =
5  std::expected<int, std::string>;
6
7DivisionResult Divide(int, int) {/*...*/}
16
17DivisionResult Log(DivisionResult) {/*...*/}
22
23DivisionResult GetDefaultValue(std::string) {/*...*/}
28
29int Increment(int x) {/*...*/}
34
35std::string FormatErrorMessage(
36  const std::string& E
37) {
38  return "Division Failed: " + E + '\n';
39}
40
41int main() {
42  Divide(2, 0)
43    .transform_error(FormatErrorMessage)
44    .or_else(GetDefaultValue)
45    .and_then(Log)
46    .transform(Increment)
47    .and_then(Log);
48}

1Division Failed: Cannot divide by zero
2 - Using Default Value
3Value: 1
4Incrementing
5Value: 2

Type Changes using `transform()` and `transform_error()`

Our previous examples are maintaining the expected type and error type throughout our pipeline, but that's not required.

The transform() and transform_error() functions can return a different type from their input, allowing us to build more complex data transformation pipelines.

Below, we add a Stringify() transformation, which converts our division result from a std::expected<int, std::string> to a std::expected<std::string, std::string>:

1#include <expected>
2#include <iostream>
3#include <string>
4
5using DivisionResult =
6  std::expected<int, std::string>;
7
8DivisionResult Divide(int, int) {/*...*/}
16
17DivisionResult GetDefaultValue(std::string) {/*...*/}
24
25
26std::string Stringify(int x) {
27  return std::to_string(x);
28}
29
30int main() {
31  std::string Result{
32    Divide(2, 0)
33      .or_else(GetDefaultValue)
34      .transform(Stringify)
35      // We're now dealing with a
36      // std::expected<std::string, std::string>
37      .value()
38  };
39
40  std::cout << "Result: " << Result;
41}

1Cannot divide by zero - Using Default Value
2Result: 1

Let's finish with a more complex example. Below, our pipeline starts with a std::expected<int, int> but ends with a std::expected<std::string, ErrorType>

1#include <expected>
2#include <iostream>
3#include <string>
4
5std::expected<int, int> DoWork() {
6  return std::unexpected{1};
7}
8
9enum class ErrorType { Unknown, NetworkError };
10
11ErrorType ImproveError(int ErrorCode) {
12  if (ErrorCode == 1) {
13    return ErrorType::NetworkError;
14  }
15  return ErrorType::Unknown;
16}
17
18std::expected<int, ErrorType> HandleError(
19  ErrorType E
20) {
21  if (E == ErrorType::NetworkError) {
22    // Reconnecting...
23  }
24
25  return 42;
26}
27
28std::string Stringify(int x) {
29  return std::to_string(x);
30}
31
32int main() {
33  std::string Result{DoWork()
34    // We have a expected<int, int>
35    .transform_error(ImproveError)
36    // Now we have expected<int, ErrorType>
37    .or_else(HandleError)
38    .transform(Stringify)
39    // Now we have expected<string, ErrorType>
40    .value()
41  };
42
43  std::cout << "Result: " << Result;
44}

Preview

Lambdas

Our previous examples are using function pointers to provide arguments for the monadic operations.

However, it is more common that lambdas be used in these scenarios. Lambdas provide a more succinct way to define small blocks of functional logic, right at the location where that logic is needed.

The following example deletes our GetDefaultValue() and Stringify() functions, and instead implements the same logic using lambda expressions as arguments to the or_else() and transform() functions:

1#include <expected>
2#include <iostream>
3#include <string>
4
5using DivisionResult =
6  std::expected<int, std::string>;
7
8DivisionResult Divide(int, int) {/*...*/}
16
17int main() {
18  std::string Result{Divide(2, 0)
19    .or_else([](const std::string& E){
20      return DivisionResult{1};
21    })
22    .transform([](int x){
23      return std::to_string(x);
24    }).value()
25  };
26
27  std::cout << "Result: " << Result;
28}

We have dedicated lessons on and later in the course.

Using `std::expected` with `void` Functions

For functions that perform an action without returning a value, we can still use std::expected for error reporting if we wish. We'd pass void as the first template parameter, as in std::expected<void, E>.

We can continue to use the bool conversion or has_value() to check if the operation was successful, and examine the error() value if it wasn't:

1#include <expected>
2#include <iostream>
3#include <string>
4
5std::expected<void, std::string> DoThing() {
6  bool Problems{true};
7  if (Problems) {
8    return std::unexpected{"Oh no"};
9  }
10
11  // Do work...
12}
13
14// Alternatively:
15std::expected<void, std::string> DoStuff() {
16  bool Problems{true};
17  if (!Problems) {
18    // Do work...
19    return {};
20  }
21
22  return std::unexpected{"Oh no"};
23}
24
25int main() {
26  std::expected Result{DoThing()};
27  if (!Result) { std::cout << Result.error(); }
28}

1Oh no

The `std::bad_expected_access` Exception

If we're using std::unexpected in a program that is also using exceptions, we can call value() without necessarily checking if the std::expected has a value.

If it doesn't, a std::bad_expected_access exception is thrown, which can be caught and handled like any other exception.

This is a template type where the template parameter corresponds to the error type of the associated std::expected.

So, for example, if we were calling value() on a std::expected<int, std::string>, then the exception that will be thrown is a std::bad_expected_access<std::string>.

We can access the error object - the std::string in this case - using the error() method on the exception:

1#include <expected>
2#include <iostream>
3#include <string>
4
5std::expected<int, std::string> DoThing() {
6  return std::unexpected{"Oh no"};
7}
8
9int main() {
10  try {
11    DoThing().value();
12  } catch (
13    std::bad_expected_access<std::string>& E
14  ) {
15    std::cout << E.what() << ": " << E.error();
16  }
17}

1Bad expected access: Oh no

Summary

In this lesson, we explored std::expected, a C++23 utility for returning either an expected value or an unexpected error. This "errors-as-values" approach provides an explicit, local, and often more performant alternative to traditional exception handling.

We saw how to create, check, and access the contents of a std::expected, and how to use its monadic operations to chain functions cleanly.

Key Takeaways:

std::expected<T, E> holds either a value of type T or an error of type E.
Return a successful value directly, such as return 42;, and an error using std::unexpected, such as return std::unexpected{"error"};.
Check for a value using a bool conversion like if (result) or the result.has_value() method.
Access the value with value(), *, or ->. Access the error with error().
Use value_or() to provide a fallback value if an error occurred.
Chain operations on std::expected objects using monadic functions like and_then(), or_else(), and transform().

Errors as Values and `std::expected`

Problems with Exceptions

Performance Overhead

Complex Control Flow

Restricted Environments

Unclear Error Sources

Errors as Values

Returning Errors

Returning Complex Types

Using `std::expected`

Handling Success

Handling Errors using `std::unexpected`

Checking for Success or Error

Using `has_value()`

Using `operator bool`

Accessing the Value

`value()`

`value_or()`

`operator*`

`operator->`

Accessing the Error Using `error()`

The `error_or()` Function

Equality Comparisons

Monadic Operations

Using `and_then()`

Using `or_else()`

Using `transform()`

Using `transform_error()`

Type Changes using `transform()` and `transform_error()`

Using `std::expected` with `void` Functions

The `std::bad_expected_access` Exception

Summary

Static Arrays using `std::array`

Professional C++

Errors as Values and std::expected

Problems with Exceptions

Performance Overhead

Complex Control Flow

Restricted Environments

Unclear Error Sources

Errors as Values

Returning Errors

Returning Complex Types

Using std::expected

Handling Success

Handling Errors using std::unexpected

Checking for Success or Error

Using has_value()

Using operator bool

Accessing the Value

value()

value_or()

operator*

operator->

Accessing the Error Using error()

The error_or() Function

Equality Comparisons

Monadic Operations

Using and_then()

Using or_else()

Using transform()

Using transform_error()

Type Changes using transform() and transform_error()

Using std::expected with void Functions

The std::bad_expected_access Exception

Summary

Static Arrays using std::array

Errors as Values and `std::expected`

Using `std::expected`

Handling Errors using `std::unexpected`

Using `has_value()`

Using `operator bool`

`value()`

`value_or()`

`operator*`

`operator->`

Accessing the Error Using `error()`

The `error_or()` Function

Using `and_then()`

Using `or_else()`

Using `transform()`

Using `transform_error()`

Type Changes using `transform()` and `transform_error()`

Using `std::expected` with `void` Functions

The `std::bad_expected_access` Exception

Static Arrays using `std::array`