Exception thrown when trying to access the value of an empty optional

Synopsis

class bad_optional_access
    : public std::exception

Base Classes

Construct a new bad optional access object

Synopsis

constexpr
bad_optional_access() = default;

Synopsis

[[__visibility__, __exclude_from_explicit_instantiation__, __abi_tag__]]
constexpr
exception&
operator=(exception const& value) noexcept = default;

Get the error message for bad optional access

Synopsis

virtual
char const*
what() const noexcept;

Return Value

Synopsis

template<class T>
struct hash;

Synopsis

template<class T>
struct hash<optional<T>>;

Tag type for in place construction

Synopsis

struct in_place_t;

Default constructor

Synopsis

constexpr
explicit
in_place_t() = default;

Tag type for nullopt construction

Synopsis

struct nullopt_t;

Tag type for nullopt_t construction

Synopsis

enum class Tag : int;

Construct a new nullopt_t object

Synopsis

constexpr
explicit
nullopt_t(Tag value) noexcept;

Description

constexpr for nullopt_t to be literal.

Parameters

Synopsis

template<class T>
class optional;

Friends

Non-Member Functions

Type alias for the const iterator type of the optional.

Synopsis

using const_iterator = /* implementation-defined */::contiguous_iterator<T const, optional>;

Description

Since P3168R2: Give std::optional Range Support.

Type alias for the iterator type of the optional.

Synopsis

using iterator = /* implementation-defined */::contiguous_iterator<T, optional>;

Description

Since P3168R2: Give std::optional Range Support.

Type alias for the value type stored in the optional.

Synopsis

using value_type = T;

Constructors

Synopses

Default constructs an empty optional.

constexpr
optional() noexcept;

Copy constructs the value from rhs if it has one.

constexpr
optional(optional const& other)
requires std::is_copy_constructible_v<T> && std::is_trivially_copy_constructible_v<T> = default;

Copy constructs the value from rhs if it has one.

constexpr
optional(optional const& rhs)
requires std::is_copy_constructible_v<T> && (!std::is_trivially_copy_constructible_v<T>);

Constructs the value from rhs if it has one.

template<class U>
constexpr
explicit(!std::is_convertible_v<U, T>)
optional(optional<U> const& rhs)
requires (detail::enable_from_other<T, U, const U&>);

Move constructs the value from rhs if it has one.

constexpr
optional(optional&& other)
requires std::is_move_constructible_v<T> && std::is_trivially_move_constructible_v<T> = default;

Move constructs the value from rhs if it has one.

constexpr
optional(optional&& rhs) noexcept(std::is_nothrow_move_constructible_v<T>)
requires std::is_move_constructible_v<T> && (!std::is_trivially_move_constructible_v<T>);

Constructs the value from rhs if it has one.

template<class U>
constexpr
explicit(!std::is_convertible_v<U, T>)
optional(optional<U>&& rhs)
requires (detail::enable_from_other<T, U, U &&>);

Constructs an empty optional.

constexpr
optional(nullopt_t value) noexcept;

Constructs the value from u, forwarding it if necessary.

template<class U = T>
constexpr
explicit(!std::is_convertible_v<U, T>)
optional(U&& u)
requires detail::enable_forward_value<T, U>;

Constructs the value in-place using the given arguments.

template<class... Args>
constexpr
explicit
optional(
    in_place_t,
    Args...&&... args)
requires std::is_constructible_v<T, Args...>;

Constructs the value in-place using the given arguments.

template<
    class U,
    class... Args>
constexpr
explicit
optional(
    in_place_t,
    std::initializer_list<U> il,
    Args...&&... args)
requires std::is_constructible_v<T, std::initializer_list<U>&, Args&&...>;

Default constructs an empty optional.

Synopsis

constexpr
optional() noexcept;

Copy constructs the value from rhs if it has one.

Synopsis

constexpr
optional(optional const& other)
requires std::is_copy_constructible_v<T> && std::is_trivially_copy_constructible_v<T> = default;

Description

Defaulted if T is trivially copy constructible.

Parameters

Copy constructs the value from rhs if it has one.

Synopsis

constexpr
optional(optional const& rhs)
requires std::is_copy_constructible_v<T> && (!std::is_trivially_copy_constructible_v<T>);

Parameters

Constructs the value from rhs if it has one.

Synopsis

template<class U>
constexpr
explicit(!std::is_convertible_v<U, T>)
optional(optional<U> const& rhs)
requires (detail::enable_from_other<T, U, const U&>);

Description

Converting copy constructor.

Parameters

Move constructs the value from rhs if it has one.

Synopsis

constexpr
optional(optional&& other)
requires std::is_move_constructible_v<T> && std::is_trivially_move_constructible_v<T> = default;

Description

Defaulted if T is trivially move constructible.

Parameters

Move constructs the value from rhs if it has one.

Synopsis

constexpr
optional(optional&& rhs) noexcept(std::is_nothrow_move_constructible_v<T>)
requires std::is_move_constructible_v<T> && (!std::is_trivially_move_constructible_v<T>);

Parameters

Constructs the value from rhs if it has one.

Synopsis

template<class U>
constexpr
explicit(!std::is_convertible_v<U, T>)
optional(optional<U>&& rhs)
requires (detail::enable_from_other<T, U, U &&>);

Description

Converting move constructor.

Parameters

Constructs an empty optional.

Synopsis

constexpr
optional(nullopt_t value) noexcept;

Parameters

Constructs the value from u, forwarding it if necessary.

Synopsis

template<class U = T>
constexpr
explicit(!std::is_convertible_v<U, T>)
optional(U&& u)
requires detail::enable_forward_value<T, U>;

Description

If u is convertible to T, this is an explicit constructor.

Constructs the stored value with u.

Parameters

Constructs the value in-place using the given arguments.

Synopsis

