C Macro API Reference

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

CXX_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.

CXX_RESULT(ident)

A reference to a previously declared result type with unique ident.

CXX_RESULT_HAS_VALUE(r)

Evaluates to 1 (true) if the input result has a value.

CXX_RESULT_HAS_ERROR(r)

Evaluates to 1 (true) if the input result has an error.

CXX_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
{
  union
  {
    T value;
    E error;
  };
  unsigned flags;
};

<system_error2> support

Because erased status codes are not trivially copyable and therefore do not have union based storage, we have separate C macros for results whose E is an erased status code:

CXX_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.

CXX_STATUS_CODE(ident)

A reference to a previously declared status code type with unique ident.

CXX_DECLARE_RESULT_STATUS_CODE(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.

CXX_RESULT_STATUS_CODE(ident)

A reference to a previously declared result 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 CXX_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.

CXX_DECLARE_RESULT_ERRNO(ident, T)

Declares to C a basic_result<T, posix_code> type uniquely identified by ident.

CXX_RESULT_ERRNO(ident)

A reference to a previously declared basic_result<T, posix_code> type with unique ident.

CXX_DECLARE_RESULT_SYSTEM(ident, T)

Declares to C a basic_result<T, system_code> type uniquely identified by ident.

CXX_RESULT_SYSTEM(ident)

A reference to a previously declared basic_result<T, system_code> type with unique ident.