Result

Result is a modern, simple, and light-weight error-handling alternative to exceptions.

Teaser

template <typename To, typename From>
auto try_narrow(const From& from) noexcept -> cpp::result<To,narrow_error>
{
  const auto to = static_cast<To>(from);

  if ((to < To{}) != (from < From{})) {
    return cpp::fail(narrow_error::sign_change);
  }
  if (static_cast<From>(to) != from) {
    return cpp::fail(narrow_error::loss_of_data);
  }
  return to;
}

Live Example

Features

• Offers a coherent, light-weight alternative to exceptions
• Compatible with C++11 (with more features in C++14 and C++17)
• Single-header, header-only solution -- easily drops into any project
• Zero overhead abstractions -- don't pay for what you don't use.
• No dependencies
• Support for value-type, reference-type, and void-type values in result
• Monadic composition functions like map, flat_map, and map_error for easy functional use
• Comprehensively unit tested for both static behavior and runtime validation
• Incurs minimal cost when optimized, especially for trivial types

For more details and examples on what is available in Result, please check out the tutorial section.

For details describing how this implementation deviates from the std::result proposals, see this page.

Documentation

• Background
  A background on the problem Result solves
• Installation
  For a quick guide on how to install/use this in other projects
• Tutorial
  A quick pocket-guide to using Result
• Examples
  Some preset live-examples of this library in use
• API Reference
  For doxygen-generated API information
• Attribution
  Information about how to attribute this project
• FAQ
  A list of frequently asked questions

Background

Error cases in C++ are often difficult to discern from the API. Any function not marked noexcept can be assumed to throw an exception, but the exact type of exception, and if it even derives from std::exception, is ambiguous. Nothing in the language forces which exceptions may propagate from an API, which can make dealing with such APIs complicated.

Often it is more desirable to achieve noexcept functions where possible, since this allows for better optimizations in containers (e.g. optimal moves/swaps) and less cognitive load on consumers.

Having a result<T, E> type on your API not only semantically encodes that a function is able to fail, it also indicates to the caller how the function may fail, and what discrete, testable conditions may cause it to fail -- which is what this library intends to solve.

As a simple example, compare these two identical functions:

// (1)
auto to_uint32(const std::string& x) -> std::uint32_t;

// (2)
enum class parse_error { overflow=1, underflow=2, bad_input=3};
auto to_uint32(const std::string& x) noexcept -> result<std::uint32_t,parse_error>;

In (1), it is ambiguous what (if anything) this function may throw on failure, or how this error case may be accounted for.

In (2), on the other hand, it is explicit that to_uint32 cannot throw -- so there is no need for a catch handler. It's also clear that it may fail for whatever reasons are in parse_error, which discretely enumerates any possible case for failure.

Optional Features

Although not required or enabled by default, Result supports two optional features that may be controlled through preprocessor symbols:

1. Using a custom namespace, and
2. Disabling all exceptions

Using a Custom Namespace

The namespace that result is defined in is configurable. By default, it is defined in namespace cpp; however this can be toggled by defining the preprocessor symbol RESULT_NAMESPACE to be the name of the desired namespace.

This could be done either through a #define preprocessor directive:

#define RESULT_NAMESPACE example
#include <result.hpp>

auto test() -> example::result<int,int>;

Try Online

Or it could also be defined using the compile-time definition with -D, such as:

g++ -std=c++11 -DRESULT_NAMESPACE=example test.cpp

#include <result.hpp>

auto test() -> example::result<int,int>;

Try Online

Disabling Exceptions

Since result serves to act as an orthogonal/alternative error-handling mechanism to exceptions, it may be desirable to not have any exceptions at all. IF the compiler has been configured to disable exception entirely, simply having a path that even encounters a throw -- even if never reached in practice may trigger compile errors.

To account for this possibility, Result may have exceptions removed by defining the preprocessor symbol RESULT_DISABLE_EXCEPTIONS.

Note that if this is done, contract-violations will now behave differently:

• Contract violations will call std::abort, causing immediate termination (and often, core-dumps for diagnostic purposes)
• Contract violations will print directly to stderr to allow context for the termination
• Since exceptions are disabled, there is no way to perform a proper stack unwinding -- so destructors will not be run. There is simply no way to allow for proper RAII cleanup without exceptions in this case.

Try Online

Building the Unit Tests

Building the unit tests are not necessary to use this project. However, if you are interested in running these yourself, you will require the following installed:

• CMake: Used for configuring/building the project
• Catch2: the unit-test library

Additionally, you will need to toggle the RESULT_COMPILE_UNIT_TESTS option during cmake configuration to ensure that unit tests configure and build.

The easiest way to install Catch2 is using the conan package manager and installing with conan install <path to conanfile> from your build directory.

A complete example of configuring, compiling, and running the tests:

# Make the build directory and enter it
mkdir build && cd build
# Install Catch with conan (optional)
conan install ..
# Configure the project
cmake .. -DRESULT_COMPILE_UNIT_TESTS=On
# Build everything
cmake --build .
# run the tests
cmake --build . --target test

Compiler Compatibility

Result is compatible with any compiler capable of compiling valid C++11. Specifically, this has been tested and is known to work with:

• GCC 5, 6, 7, 8, 9, 10
• Clang 3.5, 3.6, 3.7, 3.8, 3.9, 4, 5, 6, 7, 8, 9, 10, 11
• Apple Clang (Xcode) 10.3, 11.2, 11.3, 12.3
• Visual Studio 2017^[1], 2019

Latest patch level releases are assumed in the versions listed above.

Note: Visual Studios 2015 is not currently supported due to an internal compiler error experienced in the default constructor of result. Support for this will be added at a later time.

^{[1] Visual Studios 2017 is officially supported, though toolchain 14.16 has some issues properly compiling map_error due to insufficient support for SFINAE.}

License

Result is licensed under the MIT License:

Copyright © 2017-2021 Matthew Rodusek

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

References

• P0323R9: std::expected proposal was used as an inspiration for the general template structure.
• bit::stl: the original version that seeded this repository, based off an earlier proposal version.