std::expected - cppreference.com (original) (raw)

The class template std::expected provides a way to represent either of two values: an expected value of type T, or an unexpected value of type E. expected is never valueless.

1. The main template. Contains the expected or unexpected value within its own storage, which is nested within the expected object.

2. The void partial specialization. Represents an expected void value or contains an unexpected value. If it contains an unexpected value, it is nested within the expected object.

A program is ill-formed if it instantiates an expected with a reference type, a function type, or a specialization of std::unexpected. In addition, T must not be std::in_place_t or std::unexpect_t.

Contents

• 1 Template parameters
• 2 Nested types
• 3 Member templates
• 4 Data members
• 5 Member functions
  • 5.1 Observers
  • 5.2 Monadic operations
  • 5.3 Modifiers
• 6 Non-member functions
• 7 Helper classes
• 8 Notes
• 9 Example
• 10 Defect reports
• 11 References
• 12 See also

[edit] Template parameters

[edit] Nested types

[edit] Member templates

[edit] Data members

[edit] Member functions

[edit] Non-member functions

[edit] Helper classes

[edit] Notes

Types with the same functionality are called Result in Rust and Either in Haskell.

[edit] Example

#include #include #include #include #include   enum class parse_error { invalid_input, overflow };   auto parse_number(std::string_view& str) -> std::expected<double, parse_error> { const char* begin = str.data(); char* end; double retval = std::strtod(begin, &end);   if (begin == end) return std::unexpected(parse_error::invalid_input); else if (std::isinf(retval)) return std::unexpected(parse_error::overflow);   str.remove_prefix(end - begin); return retval; }   int main() { auto process = str) { std::cout << "str: " << std::quoted(str) << ", "; if (const auto num = parse_number(str); num.has_value()) std::cout << "value: " << *num << '\n'; // If num did not have a value, dereferencing num // would cause an undefined behavior, and // num.value() would throw std::bad_expected_access. // num.value_or(123) uses specified default value 123. else if (num.error() == parse_error::invalid_input) std::cout << "error: invalid input\n"; else if (num.error() == parse_error::overflow) std::cout << "error: overflow\n"; else std::cout << "unexpected!\n"; // or invoke std::unreachable(); };   for (auto src : {"42", "42abc", "meow", "inf"}) process(src); }

Output:

str: "42", value: 42 str: "42abc", value: 42 str: "meow", error: invalid input str: "inf", error: overflow

[edit] Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

[edit] References

• C++23 standard (ISO/IEC 14882:2024):

• 22.8 Expected objects [expected]

[edit] See also

| | a type-safe discriminated union (class template) [edit] | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | a wrapper that may or may not hold an object (class template) [edit] |