template<class... Args>
constexpr
explicit
optional(
    in_place_t,
    Args...&&... args)
requires std::is_constructible_v<T, Args...>;

Description

Constructs the stored value in-place using the given arguments.

Constructs the value in-place using the given arguments.

Synopsis

template<
    class U,
    class... Args>
constexpr
explicit
optional(
    in_place_t,
    std::initializer_list<U> il,
    Args...&&... args)
requires std::is_constructible_v<T, std::initializer_list<U>&, Args&&...>;

Destructors

Synopses

Destructs the optional.

constexpr
~optional()
requires std::is_trivially_destructible_v<T> = default;

Destroys the optional and its value if it has one.

constexpr
~optional()
requires (!std::is_trivially_destructible_v<T>);

Destructs the optional.

Synopsis

constexpr
~optional()
requires std::is_trivially_destructible_v<T> = default;

Destroys the optional and its value if it has one.

Synopsis

constexpr
~optional()
requires (!std::is_trivially_destructible_v<T>);

Assignment operators

Synopses

Copy assigns the value from rhs if it has one.

constexpr
optional&
operator=(optional const& other)
requires std::is_copy_constructible_v<T> && std::is_copy_assignable_v<T> &&
                     std::is_trivially_copy_constructible_v<T> && std::is_trivially_copy_assignable_v<T> = default;

Copy assigns the value from rhs if it has one.

constexpr
optional<T>&
operator=(optional const& rhs)
requires std::is_copy_constructible_v<T> && std::is_copy_assignable_v<T> &&
             (!std::is_trivially_copy_assignable_v<T>);

Assigns the stored value from rhs if it has one, destroying the old value if there

template<class U>
constexpr
optional<T>&
operator=(optional<U> const& rhs)
requires (detail::enable_assign_from_other<T, U, const U&>);

Move assigns the value from rhs if it has one.

constexpr
optional&
operator=(optional&& other)
requires std::is_move_constructible_v<T> && std::is_move_assignable_v<T> &&
                     std::is_trivially_move_constructible_v<T> && std::is_trivially_move_assignable_v<T> = default;

Move assigns the value from rhs if it has one.

constexpr
optional<T>&
operator=(optional&& rhs) noexcept(std::is_nothrow_move_constructible_v<T>)
requires std::is_move_constructible_v<T> && std::is_move_assignable_v<T> &&
             (!std::is_trivially_move_assignable_v<T>);

Assigns the stored value from rhs if it has one, destroying the old value if there

template<class U>
constexpr
optional<T>&
operator=(optional<U>&& rhs)
requires (detail::enable_assign_from_other<T, U, U>);

Resets the optional to an empty state.

constexpr
optional<T>&
operator=(nullopt_t value) noexcept;

Assigns the stored value from u, destroying the old value if there

template<class U = T>
constexpr
optional<T>&
operator=(U&& u)
requires detail::enable_assign_forward<T, U>;

Return Value

Copy assigns the value from rhs if it has one.

Synopsis

constexpr
optional&
operator=(optional const& other)
requires std::is_copy_constructible_v<T> && std::is_copy_assignable_v<T> &&
                     std::is_trivially_copy_constructible_v<T> && std::is_trivially_copy_assignable_v<T> = default;

Return Value

Parameters

Copy assigns the value from rhs if it has one.

Synopsis

constexpr
optional<T>&
operator=(optional const& rhs)
requires std::is_copy_constructible_v<T> && std::is_copy_assignable_v<T> &&
             (!std::is_trivially_copy_assignable_v<T>);

Return Value

Parameters

Assigns the stored value from rhs if it has one, destroying the old value if there

Synopsis

template<class U>
constexpr
optional<T>&
operator=(optional<U> const& rhs)
requires (detail::enable_assign_from_other<T, U, const U&>);

Description

Converting copy assignment operator.

Copies the value from rhs if there is one. Otherwise resets the stored value in *this.

Return Value

Parameters

Move assigns the value from rhs if it has one.

Synopsis

constexpr
optional&
operator=(optional&& other)
requires std::is_move_constructible_v<T> && std::is_move_assignable_v<T> &&
                     std::is_trivially_move_constructible_v<T> && std::is_trivially_move_assignable_v<T> = default;

Return Value

Parameters

Move assigns the value from rhs if it has one.

Synopsis

constexpr
optional<T>&
operator=(optional&& rhs) noexcept(std::is_nothrow_move_constructible_v<T>)
requires std::is_move_constructible_v<T> && std::is_move_assignable_v<T> &&
             (!std::is_trivially_move_assignable_v<T>);

Return Value

Parameters

Assigns the stored value from rhs if it has one, destroying the old value if there

Synopsis

template<class U>
constexpr
optional<T>&
operator=(optional<U>&& rhs)
requires (detail::enable_assign_from_other<T, U, U>);

Description

Converting move assignment operator.

Moves the value from rhs if there is one. Otherwise resets the stored value in *this.

Return Value

Parameters

Resets the optional to an empty state.

Synopsis

constexpr
optional<T>&
operator=(nullopt_t value) noexcept;

Return Value

Parameters

Assigns the stored value from u, destroying the old value if there

Synopsis

template<class U = T>
constexpr
optional<T>&
operator=(U&& u)
requires detail::enable_assign_forward<T, U>;

Description

Assigns the stored value from u, destroying the old value if there was one.

Return Value

Returns an optional containing the result of applying f to the stored value.

Synopses

Returns an optional containing the result of applying f to the stored value.

template<class F>
constexpr
auto
and_then(F&& f) &;

Returns an optional containing the result of applying f to the stored value.

template<class F>
constexpr
auto
and_then(F&& f) &&;

Returns an optional containing the result of applying f to the stored value.

template<class F>
constexpr
auto
and_then(F&& f) const &;

Returns an optional containing the result of applying f to the stored value.

