RPNX::DataStructures
Header-only C++ data structures and supporting utilities.
Loading...
Searching...
No Matches
rpnx::basic_variant< Allocator, Ts > Class Template Reference

Heap-backed tagged union with allocator-aware storage. More...

#include <variant.hpp>

Public Types

using allocator_type = Allocator
 Allocator type used by this variant.
 

Public Member Functions

constexpr basic_variant (const allocator_type &alloc=allocator_type())
 Default-constructs the first alternative.
 
constexpr basic_variant (basic_variant< Allocator, Ts... > &&other) noexcept(std::is_nothrow_move_constructible_v< Allocator >)
 Move-constructs from another variant of the same type.
 
constexpr basic_variant (basic_variant< Allocator, Ts... > const &other)
 Copy-constructs from another variant of the same type.
 
 ~basic_variant ()
 Destroys the currently-held value if present.
 
void reset ()
 Resets the variant to the valueless state.
 
template<typename... Ts2>
 basic_variant (basic_variant< Allocator, Ts2... > const &other, std::enable_if_t< !std::is_same_v< basic_variant< Allocator, Ts... >, basic_variant< Allocator, Ts2... > > &&!has_cvref_removed_identical_type< basic_variant< Allocator, Ts2... > >(), int >=0)
 Converting copy constructor from another compatible variant type.
 
template<typename T2>
constexpr basic_variant (T2 &&value, const allocator_type &alloc=allocator_type(), std::enable_if_t< rpnx::basic_variant< Allocator, Ts... >::can_construct_subtype_with< T2 >(), int >=0)
 Constructs the variant from a value convertible to one of the alternatives.
 
template<typename T, std::enable_if_t< can_construct_subtype_with< T >(), int > = 0>
constexpr basic_variant< Allocator, Ts... > & operator= (T &&value)
 Assigns from a value convertible to one of the alternatives.
 
basic_variant< Allocator, Ts... > & operator= (basic_variant< Allocator, Ts... > other)
 Copy-assigns by value using swap semantics.
 
template<typename T>
T & static_cast_as ()
 Returns the held value cast to T& via visitor dispatch.
 
template<typename T>
T const & static_cast_as () const
 Returns the held value cast to T const& via visitor dispatch.
 
template<typename T>
T & get_as ()
 Retrieves the held value as T& with runtime type checking.
 
template<typename T>
T & as ()
 Alias of get_as().
 
template<typename T>
T & unwrap ()
 Alias of get_as().
 
template<typename T>
T & unwrap_unchecked ()
 Retrieves the held value as T& without runtime checks.
 
template<typename T>
T const & unwrap_unchecked () const
 Retrieves the held value as T const& without runtime checks.
 
template<typename T>
T const & get_as () const
 Retrieves the held value as T const& with runtime type checking.
 
template<typename T>
T const & as () const
 Const alias of get_as().
 
template<typename T>
T const & unwrap () const
 Const alias of get_as().
 
template<std::size_t N>
auto const & get_n () const
 Retrieves the held value by alternative index with runtime checking.
 
template<std::size_t N>
auto const & get_n_unchecked () const
 Retrieves the held value by alternative index without runtime checking.
 
bool operator== (basic_variant< Allocator, Ts... > const &other) const
 Equality comparison.
 
bool operator!= (basic_variant< Allocator, Ts... > const &other) const
 Inequality comparison.
 
bool operator< (basic_variant< Allocator, Ts... > const &other) const
 Strict-weak ordering comparison.
 
std::strong_ordering operator<=> (basic_variant< Allocator, Ts... > const &other) const
 Three-way comparison.
 
template<typename T>
bool type_is () const
 Checks whether the active alternative is exactly T.
 
template<typename... Ts2>
bool type_any_of () const
 Checks whether the active alternative is any of Ts2.
 
template<typename R, dispatch_type D = dispatch_type::automatic, typename F>
apply_visitor (F &&func) &
 Applies a visitor to the active alternative.
 
template<typename R, dispatch_type D = dispatch_type::automatic, typename F>
apply_visitor (F &&func) const &
 Const lvalue overload of apply_visitor().
 
