std::visit

Since C++17

Header: <variant>

std::visit invokes a Callable visitor with the currently active alternative or alternatives of one or more std::variant objects.

# Declarations

template< class Visitor, class... Variants >
constexpr /* see below */ visit( Visitor&& v, Variants&&... values );

(since C++17)

template< class R, class Visitor, class... Variants >
constexpr R visit( Visitor&& v, Variants&&... values );

(since C++20)

template< class... Ts >
auto&& as-variant( std::variant<Ts...>& value );

(exposition only*)

template< class... Ts >
auto&& as-variant( const std::variant<Ts...>& value );

(exposition only*)

template< class... Ts >
auto&& as-variant( std::variant<Ts...>&& value );

(exposition only*)

template< class... Ts >
auto&& as-variant( const std::variant<Ts...>&& value );

(exposition only*)

# Parameters

v: a Callable that accepts every possible alternative from every variant in Variants
values: list of variants to pass to the visitor

# Return value

The result of the INVOKE operation on the selected alternative combination. The deduced return type is decltype applied to that invocation result.
Nothing if R is cv-qualified void; otherwise, the result of the corresponding INVOKE<R> operation.

The exposition-only as-variant overloads conceptually normalize derived-from-std::variant arguments into the underlying variant type before dispatch.

# Exceptions

Throws std::bad_variant_access if any visited variant is currently valueless_by_exception.

Any exception thrown by invoking the selected visitor overload is propagated to the caller.

# Complexity

If zero or one variant argument is visited, dispatch is implemented in constant time with respect to the number of alternative types.
If more than one variant is visited, the standard imposes no complexity requirement on the dispatch itself.

# Notes

Let n be (1 * ... * std::variant_size_v<std::remove_reference_t<VariantBases>>), implementations usually generate a table equivalent to a (possibly multidimensional) array of n function pointers for every specialization of std::visit, which is similar to the implementation of virtual functions.

Implementations may also generate a switch statement with n branches for std::visit (e.g., the MSVC STL implementation uses a switch statement when n is not greater than 256).

On typical implementations, the time complexity of the invocation of v can be considered equal to that of access to an element in an (possibly multidimensional) array or execution of a switch statement.

# Feature-test macro

Macro	Value	Std	Feature
`__cpp_lib_variant`	`202102L`	C++23 (DR17)	`std::visit` supports classes derived from `std::variant`

# Example

#include <iomanip>
#include <iostream>
#include <string>
#include <type_traits>
#include <variant>
#include <vector>
 
// the variant to visit
using value_t = std::variant<int, long, double, std::string>;
 
// helper type for the visitor #4
template<class... Ts>
struct overloaded : Ts... { using Ts::operator()...; };
// explicit deduction guide (not needed as of 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 visitor, only called for side-effects (here, for I/O)
        std::visit([](auto&& arg){ std::cout << arg; }, v);
 
        // 2. value-returning visitor, demonstrates the idiom of returning another variant
        value_t w = std::visit([](auto&& arg) -> value_t { return arg + arg; }, v);
 
        // 3. type-matching visitor: a lambda that handles each type differently
        std::cout << ". After doubling, variant holds ";
        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(false, "non-exhaustive visitor!");
        }, w);
    }
 
    for (auto& v: vec)
    {
        // 4. another type-matching visitor: a class with 3 overloaded operator()'s
        // Note: The `(auto arg)` template operator() will bind to `int` and `long`
        //       in this case, but in its absence the `(double arg)` operator()
        //       *will also* bind to `int` and `long` because both are implicitly
        //       convertible to double. When using this form, care has to be taken
        //       that implicit conversions are handled correctly.
        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);
    }
}

# Defect reports

DR	Applied to	Behavior as published	Correct behavior
LWG 2970	C++17	the return type of overload (1) did not preserve the value category of the result of the `INVOKE` operation	preserves
LWG 3052 (P2162R2)	C++17	the effects were unspecified if any type in `Variants` is not a `std::variant`	specified

std::visit

# Declarations

# Parameters

# Return value

# Exceptions

# Complexity

# Notes

# Feature-test macro

# Example

# Defect reports

# See also