template<class F>
constexpr
auto
and_then(F&& f) const &&;

Return Value

Returns an optional containing the result of applying f to the stored value.

Synopsis

template<class F>
constexpr
auto
and_then(F&& f) &;

Return Value

Returns an optional containing the result of applying f to the stored value.

Synopsis

template<class F>
constexpr
auto
and_then(F&& f) &&;

Return Value

Returns an optional containing the result of applying f to the stored value.

Synopsis

template<class F>
constexpr
auto
and_then(F&& f) const &;

Return Value

Returns an optional containing the result of applying f to the stored value.

Synopsis

template<class F>
constexpr
auto
and_then(F&& f) const &&;

Return Value

begin overloads

Synopses

Returns an iterator to the beginning of the optional.

constexpr
optional<T>::iterator
begin() noexcept;

Returns a const iterator to the beginning of the optional.

constexpr
optional<T>::const_iterator
begin() const noexcept;

Return Value

Returns an iterator to the beginning of the optional.

Synopsis

constexpr
optional<T>::iterator
begin() noexcept;

Return Value

Returns a const iterator to the beginning of the optional.

Synopsis

constexpr
optional<T>::const_iterator
begin() const noexcept;

Return Value

emplace overloads

Synopses

Constructs the value in-place, destroying the current one if there

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

Constructs the value in-place using the given arguments, destroying the current one if there

template<
    class U,
    class... Args>
constexpr
T&
emplace(
    std::initializer_list<U> il,
    Args...&&... args);

Return Value

Constructs the value in-place, destroying the current one if there

Synopsis

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

Description

Constructs the value in-place, destroying the current one if there is one.

Return Value

Constructs the value in-place using the given arguments, destroying the current one if there

Synopsis

template<
    class U,
    class... Args>
constexpr
T&
emplace(
    std::initializer_list<U> il,
    Args...&&... args);

Return Value

end overloads

Synopses

Returns an iterator to the end of the optional.

constexpr
optional<T>::iterator
end() noexcept;

Returns a const iterator to the end of the optional.

constexpr
optional<T>::const_iterator
end() const noexcept;

Return Value

Returns an iterator to the end of the optional.

Synopsis

constexpr
optional<T>::iterator
end() noexcept;

Return Value

Returns a const iterator to the end of the optional.

Synopsis

constexpr
optional<T>::const_iterator
end() const noexcept;

Return Value

Returns whether or not the optional has a value.

Synopsis

constexpr
bool
has_value() const noexcept;

Description

Returns whether or not the optional has a value

Return Value

Returns a reference to the stored value.

Synopses

Returns a reference to the stored value.

constexpr
T&
operator*() &;

Returns a reference to the stored value.

constexpr
T const&
operator*() const &;

Returns a reference to the stored value.

constexpr
T&&
operator*() &&;

Return Value

• T&
• const T&
• T&&

Returns a reference to the stored value.

Synopsis

constexpr
T&
operator*() &;

Description

Returns the stored value

Return Value

Returns a reference to the stored value.

Synopsis

constexpr
T const&
operator*() const &;

Return Value

Returns a reference to the stored value.

Synopsis

constexpr
T&&
operator*() &&;

Return Value

Returns a pointer to the stored value.

Synopses

Returns a pointer to the stored value.

constexpr
T const*
operator->() const;

Returns a pointer to the stored value.

constexpr
T*
operator->();

Return Value

Returns a pointer to the stored value.

Synopsis

constexpr
T const*
operator->() const;

Description

Returns a pointer to the stored value

Return Value

Returns a pointer to the stored value.

Synopsis

constexpr
T*
operator->();

Return Value

Returns an optional containing the stored value if it has one, or the result of applying f to the optional if it does not.

Synopses

Returns an optional containing the stored value if it has one, or the result of applying f to the optional if it does not.

template<class F>
constexpr
optional<T>
or_else(F&& f) const &;

Returns an optional containing the stored value if it has one, or the result of applying f to the optional if it does not.

template<class F>
constexpr
optional<T>
or_else(F&& f) &&;

Return Value

• optional
• optional<T>
• auto

Returns an optional containing the stored value if it has one, or the result of applying f to the optional if it does not.

Synopsis

template<class F>
constexpr
optional<T>
or_else(F&& f) const &;

Return Value

• optional
• optional<T>

Returns an optional containing the stored value if it has one, or the result of applying f to the optional if it does not.

Synopsis

template<class F>
constexpr
optional<T>
or_else(F&& f) &&;

Return Value

• auto
• optional<T>

Resets the optional to an empty state, destroying the stored value if there is one.

Synopsis

constexpr
void
reset() noexcept;

Swaps this optional with the other.

Synopsis

constexpr
void
swap(optional& rhs) noexcept(std::is_nothrow_move_constructible<T>::value && std::is_nothrow_swappable<T>::value);

Description

Swaps this optional with the other.

If neither optionals have a value, nothing happens. If both have a value, the values are swapped. If one has a value, it is moved to the other and the movee is left valueless.

Returns an optional containing the result of applying f to the stored value, or a default value if there is no stored value.

Synopses

Returns an optional containing the result of applying f to the stored value, or a default value if there is no stored value.

template<class F>
constexpr
auto
transform(F&& f) &;

Returns an optional containing the result of applying f to the stored value, or a default value if there is no stored value.

template<class F>
constexpr
auto
transform(F&& f) &&;

Returns an optional containing the result of applying f to the stored value, or a default value if there is no stored value.

template<class F>
constexpr
auto
transform(F&& f) const &;

Returns an optional containing the result of applying f to the stored value, or a default value if there is no stored value.

template<class F>
constexpr
auto
transform(F&& f) const &&;

Return Value

• optional
• auto

Returns an optional containing the result of applying f to the stored value, or a default value if there is no stored value.

