optional#

Fully qualified name: carb::cpp::optional

template<class T> class optional : private detail::SelectHierarchy<detail::OptionalConstructor<T>, T>#

Template class to identify an optional value.

This object may either contain a specific value of type T, or be empty. The object can be queried to first see if it is empty or not, then if not empty dereferenced to retrieve the contained value. Attempting to dereference an empty optional object is considered an error and will thrown an exception or terminate if exceptions are not enabled.

This template is intended to be a drop-in replacement for std::optional when building with C++14. For builds using C++17 and up, std::optional should be used instead.

Public Types

using value_type = T #: Type alias for the data type stored in this optional object.

Public Functions

inline constexpr optional() noexcept#: Constructor: constructs an empty optional object. The value in this object cannot be dereferenced.

inline constexpr optional(nullopt_t) noexcept#: Constructor: constructs an empty optional object. The value in this object cannot be dereferenced. This constructor variant allows for nullopt to be assigned to this object as a way of resetting or emptying it.

inline optional(const optional &other)#

Copy constructor: constructs a new optional value by copying the state from another optional object.

Parameters:: other – [in] The other optional object to copy the value or lack of value from.

inline optional( optional &&other, ) noexcept(std::is_nothrow_move_constructible<T>::value)#

Move constructor: constructs a new optional value by moving the state from another optional object.

Parameters:: other – [in] The other optional object to move the value or lack of value from. The value contained in other must be move constructible to the data type expected in this object. The other object will be left in a valid but undefined state upon return.

inline optional &operator=(const optional &other)#

Copy-assignment operator.

Parameters:: other – [in] The other optional object to copy the value or lack of value from.
Returns:: A reference to this object.

inline optional &operator=( optional &&other, ) noexcept(std::is_nothrow_move_assignable<T>::value && std::is_nothrow_move_constructible<T>::value)#

Move-assignment operator.

Parameters:: other – [in] The other optional object to move the value or lack of value from. The value contained in other must be move constructible to the data type expected in this object. The other object will be left in a valid but undefined state upon return.
Returns:: A reference to this object.

template<class U, typename std::enable_if_t<std::conjunction<AllowUnwrapping, std::is_constructible<T, const U&>, std::is_convertible<const U&, T>>::value, int> = 0> inline optional( const optional &other, )#

Copy constructor: copies the value or lack of value from another optional object.

Parameters:: other – [in] The other optional object to move the value or lack of value from. The value contained in other must be copy constructible to the data type expected in this object. The other object will be left unmodified.

template<class U, typename std::enable_if_t<std::conjunction<AllowUnwrapping, std::is_constructible<T, U>, std::is_convertible<U, T>>::value, int> = 0> inline optional( optional &&other, )#

Move constructor: moves the state from another optional object into this one.

Parameters:: other – [in] The other optional object to move the value or lack of value from. The value contained in other must be move constructible to the data type expected in this object. The other object will be left in a valid but undefined state upon return.

template<class ...Args, typename std::enable_if_t<std::is_constructible<T, Args...>::value, int> = 0> inline optional( std::in_place_t, Args&&... args, )#

Constructor: piecewise constructs a new optional object from multiple arguments.

Parameters:: args – [in] The arguments used to contruct the value contained in the new object. These arguments will be forwarded unmodified to the contained type’s constructor.

template<class U, class ...Args, typename std::enable_if_t<std::is_constructible<T, std::initializer_list&, Args...>::value, int> = 0> inline optional( std::in_place_t, std::initializer_list ilist, Args&&... args, )#

Constructor: piecewise constructs a new optional object from multiple arguments.

Parameters:

ilist – [in] The initializer list used to construct the new object.
args – [in] The arguments used to satisfy the initializer list ilist.

template<class U = value_type, typename std::enable_if_t<std::conjunction<AllowDirectConversion, std::is_convertible<U, T>>::value, int> = 0> inline constexpr optional( U &&value, )#

Move constructor: moves a value into this object.

Parameters:: value – [in] The new value to assign to this object. This value must be move constructible to the data type expected in this object. The value object will be left in a vaid but undefined state upon return.

~optional() = default#

inline optional &operator=(nullopt_t) noexcept#

Null assignment operator. This will clear out any value stored in this object and reset it to its default constructed state.

Returns:: A reference to this object.

template<class U = T, typename std::enable_if_t<std::conjunction<std::negation<std::is_same<optional, typename std::remove_cv_t<typename std::remove_reference_t>>>, std::negation<std::conjunction<std::is_scalar<T>, std::is_same<T, typename std::decay_t>>>, std::is_constructible<T, U>, std::is_assignable<T&, U>>::value, int> = 0> inline optional &operator=( U &&value, )#

Value assignment operator.

Parameters:: value – [in] The new raw value to assign to this object. This value may be of any type that can be implicitly converted to this object’s contained type.
Returns:: A reference to this object.

