C Macro API Reference - Boost.Outcome documentation

# C Macro API Reference

The C macro API header `<boost/outcome/experimental/result.h>` consists of these macros:

`BOOST_OUTCOME_C_DECLARE_RESULT(ident, T, E)`
  Declares to C a `basic_result` type uniquely identified by `ident`. `T` is available at the member variable `.value`, and `E` is available at the member variable `.error`.
`BOOST_OUTCOME_C_RESULT(ident)`
  A reference to a previously declared `result` type with unique `ident`.
`BOOST_OUTCOME_C_RESULT_HAS_VALUE(r)`
  Evaluates to 1 (true) if the input `result` has a value.
`BOOST_OUTCOME_C_RESULT_HAS_ERROR(r)`
  Evaluates to 1 (true) if the input `result` has an error.
`BOOST_OUTCOME_C_RESULT_ERROR_IS_ERRNO(r)`
  Evaluates to 1 (true) if the input `result`'s error value is a code in the POSIX `errno` domain.

The above let you work, somewhat awkwardly, with any C-compatible `basic_result<T, E>`. `basic_result<T, E>` is trivially copyable and standard layout if its `T` and `E` are both so, and it has the C layout:

    struct cxx_result_##ident
    {
      T value;
      unsigned flags;
      E error;
    };

### `<system_error2>` support

`BOOST_OUTCOME_C_DECLARE_STATUS_CODE(ident, value_type)`
  Declares to C a status code type with domain `value_type` available at the member variable `.value`. The `ident` must be any identifier fragment unique in this translation unit. It is used to uniquely identify this status code type in other macros.
`BOOST_OUTCOME_C_STATUS_CODE(ident)`
  A reference to a previously declared status code type with unique `ident`.

There is a high likelihood that C++ functions regularly called by C code will return their failures either in erased `system_code` or in `posix_code` (i.e. `errno` code domain). Via querying the returned value using `BOOST_OUTCOME_C_RESULT_ERROR_IS_ERRNO(r)`, one can determine if the returned code is in the `errno` code domain, and thus can be fed to `strerror()` and so on. Therefore there are convenience macro APIs for those particular use cases.

`BOOST_OUTCOME_C_DECLARE_RESULT_ERRNO(ident, T)`
  Declares to C a `basic_result<T, posix_code>` type uniquely identified by `ident`.
`BOOST_OUTCOME_C_RESULT_ERRNO(ident)`
  A reference to a previously declared `basic_result<T, posix_code>` type with unique `ident`.
`BOOST_OUTCOME_C_DECLARE_RESULT_SYSTEM(ident, T)`
  Declares to C a `basic_result<T, system_code>` type uniquely identified by `ident`.
`BOOST_OUTCOME_C_RESULT_SYSTEM(ident)`
  A reference to a previously declared `basic_result<T, system_code>` type with unique `ident`.

Last revised: February 05, 2019 at 17:14:18 UTC