std::variant

 

C++

编译器支持

独立和宿主

语言

标准库

标准库头文件

具名要求

特性测试宏 (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

访问

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... Types > class variant;		(自 C++17 起)

类模板 std::variant 表示类型安全的联合体。

variant 的实例在任何给定时间要么保持其备选类型之一的值，要么在错误的情况下 - 没有值（此状态很难实现，请参见 valueless_by_exception）。

与联合体一样，如果变体持有某种对象类型 T 的值，则 T 对象嵌套在 variant 对象内。

变体不允许持有引用、数组或 void 类型。

变体允许多次持有相同类型，以及持有相同类型的不同 cv 限定版本。

与聚合初始化期间联合体的行为一致，默认构造的变体持有其第一个备选类型的值，除非该备选类型不可默认构造（在这种情况下，变体也不可默认构造）。辅助类 std::monostate 可用于使此类变体可默认构造。

使用没有模板参数的 std::variant 定义实例化的程序是非良构的。可以使用 std::variant<std::monostate> 来代替。

如果程序声明 std::variant 的显式或部分特化，则程序是非良构的，无需诊断。

模板参数

Types

-

可能存储在此变体中的类型。所有类型都必须满足 Destructible 要求（特别是，不允许使用数组类型和非对象类型）。

成员函数

(构造函数)	构造 variant 对象 (公开成员函数)
(析构函数)	销毁 variant，以及其包含的值 (公开成员函数)
operator=	赋值 variant (公开成员函数)
观察器
index	返回 variant 持有的备选类型的从零开始的索引 (公开成员函数)
valueless_by_exception	检查 variant 是否处于无效状态 (公开成员函数)
修改器
emplace	在 variant 中就地构造一个值 (公开成员函数)
swap	与另一个 variant 交换 (公开成员函数)
访问
visit (C++26)	使用 variant 持有的参数调用提供的仿函数 (公开成员函数)

非成员函数

visit (C++17)	使用一个或多个 variant 持有的参数调用提供的仿函数 (函数模板)
holds_alternative (C++17)	检查 variant 当前是否持有给定类型 (函数模板)
get(std::variant) (C++17)	给定索引或类型（如果类型是唯一的）读取变体的值，错误时抛出异常 (函数模板)
get_if (C++17)	给定索引或类型（如果类型是唯一的），获取指向所指向的 variant 值的指针，错误时返回 null (函数模板)
operator==operator!=operator<operator<=operator>operator>=operator<=> (C++17)(C++17)(C++17)(C++17)(C++17)(C++17)(C++20)	比较 variant 对象，如同比较它们包含的值 (函数模板)
std::swap(std::variant) (C++17)	特化 std::swap 算法 (函数模板)

辅助类

monostate (C++17)	占位符类型，用作非默认构造类型的 variant 中的第一个备选类型 (类)
bad_variant_access (C++17)	在无效访问 variant 的值时抛出的异常 (类)
variant_sizevariant_size_v (C++17)	在编译时获取 variant 的备选类型列表的大小 (类模板) (变量模板)
variant_alternativevariant_alternative_t (C++17)	在编译时获取由索引指定的备选类型的类型 (类模板) (别名模板)
std::hash<std::variant> (C++17)	对 std::variant 的哈希支持 (类模板特化)

辅助对象

variant_npos (C++17)

处于无效状态的 variant 的索引 (常量)

注解

特性测试 宏	值	Std	特性
__cpp_lib_variant	201606L	(C++17)	std::variant: 类型安全的联合体
	202102L	(C++23) (DR17)	std::visit 用于从 std::variant 派生的类
	202106L	(C++23) (DR20)	完全 constexpr std::variant
	202306L	(C++26)	成员 visit

示例

运行此代码

#include <cassert>
#include <iostream>
#include <string>
#include <variant>
 
int main()
{
    std::variant<int, float> v, w;
    v = 42; // v contains int
    int i = std::get<int>(v);
    assert(42 == i); // succeeds
    w = std::get<int>(v);
    w = std::get<0>(v); // same effect as the previous line
    w = v; // same effect as the previous line
 
//  std::get<double>(v); // error: no double in [int, float]
//  std::get<3>(v);      // error: valid index values are 0 and 1
 
    try
    {
        std::get<float>(w); // w contains int, not float: will throw
    }
    catch (const std::bad_variant_access& ex)
    {
        std::cout << ex.what() << '\n';
    }
 
    using namespace std::literals;
 
    std::variant<std::string> x("abc");
    // converting constructors work when unambiguous
    x = "def"; // converting assignment also works when unambiguous
 
    std::variant<std::string, void const*> y("abc");
    // casts to void const* when passed a char const*
    assert(std::holds_alternative<void const*>(y)); // succeeds
    y = "xyz"s;
    assert(std::holds_alternative<std::string>(y)); // succeeds
}

可能的输出

std::get: wrong index for variant

缺陷报告

以下行为变更缺陷报告被追溯应用于先前发布的 C++ 标准。

DR	应用于	已发布行为	正确行为
LWG 2901	C++17	提供了 std::uses_allocator 的特化， 但 variant 无法正确支持分配器	特化已移除
LWG 3990	C++17	程序可以声明显式或 std::variant 的部分特化	在这种情况下，程序是非良构的 情况（无需诊断）
LWG 4141	C++17	存储的要求 分配令人困惑	包含的对象必须 嵌套在 variant 对象内

参见

in_placein_place_typein_place_indexin_place_tin_place_type_tin_place_index_t (C++17)	就地构造标签 (标签)
optional (C++17)	一个可能持有也可能不持有对象的包装器 (类模板)
any (C++17)	持有任何CopyConstructible 类型的实例的对象 (类)