Qx v0.5.7
Qt Extensions Library
|
The Error class acts as an interface for an extensible variety of error objects. More...
#include <qx/core/qx-error.h>
Public Member Functions | |
Error () | |
template<class EAble , class EAter = typename AdapterRegistry<EAble>::adapter> requires error_adaptation<EAble, EAter> | |
Error (const EAble &adapted) | |
template<class ErrorType > requires error_type<ErrorType> | |
Error (const ErrorType &e) | |
QString | caption () const |
quint64 | code () const |
QString | details () const |
bool | equivalent (const Error &other) const |
QString | hexCode () const |
bool | isValid () const |
operator bool () const | |
bool | operator!= (const Error &other) const =default |
bool | operator== (const Error &other) const =default |
QString | primary () const |
QString | secondary () const |
Error & | setSeverity (Severity sv) |
Severity | severity () const |
QString | severityString (bool uc=true) const |
QString | toString () const |
quint16 | typeCode () const |
QLatin1StringView | typeName () const |
quint32 | value () const |
Error | withSeverity (Severity sv) |
Static Public Attributes | |
static constexpr quint16 | TYPE_CODE = 0 |
static constexpr QLatin1StringView | TYPE_NAME {"Error"} |
Friends | |
QTextStream & | operator<< (QTextStream &ts, const Error &e) |
Error provides a common interface suitable for communicating most forms of error information in a unified manner. Additionally, it acts as a generic container for said information by being constructable from all derived types, providing a pseudo-polymorphic conversion mechanism with value semantics that obviates the need for typecasting and dealing with pointer semantics. Because error objects are only created when unexpected behavior occurs, and often immediately after a performance sensitive routine is paused or halted, the overhead of creating an Error object this way is generally negligible.
Additional error types are created by extending the AbstractError template class.
Technically, the underlying inheritance interface is defined by IError/AbstractError, but Error functionally acts similar to a traditional base class pointer in that it is used to access the data of extended error types in a generalized manner.
In order to provide consistent and useful context, the design of the interface is centered around two primary tenets:
All error types (represented by actual types) have a
while all errors have (at minimum) a
The type name and type code of an error type can be retrieved via the type's public members TYPE_NAME
and TYPE_CODE
respectively, or by the typeCode() and typeName() methods of an Error object created from that type. The uniqueness of each type name and code is guaranteed via runtime assertions (assuming they are not disabled, i.e. in a Release configuration). Uniqueness of error values within a given type is not enforced but a sensible implementation will ensure they do not overlap.
The following minimal example demonstrates some of the ways that Qx::Error can be used in a polymorphic-like fashion.
A complete error code(), which combines the type code and error value into one identifiable number, along with other error information can be accessed via the methods of this class.
Unlike most interface base classes an Error object can be instantiated directly via its default constructor in order to produce an invalid error.
To further streamline error handling, any existing arbitrary (presumably error related) type not derived from AbstractError can be adapted to the Error interface via an Error Adapter.
An error adapter is a specific derivation of AbstractError, in which the class is not move/copy constructable and is constructable from the type it's designed to adapt (see Qx::error_adapter). Each pair of adapter and adapted type is considered an Error Adaptation (see Qx::error_adaptation). and an instance of Error can be constructed from any valid Error Adaptation. Adaptations must be explicitly registered via the QX_DECLARE_ERROR_ADAPTATION() macro.
Error Adapters are only intended to be instantiated briefly by the appropriate Error constructor, hence the move/copy construction restriction, so it is recommended to compose an adapter such that it directly accesses the adapted type via a constant reference.
The following example shows how one might create an Error Adaptation for QSqlError.
Qx::Error::Error | ( | ) |
Constructs an invalid error.
|
inline |
Constructs a standard error object from the specific error e of type ErrorType.
|
inline |
Constructs a standard error object from adapted using its corresponding error adapter EAter.
QString Qx::Error::caption | ( | ) | const |
Returns the error's caption.
The caption is the heading of an error.
The default implementation of Error produces an empty string.
quint64 Qx::Error::code | ( | ) | const |
Returns the errors code.
An error's code is a combination of its type code, value, and severity; however, an invalid error's code is always 0
regardless of its type code.
63 - 56 | 55 - 48 | 47 - 32 | 31 - 0 |
---|---|---|---|
Reserved | Severity | Type | Value |
For example, an error with a type code of 1010
, error value of 4500
and severity of Err will have the code 4337916973460
.
The original type code and error value can be obtained by separating the low-order and high-order parts of this value.
QString Qx::Error::details | ( | ) | const |
Returns a string that contains additional details regarding the error.
The error details usually contain any remaining error information not otherwise shown in the primary and secondary information, or complete error details that generally are not of interest to an application's end user, but are useful for error reports and debugging.
bool Qx::Error::equivalent | ( | const Error & | other | ) | const |
Returns true if this error's type code and value and other's type code and value are the same; otherwise, returns false.
This is useful to check if two error's describe the same specific type of fault, even if some other minor details are different.
QString Qx::Error::hexCode | ( | ) | const |
Returns a string containing a hexadecimal representation of the error's code.
For example, an error with a type code of 1010
, error value of 4500
and severity of Err will produce the hex code string 0x0203F200001194
.
bool Qx::Error::isValid | ( | ) | const |
Returns true
if the error's value is greater than 0
; otherwise, returns false.
Invalid errors are generally used to indicate the success of an operation.
If an error is invalid, it's severity is generally meaningless.
Qx::Error::operator bool | ( | ) | const |
A convenience operator to check if the error is valid. Produces true
if the value of the error is greater than 0
; otherwise, produces false
.
|
default |
Returns true
if this error is not the same as other; otherwise, returns false.
|
default |
Returns true
if this error is the same as other; otherwise, returns false.
QString Qx::Error::primary | ( | ) | const |
Returns a string that contains primary error information.
Generally this is the action that ultimately lead to the failure, or the overarching form of the error, while secondary() usually contains more specific info.
For example, an Error recording a file write failure may contain the following error info:
Primary - "Failed to write file 'write_me.txt'." Secondary - "Permission denied."
QString Qx::Error::secondary | ( | ) | const |
Changes the severity of the error to sv and returns a reference to the error.
Although Error instances are otherwise immutable, this function allows changing the error's severity level since the severity of an error may vary depending on the context in which it occurs.
Severity Qx::Error::severity | ( | ) | const |
Returns the severity of the error.
The severity denotes the urgency with which the the rest of the contained error information should be regarded.
This is most often use to decorate error message windows or control program flow, like halting execution altogether in the event of a Critical error.
The most common setting is Error.
QString Qx::Error::severityString | ( | bool | uc = true | ) | const |
Returns the string representation of the error's severity.
If uc is set to true
, the returned string is entirely in uppercase.
QString Qx::Error::toString | ( | ) | const |
Returns a single string that contains the error's severity, code, primary info, and secondary info.
quint16 Qx::Error::typeCode | ( | ) | const |
Returns the type code of the type from which this error was constructed.
QLatin1StringView Qx::Error::typeName | ( | ) | const |
Returns the type name of the type from which this error was constructed.
quint32 Qx::Error::value | ( | ) | const |
Returns the value (i.e. type specific code) of the error.
This value can be used to programmatically identify the exact form of error that occurred.
Returns a copy of the error with the severity set to sv.
|
friend |
Writes the error e to the stream ts.
The error is written in a human-readable format, structured by its properties. A new line is always started after the error is written.
|
staticconstexpr |
Technically the type code of Error itself is never used since only invalid errors can be created directly with its constructor; however, this variable contains the value 0
for consistency with the rest of the type interface.
|
staticconstexpr |
A string representation of the type name, in this case Error
.