API reference

  1. Macros
    1. Constrained template macros
    2. Version macros
    3. OUTCOME_CO_TRY(var, expr)

      Evaluate within a coroutine an expression which results in an understood type, assigning T to a decl called var if successful, immediately returning try_operation_return_as(X) from the calling function if unsuccessful.

    4. OUTCOME_CO_TRYV(expr)/OUTCOME_CO_TRY(expr)

      Evaluate from within a coroutine an expression which results in an understood type, continuing execution if successful, immediately returning try_operation_return_as(X) from the calling function if unsuccessful.

    5. OUTCOME_CO_TRYV2(spec, expr)

      Evaluate an expression which results in an understood type, continuing execution if successful, immediately returning try_operation_return_as(X) from the calling function if unsuccessful.

    6. OUTCOME_CO_TRYV2_FAILURE_LIKELY(spec, expr)

      Evaluate an expression which results in an understood type, continuing execution if successful, immediately returning try_operation_return_as(X) from the calling function if unsuccessful.

    7. OUTCOME_CO_TRYV_FAILURE_LIKELY(expr)/OUTCOME_CO_TRY_FAILURE_LIKELY(expr)

      Evaluate from within a coroutine an expression which results in an understood type, continuing execution if successful, immediately returning try_operation_return_as(X) from the calling function if unsuccessful.

    8. OUTCOME_CO_TRYX(expr)

      Evaluate from within a coroutine an expression which results in an understood type, emitting the T if successful, immediately returning try_operation_return_as(X) from the calling function if unsuccessful.

    9. OUTCOME_CO_TRYX_FAILURE_LIKELY(expr)

      Evaluate from within a coroutine an expression which results in an understood type, emitting the T if successful, immediately returning try_operation_return_as(X) from the calling function if unsuccessful.

    10. OUTCOME_CO_TRY_FAILURE_LIKELY(var, expr)

      Evaluate within a coroutine an expression which results in an understood type, assigning T to a decl called var if successful, immediately returning try_operation_return_as(X) from the calling function if unsuccessful.

    11. OUTCOME_DISABLE_EXECINFO

      If defined, disables the use of the <execinfo.h> header (or the win32 emulation).

    12. OUTCOME_ENABLE_LEGACY_SUPPORT_FOR

      Enables backwards features and naming compatibility for earlier versions of Outcome.

    13. OUTCOME_NODISCARD

      How to tell the compiler than the return value of a function should not be discarded without examining it.

    14. OUTCOME_REQUIRES(...)

      A C++ 20 requires(...), if available.

    15. OUTCOME_SYMBOL_VISIBLE

      How to mark throwable types as always having default ELF symbol visibility.

    16. OUTCOME_THREAD_LOCAL

      How to mark variables as having thread local storage duration.

    17. OUTCOME_THROW_EXCEPTION(expr)

      How to throw a C++ exception, or equivalent thereof.

    18. OUTCOME_TRY(var, expr)

      Evaluate an expression which results in an understood type, assigning T to a decl called var if successful, immediately returning try_operation_return_as(X) from the calling function if unsuccessful.

    19. OUTCOME_TRYV(expr)/OUTCOME_TRY(expr)

      Evaluate an expression which results in an understood type, continuing execution if successful, immediately returning try_operation_return_as(X) from the calling function if unsuccessful.

    20. OUTCOME_TRYV2(spec, expr)

      Evaluate an expression which results in an understood type, continuing execution if successful, immediately returning try_operation_return_as(X) from the calling function if unsuccessful.

    21. OUTCOME_TRYV2_FAILURE_LIKELY(spec, expr)

      Evaluate an expression which results in an understood type, continuing execution if successful, immediately returning try_operation_return_as(X) from the calling function if unsuccessful.

    22. OUTCOME_TRYV_FAILURE_LIKELY(expr)/OUTCOME_TRY_FAILURE_LIKELY(expr)

      Evaluate an expression which results in an understood type, continuing execution if successful, immediately returning try_operation_return_as(X) from the calling function if unsuccessful.

    23. OUTCOME_TRYX(expr)

      Evaluate an expression which results in an understood type, emitting the T if successful, immediately returning try_operation_return_as(X) from the calling function if unsuccessful.

    24. OUTCOME_TRYX_FAILURE_LIKELY(expr)

      Evaluate an expression which results in an understood type, emitting the T if successful, immediately returning try_operation_return_as(X) from the calling function if unsuccessful.

    25. OUTCOME_TRY_FAILURE_LIKELY(var, expr)

      Evaluate an expression which results in an understood type, assigning T to a decl called var if successful, immediately returning try_operation_return_as(X) from the calling function if unsuccessful.

    26. OUTCOME_USE_STD_IN_PLACE_TYPE

      How to implement in_place_type_t<T> and in_place_type<T>.

    27. OUTCOME_USE_STD_IS_NOTHROW_SWAPPABLE

      How to implement is_nothrow_swappable<T>.

  2. Concepts
    1. basic_outcome<T>

      A boolean concept matching types which are convertible to a basic_outcome<T, EC, EP, NoValuePolicy>.

    2. basic_result<T>

      A boolean concept matching types which are convertible to a basic_result<T, E, NoValuePolicy>.

    3. value_or_error<T>

      A boolean concept matching types with either a value or an error.

    4. value_or_none<T>

      A boolean concept matching types with an optional value.

  3. Converters
    1. value_or_error<T, U>

      A customisable converter of value_or_error<T, E> concept matching types.

  4. Traits
    1. is_basic_outcome<T>

      An integral constant type true for basic_outcome<T, EC, EP, NoValuePolicy> types.

    2. is_basic_result<T>

      An integral constant type true for basic_result<T, E, NoValuePolicy> types.

    3. is_error_code_available<T>

      True if an error code can be constructed from a T.

    4. is_error_type<E>

      A customisable integral constant type true for E types which are to receive error throwing no-value policies.

    5. is_error_type_enum<E, Enum>

      A customisable integral constant type true for E types constructible from Enum types which are to receive error throwing no-value policies.

    6. is_exception_ptr_available<T>

      True if an exception ptr can be constructed from a T.

    7. is_failure_type<T>

      An integral constant boolean variable true for failure_type<EC, E = void> types.

    8. is_move_bitcopying<T>

      (>= Outcome v2.2.0) A customisable integral constant type true for T types which are move bitcopying safe.

    9. is_success_type<T>

      An integral constant boolean variable true for success_type<T> types.

    10. type_can_be_used_in_basic_result<R>

      A constexpr boolean true for types permissible in basic_result<T, E, NoValuePolicy>.

  5. Policies
    1. base

      Base class of most policy classes defining the narrow observer policies.

    2. all_narrow

      Policy class defining that hard undefined behaviour should occur on incorrect narrow and wide value, error or exception observation. Inherits publicly from base.

    3. error_code_throw_as_system_error<T, EC, EP>

      Policy class defining that EP ought to be rethrown if possible, then the ADL discovered free function outcome_throw_as_system_error_with_payload() should be called on incorrect wide value observation. Inherits publicly from base. Can only be used with basic_outcome.

    4. error_code_throw_as_system_error<T, EC, void>

      Policy class defining that the ADL discovered free function outcome_throw_as_system_error_with_payload() should be called on incorrect wide value observation. Inherits publicly from base. Can only be used with basic_result.

    5. exception_ptr_rethrow<T, EC, EP>

      Policy class defining that the ADL discovered free function rethrow_exception() should be called on incorrect wide value observation. Inherits publicly from base. Can only be used with basic_outcome.

    6. exception_ptr_rethrow<T, EC, void>

      Policy class defining that the ADL discovered free function rethrow_exception() should be called on incorrect wide value observation. Inherits publicly from base. Can only be used with basic_result.

    7. fail_to_compile_observers

      Policy class defining that a static assertion should occur upon compilation of the wide value, error or exception observation. Inherits publicly from base.

    8. terminate

      Policy class defining that std::terminate() should be called on incorrect wide value, error or exception observation. Inherits publicly from base.

    9. throw_bad_result_access<EC>

      Policy class defining that bad_result_access_with<EC> should be thrown on incorrect wide value observation. Inherits publicly from base.

  6. Types
    1. basic_outcome<T, EC, EP, NoValuePolicy>

      A type carrying one of (i) a successful T (ii) a disappointment EC (iii) a failure EP (iv) both a disappointment EC and a failure EP, with NoValuePolicy specifying what to do if one tries to read state which isn’t there.

    2. basic_result<T, E, NoValuePolicy>

      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.

    3. bad_outcome_access

      Exception type publicly inheriting from std::logic_error indicating an incorrect observation of value or error or exception occurred.

    4. bad_result_access_with<EC>

      Exception type publicly inheriting from bad_result_access indicating an incorrect observation of value occurred, supplying the error value.

    5. bad_result_access

      Exception type publicly inheriting from std::logic_error indicating an incorrect observation of value or error occurred.

    6. eager<T, Executor = void>/atomic_eager<T, Executor = void>

      An eagerly evaluated coroutine awaitable with Outcome customisation.

    7. failure_type<EC, EP = void>

      Type sugar for constructing an unsuccessful result or outcome.

    8. generator<T, Executor = void>

      A lazily evaluated coroutine generator with Outcome customisation.

    9. in_place_type_t<T>

      Either std::in_place_type_t<T> or a local emulation, depending on the OUTCOME_USE_STD_IN_PLACE_TYPE macro.

    10. lazy<T, Executor = void>/atomic_lazy<T, Executor = void>

      A lazily evaluated coroutine awaitable with Outcome customisation.

    11. success_type<T>

      Type sugar for constructing a successful result or outcome.

  7. Aliases
    1. boost_checked<T, E = boost::system::error_code>

      A type alias to a basic_result configured with boost::system::error_code and policy::throw_bad_result_access<EC>.

    2. boost_outcome<T, EC = boost::system::error_code, EP = boost::exception_ptr, NoValuePolicy = policy::default_policy<T, EC, EP>>

      A type alias to a basic_outcome configured with boost::system::error_code, boost::exception_ptr and policy::default_policy.

    3. boost_result<T, E = boost::system::error_code, NoValuePolicy = policy::default_policy<T, E, void>>

      A type alias to a basic_result configured with boost::system::error_code and policy::default_policy.

    4. boost_unchecked<T, E = boost::system::error_code>

      A type alias to a basic_result configured with boost::system::error_code and policy::all_narrow.

    5. checked<T, E = varies>

      A type alias to a std_checked<T, E> (standalone edition) or boost_checked<T, E> (Boost edition).

    6. default_policy<T, EC, EP>

      A type alias to a no-value policy selected based on traits matching of T, EC and EP.

    7. outcome<T, EC = varies, EP = varies, NoValuePolicy = policy::default_policy<T, EC, EP>>

      A type alias to a std_outcome<T, EC, EP, NoValuePolicy> (standalone edition) or boost_outcome<T, EC, EP, NoValuePolicy> (Boost edition).

    8. result<T, E = varies, NoValuePolicy = policy::default_policy<T, E, void>>

      A type alias to a std_result<T, E, NoValuePolicy> (standalone edition) or boost_result<T, E, NoValuePolicy> (Boost edition).

    9. std_checked<T, E = std::error_code>

      A type alias to a basic_result configured with std::error_code and policy::throw_bad_result_access<EC>.

    10. std_outcome<T, EC = std::error_code, EP = std::exception_ptr, NoValuePolicy = policy::default_policy<T, EC, EP>>

      A type alias to a basic_outcome configured with std::error_code, std::exception_ptr and policy::default_policy.

    11. std_result<T, E = std::error_code, NoValuePolicy = policy::default_policy<T, E, void>>

      A type alias to a basic_result configured with std::error_code and policy::default_policy.

    12. std_unchecked<T, E = std::error_code>

      A type alias to a basic_result configured with std::error_code and policy::all_narrow.

    13. unchecked<T, E = varies>

      A type alias to a std_unchecked<T, E> (standalone edition) or boost_unchecked<T, E> (Boost edition).

  8. Functions
    1. Hooks

      Functions used to hook into the functionality of basic_result and basic_outcome.

    2. Iostream

      Functions used to print, serialise and deserialise basic_result and basic_outcome.

    3. Policy

      Functions used to customise how the policy classes operate.

    4. auto failure(T &&, ...)

      Returns appropriate type sugar for constructing an unsuccessful result or outcome.

    5. auto success(T &&, ...)

      Returns appropriate type sugar for constructing a successful result or outcome.

    6. bool try_operation_has_value(X)

      Default implementation of try_operation_has_value(X) ADL customisation point for OUTCOME_TRY.

    7. decltype(auto) try_operation_extract_value(X)

      Default implementation of try_operation_extract_value(X) ADL customisation point for OUTCOME_TRY.

    8. decltype(auto) try_operation_return_as(X)

      Default implementation of try_operation_return_as(X) ADL customisation point for OUTCOME_TRY.

    9. std::error_code error_from_exception(std::exception_ptr &&ep = std::current_exception(), std::error_code not_matched = std::make_error_code(std::errc::resource_unavailable_try_again)) noexcept

      Returns an error code matching a thrown standard library exception.

    10. void strong_swap(bool &all_good, T &a, T &b)

      Tries to perform a strong guarantee swap.

    11. void try_throw_std_exception_from_error(std::error_code ec, const std::string &msg = std::string{})

      Try to throw a standard library exception type matching an error code.