Optional-like value container that stores its payload out of line. More...

#include <annex.hpp>

Public Types
using	value_type = T
	The contained value type.

using	allocator_type = typename std::allocator_traits< Alloc >::template rebind_alloc< T >
	Allocator rebound to `T`.

Public Member Functions
constexpr	annex () noexcept(std::is_nothrow_default_constructible_v< allocator_type >)=default
	Constructs an empty annex.

constexpr	annex (std::nullopt_t) noexcept(std::is_nothrow_default_constructible_v< allocator_type >)
	Constructs an empty annex from `std::nullopt`.

	annex (allocator_type const &alloc) noexcept
	Constructs an empty annex using the specified allocator.

	annex (std::allocator_arg_t, allocator_type const &alloc) noexcept
	Constructs an empty annex using allocator-argument syntax.

	annex (annex const &other)
	Copy-constructs an annex.

	annex (annex &&other) noexcept(std::is_nothrow_move_constructible_v< allocator_type >)
	Move-constructs an annex by transferring its backing pointer.

template<typename U = T, typename = std::enable_if_t< std::is_constructible_v< T, U&& > && !std::is_same_v< std::decay_t< U >, annex > && !std::is_same_v< std::decay_t< U >, std::in_place_t > && !std::is_same_v< std::decay_t< U >, std::nullopt_t > && !std::is_same_v< std::decay_t< U >, allocator_type > >>
	annex (U &&value)
	Constructs an annex containing a value.

template<typename... Args>
	annex (std::in_place_t, Args &&... args)
	Constructs the contained value in place.

template<typename U, typename... Args>
	annex (std::in_place_t, std::initializer_list< U > init, Args &&... args)
	Constructs the contained value in place with an initializer list.

template<typename... Args>
	annex (std::allocator_arg_t, allocator_type const &alloc, std::in_place_t, Args &&... args)
	Constructs the contained value in place using the specified allocator.

template<typename U, typename... Args>
	annex (std::allocator_arg_t, allocator_type const &alloc, std::in_place_t, std::initializer_list< U > init, Args &&... args)
	Constructs the contained value in place with an initializer list and allocator.

	~annex ()
	Destroys the contained value, if any, and releases its storage.

annex &	operator= (std::nullopt_t) noexcept
	Assigns the empty state.

annex &	operator= (annex const &other)
	Copy-assigns another annex.

annex &	operator= (annex &&other) noexcept(alloc_traits::propagate_on_container_move_assignment::value &&std::is_nothrow_move_assignable_v< allocator_type >)
	Move-assigns another annex.

template<typename U = T, typename = std::enable_if_t< std::is_constructible_v< T, U&& > && std::is_assignable_v< T&, U&& > && !std::is_same_v< std::decay_t< U >, annex > && !std::is_same_v< std::decay_t< U >, std::nullopt_t > >>
annex &	operator= (U &&value)
	Assigns a value to the annex.

constexpr T const *	operator-> () const noexcept
	Returns a pointer to the contained value.

constexpr T *	operator-> () noexcept
	Returns a pointer to the contained value.

constexpr T const &	operator* () const &noexcept
	Returns a const lvalue reference to the contained value.

constexpr T &	operator* () &noexcept
	Returns an lvalue reference to the contained value.

constexpr T const &&	operator* () const &&noexcept
	Returns a const rvalue reference to the contained value.

constexpr T &&	operator* () &&noexcept
	Returns an rvalue reference to the contained value.

constexpr	operator bool () const noexcept
	Tests whether the annex contains a value.

constexpr bool	has_value () const noexcept
	Tests whether the annex contains a value.

T &	value () &
	Returns the contained value.

T const &	value () const &
	Returns the contained value.

T &&	value () &&
	Returns the contained value as an rvalue reference.

T const &&	value () const &&
	Returns the contained value as a const rvalue reference.

template<typename U>
constexpr T	value_or (U &&default_value) const &
	Returns the contained value or a fallback.

template<typename U>
constexpr T	value_or (U &&default_value) &&
	Returns the contained value or a fallback.

void	swap (annex &other) noexcept(alloc_traits::propagate_on_container_swap::value &&std::is_nothrow_swappable_v< allocator_type > &&std::is_nothrow_swappable_v< T >)
	Swaps this annex with another annex.

void	reset () noexcept
	Destroys the contained value and makes the annex empty.

template<typename... Args>
T &	emplace (Args &&... args)
	Replaces the contained value by constructing a new value in place.

