FreeBSD Manual Pages
std::expected(3) C++ Standard Libary std::expected(3) NAME std::expected - std::expected Synopsis Defined in header <expected> template< class T, class E > (since C++23) class expected; The class template std::expected provides a way to store either of two values. An object of std::expected at any given time either holds an expected value of type T, or an unexpected value of type E. std::expected is never valueless. The stored value is allocated directly within the storage occupied by the expected object. No dynamic memory allocation takes place. A program is ill-formed if it instantiates an expected with a refer- ence type, a function type, or a specialization of std::unexpected. In addition, T must not be std::in_place_t or std::unexpect_t. Template parameters the type of the expected value. The type must either be (possi- bly cv-qualified) T - void, or meet the Destructible requirements (in particular, ar- ray and reference types are not allowed). the type of the unexpected value. The type must meet the De- structible E - requirements, and must be a valid template argument for std::un- expected (in particular, arrays, non-object types, and cv-qualified types are not allowed). Member types Member type Definition value_type T error_type E unexpected_type std::unexpected<E> Member alias templates Type Definition rebind<U> expected<U, error_type> Member functions constructor constructs the expected object (public member function) destructor destroys the expected object, along with its con- tained value (public member function) operator= assigns contents (public member function) Observers operator-> accesses the expected value operator* (public member function) operator bool checks whether the object contains an expected value has_value (public member function) value returns the expected value (public member function) error returns the unexpected value (public member function) value_or returns the expected value if present, another value otherwise (public member function) Monadic operations returns the result of the given function on the ex- pected value if it and_then exists; otherwise, returns the expected itself (public member function) returns an expected containing the transformed ex- pected value if it transform exists; otherwise, returns the expected itself (public member function) returns the expected itself if it contains an ex- pected value; or_else otherwise, returns the result of the given function on the unexpected value (public member function) returns the expected itself if it contains an ex- pected value; transform_error otherwise, returns an expected containing the trans- formed unexpected value (public member function) Modifiers emplace constructs the expected value in-place (public member function) swap exchanges the contents (public member function) Non-member functions operator== compares expected objects (C++23) (function template) swap(std::expected) specializes the std::swap algorithm (C++23) (function) Helper classes unexpected represented as an unexpected value (C++23) (class template) bad_expected_access exception indicating checked access to an ex- pected that contains (C++23) an unexpected value (class template) unexpect in-place construction tag for unexpected value in expected unexpect_t (tag) (C++23) Notes Types with the same functionality are called Result in Rust and Ei- ther in Haskell. Feature-test macro Value Std Feature 202202L (C++23) class template std::expected and associated __cpp_lib_expected helper classes 202211L (C++23) Monadic functions for std::ex- pected Example // Run this code #include <cmath> #include <expected> #include <iomanip> #include <iostream> #include <string_view> 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 = [](std::string_view 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::unreach- able(); }; 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 References * C++23 standard (ISO/IEC 14882:2023): * 22.8 Expected objects [expected] See also variant a type-safe discriminated union (C++17) (class template) optional a wrapper that may or may not hold an object (C++17) (class template) http://cppreference.com 2024.06.10 std::expected(3)
NAME | Synopsis | Template parameters | Member types | Member alias templates | Member functions | Observers | Modifiers | Non-member functions | Helper classes | Notes | Example | Output: | References | See also
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=std::expected&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>