optional< T > Struct Template Reference

The class template optional manages an optional contained value, i.e. a value that may or may not be present. More...

#include <etl/optional.hpp>

Public Types
using	value_type = T

Public Member Functions
constexpr	optional () noexcept=default
	Constructs an object that does not contain a value.
template<typename... Args> requires is_constructible_v<T, Args...>
constexpr	optional (in_place_t, Args &&... args)
	Constructs an optional object that contains a value, initialized as if direct-initializing.
constexpr	optional (nullopt_t) noexcept
	Constructs an object that does not contain a value.
constexpr	optional (optional &&) noexcept(is_nothrow_move_constructible_v< value_type >)=default
	Move constructor.
constexpr	optional (optional const &)=default
	Copy constructor.
template<typename F>
constexpr auto	and_then (F &&f) &
template<typename F>
constexpr auto	and_then (F &&f) &&
template<typename F>
constexpr auto	and_then (F &&f) const &
template<typename F>
constexpr auto	and_then (F &&f) const &&
template<typename... Args>
constexpr auto	emplace (Args &&... args) -> value_type &
	Constructs the contained value in-place. If *this already contains a value before the call, the contained value is destroyed by calling its destructor.
template<typename U> requires ( is_constructible_v<T, U&&> and not is_same_v<remove_cv_t<U>, bool> and not is_constructible_v<T, optional<U>&> and not is_constructible_v<T, optional<U> const&> and not is_constructible_v<T, optional<U> &&> and not is_constructible_v<T, optional<U> const&&> and not is_convertible_v<optional<U>&, T> and not is_convertible_v<optional<U> const&, T> and not is_convertible_v<optional<U>&&, T> and not is_convertible_v<optional<U> const&&, T> )
	explicit (not is_convertible_v< U &&, T >) const expr optional(optional< U > &&other)
	Converting move constructor.
template<typename U = T> requires ( is_constructible_v<T, U &&> and not is_same_v<remove_cvref_t<U>, in_place_t> and not is_same_v<remove_cvref_t<U>, optional> )
	explicit (not is_convertible_v< U &&, T >) const expr optional(U &&value)
	Constructs an optional object that contains a value, initialized as if direct-initializing.
template<typename U> requires ( is_constructible_v<T, U const&> and not is_same_v<remove_cv_t<U>, bool> and not is_constructible_v<T, optional<U>&> and not is_constructible_v<T, optional<U> const&> and not is_constructible_v<T, optional<U> &&> and not is_constructible_v<T, optional<U> const&&> and not is_convertible_v<optional<U>&, T> and not is_convertible_v<optional<U> const&, T> and not is_convertible_v<optional<U>&&, T> and not is_convertible_v<optional<U> const&&, T> )
	explicit (not is_convertible_v< U const &, T >) const expr optional(optional< U > const &other)
	Converting copy constructor.
constexpr auto	has_value () const noexcept -> bool
	Checks whether *this contains a value.
constexpr	operator bool () const noexcept
	Checks whether *this contains a value.
constexpr auto	operator* () &&-> T &&
	Returns a reference to the contained value.
constexpr auto	operator* () &-> T &
	Returns a reference to the contained value.
constexpr auto	operator* () const &&-> T const &&
	Returns a reference to the contained value.
constexpr auto	operator* () const &-> T const &
	Returns a reference to the contained value.
constexpr auto	operator-> () -> value_type *
	Returns a pointer to the contained value. The pointer is null if the optional is empty.
constexpr auto	operator-> () const -> value_type const *
	Returns a pointer to the contained value. The pointer is null if the optional is empty.
constexpr auto	operator= (etl::nullopt_t) noexcept -> optional &
	If *this contains a value before the call, the contained value is destroyed by calling its destructor as if by value().T::~T(). *this does not contain a value after this call.
constexpr auto	operator= (optional &&other) noexcept -> optional &=default
	Assigns the state of other.
constexpr auto	operator= (optional const &other) -> optional &=default
	Assigns the state of other.
