20 General utilities library [utilities]

20.6 Optional objects [optional]

20.6.1 In general [optional.general]

1
#
Subclause [optional] describes class template optional that represents optional objects.
An optional object is an object that contains the storage for another object and manages the lifetime of this contained object, if any.
The contained object may be initialized after the optional object has been initialized, and may be destroyed before the optional object has been destroyed.
The initialization state of the contained object is tracked by the optional object.

20.6.2 Header <optional> synopsis [optional.syn]

#include <compare>              // see [compare.syn]

namespace std {
  // [optional.optional], class template optional
  template<class T>
    class optional;

  // [optional.nullopt], no-value state indicator
  struct nullopt_t{see below};
  inline constexpr nullopt_t nullopt(unspecified);

  // [optional.bad.access], class bad_­optional_­access
  class bad_optional_access;

  // [optional.relops], relational operators
  template<class T, class U>
    constexpr bool operator==(const optional<T>&, const optional<U>&);
  template<class T, class U>
    constexpr bool operator!=(const optional<T>&, const optional<U>&);
  template<class T, class U>
    constexpr bool operator<(const optional<T>&, const optional<U>&);
  template<class T, class U>
    constexpr bool operator>(const optional<T>&, const optional<U>&);
  template<class T, class U>
    constexpr bool operator<=(const optional<T>&, const optional<U>&);
  template<class T, class U>
    constexpr bool operator>=(const optional<T>&, const optional<U>&);
  template<class T, three_way_comparable_with<T> U>
    constexpr compare_three_way_result_t<T,U>
      operator<=>(const optional<T>&, const optional<U>&);

  // [optional.nullops], comparison with nullopt
  template<class T> constexpr bool operator==(const optional<T>&, nullopt_t) noexcept;
  template<class T>
    constexpr strong_ordering operator<=>(const optional<T>&, nullopt_t) noexcept;

  // [optional.comp.with.t], comparison with T
  template<class T, class U> constexpr bool operator==(const optional<T>&, const U&);
  template<class T, class U> constexpr bool operator==(const T&, const optional<U>&);
  template<class T, class U> constexpr bool operator!=(const optional<T>&, const U&);
  template<class T, class U> constexpr bool operator!=(const T&, const optional<U>&);
  template<class T, class U> constexpr bool operator<(const optional<T>&, const U&);
  template<class T, class U> constexpr bool operator<(const T&, const optional<U>&);
  template<class T, class U> constexpr bool operator>(const optional<T>&, const U&);
  template<class T, class U> constexpr bool operator>(const T&, const optional<U>&);
  template<class T, class U> constexpr bool operator<=(const optional<T>&, const U&);
  template<class T, class U> constexpr bool operator<=(const T&, const optional<U>&);
  template<class T, class U> constexpr bool operator>=(const optional<T>&, const U&);
  template<class T, class U> constexpr bool operator>=(const T&, const optional<U>&);
  template<class T, three_way_comparable_with<T> U>
    constexpr compare_three_way_result_t<T,U>
      operator<=>(const optional<T>&, const U&);

  // [optional.specalg], specialized algorithms
  template<class T>
    void swap(optional<T>&, optional<T>&) noexcept(see below);

  template<class T>
    constexpr optional<see below> make_optional(T&&);
  template<class T, class... Args>
    constexpr optional<T> make_optional(Args&&... args);
  template<class T, class U, class... Args>
    constexpr optional<T> make_optional(initializer_list<U> il, Args&&... args);

  // [optional.hash], hash support
  template<class T> struct hash;
  template<class T> struct hash<optional<T>>;
}

20.6.3 Class template optional [optional.optional]

namespace std {
  template<class T>
  class optional {
  public:
    using value_type = T;

    // [optional.ctor], constructors
    constexpr optional() noexcept;
    constexpr optional(nullopt_t) noexcept;
    constexpr optional(const optional&);
    constexpr optional(optional&&) noexcept(see below);
    template<class... Args>
      constexpr explicit optional(in_place_t, Args&&...);
    template<class U, class... Args>
      constexpr explicit optional(in_place_t, initializer_list<U>, Args&&...);
    template<class U = T>
      constexpr explicit(see below) optional(U&&);
    template<class U>
      explicit(see below) optional(const optional<U>&);
    template<class U>
      explicit(see below) optional(optional<U>&&);