template<typename U, typename... Args>
T &	emplace (std::initializer_list< U > init, Args &&... args)
	Replaces the contained value using an initializer list.

allocator_type	get_allocator () const
	Returns a copy of the allocator.

Detailed Description

template<typename T, typename Alloc = std::allocator< T >>
class rpnx::annex< T, Alloc >

Optional-like value container that stores its payload out of line.

annex provides an API modeled after std::optional, but it stores the contained object through allocator-owned dynamic storage. Empty annex objects therefore only contain a pointer and allocator state, which is useful when T is large and the empty state is common.

Move construction and move assignment transfer the backing pointer when allocator rules allow it. This intentionally leaves the moved-from annex empty instead of engaged with a moved-from T.

Template Parameters

T	The type of value stored by the annex.
Alloc	Allocator used for the contained `T`.

Constructor & Destructor Documentation

◆ annex() [1/9]

template<typename T, typename Alloc = std::allocator< T >>

rpnx::annex< T, Alloc >::annex ( allocator_type const & alloc )

inlineexplicitnoexcept

Constructs an empty annex using the specified allocator.

Parameters

alloc Allocator used for future contained values.

◆ annex() [2/9]

template<typename T, typename Alloc = std::allocator< T >>

rpnx::annex< T, Alloc >::annex	(	std::allocator_arg_t	,
		allocator_type const &	alloc )

inlinenoexcept

Constructs an empty annex using allocator-argument syntax.

Parameters

alloc Allocator used for future contained values.

◆ annex() [3/9]

template<typename T, typename Alloc = std::allocator< T >>

rpnx::annex< T, Alloc >::annex ( annex< T, Alloc > const & other )

inline

Copy-constructs an annex.

If other contains a value, the value is copy-constructed into new storage selected by allocator copy-construction rules.

Parameters

other Annex to copy from.

◆ annex() [4/9]

template<typename T, typename Alloc = std::allocator< T >>

rpnx::annex< T, Alloc >::annex ( annex< T, Alloc > && other )

inlinenoexcept

Move-constructs an annex by transferring its backing pointer.

After this operation, other is empty.

Parameters

other Annex to move from.

◆ annex() [5/9]

template<typename T, typename Alloc = std::allocator< T >>

template<typename U = T, typename = std::enable_if_t< std::is_constructible_v< T, U&& > && !std::is_same_v< std::decay_t, annex > && !std::is_same_v< std::decay_t, std::in_place_t > && !std::is_same_v< std::decay_t, std::nullopt_t > && !std::is_same_v< std::decay_t, allocator_type > >>

rpnx::annex< T, Alloc >::annex ( U && value )

inline

Constructs an annex containing a value.

Template Parameters

U	Type of the source value.

Parameters

value Value used to construct the contained T.

◆ annex() [6/9]

template<typename T, typename Alloc = std::allocator< T >>

template<typename... Args>

rpnx::annex< T, Alloc >::annex	(	std::in_place_t	,
		Args &&...	args )

inlineexplicit

Constructs the contained value in place.

Template Parameters

Args	Constructor argument types for `T`.

Parameters

args	Arguments forwarded to `T`.

◆ annex() [7/9]

template<typename T, typename Alloc = std::allocator< T >>

template<typename U, typename... Args>

rpnx::annex< T, Alloc >::annex	(	std::in_place_t	,
		std::initializer_list< U >	init,
		Args &&...	args )

inlineexplicit

Constructs the contained value in place with an initializer list.

Template Parameters

U	Initializer-list element type.
Args	Additional constructor argument types for `T`.

Parameters

init	Initializer list forwarded to `T`.
args	Additional arguments forwarded to `T`.

◆ annex() [8/9]

template<typename T, typename Alloc = std::allocator< T >>

template<typename... Args>

rpnx::annex< T, Alloc >::annex	(	std::allocator_arg_t	,
		allocator_type const &	alloc,
		std::in_place_t	,
		Args &&...	args )

inline

Constructs the contained value in place using the specified allocator.

Template Parameters

Args	Constructor argument types for `T`.

Parameters

alloc	Allocator used for the contained value.
args	Arguments forwarded to `T`.

◆ annex() [9/9]

template<typename T, typename Alloc = std::allocator< T >>

template<typename U, typename... Args>