template<typename U = T> requires ( is_constructible_v<T, U> and is_assignable_v<T&, U> and not is_constructible_v<T, optional<U>&> and not is_constructible_v<T, optional<U> const&> and not is_constructible_v<T, optional<U>&&> and not is_constructible_v<T, optional<U> const&&> and not is_convertible_v<optional<U>&, T> and not is_convertible_v<optional<U> const&, T> and not is_convertible_v<optional<U>&&, T> and not is_convertible_v<optional<U> const&&, T> and not is_assignable_v<T&, optional<U>&> and not is_assignable_v<T&, optional<U> const&> and not is_assignable_v<T&, optional<U>&&> and not is_assignable_v<T&, optional<U> const&&> )
constexpr auto	operator= (optional< U > &&other) -> optional &
	Assigns the state of other.
template<typename U = T> requires ( is_constructible_v<T, U const&> and is_assignable_v<T&, U const&> and not is_constructible_v<T, optional<U>&> and not is_constructible_v<T, optional<U> const&> and not is_constructible_v<T, optional<U>&&> and not is_constructible_v<T, optional<U> const&&> and not is_convertible_v<optional<U>&, T> and not is_convertible_v<optional<U> const&, T> and not is_convertible_v<optional<U>&&, T> and not is_convertible_v<optional<U> const&&, T> and not is_assignable_v<T&, optional<U>&> and not is_assignable_v<T&, optional<U> const&> and not is_assignable_v<T&, optional<U>&&> and not is_assignable_v<T&, optional<U> const&&> )
constexpr auto	operator= (optional< U > const &other) -> optional &
	Assigns the state of other.
template<typename U = T> requires ( is_assignable_v<T&, U> and is_constructible_v<T, U> and not is_same_v<optional, decay_t<U>> and not is_scalar_v<T> and not is_same_v<T, decay_t<U>> )
constexpr auto	operator= (U &&value) -> optional &
	Perfect-forwarded assignment.
template<typename F> requires (move_constructible<T> and same_as<remove_cvref_t<invoke_result_t<F>>, optional>)
constexpr auto	or_else (F &&f) &&-> optional
template<typename F> requires (copy_constructible<T> and same_as<remove_cvref_t<invoke_result_t<F>>, optional>)
constexpr auto	or_else (F &&f) const &-> optional
constexpr auto	reset () noexcept -> void
	If *this contains a value, destroy that value as if by value().~value_type(). Otherwise, there are no effects. *this does not contain a value after this call.
constexpr auto	swap (optional &other) noexcept(is_nothrow_move_constructible_v< value_type > and is_nothrow_swappable_v< value_type >) -> void
	Swaps the contents with those of other.
template<typename U>
constexpr auto	value_or (U &&defaultValue) &&-> value_type
	Returns the contained value if *this has a value, otherwise returns default_value.
template<typename U>
constexpr auto	value_or (U &&defaultValue) const &-> value_type
	Returns the contained value if *this has a value, otherwise returns default_value.

Related Symbols
(Note that these are not member symbols.)
template<typename T>
	optional (T) -> optional< T >
template<typename T, typename... Args>
constexpr auto	make_optional (Args &&... args) -> etl::optional< T >
	Creates an optional object constructed in-place from args...
template<typename T>
constexpr auto	make_optional (T &&value) -> etl::optional< etl::decay_t< T > >
	Creates an optional object from value.
template<typename T>
constexpr auto	operator< (etl::nullopt_t, optional< T > const &opt) noexcept -> bool
	Compares opt with a nullopt.
template<typename T>
constexpr auto	operator< (optional< T > const &, etl::nullopt_t) noexcept -> bool
	Compares opt with a nullopt.
template<typename T, typename U>
constexpr auto	operator< (optional< T > const &lhs, optional< U > const &rhs) -> bool
	Compares two optional objects, lhs and rhs.
template<typename T, typename U>
constexpr auto	operator< (optional< T > const &opt, U const &value) -> bool
	Compares opt with a value. The values are compared (using the corresponding operator of T) only if opt contains a value. Otherwise, opt is considered less than value. If the corresponding two-way comparison expression between *opt and value is not well-formed, or if its result is not convertible to bool, the program is ill-formed.
