std::unexpected

 

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 E > class unexpected;		(C++23 起)

類模板 std::unexpected 表示儲存在 std::expected 中的意外值。特別是，std::expected 具有以 std::unexpected 作為單個引數的建構函式，該建構函式建立一個包含意外值的 expected 物件。

如果程式使用非物件型別、陣列型別、std::unexpected 的特化或 cv 限定型別例項化 unexpected，則該程式格式錯誤。

模板引數

E

-

意外值的型別。該型別不能是陣列型別、非物件型別、std::unexpected 的特化或 cv 限定型別。

成員函式

(建構函式)	構造 unexpected 物件 (公開成員函式)
(解構函式) (隱式宣告)	銷燬 unexpected 物件及其儲存的值 (公開成員函式)
operator= (隱式宣告)	賦值儲存的值 (公開成員函式)
error	訪問儲存的值 (公開成員函式)
swap	交換儲存的值 (公開成員函式)

非成員函式

operator== (C++23)	比較儲存的值 (函式模板)
swap(std::unexpected) (C++23)	特化 std::swap 演算法 (函式模板)

std::unexpected::unexpected

constexpr unexpected( const unexpected& ) = default;	(1)
constexpr unexpected( unexpected&& ) = default;	(2)
template< class Err = E > constexpr explicit unexpected( Err&& e );	(3)
template< class... Args > constexpr explicit unexpected( std::in_place_t, Args&&... args );	(4)
template< class U, class... Args > constexpr explicit unexpected( std::in_place_t,                                std::initializer_list<U> il, Args&&... args );	(5)

構造 std::unexpected 物件。

1,2) 複製/移動建構函式。分別複製或移動儲存的值。

3) 構造儲存的值，如同透過 直接初始化 型別為 E 的值，從 std::forward<Err>(e) 構造。

• 此過載僅在以下情況參與過載決議：
  • std::is_same_v<std::remove_cvref_t<Err>, unexpected> 為 false，且
  • std::is_same_v<std::remove_cvref_t<Err>, std::in_place_t> 為 false，且
  • std::is_constructible_v<E, Err> 為 true。

4) 構造儲存的值，如同透過 直接初始化 型別為 E 的值，從引數 std::forward<Args>(args)... 構造。

• 此過載僅在 std::is_constructible_v<E, Args...> 為 true 時參與過載決議。

5) 構造儲存的值，如同透過 直接初始化 型別為 E 的值，從引數 il, std::forward<Args>(args)... 構造。

• 此過載僅在 std::is_constructible_v<E, std::initializer_list<U>&, Args...> 為 true 時參與過載決議。

引數

e	-	用於初始化包含值的值
args...	-	用於初始化包含值的引數
il	-	用於初始化包含值的初始化列表

異常

丟擲由 E 的建構函式丟擲的任何異常。

std::unexpected::error

constexpr const E& error() const& noexcept; constexpr E& error() & noexcept; constexpr const E&& error() const&& noexcept; constexpr E&& error() && noexcept;

返回對儲存值的引用。

std::unexpected::swap

constexpr void swap( unexpected& other ) noexcept(std::is_nothrow_swappable_v<E>);

交換儲存的值，如同透過 using std::swap; swap(error(), other.error());。

如果 std::is_swappable_v<E> 為 false，則程式格式錯誤。

operator==(std::unexpected)

template< class E2 > friend constexpr bool operator==( unexpected& x, std::unexpected<E2>& y );

比較儲存的值，如同透過 return x.error() == y.error()。

如果表示式 x.error() == e.error() 格式不正確，或其結果不可轉換為 bool，則程式格式錯誤。

此函式對普通的 非限定查詢 或 限定查詢 不可見，並且只有在 std::unexpected<E> 是引數的關聯類時才能透過 引數依賴查詢 找到。

swap(std::unexpected)

friend constexpr void swap( unexpected& x, unexpected& y ) noexcept(noexcept(x.swap(y)));

等效於 x.swap(y)。

此過載僅在 std::is_swappable_v<E> 為 true 時參與過載決議。

此函式對普通的 非限定查詢 或 限定查詢 不可見，並且只有在 std::unexpected<E> 是引數的關聯類時才能透過 引數依賴查詢 找到。

推導指南

template< class E > unexpected(E) -> unexpected<E>;		(C++23 起)

為 unexpected 提供了 推導指南，以允許從建構函式引數進行推導。

註記

在 C++17 之前，名稱 std::unexpected 表示當動態異常規範被違反時，C++ 執行時呼叫的函式。

示例

執行此程式碼

#include <expected>
#include <iostream>
 
enum class error
{
    compile_time_error,
    runtime_error
};
 
[[nodiscard]] auto unexpected_runtime_error() -> std::expected<int, error>
{
    return std::unexpected(error::runtime_error);
}
 
int main()
{
    std::expected<double, int> ex = std::unexpected(3);
 
    if (!ex)
        std::cout << "ex contains an error value\n";
 
    if (ex == std::unexpected(3))
        std::cout << "The error value is equal to 3\n";
 
    const auto e = unexpected_runtime_error();
 
    e.and_then([](const auto& e) -> std::expected<int, error>
    {
        std::cout << "and_then: " << int(e); // not printed
        return {};
    })
    .or_else([](const auto& e) -> std::expected<int, error>
    {
        std::cout << "or_else: " << int(e); // prints this line
        return {};
    });
}

輸出

ex contains an error value
The error value is equal to 3
or_else: 1

參閱

(建構函式)	構造 expected 物件 (public member function)
operator== (C++23)	比較 expected 物件 (function template)