Constrained Dynamic Types using Unions and std::variant

Often, we’ll come across scenarios where we need a variable to contain one of several possible data types. For example, we may need a variable that can store either an int or a float.

We could solve this problem with a class or struct, that simply stores our types as different members:

1struct Number {
2  int i;
3  float f;
4};

But this is a little wasteful of resources. Creating an object from this struct requires the compiler to allocate enough memory to store both an int and a float. But our use case doesn’t require that - we only need to store either an int or a float.

Allocating memory for the combination of all the types is unnecessary, and it gets increasingly wasteful when our struct is declaring more, or larger, types.

Instead, we could solve problems like these using unions.

Unions

The syntax of a union is very similar to that of a struct or class - we simply use the union keyword instead:

1union Number {
2  int i;
3  float f;
4};

We then construct and use a union type in the same way we would a class or struct:

1#include <iostream>
2
3union NumberUnion {
4  float f;
5  int i;
6};
7
8int main(){
9  NumberUnion Number;
10
11  Number.f = 9.8;
12  std::cout << "Float: " << Number.f;
13
14  Number.i = 42;
15  std::cout << "\nInt: " << Number.i;
16}

1Float: 9.8
2Int: 42

Unions can even have member functions, including constructors and destructors, although in practice that is rarely used.

The main purpose of a union is what we covered in the introduction - the ability to store a variable of a dynamic type, without using unnecessary memory.

Union Type Safety

Unions solve the memory problem by only allocating enough memory for one of the types we have in the declaration. If our types have different sizes, the compiler will allocate enough memory to store the largest type, to ensure any object we assign to the union can be accommodated.

This shared memory concept can be problematic. If the memory is currently being used to store one of the types in our union, but we access another type, problems can ensue.

Below, we’ve deleted a line of code from our previous example. As a result, we’re now accessing the int form of our variant, when what is stored in the memory address is intended to represent a float:

1#include <iostream>
2
3union NumberUnion {
4  float f;
5  int i;
6};
7
8int main(){
9  NumberUnion Number;
10
11  Number.f = 9.8;
12  std::cout << "Float: " << Number.f;
13
14  Number.i = 42; 
15  std::cout << "\nInt: " << Number.i;
16}

The compiler gives us no protection here - instead, our code just runs in a way that could be dangerously wrong:

1Float: 9.8
2Int: 1092406477

Because of this, the language’s native implementation of unions is not type-safe. We should instead use type-safe unions where possible.

Type-safe unions also use the fundamental shared-memory concept, but incorporate guard rails that make the category of bugs from our previous example much less likely to occur.

The standard library’s implementation of a type-safe union is std::variant, which is a template class we spend the rest of this lesson covering.

Constructing Variants

To construct a std::variant, we #include the <variant> header, and then invoke the template in the usual way. The arguments we pass to the template are the various types our variable can have. Within the std::variant, these types are referred to as alternatives.

Below, we create a variant that can contain an int, a float, or a bool.

1#include <variant>
2
3int main(){
4  std::variant<int, float, bool> MyVariant;
5}

When default-constructed, the initial state of the std::variant is set by default-constructing the first type in the template argument list.

In the above example, the initial state of MyVariant is derived from default-constructing an int. As such, it will contain an int with a value of 0.

If the first type in the template argument list is not default-constructible, the std::variant will also not be default-constructible:

1#include <variant>
2
3struct MyType {
4  MyType() = delete;
5};
6
7int main(){
8  std::variant<MyType, int, bool> MyVariant;
9}

1error: std::variant<MyType, int, bool> MyVariant;
2no appropriate default constructor available

We cover a workaround for this later in the lesson, using std::monostate.

Assigning Values

We can provide an initial type and value for our variant by passing it as a constructor argument. Below, our variant will be initialized as a float with a value of 9.8:

1#include <variant>
2
3int main(){
4  std::variant<int, float, bool> Variant{9.8f};
5}

We can update the variant, including its type if needed, using the basic assignment operator =:

1#include <variant>
2
3int main(){
4  std::variant<int, float, bool> Variant{9.8f};
5
6  Variant = 42;
7  Variant = true;
8}

Emplacing Values

We also have access to the emplace() method. Similar to other containers, emplace() constructs an object directly into our container.

With more complex types, this is more performant than constructing an object outside of the container, and then moving or copying it into the std::variant.

The emplace() method accepts the type we’re constructing as a template argument and a list of function arguments to forward to the constructor of that type:

1#include <variant>
2#include <string>
3
4class Character {
5public:
6  Character(std::string Name){/* ... */}
7};
8
9int main(){
10  std::variant<int, Character> Variant;
11  Variant.emplace<Character>("Roderick");
12}

Instead of passing a type as the template argument, we can alternatively pass a zero-based index. This index maps to the types we specified in the template arguments of our std::variant.