    // [optional.dtor], destructor
    ~optional();

    // [optional.assign], assignment
    optional& operator=(nullopt_t) noexcept;
    constexpr optional& operator=(const optional&);
    constexpr 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&&...);

    // [optional.swap], swap
    void swap(optional&) noexcept(see below);

    // [optional.observe], observers
    constexpr const T* operator->() const;
    constexpr T* operator->();
    constexpr const T& operator*() const&;
    constexpr T& operator*() &;
    constexpr T&& operator*() &&;
    constexpr const T&& operator*() const&&;
    constexpr explicit operator bool() const noexcept;
    constexpr bool has_value() const noexcept;
    constexpr const T& value() const&;
    constexpr T& value() &;
    constexpr T&& value() &&;
    constexpr const T&& value() const&&;
    template<class U> constexpr T value_or(U&&) const&;
    template<class U> constexpr T value_or(U&&) &&;

    // [optional.mod], modifiers
    void reset() noexcept;

  private:
    T *val;         // exposition only
  };

  template<class T>
    optional(T) -> optional<T>;
}
1
#
Any instance of optional<T> at any given time either contains a value or does not contain a value.
When an instance of optional<T> contains a value, it means that an object of type T, referred to as the optional object's contained value, is allocated within the storage of the optional object.
Implementations are not permitted to use additional storage, such as dynamic memory, to allocate its contained value.
The contained value shall be allocated in a region of the optional<T> storage suitably aligned for the type T.
When an object of type optional<T> is contextually converted to bool, the conversion returns true if the object contains a value; otherwise the conversion returns false.
2
#
Member val is provided for exposition only.
When an optional<T> object contains a value, val points to the contained value.
3
#
T shall be a type other than cv in_­place_­t or cv nullopt_­t that meets the Cpp17Destructible requirements (Table 32).

20.6.3.1 Constructors [optional.ctor]

🔗
constexpr optional() noexcept; constexpr optional(nullopt_t) noexcept;
1
#
Postconditions: *this does not contain a value.
2
#
Remarks: No contained value is initialized.
For every object type T these constructors are constexpr constructors ([dcl.constexpr]).
🔗
constexpr optional(const optional& rhs);
3
#
Effects: If rhs contains a value, initializes the contained value as if direct-non-list-initializing an object of type T with the expression *rhs.
4
#
Postconditions: bool(rhs) == bool(*this).
5
#
Throws: Any exception thrown by the selected constructor of T.
6
#
Remarks: This constructor is defined as deleted unless is_­copy_­constructible_­v<T> is true.
If is_­trivially_­copy_­constructible_­v<T> is true, this constructor is trivial.
🔗
constexpr optional(optional&& rhs) noexcept(see below);
7
#
Constraints: is_­move_­constructible_­v<T> is true.
8
#
Effects: If rhs contains a value, initializes the contained value as if direct-non-list-initializing an object of type T with the expression std​::​move(*rhs).
bool(rhs) is unchanged.
9
#
Postconditions: bool(rhs) == bool(*this).
10
#
Throws: Any exception thrown by the selected constructor of T.
11
#
Remarks: The expression inside noexcept is equivalent to is_­nothrow_­move_­constructible_­v<T>.
If is_­trivially_­move_­constructible_­v<T> is true, this constructor is trivial.
🔗
template<class... Args> constexpr explicit optional(in_place_t, Args&&... args);
12
#
Constraints: is_­constructible_­v<T, Args...> is true.
13
#
Effects: Initializes the contained value as if direct-non-list-initializing an object of type T with the arguments std​::​forward<Args>(args)....
14
#
Postconditions: *this contains a value.
15
#
Throws: Any exception thrown by the selected constructor of T.
16
#
Remarks: If T's constructor selected for the initialization is a constexpr constructor, this constructor is a constexpr constructor.
🔗
template<class U, class... Args> constexpr explicit optional(in_place_t, initializer_list<U> il, Args&&... args);
17
#
Constraints: is_­constructible_­v<T, initializer_­list<U>&, Args...> is true.
18
#
Effects: Initializes the contained value as if direct-non-list-initializing an object of type T with the arguments il, std​::​forward<Args>(args)....
19
#
Postconditions: *this contains a value.
20
#
Throws: Any exception thrown by the selected constructor of T.
21
#
Remarks: If T's constructor selected for the initialization is a constexpr constructor, this constructor is a constexpr constructor.
🔗
template<class U = T> constexpr explicit(see below) optional(U&& v);
22
#
Constraints: is_­constructible_­v<T, U> is true, is_­same_­v<remove_­cvref_­t<U>, in_­place_­t> is false, and is_­same_­v<remove_­cvref_­t<U>, optional> is false.
23
#
Effects: Initializes the contained value as if direct-non-list-initializing an object of type T with the expression std​::​forward<U>(v).
24
#
Postconditions: *this contains a value.
25
#
Throws: Any exception thrown by the selected constructor of T.
26
#
Remarks: If T's selected constructor is a constexpr constructor, this constructor is a constexpr constructor.
The expression inside explicit is equivalent to: 
!is_convertible_v<U, T>
🔗
template<class U> explicit(see below) optional(const optional<U>& rhs);
27
#
Constraints:
  • (27.1)
    is_­constructible_­v<T, const U&> is true,
  • (27.2)
    is_­constructible_­v<T, optional<U>&> is false,
  • (27.3)
    is_­constructible_­v<T, optional<U>&&> is false,
  • (27.4)
    is_­constructible_­v<T, const optional<U>&> is false,
  • (27.5)
    is_­constructible_­v<T, const optional<U>&&> is false,
  • (27.6)
    is_­convertible_­v<optional<U>&, T> is false,
  • (27.7)
    is_­convertible_­v<optional<U>&&, T> is false,
  • (27.8)
    is_­convertible_­v<const optional<U>&, T> is false, and
  • (27.9)
    is_­convertible_­v<const optional<U>&&, T> is false.