template<typename R, dispatch_type D = dispatch_type::automatic, typename F>
apply_visitor (F &&func) &&
 Rvalue overload of apply_visitor().
 
template<typename R, typename F>
apply_visitor_checked (F &&func) &
 Applies a visitor and throws if not invocable for the active alternative.
 
template<typename R, typename F>
apply_visitor_checked (F &&func) const &
 Const lvalue overload of apply_visitor_checked().
 
template<typename R, typename F>
apply_visitor_checked (F &&func) &&
 Rvalue overload of apply_visitor_checked().
 
template<typename R, typename F>
try_apply_visitor (F &&func) &
 Applies a visitor and returns default R{} when not invocable for the active type.
 
template<typename R, typename F>
try_apply_visitor (F &&func) const &
 Const lvalue overload of try_apply_visitor().
 
template<typename R, typename F>
try_apply_visitor (F &&func) &&
 Rvalue overload of try_apply_visitor().
 
template<typename T, typename F>
bool match (F &&func)
 Invokes func with the held value if it is of type T.
 
template<typename T, typename F>
bool test (F &&func)
 Invokes func with the held value if it is of type T and returns predicate result.
 
template<typename T, typename F>
bool match (F &&func) const
 Const overload of match().
 
template<typename T, typename F>
bool test (F &&func) const
 Const overload of test().
 
template<typename T>
T * cast_ptr ()
 Returns pointer to held value if active type is T.
 
template<typename T>
T const * cast_ptr () const
 Const overload of cast_ptr().
 
std::type_info const & type () const
 Returns RTTI for the active alternative.
 
std::type_index type_index () const
 Returns std::type_index for the active alternative.
 
template<std::size_t N>
auto & get_n ()
 Retrieves the held value by alternative index with runtime checking.
 
template<std::size_t N>
auto & get_n_unchecked ()
 Retrieves the held value by alternative index without runtime checking.
 
std::size_t index () const
 Returns the active alternative index.
 

Static Public Member Functions

template<typename T>
static consteval bool can_construct_subtype_with ()
 Indicates whether this variant can be constructed from T.
 

Detailed Description

template<typename Allocator, typename... Ts>
class rpnx::basic_variant< Allocator, Ts >

Heap-backed tagged union with allocator-aware storage.

The active alternative is tracked by a runtime index and each stored value is allocated through Allocator rebound to the concrete held type.

Template Parameters
AllocatorAllocator used to allocate and destroy held values.
TsVariant alternative types.

Constructor & Destructor Documentation

◆ basic_variant() [1/5]

template<typename Allocator, typename... Ts>
rpnx::basic_variant< Allocator, Ts >::basic_variant ( const allocator_type & alloc = allocator_type())
inlineconstexpr

Default-constructs the first alternative.

Parameters
allocAllocator instance used for internal allocations.
Exceptions
Anyexception thrown by allocating or constructing Ts[0].

◆ basic_variant() [2/5]

template<typename Allocator, typename... Ts>
rpnx::basic_variant< Allocator, Ts >::basic_variant ( basic_variant< Allocator, Ts... > && other)
inlineconstexprnoexcept

Move-constructs from another variant of the same type.

Parameters
otherSource variant to move from.

◆ basic_variant() [3/5]

template<typename Allocator, typename... Ts>
rpnx::basic_variant< Allocator, Ts >::basic_variant ( basic_variant< Allocator, Ts... > const & other)
inlineconstexpr

Copy-constructs from another variant of the same type.

Parameters
otherSource variant to copy from.
Exceptions
Anyexception thrown by allocation or copy construction of the held value.

◆ basic_variant() [4/5]

template<typename Allocator, typename... Ts>
template<typename... Ts2>
rpnx::basic_variant< Allocator, Ts >::basic_variant ( basic_variant< Allocator, Ts2... > const & other,
std::enable_if_t< !std::is_same_v< basic_variant< Allocator, Ts... >, basic_variant< Allocator, Ts2... > > &&!has_cvref_removed_identical_type< basic_variant< Allocator, Ts2... > >(), int > = 0 )
inline

Converting copy constructor from another compatible variant type.

