close

std::visit

来自cppreference.com
 
C++
 
工具库
通用工具
关系运算符 (C++20 弃用)
 
std::variant
 
在标头 <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) (仅用于阐述*)

向一组变体 values 应用探访器 v（可以以变体中类型的任意组合调用的可调用 (Callable) 对象）。

给定 VariantBases 为 decltype(as-variant(std::forward<Variants>(values))...（包含 sizeof...(Variants) 个类型的包）：

1) 如同以 INVOKE(std::forward<Visitor>(v),
std::get<indices>(std::forward<VariantBases>(values))...) 调用 v，其中 indices 是 as-variant(vars).index()...。
2) 如同以 INVOKE<R>(std::forward<Visitor>(v),
std::get<indices>(std::forward<VariantBases>(values))...) 调用 v，其中 indices 是 as-variant(values).index()...。

这些重载只有在 VariantBases 中的每个类型都合法时才会参与重载决议。如果由 INVOKE 或 INVOKE<R>(C++20 起) 表示的表达式非法，或者 INVOKE 或 INVOKE<R>(C++20 起) 的结果在对于不同的 indices 会有不同的类型或值类别，那么程序非良构。

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 - 接受 Variants 中每个变体的每个可能可选项的可调用 (Callable) 对象
values - 传递给探访器的变体列表

返回值

1) INVOKE 操作的结果。返回类型是将 decltype 应用到结果上取得的类型。
2) 在 R 是（可有 cv 限定的）void 时没有返回值；否则返回 INVOKE<R> 操作的结果。
3-6) 从 value 转换而成的 std::variant 值。

异常

在 as-variant(value_i).valueless_by_exception() 对于 values 中的任何变体 value_i 是 true 时抛出 std::bad_variant_access。

复杂度

当变体的数量为零或一时，可调用对象的调用在常数时间内实现；即它不取决于变体中能存储的类型数量。

如果变体的数量大于一，那么可调用对象的调用没有复杂度要求。

注解

令 n 为 (1 * ... * std::variant_size_v<std::remove_reference_t<VariantBases>>)，实现通常会为每个 std::visit 的特化生成等价于有 n 个函数指针的（可能多维的）数组的一张表，这与虚函数的实现类似。

实现亦可能为 std::visit 生成有 n 个分支的 switch 语句（例如 MSVC STL 实现在 n 不大于 256 时使用 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>

// 要探访的变体
using value_t = std::variant<int, long, double, std::string>;

// 探访器 #4 的辅助类型
template<class... Ts>
struct overloaded : Ts... { using Ts::operator()...; };
// 显式推导指引（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 探访器，仅为它的副作用而调用
        std::visit([](auto&& arg){ std::cout << arg; }, v);
        
        // 2. 返回值的探访器，演示返回另一变体的常见惯用法
        value_t w = std::visit([](auto&& arg) -> value_t { return arg + arg; }, v);
        
        // 3. 类型匹配探访器：以不同方式处理每个类型的 lambda
        std::cout << "。翻倍后，变体持有";
        std::visit([](auto&& arg)
        {
            using T = std::decay_t<decltype(arg)>;
            if constexpr (std::is_same_v<T, int>)
                std::cout << "值为 " << arg << " 的 int\n";
            else if constexpr (std::is_same_v<T, long>)
                std::cout << "值为 " << arg << " 的 long\n";
            else if constexpr (std::is_same_v<T, double>)
                std::cout << "值为 " << arg << " 的 double\n";
            else if constexpr (std::is_same_v<T, std::string>)
                std::cout << "值为 " << std::quoted(arg) << " 的 std::string\n";
            else 
                static_assert(false, "探访器无法穷尽类型！");
        }, w);
    }

    for (auto&& v: vec)
    {
        // 4. 另一种类型匹配探访器：有三个重载的 operator() 的类
        // 注：此情况下 '(auto arg)' 模板 operator() 将绑定到 'int' 与 'long'，
        //    但它不存在时 '(double arg)' operator() *也会* 绑定到 'int' 与 'long'，
        //    因为两者均可隐式转换到 double。使用此形式时应留心以正确处理隐式转换。
        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。翻倍后，变体持有值为 20 的 int
15。翻倍后，变体持有值为 30 的 long
1.5。翻倍后，变体持有值为 3 的 double
hello。翻倍后，变体持有值为 "hellohello" 的 std::string
10 15 1.500000 "hello"

缺陷报告

下列更改行为的缺陷报告追溯地应用于以前出版的 C++ 标准。

缺陷报告 应用于 出版时的行为 正确行为
LWG 2970 C++17 重载 (1) 的返回类型没有保留 INVOKE 操作的结果的值类别 保留值类别
LWG 3052
(P2162R2) 		C++17 未指定在 Variants 中的有类型不是 std::variant 时的效果 已指定

参阅

(C++26)
 以 variant 所保有的实参调用提供的函数对象
(公开成员函数) [编辑]
与另一 variant 交换
(公开成员函数) [编辑]