28
#
Effects: If rhs contains a value, initializes the contained value as if direct-non-list-initializing an object of type T with the expression *rhs.
29
#
Postconditions: bool(rhs) == bool(*this).
30
#
Throws: Any exception thrown by the selected constructor of T.
31
#
Remarks: The expression inside explicit is equivalent to: 
!is_convertible_v<const U&, T>
🔗
template<class U> explicit(see below) optional(optional<U>&& rhs);
32
#
Constraints:
  • (32.1)
    is_­constructible_­v<T, U> is true,
  • (32.2)
    is_­constructible_­v<T, optional<U>&> is false,
  • (32.3)
    is_­constructible_­v<T, optional<U>&&> is false,
  • (32.4)
    is_­constructible_­v<T, const optional<U>&> is false,
  • (32.5)
    is_­constructible_­v<T, const optional<U>&&> is false,
  • (32.6)
    is_­convertible_­v<optional<U>&, T> is false,
  • (32.7)
    is_­convertible_­v<optional<U>&&, T> is false,
  • (32.8)
    is_­convertible_­v<const optional<U>&, T> is false, and
  • (32.9)
    is_­convertible_­v<const optional<U>&&, T> is false.
33
#
Effects: If rhs contains a value, initializes the contained value as if direct-non-list-initializing an object of type T with the expression std​::​move(*rhs).
bool(rhs) is unchanged.
34
#
Postconditions: bool(rhs) == bool(*this).
35
#
Throws: Any exception thrown by the selected constructor of T.
36
#
Remarks: The expression inside explicit is equivalent to: 
!is_convertible_v<U, T>

20.6.3.2 Destructor [optional.dtor]

🔗
~optional();
1
#
Effects: If is_­trivially_­destructible_­v<T> != true and *this contains a value, calls 
val->T::~T()
2
#
Remarks: If is_­trivially_­destructible_­v<T> is true, then this destructor is trivial.

20.6.3.3 Assignment [optional.assign]

