--- title: "variant" --- {{< callout type="info">}} Header: `variant.h` Similar to: `std::variant` For C++11 and above. {{< /callout >}} ```cpp template class variant ``` A variadic class that can contain one a several specified types in a type safe manner. Accepts functors, `etl::overload` and `etl::visitor` types as visitor callbacks. Accepts `etl::visit` since `20.28.0`. ## Error exception types ```cpp class variant_exception ``` **Description** The base for all variant exceptions. Derived from `etl::exception`. --- ```cpp class variant_incorrect_type_exception ``` **Description** The error types emitted when a non-supported type is requested from the variant. ## Construction ```cpp ETL_CONSTEXPR14 variant() ``` **Description** Default constructor. --- ```cpp template ETL_CONSTEXPR14 variant(T&& value) ``` **Description** Constructor from a value. --- ```cpp template ETL_CONSTEXPR14 explicit variant(etl::in_place_type_t, TArgs&&... args) ``` **Description** Construct T from arguments. --- ```cpp template ETL_CONSTEXPR14 explicit variant(etl::in_place_index_t, TArgs&&... args) ``` **Description** Construct from Index using args. --- ```cpp template ETL_CONSTEXPR14 explicit variant(etl::in_place_type_t, std::initializer_list init, TArgs&&... args) ``` **Description** Construct from type, `initializer_list` and arguments. --- ```cpp template ETL_CONSTEXPR14 explicit variant(etl::in_place_index_t, std::initializer_list init, TArgs&&... args) ``` **Description** Construct from `Index`, initializer_list and arguments. --- ```cpp ETL_CONSTEXPR14 variant(const variant& other) ``` **Description** Copy constructor. --- ```cpp ETL_CONSTEXPR14 variant(variant&& other) ``` **Description** Move constructor. ## Operations ```cpp template T& emplace(TArgs&&... args) ``` **Description** Set to type `T` using the construction parameters args. --- ```cpp template variant& operator =(T&& value) ``` **Description** --- ```cpp variant& operator =(const variant& other) ``` **Description** Copies other to the current variant. --- ```cpp variant& operator =(variant&& other) ``` **Description** Moves other to the current variant. --- ```cpp constexpr bool valueless_by_exception() const noexcept ``` **Description** Returns `true` if the type id is `etl::variant_npos`. --- ```cpp constexpr size_t index() const noexcept ``` **Description** Returns the index of the type contained in the variant. Returns `etl::variant_npos` if the variant does not hold a valid type. --- ```cpp void swap(variant& rhs) noexcept ``` **Description** Swaps rhs with the current variant. ## Access **Non-member functions** ### get ```cpp template ETL_CONSTEXPR14 etl::variant_alternative_t>& get(etl::variant& v) ``` **Description** Get the value based on `Index`. If `Index` matches the current index of the variant, returns a reference to the stored value, otherwise, asserts `etl::variant_incorrect_type_exception`. **Parameters** A reference to a variant. --- ```cpp template ETL_CONSTEXPR14 etl::variant_alternative_t>&& get(etl::variant&& v) ``` **Description** Get the value based on `Index`. If `Index` matches the current index of the variant, returns a reference to the stored value, otherwise, asserts `etl::variant_incorrect_type_exception`. **Parameters** An rvalue reference to a variant. --- ```cpp template ETL_CONSTEXPR14 const etl::variant_alternative_t>& get(const etl::variant& v) ``` **Description** Get the value based on `Index`. If `Index` matches the current index of the variant, returns a reference to the stored value, otherwise, asserts `etl::variant_incorrect_type_exception`. **Parameters** A const reference to a variant. --- ```cpp template ETL_CONSTEXPR14 const etl::variant_alternative_t>&& get(const etl::variant&& v) ``` **Description** Get the value based on `Index`. If `Index` matches the current index of the variant, returns a reference to the stored value, otherwise, asserts `etl::variant_incorrect_type_exception`. **Parameters** A const rvalue reference to a variant. --- ```cpp template ETL_CONSTEXPR14 T& get(etl::variant& v) ``` **Description** Get the value based on `T`. If `T` matches the current type stored in the variant, returns a reference to the stored value, otherwise, asserts `etl::variant_incorrect_type_exception`. **Parameters** A reference to a variant. --- ```cpp template ETL_CONSTEXPR14 T&& get(etl::variant&& v) ``` **Description** Get the value based on `T`. If `T` matches the current type stored in the variant, returns a reference to the stored value, otherwise, asserts `etl::variant_incorrect_type_exception`. **Parameters** An rvalue reference to a variant. --- ```cpp template ETL_CONSTEXPR14 const T& get(const etl::variant& v) ``` **Description** Get the value based on `T`. If `T` matches the current type stored in the variant, returns a reference to the stored value, otherwise, asserts `etl::variant_incorrect_type_exception`. **Parameters** A const reference to a variant. --- ```cpp template ETL_CONSTEXPR14 const T&& get(const etl::variant&& v) ``` **Description** Get the value based on `T`. If `T` matches the current type stored in the variant, returns a reference to the stored value, otherwise, asserts `etl::variant_incorrect_type_exception`. **Parameters** A const rvalue reference to a variant. ### get_if ```cpp template ETL_CONSTEXPR14 etl::add_pointer_t>> get_if(etl::variant* pv) noexcept ``` **Description** Get the value based on `Index`. If `Index` matches the current index of the variant, returns a pointer to the stored value, otherwise returns `nullptr`. **Parameters** A pointer to a variant. --- ```cpp template ETL_CONSTEXPR14 etl::add_pointer_t>> get_if(const etl::variant* pv) noexcept ``` **Description** Get the value based on `Index`. If `Index` matches the current index of the variant, returns a const pointer to the stored value, otherwise returns `nullptr`. **Parameters** A const pointer to a variant. --- ```cpp template ETL_CONSTEXPR14 etl::add_pointer_t get_if(etl::variant* pv) noexcept ``` **Description** Get the value based on `T`. If `T` matches the current type stored in the variant, returns a pointer to the stored value, otherwise return `nullptr`. **Parameters** An pointer to a variant. --- ```cpp template ETL_CONSTEXPR14 etl::add_pointer_t get_if(const etl::variant* pv) noexcept ``` **Description** Get the value based on `T`. If `T` matches the current type stored in the variant, returns a const pointer to the stored value, otherwise return `nullptr`. **Parameters** An const pointer to a variant. ## Other ```cpp struct monostate ``` **Description** A default constructible type. For use as the first state to turn a non-default constructible variant into a default constructible variant. --- ```cpp template void swap(etl::variant& lhs, etl::variant& rhs) ``` **Description** Swaps lhs and rhs. --- ```cpp template struct variant_size> ``` **Description** The member constant value contains the number of types. For C++17 and above. ```cpp template inline constexpr size_t variant_size_v = variant_size::value; ``` **Description** Has the value equal to the number of types. ## Tests ### Non-member functions ```cpp template ETL_CONSTEXPR14 bool holds_alternative(const etl::variant& v) noexcept ``` **Description** Checks if the variant v holds the alternative T. --- ```cpp template ETL_CONSTEXPR14 bool holds_alternative(const etl::variant& v) noexcept ``` **Description** Checks if the variant v holds the alternative Index. --- ```cpp template ETL_CONSTEXPR14 bool holds_alternative(size_t index, const etl::variant& v) noexcept ``` **Description** Checks if the variant v holds the alternative index. ## Visitation `etl::variant` provides member functions that support three methods of visitation. {{< callout type="info">}} ### Before: `20.50.0` - C++11 and C++14: Supports up to 32 types of functor, `etl::visitor`, or `etl::overload` callback types. - C++17 and above: Supports any number of functor or `etl::visitor`, or `etl::overload`callback types. ### From: `20.50.0` - Supports any number of visitor callback types. - Compiles to smaller object code. {{< /callout >}} ### etl::visitor ```cpp void accept_visitor(etl::visitor& v) ``` **Description** Accepts an `etl::visitor` derived type. {{< callout type="warning">}} Deprecated from `20.36.0` {{< /callout >}} --- ```cpp void accept_visitor(etl::visitor& v) const ``` **Description** Accepts `an etl::visitor` derived type. {{< callout type="warning">}} Deprecated from `20.36.0` {{< /callout >}} --- ```cpp void accept(etl::visitor& v) ``` **Description** Accepts an `etl::visitor` derived type. Since: `20.36.0` --- ```cpp void accept(etl::visitor& v) const ``` **Description** Accepts an `etl::visitor` derived type. Since: `20.36.0` [See visitor]({{< relref "../../patterns/visitor.md" >}}) ### Functors ```cpp template void accept_functor(TVisitor& v) ``` **Description** Accepts a functor that overrides `operator()` for each type. {{< callout type="warning">}} Deprecated from `20.36.0` {{< /callout >}} --- ```cpp template void accept_functor(TVisitor& v) const ``` **Description** Accepts a functor that overrides `operator()` for each type. {{< callout type="warning">}} Deprecated from `20.36.0` {{< /callout >}} --- ```cpp template void accept(TVisitor& v) ``` **Description** Accepts a functor that overrides `operator()` for each type. Since: `20.36.0` --- ```cpp template void accept(TVisitor& v) const ``` **Description** Accepts a functor that overrides `operator()` for each type. Since: `20.36.0` See overload ### etl::visit For STL style `etl::visit`. Since: `20.28.0` The ETL implements an STL style visit function.