#include <Corrade/Containers/Optional.h>
template<class T>
Corrade::Containers::Optional class

Lightweight optional value.

Equivalent to std::optional from C++17, provides an optional checked storage for object of type T. The optional object can be seen as a container of T objects with maximal size 1 and can be in two states, either empty or having a value. A non-allocating counterpart to Pointer.

A common use for an optional object is for a return value of function that can fail — like Pointer, but without the unnecessary allocation overhead. Similarly to Pointer, the presence of an object can be checked using operator bool(), or alternatively by comparing to NullOpt (same as a pointer can be compared to nullptr). The stored object can be accessed using operator->(), operator*() or using implicit conversion, while attempt to access a stored object in an empty state leads to assertion error.

Unlike std::optional, this class does not provide a constexpr implementation or ordering operators, which makes it fairly simple and lightweight. If you need the extra features, use the standard std::optional.

STL compatibility

Instances of Optional are explicitly copy- and move-convertible to and from std::optional if you include Corrade/Containers/OptionalStl.h and build your code with C++17 enabled. The conversion is provided in a separate header to avoid unconditional #include <optional>, which significantly affects compile times. Additionally, the optional(T&&) overload also allows for such a conversion. Example:

#include <Corrade/Containers/Optional.h>

…

std::optional<int> a{5};
Containers::Optional<int> b(a);

std::optional<std::string> c(Containers::Optional<std::string>{"hello"});

auto d = Containers::optional(std::optional<int>{17});
        // d is Containers::Optional<int>

Public types

using Type = T new in Git master
Value type.

Constructors, destructors, conversion operators

Optional(NullOptT = NullOpt) noexcept
Default constructor.
Optional(const T& value) noexcept(…)
Construct optional object by copy.
Optional(T&& value) noexcept(…)
Construct optional object by move.
template<class ... Args>
Optional(Corrade::InPlaceInitT, Args && ... args) noexcept(…)
Construct optional object in-place.
template<class U, class = decltype(Implementation::OptionalConverter<T, U>::from(std::declval<const U&>()))>
Optional(const U& other) explicit noexcept(…)
Copy-construct an optional from external representation.
template<class U, class = decltype(Implementation::OptionalConverter<T, U>::from(std::declval<U && >()))>
Optional(U&& other) explicit noexcept(…)
Move-construct an optional from external representation.
Optional(const Optional<T>& other) noexcept(…)
Copy constructor.
Optional(Optional<T>&& other) noexcept(…)
Move constructor.
template<class U, class = decltype(Implementation::OptionalConverter<T, U>::to(std::declval<const Optional<T>&>()))>
operator U() const & explicit
Copy-convert the optional to external representation.
template<class U, class = decltype(Implementation::OptionalConverter<T, U>::to(std::declval<Optional<T> && >()))>
operator U() && explicit
Move-convert the optional to external representation.
~Optional()
Destructor.
operator bool() const explicit
Whether the optional object has a value.

Public functions

auto operator=(const Optional<T>& other) -> Optional<T>& noexcept(…)
Copy assignment.
auto operator=(Optional<T>&& other) -> Optional<T>& noexcept(…)
Move assignment.
auto operator=(NullOptT) -> Optional<T>& noexcept
Clear the contained value.
auto operator==(const Optional<T>& other) const -> bool
Equality comparison to another optional.
auto operator!=(const Optional<T>& other) const -> bool
Non-equality comparison to another optional.
auto operator==(NullOptT) const -> bool
Equality comparison to a null optional.
auto operator!=(NullOptT) const -> bool
Non-equality comparison to a null optional.
auto operator==(const T& other) const -> bool
Equality comparison to a value.
auto operator!=(const T& other) const -> bool
Non-equality comparison to a value.
auto operator->() -> T*
Access the stored object.
auto operator->() const -> const T*
auto operator*() & -> T&
Access the stored object.
auto operator*() && -> T
auto operator*() const & -> const T&
template<class ... Args>
auto emplace(Args && ... args) -> T&
Emplace a new value.

Function documentation

template<class T>
Corrade::Containers::Optional<T>::Optional(NullOptT = NullOpt) noexcept

Default constructor.

Creates an optional object in empty state.

template<class T>
Corrade::Containers::Optional<T>::Optional(const T& value) noexcept(…)

Construct optional object by copy.

Stores a copy of passed object.

template<class T>
Corrade::Containers::Optional<T>::Optional(T&& value) noexcept(…)

Construct optional object by move.

Moves the passed object to internal storage.

template<class T> template<class ... Args>
Corrade::Containers::Optional<T>::Optional(Corrade::InPlaceInitT, Args && ... args) noexcept(…)

Construct optional object in-place.

Constructs the value by passing args to its constructor in-place.

template<class T> template<class U, class = decltype(Implementation::OptionalConverter<T, U>::from(std::declval<const U&>()))>
Corrade::Containers::Optional<T>::Optional(const U& other) explicit noexcept(…)

Copy-construct an optional from external representation.

template<class T> template<class U, class = decltype(Implementation::OptionalConverter<T, U>::from(std::declval<U && >()))>
Corrade::Containers::Optional<T>::Optional(U&& other) explicit noexcept(…)

