std::expected

 

C++

編譯器支援

獨立式與託管式

語言

標準函式庫

標準函式庫標頭檔

具名要求

特性測試巨集 (C++20)

語言支援函式庫

概念函式庫 (C++20)

診斷函式庫

記憶體管理函式庫

元編程函式庫 (C++11)

通用公用程式函式庫

容器函式庫

疊代器函式庫

Ranges 函式庫 (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 與 型別操作 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) 操作

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 的預期（expected）值，或型別為 E 的非預期（unexpected）值。expected 永遠不會處於無值狀態。

1) 主模板。將預期值或非預期值儲存在其自身的儲存空間內，該空間嵌套於 expected 物件之中。

2) void 部分特化。表示預期的 void 值或包含一個非預期值。若它包含一個非預期值，該值會嵌套於 expected 物件之中。

若程式將 expected 具現化為參考型別、函式型別，或 std::unexpected 的特化，則該程式為格式錯誤（ill-formed）。此外，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) 操作
and_then	若存在預期值，則傳回將給定函式應用於該值的結果；否則，傳回 expected 本身 (公開成員函式)
transform	若存在預期值，則傳回包含轉換後預期值的 expected；否則，傳回 expected 本身 (公開成員函式)
or_else	若包含預期值則傳回 expected 本身；否則，傳回將給定函式應用於非預期值的結果 (公開成員函式)
transform_error	若包含預期值則傳回 expected 本身；否則，傳回包含轉換後非預期值的 expected (公開成員函式)
修改器
emplace	原地（in-place）建構預期值 (公開成員函式)
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 的單子（Monadic）函式

範例

執行此程式碼

#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++ 標準。

DR	應用於	出版時的行為	正確的行為
LWG 4141	C++23	儲存需求 配置 (allocation) 描述易造成混淆	所包含的物件必須 嵌套於 expected 物件內

參考資料

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

• 22.8 Expected 物件 [expected]

參見

variant (C++17)	一種型別安全的識別聯合體 (discriminated union) (類別模板)
optional (C++17)	一個可能持有也可能不持有物件的封裝器 (類別模板)