Template Parameters
Ts2Source variant alternatives.
Parameters
otherSource variant.
Exceptions
Anyexception thrown while assigning the converted held value.

◆ basic_variant() [5/5]

template<typename Allocator, typename... Ts>
template<typename T2>
rpnx::basic_variant< Allocator, Ts >::basic_variant ( T2 && value,
const allocator_type & alloc = allocator_type(),
std::enable_if_t< rpnx::basic_variant< Allocator, Ts... >::can_construct_subtype_with< T2 >(), int > = 0 )
inlineconstexpr

Constructs the variant from a value convertible to one of the alternatives.

Template Parameters
T2Source type.
Parameters
valueValue used to initialize the held alternative.
allocAllocator instance used for internal allocations.
Exceptions
Anyexception thrown by allocation or construction of the selected alternative.

Member Function Documentation

◆ apply_visitor() [1/3]

template<typename Allocator, typename... Ts>
template<typename R, dispatch_type D = dispatch_type::automatic, typename F>
R rpnx::basic_variant< Allocator, Ts >::apply_visitor ( F && func) &
inline

Applies a visitor to the active alternative.

Template Parameters
RVisitor return type.
DDispatch policy.
FVisitor type.
Parameters
funcVisitor callable.
Returns
Visitor result.

◆ apply_visitor() [2/3]

template<typename Allocator, typename... Ts>
template<typename R, dispatch_type D = dispatch_type::automatic, typename F>
R rpnx::basic_variant< Allocator, Ts >::apply_visitor ( F && func) &&
inline

Rvalue overload of apply_visitor().

Template Parameters
RVisitor return type.
DDispatch policy.
FVisitor type.
Parameters
funcVisitor callable.
Returns
Visitor result.

◆ apply_visitor() [3/3]

template<typename Allocator, typename... Ts>
template<typename R, dispatch_type D = dispatch_type::automatic, typename F>
R rpnx::basic_variant< Allocator, Ts >::apply_visitor ( F && func) const &
inline

Const lvalue overload of apply_visitor().

Template Parameters
RVisitor return type.
DDispatch policy.
FVisitor type.
Parameters
funcVisitor callable.
Returns
Visitor result.

◆ apply_visitor_checked() [1/3]

template<typename Allocator, typename... Ts>
template<typename R, typename F>
R rpnx::basic_variant< Allocator, Ts >::apply_visitor_checked ( F && func) &
inline

Applies a visitor and throws if not invocable for the active alternative.

Template Parameters
RVisitor return type.
FVisitor type.
Parameters
funcVisitor callable.
Returns
Visitor result.
Exceptions
std::bad_variant_accessIf func cannot be called for the active type.

◆ apply_visitor_checked() [2/3]

template<typename Allocator, typename... Ts>
template<typename R, typename F>
R rpnx::basic_variant< Allocator, Ts >::apply_visitor_checked ( F && func) &&
inline

Rvalue overload of apply_visitor_checked().

Template Parameters
RVisitor return type.
FVisitor type.
Parameters
funcVisitor callable.
Returns
Visitor result.
Exceptions
std::bad_variant_accessIf func cannot be called for the active type.

◆ apply_visitor_checked() [3/3]

template<typename Allocator, typename... Ts>
template<typename R, typename F>
R rpnx::basic_variant< Allocator, Ts >::apply_visitor_checked ( F && func) const &
inline

Const lvalue overload of apply_visitor_checked().

Template Parameters
RVisitor return type.
FVisitor type.
Parameters
funcVisitor callable.
Returns
Visitor result.
Exceptions
std::bad_variant_accessIf func cannot be called for the active type.

◆ as() [1/2]

template<typename Allocator, typename... Ts>
template<typename T>
T & rpnx::basic_variant< Allocator, Ts >::as ( )
inline

Alias of get_as().

Template Parameters
TExpected held type.
Returns
Mutable reference to the held value.
Exceptions
std::bad_variant_accessIf the active alternative is not T.

◆ as() [2/2]

template<typename Allocator, typename... Ts>
template<typename T>
T const & rpnx::basic_variant< Allocator, Ts >::as ( ) const
inline

Const alias of get_as().

