When C++ evolved from a language dominated by raw pointers and manual memory management to one that embraces type safety and expressive abstractions, std::variant emerged as a key player in the type-safe union family. Introduced in C++17, std::variant allows you to store one of several specified types in a single variable, eliminating the dangers of void* or boost::variant without external dependencies. This article takes a deep dive into std::variant: its design principles, practical use cases, common pitfalls, and how it integrates seamlessly with other modern C++ features such as std::visit, std::optional, and structured bindings.
1. What is std::variant?
std::variant is a discriminated union—a compile‑time construct that can hold a value of one of several types. Unlike std::any, which stores type-erased values, std::variant retains compile‑time type information, enabling static checks and type‑safe visitation.
#include <variant>
#include <string>
#include <iostream>
std::variant<int, std::string> v = 42; // holds an int
v = std::string("hello"); // now holds a stringThe variant keeps a discriminant (an index) indicating the active type, and uses perfect forwarding to construct and destroy the contained object.
1.1 Value‑Semantic Guarantees
std::variant behaves like a value type: it supports copy/move construction and assignment, and its copy/move operations are exception‑safe. When copying, each alternative type’s copy constructor is invoked; if any throws, the original remains unchanged.
2. Common Operations
| Operation | Function | Description |
|---|---|---|
| Construct | variant<Ts...>(Ts&&...) |
Construct directly from a value of one of the alternatives. |
| Access | `std::get | |
(variant)orstd::get(variant)| Retrieve the contained value, throwingstd::bad_variant_access` if the wrong type is requested. |
||
| Index | variant.index() |
Get the active type index. |
| Alternative Count | variant::index() |
Compile‑time constant indicating the number of alternatives. |
| Visitor | std::visit(visitor, variant) |
Apply a callable to the active value. |
| Swap | v1.swap(v2) |
Swap two variants. |
| Default | variant() |
Default constructs to the first alternative if it is default‑constructible. |
2.1 The get Function
`std::get
` retrieves the stored value of type `T`. It is a compile‑time safe way to fetch the data, but beware of the exception if the variant holds a different type: “`cpp try { std::string s = std::get(v); } catch (const std::bad_variant_access&) { std::cerr << "Variant does not hold a string.\n"; } “` Alternatively, `std::get_if (&v)` returns a pointer or `nullptr` if the type is not active, enabling safer checks. — ## 3. Visitation: The Heart of Variant Processing Visitation is where `std::variant` shines. A visitor is any callable that accepts each alternative type. `std::visit` applies the visitor to the active alternative, invoking the appropriate overload. “`cpp struct Visitor { void operator()(int i) const { std::cout << "int: " << i << '\n'; } void operator()(const std::string& s) const { std::cout << "str: " << s << '\n'; } }; std::variant v = 99; std::visit(Visitor{}, v); “` ### 3.1 Lambda Visitors For quick inline visitors, use a lambda: “`cpp std::visit([](auto&& arg){ using T = std::decay_t; if constexpr (std::is_same_v) std::cout << "int: " << arg << '\n'; else if constexpr (std::is_same_v) std::cout << "str: " << arg << '\n'; }, v); “` The `if constexpr` guard allows branching based on the concrete type at compile time. ### 3.2 Overloaded Lambdas A common pattern uses a helper to combine multiple lambdas: “`cpp template struct overloaded : Ts… { using Ts::operator()…; }; template overloaded(Ts…) -> overloaded; std::visit(overloaded{ [](int i) { std::cout << "int: " << i << '\n'; }, [](const std::string& s) { std::cout << "str: " << s << '\n'; } }, v); “` This creates a single visitor with overloads for each alternative. — ## 4. Integrating Variant with Other Modern C++ Features ### 4.1 Combining with std::optional Sometimes you want an optional value that can be of several types. Wrap a variant inside an optional: “`cpp std::optional<std::variant> maybe = std::variant{42}; “` Visiting becomes: “`cpp if (maybe) { std::visit([](auto&& val){ std::cout << val; }, *maybe); } “` ### 4.2 Structured Bindings with std::variant C++17’s structured bindings can unpack the index and value: “`cpp auto [index, value] = std::visit([](auto&& val){ return std::make_tuple(std::type_index(typeid(val)), val); }, v); “` But this requires the visitor to return a pair. A more common use is to pair the variant with its index for debugging: “`cpp auto index = v.index(); if (index == 0) std::cout << "int\n"; else if (index == 1) std::cout << "string\n"; “` — ## 5. Common Pitfalls and How to Avoid Them | Pitfall | Why It Happens | Fix | |———|—————-|—–| | **Throwing `bad_variant_access`** | Accessing the wrong type. | Use `std::get_if` or `std::holds_alternative`. | | **Copying a Non‑Copyable Type** | Storing `std::unique_ptr` in a variant. | Use `std::unique_ptr` as an alternative; ensure the variant is move‑only. | | **Infinite Recursion** | Visitor that returns a variant containing itself. | Avoid recursive variants unless using indirection (e.g., `std::shared_ptr`). | | **Performance Overheads** | Unnecessary heap allocation due to large types. | Prefer small types or use `std::variant`; ensure alternatives are small. | — ## 6. Real‑World Use Cases ### 6.1 Expression Trees “`cpp struct Expr; using ExprPtr = std::shared_ptr ; struct IntLiteral { int value; }; struct Add { ExprPtr left, right; }; using Node = std::variant; struct Expr { Node node; }; “` Visiting evaluates or prints the expression: “`cpp int evaluate(const Expr& e) { return std::visit(overloaded{ [](const IntLiteral& lit){ return lit.value; }, [](const Add& a){ return evaluate(*a.left) + evaluate(*a.right); } }, e.node); } “` ### 6.2 Event Handling in GUIs “`cpp using Event = std::variant; void handleEvent(const Event& e) { std::visit(overloaded{ [](const KeyEvent& k){ /* process key */ }, [](const MouseEvent& m){ /* process mouse */ }, [](const ResizeEvent& r){ /* process resize */ } }, e); } “` — ## 7. Future Directions With C++20, `std::variant` gained `operator==` and `operator` overloads, making it trivially comparable if all alternatives support comparison. C++23 introduced `std::variant::apply` for more ergonomic visitation. The library continues to evolve, offering better integration with ranges, coroutines, and template metaprogramming. — ## 8. Conclusion `std::variant` is a powerful, type‑safe alternative to union-like structures. By coupling it with visitation, modern C++ programmers can write clear, maintainable code that handles multiple types without sacrificing safety or performance. Whether you’re building expression trees, event systems, or generic data containers, `std::variant` provides the expressive toolkit you need. Embrace it, and let your code be both type‑safe and expressive.</std::variant