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 2 April 2022 at 16:37:47 CEST