optional#

Fully qualified name: carb::cpp::optional

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

Template class to manage an optional contained value, i.e.

a value that may or may not be present.

A common use case for optional is the return value of a function that may fail. As opposed to other approaches such as std::pair<T, bool>, optional handles expensive-to-construct objects well and is more readable, as the intent is expressed explicitly.

Any instance of optional at any given point in time either contains a value or does not contain a value.

If an optional contains a value, the value is guaranteed to be nested within the optional object. Thus, an optional object models an object, not a pointer, even though operator* and operator-> are defined.

When an object of type optional<T> is contextually convertible to bool, the conversion returns true if the optional contains a value and false if it does not contain a value.

The optional object contains a value in the following conditions:

The object is initialized with/assigned from a value of type T or another optional that contains a value.

The optional object does not contain a value in the following conditions:

The object is default-initialized.
The object is initialized with/assigned from a value of type nullopt_t or an optional object that does not contain a value.
The member function reset() is called.

The optional object is a view that contains either one element if it contains a value, or otherwise zero elements if it does not contain a value. The lifetime of the contained element is bound to the object.

There are no optional references, functions, arrays, or (possibly cv-qualified) void; a program is ill-formed if it instantiates an optional with such a type. In addition, a program is ill-formed if it instantiates an optional with the (possibly cv-qualified) tag types nullopt_t or std::in_place_t.

Attempting to dereference an empty optional object is considered an error and will throw an exception (or terminate if exceptions are not enabled).

This implementation is intended to be a drop-in replacement for std::optional (introduced in C++17) and existed when Carbonite’s minimum support was C++14. Since Carbonite requires C++17 or greater, std::optional may be used instead, however, this implementation adds additional features that are not available in std::optional until even later versions of C++.

Public Types

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

using iterator = omni::detail::PointerIterator<value_type*, optional<value_type>>#: Iterator type alias. (Introduced C++26)

using const_iterator = omni::detail::PointerIterator<const value_type*, optional<value_type>>#: Const Iterator type alias. (Introduced C++26)

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_v<T>)#

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_v<T> && std::is_nothrow_move_constructible_v<T>)#

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<typename U, std::enable_if_t<AllowUnwrapping_v && std::is_constructible_v<T, const U&> && std::is_convertible_v<const U&, T>, 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<typename U, std::enable_if_t<AllowUnwrapping_v && std::is_constructible_v<T, U> && std::is_convertible_v<U, T>, 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, std::enable_if_t<std::is_constructible_v<T, Args...>, 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<typename U, class ...Args, std::enable_if_t<std::is_constructible_v<T, std::initializer_list&, Args...>, 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<typename U = value_type, std::enable_if_t<AllowDirectConversion_v && std::is_convertible_v<U, T>, 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<typename U = value_type, std::enable_if_t<!std::is_same_v<optional, remove_cvref_t> && !(std::is_scalar_v<T> && std::is_same_v<T, std::decay_t>) && std::is_constructible_v<T, U> && std::is_assignable_v<T&, U>, 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<typename U, std::enable_if_t<AllowUnwrappingAssignment_v && std::is_constructible_v<T, const U&> && std::is_assignable_v<T&, const U&>, 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<typename U, std::enable_if_t<AllowUnwrappingAssignment_v && std::is_constructible_v<T, U> && std::is_assignable_v<T&, U>, 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 iterator begin() noexcept#

Returns an iterator to the beginning.

If *this contains a value, returns an iterator to the contained value. Otherwise, a past-the-end iterator.

Returns:: Iterator to the contained value if has_value() is true. Otherwise, a past-the-end iterator.

inline const_iterator begin() const noexcept#

Returns an iterator to the beginning.

If *this contains a value, returns an iterator to the contained value. Otherwise, a past-the-end iterator.

Returns:: Iterator to the contained value if has_value() is true. Otherwise, a past-the-end iterator.

inline iterator end() noexcept#

Returns an iterator to the end.

Returns a past-the-end iterator. Equivalent to return begin() + has_value();.

Returns:: a past-the-end iterator.

inline const_iterator end() const noexcept#

Returns an iterator to the end.

Returns a past-the-end iterator. Equivalent to return begin() + has_value();.

Returns:: a past-the-end iterator.

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<typename 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<typename 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.

template<typename F> inline constexpr auto and_then(F &&f) &#

Returns the result of the given function on the contained value if it exists, or an empty optional otherwise.

If *this contains a value, invokes f with the contained value as an argument, and returns the result of that invocation; otherwise returns an empty optional.

The return type must be a specialization of optional (unlike transform()). Otherwise, the program is ill-formed.

Parameters:: f – A suitable function or Callable object that returns an optional.
Returns:: The result of f or an empty optional, as described above.

template<typename F> inline constexpr auto and_then(F &&f) const &#

Returns the result of the given function on the contained value if it exists, or an empty optional otherwise.

If *this contains a value, invokes f with the contained value as an argument, and returns the result of that invocation; otherwise returns an empty optional.

