optional Class

The class template optional<T> describes an object that may or may not contain a value of type T, known as the contained value.

When an instance of optional<T> contains a value, the contained value is allocated within the storage of the optional object, in a region suitably aligned for type T. When an optional<T> is converted to bool, the result is true if the object contains a value; otherwise, it's false.

The contained object type T must not be in_place_t or nullopt_t. T must be destructible, that is, its destructor must reclaim all owned resources, and may throw no exceptions.

The optional class is new in C++17.

Syntax

template <class T>
class optional
{
    using value_type = T;
};

template<class T> optional(T) -> optional<T>;

Members

Constructors

Name	Description
Constructors and destructor
optional	Constructs an object of type optional.
~optional	Destroys an object of type optional.
Assignment
operator=	Replaces the optional with a copy of another optional.
emplace	Initializes the contained value with specified arguments.
Swap
swap	Swaps the contained value or the empty state with another optional.
Observers
has_value	Returns whether an optional object contains a value.
value	Returns the contained value.
value_or	Returns the contained value, or an alternative if no value is present.
operator->	References the contained value of an optional object.
operator*	References the contained value of an optional object.
operator bool	Returns whether an optional object contains a value.
Modifiers
reset	Resets the optional by destroying any contained value.

has_value

constexpr bool has_value() const noexcept;

optional constructor

Constructs an object of type optional.

constexpr optional() noexcept;
constexpr optional(nullopt_t nullopt) noexcept;
constexpr optional(const optional& rhs);
constexpr optional(optional&& rhs) noexcept;

template <class... Args>
constexpr explicit optional(in_place_t, Args&&... args);

template <class U, class... Args>
constexpr explicit optional(in_place_t, initializer_list<U> i_list, Args&&... args);

template <class U = T>
explicit constexpr optional(U&& rhs);

template <class U>
explicit optional(const optional<U>& rhs);

template <class U>
explicit optional(optional<U>&& rhs);

Parameters

rhs
The optional to copy or move construct the contained value from.

i_list
The initializer list to construct the contained value from.

args
The argument list to construct the contained value from.

Remarks

constexpr optional() noexcept; constexpr optional(nullopt_t nullopt) noexcept; These constructors construct an optional that doesn't contain a value.

constexpr optional(const optional& rhs); The copy constructor initializes the contained value from the contained value of the argument. It's defined as deleted unless is_copy_constructible_v<T> is true, and it's trivial if is_trivially_copy_constructible_v<T> is true.

constexpr optional(optional&& rhs) noexcept; The move constructor initializes the contained value by moving from the contained value of the argument. It doesn't participate in overload resolution unless is_move_constructible_v<T> is true, and it's trivial if is_trivially_move_constructible_v<T> is true.

template <class... Args> constexpr explicit optional(in_place_t, Args&&... args); Direct initializes the contained value as if using the arguments std::forward<Args>(args). This constructor is constexpr if the T constructor used is constexpr. It doesn't participate in overload resolution unless is_constructible_v<T, Args...> is true.

template <class U, class... Args> constexpr explicit optional(in_place_t, initializer_list<U> i_list, Args&&... args); Direct initializes the contained value as if using the arguments i_list, std::forward<Args>(args). This constructor is constexpr if the T constructor used is constexpr. It doesn't participate in overload resolution unless is_constructible_v<T, initializer_list<U>&, Args&&...> is true.

template <class U = T> explicit constexpr optional(U&& rhs); Direct initializes the contained value as if using std::forward<U>(v). This constructor is constexpr if the T constructor used is constexpr. It doesn't participate in overload resolution unless is_constructible_v<T, U&&> is true, and is_same_v<remove_cvref_t<U>, in_place_t> and is_same_v<remove_cvref_t<U>, optional> are false.

template <class U> explicit optional(const optional<U>& rhs); If rhs contains a value, direct initializes the contained value from the contained value of the argument. It doesn't participate in overload resolution unless is_constructible_v<T, const U&> is true, and is_constructible_v<T, optional<U>&>, is_constructible_v<T, optional<U>&&>, is_constructible_v<T, const optional<U>&>, is_constructible_v<T, const optional<U>&&>, is_convertible_v<optional<U>&, T>, is_convertible_v<optional<U>&&, T>, is_convertible_v<const optional<U>&, T>, and is_convertible_v<const optional<U>&&, T> are all false.

template <class U> explicit optional(optional<U>&& rhs); If rhs contains a value, direct initializes the contained value as if using std::move(*rhs). It doesn't participate in overload resolution unless is_constructible_v<T, U&&> is true, and is_constructible_v<T, optional<U>&>, is_constructible_v<T, optional<U>&&>, is_constructible_v<T, const optional<U>&>, is_constructible_v<T, const optional<U>&&>, is_convertible_v<optional<U>&, T>, is_convertible_v<optional<U>&&, T>, is_convertible_v<const optional<U>&, T>, and is_convertible_v<const optional<U>&&, T> are all false.

~optional destructor

Destroys the contained value, if one is present.

~optional();

Remarks

If T is trivially destructible, then optional<T> is also trivially destructible.

operator=

Replaces the contained value of an optional with a copy or move from another optional contained value.

optional& operator=(nullopt_t) noexcept;
optional& operator=(const optional& rhs);
optional& operator=(optional&&) noexcept( /* see below */ );

template <class U = T>
    optional& operator=(U&&);

template <class U>
optional& operator=(const optional<U>&);

template <class U>
    optional& operator=(optional<U>&&);

template <class... Args>
T& emplace(Args&&...);

template <class U, class... Args>
T& emplace(initializer_list<U>, Args&&...);

operator->

Dereferences the contained value of an optional object.

constexpr const T* operator->() const;
constexpr T* operator->();

operator*

Dereferences the contained value of an optional object.

constexpr const T& operator*() const&;
constexpr T& operator*() &;
constexpr T&& operator*() &&;
constexpr const T&& operator*() const&&;

operator bool

Reports whether the optional object has a contained value.

constexpr explicit operator bool() const noexcept;

reset

Effectively, calls the destructor of the contained object, if any, and sets it to an uninitialized state.

void reset() noexcept;

swap

template<class T>
void swap(optional<T>&, optional<T>&) noexcept;

value

constexpr const T& value() const&;
constexpr T& value() &;
constexpr T&& value() &&;
constexpr const T&& value() const&&;

value_or

template <class U>
    constexpr T value_or(U&&) const&;
template <class U>
    constexpr T value_or(U&&) &&;

See also

<optional>