Namespaces
Variants

std:: expected

From cppreference.net
C++
Utilities library
std::expected
Défini dans l'en-tête <expected>
template < class T, class E >
class expected ;
(1) (depuis C++23)
template < class T, class E >

requires std:: is_void_v < T >

class expected < T, E > ;
(2) (depuis C++23)

Le modèle de classe std::expected fournit un moyen de représenter l'une ou l'autre de deux valeurs : une valeur attendue de type T , ou une valeur inattendue de type E . expected n'est jamais sans valeur.

1) Le modèle principal. Contient la valeur attendue ou inattendue dans son propre stockage, qui est imbriqué dans l'objet expected .
2) La void spécialisation partielle. Représente une valeur void attendue ou contient une valeur inattendue. Si elle contient une valeur inattendue, elle est imbriquée dans l'objet expected .

Un programme est mal formé s'il instancie un expected avec un type référence, un type fonction ou une spécialisation de std::unexpected . De plus, T ne doit pas être std::in_place_t ou std::unexpect_t .

Table des matières

Paramètres du modèle

T - le type de la valeur attendue. Le type doit être soit (éventuellement qualifié cv) void , soit satisfaire aux exigences Destructible (en particulier, les types tableau et référence ne sont pas autorisés).
E - le type de la valeur inattendue. Le type doit satisfaire aux exigences Destructible , et doit être un argument de modèle valide pour std::unexpected (en particulier, les tableaux, les types non-objets et les types qualifiés cv ne sont pas autorisés).

Types imbriqués

Type Définition
value_type T
error_type E
unexpected_type std::unexpected<E>

Modèles de membre

Modèle Définition
rebind < U > std :: expected < U, error_type >

Membres de données

Membre Description
bool has_val indique si l'objet expected représente actuellement la valeur attendue
( objet membre d'exposition uniquement* )
T val (modèle principal uniquement) la valeur attendue
( objet membre variant d'exposition uniquement* )
E unex la valeur inattendue
( objet membre variant d'exposition uniquement* )

Fonctions membres

construit l'objet expected
(fonction membre publique)
détruit l'objet expected ainsi que sa valeur contenue
(fonction membre publique)
assigne le contenu
(fonction membre publique)
Observateurs
accède à la valeur attendue
(fonction membre publique)
vérifie si l'objet contient une valeur attendue
(fonction membre publique)
retourne la valeur attendue
(fonction membre publique)
retourne la valeur inattendue
(fonction membre publique)
retourne la valeur attendue si présente, une autre valeur sinon
(fonction membre publique)
retourne la valeur inattendue si présente, une autre valeur sinon
(fonction membre publique)
Opérations monadiques
retourne le résultat de la fonction donnée sur la valeur attendue si elle existe ; sinon, retourne l' expected lui-même
(fonction membre publique)
retourne un expected contenant la valeur attendue transformée si elle existe ; sinon, retourne l' expected lui-même
(fonction membre publique)
retourne l' expected lui-même s'il contient une valeur attendue ; sinon, retourne le résultat de la fonction donnée sur la valeur inattendue
(fonction membre publique)
retourne l' expected lui-même s'il contient une valeur attendue ; sinon, retourne un expected contenant la valeur inattendue transformée
(fonction membre publique)
Modificateurs
construit la valeur attendue en place
(fonction membre publique)
échange le contenu
(fonction membre publique)

Fonctions non membres

(C++23)
compare les objets expected
(modèle de fonction)
(C++23)
spécialise l'algorithme std::swap
(fonction)

Classes d'assistance

(C++23)
représenté comme une valeur inattendue
(modèle de classe)
(C++23)
exception indiquant un accès vérifié à un expected qui contient une valeur inattendue
(modèle de classe)
(C++23)
étiquette de construction en place pour la valeur inattendue dans expected
(étiquette)

Notes

Les types ayant la même fonctionnalité sont appelés Result en Rust et Either en Haskell.

Macro de test de fonctionnalité Valeur Std Fonctionnalité
__cpp_lib_expected 202202L (C++23) Classe template std::expected et classes auxiliaires associées
202211L (C++23) Fonctions monadiques pour std::expected

Exemple

Exécuter ce 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::unreachable();
    };
    for (auto src : {"42", "42abc", "meow", "inf"})
        process(src);
}

Sortie : 

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

Rapports de défauts

Les rapports de défauts modifiant le comportement suivants ont été appliqués rétroactivement aux normes C++ précédemment publiées.

DR Appliqué à Comportement publié Comportement corrigé
LWG 4141 C++23 l'exigence d'allocation de stockage
était confuse 		l'objet contenu doit être
imbriqué dans l'objet expected

Références

  • Norme C++23 (ISO/CEI 14882:2024) :
  • 22.8 Objets attendus [expected]

Voir aussi

(C++17)
une union discriminée type-safe
(modèle de classe)
(C++17)
un wrapper qui peut contenir ou non un objet
(modèle de classe)