std::visit

来自cppreference.com
< cpp‎ | utility‎ | variant
 
C++
 
工具库
通用工具
日期和时间
函数对象
格式化库 (C++20)
(C++11)
关系运算符 (C++20 中弃用)
整数比较函数
(C++20)(C++20)(C++20)
(C++20)
swap 与类型运算
(C++20)
(C++14)
(C++11)
(C++23)
(C++11)
(C++23)
(C++11)
(C++11)
(C++17)
常用词汇类型
(C++11)
(C++17)
(C++17)
(C++17)
(C++11)
(C++11)
(C++17)
(C++17)
(C++23)
初等字符串转换
(C++17)
(C++17)
(C++17)
 
std::variant
 
在标头 <variant> 定义
template <class Visitor, class... Variants>
constexpr /* 见下文 */ visit( Visitor&& vis, Variants&&... vars );
 (1) (C++17 起)
template <class R, class Visitor, class... Variants>
constexpr R visit( Visitor&& vis, Variants&&... vars );
 (2) (C++20 起)
template<class... Ts>
auto&& as-variant( std::variant<Ts...>& var );        // 仅用于阐述
 (3) (C++17 起)
template<class... Ts>
auto&& as-variant( const std::variant<Ts...>& var );  // 仅用于阐述
 (4) (C++17 起)
template<class... Ts>
auto&& as-variant( std::variant<Ts...>&& var );       // 仅用于阐述
 (5) (C++17 起)
template<class... Ts>
auto&& as-variant( const std::variant<Ts...>&& var ); // 仅用于阐述
 (6) (C++17 起)

应用观览器 vis（可以通过变化体中任意类型组合调用的可调用 (Callable) 对象）到一组变化体 vars。

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

1) 如同以 INVOKE(std::forward<Visitor>(vis),
       std::get<indices>(std::forward<VariantBases>(vars))...) 调用 vis，其中 indices 是 as-variant(vars).index()...。
2) 如同以 INVOKE<R>(std::forward<Visitor>(vis),
          std::get<indices>(std::forward<VariantBases>(vars))...) 调用 vis，其中 indices 是 as-variant(vars).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) 返回 var。
5,6) 返回 std::move(var)。

参数

vis - 接受每个变化体的每个可能可选项的可调用 (Callable) 对象
vars - 传递给观览器的变化体列表

返回值

1) INVOKE 操作的结果。返回类型是将 decltype 应用到结果上取得的类型。
2) 在 R 是（可有 cv 限定的）void 时没有返回值；否则返回 INVOKE<R> 操作的结果。

异常

在 as-variant(vars_i).valueless_by_exception() 对于 vars 中的某个变化体 vars_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 语句）。

在典型实现上，能认为调用 vis 的时间复杂度等于访问（可能多维的）数组中的元素，或执行 switch 语句的时间复杂度。

示例

运行此代码
#include <iomanip>
#include <iostream>
#include <string>
#include <type_traits>
#include <variant>
#include <vector>
 
// 要观览的变化体
using var_t = std::variant<int, long, double, std::string>;
 
// 观览器 #3 的辅助常量
template<class>
inline constexpr bool always_false_v = false;
 
// 观览器 #4 的辅助类型
template<class... Ts>
struct overloaded : Ts... { using Ts::operator()...; };
// 显式推导指引（C++20 起不需要）
template<class... Ts>
overloaded(Ts...) -> overloaded<Ts...>;
 
int main()
{
    std::vector<var_t> vec = {10, 15l, 1.5, "hello"};
 
    for (auto&& v: vec)
    {
        // 1. void 观览器，仅为它的副作用而调用
        std::visit([](auto&& arg){ std::cout << arg; }, v);
 
        // 2. 返回值的观览器，返回另一 variant 的常见模式
        var_t w = std::visit([](auto&& arg) -> var_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(always_false_v<T>, "观览器无法穷尽类型！");
        }, 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 时的效果 已指定

参阅

 与另一 variant 交换
(公开成员函数)
来自“https://zh.cppreference.com/mwiki/index.php?title=cpp/utility/variant/visit&oldid=77630”