C++ Library - <expected>

The <expected> header in C++, provides various functions and operations to handle the values or errors in a way that can express either the presence of an expected value or an unexpected error.

It is similar to std::optional but in addition, capability to store the information when an expected value is not present. This <expected> header is part of the general utility library.

Including <expected> Header

To include the <expected> header in your C++ program, you can use the following syntax.

#include <expected>

Functions of <expected> Header

Below is list of all functions from <expected> header.

Retrieving the Value

In the following example we are going to use value() to retrieve the expected value if it exists.

#include <iostream>
#include <expected>
int main() {
    std::expected<int, std::string> result = 42;  
    if (result.has_value()) {
        std::cout << "Expected value: " << result.value() << std::endl;  
    } else {
        std::cout << "Unexpected error: " << result.error() << std::endl;
    }
    return 0;
}

Output

If we run the above code it will generate the following output

Expected value: 42

Monadic Operations

The Monadic operations provide ways to manipulate and transform the value or error within the expected object.

Monadic Operation Example

In the following example we are going to use and_then() function applies multiply_by_two to the expected value (21), returning a new std::expected object containing the result (42).

#include <iostream>
#include <expected>
std::expected<int, std::string multiply_by_two(int x) {
    return x * 2;
}
int main() {
    std::expected<int, std::string> result = 21;
    auto new_result = result.and_then(multiply_by_two);  

    if (new_result.has_value()) {
        std::cout << "New expected value: " << new_result.value() << std::endl;
    } else {
        std::cout << "Unexpected error: " << new_result.error() << std::endl;
    }
    return 0;
}

Output

If we run the above code it will generate the following output

New expected value: 42

Modifiers

Modifiers in std::expected are the functions which allows us to modify the state or contents of the expected object.

Modifying the Value

In the following example we are going to use emplace(), it replaces any current state (whether it contains a value or error) with a new expected value (10).

#include <iostream>
#include <expected>
int main() {
    std::expected<int, std::string> result = std::unexpected("Initial error");
    result.emplace(10);

    if (result.has_value()) {
        std::cout << "Replaced with new expected value: " << result.value() << std::endl;
    } else {
        std::cout << "Unexpected error: " << result.error() << std::endl;
    }
    return 0;
}

Output

If we run the above code it will generate the following output

Replaced with new expected value: 10