Template Parameters
TExpected held type.
Returns
Const reference to the held value.
Exceptions
std::bad_variant_accessIf the active alternative is not T.

◆ can_construct_subtype_with()

template<typename Allocator, typename... Ts>
template<typename T>
static consteval bool rpnx::basic_variant< Allocator, Ts >::can_construct_subtype_with ( )
inlinestaticconsteval

Indicates whether this variant can be constructed from T.

Template Parameters
TCandidate source type.
Returns
true when T can initialize one of Ts..., excluding self-type conversion.

◆ cast_ptr() [1/2]

template<typename Allocator, typename... Ts>
template<typename T>
T * rpnx::basic_variant< Allocator, Ts >::cast_ptr ( )
inline

Returns pointer to held value if active type is T.

Template Parameters
TType to retrieve.
Returns
Pointer to held value, or nullptr if type does not match.

◆ cast_ptr() [2/2]

template<typename Allocator, typename... Ts>
template<typename T>
T const * rpnx::basic_variant< Allocator, Ts >::cast_ptr ( ) const
inline

Const overload of cast_ptr().

Template Parameters
TType to retrieve.
Returns
Pointer to held value, or nullptr if type does not match.

◆ get_as() [1/2]

template<typename Allocator, typename... Ts>
template<typename T>
T & rpnx::basic_variant< Allocator, Ts >::get_as ( )
inline

Retrieves the held value as T& with runtime type checking.

Template Parameters
TExpected held type.
Returns
Mutable reference to the held value.
Exceptions
std::bad_variant_accessIf the active alternative is not T.

◆ get_as() [2/2]

template<typename Allocator, typename... Ts>
template<typename T>
T const & rpnx::basic_variant< Allocator, Ts >::get_as ( ) const
inline

Retrieves the held value as T const& with runtime type checking.

Template Parameters
TExpected held type.
Returns
Const reference to the held value.
Exceptions
std::bad_variant_accessIf the active alternative is not T.

◆ get_n() [1/2]

template<typename Allocator, typename... Ts>
template<std::size_t N>
auto & rpnx::basic_variant< Allocator, Ts >::get_n ( )
inline

Retrieves the held value by alternative index with runtime checking.

Template Parameters
NAlternative index.
Returns
Mutable reference to the held value.
Exceptions
std::bad_variant_accessIf the active index is not N.

◆ get_n() [2/2]

template<typename Allocator, typename... Ts>
template<std::size_t N>
auto const & rpnx::basic_variant< Allocator, Ts >::get_n ( ) const
inline

Retrieves the held value by alternative index with runtime checking.

Template Parameters
NAlternative index.
Returns
Const reference to the held value.
Exceptions
std::bad_variant_accessIf the active index is not N.

◆ get_n_unchecked() [1/2]

template<typename Allocator, typename... Ts>
template<std::size_t N>
auto & rpnx::basic_variant< Allocator, Ts >::get_n_unchecked ( )
inline

Retrieves the held value by alternative index without runtime checking.

Template Parameters
NAlternative index.
Returns
Mutable reference to the held value.
Note
Uses assertions in debug builds for validation.

◆ get_n_unchecked() [2/2]

template<typename Allocator, typename... Ts>
template<std::size_t N>
auto const & rpnx::basic_variant< Allocator, Ts >::get_n_unchecked ( ) const
inline

Retrieves the held value by alternative index without runtime checking.

Template Parameters
NAlternative index.
Returns
Const reference to the held value.
Note
Uses assertions in debug builds for validation.

◆ index()

template<typename Allocator, typename... Ts>
std::size_t rpnx::basic_variant< Allocator, Ts >::index ( ) const
inline

Returns the active alternative index.

Returns
Zero-based index into Ts....
Exceptions
std::bad_variant_accessIf the variant is valueless.

◆ match() [1/2]

template<typename Allocator, typename... Ts>
template<typename T, typename F>
bool rpnx::basic_variant< Allocator, Ts >::match ( F && func)
inline

Invokes func with the held value if it is of type T.

Template Parameters
TType to match.
FCallable type.
Parameters
funcCallable invoked on match.
Returns
true if the type matched and callable was invoked.