Synopsis

template<class F>
constexpr
auto
transform(F&& f) &;

Description

Carries out some operation on the stored object if there is one.

Return Value

Returns an optional containing the result of applying f to the stored value, or a default value if there is no stored value.

Synopsis

template<class F>
constexpr
auto
transform(F&& f) &&;

Return Value

Returns an optional containing the result of applying f to the stored value, or a default value if there is no stored value.

Synopsis

template<class F>
constexpr
auto
transform(F&& f) const &;

Return Value

Returns an optional containing the result of applying f to the stored value, or a default value if there is no stored value.

Synopsis

template<class F>
constexpr
auto
transform(F&& f) const &&;

Return Value

Returns a reference to the stored value.

Synopses

Returns a reference to the stored value.

constexpr
T&
value() &;

Returns a reference to the stored value.

constexpr
T const&
value() const &;

Returns a reference to the stored value.

constexpr
T&&
value() &&;

Return Value

• T&
• const T&
• T&&

Returns a reference to the stored value.

Synopsis

constexpr
T&
value() &;

Description

Returns the contained value if there is one, otherwise throws bad_optional_access

Return Value

Returns a reference to the stored value.

Synopsis

constexpr
T const&
value() const &;

Return Value

Returns a reference to the stored value.

Synopsis

constexpr
T&&
value() &&;

Return Value

Returns a reference to the stored value.

Synopses

Returns a reference to the stored value.

template<class U = std::remove_cv_t<T>>
constexpr
T
value_or(U&& u) const &;

Returns a reference to the stored value.

template<class U = std::remove_cv_t<T>>
constexpr
T
value_or(U&& u) &&;

Return Value

Returns a reference to the stored value.

Synopsis

template<class U = std::remove_cv_t<T>>
constexpr
T
value_or(U&& u) const &;

Description

Returns the stored value if there is one, otherwise returns u

Return Value

Returns a reference to the stored value.

Synopsis

template<class U = std::remove_cv_t<T>>
constexpr
T
value_or(U&& u) &&;

Return Value

Converts the optional to a boolean indicating whether it has a value.

Synopsis

constexpr
explicit
operator bool() const noexcept;

Return Value

The empty state of the optional.

Synopsis

empty _ = {};

The stored value of the optional.

Synopsis

T value_;

Synopsis

template<class T>
class optional<T&>;

Friends

The type of the iterator for the optional.

Synopsis

using iterator = /* implementation-defined */::contiguous_iterator<T, optional>;

The type of the value stored in the optional.

Synopsis

using value_type = T;

Constructors

Synopses

Default constructor.

constexpr
optional() noexcept = default;

Copy constructor.

constexpr
optional(optional const& rhs) noexcept = default;

Constructs an empty optional.

constexpr
optional(nullopt_t value) noexcept;

Constructs an optional from another optional of type U

template<class U>
requires (std::is_constructible_v<T&, U&> && !std::is_same_v<std::remove_cv_t<T>, optional<U>> &&
                 !std::is_same_v<T&, U> && detail::reference_constructs_from_temporary_v<T&, U&>)
constexpr
optional(optional<U>& rhs) = delete;

Constructs an optional from another optional of type U.

template<class U>
requires (std::is_constructible_v<T&, U&> && !std::is_same_v<std::remove_cv_t<T>, optional<U>> &&
             !std::is_same_v<T&, U> && !detail::reference_constructs_from_temporary_v<T&, U&>)
constexpr
explicit(!std::is_convertible_v<U &, T &>)
optional(optional<U>& rhs) noexcept(std::is_nothrow_constructible_v<T &, U &>);

Constructs an optional from another optional of type U

template<class U>
requires (std::is_constructible_v<T&, const U&> && !std::is_same_v<std::remove_cv_t<T>, optional<U>> &&
                 !std::is_same_v<T&, U> && detail::reference_constructs_from_temporary_v<T&, const U&>)
constexpr
optional(optional<U> const& rhs) = delete;

Constructs an optional from another optional of type U.

template<class U>
requires (std::is_constructible_v<T&, const U&> && !std::is_same_v<std::remove_cv_t<T>, optional<U>> &&
             !std::is_same_v<T&, U> && !detail::reference_constructs_from_temporary_v<T&, const U&>)
constexpr
explicit(!std::is_convertible_v<const U &, T &>)
optional(optional<U> const& rhs) noexcept(std::is_nothrow_constructible_v<T &, const U &>);

Construct from a U

template<class U>
requires (std::is_constructible_v<T&, U> && !(std::is_same_v<std::remove_cvref_t<U>, in_place_t>) &&
                 !(std::is_same_v<std::remove_cvref_t<U>, optional>) &&
                 !detail::reference_constructs_from_temporary_v<T&, U>)
constexpr
explicit(!std::is_convertible_v<U, T &>)
optional(U&& u) noexcept(std::is_nothrow_constructible_v<T &, U>);

Constructs an optional from a U, but deletes the constructor if

template<class U>
requires (std::is_constructible_v<T&, U> && !(std::is_same_v<std::remove_cvref_t<U>, in_place_t>) &&
                 !(std::is_same_v<std::remove_cvref_t<U>, optional>) &&
                 detail::reference_constructs_from_temporary_v<T&, U>)
constexpr
optional(U&& u) = delete;

Constructs an optional from another optional of type U

template<class U>
requires (std::is_constructible_v<T&, U> && !std::is_same_v<std::remove_cv_t<T>, optional<U>> &&
                 !std::is_same_v<T&, U> && detail::reference_constructs_from_temporary_v<T&, U>)
constexpr
optional(optional<U>&& rhs) = delete;

Constructs an optional from another optional of type U.

template<class U>
requires (std::is_constructible_v<T&, U> && !std::is_same_v<std::remove_cv_t<T>, optional<U>> &&
             !std::is_same_v<T&, U> && !detail::reference_constructs_from_temporary_v<T&, U>)
