ts::ErrCodeReport Class Reference

A proxy class to automatically report std::error_code errors. More...

#include <tsErrCodeReport.h>

Inheritance diagram for ts::ErrCodeReport:

Collaboration diagram for ts::ErrCodeReport:

Public Member Functions
	ErrCodeReport ()=default
	Default, constructor with no error reporting.
	ErrCodeReport (bool &success)
	Constructor with error indicator only and no error reporting.
	ErrCodeReport (bool &success, Report &report, const UString &message=UString(), const UString &object=UString(), int severity=Severity::Error)
	Constructor with error indicator and error reporting.
	ErrCodeReport (Report &report, const UString &message=UString(), const UString &object=UString(), int severity=Severity::Error)
	Main constructor.
	~ErrCodeReport ()
	Destructor.
void	log ()
	Report error immediately instead of waiting for the destructor.
ErrCodeReport &	operator& ()
	Turn a constructor expression into an lvalue to be used in system function calls.

Detailed Description

A proxy class to automatically report std::error_code errors.

This class derives from std::error_code and can be used in any C++ standard library call which takes an output parameter of type std::error_code.

The magic is in the destructor of the class. Whenever an instance of this class is destructed, if the object contains an error, the corresponding error message is logged in the associated Report object. Therefore, the standard usage pattern is the following:

if (!std::filesystem::create_directory(dir, &ErrCodeReport(report, "error creating directory", dir))) {
    // error processing, error message already logged to report
    return false;
}

The first important point is the usage of a constructor, directly as a parameter of the system call, here std::filesystem::create_directory. According to C++ rules, a temporary instance of ErrCodeReport is constructed just before calling create_directory. This instance is then destructed immediately after returning from create_directory. Therefore, in case of error, the error message is automatically logged upon returning from create_directory, before the next instructions.

The second important point is the usage of the "&" operator in front of the constructor. This is a trick to allow the direct usage of a constructor in the function argument list. All system functions which return an error code in a parameter declare that parameter as a non-constant reference to an instance of std::error_code. Because the reference is not constant, the parameter must be an lvalue. And a constructor call is an rvalue, not an lvalue. The operator "&" is redefined in the class and return a non-constant reference to the object. Thus, the expression becomes an lvalue. Note that the choice of "&" is arbitrary and any other unitary operator could have been used instead.

Also note that many apparently redundant constructors are defined. This is a solution to an issue with Microsoft C++. With gcc and clang, calling the first ErrCodeReport constructor with expressions which are convertible to UString is accepted. However, Microsoft C++ generates an obscure error. To avoid that error, a constructor must be found with the exact same paramater types as the values in the constructor call. This is why additional constructors are defined with various common combinations of parameter types. More constructors may need to be defined with new code.

Constructor & Destructor Documentation

ErrCodeReport() [1/4]

ts::ErrCodeReport::ErrCodeReport ( Report &  report, const UString &  message = UString(), const UString &  object = UString(), int  severity = Severity::Error  )

inline

Main constructor.

Parameters

[in,out]	report	The report to which all error messages are logged in the destructor.
[in]	message	Option message to display before the system error message.
[in]	object	Optional "object" name, to be displayed after message.
[in]	severity	Severity at which the message is reported (default: error).

ErrCodeReport() [2/4]

ts::ErrCodeReport::ErrCodeReport ( bool &  success, Report &  report, const UString &  message = UString(), const UString &  object = UString(), int  severity = Severity::Error  )

inline

Constructor with error indicator and error reporting.

Parameters

[out]	success	The boolean to set in the destructor to indicate success or error.
[in,out]	report	The report to which all error messages are logged in the destructor.
[in]	message	Option message to display before the system error message.
[in]	object	Optional "object" name, to be displayed after message.
[in]	severity	Severity at which the message is reported (default: error).

ErrCodeReport() [3/4]

ts::ErrCodeReport::ErrCodeReport ( bool &  success )

inline

Constructor with error indicator only and no error reporting.

Parameters

[out]

success

The boolean to set in the destructor to indicate success or error.

ErrCodeReport() [4/4]

ts::ErrCodeReport::ErrCodeReport ( )

default

Default, constructor with no error reporting.

Typically used to select the non-throwing variant of std::filesystem calls and avoid throwing an exception.

~ErrCodeReport()

ts::ErrCodeReport::~ErrCodeReport ( )

inline

Destructor.

If this object contains a non-success code, an error message is logged on the report.

Member Function Documentation

operator&()

ErrCodeReport & ts::ErrCodeReport::operator& ( )

inline

Turn a constructor expression into an lvalue to be used in system function calls.

See the description of ErrCodeReport for usage patterns.

Returns

A non-constant reference to this object.

See also

ErrCodeReport

log()

void ts::ErrCodeReport::log

(

)

Report error immediately instead of waiting for the destructor.

The error is then cleared, to avoid later report in the destructor.

---

The documentation for this class was generated from the following file:

• tsErrCodeReport.h