template<typename T, typename U>
constexpr auto	operator< (T const &value, optional< U > const &opt) -> bool
	Compares opt with a value. The values are compared (using the corresponding operator of T) only if opt contains a value. Otherwise, opt is considered less than value. If the corresponding two-way comparison expression between *opt and value is not well-formed, or if its result is not convertible to bool, the program is ill-formed.
template<typename T, typename U>
constexpr auto	operator<= (optional< T > const &lhs, optional< U > const &rhs) -> bool
	Compares two optional objects, lhs and rhs.
template<typename T, typename U>
constexpr auto	operator<= (optional< T > const &opt, U const &value) -> bool
	Compares opt with a value. The values are compared (using the corresponding operator of T) only if opt contains a value. Otherwise, opt is considered less than value. If the corresponding two-way comparison expression between *opt and value is not well-formed, or if its result is not convertible to bool, the program is ill-formed.
template<typename T, typename U>
constexpr auto	operator<= (T const &value, optional< U > const &opt) -> bool
	Compares opt with a value. The values are compared (using the corresponding operator of T) only if opt contains a value. Otherwise, opt is considered less than value. If the corresponding two-way comparison expression between *opt and value is not well-formed, or if its result is not convertible to bool, the program is ill-formed.
template<typename T>
constexpr auto	operator== (etl::nullopt_t, optional< T > const &opt) noexcept -> bool
	Compares opt with a nullopt.
template<typename T, typename U>
constexpr auto	operator== (optional< T > const &lhs, optional< U > const &rhs) -> bool
	Compares two optional objects, lhs and rhs.
template<typename T>
constexpr auto	operator== (optional< T > const &opt, etl::nullopt_t) noexcept -> bool
	Compares opt with a nullopt.
template<typename T, typename U>
constexpr auto	operator== (optional< T > const &opt, U const &value) -> bool
	Compares opt with a value. The values are compared (using the corresponding operator of T) only if opt contains a value. Otherwise, opt is considered less than value. If the corresponding two-way comparison expression between *opt and value is not well-formed, or if its result is not convertible to bool, the program is ill-formed.
template<typename T, typename U>
constexpr auto	operator> (optional< T > const &lhs, optional< U > const &rhs) -> bool
	Compares two optional objects, lhs and rhs.
template<typename T, typename U>
constexpr auto	operator> (optional< T > const &opt, U const &value) -> bool
	Compares opt with a value. The values are compared (using the corresponding operator of T) only if opt contains a value. Otherwise, opt is considered less than value. If the corresponding two-way comparison expression between *opt and value is not well-formed, or if its result is not convertible to bool, the program is ill-formed.
template<typename T, typename U>
constexpr auto	operator> (T const &value, optional< U > const &opt) -> bool
	Compares opt with a value. The values are compared (using the corresponding operator of T) only if opt contains a value. Otherwise, opt is considered less than value. If the corresponding two-way comparison expression between *opt and value is not well-formed, or if its result is not convertible to bool, the program is ill-formed.
template<typename T, typename U>
constexpr auto	operator>= (optional< T > const &lhs, optional< U > const &rhs) -> bool
	Compares two optional objects, lhs and rhs.
template<typename T, typename U>
constexpr auto	operator>= (optional< T > const &opt, U const &value) -> bool
	Compares opt with a value. The values are compared (using the corresponding operator of T) only if opt contains a value. Otherwise, opt is considered less than value. If the corresponding two-way comparison expression between *opt and value is not well-formed, or if its result is not convertible to bool, the program is ill-formed.
template<typename T, typename U>
constexpr auto	operator>= (T const &value, optional< U > const &opt) -> bool
	Compares opt with a value. The values are compared (using the corresponding operator of T) only if opt contains a value. Otherwise, opt is considered less than value. If the corresponding two-way comparison expression between *opt and value is not well-formed, or if its result is not convertible to bool, the program is ill-formed.

Detailed Description

template<typename T>
struct etl::optional< T >

The class template optional manages 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 etl::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 allocated as part of the optional object footprint, i.e. no dynamic memory allocation ever takes place. Thus, an optional object models an object, not a pointer, even though operator*() and operator->() are defined.

