std::expected

 

C++

編譯器支援

自由（freestanding）與宿主（hosted）

語言

標準庫

標準庫標頭檔案

具名要求

特性測試宏 (C++20)

語言支援庫

概念庫 (C++20)

診斷庫

記憶體管理庫

超程式設計庫 (C++11)

通用工具庫

容器庫

迭代器庫

範圍庫 (C++20)

演算法庫

字串庫

文字處理庫

數值庫

日期和時間庫

輸入/輸出庫

檔案系統庫 (C++17)

併發支援庫 (C++11)

執行控制庫 (C++26)

技術規範

符號索引

外部庫

 

工具庫

語言支援 型別支援（基本型別、RTTI） 庫特性測試宏 (C++20) 程式工具 變參函式 initializer_list (C++11) is_constant_evaluated (C++20) is_within_lifetime (C++26) source_location (C++20) 協程支援 (C++20) 契約支援 (C++26) 三路比較 three_way_comparablethree_way_comparable_with (C++20)(C++20) strong_ordering (C++20) weak_ordering (C++20) partial_ordering (C++20) common_comparison_category (C++20) compare_three_way_result (C++20) compare_three_way (C++20) strong_order (C++20) weak_order (C++20) partial_order (C++20) compare_strong_order_fallback (C++20) compare_weak_order_fallback (C++20) compare_partial_order_fallback (C++20)   is_eqis_ltis_lteq (C++20)(C++20)(C++20)   is_neqis_gtis_gteq (C++20)(C++20)(C++20)

通用工具 函式物件 位操作 (C++20) bitset hash (C++11) 關係運算符 (C++20 中棄用) rel_ops::operator!=rel_ops::operator>    rel_ops::operator<=rel_ops::operator>= 整數比較函式 cmp_equalcmp_lesscmp_less_than (C++20)(C++20)(C++20)   cmp_not_equalcmp_greatercmp_greater_than (C++20)(C++20)(C++20) in_range (C++20) 交換與型別操作 swap ranges::swap (C++20) exchange (C++14) declval (C++11) to_underlying (C++23) forward (C++11) forward_like (C++23) move (C++11) move_if_noexcept (C++11) as_const (C++17) 常用詞彙型別 pair tuple (C++11) optional (C++17) any (C++17) variant (C++17) tuple_size (C++11) tuple_element (C++11) apply (C++17) make_from_tuple (C++17) expected (C++23)

 

std::expected

成員函式

expected::expected

expected::~expected

expected::operator=

觀察器

expected::operator->expected::operator*

expected::operator boolexpected::has_value

expected::value

expected::error

expected::value_or

expected::error_or

Monadic operations

expected::and_then

expected::or_else

expected::transform

expected::transform_error

修改器

expected::emplace

expected::swap

非成員函式

operator==(std::expected)

swap(std::expected)

輔助類

unexpected

bad_expected_access

unexpect_tunexpect

 

定義於標頭檔案 <expected>
template< class T, class E > class expected;	(1)	(C++23 起)
template< class T, class E >     requires std::is_void_v<T> class expected<T, E>;	(2)	(C++23 起)

類模板 std::expected 提供了一種表示兩種值之一的方式：一個型別為 T 的*預期*值，或一個型別為 E 的*非預期*值。expected 永遠不會是無值的。

1) 主模板。在其自身的儲存中包含預期值或非預期值，該儲存 巢狀在 expected 物件內。

2) void 偏特化。表示一個預期的 void 值或包含一個非預期值。如果它包含一個非預期值，則該值巢狀在 expected 物件內。

如果程式例項化了一個引用型別、函式型別或 std::unexpected 的特化的 expected，則程式格式錯誤。此外，T 不能是 std::in_place_t 或 std::unexpect_t。

模板引數

T	-	預期值的型別。該型別必須是（可能是 cv 限定的）void，或者滿足 可析構 (Destructible) 要求（特別是，不允許陣列和引用型別）。
E	-	非預期值的型別。該型別必須滿足 可析構 (Destructible) 要求，並且必須是 std::unexpected 的有效模板引數（特別是，不允許陣列、非物件型別和 cv 限定型別）。

成員型別

成員型別	定義
value_type	T
error_type	E
unexpected_type	std::unexpected<E>

成員別名模板

型別	定義
rebind<U>	std::expected<U, error_type>

資料成員

成員	定義
bool has_val	expected 物件當前是否表示預期值 (僅用於闡釋的成員物件*)
T val (僅限主模板)	預期值 (僅作說明的變體成員物件*)
E unex	非預期值 (僅作說明的變體成員物件*)

成員函式

(建構函式)	構造 expected 物件 (公共成員函式)
(解構函式)	銷燬 expected 物件及其包含的值 (公共成員函式)
operator=	賦值內容 (公共成員函式)
觀察器
operator->operator*	訪問預期值 (公共成員函式)
operator boolhas_value	檢查物件是否包含預期值 (公共成員函式)
value	返回預期值 (公共成員函式)
error	返回非預期值 (公共成員函式)
value_or	如果存在，返回預期值；否則返回另一個值 (公共成員函式)
error_or	如果存在，返回非預期值；否則返回另一個值 (公共成員函式)
Monadic operations
and_then	如果預期值存在，返回給定函式作用於預期值的結果；否則返回 expected 自身 (公共成員函式)
transform	如果預期值存在，返回包含轉換後的預期值的 expected；否則返回 expected 自身 (公共成員函式)
or_else	如果 expected 包含預期值，返回 expected 自身；否則返回給定函式作用於非預期值的結果 (公共成員函式)
transform_error	如果 expected 包含預期值，返回 expected 自身；否則返回包含轉換後的非預期值的 expected (公共成員函式)
修改器
emplace	就地構造預期值 (公共成員函式)
swap	交換內容 (公共成員函式)

非成員函式

operator== (C++23)	比較 expected 物件 (函式模板)
swap(std::expected) (C++23)	特化 std::swap 演算法 (函式)

輔助類

unexpected (C++23)	表示為意外值 (類模板)
bad_expected_access (C++23)	表示對包含非預期值的 expected 進行檢查訪問時丟擲的異常 (類模板)
unexpectunexpect_t (C++23)	用於 expected 中非預期值就地構造的標籤 (標籤)

注

在 Rust 中，具有相同功能的型別稱為 Result；在 Haskell 中，稱為 Either。

特性測試宏	值	標準	特性
__cpp_lib_expected	202202L	(C++23)	類模板 std::expected 及相關 輔助類
	202211L	(C++23)	std::expected 的單子函式

示例

執行此程式碼

#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);
}

輸出

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

缺陷報告

下列更改行為的缺陷報告追溯地應用於以前出版的 C++ 標準。

缺陷報告	應用於	釋出時的行為	正確的行為
LWG 4141	C++23	儲存要求 令人困惑	包含的物件必須 巢狀在 expected 物件內

參考

• C++23 標準 (ISO/IEC 14882:2024)

• 22.8 預期物件 [expected]

另請參閱

variant (C++17)	一種型別安全的帶判別聯合體 (類模板)
optional (C++17)	可能包含或不包含物件的包裝器 (類模板)