The return type must be a specialization of optional (unlike transform()). Otherwise, the program is ill-formed.

Parameters:: f – A suitable function or Callable object that returns an optional.
Returns:: The result of f or an empty optional, as described above.

template<typename F> inline constexpr auto and_then(F &&f) &&#

Returns the result of the given function on the contained value if it exists, or an empty optional otherwise.

If *this contains a value, invokes f with the contained value as an argument, and returns the result of that invocation; otherwise returns an empty optional.

The return type must be a specialization of optional (unlike transform()). Otherwise, the program is ill-formed.

Parameters:: f – A suitable function or Callable object that returns an optional.
Returns:: The result of f or an empty optional, as described above.

template<typename F> inline constexpr auto and_then(F &&f) const &&#

Returns the result of the given function on the contained value if it exists, or an empty optional otherwise.

If *this contains a value, invokes f with the contained value as an argument, and returns the result of that invocation; otherwise returns an empty optional.

The return type must be a specialization of optional (unlike transform()). Otherwise, the program is ill-formed.

Parameters:: f – A suitable function or Callable object that returns an optional.
Returns:: The result of f or an empty optional, as described above.

template<typename F> inline constexpr auto transform(F &&f) &#

Returns an optional containing the transformed contained value if it exists, or an empty optional otherwise.

If *this contains a value, invokes f with the contained value as an argument, and returns an optional that contains the result of that invocation; otherwise, returns an empty optional.

The type of contained value in the result must be a non-array object type, and must not be in_place_t or nullopt_t. Otherwise, the program is ill-formed.

Parameters:: f – A suitable function or Callable object whose call signature contains a non-reference type.
Returns:: An optional containing the result of f or an empty optional, as described above.

template<typename F> inline constexpr auto transform(F &&f) const &#

Returns an optional containing the transformed contained value if it exists, or an empty optional otherwise.

If *this contains a value, invokes f with the contained value as an argument, and returns an optional that contains the result of that invocation; otherwise, returns an empty optional.

The type of contained value in the result must be a non-array object type, and must not be in_place_t or nullopt_t. Otherwise, the program is ill-formed.

Parameters:: f – A suitable function or Callable object whose call signature contains a non-reference type.
Returns:: An optional containing the result of f or an empty optional, as described above.

template<typename F> inline constexpr auto transform(F &&f) &&#

Returns an optional containing the transformed contained value if it exists, or an empty optional otherwise.

If *this contains a value, invokes f with the contained value as an argument, and returns an optional that contains the result of that invocation; otherwise, returns an empty optional.

The type of contained value in the result must be a non-array object type, and must not be in_place_t or nullopt_t. Otherwise, the program is ill-formed.

Parameters:: f – A suitable function or Callable object whose call signature contains a non-reference type.
Returns:: An optional containing the result of f or an empty optional, as described above.

template<typename F> inline constexpr auto transform(F &&f) const &&#

Returns an optional containing the transformed contained value if it exists, or an empty optional otherwise.

If *this contains a value, invokes f with the contained value as an argument, and returns an optional that contains the result of that invocation; otherwise, returns an empty optional.

The type of contained value in the result must be a non-array object type, and must not be in_place_t or nullopt_t. Otherwise, the program is ill-formed.

Parameters:: f – A suitable function or Callable object whose call signature contains a non-reference type.
Returns:: An optional containing the result of f or an empty optional, as described above.

template<typename F, typename U = T, std::enable_if_t<std::is_invocable_v<F> && std::is_copy_constructible_v, int> = 0> inline constexpr optional or_else( F &&f, ) const &#

Returns the optional itself if it contains a value, or the result of the given function otherwise.

Returns *this if it contains a value. Otherwise returns the result of f. The program is ill-formed if remove_cvref_t<std::invoke_result_t<F>> is not the same as optional<T>.

Parameters:: f – A function or Callable object that returns an optional<T>.
Returns:: *this or the result of f, as described above.

template<typename F, typename U = T, std::enable_if_t<std::is_invocable_v<F> && std::is_move_constructible_v, int> = 0> inline constexpr optional or_else( F &&f, ) &&#

Returns the optional itself if it contains a value, or the result of the given function otherwise.

Returns *this if it contains a value. Otherwise returns the result of f. The program is ill-formed if remove_cvref_t<std::invoke_result_t<F>> is not the same as optional<T>.

Parameters:: f – A function or Callable object that returns an optional<T>.
Returns:: *this or the result of f, as described above.

inline void swap( optional &other, ) noexcept(std::is_nothrow_move_constructible_v<T> && std::is_nothrow_swappable_v<T>)#

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.

inline void reset() noexcept#

Destroys any contained value.

If *this contains a value, destroy that value as if by value().T::~T(). Otherwise, there are no effects. *this does not contain a value after this call.

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<typename U, class ...Args, std::enable_if_t<std::is_constructible_v<T, std::initializer_list&, Args...>, 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.