Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

Prev Up HomeNext

Worked example: Custom domain (the short way)

The section after this one will take the long way through defining a custom domain which sometimes is necessary if you have particularly bespoke requirements. If however you just want to wrap a custom enum type of yours into its own custom code domain, the boilerplate can be automated away by filling in a few simple fields like this:

// My custom enum type
enum class custom_failure
{
  not_found,
  bad_argument
};

// Tell `status_code` to stamp out a custom code domain for this enum type
BOOST_OUTCOME_SYSTEM_ERROR2_NAMESPACE_BEGIN
template <> struct quick_status_code_from_enum<custom_failure> : quick_status_code_from_enum_defaults<custom_failure>
{
  // Text name of the enum
  static constexpr const auto domain_name = "My custom failure";
  // Unique UUID for the enum. PLEASE use https://www.random.org/cgi-bin/randbyte?nbytes=16&format=h
  static constexpr const auto domain_uuid = "{be201f65-3962-dd0e-1266-a72e63776a42}";
  // Map of each enum value to its text string, and list of semantically equivalent errc's
  static const std::initializer_list<mapping> &value_mappings()
  {
    static const std::initializer_list<mapping> v = {
    // Format is: { enum value, "string representation", { list of errc mappings ... } }
    {custom_failure::not_found, "item not found", {errc::no_such_file_or_directory}},  //
    {custom_failure::bad_argument, "invoked wrong", {errc::invalid_argument}},         //
    };
    return v;
  }
  // Completely optional definition of mixin for the status code synthesised from `Enum`. It can be omitted.
  template <class Base> struct mixin : Base
  {
    using Base::Base;
    constexpr int custom_method() const { return 42; }
  };
};
BOOST_OUTCOME_SYSTEM_ERROR2_NAMESPACE_END
View this code on Github

Here we supply the bare minimum requirements for a status code domain:

  1. The name in text, so it can be printed.
  2. The unique UUID to identify when multiple copies of the domain are the same. PLEASE use https://www.random.org/cgi-bin/randbyte?nbytes=16&format=h to generate this, do not twiddle a few bits.
  3. For each enum value, its printable text and a sequence of errc:: enumerations which you think it is semantically equivalent to i.e. its mapping onto generic_code which is how status code defines the common mapping between status codes. If you later compare the status code to one of those values (or to another status code which also provides a mapping), if the generic codes are equivalent then the comparison will return true. This means code like if(sc == errc::no_such_file_or_directory) ... would match all custom error codes which mean ‘something was not found’.
  4. OPTIONAL: if you would like the custom status code type generated by this to have additional member functions or additional payload, you can define a mixin here to inject either data or functions or both. If you omit this, nothing gets injected.

Last revised: July 16, 2024 at 21:33:35 +0100


Prev Up HomeNext