constexpr
explicit(!std::is_convertible_v<U, T &>)
optional(optional<U>&& rhs) noexcept(noexcept(std::is_nothrow_constructible_v<T &, U>));

Constructs an optional from another optional of type U

template<class U>
requires (std::is_constructible_v<T&, const U> && !std::is_same_v<std::remove_cv_t<T>, optional<U>> &&
                 !std::is_same_v<T&, U> && detail::reference_constructs_from_temporary_v<T&, const U>)
constexpr
optional(optional<U> const&& rhs) = delete;

Constructs an optional from another optional of type U.

template<class U>
requires (std::is_constructible_v<T&, const U> && !std::is_same_v<std::remove_cv_t<T>, optional<U>> &&
             !std::is_same_v<T&, U> && !detail::reference_constructs_from_temporary_v<T&, const U>)
constexpr
explicit(!std::is_convertible_v<const U, T &>)
optional(optional<U> const&& rhs) noexcept(noexcept(std::is_nothrow_constructible_v<T &, const U>));

In-place constructor.

template<class Arg>
requires (std::is_constructible_v<T&, Arg> && !detail::reference_constructs_from_temporary_v<T&, Arg>)
constexpr
explicit
optional(
    in_place_t,
    Arg&& arg);

Default constructor.

Synopsis

constexpr
optional() noexcept = default;

Copy constructor.

Synopsis

constexpr
optional(optional const& rhs) noexcept = default;

Description

Constructs an empty optional if the rhs is empty, otherwise constructs the stored value from the rhs.

Parameters

Constructs an empty optional.

Synopsis

constexpr
optional(nullopt_t value) noexcept;

Parameters

Constructs an optional from another optional of type U

Synopsis

template<class U>
requires (std::is_constructible_v<T&, U&> && !std::is_same_v<std::remove_cv_t<T>, optional<U>> &&
                 !std::is_same_v<T&, U> && detail::reference_constructs_from_temporary_v<T&, U&>)
constexpr
optional(optional<U>& rhs) = delete;

Description

Constructs the stored value from the rhs if it has a value, otherwise constructs an empty optional. If T& can be constructed from a temporary, this constructor is deleted to prevent binding a temporary to a reference.

Constructs an optional from another optional of type U.

Synopsis

template<class U>
requires (std::is_constructible_v<T&, U&> && !std::is_same_v<std::remove_cv_t<T>, optional<U>> &&
             !std::is_same_v<T&, U> && !detail::reference_constructs_from_temporary_v<T&, U&>)
constexpr
explicit(!std::is_convertible_v<U &, T &>)
optional(optional<U>& rhs) noexcept(std::is_nothrow_constructible_v<T &, U &>);

Description

Constructs the stored value from the rhs if it has a value, otherwise constructs an empty optional. If T& can be constructed from a temporary, this constructor is deleted to prevent binding a temporary to a reference.

Constructs an optional from another optional of type U

Synopsis

template<class U>
requires (std::is_constructible_v<T&, const U&> && !std::is_same_v<std::remove_cv_t<T>, optional<U>> &&
                 !std::is_same_v<T&, U> && detail::reference_constructs_from_temporary_v<T&, const U&>)
constexpr
optional(optional<U> const& rhs) = delete;

Description

Constructs the stored value from the rhs if it has a value, otherwise constructs an empty optional. If T& can be constructed from a temporary, this constructor is deleted to prevent binding a temporary to a reference.

Constructs an optional from another optional of type U.

Synopsis

template<class U>
requires (std::is_constructible_v<T&, const U&> && !std::is_same_v<std::remove_cv_t<T>, optional<U>> &&
             !std::is_same_v<T&, U> && !detail::reference_constructs_from_temporary_v<T&, const U&>)
constexpr
explicit(!std::is_convertible_v<const U &, T &>)
optional(optional<U> const& rhs) noexcept(std::is_nothrow_constructible_v<T &, const U &>);

Description

Constructs the stored value from the rhs if it has a value, otherwise constructs an empty optional. If T& can be constructed from a temporary, this constructor is deleted to prevent binding a temporary to a reference.

Construct from a U

Synopsis

template<class U>
requires (std::is_constructible_v<T&, U> && !(std::is_same_v<std::remove_cvref_t<U>, in_place_t>) &&
                 !(std::is_same_v<std::remove_cvref_t<U>, optional>) &&
                 !detail::reference_constructs_from_temporary_v<T&, U>)
constexpr
explicit(!std::is_convertible_v<U, T &>)
optional(U&& u) noexcept(std::is_nothrow_constructible_v<T &, U>);

Description

Constructs the stored value from u if it is convertible to T&. If T& can be constructed from a temporary, this constructor is deleted to prevent binding a temporary to a reference.

Constructs an optional from a U, but deletes the constructor if

Synopsis

template<class U>
requires (std::is_constructible_v<T&, U> && !(std::is_same_v<std::remove_cvref_t<U>, in_place_t>) &&
                 !(std::is_same_v<std::remove_cvref_t<U>, optional>) &&
                 detail::reference_constructs_from_temporary_v<T&, U>)
constexpr
optional(U&& u) = delete;

Parameters

Constructs an optional from another optional of type U

Synopsis

template<class U>
requires (std::is_constructible_v<T&, U> && !std::is_same_v<std::remove_cv_t<T>, optional<U>> &&
                 !std::is_same_v<T&, U> && detail::reference_constructs_from_temporary_v<T&, U>)
constexpr
optional(optional<U>&& rhs) = delete;

Description

Constructs the stored value from the rhs if it has a value, otherwise constructs an empty optional. If T& can be constructed from a temporary, this constructor is deleted to prevent binding a temporary to a reference.

