std::expected - cppreference.com

De cppreference.com

Definido en el archivo de encabezado `<expected>`
`template< class T, class E > class expected;`	(1)	(desde C++23)
`template< class T, class E > requires std::is_void_v<T> class expected<T, E>;`	(2)	(desde C++23)

La plantilla de clase std::expected proporciona una forma de representar cualquiera de dos valores: un valor esperado de tipo T o un valor no esperado de tipo E. std::expected nunca carece de valor.

1) La plantilla principal. Contiene el valor esperado o no esperado dentro de su propio almacenamiento. No se realiza ninguna asignación de memoria dinámica.

2) La especialización parcial void. Representa un valor void esperado o contiene el valor no esperado dentro de su propio almacenamiento. No se realiza ninguna asignación de memoria dinámica.

Un programa está mal formado si crea una instancia de un expected con un tipo referencia, un tipo función o una especialización de std::unexpected. Además, T no debe ser std::in_place_t o std::unexpect_t.

Parámetros de plantilla

T	-	El tipo del valor esperado. El tipo debe ser (posiblemente calificado cv) `void` o cumplir con los requisitos de Destructible (en particular, no se permiten tipos array ni tipos referencia).
E	-	El tipo del valor no esperado. El tipo debe cumplir con los requisitos de Destructible y debe ser un argumento de plantilla válido para `std::unexpected` (en particular, arrays, tipo no objeto, y no se permiten tipos calificados cv).

Tipos anidados

Plantillas de alias miembro

Tipo	Definición
`rebind<U>`	`std::expected<U, error_type>`

Datos miembro

Dato miembro	Definición
`has_val`	Si el objeto `expected` representa actualmente el valor esperado. (objeto miembro solo de exposición*)
T `val` (solo plantila principal.)	El valor esperado (objeto miembro variante solo de exposición*)
E `unex`	El valor no esperado. (objeto miembro variante solo de exposición*)

Funciones miembro

(constructor)	Construye el objeto `expected`. (función miembro pública) [editar]
(destructor)	Destruye el objeto `expected`, así como su valor contenido. (función miembro pública) [editar]
operator=	Asigna el contenido. (función miembro pública) [editar]
Observadores
operator->operator*	Accede al valor esperado. (función miembro pública) [editar]
operator boolhas_value	Comprueba si el objeto contiene un valor esperado. (función miembro pública) [editar]
value	Devuelve el valor `expected`. (función miembro pública) [editar]
error	Devuelve el valor no esperado. (función miembro pública) [editar]
value_or	Devuelve el valor `expected` si está presente. De lo contrario, otro valor. (función miembro pública) [editar]
error_or	Devuelve el valor no esperado si está presente. De lo contrario, otro valor. (función miembro pública) [editar]
Operaciones monádicas
and_then	Devuelve el resultado de la función dada sobre el valor esperado si existe; de lo contrario, devuelve el propio `expected`. (función miembro pública) [editar]
transform	Devuelve un objeto `expected` que contiene el valor esperado transformado si existe; de lo contrario, devuelve el propio `expected`. (función miembro pública) [editar]
or_else	Devuelve el propio `expected` si contiene un valor esperado; de lo contrario, devuelve el resultado de la función dada en el valor no esperado. (función miembro pública) [editar]
transform_error	Devuelve el propio objeto `expected` si contiene un valor esperado; de lo contrario, devuelve un objeto `expected` que contiene el valor no esperado transformado. (función miembro pública) [editar]
Modificadores
emplace	Construye el valor esperado in situ. (función miembro pública) [editar]
swap	Intercambia el contenido. (función miembro pública) [editar]

Funciones no miembro

Clases auxiliares

Notas

Los tipos con la misma funcionalidad se llaman Result en Rust y Either en Haskell.

Macro de prueba de característica	Valor	Estándar	Comentario
`__cpp_lib_expected`	`202202L`	(C++23)	Plantilla de clase `std::expected` y clases auxiliares.
`__cpp_lib_expected`	`202211L`	(C++23)	Funciones monádicas para `std::expected`.

Ejemplo

#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 << "valor: " << *num << '\n';
            // Si num no tenía valor, dereferenciar num
            // ocasionaría un comportamiento no definido, y
            // num.value() lanzaría std::bad_expected_access.
            // num.value_or(123) usa un valor especificado por defecto 123.
        else if (num.error() == parse_error::invalid_input)
            std::cout << "error: entrada no válida\n";
        else if (num.error() == parse_error::overflow)
            std::cout << "error: desbordamiento\n";
        else
            std::cout << "¡no esperado!\n"; // o invocar std::unreachable();
    };
    
    for (auto src : {"42", "42abc", "miau", "inf"})
        process(src);
}

Salida:

str: "42", valor: 42
str: "42abc", valor: 42
str: "miau", error: entrada no válida
str: "inf", error: desbordamiento

Referencias

El estándar C++23 (ISO/IEC 14882:2023):

22.8 Expected objects [expected]

Véase también

	Una unión discriminada con seguridad de tipo. (plantilla de clase) [editar]
	Un envoltorio que puede o no mantener un objeto. (plantilla de clase) [editar]