When an object of type optional is contextually converted to bool, the conversion returns true if the object 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 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 etl::nullopt_t or an optional object that does not contain a value.
• The member function reset() is called.

There are no optional references; a program is ill-formed if it instantiates an optional with a reference type. Alternatively, an optional of a etl::reference_wrapper of type T may be used to hold a reference. In addition, a program is ill-formed if it instantiates an optional with the (possibly cv-qualified) tag types etl::nullopt_t or etl::in_place_t.

https://en.cppreference.com/w/cpp/utility/optional

Template Parameters

T	The type of the value to manage initialization state for. The type must meet the requirements of Destructible (in particular, array types are not allowed).

// SPDX-License-Identifier: BSL-1.0
 
#undef NDEBUG
 
#include <etl/cassert.hpp>
#include <etl/optional.hpp>
 
auto main() -> int
{
    using etl::nullopt;
    using etl::optional;
 
    // construct default (implicit empty)
    auto opt0 = optional<short>();
    assert(opt0.has_value() == false);
    assert(static_cast<bool>(opt0) == false);
 
    // construct explicit empty
    auto opt1 = optional<int>(nullopt);
    assert(opt1.has_value() == false);
    assert(static_cast<bool>(opt1) == false);
 
    // construct explicit with value
    auto opt2 = optional<float>(42.0F);
    assert(opt2.has_value());
    assert(static_cast<bool>(opt2));
 
    // assign copy
    auto const opt3 = opt2;
    assert(opt3.has_value());
    assert(static_cast<bool>(opt3));
 
    // assign move
    auto const opt4 = etl::move(opt2);
    assert(opt4.has_value());
    assert(static_cast<bool>(opt4));
 
    // value & value_or
    assert(optional<int>().value_or(1) == 1);
 
    // Fails to compile, or raises an exception if invoked at runtime
    // static_assert(optional<int>().value());
    // assert(optional<int>().value());
 
    // reset
    auto opt5 = optional<float>(1.0F);
    assert(opt5.has_value());
    opt5.reset();
    assert(opt5.has_value() == false);
 
    return 0;
}

Examples

optional.cpp.

Member Typedef Documentation

value_type

template<typename T>

using value_type = T

Constructor & Destructor Documentation

optional() [1/5]

template<typename T>

optional ( )

constexprdefaultnoexcept

Constructs an object that does not contain a value.

optional() [2/5]

template<typename T>

optional ( nullopt_t )

inlineconstexprnoexcept

Constructs an object that does not contain a value.

optional() [3/5]

template<typename T>

optional ( optional< T > const & )

constexprdefault

Copy constructor.

optional() [4/5]

template<typename T>

optional ( optional< T > && ) const

constexprdefaultnoexcept

Move constructor.

optional() [5/5]

template<typename T>

template<typename... Args>
requires is_constructible_v<T, Args...>

optional ( in_place_t , Args &&... args )

inlineexplicitconstexpr

Constructs an optional object that contains a value, initialized as if direct-initializing.

https://en.cppreference.com/w/cpp/utility/optional/optional

Member Function Documentation

and_then() [1/4]

template<typename T>

template<typename F>

auto and_then ( F && f ) &

inlineconstexpr

and_then() [2/4]

template<typename T>

template<typename F>

auto and_then ( F && f ) &&

inlineconstexpr

and_then() [3/4]

template<typename T>

template<typename F>

auto and_then ( F && f ) const &

inlineconstexpr

and_then() [4/4]

template<typename T>

template<typename F>

auto and_then ( F && f ) const &&

inlineconstexpr

emplace()

template<typename T>

template<typename... Args>

auto emplace ( Args &&... args ) -> value_type&

inlineconstexpr

Constructs the contained value in-place. If *this already contains a value before the call, the contained value is destroyed by calling its destructor.

explicit() [1/3]

template<typename T>

template<typename U>
requires ( is_constructible_v<T, U&&> and not is_same_v<remove_cv_t<U>, bool> and not is_constructible_v<T, optional<U>&> and not is_constructible_v<T, optional<U> const&> and not is_constructible_v<T, optional<U> &&> and not is_constructible_v<T, optional<U> const&&> and not is_convertible_v<optional<U>&, T> and not is_convertible_v<optional<U> const&, T> and not is_convertible_v<optional<U>&&, T> and not is_convertible_v<optional<U> const&&, T> )