Constructs an optional from another optional of type U.

Synopsis

template<class U>
requires (std::is_constructible_v<T&, U> && !std::is_same_v<std::remove_cv_t<T>, optional<U>> &&
             !std::is_same_v<T&, U> && !detail::reference_constructs_from_temporary_v<T&, U>)
constexpr
explicit(!std::is_convertible_v<U, T &>)
optional(optional<U>&& rhs) noexcept(noexcept(std::is_nothrow_constructible_v<T &, U>));

Description

Constructs the stored value from the rhs if it has a value, otherwise constructs an empty optional. If T& can be constructed from a temporary, this constructor is deleted to prevent binding a temporary to a reference.

Constructs an optional from another optional of type U

Synopsis

template<class U>
requires (std::is_constructible_v<T&, const U> && !std::is_same_v<std::remove_cv_t<T>, optional<U>> &&
                 !std::is_same_v<T&, U> && detail::reference_constructs_from_temporary_v<T&, const U>)
constexpr
optional(optional<U> const&& rhs) = delete;

Description

Constructs the stored value from the rhs if it has a value, otherwise constructs an empty optional. If T& can be constructed from a temporary, this constructor is deleted to prevent binding a temporary to a reference.

Constructs an optional from another optional of type U.

Synopsis

template<class U>
requires (std::is_constructible_v<T&, const U> && !std::is_same_v<std::remove_cv_t<T>, optional<U>> &&
             !std::is_same_v<T&, U> && !detail::reference_constructs_from_temporary_v<T&, const U>)
constexpr
explicit(!std::is_convertible_v<const U, T &>)
optional(optional<U> const&& rhs) noexcept(noexcept(std::is_nothrow_constructible_v<T &, const U>));

Description

Constructs the stored value from the rhs if it has a value, otherwise constructs an empty optional. If T& can be constructed from a temporary, this constructor is deleted to prevent binding a temporary to a reference.

In-place constructor.

Synopsis

template<class Arg>
requires (std::is_constructible_v<T&, Arg> && !detail::reference_constructs_from_temporary_v<T&, Arg>)
constexpr
explicit
optional(
    in_place_t,
    Arg&& arg);

Destructor.

Synopsis

constexpr
~optional() = default;

Description

Does not destroy the stored value, as it is a reference.

Assignment operators

Synopses

Assignment operator.

constexpr
optional&
operator=(optional const& rhs) noexcept = default;

Nullopt assignment operator.

constexpr
optional<T&>&
operator=(nullopt_t value) noexcept;

Return Value

Assignment operator.

Synopsis

constexpr
optional&
operator=(optional const& rhs) noexcept = default;

Description

If rhs has a value, assigns it to the stored value. Otherwise resets the stored value in *this.

Return Value

Nullopt assignment operator.

Synopsis

constexpr
optional<T&>&
operator=(nullopt_t value) noexcept;

Description

Destroys the current value if there is one, and leaves the optional in an empty state.

Return Value

Parameters

Applies a function to the stored value if there is one.

Synopsis

template<class F>
constexpr
auto
and_then(F&& f) const;

Description

The return type is the same as

Return Value

Returns an iterator to the beginning of the optional.

Synopsis

constexpr
optional<T&>::iterator
begin() const noexcept;

Return Value

Emplaces a new value in the optional, destroying the current one if

Synopsis

template<class U>
requires (std::is_constructible_v<T&, U> && !detail::reference_constructs_from_temporary_v<T&, U>)
constexpr
T&
emplace(U&& u) noexcept(std::is_nothrow_constructible_v<T &, U>);

Description

Constructs the stored value from u if it is convertible to T&.

Return Value

Returns an iterator to the end of the optional.

Synopsis

constexpr
optional<T&>::iterator
end() const noexcept;

Return Value

Checks if the optional has a value.

Synopsis

constexpr
bool
has_value() const noexcept;

Return Value

Returns a reference to the stored value.

Synopsis

constexpr
T&
operator*() const noexcept;

Return Value

Returns a pointer to the stored value.

Synopsis

constexpr
T*
operator->() const noexcept;

Return Value

Calls a function if the optional is empty.

Synopsis

template<class F>
constexpr
optional<T&>
or_else(F&& f) const;

Description

The return type is the same as the return type of f, which must return an optional type.

Return Value

• optional
• optional<T&>

Resets the optional to an empty state.

Synopsis

constexpr
void
reset() noexcept;

Swaps the contents of this optional with another.

Synopsis

constexpr
void
swap(optional& rhs) noexcept;

Applies a function to the stored value if there is one.

Synopsis

template<class F>
constexpr
optional<std::invoke_result_t<F, T&>>
transform(F&& f) const;

Description

The return type is the same as

Return Value

Returns the stored value if there is one, otherwise throws

Synopsis

constexpr
T&
value() const;

Return Value

Returns the stored value if there is one, otherwise returns u.

Synopsis

template<class U = std::remove_cv_t<T>>
constexpr
std::remove_cv_t<T>
value_or(U&& u) const;

Return Value

Converts the optional to a boolean value.

Synopsis

constexpr
explicit
operator bool() const noexcept;

Return Value

Synopses

template<
    int = 0,
    class T>
constexpr
optional<std::decay_t<T>>
make_optional(T&& t) noexcept(std::is_nothrow_constructible_v<optional<std::decay_t<T>>, T>)
requires std::is_constructible_v<std::decay_t<T>, T>;

template<
    typename T,
    typename... Args>
constexpr
optional<T>
make_optional(Args...&&... args) noexcept(std::is_nothrow_constructible_v<T, Args...>)
requires std::is_constructible_v<T, Args...>;

template<
    typename T,
    typename U,
    typename... Args>
constexpr
optional<T>
make_optional(
    std::initializer_list<U> il,
    Args...&&... args) noexcept(std::is_nothrow_constructible_v<T, std::initializer_list<U> &, Args...>)