◆ match() [2/2]

template<typename Allocator, typename... Ts>
template<typename T, typename F>
bool rpnx::basic_variant< Allocator, Ts >::match ( F && func) const
inline

Const overload of match().

Template Parameters
TType to match.
FCallable type.
Parameters
funcCallable invoked on match.
Returns
true if the type matched and callable was invoked.

◆ operator!=()

template<typename Allocator, typename... Ts>
bool rpnx::basic_variant< Allocator, Ts >::operator!= ( basic_variant< Allocator, Ts... > const & other) const
inline

Inequality comparison.

Parameters
otherVariant to compare against.
Returns
true if variants are not equal.
Exceptions
std::bad_variant_accessIf either variant is valueless.

◆ operator<()

template<typename Allocator, typename... Ts>
bool rpnx::basic_variant< Allocator, Ts >::operator< ( basic_variant< Allocator, Ts... > const & other) const
inline

Strict-weak ordering comparison.

Parameters
otherVariant to compare against.
Returns
true if *this is ordered before other.
Exceptions
std::bad_variant_accessIf either variant is valueless.

◆ operator<=>()

template<typename Allocator, typename... Ts>
std::strong_ordering rpnx::basic_variant< Allocator, Ts >::operator<=> ( basic_variant< Allocator, Ts... > const & other) const
inline

Three-way comparison.

Parameters
otherVariant to compare against.
Returns
Strong ordering result between the two variants.
Exceptions
std::bad_variant_accessIf either variant is valueless.

◆ operator=() [1/2]

template<typename Allocator, typename... Ts>
basic_variant< Allocator, Ts... > & rpnx::basic_variant< Allocator, Ts >::operator= ( basic_variant< Allocator, Ts... > other)
inline

Copy-assigns by value using swap semantics.

Parameters
otherSource variant.
Returns
Reference to *this.

◆ operator=() [2/2]

template<typename Allocator, typename... Ts>
template<typename T, std::enable_if_t< can_construct_subtype_with< T >(), int > = 0>
basic_variant< Allocator, Ts... > & rpnx::basic_variant< Allocator, Ts >::operator= ( T && value)
inlineconstexpr

Assigns from a value convertible to one of the alternatives.

Template Parameters
TSource type.
Parameters
valueValue to store.
Returns
Reference to *this.
Exceptions
Anyexception thrown by allocation or construction of the new value.

◆ operator==()

template<typename Allocator, typename... Ts>
bool rpnx::basic_variant< Allocator, Ts >::operator== ( basic_variant< Allocator, Ts... > const & other) const
inline

Equality comparison.

Parameters
otherVariant to compare against.
Returns
true if both active alternative and value are equal.
Exceptions
std::bad_variant_accessIf either variant is valueless.

◆ static_cast_as() [1/2]

template<typename Allocator, typename... Ts>
template<typename T>
T & rpnx::basic_variant< Allocator, Ts >::static_cast_as ( )
inline

Returns the held value cast to T& via visitor dispatch.

Template Parameters
TTarget reference type.
Returns
Reference to the held value as T&.
Exceptions
std::bad_variant_accessIf conversion is not valid for the active alternative.

◆ static_cast_as() [2/2]

template<typename Allocator, typename... Ts>
template<typename T>
T const & rpnx::basic_variant< Allocator, Ts >::static_cast_as ( ) const
inline

Returns the held value cast to T const& via visitor dispatch.

Template Parameters
TTarget referenced type.
Returns
Reference to the held value as T const&.
Exceptions
std::bad_variant_accessIf conversion is not valid for the active alternative.

◆ test() [1/2]

template<typename Allocator, typename... Ts>
template<typename T, typename F>
bool rpnx::basic_variant< Allocator, Ts >::test ( F && func)
inline

Invokes func with the held value if it is of type T and returns predicate result.

Template Parameters
TType to test.
FCallable type.
Parameters
funcPredicate callable.
Returns
Predicate result on match, otherwise false.

◆ test() [2/2]

template<typename Allocator, typename... Ts>
template<typename T, typename F>
bool rpnx::basic_variant< Allocator, Ts >::test ( F && func) const
inline

