Result
|
Result is a modern, simple, and light-weight error-handling alternative to exceptions.
C++11
(with more features in C++14
and C++17
)void
-type values in result
map
, flat_map
, and map_error
for easy functional useFor 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.
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:
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.
Although not required or enabled by default, Result supports two optional features that may be controlled through preprocessor symbols:
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:
Or it could also be defined using the compile-time definition with -D
, such as:
g++ -std=c++11 -DRESULT_NAMESPACE=example test.cpp
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:
std::abort
, causing immediate termination (and often, core-dumps for diagnostic purposes)stderr
to allow context for the terminationBuilding 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:
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:
Result is compatible with any compiler capable of compiling valid C++11
. Specifically, this has been tested and is known to work with:
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.