Move-construct an optional from external representation.

template<class T> template<class U, class = decltype(Implementation::OptionalConverter<T, U>::to(std::declval<const Optional<T>&>()))>
Corrade::Containers::Optional<T>::operator U() const & explicit

Copy-convert the optional to external representation.

template<class T> template<class U, class = decltype(Implementation::OptionalConverter<T, U>::to(std::declval<Optional<T> && >()))>
Corrade::Containers::Optional<T>::operator U() && explicit

Move-convert the optional to external representation.

template<class T>
Corrade::Containers::Optional<T>::~Optional()

Destructor.

If the optional object is not empty, calls destructor on stored value.

template<class T>
Corrade::Containers::Optional<T>::operator bool() const explicit

Whether the optional object has a value.

Returns true if the optional object has a value, false otherwise.

template<class T>
Optional<T>& Corrade::Containers::Optional<T>::operator=(const Optional<T>& other) noexcept(…)

Copy assignment.

If the object already contains a value, calls its destructor. Copy-constructs the value from other using placement-new.

template<class T>
Optional<T>& Corrade::Containers::Optional<T>::operator=(Optional<T>&& other) noexcept(…)

Move assignment.

If both objects contain a value, the value is swapped. Otherwise, if the object contains a value, calls its destructor. If other contains a value, move-constructs the value from it using placement new.

template<class T>
Optional<T>& Corrade::Containers::Optional<T>::operator=(NullOptT) noexcept

Clear the contained value.

If the object contains a value, calls its destructor. Compared to operator=(Optional<T>&&) this doesn't require the type to be move-assignable.

template<class T>
bool Corrade::Containers::Optional<T>::operator==(const Optional<T>& other) const

Equality comparison to another optional.

Returns true if either both instances are empty or both instances have a value and the values compare equal, false otherwise.

template<class T>
bool Corrade::Containers::Optional<T>::operator!=(const Optional<T>& other) const

Non-equality comparison to another optional.

Returns negation of operator==(const Optional<T>&) const.

template<class T>
bool Corrade::Containers::Optional<T>::operator==(NullOptT) const

Equality comparison to a null optional.

Returns true if the instance is empty, false otherwise.

template<class T>
bool Corrade::Containers::Optional<T>::operator!=(NullOptT) const

Non-equality comparison to a null optional.

Returns true if the instance has a value, false otherwise.

template<class T>
bool Corrade::Containers::Optional<T>::operator==(const T& other) const

Equality comparison to a value.

Returns true if the instance has a value which compares equal to other, false otherwise.

template<class T>
bool Corrade::Containers::Optional<T>::operator!=(const T& other) const

Non-equality comparison to a value.

Returns negation of operator==(const T&) const.

template<class T>
T* Corrade::Containers::Optional<T>::operator->()

Access the stored object.

Expects that the optional object has a value.

template<class T>
const T* Corrade::Containers::Optional<T>::operator->() const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<class T>
T& Corrade::Containers::Optional<T>::operator*() &

Access the stored object.

Expects that the optional object has a value.

template<class T>
T Corrade::Containers::Optional<T>::operator*() &&

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<class T>
const T& Corrade::Containers::Optional<T>::operator*() const &

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<class T> template<class ... Args>
T& Corrade::Containers::Optional<T>::emplace(Args && ... args)

Emplace a new value.

If the object already contains a value, calls its destructor. Constructs the value by passing args to its constructor using placement new.

template<class T> template<class T>
bool operator==(NullOptT, const Optional<T>& b)

Equality comparison of a null optional and an optional.

See Optional::operator==(NullOptT) const for more information.

template<class T> template<class T>
bool operator!=(NullOptT, const Optional<T>& b)

Non-euality comparison of a null optional and an optional.

See Optional::operator!=(NullOptT) const for more information.

template<class T> template<class T>
bool operator==(const T& a, const Optional<T>& b)

Equality comparison of a value and an optional.

See Optional::operator==(const T&) const for more information.

template<class T> template<class T>
bool operator!=(const T& a, const Optional<T>& b)

Non-equality comparison of a value and an optional.

See Optional::operator!=(const T&) const for more information.

template<class T> template<class T>
Optional<typename std::decay<T>::type> optional(T&& value)

Make an optional.

Convenience alternative to Optional::Optional(const T&) or Optional::Optional(T&&). The following two lines are equivalent:

std::string value;

auto a = Containers::Optional<std::string>{value};
auto b = Containers::optional(value);

template<class T> template<class T, class ... Args>
Optional<T> optional(Args && ... args)

Make an optional.

Convenience alternative to Optional::Optional(InPlaceInitT, Args&&... args). The following two lines are equivalent:

auto a = Containers::Optional<std::string>{InPlaceInit, 'a', 'b'};
auto b = Containers::optional<std::string>('a', 'b');

template<class T> template<class T>
auto optional(T&& other)

Make an optional from external representation.

template<class T> template<class T>
Utility::Debug& operator<<(Utility::Debug& debug, const Optional<T>& value)

Debug output operator.