In this example, our std::variant template parameters are int followed by Character. So, int corresponds to the index 0 whilst Character corresponds to 1.

As such, the following example has updated our previous code by replacing the type name Character with the index 1, which results in the same behavior:

1#include <variant>
2#include <string>
3
4class Character {
5public:
6  Character(std::string Name){/* ... */}
7};
8
9int main(){
10  std::variant<int, Character> Variant;
11  Variant.emplace<1>("Roderick");
12}

Getting the Current Value

To retrieve the value in our std::variant, we use the std::get() function. We pass the type we expect to get as a template argument, and our variant as a function argument:

1#include <variant>
2#include <iostream>
3
4int main(){
5  std::variant<int, float, bool> Variant{9.8f};
6  std::cout << std::get<float>(Variant);
7}

19.8

This provides type safety as our program will ensure the type we passed as a template argument to std::get() matches the type currently stored in our variant.

If they don’t match, an exception is thrown. Below, we update our variant to contain an int, and then use it as if it were still holding a float:

1#include <variant>
2#include <iostream>
3
4int main(){
5  std::variant<int, float, bool> Variant{9.8f};
6  Variant = 2;
7
8  std::cout << std::get<float>(Variant);
9}

1Unhandled exception: std::bad_variant_access

Exception: std::bad_variant_access

The specific exception type that is thrown when access to a std::variant fails is std::bad_variant_access. We covered exceptions and how to handle them in a dedicated chapter earlier in the course:

Exceptions: throw, try and catch

This lesson provides an introduction to exceptions, detailing the use of throw, try, and catch.

Exception Types

Gain a thorough understanding of exception types, including how to throw and catch both standard library and custom exceptions in your code

Below, we use these techniques to catch and handle the std::bad_variant_access exception when we’re wrong about the type our std::variant is currently holding:

1#include <variant>
2#include <iostream>
3
4int main(){
5  std::variant<int, float, bool> Variant{9.8f};
6  Variant = 2;
7
8  try {
9    std::cout << std::get<float>(Variant);
10  } catch (const std::bad_variant_access& e) {
11    std::cout << "It wasn't storing a float";
12  }
13}

1It wasn't storing a float

Getting a Pointer

The std::get_if() function gives us a type-safe way to generate a pointer to the value stored in our variant. The function receives the type we’re expecting as a template argument, and the address of our variant as a function argument.

std::get_if() will not throw an exception if our type is incorrect. Instead, it will generate a nullptr which we can test for in the usual ways:

1#include <iostream>
2#include <variant>
3
4void Log(float* ptr){
5  if (ptr) {
6    std::cout << "Float: " << *ptr;
7  } else {
8    std::cout << "\nNot a float - got nullptr";
9  }
10}
11
12int main(){
13  std::variant<int, float, bool> Variant{9.8f};
14  Log(std::get_if<float>(&Variant));
15
16  Variant = 2;
17  Log(std::get_if<float>(&Variant));
18}

1Float: 9.8
2Not a float - got nullptr

Getting the Current Type

We can directly test if our variant is currently holding a specific type using the std::holds_alternative() function. It receives the type we want to test for as a template argument, and the variant we’re testing as a function argument:

1#include <variant>
2#include <iostream>
3
4int main(){
5  std::variant<int, float, bool> Variant{9.8f};
6  Variant = 2;
7
8  if (std::holds_alternative<int>(Variant)) {
9    std::cout << "It's holding an int";
10  }
11
12  if (!std::holds_alternative<float>(Variant)) {
13    std::cout << ", not a float";
14  }
15}

1It's holding an int, not a float

The index() Method

std::variant objects also have access to the index() method, which gives us an alternative way to understand what type it’s currently storing.

The value returned from index() is a numeric, zero-based index that corresponds to the argument list provided when constructing our std::variant.

In the following example, our variant initially holds an int. Given int is the first argument we provided to the template, index() returns 0.

When we update our variant to hold a float - the second index in our argument list - index() returns 1:

1#include <variant>
2#include <iostream>
3
4int main(){
5  std::variant<int, float, bool> Variant;
6  std::cout << "Index: " << Variant.index();
7  Variant = 3.14f;
8  std::cout << "\nIndex: " << Variant.index();
9}

1Index: 0
2Index: 1

The Visitor Pattern and std::visit()

The visitor pattern is a concept that involves separating algorithms from the objects those algorithms work on. This is easier to introduce with an example:

1#include <iostream>
2#include <variant>
3
4struct Visitor {
5  void operator()(int i){
6    std::cout << "It's an integer: " << i;
7  }
8
9  void operator()(float f){
10    std::cout << "It's a float: " << f;
11  }
12
13  void operator()(bool b){
14    std::cout << "It's a bool: " << b;
15  }
16};
17
18int main(){
19  std::variant<int, float, bool> Variant{3.14f};
20  std::visit(Visitor{}, Variant);
21}

