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
Here we supply the bare minimum requirements for a status code domain:
- The name in text, so it can be printed.
- 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.
- 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 ontogeneric_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 likeif(sc == errc::no_such_file_or_directory) ...
would match all custom error codes which mean ‘something was not found’. - 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.