🔗
optional<T>& operator=(nullopt_t) noexcept;
1
#
Effects: If *this contains a value, calls val->T​::​~T() to destroy the contained value; otherwise no effect.
2
#
Postconditions: *this does not contain a value.
3
#
Returns: *this.
🔗
constexpr optional<T>& operator=(const optional& rhs);
4
#
Effects: See Table 42.
Table 42: optional​::​operator=(const optional&) effects   [tab:optional.assign.copy]
*this contains a value
*this does not contain a value
rhs contains a value
assigns *rhs to the contained value
initializes the contained value as if direct-non-list-initializing an object of type T with *rhs
rhs does not contain a value
destroys the contained value by calling val->T​::​~T()
no effect
5
#
Postconditions: bool(rhs) == bool(*this).
6
#
Returns: *this.
7
#
Remarks: If any exception is thrown, the result of the expression bool(*this) remains unchanged.
If an exception is thrown during the call to T's copy constructor, no effect.
If an exception is thrown during the call to T's copy assignment, the state of its contained value is as defined by the exception safety guarantee of T's copy assignment.
This operator is defined as deleted unless is_­copy_­constructible_­v<T> is true and is_­copy_­assignable_­v<T> is true.
If is_­trivially_­copy_­constructible_­v<T> && is_­trivially_­copy_­assignable_­v<T> && is_­trivially_­destructible_­v<T> is true, this assignment operator is trivial.
🔗
constexpr optional& operator=(optional&& rhs) noexcept(see below);
8
#
Constraints: is_­move_­constructible_­v<T> is true and is_­move_­assignable_­v<T> is true.
9
#
Effects: See Table 43.
The result of the expression bool(rhs) remains unchanged.
Table 43: optional​::​operator=(optional&&) effects   [tab:optional.assign.move]
*this contains a value
*this does not contain a value
rhs contains a value
assigns std​::​move(*rhs) to the contained value
initializes the contained value as if direct-non-list-initializing an object of type T with std​::​move(*rhs)
rhs does not contain a value
destroys the contained value by calling val->T​::​~T()
no effect
10
#
Postconditions: bool(rhs) == bool(*this).
11
#
Returns: *this.
12
#
Remarks: The expression inside noexcept is equivalent to: 
is_nothrow_move_assignable_v<T> && is_nothrow_move_constructible_v<T>
13
#
If any exception is thrown, the result of the expression bool(*this) remains unchanged.
If an exception is thrown during the call to T's move constructor, the state of *rhs.val is determined by the exception safety guarantee of T's move constructor.
If an exception is thrown during the call to T's move assignment, the state of *val and *rhs.val is determined by the exception safety guarantee of T's move assignment.
If is_­trivially_­move_­constructible_­v<T> && is_­trivially_­move_­assignable_­v<T> && is_­trivially_­destructible_­v<T> is true, this assignment operator is trivial.
🔗
template<class U = T> optional<T>& operator=(U&& v);
14
#
Constraints: is_­same_­v<remove_­cvref_­t<U>, optional> is false, conjunction_­v<is_­scalar<T>, is_­same<T, decay_­t<U>>> is false, is_­constructible_­v<T, U> is true, and is_­assignable_­v<T&, U> is true.
15
#
Effects: If *this contains a value, assigns std​::​forward<U>(v) to the contained value; otherwise initializes the contained value as if direct-non-list-initializing object of type T with std​::​forward<U>(v).
16
#
Postconditions: *this contains a value.
17
#
Returns: *this.
18
#
Remarks: If any exception is thrown, the result of the expression bool(*this) remains unchanged.
If an exception is thrown during the call to T's constructor, the state of v is determined by the exception safety guarantee of T's constructor.
If an exception is thrown during the call to T's assignment, the state of *val and v is determined by the exception safety guarantee of T's assignment.
🔗
template<class U> optional<T>& operator=(const optional<U>& rhs);
19
#
Constraints:
  • (19.1)
    is_­constructible_­v<T, const U&> is true,
  • (19.2)
    is_­assignable_­v<T&, const U&> is true,
  • (19.3)
    is_­constructible_­v<T, optional<U>&> is false,
  • (19.4)
    is_­constructible_­v<T, optional<U>&&> is false,
  • (19.5)
    is_­constructible_­v<T, const optional<U>&> is false,
  • (19.6)
    is_­constructible_­v<T, const optional<U>&&> is false,
  • (19.7)
    is_­convertible_­v<optional<U>&, T> is false,
  • (19.8)
    is_­convertible_­v<optional<U>&&, T> is false,
  • (19.9)
    is_­convertible_­v<const optional<U>&, T> is false,
  • (19.10)
    is_­convertible_­v<const optional<U>&&, T> is false,
  • (19.11)
    is_­assignable_­v<T&, optional<U>&> is false,
  • (19.12)
    is_­assignable_­v<T&, optional<U>&&> is false,
  • (19.13)
    is_­assignable_­v<T&, const optional<U>&> is false, and
  • (19.14)
    is_­assignable_­v<T&, const optional<U>&&> is false.
