std::visit

Defined in header `<variant>`
template <class Visitor, class... Variants> constexpr /see below/ visit(Visitor&& vis, Variants&&... vars);		(since C++17)

Applies the visitor vis to the variants vars

Effectively returns

std::invoke(std::forward<Visitor>(vis), std::get<is>(std::forward<Variants>(vars))...)

, where is... is vars.index()....

The call is ill-formed if the invocation above is not a valid expression of the same type and value category, for all combinations of alternative types of all variants.

Parameters

vis	-	a `Callable` that accepts every possible alternative from every variant
vars	-	list of variants to pass to the visitor

Return value

The value returned by the selected invocation of the visitor, converted to the common type of all possible std::invoke expressions.

Exceptions

Throws std::bad_variant_access if any variant in vars is valueless_by_exception.

Complexity

When the number of variants is zero or one, the invocation of the callable object is implemented in constant time, i.e. it does not depend on sizeof...(Types).

If the number of variants is larger than 1, the invocation of the callable object has no complexity requirements.

Example

Run this code

#include <variant>
#include <iostream>
#include <type_traits>
#include <iomanip>
#include <vector>
 
 
template<class T> struct always_false : std::false_type {};
 
using var_t = std::variant<int, long, double, std::string>;
 
template<class... Ts> struct overloaded : Ts... { using Ts::operator()...; };
template<class... Ts> overloaded(Ts...) -> overloaded<Ts...>;
 
int main() {
    std::vector<var_t> vec = {10, 15l, 1.5, "hello"};
    for(auto& v: vec) {
        // void visitor, only called for side-effects
        std::visit([](auto&& arg){std::cout << arg;}, v);
 
        // value-returning visitor. A common idiom is to return another variant
        var_t w = std::visit([](auto&& arg) -> var_t {return arg + arg;}, v);
 
        std::cout << ". After doubling, variant holds ";
        // type-matching visitor: can also be a class with 4 overloaded operator()'s
        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(always_false<T>::value, "non-exhaustive visitor!");
        }, w);
    }
 
    for (auto& v: vec) {
        std::visit(overloaded {
            [](int arg) { std::cout << arg << ' '; },
            [](long arg) { std::cout << arg << ' '; },
            [](double arg) { std::cout << arg << ' '; },
            [](const std::string& arg) { std::cout << std::quoted(arg) << ' '; },
        }, v);
    }
}

Output:

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.5 "hello"

Language
Standard library headers
Concepts
Utilities library
Strings library
Containers library
Algorithms library
Iterators library
Numerics library
Input/output library
Localizations library
Regular expressions library (C++11)
Atomic operations library (C++11)
Thread support library (C++11)
Filesystem library (C++17)
Technical Specifications

Type support (basic types, RTTI, type traits)
Dynamic memory management
Error handling
Program utilities
Variadic functions
Date and time
Function objects
initializer_list (C++11)
bitset
hash (C++11)
Relational operators
rel_ops::operator!=rel_ops::operator>rel_ops::operator<=rel_ops::operator>=
`optional`, `any` and `variant` (C++17)
optional
any
variant
in_placein_place_typein_place_indexin_place_tin_place_type_tin_place_index_t
Pairs and tuples
pair
tuple (C++11)
apply (C++17)
make_from_tuple (C++17)
piecewise_construct_t (C++11)
piecewise_construct (C++11)
integer_sequence (C++14)
Swap, forward and move
swap
exchange (C++14)
forward (C++11)
move (C++11)
move_if_noexcept (C++11)
Elementary string conversions
to_chars (C++17)
from_chars (C++17)
chars_format (C++17)
Type operations
declval (C++11)
as_const (C++17)