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

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 \ ✔️ Optional support to disable all exceptions and rename the cpp namespace \ ✔️ Comprehensively unit tested for both static behavior and runtime validation \ ✔️ Incurs minimal cost when optimized, especially for trivial types

Check out the tutorial to see what other features Result offers.

If you're interested in how cpp::result deviates from std::expected proposals, please see this page.

Teaser

enum class narrow_error{ none, loss_of_data };
 
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 (static_cast<From>(to) != from) {
    return cpp::fail(narrow_error::loss_of_data);
  }
 
  return to;
}
 
struct {
  template <typename T>
  auto operator()(const T& x) -> std::string {
    return std::to_string(x);
  }
} to_string;
 
auto main() -> int {
  assert(try_narrow<std::uint8_t>(42LL).map(to_string) == "42");
}

Try online

Quick References

🔍 Why result? \ 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
📄 API Reference \ For doxygen-generated API information
🚀 Contributing \ How to contribute to the Result project
💼 Attribution \ Information about how to attribute this project
❓ FAQ \ A list of frequently asked questions

Why `result`?

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.

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.