Built-in policies - Boost.Outcome documentation

# Built-in policies

These are the predefined policies built into Outcome:

`all_narrow`

If there is an observation of a value/error/exception which is not present, the program is put into a hard undefined behaviour situation. The compiler literally compiles no code for an invalid observation – the CPU “runs off” into the unknown.

As bad as this may sound, it generates the most optimal code, and such hard UB is very tool-friendly for detection e.g. undefined behaviour sanitiser, valgrind memcheck, etc.

If you are considering choosing this policy, definitely read `static void _ub(Impl &&)` first.

Note that `unchecked<T, E = varies>` aliases a `basic_result` with the `all_narrow` no-value policy.

`terminate`

Observation of a missing value/error/exception causes a call to `std::terminate()`.

Note that configuring `EC = void` or `EP = void` causes `default_policy` to choose `terminate` as the no-value policy.

`error_code_throw_as_system_error<T, EC, EP>`

This policy assumes that `EC` has the interface of `std::error_code`, and `EP` has the interface of `std::exception_ptr`. Upon missing value observation:

- if an exception is stored through pointer of type `EP` it is rethrown;
- otherwise, if an error of type `EC` is stored, it is converted to `error_code` and then thrown as `system_error`.

Upon missing error observation throws:

- `bad_result_access("no error")` from instances of `basic_result<>`.
- `bad_outcome_access("no error")` from instances of `basic_outcome<>`.

Upon missing exception observation throws `bad_outcome_access("no exception")`.

Overloads are provided for `boost::system::error_code` and `boost::exception_ptr`.

Note that if `is_error_code_available<T>` is true for `EC`, and (if `basic_outcome`) `is_exception_ptr_available<T>` is true for `EP`, `default_policy` chooses `error_code_throw_as_system_error<T, EC, EP>` as the no-value policy.

`exception_ptr_rethrow<T, EC, EP>`

This policy assumes that either `EC` or `EP` (unless `void`) has the interface of `std::exception_ptr`. Upon missing value observation:

- in instances of `basic_result<>`, rethrows exception pointed to by `EC`;
- in instances of `basic_outcome<>`, if exception `EP` is present rethrows it, otherwise rethrows `EC`.

Upon missing error observation:

- in instances of `basic_result<>`, throws `bad_result_access("no error")` ;
- in instances of `basic_outcome<>`, throws `bad_outcome_access("no error")`.

Upon missing exception observation throws `bad_outcome_access("no exception")`.

Overloads are provided for `boost::exception_ptr`.

Note that if `is_exception_ptr_available<T>` is true for `EC`, or (if `basic_outcome`) `is_exception_ptr_available<T>` is true for `EP`, `default_policy` chooses `exception_ptr_rethrow<T, EC, EP>` as the no-value policy.

`throw_bad_result_access<EC>`

Upon missing value observation throws `bad_result_access_with<EC>(ec)`, where `ec` is the value of the stored error. If error is not stored, the behaviour is undefined.

Upon missing error observation throws `bad_result_access("no error")`.

This policy can be used with `basic_outcome<>` instances, where it always throws `bad_outcome_access` for all no-value/error/exception observations.

Note that `checked<T, E = varies>` aliases a `basic_result` with the `throw_bad_result_access<EC>` no-value policy.

Last revised: February 09, 2019 at 15:18:26 UTC