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.

S.No	Functions & Description
1	operator->, operator* These functions provide accesses the expected value.
2	operator bool, has_value These functions checks whether the object contains an expected value.
3	value This function returns the expected value.
4	error This function returns the unexpected value.
5	value_or This function returns the expected value if present, another value otherwise.
6	error_or This function returns the unexpected value if present, another value otherwise.

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.

S.No	Functions & Description
1	and_then This function returns the result of the given function on the expected value if it exists; otherwise, returns the expected itself.
2	transform This function returns an expected containing the transformed expected value if it exists; otherwise, returns the expected itself.
3	or_else This function returns the expected itself if it contains an expected value; otherwise, returns the result of the given function on the unexpected value.
4	transform_error This function returns the expected itself if it contains an expected value; otherwise, returns an expected containing the transformed unexpected value.

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.

S.No	Functions & Description
1	emplace This function constructs the expected value in-place, replacing any existing value or error..
2	operator bool, has_value This function exchanges the contents of two objects.

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

Print Page