20
#
Effects: See Table 44.
Table 44: optional​::​operator=(const optional<U>&) effects   [tab:optional.assign.copy.templ]
*this contains a value
*this does not contain a value
rhs contains a value
assigns *rhs to the contained value
initializes the contained value as if direct-non-list-initializing an object of type T with *rhs
rhs does not contain a value
destroys the contained value by calling val->T​::​~T()
no effect
21
#
Postconditions: bool(rhs) == bool(*this).
22
#
Returns: *this.
23
#
Remarks: If any exception is thrown, the result of the expression bool(*this) remains unchanged.
If an exception is thrown during the call to T's constructor, the state of *rhs.val is determined by the exception safety guarantee of T's constructor.
If an exception is thrown during the call to T's assignment, the state of *val and *rhs.val is determined by the exception safety guarantee of T's assignment.
🔗
template<class U> optional<T>& operator=(optional<U>&& rhs);
24
#
Constraints:
  • (24.1)
    is_­constructible_­v<T, U> is true,
  • (24.2)
    is_­assignable_­v<T&, U> is true,
  • (24.3)
    is_­constructible_­v<T, optional<U>&> is false,
  • (24.4)
    is_­constructible_­v<T, optional<U>&&> is false,
  • (24.5)
    is_­constructible_­v<T, const optional<U>&> is false,
  • (24.6)
    is_­constructible_­v<T, const optional<U>&&> is false,
  • (24.7)
    is_­convertible_­v<optional<U>&, T> is false,
  • (24.8)
    is_­convertible_­v<optional<U>&&, T> is false,
  • (24.9)
    is_­convertible_­v<const optional<U>&, T> is false,
  • (24.10)
    is_­convertible_­v<const optional<U>&&, T> is false,
  • (24.11)
    is_­assignable_­v<T&, optional<U>&> is false,
  • (24.12)
    is_­assignable_­v<T&, optional<U>&&> is false,
  • (24.13)
    is_­assignable_­v<T&, const optional<U>&> is false, and
  • (24.14)
    is_­assignable_­v<T&, const optional<U>&&> is false.
25
#
Effects: See Table 45.
The result of the expression bool(rhs) remains unchanged.
Table 45: optional​::​operator=(optional<U>&&) effects   [tab:optional.assign.move.templ]
*this contains a value
*this does not contain a value
rhs contains a value
assigns std​::​move(*rhs) to the contained value
initializes the contained value as if direct-non-list-initializing an object of type T with std​::​move(*rhs)
rhs does not contain a value
destroys the contained value by calling val->T​::​~T()
no effect
26
#
Postconditions: bool(rhs) == bool(*this).
27
#
Returns: *this.
28
#
Remarks: If any exception is thrown, the result of the expression bool(*this) remains unchanged.
If an exception is thrown during the call to T's constructor, the state of *rhs.val is determined by the exception safety guarantee of T's constructor.
If an exception is thrown during the call to T's assignment, the state of *val and *rhs.val is determined by the exception safety guarantee of T's assignment.
🔗
template<class... Args> T& emplace(Args&&... args);
29
#
Mandates: is_­constructible_­v<T, Args...> is true.
30
#
Effects: Calls *this = nullopt.
Then initializes the contained value as if direct-non-list-initializing an object of type T with the arguments std​::​forward<Args>(args)....
31
#
Postconditions: *this contains a value.
32
#
Returns: A reference to the new contained value.
33
#
Throws: Any exception thrown by the selected constructor of T.
34
#
Remarks: If an exception is thrown during the call to T's constructor, *this does not contain a value, and the previous *val (if any) has been destroyed.
🔗
template<class U, class... Args> T& emplace(initializer_list<U> il, Args&&... args);
35
#
Constraints: is_­constructible_­v<T, initializer_­list<U>&, Args...> is true.
36
#
Effects: Calls *this = nullopt.
Then initializes the contained value as if direct-non-list-initializing an object of type T with the arguments il, std​::​forward<Args>(args)....
37
#
Postconditions: *this contains a value.
38
#
Returns: A reference to the new contained value.
39
#
Throws: Any exception thrown by the selected constructor of T.
40
#
Remarks: If an exception is thrown during the call to T's constructor, *this does not contain a value, and the previous *val (if any) has been destroyed.

