Introduction

Result is a header-only minimalistic library for safe, correct and complete error handling in C++

This library guarantees the following properties:

• When a function that can generate an error is called, there is a compile-time guarantee that the possible correct value cannot be retrieved without checking if there is an error.
• Errors shall not create side-effects, and shall preserve safety and determinism. This implies throwing exceptions are not allowed as mechanism. The library supports an easy integration for functions that can throw exceptions.
• Errors and correct results shall be mutually exclusive. This implies using union types and therefore C++ std::variant and std::visit. The type used to represent a result that might have an error is Result<T> where T is the type of the correct result. Additionally, it is available a GenericResult<T,E> where T is the correct result type and E the error type.
• Result<T> objects shall be monadic-composible. This implies that two Result<T> should be safely directly composable without any need for manual error checking. The library adds a bind method to compose results. As it's a monad, a functor map method is also added to transform safely the Result<T> types without doing any manual error checking either. For GenericError<T,E> there is both bind as well as bind_error as welll as map and map_error for each type. Note that GenericError<T,E> has two monads, one for the valid error and another for the error.
• Errors shall be chainable, allowing the creation of a stack of errors with different levels of abstraction. There is also a mechanism to chain errors without manually checking for them using chain_if_error.
• 100% covered by unit tests

Usage

For usage see unit tests.

We wrote unit tests so that they serve for a repository of examples as well as for functionality validation.

Commands

Build

make release

Test

make release && make test

Coverage

make release && make test && make coverage

Add library to your project

CMake Projects

First add to CMakeLists.txt the following find_package entry:

find_package(result CONFIG REQUIRED)

Finally, add to CMakeLists.txt the library in the included directories:

include_directories(include
  # Other include dirs go here
  ${result_INCLUDE_DIRS}
)

ROS2 Projects

First follow the previous section for CMake Projects to get the CMakeLists.txt ready.

The next step is adding the dependency in package.xml:

<build>result</build>

Clone the result repository in your workspace /src folder

cd $WORKSPACE/src && git clone https://github.com/cmrobotics/result.git

Finally, add the include in your C++ sources:

#include <result.hpp>