rpnx::annex< T, Alloc >::annex	(	std::allocator_arg_t	,
		allocator_type const &	alloc,
		std::in_place_t	,
		std::initializer_list< U >	init,
		Args &&...	args )

inline

Constructs the contained value in place with an initializer list and allocator.

Template Parameters

U	Initializer-list element type.
Args	Additional constructor argument types for `T`.

Parameters

alloc	Allocator used for the contained value.
init	Initializer list forwarded to `T`.
args	Additional arguments forwarded to `T`.

Member Function Documentation

◆ emplace() [1/2]

template<typename T, typename Alloc = std::allocator< T >>

template<typename... Args>

T & rpnx::annex< T, Alloc >::emplace ( Args &&... args )

inline

Replaces the contained value by constructing a new value in place.

Template Parameters

Args	Constructor argument types for `T`.

Parameters

args	Arguments forwarded to `T`.

Returns: Reference to the newly constructed value.

◆ emplace() [2/2]

template<typename T, typename Alloc = std::allocator< T >>

template<typename U, typename... Args>

T & rpnx::annex< T, Alloc >::emplace	(	std::initializer_list< U >	init,
		Args &&...	args )

inline

Replaces the contained value using an initializer list.

Template Parameters

U	Initializer-list element type.
Args	Additional constructor argument types for `T`.

Parameters

init	Initializer list forwarded to `T`.
args	Additional arguments forwarded to `T`.

Returns: Reference to the newly constructed value.

◆ get_allocator()

template<typename T, typename Alloc = std::allocator< T >>

allocator_type rpnx::annex< T, Alloc >::get_allocator ( ) const

inline

Returns a copy of the allocator.

Returns: Allocator used for contained-value storage.

◆ has_value()

template<typename T, typename Alloc = std::allocator< T >>

bool rpnx::annex< T, Alloc >::has_value ( ) const

inlineconstexprnoexcept

Tests whether the annex contains a value.

Returns: true if a value is present.

◆ operator bool()

template<typename T, typename Alloc = std::allocator< T >>

rpnx::annex< T, Alloc >::operator bool ( ) const

inlineexplicitconstexprnoexcept

Tests whether the annex contains a value.

Returns: true if a value is present.

◆ operator*() [1/4]

template<typename T, typename Alloc = std::allocator< T >>

T && rpnx::annex< T, Alloc >::operator* ( ) &&

inlineconstexprnoexcept

Returns an rvalue reference to the contained value.

Returns: Rvalue reference to the contained value.

Precondition: has_value() is true.

◆ operator*() [2/4]

template<typename T, typename Alloc = std::allocator< T >>

T & rpnx::annex< T, Alloc >::operator* ( ) &

inlineconstexprnoexcept

Returns an lvalue reference to the contained value.

Returns: Mutable reference to the contained value.

Precondition: has_value() is true.

◆ operator*() [3/4]

template<typename T, typename Alloc = std::allocator< T >>

T const && rpnx::annex< T, Alloc >::operator* ( ) const &&

inlineconstexprnoexcept

Returns a const rvalue reference to the contained value.

Returns: Immutable rvalue reference to the contained value.

Precondition: has_value() is true.

◆ operator*() [4/4]

template<typename T, typename Alloc = std::allocator< T >>

T const & rpnx::annex< T, Alloc >::operator* ( ) const &

inlineconstexprnoexcept

Returns a const lvalue reference to the contained value.

Returns: Immutable reference to the contained value.

Precondition: has_value() is true.

◆ operator->() [1/2]

template<typename T, typename Alloc = std::allocator< T >>

T const * rpnx::annex< T, Alloc >::operator-> ( ) const

inlineconstexprnoexcept

Returns a pointer to the contained value.

Returns: Pointer to the contained value.

Precondition: has_value() is true.

◆ operator->() [2/2]

template<typename T, typename Alloc = std::allocator< T >>

T * rpnx::annex< T, Alloc >::operator-> ( )

inlineconstexprnoexcept

Returns a pointer to the contained value.

Returns: Pointer to the contained value.

Precondition: has_value() is true.

◆ operator=() [1/4]

template<typename T, typename Alloc = std::allocator< T >>

annex & rpnx::annex< T, Alloc >::operator= ( annex< T, Alloc > && other )

inlinenoexcept

Move-assigns another annex.

When allocator propagation or equality permits, this transfers the backing pointer and leaves other empty. Otherwise, the contained value is move-assigned or move-constructed.

Parameters

other Annex to move from.