explicit ( not is_convertible_v< U &&, T > ) const &&

inline

Converting move constructor.

If other doesn't contain a value, constructs an optional object that does not contain a value. Otherwise, constructs an optional object that contains a value, initialized as if direct-initializing (but not direct-list-initializing) an object of type T with the expression etl::move(*other).

https://en.cppreference.com/w/cpp/utility/optional/optional

explicit() [2/3]

template<typename T>

template<typename U = T>
requires ( is_constructible_v<T, U &&> and not is_same_v<remove_cvref_t<U>, in_place_t> and not is_same_v<remove_cvref_t<U>, optional> )

explicit ( not is_convertible_v< U &&, T > ) const &&

inline

Constructs an optional object that contains a value, initialized as if direct-initializing.

https://en.cppreference.com/w/cpp/utility/optional/optional

explicit() [3/3]

template<typename T>

template<typename U>
requires ( is_constructible_v<T, U const&> and not is_same_v<remove_cv_t<U>, bool> and not is_constructible_v<T, optional<U>&> and not is_constructible_v<T, optional<U> const&> and not is_constructible_v<T, optional<U> &&> and not is_constructible_v<T, optional<U> const&&> and not is_convertible_v<optional<U>&, T> and not is_convertible_v<optional<U> const&, T> and not is_convertible_v<optional<U>&&, T> and not is_convertible_v<optional<U> const&&, T> )

explicit ( not is_convertible_v< U const &, T > ) const &

inline

Converting copy constructor.

If other doesn't contain a value, constructs an optional object that does not contain a value. Otherwise, constructs an optional object that contains a value, initialized as if direct-initializing (but not direct-list-initializing) an object of type T with the expression *other.

https://en.cppreference.com/w/cpp/utility/optional/optional

has_value()

template<typename T>

auto has_value ( ) const -> bool

inlinenodiscardconstexprnoexcept

Checks whether *this contains a value.

operator bool()

template<typename T>

operator bool ( ) const

inlineexplicitnodiscardconstexprnoexcept

Checks whether *this contains a value.

operator*() [1/4]

template<typename T>

auto operator* ( ) && -> T&&

inlinenodiscardconstexpr

Returns a reference to the contained value.

This operator only checks whether the optional contains a value in debug builds! You can do so manually by using has_value() or simply operator bool(). Alternatively, if checked access is needed, value() or value_or() may be used.

https://en.cppreference.com/w/cpp/utility/optional/operator*

operator*() [2/4]

template<typename T>

auto operator* ( ) & -> T&

inlinenodiscardconstexpr

Returns a reference to the contained value.

This operator only checks whether the optional contains a value in debug builds! You can do so manually by using has_value() or simply operator bool(). Alternatively, if checked access is needed, value() or value_or() may be used.

https://en.cppreference.com/w/cpp/utility/optional/operator*

operator*() [3/4]

template<typename T>

auto operator* ( ) const && -> T const&&

inlinenodiscardconstexpr

Returns a reference to the contained value.

This operator only checks whether the optional contains a value in debug builds! You can do so manually by using has_value() or simply operator bool(). Alternatively, if checked access is needed, value() or value_or() may be used.

https://en.cppreference.com/w/cpp/utility/optional/operator*

operator*() [4/4]

template<typename T>

auto operator* ( ) const & -> T const&

inlinenodiscardconstexpr

Returns a reference to the contained value.

This operator only checks whether the optional contains a value in debug builds! You can do so manually by using has_value() or simply operator bool(). Alternatively, if checked access is needed, value() or value_or() may be used.

https://en.cppreference.com/w/cpp/utility/optional/operator*

operator->() [1/2]

template<typename T>

auto operator-> ( ) -> value_type*

inlinenodiscardconstexpr

Returns a pointer to the contained value. The pointer is null if the optional is empty.

operator->() [2/2]

template<typename T>

