std::variant

 

C++

Поддержка компилятором

Автономные и размещённые реализации

Язык

Заголовки стандартной библиотеки

Требования к именованию

Макросы тестирования функциональности (C++20)

Поддержка языка

Библиотека концептов (C++20)

Библиотека диагностики

Библиотека общих утилит

Библиотека строк

Библиотека контейнеров

Библиотека итераторов

Библиотека диапазонов (C++20)

Библиотека алгоритмов

Библиотека численных данных

Библиотека ввода/вывода

Библиотека локализаций

Регулярные выражения (C++11)

Атомарные операции (C++11)

Библиотека поддержки потоков (C++11)

Библиотека файловой системы (C++17)

Технические спецификации

Указатель символов

Внешние библиотеки

 

Библиотека утилит

Поддержка языка Поддержка типа (базовые типы, RTTI, свойства типов)     Макросы тестирования функциональности библиотеки (C++20) Управление динамической памятью Программные утилиты Обработка ошибок Поддержка сопрограмм (C++20) Вариативные функции launder (C++17) initializer_list (C++11) source_location (C++20) Трёхстороннее сравнение (C++20) 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_neqis_ltis_lteqis_gtis_gteq (C++20)(C++20)(C++20)(C++20)(C++20)(C++20)

Общие утилиты Дата и время Объекты функции bitset Библиотека форматирования (C++20) hash (C++11) integer_sequence (C++14) Операторы отношения (устарело в 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) forward (C++11) move (C++11) move_if_noexcept (C++11) as_const (C++17) to_underlying (C++23) Общие лексические типы pair tuple (C++11) apply (C++17) make_from_tuple (C++17) optional (C++17) any (C++17) variant (C++17) Элементарные преобразования строк to_chars (C++17) from_chars (C++17) chars_format (C++17) Stacktrace stacktrace_entry (C++23) basic_stacktrace (C++23)

 

std::variant

Функции-элементы

variant::variant

variant::~variant

variant::operator=

Наблюдатели

variant::index

variant::valueless_by_exception

Модификаторы

variant::emplace

variant::swap

Функции, не являющиеся элементами

visit

holds_alternative

get

get_if

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

swap

Вспомогательные классы

monostate

bad_variant_access

variant_size

variant_alternative

hash

Вспомогательные объекты

variant_npos

 

Определено в заголовочном файле <variant>
template <class... Types> class variant;		(начиная с C++17)

Шаблон класса std::variant представляет типобезопасное объединение. Экземпляр std::variant в любой момент времени либо содержит значение одного из его альтернативных типов, либо, в случае ошибки, не содержит значения (этого состояния трудно достичь, смотрите valueless_by_exception).

Как и в случае с объединениями, если variant содержит значение некоторого объекта типа T, объектное представление T выделяется непосредственно внутри объектного представления самого variant. Variant не позволяет выделять дополнительную (динамическую) память.

variant не может содержать ссылки, массивы или тип void. Пустой variant также имеет неправильный формат (вместо него можно использовать (std::variant<std::monostate>).

variant может содержать один и тот же тип более одного раза и содержать разные версии одного и того же типа с cv-квалификацией.

В соответствии с поведением объединений во время агрегатной инициализации, variant, созданный по умолчанию, содержит значение своей первой альтернативы, если только эта альтернатива не является конструируемой по умолчанию (в этом случае variant тоже не является конструируемым по умолчанию). Вспомогательный класс std::monostate может использоваться, чтобы сделать такой variant конструируемым по умолчанию.

Параметры шаблона

Types

—

типы, которые могут храниться в этом variant. Все типы должны соответствовать требованиям Destructible (в частности, типы массивов и типы, не являющиеся объектами, не допускаются).

Функции элементы

(конструктор)	создаёт объект variant (public функция-элемент)
(деструктор)	уничтожает variant вместе с содержащимся в нём значением (public функция-элемент)
operator=	присваивает variant (public функция-элемент)
Наблюдатели
index	возвращает отсчитываемый от нуля индекс альтернативы, удерживаемой variant (public функция-элемент)
valueless_by_exception	проверяет, находится ли variant в недопустимом состоянии (public функция-элемент)
Модификаторы
emplace	создаёт значение в variant на месте (public функция-элемент)
swap	меняет местами с другим variant (public функция-элемент)

Функции, не являющиеся элементами

visit (C++17)	вызывает предоставленный функтор с аргументами, содержащимися в одном или нескольких variant’ах (шаблон функции)
holds_alternative (C++17)	проверяет, имеет ли variant в настоящее время данный тип (шаблон функции)
std::get(std::variant) (C++17)	читает значение variant по индексу или типу (если тип уникален), бросает ошибку (шаблон функции)
get_if (C++17)	получает указатель на значение указанного variant по индексу или типу (если он уникален), возвращает ноль при ошибке (шаблон функции)
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_size variant_size_v (C++17)	получает размер списка альтернатив во время компиляции (шаблон класса) (шаблонная переменная)
variant_alternative variant_alternative_t (C++17)	получает тип альтернативы, указанный её индексом, во время компиляции (шаблон класса) (псевдоним шаблона)
std::hash<std::variant> (C++17)	специализация алгоритма std::hash (специализация шаблона класса)

Вспомогательные объекты

variant_npos (C++17)	индекс variant в недопустимом состоянии (константа)

Пример

Запустить этот код

#include <variant>
#include <string>
#include <cassert>
#include <iostream>
 
int main()
{
    std::variant<int, float> v, w;
    v = 42; // v содержит int
    int i = std::get<int>(v);
    assert(42 == i); // успешно
    w = std::get<int>(v);
    w = std::get<0>(v); // тот же эффект, что и в предыдущей строке
    w = v; // тот же эффект, что и в предыдущей строке
 
//  std::get<double>(v); // ошибка: нет double в [int, float]
//  std::get<3>(v);      // ошибка: допустимые значения индекса 0 и 1
 
    try {
      std::get<float>(w); // w содержит int, а не float: будет брошено исключение
    }
    catch (const std::bad_variant_access& ex) {
      std::cout << ex.what() << '\n';
    }
 
    using namespace std::literals;
 
    std::variant<std::string> x("abc");
    // конвертирующие конструкторы работают, когда есть однозначность
    x = "def"; // конвертирующее присваивание также работает, когда однозначно
 
    std::variant<std::string, void const*> y("abc");
    // преобразуется в void const * при передаче char const *
    assert(std::holds_alternative<void const*>(y)); // успешно
    y = "xyz"s;
    assert(std::holds_alternative<std::string>(y)); // успешно
}

Возможный вывод:

std::get: неверный индекс для variant

Отчёты о дефектах

Следующие изменения поведения были применены с обратной силой к ранее опубликованным стандартам C++:

Номер	Применён	Поведение в стандарте	Корректное поведение
LWG 2901	C++17	предоставлена специализация std::uses_allocator, но variant не поддерживает должным образом аллокаторы	специализация удалена

Смотрите также

in_place in_place_type in_place_index in_place_t in_place_type_t in_place_index_t (C++17)	метка конструирования на месте (шаблон класса)
optional (C++17)	обёртка, которая может содержать или не содержать объект (шаблон класса)
any (C++17)	объекты, содержащие экземпляры любого CopyConstructible типа. (класс)