Result is a modern, simple, and light-weight error-handling alternative to exceptions with a rich feature-set.
✔️ 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.
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");
}- 🔍 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
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.
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.
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.