20.6.3.4 Swap [optional.swap]

🔗
void swap(optional& rhs) noexcept(see below);
1
#
Mandates: is_­move_­constructible_­v<T> is true.
2
#
Preconditions: Lvalues of type T are swappable.
3
#
Effects: See Table 46.
Table 46: optional​::​swap(optional&) effects   [tab:optional.swap]
*this contains a value
*this does not contain a value
rhs contains a value
calls swap(*(*this), *rhs)
initializes the contained value of *this as if direct-non-list-initializing an object of type T with the expression std​::​move(*rhs), followed by rhs.val->T​::​~T(); postcondition is that *this contains a value and rhs does not contain a value
rhs does not contain a value
initializes the contained value of rhs as if direct-non-list-initializing an object of type T with the expression std​::​move(*(*this)), followed by val->T​::​~T(); postcondition is that *this does not contain a value and rhs contains a value
no effect
4
#
Throws: Any exceptions thrown by the operations in the relevant part of Table 46.
5
#
Remarks: The expression inside noexcept is equivalent to: 
is_nothrow_move_constructible_v<T> && is_nothrow_swappable_v<T>
If any exception is thrown, the results of the expressions bool(*this) and bool(rhs) remain unchanged.
If an exception is thrown during the call to function swap, the state of *val and *rhs.val is determined by the exception safety guarantee of swap for lvalues of T.
If an exception is thrown during the call to T's move constructor, the state of *val and *rhs.val is determined by the exception safety guarantee of T's move constructor.

20.6.3.5 Observers [optional.observe]

🔗
constexpr const T* operator->() const; constexpr T* operator->();
1
#
Preconditions: *this contains a value.
2
#
Returns: val.
3
#
Throws: Nothing.
4
#
Remarks: These functions are constexpr functions.
🔗
constexpr const T& operator*() const&; constexpr T& operator*() &;
5
#
Preconditions: *this contains a value.
6
#
Returns: *val.
7
#
Throws: Nothing.
8
#
Remarks: These functions are constexpr functions.
🔗
constexpr T&& operator*() &&; constexpr const T&& operator*() const&&;
9
#
Preconditions: *this contains a value.
10
#
Effects: Equivalent to: return std​::​move(*val);
🔗
constexpr explicit operator bool() const noexcept;
11
#
Returns: true if and only if *this contains a value.
12
#
Remarks: This function is a constexpr function.
🔗
constexpr bool has_value() const noexcept;
13
#
Returns: true if and only if *this contains a value.
14
#
Remarks: This function is a constexpr function.
🔗
constexpr const T& value() const&; constexpr T& value() &;
15
#
Effects: Equivalent to: 
return bool(*this) ? *val : throw bad_optional_access();
🔗
constexpr T&& value() &&; constexpr const T&& value() const&&;
16
#
Effects: Equivalent to: 
return bool(*this) ? std::move(*val) : throw bad_optional_access();
🔗
template<class U> constexpr T value_or(U&& v) const&;
17
#
Mandates: is_­copy_­constructible_­v<T> && is_­convertible_­v<U&&, T> is true.
18
#
Effects: Equivalent to: 
return bool(*this) ? **this : static_cast<T>(std::forward<U>(v));
🔗
template<class U> constexpr T value_or(U&& v) &&;
19
#
Mandates: is_­move_­constructible_­v<T> && is_­convertible_­v<U&&, T> is true.
20
#
Effects: Equivalent to: 
return bool(*this) ? std::move(**this) : static_cast<T>(std::forward<U>(v));

20.6.3.6 Modifiers [optional.mod]

🔗
void reset() noexcept;
1
#
Effects: If *this contains a value, calls val->T​::​~T() to destroy the contained value; otherwise no effect.
2
#
Postconditions: *this does not contain a value.

20.6.4 No-value state indicator [optional.nullopt]

🔗
struct nullopt_t{see below}; inline constexpr nullopt_t nullopt(unspecified);
1
#
The struct nullopt_­t is an empty class type used as a unique type to indicate the state of not containing a value for optional objects.
In particular, optional<T> has a constructor with nullopt_­t as a single argument; this indicates that an optional object not containing a value shall be constructed.
2
#
Type nullopt_­t shall not have a default constructor or an initializer-list constructor, and shall not be an aggregate.