auto operator-> ( ) const -> value_type const*

inlinenodiscardconstexpr

Returns a pointer to the contained value. The pointer is null if the optional is empty.

operator=() [1/6]

template<typename T>

auto operator= ( etl::nullopt_t ) -> optional&

inlineconstexprnoexcept

If *this contains a value before the call, the contained value is destroyed by calling its destructor as if by value().T::~T(). *this does not contain a value after this call.

operator=() [2/6]

template<typename T>

auto operator= ( optional< T > && other ) -> optional &=default

constexprdefaultnoexcept

Assigns the state of other.

operator=() [3/6]

template<typename T>

auto operator= ( optional< T > const & other ) -> optional &=default

constexprdefault

Assigns the state of other.

operator=() [4/6]

template<typename T>

template<typename U = T>
requires ( is_constructible_v<T, U> and is_assignable_v<T&, U> and not is_constructible_v<T, optional<U>&> and not is_constructible_v<T, optional<U> const&> and not is_constructible_v<T, optional<U>&&> and not is_constructible_v<T, optional<U> const&&> and not is_convertible_v<optional<U>&, T> and not is_convertible_v<optional<U> const&, T> and not is_convertible_v<optional<U>&&, T> and not is_convertible_v<optional<U> const&&, T> and not is_assignable_v<T&, optional<U>&> and not is_assignable_v<T&, optional<U> const&> and not is_assignable_v<T&, optional<U>&&> and not is_assignable_v<T&, optional<U> const&&> )

auto operator= ( optional< U > && other ) -> optional&

inlineconstexpr

Assigns the state of other.

operator=() [5/6]

template<typename T>

template<typename U = T>
requires ( is_constructible_v<T, U const&> and is_assignable_v<T&, U const&> and not is_constructible_v<T, optional<U>&> and not is_constructible_v<T, optional<U> const&> and not is_constructible_v<T, optional<U>&&> and not is_constructible_v<T, optional<U> const&&> and not is_convertible_v<optional<U>&, T> and not is_convertible_v<optional<U> const&, T> and not is_convertible_v<optional<U>&&, T> and not is_convertible_v<optional<U> const&&, T> and not is_assignable_v<T&, optional<U>&> and not is_assignable_v<T&, optional<U> const&> and not is_assignable_v<T&, optional<U>&&> and not is_assignable_v<T&, optional<U> const&&> )

auto operator= ( optional< U > const & other ) -> optional&

inlineconstexpr

Assigns the state of other.

operator=() [6/6]

template<typename T>

template<typename U = T>
requires ( is_assignable_v<T&, U> and is_constructible_v<T, U> and not is_same_v<optional, decay_t<U>> and not is_scalar_v<T> and not is_same_v<T, decay_t<U>> )

auto operator= ( U && value ) -> optional&

inlineconstexpr

Perfect-forwarded assignment.

Depending on whether *this contains a value before the call, the contained value is either direct-initialized from etl::forward<U>(value) or assigned from etl::forward<U>(value).

https://en.cppreference.com/w/cpp/utility/optional/operator%3D

or_else() [1/2]

template<typename T>

template<typename F>
requires (move_constructible<T> and same_as<remove_cvref_t<invoke_result_t<F>>, optional>)

auto or_else ( F && f ) && -> optional

inlineconstexpr

or_else() [2/2]

template<typename T>

template<typename F>
requires (copy_constructible<T> and same_as<remove_cvref_t<invoke_result_t<F>>, optional>)

auto or_else ( F && f ) const & -> optional

inlineconstexpr

reset()

template<typename T>

auto reset ( ) -> void

inlineconstexprnoexcept

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

swap()

template<typename T>

auto swap ( optional< T > & other ) -> void

inlineconstexprnoexcept

Swaps the contents with those of other.

value_or() [1/2]

template<typename T>

template<typename U>

auto value_or ( U && defaultValue ) && -> value_type

inlinenodiscardconstexpr

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

value_or() [2/2]

template<typename T>

template<typename U>

auto value_or ( U && defaultValue ) const & -> value_type

inlinenodiscardconstexpr

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

---

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

• include/etl/_optional/optional.hpp