Template Class optional

Class Documentation

template<typename T>
class optional

Optional implementation from the C++17 standard with C++11. The interface is analog to the C++17 standard and it can be used in factory functions which can fail. 

#include "iceoryx_hoofs/cxx/optional.hpp"

cxx::optional<void*> SomeFactory() {
    void *memory = malloc(1234);
    if ( memory == nullptr )
        return cxx::nullopt_t();
    else
        return cxx::make_optional<void*>(memory);
}

int main() {
    auto var = SomeFactory();
    // never forget the has_value call before working with an optional
    if ( var.has_value() ) {
        // do stuff with var
    }
}

Public Types

using type = T

Public Functions

optional() noexcept

Creates an optional which has no value. If you access such an optional via .value() or the arrow operator the behavior is undefined.

optional(const nullopt_t&) noexcept

Creates an optional which has no value. If you access such an optional via .value() or the arrow operator the behavior is defined in the cxx::Expects handling.

optional(T &&value) noexcept

Creates an optional by forwarding value to the constructor of T. This optional has a value.

Parameters:

value – [in] rvalue of type T which will be moved into the optional

optional(const T &value) noexcept

Creates an optional by using the copy constructor of T.

Parameters:

value – [in] lvalue of type T which will be copy constructed into the optional

template<typename ...Targs>
optional(in_place_t, Targs&&... args) noexcept

Creates an optional and an object inside the optional on construction by perfectly forwarding args to the constructor of T. Could be used e.g. when T is not copyable/movable.

Template Parameters:

Targs – is the template parameter pack for the perfectly forwarded arguments

Parameters:

in_place_t – compile time variable to distinguish between constructors with certain behavior

~optional() noexcept

The destructor will call the destructor of T if a value is set.

optional(const optional &rhs) noexcept

Constructs a value with the copy constructor if rhs has a value. Otherwise it contains no value.

Parameters:

rhs – [in] source of the copy

optional(optional &&rhs) noexcept

Constructs a value with the move constructor if rhs has a value. Otherwise it contains no value.

Parameters:

rhs – [in] source of the move

optional &operator=(const optional &rhs) noexcept

Copies an optional. If the optional has a value then the copy assignment of that value is called. If the optional has no value a new value is constructed with the copy constructor.

Parameters:

rhs – [in] source of the copy

Returns:

reference to the current optional

optional &operator=(optional &&rhs) noexcept

Moves an optional. If the optional has a value then the move assignment of that value is called. If the optional has no value a new value is constructed with the move constructor.

Parameters:

rhs – [in] source of the move

Returns:

reference to the current optional

constexpr bool operator==(const optional<T> &rhs) const noexcept

If the optionals have values it compares these values by using their comparison operator.

Parameters:

rhs – [in] value to which this optional should be compared to

Returns:

true if the contained values are equal, otherwise false

constexpr bool operator==(const nullopt_t&) const noexcept

Comparison with nullopt_t for easier unset optional comparison.

Returns:

true if the optional is unset, otherwise false

constexpr bool operator!=(const optional<T> &rhs) const noexcept

If the optionals have values it compares these values by using their comparison operator.

Parameters:

rhs – [in] value to which this optional should be compared to

Returns:

true if the contained values are not equal, otherwise false

constexpr bool operator!=(const nullopt_t&) const noexcept

Comparision with nullopt_t for easier unset optional comparison.

Returns:

true if the optional is set, otherwise false

template<typename U = T>
std::enable_if<!std::is_same<U, optional<T>&>::value, optional>::type &operator=(U &&value) noexcept

Direct assignment of the underlying value. If the optional has no value then a new T is constructed by forwarding the assignment to T’s constructor. If the optional has a value the assignment operator of T is called.

Parameters:

value – [in] value to assign to the underlying optional value

Returns:

reference to the current optional

const T *operator->() const noexcept

Returns a pointer to the underlying value. If the optional has no value the behavior is undefined. You need to verify that the optional has a value by calling has_value() before using it.

Returns:

pointer of type const T to the underlying type

const T &operator*() const noexcept

Returns a reference to the underlying value. If the optional has no value the behavior is undefined. You need to verify that the optional has a value by calling has_value() before using it.

Returns:

reference of type const T to the underlying type

T *operator->() noexcept

Returns a pointer to the underlying value. If the optional has no value the behavior is undefined. You need to verify that the optional has a value by calling has_value() before using it.

Returns:

pointer of type T to the underlying type

T &operator*() noexcept

Returns a reference to the underlying value. If the optional has no value the behavior is undefined. You need to verify that the optional has a value by calling has_value() before using it.

Returns:

reference of type T to the underlying type

explicit constexpr operator bool() const noexcept

Will return true if the optional contains a value, otherwise false.

Returns:

true if optional contains a value, otherwise false

constexpr bool has_value() const noexcept

Will return true if the optional contains a value, otherwise false.

Returns:

true if optional contains a value, otherwise false

template<typename ...Targs>
T &emplace(Targs&&... args) noexcept

A new element is constructed by forwarding the arguments to the constructor of T. If the optional has a value then the destructor of T is called.

Parameters:

perfectly – [in] forwards args to the constructor of T to perform a placement new

Returns:

reference to the underlying type

void reset() noexcept

Calls the destructor of T if the optional has a value. If the optional has no value, nothing happens. After that call the optional has no more value.

T &value() & noexcept

Returns a reference to the underlying value. If the optional has no value the application terminates. You need to verify that the optional has a value by calling has_value() before using it.

Returns:

reference to the underlying type

const T &value() const & noexcept

Returns a const reference to the underlying value. If the optional has no value the application terminates. You need to verify that the optional has a value by calling has_value() before using it.

Returns:

const reference to the underlying type

T &&value() && noexcept

Returns a rvalue reference to the underlying value. If the optional has no value the application terminates. You need to verify that the optional has a value by calling has_value() before using it.

Returns:

rvalue reference to the underlying type

const T &&value() const && noexcept

Returns a const rvalue reference to the underlying value. If the optional has no value the application terminates. You need to verify that the optional has a value by calling has_value() before using it.

Returns:

const rvalue reference to the underlying type

template<typename U>
constexpr T value_or(U &&default_value) const noexcept

If the optional contains a value a copy of that value is returned, otherwise the default_value is returned.

Returns:

copy of the underlying type if the optional has a value otherwise a copy of default_value

optional &and_then(const cxx::function_ref<void(T&)> &callable) noexcept

calls the provided callable with the optional value as arguments if the optional contains a value

Parameters:

callable – [in] which has T as argument

Returns:

reference to this

const optional &and_then(const cxx::function_ref<void(const T&)> &callable) const noexcept

calls the provided callable with the optional value as arguments if the optional contains a value

Parameters:

callable – [in] which has T as argument

Returns:

reference to this

optional &or_else(const cxx::function_ref<void()> &callable) noexcept

calls the provided callable if the optional does not contain a value

Parameters:

callable – [in]

Returns:

reference to this

const optional &or_else(const cxx::function_ref<void()> &callable) const noexcept

calls the provided callable if the optional does not contain a value

Parameters:

callable – [in]

Returns:

reference to this