1It's a float: 3.14

Here, we have a series of simple algorithms that log out different data types. These are defined within a Visitor struct. This struct overloads the () operator for various argument types.

Because of this overloading, if we create an object from this struct, we can use the () operator with that object. This effectively lets us use it like we would a function:

1struct Visitor {
2  void operator()(int i){ /*...*/ }
3};
4
5int main(){
6  Visitor FunctionObject;
7  FunctionObject(42);
8}

Such an object is called a function object or a functor. We cover this in more detail in our dedicated chapter on functions, later in the course.

Function Objects (Functors)

This lesson introduces function objects, or functors. This concept allows us to create objects that can be used as functions, including state management and parameter handling.

Looking back at our original code using std::visit(), we can note our Variant object can contain one of three types.

Additionally, the objects we create from our Visitor struct are "callable" with any of those types, as we’ve overloaded the () operator to handle each of them. Therefore, we can pass both of those objects to std::visit().

This allows our code to be decoupled - our function object and its algorithms aren’t dependent upon our variant, and our variant isn’t dependent upon our function object.

As such, they can both exist independently of the other. But, with the visitor pattern and std::visit(), they can also interact with each other to create more complex behaviors.

Comparing Variants

When two std::variant objects are the same type - that is, they have the same template parameter list - we can compare them using the standard suite of comparison operators, such as ==, <, and >=.

Additionally, when the two variants we are comparing are currently storing the same type - that is index() would return the same value for both variants - the comparison call is forwarded to that underlying type.

Below, we’re effectively comparing two floats:

1#include <iostream>
2#include <variant>
3
4int main(){
5  std::variant<int, float, bool> A{9.8f};
6  std::variant<int, float, bool> B{3.14f};
7  if (A > B) { std::cout << "A > B"; }
8}

1A > B

However, when two variants are not currently storing the same type, the behaviour is different, and somewhat unintuitive:

1#include <iostream>
2#include <variant>
3
4int main() {
5  if (9.0f == 9) {
6    std::cout << "9.0f == 9";
7  }
8
9  std::variant<int, float, bool> A{9.0f};
10  std::variant<int, float, bool> B{9};
11
12  if (A != B) {
13    std::cout << " but A != B";
14  }
15}

19.0f == 9 but A != B

Specifically, when the index() method of two variants returns different values, the comparison operators compare those indices.

Below, variant A is storing a float, which is index 1. Variant B is storing an int, which is index 0. As such, A is "greater than" B:

1#include <iostream>
2#include <variant>
3
4int main(){
5  std::variant<int, float, bool> A{9.8f};
6  std::variant<int, float, bool> B{10};
7  if (A > B) { std::cout << "A > B"; }
8}

1A > B

Default Construction and std::monostate

Earlier in this lesson, we saw how a std::variant could not be default-constructed if the first type in its template argument list is not default-constructible.

Sometimes, we need a way to bypass that. One option is to simply include an additional, default-constructible type as the first argument.

Any type could work, but std::monostate was specifically introduced for this purpose. It’s a simple type, which is widely understood to denote an "empty" type for use in variants:

1#include <variant>
2
3struct T1 {
4  T1() = delete;
5};
6
7struct T2 {
8  T2() = delete;
9};
10
11int main(){
12  std::variant<std::monostate, T1, T2> Variant;
13}

std::monostate is a type like any other. As such, we have to account for its existence when using methods like index(). Similarly, when using the visitor pattern, our callable needs to be able to handle the possibility that our variant is "empty":

1#include <iostream>
2#include <variant>
3
4struct T {
5  T() = delete;
6};
7
8struct Visitor {
9  void operator()(const std::monostate&){
10    std::cout << "It's empty";
11  }
12
13  void operator()(const T&){
14    std::cout << "It's a T";
15  }
16};
17
18int main(){
19  std::variant<std::monostate, T> Variant;
20  std::visit(Visitor{}, Variant);
21}

1It's empty

Valueless Variants By Exception

In addition to the std::monostate scenario, our variants can also become "valueless" by way of an exception. This is sometimes caused when an exception is thrown in the process of updating our variant’s value.

In this valueless state, std::get() and std::visit() will throw a std::bad_variant_access exception. Additionally, the index() method will return an object that is equal to std::variant_npos.

The valueless_by_exception() method lets us specifically test for this scenario, returning true if we’re in the error state.

The following example creates this situation by throwing an exception during an emplace() call:

1#include <variant>
2#include <iostream>
3
4struct GetInt {
5  operator int(){ throw 0; }
6};
7
8int main(){
9  std::variant<int> Variant;
10  try {
11    Variant.emplace<int>(GetInt());
12  } catch (...) { }
13
14  if (Variant.valueless_by_exception()) {
15    std::cout << "Variant is valueless";
16  }
17
18  if (Variant.index() == std::variant_npos) {
19    std::cout << "\nindex() returned npos";
20  }
21
22  try {
23    std::get<int>(Variant); 
24  }  catch (const std::bad_variant_access& e) {
25    std::cout << "\nstd::get threw exception";
26  }
27
28  Variant = 3;
29  if (!Variant.valueless_by_exception()) {
30    std::cout << "\n\nVariant has a value now";
31  }
32}

1Variant is valueless
2index() returned npos
3std::get threw exception
4
5Variant has a value now

Variant Type Traits

When creating advanced templates for use with variants, the <variant> header includes two type traits we may find useful. These type traits follow the same principles and patterns as those that we covered earlier in the course:

Type Traits: Compile-Time Type Analysis

Learn how to use type traits to perform compile-time type analysis, enable conditional compilation, and enforce type requirements in templates.

std::variant_size()

The std::variant_size() type trait returns the number of types (or "alternatives") a variant type supports. If our variant includes a std::monostate type, this is included in the count.

To access this count, we pass the type as a template argument and then access the static value variable of the generated struct.

Alternatively, we can access the value directly using std::variant_size_v. The following two expressions are equivalent:

1template <typename T>
2void Handle(T Variant){
3  std::variant_size<T>::value;
4  std::variant_size_v<T>;
5}

Below, we show this in use by instantiating a template with the std::variant<int, float, bool> type as an argument:

1#include <variant>
2#include <iostream>
3
4template <typename T>
5void Handle(T Variant){
6  std::cout << "Number of alternatives: "
7    << std::variant_size_v<T>;
8}
9
10int main(){
11  std::variant<int, float, bool> Variant;
12  Handle(Variant);
13}

1Number of alternatives: 3

std::variant_alternative()

The std::variant_alternative type trait lets us determine each alternative type in our variant’s template parameter list. We pass two template arguments:

• The zero-based index of the alternative we want to check
• The type of the variant

As usual, the type is available within the type static member, or directly using the std::variant_alternative_t shortcut.

Below, we get the first, second, and third alternatives of the variant type that was used to instantiate our template:

1template <typename T>
2void Handle(T Variant) {
3  std::variant_alternative<0, T>::type;
4  std::variant_alternative_t<1, T>;
5  std::variant_alternative_t<2, T>;
6}

When using this, we also typically need to use the std::variant_size type trait, to discover how many alternatives there are.

In the following example, we get the type of the last alternative in our variant. Given the indexing is zero-based, the last index is one less than the size of the alternative list:

1template <typename T>
2void Handle(T Variant){
3  std::variant_alternative_t<
4    std::variant_size_v<T> - 1, T>;
5}

This evaluation is performed at compile time, and we are free to use any other compile-time logic to build more complex behaviour. This can include C++20 concepts or other type traits.

Below, we use std::variant_alternative with some of the other type traits we introduced earlier in the course, such as std::is_same, std::is_arithmetic, and std::is_convertible.

This lets us discover some characteristics of the std::variant<int, float, bool> that was used to invoke our template:

1#include <variant>
2#include <iostream>
3
4template <typename T>
5void Handle(T Variant){
6  if constexpr (std::is_same_v<
7    std::variant_alternative_t<0, T>, int>) {
8    std::cout << "The first type is an int";
9  }
10  if constexpr (std::is_arithmetic_v<
11    std::variant_alternative_t<1, T>>) {
12    std::cout <<
13      "\nThe second is arithmetic";
14  }
15  if constexpr (std::is_convertible_v<
16    std::variant_alternative_t<2, T>, int>) {
17    std::cout <<
18      "\nThe third is convertible to an int";
19  }
20}
21
22int main(){
23  std::variant<int, float, bool> Variant;
24  Handle(Variant);
25}

1The first type is an int
2The second is arithmetic
3The third is convertible to an int

Summary

This lesson provides an in-depth look at using unions and std::variant in C++ to store dynamic data types. Key takeaways include:

• Unions allow storing different data types in the same memory location, but are not type-safe
• std::variant is a type-safe alternative to unions that can store one value from a specified list of types
• Variants can be constructed, assigned values, and accessed using various methods like std::get(), std::get_if(), std::holds_alternative(), and the visitor pattern with std::visit()
• Special cases like valueless variants and using std::monostate for default construction are covered
• Variant type traits std::variant_size and std::variant_alternative provide compile-time information about variant types

Next Lesson

Void Pointers and std::any

Learn how to use void pointers and std::any to implement unconstrained dynamic types, and understand when they should be used

ContinueView Course