template<class U, typename std::enable_if_t<std::conjunction<AllowUnwrappingAssignment, std::is_constructible<T, const U&>, std::is_assignable<T&, const U&>>::value, int> = 0> inline optional &operator=( const optional &other, )#

Value assignment operator.

Parameters:: other – [in] The optional value containing the new value (or lack of value) to assign to this object. The contained value may be of any type that can be implicitly converted to this object’s contained type.
Returns:: A reference to this object.

template<class U, typename std::enable_if_t<std::conjunction<AllowUnwrappingAssignment, std::is_constructible<T, U>, std::is_assignable<T&, U>>::value, int> = 0> inline optional &operator=( optional &&other, )#

Move assignment operator.

Parameters:: other – [in] The optional value containing the new value (or lack of value) to assign to this object. The contained value may be of any type that can be implicitly converted to this object’s contained type. The other object will be in a valid but undefined state upon return.
Returns:: A reference to this object.

inline constexpr const T *operator->() const#

Access operator. This operation is considered undefined behavior if no value is currently contained in this object.

Returns:: The address of the contained value.

inline constexpr T *operator->()#

Access operator. This operation is considered undefined behavior if no value is currently contained in this object.

Returns:: The address of the contained value.

inline constexpr const T &operator*() const &#

Dereference operator for the contained value. This operation is considered undefined behavior if no value is currently contained in this object.

Returns:: A const reference to the contained value.

inline constexpr T &operator*() &#

Dereference operator for the contained value. This operation is considered undefined behavior if no value is currently contained in this object.

Returns:: A reference to the contained value.

inline constexpr const T &&operator*() const &&#

Dereference-and-move operator for the contained value. This operation is considered undefined behavior if no value is currently contained in this object.

Returns:: A const reference to the contained value.

inline constexpr T &&operator*() &&#

Dereference-and-move operator for the contained value. This operation is considered undefined behavior if no value is currently contained in this object.

Returns:: A reference to the contained value.

inline explicit constexpr operator bool() const noexcept#

Value test operator. Checks if this object currently contains a value.

Returns:: true if a value is currently contained in this object and false otherwise.

inline constexpr bool has_value() const noexcept#

Value test operator. Checks if this object currently contains a value.

Returns:: true if a value is currently contained in this object and false otherwise.

inline constexpr const T &value() const &#

Value retrieval accessor. This will throw bad_optional_access if no value is contained in this object (or terminate if exceptions are disabled).

Returns:: A reference to the value contained in this object.

inline constexpr T &value() &#

Value retrieval accessor. This will throw bad_optional_access if no value is contained in this object (or terminate if exceptions are disabled).

Returns:: A reference to the value contained in this object.

inline constexpr const T &&value() const &&#

Value move accessor. This will throw bad_optional_access if no value is contained in this object (or terminate if exceptions are disabled). This object will be left in a valid but undefined state.

Returns:: An rvalue-reference to the contained value.

inline constexpr T &&value() &&#

Value move accessor. This will throw bad_optional_access if no value is contained in this object (or terminate if exceptions are disabled). This object will be left in a valid but undefined state.

Returns:: An rvalue-reference to the contained value.

template<class U> inline constexpr std::remove_cv_t<T> value_or( U &&default_value, ) const &#

Returns the contained value if *this has a value, otherwise returns default_value.

Parameters:: default_value – [in] The value to use in case *this is empty.
Returns:: The current value if *this has a value, or default_value otherwise.

template<class U> inline constexpr std::remove_cv_t<T> value_or( U &&default_value, ) &&#

Returns the contained value if *this has a value, otherwise returns default_value.

Parameters:: default_value – [in] The value to use in case *this is empty.
Returns:: The current value if *this has a value, or default_value otherwise.

inline void swap( optional &other, ) noexcept(std::is_nothrow_move_constructible<T>::value && std::is_nothrow_swappable<T>::value)#

Swaps the values or lack of value between this object and another object.

Parameters:: other – [in] The object to swap the state with this object. If other did not contain a value, this object will not contain a value upon return. If this object does not contain a value, other will not contain a value upon return. If both contain a value, those values will be swapped upon return. The contained type must be move constructible and swappable.

template<class ...Args> inline T &emplace(Args&&... args)#

Piecewise constructs a new value in this object. Any previous contained value will be destructed and discarded.

Parameters:: args – [in] Argument list needed to construct the new object.
Returns:: A reference to this object.

template<class U, class ...Args, typename std::enable_if_t<std::is_constructible<T, std::initializer_list&, Args...>::value, int> = 0> inline T &emplace( std::initializer_list ilist, Args&&... args, )#

Piecewise constructs a new value in this object. Any previous contained value will be destructed and discarded.

Parameters:

ilist – [in] Initializer list used to construct the new value.
args – [in] Argument list needed to satisfy the initializer list ilist.

Returns:

A reference to this object.