20.6.5 Class bad_­optional_­access [optional.bad.access]

class bad_optional_access : public exception {
public:
  // see [exception] for the specification of the special member functions
  const char* what() const noexcept override;
};
1
#
The class bad_­optional_­access defines the type of objects thrown as exceptions to report the situation where an attempt is made to access the value of an optional object that does not contain a value.
🔗
const char* what() const noexcept override;
2
#
Returns: An implementation-defined ntbs.

20.6.6 Relational operators [optional.relops]

🔗
template<class T, class U> constexpr bool operator==(const optional<T>& x, const optional<U>& y);
1
#
Mandates: The expression *x == *y is well-formed and its result is convertible to bool.
[Note
:
T need not be Cpp17EqualityComparable.
— end note
]
2
#
Returns: If bool(x) != bool(y), false; otherwise if bool(x) == false, true; otherwise *x == *y.
3
#
Remarks: Specializations of this function template for which *x == *y is a core constant expression are constexpr functions.
🔗
template<class T, class U> constexpr bool operator!=(const optional<T>& x, const optional<U>& y);
4
#
Mandates: The expression *x != *y is well-formed and its result is convertible to bool.
5
#
Returns: If bool(x) != bool(y), true; otherwise, if bool(x) == false, false; otherwise *x != *y.
6
#
Remarks: Specializations of this function template for which *x != *y is a core constant expression are constexpr functions.
🔗
template<class T, class U> constexpr bool operator<(const optional<T>& x, const optional<U>& y);
7
#
Mandates: *x < *y is well-formed and its result is convertible to bool.
8
#
Returns: If !y, false; otherwise, if !x, true; otherwise *x < *y.
9
#
Remarks: Specializations of this function template for which *x < *y is a core constant expression are constexpr functions.
🔗
template<class T, class U> constexpr bool operator>(const optional<T>& x, const optional<U>& y);
10
#
Mandates: The expression *x > *y is well-formed and its result is convertible to bool.
11
#
Returns: If !x, false; otherwise, if !y, true; otherwise *x > *y.
12
#
Remarks: Specializations of this function template for which *x > *y is a core constant expression are constexpr functions.
🔗
template<class T, class U> constexpr bool operator<=(const optional<T>& x, const optional<U>& y);
13
#
Mandates: The expression *x <= *y is well-formed and its result is convertible to bool.
14
#
Returns: If !x, true; otherwise, if !y, false; otherwise *x <= *y.
15
#
Remarks: Specializations of this function template for which *x <= *y is a core constant expression are constexpr functions.
🔗
template<class T, class U> constexpr bool operator>=(const optional<T>& x, const optional<U>& y);
16
#
Mandates: The expression *x >= *y is well-formed and its result is convertible to bool.
17
#
Returns: If !y, true; otherwise, if !x, false; otherwise *x >= *y.
18
#
Remarks: Specializations of this function template for which *x >= *y is a core constant expression are constexpr functions.
🔗
template<class T, three_­way_­comparable_­with<T> U> constexpr compare_three_way_result_t<T,U> operator<=>(const optional<T>& x, const optional<U>& y);
19
#
Returns: If x && y, *x <=> *y; otherwise bool(x) <=> bool(y).
20
#
Remarks: Specializations of this function template for which *x <=> *y is a core constant expression are constexpr functions.

20.6.7 Comparison with nullopt [optional.nullops]

🔗
template<class T> constexpr bool operator==(const optional<T>& x, nullopt_t) noexcept;
1
#
Returns: !x.
🔗
template<class T> constexpr strong_ordering operator<=>(const optional<T>& x, nullopt_t) noexcept;
2
#
Returns: bool(x) <=> false.

20.6.8 Comparison with T [optional.comp.with.t]