requires std::is_constructible_v<T, std::initializer_list<U>&, Args...>;

Synopsis

template<
    int = 0,
    class T>
constexpr
optional<std::decay_t<T>>
make_optional(T&& t) noexcept(std::is_nothrow_constructible_v<optional<std::decay_t<T>>, T>)
requires std::is_constructible_v<std::decay_t<T>, T>;

Synopsis

template<
    typename T,
    typename... Args>
constexpr
optional<T>
make_optional(Args...&&... args) noexcept(std::is_nothrow_constructible_v<T, Args...>)
requires std::is_constructible_v<T, Args...>;

Synopsis

template<
    typename T,
    typename U,
    typename... Args>
constexpr
optional<T>
make_optional(
    std::initializer_list<U> il,
    Args...&&... args) noexcept(std::is_nothrow_constructible_v<T, std::initializer_list<U> &, Args...>)
requires std::is_constructible_v<T, std::initializer_list<U>&, Args...>;

Synopsis

template<class T>
constexpr
void
swap(
    optional<T>& x,
    optional<T>& y) noexcept(noexcept(lhs.swap(rhs)))
requires std::is_move_constructible_v<T> && std::is_swappable_v<T>;

Equality operators

Synopses

Equality operator

template<
    typename T,
    typename U>
constexpr
bool
operator==(
    optional<T> const& lhs,
    optional<U> const& rhs)
requires detail::optional_eq_rel<T, U>;

Equality operator

template<class T>
constexpr
bool
operator==(
    optional<T> const& lhs,
    nullopt_t rhs) noexcept;

Equality operator

template<
    typename T,
    typename U>
constexpr
bool
operator==(
    optional<T> const& lhs,
    U const& rhs)
requires detail::optional_eq_rel<T, U>;

Equality operator

template<
    typename T,
    typename U>
constexpr
bool
operator==(
    T const& lhs,
    optional<U> const& rhs)
requires detail::optional_eq_rel<T, U>;

Equality operator

Synopsis

template<
    typename T,
    typename U>
constexpr
bool
operator==(
    optional<T> const& lhs,
    optional<U> const& rhs)
requires detail::optional_eq_rel<T, U>;

Return Value

Parameters

Equality operator

Synopsis

template<class T>
constexpr
bool
operator==(
    optional<T> const& lhs,
    nullopt_t rhs) noexcept;

Return Value

Parameters

Equality operator

Synopsis

template<
    typename T,
    typename U>
constexpr
bool
operator==(
    optional<T> const& lhs,
    U const& rhs)
requires detail::optional_eq_rel<T, U>;

Return Value

Parameters

Equality operator

Synopsis

template<
    typename T,
    typename U>
constexpr
bool
operator==(
    T const& lhs,
    optional<U> const& rhs)
requires detail::optional_eq_rel<T, U>;

Return Value

Parameters

Inequality operators

Synopses

Inequality operator

template<
    typename T,
    typename U>
constexpr
bool
operator!=(
    optional<T> const& lhs,
    optional<U> const& rhs)
requires detail::optional_ne_rel<T, U>;

Inequality operator

template<
    typename T,
    typename U>
constexpr
bool
operator!=(
    optional<T> const& lhs,
    U const& rhs)
requires detail::optional_ne_rel<T, U>;

Inequality operator

template<
    typename T,
    typename U>
constexpr
bool
operator!=(
    T const& lhs,
    optional<U> const& rhs)
requires detail::optional_ne_rel<T, U>;

Inequality operator

Synopsis

template<
    typename T,
    typename U>
constexpr
bool
operator!=(
    optional<T> const& lhs,
    optional<U> const& rhs)
requires detail::optional_ne_rel<T, U>;

Return Value

Parameters

Inequality operator

Synopsis

template<
    typename T,
    typename U>
constexpr
bool
operator!=(
    optional<T> const& lhs,
    U const& rhs)
requires detail::optional_ne_rel<T, U>;

Return Value

Parameters

Inequality operator

Synopsis

template<
    typename T,
    typename U>
constexpr
bool
operator!=(
    T const& lhs,
    optional<U> const& rhs)
requires detail::optional_ne_rel<T, U>;

Return Value

Parameters

Less-than operators

Synopses

Less-than operator

template<
    typename T,
    typename U>
constexpr
bool
operator<(
    optional<T> const& lhs,
    optional<U> const& rhs)
requires detail::optional_lt_rel<T, U>;

Less-than operator

template<
    typename T,
    typename U>
constexpr
bool
operator<(
    optional<T> const& lhs,
    U const& rhs)
requires detail::optional_lt_rel<T, U>;

Less-than operator

template<
    typename T,
    typename U>
constexpr
bool
operator<(
    T const& lhs,
    optional<U> const& rhs)
requires detail::optional_lt_rel<T, U>;

Less-than operator

Synopsis

template<
    typename T,
    typename U>
constexpr
bool
operator<(
    optional<T> const& lhs,
    optional<U> const& rhs)
requires detail::optional_lt_rel<T, U>;

Return Value

Parameters

Less-than operator

Synopsis

template<
    typename T,
    typename U>
constexpr
bool
operator<(
    optional<T> const& lhs,
    U const& rhs)
requires detail::optional_lt_rel<T, U>;

Return Value

Parameters

Less-than operator

Synopsis

template<
    typename T,
    typename U>
constexpr
bool
operator<(
    T const& lhs,
    optional<U> const& rhs)
requires detail::optional_lt_rel<T, U>;

Return Value

Parameters

Less-than-or-equal operators

Synopses

Less-than-or-equal operator

template<
    typename T,
    typename U>
constexpr
bool
operator<=(
    optional<T> const& lhs,
    optional<U> const& rhs)
requires detail::optional_le_rel<T, U>;

