std::visit

 

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::variant

成員函式

variant::variant

variant::~variant

variant::operator=

觀察器

variant::index

variant::valueless_by_exception

修改器

variant::emplace

variant::swap

訪問（Visitation）

variant::visit (C++26)

非成員函式

visit(std::variant)

holds_alternative

get(std::variant)

get_if

operator==operator!=operator<operator<=operator>operator>=operator<=> (C++20)

swap(std::variant)

輔助類

monostate

bad_variant_access

variant_size

variant_alternative

hash<std::variant>

輔助物件

variant_npos

 

定義於標頭檔案 <variant>
template< class Visitor, class... Variants > constexpr /* 見下方 */ visit( Visitor&& v, Variants&&... values );	(1)	(C++17 起)
template< class R, class Visitor, class... Variants > constexpr R visit( Visitor&& v, Variants&&... values );	(2)	(C++20 起)
幫助模板
template< class... Ts > auto&& as-variant( std::variant<Ts...>& value );	(3)	(僅作說明*)
template< class... Ts > auto&& as-variant( const std::variant<Ts...>& value );	(4)	(僅作說明*)
template< class... Ts > auto&& as-variant( std::variant<Ts...>&& value );	(5)	(僅作說明*)
template< class... Ts > auto&& as-variant( const std::variant<Ts...>&& value );	(6)	(僅作說明*)

將訪問器 v （一個可以用來自 Variants 的任意型別組合呼叫的可呼叫 (Callable) 物件）應用於 Variants values。

給定 VariantBases 為 decltype(as-variant(std::forward<Variants>(values))...（一個包含 sizeof...(Variants) 個型別的包）。

1) 呼叫 v，如同透過

INVOKE(std::forward<Visitor>(v),
       std::get<indices>(std::forward<VariantBases>(values))...),

其中 indices 是 as-variant(values).index()...。

2) 呼叫 v，如同透過

INVOKE<R>(std::forward<Visitor>(v),
          std::get<indices>(std::forward<VariantBases>(values))...),

其中 indices 是 as-variant(values).index()...。

這些過載僅當 VariantBases 中的每個型別都是有效型別時才參與過載決議。如果由 INVOKE 或 INVOKE<R>(C++20 起) 表示的表示式是無效的，或者對於不同的 indices，INVOKE 或 INVOKE<R>(C++20 起) 的結果具有不同的型別或值類別，則程式非良構。

3-6) 僅用於闡釋的 as-variant 函式模板接受一個其型別可以被推導為 std::variant<Ts...> 的值（即，要麼是 std::variant<Ts...>，要麼是從 std::variant<Ts...> 派生的型別），並返回具有相同 const 限定和值類別的 std::variant 值。

3,4) 返回 value。

5,6) 返回 std::move(value)。

引數

v	-	一個可呼叫 (Callable) 物件，它接受來自 Variants 中每個 variant 的每一種可能的備選型別
values	-	要傳遞給訪問器的 variant 列表

返回值

1) INVOKE 操作的結果。返回型別是透過對結果應用 decltype 獲得的型別。

2) 如果 R 是（可能 cv 限定的）void，則無返回值；否則為 INVOKE<R> 操作的結果。

3-6) 從 value 轉換而來的 std::variant 值。

異常

如果對於 values 中的任何 variant value_i，as-variant(value_i).valueless_by_exception() 為 true，則丟擲 std::bad_variant_access。

複雜度

當 variant 的數量為零或一時，可呼叫物件的呼叫以常數時間實現；也就是說，它不依賴於 variant 中可儲存的型別數量。

如果 variant 的數量大於一，可呼叫物件的呼叫沒有複雜度要求。

注意

令 n 為 (1 * ... * std::variant_size_v<std::remove_reference_t<VariantBases>>)，實現通常會為 std::visit 的每個特化生成一個等價於包含 n 個函式指標的（可能多維的）陣列的表，這類似於虛擬函式的實現。

實現也可能為 std::visit 生成一個帶有 n 個分支的 switch 語句（例如，當 n 不大於 256 時，MSVC STL 實現使用 switch 語句）。

在典型的實現中，呼叫 v 的時間複雜度可以被認為等同於訪問一個（可能多維的）陣列中的元素或執行一個 switch 語句的時間複雜度。

特性測試宏	值	標準	特性
__cpp_lib_variant	202102L	(C++23) (DR17)	支援派生自 std::variant 的類的 std::visit

示例

執行此程式碼

#include <iomanip>
#include <iostream>
#include <string>
#include <type_traits>
#include <variant>
#include <vector>
 
// the variant to visit
using value_t = std::variant<int, long, double, std::string>;
 
// helper type for the visitor #4
template<class... Ts>
struct overloaded : Ts... { using Ts::operator()...; };
// explicit deduction guide (not needed as of C++20)
template<class... Ts>
overloaded(Ts...) -> overloaded<Ts...>;
 
int main()
{
    std::vector<value_t> vec = {10, 15l, 1.5, "hello"};
 
    for (auto& v: vec)
    {
        // 1. void visitor, only called for side-effects (here, for I/O)
        std::visit([](auto&& arg){ std::cout << arg; }, v);
 
        // 2. value-returning visitor, demonstrates the idiom of returning another variant
        value_t w = std::visit([](auto&& arg) -> value_t { return arg + arg; }, v);
 
        // 3. type-matching visitor: a lambda that handles each type differently
        std::cout << ". After doubling, variant holds ";
        std::visit([](auto&& arg)
        {
            using T = std::decay_t<decltype(arg)>;
            if constexpr (std::is_same_v<T, int>)
                std::cout << "int with value " << arg << '\n';
            else if constexpr (std::is_same_v<T, long>)
                std::cout << "long with value " << arg << '\n';
            else if constexpr (std::is_same_v<T, double>)
                std::cout << "double with value " << arg << '\n';
            else if constexpr (std::is_same_v<T, std::string>)
                std::cout << "std::string with value " << std::quoted(arg) << '\n';
            else
                static_assert(false, "non-exhaustive visitor!");
        }, w);
    }
 
    for (auto& v: vec)
    {
        // 4. another type-matching visitor: a class with 3 overloaded operator()'s
        // Note: The `(auto arg)` template operator() will bind to `int` and `long`
        //       in this case, but in its absence the `(double arg)` operator()
        //       *will also* bind to `int` and `long` because both are implicitly
        //       convertible to double. When using this form, care has to be taken
        //       that implicit conversions are handled correctly.
        std::visit(overloaded{
            [](auto arg) { std::cout << arg << ' '; },
            [](double arg) { std::cout << std::fixed << arg << ' '; },
            [](const std::string& arg) { std::cout << std::quoted(arg) << ' '; }
        }, v);
    }
}

輸出

10. After doubling, variant holds int with value 20
15. After doubling, variant holds long with value 30
1.5. After doubling, variant holds double with value 3
hello. After doubling, variant holds std::string with value "hellohello"
10 15 1.500000 "hello"

缺陷報告

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

缺陷報告	應用於	釋出時的行為	正確的行為
LWG 2970	C++17	過載 (1) 的返回型別未保留 INVOKE 操作結果的值類別 value category of the result of the INVOKE operation	保留
LWG 3052 (P2162R2)	C++17	若 Variants 中任何型別不是 std::variant，則效果未指定 in Variants is not a std::variant	已指定

參見

visit (C++26)	使用 variant 持有的引數呼叫提供的函式物件 (公開成員函式)
swap	與另一個 variant 交換 (公開成員函式)