Returns: *this.

◆ operator=() [2/4]

template<typename T, typename Alloc = std::allocator< T >>

annex & rpnx::annex< T, Alloc >::operator= ( annex< T, Alloc > const & other )

inline

Copy-assigns another annex.

Parameters

other Annex to copy from.

Returns: *this.

◆ operator=() [3/4]

template<typename T, typename Alloc = std::allocator< T >>

annex & rpnx::annex< T, Alloc >::operator= ( std::nullopt_t )

inlinenoexcept

Assigns the empty state.

Returns: *this.

◆ operator=() [4/4]

template<typename T, typename Alloc = std::allocator< T >>

template<typename U = T, typename = std::enable_if_t< std::is_constructible_v< T, U&& > && std::is_assignable_v< T&, U&& > && !std::is_same_v< std::decay_t, annex > && !std::is_same_v< std::decay_t, std::nullopt_t > >>

annex & rpnx::annex< T, Alloc >::operator= ( U && value )

inline

Assigns a value to the annex.

If a value is already present, it is assigned to. Otherwise, a new contained value is constructed.

Template Parameters

U	Type of the source value.

Parameters

value Value to assign.

Returns: *this.

◆ swap()

template<typename T, typename Alloc = std::allocator< T >>

void rpnx::annex< T, Alloc >::swap ( annex< T, Alloc > & other )

inlinenoexcept

Swaps this annex with another annex.

Parameters

other Annex to swap with.

◆ value() [1/4]

template<typename T, typename Alloc = std::allocator< T >>

T & rpnx::annex< T, Alloc >::value ( ) &

inline

Returns the contained value.

Returns: Mutable reference to the contained value.

Exceptions

std::bad_optional_access if no value is present.

◆ value() [2/4]

template<typename T, typename Alloc = std::allocator< T >>

T && rpnx::annex< T, Alloc >::value ( ) &&

inline

Returns the contained value as an rvalue reference.

Returns: Rvalue reference to the contained value.

Exceptions

std::bad_optional_access if no value is present.

◆ value() [3/4]

template<typename T, typename Alloc = std::allocator< T >>

T const & rpnx::annex< T, Alloc >::value ( ) const &

inline

Returns the contained value.

Returns: Immutable reference to the contained value.

Exceptions

std::bad_optional_access if no value is present.

◆ value() [4/4]

template<typename T, typename Alloc = std::allocator< T >>

T const && rpnx::annex< T, Alloc >::value ( ) const &&

inline

Returns the contained value as a const rvalue reference.

Returns: Immutable rvalue reference to the contained value.

Exceptions

std::bad_optional_access if no value is present.

◆ value_or() [1/2]

template<typename T, typename Alloc = std::allocator< T >>

template<typename U>

T rpnx::annex< T, Alloc >::value_or ( U && default_value ) &&

inlineconstexpr

Returns the contained value or a fallback.

Template Parameters

U	Fallback value type.

Parameters

default_value Value returned when the annex is empty.

Returns: The moved contained value, or default_value converted to T.

◆ value_or() [2/2]

template<typename T, typename Alloc = std::allocator< T >>

template<typename U>

T rpnx::annex< T, Alloc >::value_or ( U && default_value ) const &

inlineconstexpr

Returns the contained value or a fallback.

Template Parameters

U	Fallback value type.

Parameters

default_value Value returned when the annex is empty.

Returns: A copy of the contained value, or default_value converted to T.

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

include/rpnx/annex.hpp

Public Types

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ annex() [1/9]

◆ annex() [2/9]

◆ annex() [3/9]

◆ annex() [4/9]

◆ annex() [5/9]

◆ annex() [6/9]

◆ annex() [7/9]

◆ annex() [8/9]

◆ annex() [9/9]

Member Function Documentation

◆ emplace() [1/2]

◆ emplace() [2/2]

◆ get_allocator()

◆ has_value()

◆ operator bool()

◆ operator*() [1/4]

◆ operator*() [2/4]

◆ operator*() [3/4]

◆ operator*() [4/4]

◆ operator->() [1/2]

◆ operator->() [2/2]

◆ operator=() [1/4]

◆ operator=() [2/4]

◆ operator=() [3/4]

◆ operator=() [4/4]

◆ swap()

◆ value() [1/4]

◆ value() [2/4]

◆ value() [3/4]

◆ value() [4/4]

◆ value_or() [1/2]

◆ value_or() [2/2]