Less-than-or-equal operator

template<
    typename T,
    typename U>
constexpr
bool
operator<=(
    optional<T> const& lhs,
    U const& rhs)
requires detail::optional_le_rel<T, U>;

Less-than-or-equal operator

template<
    typename T,
    typename U>
constexpr
bool
operator<=(
    T const& lhs,
    optional<U> const& rhs)
requires detail::optional_le_rel<T, U>;

Less-than-or-equal operator

Synopsis

template<
    typename T,
    typename U>
constexpr
bool
operator<=(
    optional<T> const& lhs,
    optional<U> const& rhs)
requires detail::optional_le_rel<T, U>;

Return Value

Parameters

Less-than-or-equal operator

Synopsis

template<
    typename T,
    typename U>
constexpr
bool
operator<=(
    optional<T> const& lhs,
    U const& rhs)
requires detail::optional_le_rel<T, U>;

Return Value

Parameters

Less-than-or-equal operator

Synopsis

template<
    typename T,
    typename U>
constexpr
bool
operator<=(
    T const& lhs,
    optional<U> const& rhs)
requires detail::optional_le_rel<T, U>;

Return Value

Parameters

Greater-than operators

Synopses

Greater-than operator

template<
    typename T,
    typename U>
constexpr
bool
operator>(
    optional<T> const& lhs,
    optional<U> const& rhs)
requires detail::optional_gt_rel<T, U>;

Greater-than operator

template<
    typename T,
    typename U>
constexpr
bool
operator>(
    optional<T> const& lhs,
    U const& rhs)
requires detail::optional_gt_rel<T, U>;

Greater-than operator

template<
    typename T,
    typename U>
constexpr
bool
operator>(
    T const& lhs,
    optional<U> const& rhs)
requires detail::optional_gt_rel<T, U>;

Greater-than operator

Synopsis

template<
    typename T,
    typename U>
constexpr
bool
operator>(
    optional<T> const& lhs,
    optional<U> const& rhs)
requires detail::optional_gt_rel<T, U>;

Return Value

Parameters

Greater-than operator

Synopsis

template<
    typename T,
    typename U>
constexpr
bool
operator>(
    optional<T> const& lhs,
    U const& rhs)
requires detail::optional_gt_rel<T, U>;

Return Value

Parameters

Greater-than operator

Synopsis

template<
    typename T,
    typename U>
constexpr
bool
operator>(
    T const& lhs,
    optional<U> const& rhs)
requires detail::optional_gt_rel<T, U>;

Return Value

Parameters

Greater-than-or-equal operators

Synopses

Greater-than-or-equal operator

template<
    typename T,
    typename U>
constexpr
bool
operator>=(
    optional<T> const& lhs,
    optional<U> const& rhs)
requires detail::optional_ge_rel<T, U>;

Greater-than-or-equal operator

template<
    typename T,
    typename U>
constexpr
bool
operator>=(
    optional<T> const& lhs,
    U const& rhs)
requires detail::optional_ge_rel<T, U>;

Greater-than-or-equal operator

template<
    typename T,
    typename U>
constexpr
bool
operator>=(
    T const& lhs,
    optional<U> const& rhs)
requires detail::optional_ge_rel<T, U>;

Greater-than-or-equal operator

Synopsis

template<
    typename T,
    typename U>
constexpr
bool
operator>=(
    optional<T> const& lhs,
    optional<U> const& rhs)
requires detail::optional_ge_rel<T, U>;

Return Value

Parameters

Greater-than-or-equal operator

Synopsis

template<
    typename T,
    typename U>
constexpr
bool
operator>=(
    optional<T> const& lhs,
    U const& rhs)
requires detail::optional_ge_rel<T, U>;

Return Value

Parameters

Greater-than-or-equal operator

Synopsis

template<
    typename T,
    typename U>
constexpr
bool
operator>=(
    T const& lhs,
    optional<U> const& rhs)
requires detail::optional_ge_rel<T, U>;

Return Value

Parameters

Three-way comparison operators

Synopses

Three-way comparison operator

template<
    typename T,
    std::three_way_comparable_with<T> U>
constexpr
std::compare_three_way_result_t<T, U>
operator<=>(
    optional<T> const& x,
    optional<U> const& y);

Three-way comparison operator

template<class T>
constexpr
std::strong_ordering
operator<=>(
    optional<T> const& x,
    nullopt_t rhs) noexcept;

Three-way comparison operator

template<
    typename T,
    typename U>
requires (!is_derived_from_optional<U>) && std::three_way_comparable_with<T, U>
constexpr
std::compare_three_way_result_t<T, U>
operator<=>(
    optional<T> const& x,
    U const& v);

Three-way comparison operator

Synopsis

template<
    typename T,
    std::three_way_comparable_with<T> U>
constexpr
std::compare_three_way_result_t<T, U>
operator<=>(
    optional<T> const& x,
    optional<U> const& y);

Return Value

Parameters

Three-way comparison operator

Synopsis

template<class T>
constexpr
std::strong_ordering
operator<=>(
    optional<T> const& x,
    nullopt_t rhs) noexcept;

Return Value

Parameters

Three-way comparison operator

Synopsis

template<
    typename T,
    typename U>
requires (!is_derived_from_optional<U>) && std::three_way_comparable_with<T, U>
constexpr
std::compare_three_way_result_t<T, U>
operator<=>(
    optional<T> const& x,
    U const& v);

Return Value

Parameters

Synopsis

inline constexpr in_place_t in_place = in_place{};

Tag to disengage optional objects.

Synopsis

inline constexpr nullopt_t nullopt = nullopt{nullopt_t::Tag::tag};

Synopsis

template<class T>
concept is_derived_from_optional = requires(const T& t) { // exposition only
    []<class U>(const optional<U>&) {}(t);
};