🔗
template<class T, class U> constexpr bool operator==(const optional<T>& x, const U& v);
1
#
Mandates: The expression *x == v is well-formed and its result is convertible to bool.
[Note
:
T need not be Cpp17EqualityComparable.
— end note
]
2
#
Effects: Equivalent to: return bool(x) ? *x == v : false;
🔗
template<class T, class U> constexpr bool operator==(const T& v, const optional<U>& x);
3
#
Mandates: The expression v == *x is well-formed and its result is convertible to bool.
4
#
Effects: Equivalent to: return bool(x) ? v == *x : false;
🔗
template<class T, class U> constexpr bool operator!=(const optional<T>& x, const U& v);
5
#
Mandates: The expression *x != v is well-formed and its result is convertible to bool.
6
#
Effects: Equivalent to: return bool(x) ? *x != v : true;
🔗
template<class T, class U> constexpr bool operator!=(const T& v, const optional<U>& x);
7
#
Mandates: The expression v != *x is well-formed and its result is convertible to bool.
8
#
Effects: Equivalent to: return bool(x) ? v != *x : true;
🔗
template<class T, class U> constexpr bool operator<(const optional<T>& x, const U& v);
9
#
Mandates: The expression *x < v is well-formed and its result is convertible to bool.
10
#
Effects: Equivalent to: return bool(x) ? *x < v : true;
🔗
template<class T, class U> constexpr bool operator<(const T& v, const optional<U>& x);
11
#
Mandates: The expression v < *x is well-formed and its result is convertible to bool.
12
#
Effects: Equivalent to: return bool(x) ? v < *x : false;
🔗
template<class T, class U> constexpr bool operator>(const optional<T>& x, const U& v);
13
#
Mandates: The expression *x > v is well-formed and its result is convertible to bool.
14
#
Effects: Equivalent to: return bool(x) ? *x > v : false;
🔗
template<class T, class U> constexpr bool operator>(const T& v, const optional<U>& x);
15
#
Mandates: The expression v > *x is well-formed and its result is convertible to bool.
16
#
Effects: Equivalent to: return bool(x) ? v > *x : true;
🔗
template<class T, class U> constexpr bool operator<=(const optional<T>& x, const U& v);
17
#
Mandates: The expression *x <= v is well-formed and its result is convertible to bool.
18
#
Effects: Equivalent to: return bool(x) ? *x <= v : true;
🔗
template<class T, class U> constexpr bool operator<=(const T& v, const optional<U>& x);
19
#
Mandates: The expression v <= *x is well-formed and its result is convertible to bool.
20
#
Effects: Equivalent to: return bool(x) ? v <= *x : false;
🔗
template<class T, class U> constexpr bool operator>=(const optional<T>& x, const U& v);
21
#
Mandates: The expression *x >= v is well-formed and its result is convertible to bool.
22
#
Effects: Equivalent to: return bool(x) ? *x >= v : false;
🔗
template<class T, class U> constexpr bool operator>=(const T& v, const optional<U>& x);
23
#
Mandates: The expression v >= *x is well-formed and its result is convertible to bool.
24
#
Effects: Equivalent to: return bool(x) ? v >= *x : true;
🔗
template<class T, three_­way_­comparable_­with<T> U> constexpr compare_three_way_result_t<T,U> operator<=>(const optional<T>& x, const U& v);
25
#
Effects: Equivalent to: return bool(x) ? *x <=> v : strong_­ordering​::​less;

20.6.9 Specialized algorithms [optional.specalg]

🔗
template<class T> void swap(optional<T>& x, optional<T>& y) noexcept(noexcept(x.swap(y)));
1
#
Constraints: is_­move_­constructible_­v<T> is true and is_­swappable_­v<T> is true.
2
#
Effects: Calls x.swap(y).
🔗
template<class T> constexpr optional<decay_t<T>> make_optional(T&& v);
3
#
Returns: optional<decay_­t<T>>(std​::​forward<T>(v)).
🔗
template<class T, class...Args> constexpr optional<T> make_optional(Args&&... args);
4
#
Effects: Equivalent to: return optional<T>(in_­place, std​::​forward<Args>(args)...);
🔗
template<class T, class U, class... Args> constexpr optional<T> make_optional(initializer_list<U> il, Args&&... args);
5
#
Effects: Equivalent to: return optional<T>(in_­place, il, std​::​forward<Args>(args)...);

20.6.10 Hash support [optional.hash]

🔗
template<class T> struct hash<optional<T>>;
1
#
The specialization hash<optional<T>> is enabled ([unord.hash]) if and only if hash<remove_­const_­t<T>> is enabled.
When enabled, for an object o of type optional<T>, if bool(o) == true, then hash<optional<T>>()(o) evaluates to the same value as hash<remove_­const_­t<T>>()(*o); otherwise it evaluates to an unspecified value.
The member functions are not guaranteed to be noexcept.