1+++ 2title = "`basic_result<T, E, NoValuePolicy>`" 3description = "A sum type carrying either a successful `T`, or a disappointment `E`, with `NoValuePolicy` specifying what to do if one tries to read state which isn't there." 4+++ 5 6A sum type carrying either a `T` or an `E`, with `NoValuePolicy` specifying what to do if one tries to read state which isn't there. Either or both of `T` and `E` can be `void` to indicate no value for that state is present. Note that `E = void` makes basic result into effectively an `optional<T>`, but with `NoValuePolicy` configurable behaviour. Detectable using {{% api "is_basic_result<T>" %}}. 7 8*Requires*: Concept requirements if C++ 20, else static asserted: 9 10- That trait {{% api "type_can_be_used_in_basic_result<R>" %}} is true for both `T` and `E`. 11- That either `E` is `void` or `DefaultConstructible`. 12 13*Namespace*: `BOOST_OUTCOME_V2_NAMESPACE` 14 15*Header*: `<boost/outcome/basic_result.hpp>` 16 17*Inclusions*: The very lightest weight of C and C++ header files: 18 191. `<cstdint>` 202. `<initializer_list>` 213. `<iosfwd>` 224. `<new>` 235. `<type_traits>` 246. If {{% api "BOOST_OUTCOME_USE_STD_IN_PLACE_TYPE" %}} is `1`, `<utility>` (defaults to `1` for C++ 17 or later only) 257. If C++ exceptions disabled and `BOOST_OUTCOME_DISABLE_EXECINFO` undefined only (used to print stack backtraces on "exception throw"): 26 1. `<sal.h>` (Windows only) 27 2. `<stddef.h>` (Windows only) 28 3. `<string.h>` (Windows only) 29 4. `<execinfo.h>` (POSIX only) 308. `<cstdio>` 319. `<cstdlib>` 3210. `<cassert>` 33 34This very light weight set of inclusion dependencies makes basic result suitable for use in global header files of very large C++ codebases. 35 36### Design rationale 37 38The basic result type is the main workhorse type of the Outcome library, providing a simple sum type with optional values representing success or disappointment. Unlike {{% api "std::expected<T, E>" %}}, Outcome's result type is designed specifically for convenience when implementing failure handling across very large codebases, and it has a number of API differences to facilitate that. 39 40The first major design difference is that basic result models its constructor design on {{% api "std::variant<...>" %}}, rather than modelling {{% api "std::optional<T>" %}}'s constructor design like `std::expected<T, E>` does. This means that basic result will implicitly construct either a `T` or an `E` if doing so is unambiguous, same as `variant` does. Where implicit construction is ambiguous, the implicit constructors disable and a `T` or `E` can be specified via {{% api "in_place_type_t<T>" %}}, or via {{% api "success_type<T>" %}} or {{% api "failure_type<T>" %}}. We implement a subset of variant's constructors for improved compile time impact, so the implicit and explicit constructor design is split into fixed subsets to reduce SFINAE execution. 41 42The second major design difference is that union storage is NOT used, as it is assumed that `sizeof(E)` will be small for failure handling. This very considerably reduces load on the compiler, and substantially improves compile times in very large C++ 14 codebases, because copies and moves do not need to jump through complex ceremony in order to implement the never-empty guarantees which would be required in a union storage based implementation (C++ 17 onwards does far fewer copy and move constructor instantiations, but it all adds up -- work avoided is always the fastest). 43 44### Public member type aliases 45 46- `value_type` is `T`. 47- `error_type` is `E`. 48- `value_type_if_enabled` is `T` if construction from `T` is available, else it is a usefully named unusable internal type. 49- `error_type_if_enabled` is `E` if construction from `E` is available, else it is a usefully named unusable internal type. 50- `rebind<A, B = E, C = NoValuePolicy>` is `basic_result<A, B, C>`. 51 52### Protected member predicate booleans 53 54- `predicate::constructors_enabled` is constexpr boolean true if decayed `value_type` and decayed `error_type` are not the same type. 55 56- `predicate::implicit_constructors_enabled` is constexpr boolean true if: 57 1. `predicate::constructors_enabled` is true. 58 2. Trait {{% api "is_error_type<E>" %}} is not true for both decayed `value_type` and decayed `error_type` at the same time. 59 3. `value_type` is not implicitly constructible from `error_type` and `error_type` is not implicitly constructible from `value_type`.<br>OR<br>trait {{% api "is_error_type<E>" %}} is true for decayed `error_type` and `error_type` is not implicitly constructible from `value_type` and `value_type` is an integral type. 60 61- `predicate::enable_value_converting_constructor<A>` is constexpr boolean true if: 62 1. `predicate::constructors_enabled` is true. 63 2. Decayed `A` is not this `basic_result` type. 64 3. `predicate::implicit_constructors_enabled` is true. 65 4. Decayed `A` is not an `in_place_type_t`. 66 5. Trait {{% api "is_error_type_enum<E, Enum>" %}} is false for `error_type` and decayed `A`. 67 6. `value_type` is implicitly constructible from `A` and `error_type` is not implicitly constructible from `A`.<br>OR<br>`value_type` is the exact same type as decayed `A` and `value_type` is implicitly constructible from `A`. 68 69- `predicate::enable_error_converting_constructor<A>` is constexpr boolean true if: 70 1. `predicate::constructors_enabled` is true. 71 2. Decayed `A` is not this `basic_result` type. 72 3. `predicate::implicit_constructors_enabled` is true. 73 4. Decayed `A` is not an `in_place_type_t`. 74 5. Trait {{% api "is_error_type_enum<E, Enum>" %}} is false for `error_type` and decayed `A`. 75 6. `value_type` is not implicitly constructible from `A` and `error_type` is implicitly constructible from `A`.<br>OR<br>`error_type` is the exact same type as decayed `A` and `error_type` is implicitly constructible from `A`. 76 77- `predicate::enable_error_condition_converting_constructor<ErrorCondEnum>` is constexpr boolean true if: 78 1. `predicate::constructors_enabled` is true. 79 2. Decayed `ErrorCondEnum` is not this `basic_result` type. 80 3. Decayed `ErrorCondEnum` is not an `in_place_type_t`. 81 4. Trait {{% api "is_error_type_enum<E, Enum>" %}} is true for `error_type` and decayed `ErrorCondEnum`. 82 83- `predicate::enable_compatible_conversion<A, B, C>` is constexpr boolean true if: 84 1. `predicate::constructors_enabled` is true. 85 2. `basic_result<A, B, C>` is not this `basic_result` type. 86 3. `A` is `void` OR `value_type` is explicitly constructible from `A`. 87 4. `B` is `void` OR `error_type` is explicitly constructible from `B`. 88 89- `predicate::enable_make_error_code_compatible_conversion<A, B, C>` is constexpr boolean true if: 90 1. `predicate::constructors_enabled` is true. 91 2. `basic_result<A, B, C>` is not this `basic_result` type. 92 3. Trait {{% api "is_error_code_available<E>" %}} is true for decayed `error_type`. 93 4. `predicate::enable_compatible_conversion<A, B, C>` is not true. 94 5. `A` is `void` OR `value_type` is explicitly constructible from `A`. 95 6. `error_type` is explicitly constructible from `make_error_code(B)`. 96 97- `predicate::enable_make_exception_ptr_compatible_conversion<A, B, C>` is constexpr boolean true if: 98 1. `predicate::constructors_enabled` is true. 99 2. `basic_result<A, B, C>` is not this `basic_result` type. 100 3. Trait {{% api "is_exception_ptr_available<E>" %}} is true for decayed `error_type`. 101 4. `predicate::enable_compatible_conversion<A, B, C>` is not true. 102 5. `A` is `void` OR `value_type` is explicitly constructible from `A`. 103 6. `error_type` is explicitly constructible from `make_exception_ptr(B)`. 104 105- `predicate::enable_inplace_value_constructor<Args...>` is constexpr boolean true if: 106 1. `predicate::constructors_enabled` is true. 107 2. `value_type` is `void` OR `value_type` is explicitly constructible from `Args...`. 108 109- `predicate::enable_inplace_error_constructor<Args...>` is constexpr boolean true if: 110 1. `predicate::constructors_enabled` is true. 111 2. `error_type` is `void` OR `error_type` is explicitly constructible from `Args...`. 112 113- `predicate::enable_inplace_value_error_constructor<Args...>` is constexpr boolean true if: 114 1. `predicate::constructors_enabled` is true. 115 2. `predicate::implicit_constructors_enabled` is true. 116 3. Either, but not both, of `value_type` is explicitly constructible from `Args...` or `error_type` is explicitly constructible from `Args...`. 117 118#### Summary of [standard requirements provided](https://en.cppreference.com/w/cpp/named_req) 119 120- ~~`DefaultConstructible`~~, always deleted to force user to choose valued or errored for every result instanced. 121- `MoveConstructible`, if both `value_type` and `error_type` implement move constructors. 122- `CopyConstructible`, if both `value_type` and `error_type` implement copy constructors. 123- `MoveAssignable`, if both `value_type` and `error_type` implement move constructors and move assignment. 124- `CopyAssignable`, if both `value_type` and `error_type` implement copy constructors and copy assignment. 125- `Destructible`. 126- `TriviallyCopyable`, if both `value_type` and `error_type` are trivially copyable. 127- `TrivialType`, if both `value_type` and `error_type` are trivial types. 128- `LiteralType`, if both `value_type` and `error_type` are literal types. 129- `StandardLayoutType`, if both `value_type` and `error_type` are standard layout types. If so, layout of `basic_result` in C is guaranteed to be: 130 131 ```c++ 132 struct result_layout { 133 value_type value; 134 unsigned int flags; 135 error_type error; 136 }; 137 ``` 138- `EqualityComparable`, if both `value_type` and `error_type` implement equality comparisons with one another. 139- ~~`LessThanComparable`~~, not implemented due to availability of implicit conversions from `value_type` and `error_type`, this can cause major surprise (i.e. hard to diagnose bugs), so we don't implement these at all. 140~ `Swappable` 141- ~~`Hash`~~, not implemented as a generic implementation of a unique hash for non-valued items which are unequal would require a dependency on RTTI being enabled. 142 143Thus `basic_result` meets the `Regular` concept if both `value_type` and `error_type` are `Regular`, except for the lack of a default constructor. Often where one needs a default constructor, wrapping `basic_result` into {{% api "std::optional<T>" %}} will suffice. 144 145### Public member functions 146 147#### Disabling constructors 148 149{{% children description="true" depth="2" categories="disabling-constructors" %}} 150 151#### Copy and move constructors and assignment, and destructor 152 153{{% children description="true" depth="2" categories="default-constructors,copy-constructors,move-constructors,copy-assignment,move-assignment,destructors" %}} 154 155#### Converting constructors 156 157{{% children description="true" depth="2" categories="converting-constructors" %}} 158 159#### Inplace constructors 160 161{{% children description="true" depth="2" categories="inplace-constructors" %}} 162 163#### Tagged constructors 164 165{{% children description="true" depth="2" categories="tagged-constructors" %}} 166 167#### Observers 168 169{{% children description="true" depth="2" categories="observers" %}} 170 171#### Modifiers 172 173{{% children description="true" depth="2" categories="modifiers" %}} 174 175#### Comparisons 176 177See above for why `LessThanComparable` is not implemented. 178 179{{% children description="true" depth="2" categories="comparisons" %}} 180 181