Namespaces
Variants

std:: expected

From cppreference.net
C++
Utilities library
std::expected
Definido en el 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 uno de dos valores: un valor esperado de tipo T , o un valor inesperado de tipo E . expected nunca carece de valor.

1) La plantilla principal. Contiene el valor esperado o inesperado dentro de su propio almacenamiento, que está anidado dentro del objeto expected .
2) La void especialización parcial. Representa un valor esperado void o contiene un valor inesperado. Si contiene un valor inesperado, está anidado dentro del objeto expected .

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

Contenidos

Parámetros de plantilla

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

Tipos anidados

Tipo Definición
value_type T
error_type E
unexpected_type std::unexpected<E>

Plantillas de miembros

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

Miembros de datos

Miembro Descripción
bool has_val si el objeto expected actualmente representa el valor esperado
( objeto miembro solo para exposición* )
T val (solo plantilla principal) el valor esperado
( objeto miembro variante solo para exposición* )
E unex el valor inesperado
( objeto miembro variante solo para exposición* )

Funciones miembro

construye el objeto expected
(función miembro pública)
destruye el objeto expected junto con su valor contenido
(función miembro pública)
asigna contenidos
(función miembro pública)
Observadores
accede al valor esperado
(función miembro pública)
verifica si el objeto contiene un valor esperado
(función miembro pública)
devuelve el valor esperado
(función miembro pública)
devuelve el valor inesperado
(función miembro pública)
devuelve el valor esperado si está presente, otro valor en caso contrario
(función miembro pública)
devuelve el valor inesperado si está presente, otro valor en caso contrario
(función miembro pública)
Operaciones monádicas
devuelve el resultado de la función dada sobre el valor esperado si existe; de lo contrario, devuelve el expected mismo
(función miembro pública)
devuelve un expected que contiene el valor esperado transformado si existe; de lo contrario, devuelve el expected mismo
(función miembro pública)
devuelve el expected mismo si contiene un valor esperado; de lo contrario, devuelve el resultado de la función dada sobre el valor inesperado
(función miembro pública)
devuelve el expected mismo si contiene un valor esperado; de lo contrario, devuelve un expected que contiene el valor inesperado transformado
(función miembro pública)
Modificadores
construye el valor esperado in situ
(función miembro pública)
intercambia los contenidos
(función miembro pública)

Funciones no miembro

(C++23)
compara objetos expected
(plantilla de función)
(C++23)
especializa el algoritmo std::swap
(función)

Clases auxiliares

(C++23)
representado como un valor inesperado
(plantilla de clase)
(C++23)
excepción que indica acceso verificado a un expected que contiene un valor inesperado
(plantilla de clase)
(C++23)
etiqueta de construcción in situ para valor inesperado en expected
(etiqueta)

Notas

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

Macro de prueba de características Valor Std Característica
__cpp_lib_expected 202202L (C++23) Plantilla de clase std::expected y clases auxiliares asociadas
202211L (C++23) Funciones mónadas para std::expected

Ejemplo

Ejecutar este código 
#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';
            // Si num no tuviera un valor, desreferenciar num
            // causaría un comportamiento indefinido, y
            // num.value() lanzaría std::bad_expected_access.
            // num.value_or(123) usa el valor por defecto especificado 123.
        else if (num.error() == parse_error::invalid_input)
            std::cout << "error: entrada inválida\n";
        else if (num.error() == parse_error::overflow)
            std::cout << "error: desbordamiento\n";
        else
            std::cout << "¡inesperado!\n"; // o invocar std::unreachable();
    };
    for (auto src : {"42", "42abc", "meow", "inf"})
        process(src);
}

Salida: 

str: "42", value: 42
str: "42abc", value: 42
str: "meow", error: entrada inválida
str: "inf", error: desbordamiento

Informes de defectos

Los siguientes informes de defectos que modifican el comportamiento se aplicaron retroactivamente a los estándares publicados anteriormente de C++.

DR Aplicado a Comportamiento publicado Comportamiento correcto
LWG 4141 C++23 el requisito de asignación de almacenamiento
era confuso 		el objeto contenido debe estar
anidado dentro del objeto expected

Referencias

  • Estándar C++23 (ISO/IEC 14882:2024):
  • 22.8 Objetos esperados [expected]

Véase también

(C++17)
una unión discriminada con seguridad de tipos
(plantilla de clase)
(C++17)
un contenedor que puede o no contener un objeto
(plantilla de clase)