From 897d33956da896ab1b96c879de513df04ef7df5c Mon Sep 17 00:00:00 2001 From: Marika Lehmann Date: Wed, 31 Mar 2021 15:17:58 +0200 Subject: [PATCH] iox-#482 update optional&expected md, update doxygen docu of optional Signed-off-by: Marika Lehmann --- ...nd-error-values-are-returned-in-iceoryx.md | 22 +++++++++++++++++-- doc/website/getting-started/overview.md | 4 ++-- .../include/iceoryx_utils/cxx/optional.hpp | 8 +++---- 3 files changed, 26 insertions(+), 8 deletions(-) diff --git a/doc/website/advanced/how-optional-and-error-values-are-returned-in-iceoryx.md b/doc/website/advanced/how-optional-and-error-values-are-returned-in-iceoryx.md index 3926812853b..2501470cfd8 100644 --- a/doc/website/advanced/how-optional-and-error-values-are-returned-in-iceoryx.md +++ b/doc/website/advanced/how-optional-and-error-values-are-returned-in-iceoryx.md @@ -34,7 +34,7 @@ auto value = *result; ``` !!! attention -Accessing the value if there is no value is undefined behavior, so it must be checked beforehand. + Accessing the value if there is no value terminates the application, so it must be checked beforehand. We can achieve the same with the functional approach by providing a function for both cases. @@ -59,12 +59,17 @@ result = iox::cxx::nullopt; For a complete list of available functions see [``optional.hpp``](https://github.com/eclipse-iceoryx/iceoryx/blob/master/iceoryx_utils/include/iceoryx_utils/cxx/optional.hpp). +The ``iox::cxx::optional`` behaves like the [``std::optional``](https://en.cppreference.com/w/cpp/utility/optional) +except that it does not throw exceptions and has no undefined behavior. ### Expected ``iox::cxx::expected`` generalizes ``iox::cxx::optional`` by admitting a value of another type ``E`` instead of 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 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 -error type. For more information on how it is used for error handling see +error type. ``E`` must contain a static member or an enum value called ``INVALID_STATE``. Alternatively an +``ErrorTypeAdapter`` can be implemented. + +For more information on how it is used for error handling see [error-handling.md](https://github.com/eclipse-iceoryx/iceoryx/blob/master/doc/design/error-handling.md). Assume we have ``E`` as an error type, then we can create a value @@ -102,3 +107,16 @@ result.and_then(handleValue).or_else(handleError); There are more convenience functions such as ``value_or`` which provides the value or an alternative specified by the user. These can be found in [``expected.hpp``](https://github.com/eclipse-iceoryx/iceoryx/blob/master/iceoryx_utils/include/iceoryx_utils/cxx/expected.hpp). + +Note that when we move an ``expected``, the origin is set to the error value ``E::INVALID_STATE`` and will always return true +in ``has_error()``: +```cpp +cxx::expected result(iox::cxx::success(1421)); +cxx::expected anotherResult = std::move(result); + +if (result.has_error()) // is now true since it was moved +{ + result.get_error(); // returns E::INVALID_STATE +} +``` + diff --git a/doc/website/getting-started/overview.md b/doc/website/getting-started/overview.md index 2dd36aee57b..72f3944ad5b 100644 --- a/doc/website/getting-started/overview.md +++ b/doc/website/getting-started/overview.md @@ -51,7 +51,7 @@ else } ``` Here ``result`` is an ``expected`` and hence we may get an error. This can happen if we try to loan too many samples -and exhaust memory. We have to handle this possible error since the expected class has the ``nodiscard`` keyword +and exhaust memory. We have to handle this potential error since the expected class has the ``nodiscard`` keyword attached. This means we get a warning (or an error when build in strict mode) when we don't handle it. We could also explicitly discrad it with ``IOX_DISCARD_RESULT`` which is discouraged. If you want to know more about ``expected``, take a look at @@ -85,7 +85,7 @@ while (keepRunning) } } ``` -By calling ``take`` we get an ``expected`` and hence we have to handle a possible error. +By calling ``take`` we get an ``expected`` and hence we have to handle the potential error. And that's it. We have created our first simple iceoryx example. [Here](https://github.com/eclipse-iceoryx/iceoryx/blob/master/iceoryx_examples/README.md) you can find further examples diff --git a/iceoryx_utils/include/iceoryx_utils/cxx/optional.hpp b/iceoryx_utils/include/iceoryx_utils/cxx/optional.hpp index 89f744cc85d..81f43fa903b 100644 --- a/iceoryx_utils/include/iceoryx_utils/cxx/optional.hpp +++ b/iceoryx_utils/include/iceoryx_utils/cxx/optional.hpp @@ -186,25 +186,25 @@ class optional void reset() noexcept; /// @brief Returns a reference to the underlying value. If the optional has no - /// value the behavior is undefined. You need to verify that the + /// 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 T& value() & noexcept; /// @brief Returns a const reference to the underlying value. If the optional has no - /// value the behavior is undefined. You need to verify that the + /// 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 const T& value() const& noexcept; /// @brief Returns a rvalue reference to the underlying value. If the optional has no - /// value the behavior is undefined. You need to verify that the + /// 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 T&& value() && noexcept; /// @brief Returns a const rvalue reference to the underlying value. If the optional has no - /// value the behavior is undefined. You need to verify that the + /// 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 const T&& value() const&& noexcept;