Draft:Std::expected

Review waiting, please be patient. This may take 2 months or more, since drafts are reviewed in no specific order. There are 2,360 pending submissions waiting for review. If the submission is accepted, then this page will be moved into the article space. If the submission is declined, then the reason will be posted here. In the meantime, you can continue to improve this submission by editing normally. Where to get help If you need help editing or submitting your draft, please ask us a question at the AfC Help Desk or get live help from experienced editors. These venues are only for help with editing and the submission process, not to get reviews. If you need feedback on your draft, or if the review is taking a lot of time, you can try asking for help on the talk page of a relevant WikiProject. Some WikiProjects are more active than others so a speedy reply is not guaranteed. How to improve a draft Wikipedia:Contributing to Wikipedia – a basic overview on how to edit Wikipedia. Help:Wikitext – how to use the markup Help:Referencing for beginners – how to include references Wikipedia:Article development – how to develop your article Wikipedia:Writing better articles – how to improve your article Wikipedia:Verifiability – make sure your article includes reliable third-party sources You can also browse Wikipedia:Featured articles and Wikipedia:Good articles to find examples of Wikipedia's best writing on topics similar to your proposed article. Improving your odds of a speedy review To improve your odds of a faster review, tag your draft with relevant WikiProject tags using the button below. This will let reviewers know a new draft has been submitted in their area of interest. For instance, if you wrote about a female astronomer, you would want to add the Biography, Astronomy, and Women scientists tags. Add tags to your draft Editor resources Easy tools: Citation bot (help) | Advanced: Fix bare URLs Reviewer tools Instructions · What links here · Std::expected (talk: + · bio) · (log) · Copyvios report · reFill · Citation Bot · (Search: Google, Wikipedia) · Submitted 2 days ago by Spatulari (talk: D · +) · Last edited 2 days ago by Colorado001

std::expected is a class template in the C++ Standard Library introduced in C++23. It is a vocabulary type that represents either an expected value of type T or an unexpected value of type E.^[1] It is intended for functions that may either produce a value or report an error without using exceptions.^[2] The class template is defined in the <expected> header.

Historically, error handling in C++ has relied primarily on two strategies: returning status/error codes or throwing standard C++ exceptions. While exceptions allow for clean separation of happy-path logic from error handling, they introduce non-deterministic performance characteristics, potential binary size bloat, and require runtime support stack unwinding.^[3] As a result, codebases in safety-critical, real-time, or embedded software development frequently disallow exceptions using compiler flags such as -fno-exceptions.^[4]

Conversely, traditional status codes require out-of-band error return channels (such as output parameters) or forced sentinel values, which can obscure function signatures and invite unhandled runtime failures if callers ignore return codes.^[5]

While std::optional was added in C++17 to convey the presence or absence of a value, it carries no explicit context regarding *why* an operation failed. std::expected bridges this gap by marrying the safety of explicit return values with detailed error payload reporting.

The conceptual origins of std::expected stem from functional programming constructs, most notably the Either monad. The C++ design drew heavy inspiration from Andrei Alexandrescu's 2012 talk and paper on "Systematic Error Handling", as well as error handling abstractions in modern systems languages such as Rust's Result<T, E> type.^[1]

An instance of std::expected<T, E> represents a discriminated union containing either:

• an expected value of type T, or
• an unexpected value of type E representing an error state.

Unlike polymorphic pointer types, std::expected stores its underlying value directly within its memory footprint (typically allocating enough storage for the larger of T or E plus a boolean flag), avoiding dynamic heap allocation. The type is guaranteed to never be valueless.

Specializations exist for cases where T is void (i.e., std::expected<void, E>), enabling functions that return no meaningful result on success to still communicate failure metadata.

The effort to standardise expected values in C++ began with proposal paper P0323, presented to the ISO C++ Standards Committee (WG21). Following extensive design revisions across several years, the revision P0323R12 was officially accepted for inclusion in C++23.^[1]

In parallel, standardisation efforts aimed at equipping C++ vocabulary types with functional composition tools led to the acceptance of paper P2505R5. This added monadic member functions (such as and_then, transform, and or_else) to both std::optional and std::expected, enabling clean operation chaining without requiring nested conditional checks.^[6]

The class template provides standard observers to query state and access contained values:

• has_value() – checks whether the object contains an expected value.
• value() – returns the contained value, or throws std::bad_expected_access if the object contains an error.
• error() – accesses the underlying error object.
• value_or() – returns the contained value or a provided fallback default.

C++23 monadic utilities facilitate functional operation chaining:

• and_then() – executes a function returning an expected if a value is present.
• transform() – applies a transformation function to the expected value.
• or_else() – executes a recovery routine returning an expected if an error state is present.
• transform_error() – applies a transformation function specifically to the stored error type.

The standard library also defines helper utilities: std::unexpected (a wrapper used to signal error construction), std::unexpect_t / std::unexpect (in-place tagging utilities), and std::bad_expected_access (the exception type thrown on invalid access).

The following example demonstrates basic usage, returning an error payload on division by zero:

#include <expected>
#include <iostream>
#include <string>

std::expected<double, std::string> safe_divide(double numerator, double denominator)
{
    if (denominator == 0.0)
        return std::unexpected("Error: Division by zero.");

    return numerator / denominator;
}

int main()
{
    auto result = safe_divide(10.0, 2.0);

    if (result.has_value()) {
        std::cout << "Result: " << result.value() << '\n';
    } else {
        std::cerr << result.error() << '\n';
    }

    // Example of monadic chaining
    auto chained = safe_divide(10.0, 2.0)
        .transform([](double v) { return v * 2.0; })
        .value_or(0.0);

    std::cout << "Chained result: " << chained << '\n';
}

• C++23
• C++ Standard Library
• Monad (functional programming)
• Exception handling

Category:C++ Category:Standard Template Library