Const overload of test().

Template Parameters
TType to test.
FCallable type.
Parameters
funcPredicate callable.
Returns
Predicate result on match, otherwise false.

◆ try_apply_visitor() [1/3]

template<typename Allocator, typename... Ts>
template<typename R, typename F>
R rpnx::basic_variant< Allocator, Ts >::try_apply_visitor ( F && func) &
inline

Applies a visitor and returns default R{} when not invocable for the active type.

Template Parameters
RVisitor return type.
FVisitor type.
Parameters
funcVisitor callable.
Returns
Visitor result or default-constructed R.

◆ try_apply_visitor() [2/3]

template<typename Allocator, typename... Ts>
template<typename R, typename F>
R rpnx::basic_variant< Allocator, Ts >::try_apply_visitor ( F && func) &&
inline

Rvalue overload of try_apply_visitor().

Template Parameters
RVisitor return type.
FVisitor type.
Parameters
funcVisitor callable.
Returns
Visitor result or default-constructed R.

◆ try_apply_visitor() [3/3]

template<typename Allocator, typename... Ts>
template<typename R, typename F>
R rpnx::basic_variant< Allocator, Ts >::try_apply_visitor ( F && func) const &
inline

Const lvalue overload of try_apply_visitor().

Template Parameters
RVisitor return type.
FVisitor type.
Parameters
funcVisitor callable.
Returns
Visitor result or default-constructed R.

◆ type()

template<typename Allocator, typename... Ts>
std::type_info const & rpnx::basic_variant< Allocator, Ts >::type ( ) const
inline

Returns RTTI for the active alternative.

Returns
Reference to std::type_info for the active type.
Exceptions
std::bad_variant_accessIf the variant is valueless.

◆ type_any_of()

template<typename Allocator, typename... Ts>
template<typename... Ts2>
bool rpnx::basic_variant< Allocator, Ts >::type_any_of ( ) const
inline

Checks whether the active alternative is any of Ts2.

Template Parameters
Ts2Types to test.
Returns
true if active type is in Ts2....

◆ type_index()

template<typename Allocator, typename... Ts>
std::type_index rpnx::basic_variant< Allocator, Ts >::type_index ( ) const
inline

Returns std::type_index for the active alternative.

Returns
Type index of active alternative.
Exceptions
std::bad_variant_accessIf the variant is valueless.

◆ type_is()

template<typename Allocator, typename... Ts>
template<typename T>
bool rpnx::basic_variant< Allocator, Ts >::type_is ( ) const
inline

Checks whether the active alternative is exactly T.

Template Parameters
TType to test.
Returns
true if T is the active alternative.

◆ unwrap() [1/2]

template<typename Allocator, typename... Ts>
template<typename T>
T & rpnx::basic_variant< Allocator, Ts >::unwrap ( )
inline

Alias of get_as().

Template Parameters
TExpected held type.
Returns
Mutable reference to the held value.
Exceptions
std::bad_variant_accessIf the active alternative is not T.

◆ unwrap() [2/2]

template<typename Allocator, typename... Ts>
template<typename T>
T const & rpnx::basic_variant< Allocator, Ts >::unwrap ( ) const
inline

Const alias of get_as().

Template Parameters
TExpected held type.
Returns
Const reference to the held value.
Exceptions
std::bad_variant_accessIf the active alternative is not T.

◆ unwrap_unchecked() [1/2]

template<typename Allocator, typename... Ts>
template<typename T>
T & rpnx::basic_variant< Allocator, Ts >::unwrap_unchecked ( )
inline

Retrieves the held value as T& without runtime checks.

Template Parameters
TExpected held type.
Returns
Mutable reference to the held value.
Note
Uses assertions in debug builds for validation.

◆ unwrap_unchecked() [2/2]

template<typename Allocator, typename... Ts>
template<typename T>
T const & rpnx::basic_variant< Allocator, Ts >::unwrap_unchecked ( ) const
inline

Retrieves the held value as T const& without runtime checks.

Template Parameters
TExpected held type.
Returns
Const reference to the held value.
Note
Uses assertions in debug builds for validation.

The documentation for this class was generated from the following file: