|
| 1 | +# How optional and error values are returned in iceoryx |
| 2 | + |
| 3 | +Many parts of the iceoryx C++ API follow a functional programming approach and allow the user to specify functions |
| 4 | +which handle the possible cases, e.g. what should happen when data is received. |
| 5 | + |
| 6 | +This is very flexible but requires using the monadic types `cxx::expected` and `cxx::optional`, which we |
| 7 | +introduce in the following sections. |
| 8 | + |
| 9 | +## Optional |
| 10 | + |
| 11 | +The type `iox::cxx::optional<T>` is used to indicate that there may or may not be a value of a specific type `T` |
| 12 | +available. This is essentially the 'maybe [monad](https://en.wikipedia.org/wiki/Monad_(functional_programming))' in |
| 13 | +functional programming. Assuming we have some optional (usually the result of some computation) |
| 14 | + |
| 15 | +```cpp |
| 16 | +optional<int> result = someComputation(); |
| 17 | +``` |
| 18 | + |
| 19 | +we can check for its value using |
| 20 | + |
| 21 | +```cpp |
| 22 | +if(result.has_value()) |
| 23 | +{ |
| 24 | + auto value = result.value(); |
| 25 | + // do something with the value |
| 26 | +} |
| 27 | +else |
| 28 | +{ |
| 29 | + // handle the case that there is no value |
| 30 | +} |
| 31 | +``` |
| 32 | + |
| 33 | +A shorthand to get the value is |
| 34 | + |
| 35 | +```cpp |
| 36 | +auto value = *result; |
| 37 | +``` |
| 38 | + |
| 39 | +!!! attention |
| 40 | + Accessing the value if there is no value terminates the application, so it must be checked beforehand. |
| 41 | + |
| 42 | +We can achieve the same with the functional approach by providing a function for both cases. |
| 43 | + |
| 44 | +```cpp |
| 45 | +result.and_then([](int& value) { /*do something with the value*/ }) |
| 46 | + .or_else([]() { /*handle the case that there is no value*/ }); |
| 47 | +``` |
| 48 | +
|
| 49 | +Notice that we get the value by reference, so if a copy is desired it has to be created explicitly in the |
| 50 | +[lambda](https://en.wikipedia.org/wiki/Anonymous_function#C++_(since_C++11)) or function we pass. |
| 51 | +
|
| 52 | +The optional can be initialized from a value directly |
| 53 | +
|
| 54 | +```cpp |
| 55 | +optional<int> result = 73; |
| 56 | +result = 37; |
| 57 | +``` |
| 58 | + |
| 59 | +If the optional is default initialized, it is automatically set to its null value of type `iox::cxx::nullopt_t`. |
| 60 | +This can be also done directly by using the constant `iox::cxx::nullopt` |
| 61 | + |
| 62 | +```cpp |
| 63 | +result = iox::cxx::nullopt; |
| 64 | +``` |
| 65 | + |
| 66 | +For a complete list of available functions see |
| 67 | +[`optional.hpp`](https://github.com/eclipse-iceoryx/iceoryx/blob/master/iceoryx_hoofs/include/iceoryx_hoofs/cxx/optional.hpp). |
| 68 | +The `iox::cxx::optional` behaves like the [`std::optional`](https://en.cppreference.com/w/cpp/utility/optional) |
| 69 | +except that it does not throw exceptions and has no undefined behavior. |
| 70 | + |
| 71 | +## Expected |
| 72 | + |
| 73 | +`iox::cxx::expected<T, E>` generalizes `iox::cxx::optional` by admitting a value of another type `E` instead of |
| 74 | +no value at all, i.e. it contains either a value of type `T` or `E`. In this way, `expected` is a special case of |
| 75 | +the 'either monad'. It is usually used to pass a value of type `T` or an error that may have occurred, i.e. `E` is the |
| 76 | +error type. |
| 77 | + |
| 78 | +For more information on how it is used for error handling see |
| 79 | +[error-handling.md](https://github.com/eclipse-iceoryx/iceoryx/blob/master/doc/design/error-handling.md). |
| 80 | + |
| 81 | +Assume we have `E` as an error type, then we can create a value |
| 82 | + |
| 83 | +```cpp |
| 84 | +iox::cxx::expected<int, E> result(iox::cxx::success<int>(73)); |
| 85 | +``` |
| 86 | +
|
| 87 | +and use the value or handle a potential error |
| 88 | +
|
| 89 | +```cpp |
| 90 | +if (!result.has_error()) |
| 91 | +{ |
| 92 | + auto value = result.value(); |
| 93 | + // do something with the value |
| 94 | +} |
| 95 | +else |
| 96 | +{ |
| 97 | + auto error = result.get_error(); |
| 98 | + // handle the error |
| 99 | +} |
| 100 | +``` |
| 101 | + |
| 102 | +If we need an error value, we set |
| 103 | + |
| 104 | +```cpp |
| 105 | +result = iox::cxx::error<E>(errorCode); |
| 106 | +``` |
| 107 | + |
| 108 | +which assumes that `E` can be constructed from an `errorCode`. |
| 109 | + |
| 110 | +We again can employ a functional approach like this: |
| 111 | + |
| 112 | +```cpp |
| 113 | +auto handleValue = [](int& value) { /*do something with the value*/ }; |
| 114 | +auto handleError = [](E& value) { /*handle the error*/ }; |
| 115 | +result.and_then(handleValue).or_else(handleError); |
| 116 | +``` |
| 117 | +
|
| 118 | +There are more convenience functions such as `value_or` which provides the value or an alternative specified by the |
| 119 | +user. These can be found in |
| 120 | +[`expected.hpp`](https://github.com/eclipse-iceoryx/iceoryx/blob/master/iceoryx_hoofs/include/iceoryx_hoofs/cxx/expected.hpp). |
| 121 | +
|
| 122 | +Note that when we move an `expected`, the origin contains a moved `T` or `E`, depending on the content before the move. |
| 123 | +This mirrors the behavior of moving the content out of the `iox::cxx::expected` like with |
| 124 | +`auto foo = std::move(bar.value());` with `bar` being an `iox::cxx::expected`. |
| 125 | +Like all objects, `T` and `E` must therefore be in a well defined state after the move. |
0 commit comments