Skip to content

iox::cxx::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. More...

#include <iceoryx_hoofs/cxx/optional.hpp>

Public Types🔗

Name
using T type

Public Functions🔗

Name
optional()
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 & )
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)
Creates an optional by forwarding value to the constructor of T. This optional has a value.
optional(const T & value)
Creates an optional by using the copy constructor of T.
template <typename... Targs>
optional(in_place_t , Targs &&... args)
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.
~optional()
The destructor will call the destructor of T if a value is set.
optional(const optional & rhs)
Constructs a value with the copy constructor if rhs has a value. Otherwise it contains no value.
optional(optional && rhs)
Constructs a value with the move constructor if rhs has a value. Otherwise it contains no value.
optional & operator=(const optional & rhs)
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.
optional & operator=(optional && rhs)
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.
constexpr bool operator==(const optional< T > & rhs) const
If the optionals have values it compares these values by using their comparison operator.
constexpr bool operator==(const nullopt_t & ) const
Comparison with nullopt_t for easier unset optional comparison.
constexpr bool operator!=(const optional< T > & rhs) const
If the optionals have values it compares these values by using their comparison operator.
constexpr bool operator!=(const nullopt_t & ) const
Comparision with nullopt_t for easier unset optional comparison.
template <typename U =T>
std::enable_if<!std::is_same< U, optional< T > & >::value, optional >::type &
operator=(U && value)
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.
const T * operator->() const
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.
const T & operator*() const
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.
T * operator->()
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.
T & operator*()
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.
constexpr operator bool() const
Will return true if the optional contains a value, otherwise false.
constexpr bool has_value() const
Will return true if the optional contains a value, otherwise false.
template <typename... Targs>
T &
emplace(Targs &&... args)
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.
void reset()
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()
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.
const T & value() const
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.
T && value()
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.
const T && value() const
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.
template <typename U >
constexpr T
value_or(U && default_value) const
If the optional contains a value a copy of that value is returned, otherwise the default_value is returned.
optional & and_then(const cxx::function_ref< void(T &)> & callable)
calls the provided callable with the optional value as arguments if the optional contains a value
const optional & and_then(const cxx::function_ref< void(const T &)> & callable) const
calls the provided callable with the optional value as arguments if the optional contains a value
optional & or_else(const cxx::function_ref< void()> & callable)
calls the provided callable if the optional does not contain a value
const optional & or_else(const cxx::function_ref< void()> & callable) const
calls the provided callable if the optional does not contain a value

Detailed Description🔗

template <typename T >
class iox::cxx::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 Documentation🔗

using type🔗

using iox::cxx::optional< T >::type =  T;

Public Functions Documentation🔗

function optional🔗

optional()

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

function optional🔗

optional(
    const nullopt_t & 
)

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.

function optional🔗

optional(
    T && value
)

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

Parameters:

  • value rvalue of type T which will be moved into the optional

function optional🔗

optional(
    const T & value
)

Creates an optional by using the copy constructor of T.

Parameters:

  • value lvalue of type T which will be copy constructed into the optional

function optional🔗

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

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.

Parameters:

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

Template Parameters:

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

function ~optional🔗

~optional()

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

function optional🔗

optional(
    const optional & rhs
)

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

Parameters:

  • rhs source of the copy

function optional🔗

optional(
    optional && rhs
)

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

Parameters:

  • rhs source of the move

function operator=🔗

optional & operator=(
    const optional & rhs
)

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 source of the copy

Return: reference to the current optional

function operator=🔗

optional & operator=(
    optional && rhs
)

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 source of the move

Return: reference to the current optional

function operator==🔗

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

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

Parameters:

  • rhs value to which this optional should be compared to

Return: true if the contained values are equal, otherwise false

function operator==🔗

constexpr bool operator==(
    const nullopt_t & 
) const

Comparison with nullopt_t for easier unset optional comparison.

Return: true if the optional is unset, otherwise false

function operator!=🔗

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

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

Parameters:

  • rhs value to which this optional should be compared to

Return: true if the contained values are not equal, otherwise false

function operator!=🔗

constexpr bool operator!=(
    const nullopt_t & 
) const

Comparision with nullopt_t for easier unset optional comparison.

Return: true if the optional is set, otherwise false

function operator=🔗

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

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 value to assign to the underlying optional value

Return: reference to the current optional

function operator->🔗

const T * operator->() const

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.

Return: pointer of type const T to the underlying type

function operator*🔗

const T & operator*() const

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.

Return: reference of type const T to the underlying type

function operator->🔗

T * operator->()

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.

Return: pointer of type T to the underlying type

function operator*🔗

T & operator*()

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.

Return: reference of type T to the underlying type

function operator bool🔗

explicit constexpr operator bool() const

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

Return: true if optional contains a value, otherwise false

function has_value🔗

constexpr bool has_value() const

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

Return: true if optional contains a value, otherwise false

function emplace🔗

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

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 forwards args to the constructor of T to perform a placement new

Return: reference to the underlying type

function reset🔗

void reset()

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.

function value🔗

T & value()

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.

Return: reference to the underlying type

function value🔗

const T & value() const

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.

Return: const reference to the underlying type

function value🔗

T && value()

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.

Return: rvalue reference to the underlying type

function value🔗

const T && value() const

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.

Return: const rvalue reference to the underlying type

function value_or🔗

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

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

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

function and_then🔗

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

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

Parameters:

  • callable which has T as argument

Return: reference to this

function and_then🔗

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

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

Parameters:

  • callable which has T as argument

Return: reference to this

function or_else🔗

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

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

Parameters:

  • callable

Return: reference to this

function or_else🔗

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

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

Parameters:

  • callable

Return: reference to this


Updated on 18 December 2023 at 13:11:42 CET