# optional, variant and any

> Three vocabulary types answer three different questions. optional is a value or nothing, variant is exactly one of a closed list, and any is one of an open set, checked at run time. Each has a precise rule for how it can be wrong, and those rules are the part worth knowing.

- **Source:** C++ Atlas (https://cppatlas.com/topics/optional-variant-any)
- **Track:** Library utilities
- **Estimated reading time:** 14 minutes
- **ISO C++ clauses:** [optional] (https://eel.is/c++draft/optional), [optional.observe] (https://eel.is/c++draft/optional.observe), [optional.comp.with.t] (https://eel.is/c++draft/optional.comp.with.t), [variant] (https://eel.is/c++draft/variant), [variant.ctor] (https://eel.is/c++draft/variant.ctor), [variant.assign] (https://eel.is/c++draft/variant.assign), [variant.mod] (https://eel.is/c++draft/variant.mod), [variant.visit] (https://eel.is/c++draft/variant.visit), [variant.get] (https://eel.is/c++draft/variant.get), [any] (https://eel.is/c++draft/any), [any.cons] (https://eel.is/c++draft/any.cons)
- **cppreference links:** [std::optional](https://en.cppreference.com/w/cpp/utility/optional), [std::variant](https://en.cppreference.com/w/cpp/utility/variant), [std::variant::valueless_by_exception](https://en.cppreference.com/w/cpp/utility/variant/valueless_by_exception), [std::visit](https://en.cppreference.com/w/cpp/utility/variant/visit), [std::any](https://en.cppreference.com/w/cpp/utility/any), [std::any_cast](https://en.cppreference.com/w/cpp/utility/any/any_cast)
- **Prerequisites:** copy-and-move, exceptions-and-stack-unwinding

## The one idea

These three types are all "a value that might be one of several things", and they differ in who knows the answer. With `optional<T>`, the type says the choices are a `T` or nothing. With `variant<A, B, C>`, the type lists every alternative, so the compiler can check that you handled all of them. With `any`, the type says nothing; only the object knows what it holds, and the check moves to run time.

All three store the value inside the object. None of them allocates for `optional` or `variant`; the standard forbids it. `any` is allowed to allocate and usually does for large types.

> **Mental model.** `optional` adds one state to a type, `variant` makes a tagged union you cannot misread, and `any` is a type-erased box that remembers only what it was constructed from.

The monadic operations of `optional` (`and_then`, `transform`, `or_else`) and `std::expected` belong to the topic on `optional-expected-and-error-codes`; this one is about the state model of each type.

## optional: engaged or empty

An `optional<T>` is either engaged, holding a `T`, or empty. The two ways to read it differ in what happens when you are wrong.

```cpp
#include <optional>
#include <cstdio>

int main() {
  std::optional<int> o;
  try {
    (void)o.value();             // throws std::bad_optional_access
  } catch (const std::bad_optional_access&) {
    std::puts("empty");
  }
  // *o;                         // undefined behavior: precondition is has_value()
  std::printf("%d\n", o.value_or(7));  // 7
}
```

`operator*` and `operator->` have the precondition that the optional is engaged, and violating it is undefined behavior. `value()` checks and throws `bad_optional_access`. Use `*` after a test, and `value()` or `value_or` when you do not want to prove it.

### Assignment follows the engaged states

Assigning to an optional does whatever the pair of states calls for. If both sides are engaged, the contained value is assigned. If the target is empty and the source is engaged, a value is constructed. If the target is engaged and the source is empty, the value is destroyed. If both are empty, nothing happens. Assigning a plain `T` works like the first two cases. `emplace` is different: it always destroys the old value first and then constructs the new one, so it needs no assignment operator.

```cpp
#include <optional>
#include <cstdio>

struct Noisy {
  Noisy() = default;
  Noisy(int) { std::puts("construct"); }
  Noisy& operator=(int) { std::puts("assign"); return *this; }
};

int main() {
  std::optional<Noisy> o;
  o = 1;   // construct: the optional was empty
  o = 2;   // assign: the optional was engaged
  o = {};  // destroys the value; o is empty again
}
```

### The `optional<bool>` trap

`optional` converts to `bool` to ask whether it is engaged, not what it holds. For `optional<bool>`, the two questions look identical and are not.

```cpp
#include <optional>
#include <cstdio>

int main() {
  std::optional<bool> flag = false;
  if (flag) std::puts("engaged");   // prints: the test is has_value()
  if (*flag) std::puts("true");     // does not print
}
```

The conversion is `explicit`, so `bool b = flag;` does not compile, but contexts such as `if`, `!` and `&&` still apply it. When the payload is a boolean, say `flag.has_value()` or `flag.value_or(false)` so the reader can tell which you meant.

### Comparisons

Comparing two optionals treats an empty one as smaller than any engaged one, and two empty ones as equal. Comparing an optional with a plain `T` compares the value if engaged, and an empty optional is less than every `T`.

```cpp
#include <optional>
#include <cstdio>

int main() {
  std::optional<int> n;                           // empty
  std::printf("%d %d %d\n", n < 0, n == 0, n < -1);  // 1 0 1
  std::printf("%d\n", n == std::nullopt);            // 1
}
```

Ordering is therefore total, which makes optionals usable as keys, but it can surprise: an empty optional is below `INT_MIN`.

## variant: a union that knows what it holds

A `variant<A, B, C>` holds exactly one alternative, and `index()` says which. A default-constructed variant holds a value-initialized first alternative, so if the first type has no default constructor, the variant does not either. The standard remedy is `std::monostate`, an empty type with all comparisons equal, placed first.

```cpp
#include <variant>
#include <string>
#include <cstdio>

struct NoDefault { NoDefault(int) {} };

int main() {
  std::variant<std::string, int> a;            // holds "" at index 0
  std::variant<std::monostate, NoDefault> b;   // OK because of monostate
  std::printf("%zu %zu\n", a.index(), b.index());  // 0 0
}
```

Duplicate alternatives are legal, but then the type-based accessors are ambiguous. You reach them with `in_place_index<N>` and `get<N>`.

### get, get_if and visit

`get<T>(v)` or `get<N>(v)` returns a reference and throws `bad_variant_access` if the variant holds something else. `get_if<T>(&v)` takes a pointer and returns a pointer, null on mismatch, so it fits in an `if` and cannot throw. `holds_alternative<T>(v)` only asks the question.

`std::visit` is the way to handle every alternative. It calls a callable with the held value, and the compiler requires that the callable accepts all of them.

```cpp
#include <variant>
#include <string>
#include <cstdio>

template <class... Ts> struct overloaded : Ts... { using Ts::operator()...; };

int main() {
  std::variant<int, std::string> v = std::string("hi");
  std::visit(overloaded{
    [](int i)                { std::printf("int %d\n", i); },
    [](const std::string& s) { std::printf("string %s\n", s.c_str()); },
  }, v);                                        // string hi
}
```

The `overloaded` idiom inherits every lambda's call operator, so overload resolution picks the arm. Since C++20 the deduction guide it needed in C++17 is generated automatically for aggregates. Adding a new alternative makes any visitor that does not cover it fail to compile, which is the reason to prefer `visit` over a chain of `holds_alternative` tests. All arms must return the same type unless you name one with `visit<R>` (C++20).

### The converting constructor

Initializing a variant from a value picks the alternative by overload resolution over an imaginary function `F(T_i)` for each alternative. Originally this admitted far too much: `variant<bool, string>` built from a string literal picked `bool`, because pointer-to-bool is a standard conversion and beat the user-defined conversion to `string`.

The fix, P0608R3 plus P1957R2 for the pointer case, was adopted for C++20 and is applied by current library implementations to older modes as well. Alternatives that would need a narrowing conversion are not candidates, and pointer-to-bool counts as narrowing.

```cpp
#include <variant>
#include <string>
#include <cstdio>

int main() {
  std::variant<bool, std::string> v = "hello";
  std::printf("%zu\n", v.index());   // 1: string; bool is not a candidate
  // std::variant<int, double> w = 1L;  // ill-formed: both conversions narrow
}
```

If two alternatives accept the argument equally well, there is no unique choice and the constructor is not available. `variant<int, int> v = 5;` is ill-formed for that reason; write `variant<int, int> v{std::in_place_index<0>, 5};`.

### valueless_by_exception

A variant has to hold something, but changing alternative is a destroy followed by a construct, and the construct can throw. With no allocation allowed, the old value cannot be kept, so the variant may end up in a state where it holds nothing. That is `valueless_by_exception()`. Then `index()` returns `variant_npos`, `get` throws `bad_variant_access`, and `visit` throws `bad_variant_access`.

```cpp
#include <variant>
#include <string>
#include <cstdio>

struct Bad {
  Bad(int) {}
  Bad(const Bad&) { throw 1; }
};

int main() {
  std::variant<std::string, Bad> v = "text";
  try { v = Bad{1}; } catch (int) {}
  std::printf("%d\n", v.valueless_by_exception());  // 1 with libstdc++
}
```

> **Standardese.** [variant.mod] and [variant.assign] say that if an exception is thrown while initializing the new alternative during `emplace` or a type-changing assignment, the variant might not hold a value. Move assignment between different alternatives, where the move constructor throws, is the case cppreference lists as always producing the valueless state. Implementations may avoid it by building a temporary first when the alternative's move is `noexcept`, so what the example prints is implementation behavior, not a promise.

The practical rule: keep alternatives nothrow-movable and valueless is nearly unreachable, and `std::visit` throwing on it is then a bug check rather than a case to handle.

## any: type erasure with a run-time check

`std::any` holds a copy of any copy-constructible value. It stores the decayed type, so `any a = "hello"` holds a `const char*`, not a `std::string`. The standard encourages implementations to keep small objects inside the `any` and avoid allocating, but does not require it, and what counts as small differs by library.

Copyability is a hard requirement because an `any` can itself be copied, and the copy must work for whatever it holds. That rules out `unique_ptr` and other move-only types, even if you never copy the `any`.

```cpp
#include <any>
#include <memory>
#include <string>
#include <cstdio>

int main() {
  std::any a = std::string("s");
  // std::any b = std::make_unique<int>(1);    // ill-formed: not copy-constructible
  std::printf("%d\n", std::any_cast<std::string>(&a) != nullptr);  // 1
  std::printf("%d\n", std::any_cast<int>(&a) != nullptr);          // 0
}
```

### any_cast has three shapes

`any_cast<T>(any&)` and `any_cast<T>(const any&)` return a value, and `any_cast<T&>` returns a reference. All of them throw `bad_any_cast` on a mismatch. The overload taking a pointer, `any_cast<T>(&a)`, returns a pointer and gives null on mismatch.

The match is exact, by dynamic type. There are no conversions, so an `any` holding an `int` does not yield a `long`, and one built from a literal does not yield a `std::string`.

```cpp
#include <any>
#include <string>
#include <cstdio>

int main() {
  std::any a = "hello";                  // holds const char*
  try {
    (void)std::any_cast<std::string>(a);
  } catch (const std::bad_any_cast&) {
    std::puts("bad_any_cast");           // printed
  }
  std::string s = std::any_cast<const char*>(a);  // OK: a const char* converts here
  std::printf("%s\n", s.c_str());
}
```

Use `any` when the set of types really is open, for example at a plugin boundary. If you can list the types, a `variant` is checked at compile time, cheaper, and cannot hold surprises.

## Choosing between them

| Need | Use |
| --- | --- |
| A value that may be absent | `optional<T>` |
| One of a known, closed set of types | `variant<...>` |
| An open set of types, checked at run time | `any` |
| Absent or an error value | `expected` (see the sibling topic) |

> **Pitfall.** `if (opt)` on an `optional<bool>`, and `get<T>(v)` on a variant that holds a different type, both compile and both do the wrong thing in a way tests with `true` data will not catch. Use `has_value()`, `get_if` and `visit`, which say what you mean.

## What to remember

- `optional`: `*o` on an empty optional is undefined behavior, `value()` throws `bad_optional_access`, and `value_or` supplies a fallback.
- Assigning an optional constructs, assigns or destroys according to which side is engaged; `emplace` destroys then constructs.
- `if (optional<bool>)` tests engagement, not the boolean. An empty optional compares less than every value and equal to `nullopt`.
- A default-constructed `variant` holds its first alternative, so use `monostate` first when that type has no default constructor.
- `get` throws on the wrong alternative, `get_if` returns null, and `visit` with an `overloaded` set checks at compile time that every alternative is handled.
- The converting constructor ignores narrowing candidates since the C++20 fix, so `variant<bool, string>` from a literal holds the string; ambiguous cases are ill-formed.
- A variant can become valueless after an exception during a type change; `index()` is then `variant_npos` and `visit` throws.
- `any` stores the decayed type and requires it to be copy constructible; `any_cast` matches the exact type, and the pointer form returns null instead of throwing.

## Concept Map Outline

- **optional, variant, any:** Three vocabulary types for a value that may be absent, one of a closed set, or anything.
  - **optional:** A T or nothing, stored inline with no allocation.
    - **Accessors:** operator* on an empty optional is undefined behavior; value() throws bad_optional_access.
    - **Assignment:** Constructs, assigns or destroys depending on which side is engaged; emplace destroys then constructs.
    - **optional<bool> trap:** if (opt) tests engagement, not the contained boolean.
    - **Comparisons:** An empty optional equals nullopt and is less than every value.
  - **variant basics:** Exactly one of a fixed list of alternatives, with index() saying which.
    - **Default construction:** Holds a value-initialized first alternative; put monostate first if that type has no default constructor.
    - **get versus get_if:** get throws bad_variant_access on mismatch; get_if takes a pointer and returns null.
    - **visit and overloaded:** visit with an overloaded lambda set forces every alternative to be handled at compile time.
  - **variant conversions:** How a value picks an alternative, and what happens when that goes wrong.
    - **Converting constructor:** Overload resolution over the alternatives; ties make the constructor unavailable.
    - **Narrowing excluded:** Since the C++20 fix, narrowing candidates are dropped, so a literal no longer picks bool.
    - **valueless_by_exception:** A throw during a type change can leave no value; index() is then variant_npos.
  - **any:** A type-erased box holding a copy of any copy-constructible value.
    - **Decayed storage:** any a = "hi" holds a const char*, not a std::string.
    - **Copy requirement:** The decayed type must be copy constructible, so move-only types are rejected.
    - **Small buffer:** Implementations are encouraged but not required to avoid allocating for small types.
    - **any_cast forms:** Value and reference forms throw bad_any_cast; the pointer form returns null.
  - **Choosing:** Pick by how much the type system knows about the alternatives.
    - **Closed set:** Use variant when you can list the types; it is checked at compile time.
    - **Open set:** Use any only when the types are genuinely unknown, and expect a run-time check.

## Standardese Quiz Questions

### Question 1 [warmup] ([optional.observe])

What does this program print?

```cpp
#include <optional>
#include <cstdio>

int main() {
  std::optional<bool> flag = false;
  if (flag) std::puts("A");
  if (flag.value()) std::puts("B");
}
```

A. Nothing
B. `A`
C. `B`
D. `A` then `B`

**Answer (B):** `A`

**Why:** The contextual conversion of an `optional` to `bool` reports whether it is engaged, and `flag` holds a value, so `A` is printed. `value()` returns the contained `false`, so `B` is not printed. The tempting answer is nothing, from reading `if (flag)` as testing the boolean inside.

### Question 2 [warmup] ([optional.observe])

Which statement about an empty `std::optional<int> o;` is correct?

A. `o.value()` throws `std::bad_optional_access`, while `*o` is undefined behavior
B. Both `o.value()` and `*o` throw `std::bad_optional_access`
C. `*o` returns a value-initialized `int`, and `o.value()` throws
D. Both `o.value()` and `*o` are undefined behavior

**Answer (A):** `o.value()` throws `std::bad_optional_access`, while `*o` is undefined behavior

**Why:** `operator*` has the precondition that the optional contains a value, so calling it on an empty optional is undefined behavior. `value()` is the checked accessor and throws `bad_optional_access`. Neither returns a default value; `value_or` is the accessor for that.

### Question 3 [warmup] ([variant.ctor])

What does this program print?

```cpp
#include <variant>
#include <string>
#include <cstdio>

int main() {
  std::variant<std::string, int> v;
  std::printf("%zu %zu\n", v.index(), std::get<0>(v).size());
}
```

A. `0 0`
B. `1 0`
C. It throws `std::bad_variant_access`
D. Undefined behavior: the variant is uninitialized

**Answer (A):** `0 0`

**Why:** A default-constructed variant holds a value-initialized first alternative, here an empty `std::string`, so the index is 0 and the size is 0. It is never empty and never holds an indeterminate `int` instead. If the first alternative were not default constructible, the variant would not be either.

### Question 4 [tricky] ([optional.comp.with.t])

What does this program print?

```cpp
#include <optional>
#include <cstdio>

int main() {
  std::optional<int> n;
  std::printf("%d%d%d\n", n < -1, n == 0, n > 0);
}
```

A. `000`, because comparing an empty optional is always false
B. `100`
C. `110`
D. Undefined behavior: `n` is empty

**Answer (B):** `100`

**Why:** An empty optional compares less than any value of `T`, so `n < -1` is true. `n == 0` is false because there is no value to equal 0, and `n > 0` is false because an empty optional is never greater than a value. The comparison operators do not dereference, so there is no undefined behavior.

### Question 5 [tricky] ([variant.ctor])

In C++20 mode, with a library that implements the P0608R3 and P1957R2 changes to the converting constructor, what does this print?

```cpp
#include <variant>
#include <string>
#include <cstdio>

int main() {
  std::variant<bool, std::string> v = "hello";
  std::printf("%zu\n", v.index());
}
```

A. `0`, because the array-to-pointer-to-bool conversion is a standard conversion
B. Ill-formed: the call is ambiguous
C. `1`
D. It throws `std::bad_variant_access`

**Answer (C):** `1`

**Why:** The converting constructor ignores alternatives that would need a narrowing conversion, and a pointer-to-bool conversion counts as narrowing. That leaves only `std::string`, so the index is 1. Before those changes `bool` won, because a standard conversion beats a user-defined one, which is the tempting answer.

### Question 6 [tricky] ([any.cons], [any.nonmembers])

What does this program print?

```cpp
#include <any>
#include <string>
#include <cstdio>

int main() {
  std::any a = "hello";
  try {
    std::string s = std::any_cast<std::string>(a);
    std::puts(s.c_str());
  } catch (const std::bad_any_cast&) {
    std::puts("bad");
  }
}
```

A. `hello`
B. `bad`
C. Ill-formed: `any` cannot hold a string literal
D. Undefined behavior: the cast reinterprets a `const char*`

**Answer (B):** `bad`

**Why:** An `any` stores the decayed type of its initializer, so `a` holds a `const char*`, not a `std::string`. `any_cast` requires an exact type match and performs no conversion, so it throws `bad_any_cast`. The cast `any_cast<const char*>(a)` would succeed.

### Question 7 [standardese] ([variant.ctor])

Is this program well-formed in C++23?

```cpp
#include <variant>

int main() {
  std::variant<int, int> v = 5;
  (void)v;
}
```

A. Yes; it holds alternative 0
B. Yes; it holds alternative 1, the last match
C. No: the converting constructor is not viable because no single alternative is selected
D. Yes, but the behavior is undefined when the variant is read

**Answer (C):** No: the converting constructor is not viable because no single alternative is selected

**Why:** The converting constructor selects an alternative by overload resolution over `F(int)` twice, which is ambiguous, so the constructor does not participate and the initialization is ill-formed. There is no tie-break by position. To pick an alternative explicitly use `std::in_place_index<0>`.

### Question 8 [standardese] ([any.cons])

Is this program well-formed in C++23?

```cpp
#include <any>
#include <memory>

int main() {
  std::any a = std::make_unique<int>(1);
  (void)a;
}
```

A. Yes; the `any` is simply not copyable
B. Yes; it holds a copy of the pointee
C. No: the decayed type must be copy constructible
D. Yes, but copying `a` later throws `bad_any_cast`

**Answer (C):** No: the decayed type must be copy constructible

**Why:** The converting constructor of `any` only participates when the decayed type is copy constructible, because the `any` itself must be copyable for whatever it holds. `unique_ptr<int>` is not, so no constructor is viable and the program is ill-formed. A move-only payload is rejected even if you never copy the `any`.
