|
boost::taar::failure — A failure: what went wrong, where, and why.
// In header: <boost/taar/core/error.hpp> class failure { public: // public member functions failure() = default; explicit failure(boost::system::error_code, std::string = {}, boost::source_location const & = BOOST_CURRENT_LOCATION); explicit failure(error, std::string = {}, boost::source_location const & = BOOST_CURRENT_LOCATION); boost::system::error_code const & code() const noexcept; std::string const & message() const noexcept; boost::json::value const & data() const noexcept; failure const * cause() const noexcept; boost::source_location const & where() const noexcept; std::exception_ptr exception() const noexcept; failure & with_message(std::string); failure & with_data(boost::json::value); failure & with_cause(failure); failure & with_exception(std::exception_ptr); bool is(boost::system::error_code const &) const noexcept; bool has(boost::system::error_code const &) const noexcept; failure const & root() const noexcept; std::string chain() const; std::string text() const; template<typename E> std::optional< E > as() const; void rethrow() const; // public static functions static failure from_exception(std::exception_ptr); // private static functions static std::string strip_code_text(std::string_view, std::string_view); };
The one error value of Boost.Taar. A failure carries
an error_code from any category (error, Asio, Beast, Boost.JSON, jsonrpc::error, generic errc, ...);
a message specific to this occurrence ("query parameter 'page' occurs more than once"), which does not repeat the code's generic text and reads on its own, since text prints it instead of the code's text;
optional structured data (a JSON value);
an optional nested cause, so a failure can explain itself in layers ("argument page (position 1) is invalid" caused by "value 'abc' is not a number");
the source location where it was raised;
optionally the foreign exception it was made from (see from_exception), so a user can still rethrow and catch their own type.
A default-constructed failure means "no error": its code is success. A failure with no message, data or cause allocates nothing, which keeps hot paths such as error::argument_not_found cheap. Copies share the cause chain.
See Also: result, exception
failure public member functionsfailure() = default;No error:
code() is success. explicit failure(boost::system::error_code code, std::string message = {}, boost::source_location const & where = BOOST_CURRENT_LOCATION);A failure carrying code, an optional message for this occurrence, and its location.
explicit failure(error code, std::string message = {}, boost::source_location const & where = BOOST_CURRENT_LOCATION);Convenience for codes of the error enum.
boost::system::error_code const & code() const noexcept;The error code; any category.
std::string const & message() const noexcept;The message for this occurrence only; may be empty.
boost::json::value const & data() const noexcept;Structured data attached to this occurrence; null when none.
failure const * cause() const noexcept;The nested cause, or
nullptr. boost::source_location const & where() const noexcept;Where the failure was raised.
std::exception_ptr exception() const noexcept;The innermost foreign exception kept in the chain, if any.
failure & with_message(std::string message);Replace the message.
failure & with_data(boost::json::value data);Replace the structured data.
failure & with_cause(failure cause);Nest cause below this failure.
failure & with_exception(std::exception_ptr exception);Keep exception, the foreign exception this failure stands for.
bool is(boost::system::error_code const & code) const noexcept;True if this failure's own code equals code.
bool has(boost::system::error_code const & code) const noexcept;True if this failure or any of its causes carries code.
failure const & root() const noexcept;The innermost cause (this failure if it has none).
std::string chain() const;Render the failure and its causes as text.
Each level reads message: code text [category:value] (or code text [category:value] when it has no message); causes follow in (caused by: ...). For a failure without cause this is the same text as boost::system::system_error::what().
std::string text() const;Render the failure and its causes as human-readable text.
Like chain but without category tags: each level reads its message, or the code's own text when the message is empty; causes follow in (caused by: ...). Suitable for response bodies and tool error content; chain is for logs.
template<typename E> std::optional< E > as() const;A copy of the kept foreign exception (exception) if it is an E.
Lets a hook recognise its own domain exception without a try/catch ladder:
if (auto const e = f.as<not_found>()) return reply(404, e->what());
The result is a copy because the standard leaves it unspecified whether std::rethrow_exception copies the exception object (MSVC does), so the address of a caught object cannot be returned portably. The copy is of the E subobject: ask for the type that was thrown, or a base that carries what you need (the standard exceptions keep their what() text; std::exception itself does not, so test with f.as<std::exception>().has_value() rather than reading it).
Template Parameters: |
|
||
Returns: |
The copy, or |
void rethrow() const;Throw the failure.
Rethrows the kept foreign exception (exception) if there is one, so a user's own exception type can be caught again; throws boost::taar::exception carrying this failure otherwise.
failure public static functionsstatic failure from_exception(std::exception_ptr eptr);Wrap an exception as a failure.
A boost::taar::exception yields its failure, unwrapped.
boost::system::system_error and std::system_error: the exception's code, its text without the code's own text as the message, the exception kept.
Any other std::exception: error::unknown_exception with what() as the message, the exception kept.
Anything else: error::unknown_exception, message "unknown exception", the exception kept.
A null pointer: no error.