xtd - Reference Guide  0.1.0
Modern c++17/20 framework to create console, GUI and unit test applications on Windows, macOS, Linux, iOS and android.
Public Member Functions | List of all members
xtd::diagnostics::default_trace_listener Class Reference

#include <default_trace_listener.h>

Definition

Provides the default output methods and behavior for tracing.

Namespace
xtd::diagnostics
Library
xtd.core
Examples
The following code example calculates binomial coefficients, which are values used in probability and statistics. This example uses a xtd::diagnostics::default_trace_listener to trace results and log errors. It creates a new xtd::diagnostics::default_trace_listener, adds it to the xtd::diagnostics::trace::listeners collection, and sets the xtd::diagnostics::default_trace_listener::log_file_name property to the log file specified in the command-line arguments.

If an error is detected while processing the input parameter, or if the calc_binomial function throws an exception, the xtd::diagnostics::default_trace_listener::fail method logs and displays an error message. If the xtd::diagnostics::default_trace_listener::assert_ui_enabled property is false, the error message is also written to the console. When the result is calculated successfully, the xtd::diagnostics::default_trace_listener::write and xtd::diagnostics::default_trace_listener::write_line methods write the results to the log file.

The xtd::diagnostics::default_trace_listener::fail, xtd::diagnostics::default_trace_listener::write, and xtd::diagnostics::default_trace_listener::write_line methods cause trace information to be written only to the xtd::diagnostics::default_trace_listener. To write trace information to all listeners in the xtd::diagnostics::trace::listeners collection, use the xtd::diagnostics::trace::fail, xtd::diagnostics::trace::write, and xtd::diagnostics::trace::write_line methods of the xtd::diagnostics::trace class.
#include <xtd/xtd>
using namespace std;
using namespace xtd;
using namespace xtd::diagnostics;
class binomial {
public:
// args(0) is the number of possibilities for binomial coefficients.
// args(1) is the file specification for the trace log file.
static void main(const vector<ustring>& args) {
decimal possibilities;
decimal iter;
// Remove the original default trace listener.
trace::listeners().erase(trace::listeners().begin());
// Create and add a new default trace listener.
shared_ptr<default_trace_listener> default_listener = make_shared<default_trace_listener>();
trace::listeners().push_back(default_listener);
// Assign the log file specification from the command line, if entered.
if (args.size() >= 2)
default_listener->log_file_name(args[1]);
// Validate the number of possibilities argument.
if (args.size() >= 1) {
// Verify that the argument is a number within the correct range.
try {
const decimal MAX_POSSIBILITIES = 99;
possibilities = parse<decimal>(args[0]);
if (possibilities < 0 || possibilities > MAX_POSSIBILITIES)
throw new system_exception(ustring::format("The number of possibilities must be in the range 0..{}.", MAX_POSSIBILITIES));
} catch (const system_exception& ex) {
ustring fail_message = ustring::format("\"{}\" is not a valid number of possibilities.", args[0]);
default_listener->fail(fail_message, ex.message());
if (!default_listener->assert_ui_enabled())
console::write_line(fail_message + "\n" + ex.message());
return;
}
} else {
// Report that the required argument is not present.
const ustring ENTER_PARAM = "Enter the number of possibilities as a command line argument.";
default_listener->fail(ENTER_PARAM);
if (!default_listener->assert_ui_enabled())
console::write_line(ENTER_PARAM);
return;
}
for (iter = 0; iter <= possibilities; iter++) {
decimal result;
ustring binomial;
// Compute the next binomial coefficient and handle all exceptions.
try {
result = calc_binomial(possibilities, iter);
} catch (const system_exception& ex) {
ustring fail_message = ustring::format("An exception was raised when calculating Binomial( {}, {} ).", possibilities, iter);
default_listener->fail(fail_message, ex.message());
if (!default_listener->assert_ui_enabled())
console::write_line(fail_message + "\n" + ex.message());
return;
}
// Format the trace and console output.
binomial = ustring::format("Binomial( {0}, {1} ) = ", possibilities, iter);
default_listener->write(binomial);
default_listener->write_line(ustring::format("{}", result));
console::write_line("{0} {1}", binomial, result);
}
}
static decimal calc_binomial(xtd::decimal possibilities, decimal outcomes) {
// Calculate a binomial coefficient, and minimize the chance of overflow.
decimal result = 1;
decimal iter;
for (iter = 1; iter <= possibilities - outcomes; iter++) {
result *= outcomes + iter;
result /= iter;
}
return result;
}
};
startup_(binomial);
// This code can produces the following output :
//
// Binomial( 20, 0 ) = 1
// Binomial( 20, 1 ) = 20
// Binomial( 20, 2 ) = 190
// Binomial( 20, 3 ) = 1140
// Binomial( 20, 4 ) = 4845
// Binomial( 20, 5 ) = 15504
// Binomial( 20, 6 ) = 38760
// Binomial( 20, 7 ) = 77520
// Binomial( 20, 8 ) = 125970
// Binomial( 20, 9 ) = 167960
// Binomial( 20, 10 ) = 184756
// Binomial( 20, 11 ) = 167960
// Binomial( 20, 12 ) = 125970
// Binomial( 20, 13 ) = 77520
// Binomial( 20, 14 ) = 38760
// Binomial( 20, 15 ) = 15504
// Binomial( 20, 16 ) = 4845
// Binomial( 20, 17 ) = 1140
// Binomial( 20, 18 ) = 190
// Binomial( 20, 19 ) = 20
// Binomial( 20, 20 ) = 1

Public Member Functions

 default_trace_listener ()
 Initializes a new instance of the default_trace_listener class with "default" as its xtd::diagnostics::default_trace_listener::name property value. More...
 
bool assert_ui_enabled ()
 Gets a value indicating whether the application is running in user-interface mode. More...
 
void assert_ui_enabled (bool assert_ui_enabled)
 Sets a value indicating whether the application is running in user-interface mode. More...
 
void close () override
 When overridden in a derived class, closes the output stream so it no longer receives tracing or debugging output. More...
 
void flush () override
 When overridden in a derived class, flushes the output buffer. More...
 
xtd::ustring log_file_name () const
 Gets the name of a log file to write trace or debug messages to. More...
 
void log_file_name (const xtd::ustring log_file_name)
 Sets the name of a log file to write trace or debug messages to. More...
 
void write (const xtd::ustring &message) override
 Writes the message to the listener you create when you implement the trace_listener class. More...
 
void write_line (const xtd::ustring &message) override
 Writes the message to the listener you create when you implement the trace_listener class followed by a line terminator.followed by a line terminator. More...
 
- Public Member Functions inherited from xtd::diagnostics::trace_listener
 trace_listener ()=default
 Initializes a new instance of the trace_listener class. More...
 
 trace_listener (const xtd::ustring &name)
 Initializes a new instance of the trace_listener class using the specified name as the listener. More...
 
virtual void fail (const xtd::ustring &message)
 Emits an error message to the listener you create when you implement the TraceListener class. More...
 
virtual void fail (const xtd::ustring &message, const xtd::ustring &detail_message)
 Emits the specified error message. More...
 
unsigned int indent_level () const
 Gets the indent level. More...
 
void indent_level (unsigned int indent_level)
 Sets the indent level. More...
 
unsigned int indent_size () const
 Gets the number of spaces in an indent. More...
 
void indent_size (unsigned int indent_size)
 Sets the number of spaces in an indent. More...
 
virtual bool is_thread_safe () const
 Gets a value indicating whether the trace listener is thread safe. More...
 
const xtd::ustringname () const
 Gets or sets a name for this TraceListener. More...
 
void name (const xtd::ustring &name)
 Sets a name for this TraceListener. More...
 
template<typename object >
void trace_data (const xtd::diagnostics::trace_event_cache &event_cache, const xtd::ustring &source, const xtd::diagnostics::trace_event_type &event_type, int id, const object &data)
 Writes trace information, a data object and event information to the listener specific output. More...
 
template<typename object >
void trace_data (const xtd::diagnostics::trace_event_cache &event_cache, const xtd::ustring &source, const xtd::diagnostics::trace_event_type &event_type, int id, const std::vector< object > &data)
 Writes trace information, a data object and event information to the listener specific output. More...
 
template<typename ... objects>
void trace_data (const xtd::diagnostics::trace_event_cache &event_cache, const xtd::ustring &source, const xtd::diagnostics::trace_event_type &event_type, int id, const objects &... data)
 Writes trace information, an array of data objects and event information to the listener specific output. More...
 
virtual void trace_event (const xtd::diagnostics::trace_event_cache &event_cache, const xtd::ustring &source, const xtd::diagnostics::trace_event_type &event_type, int id)
 Writes trace and event information to the listener specific output. More...
 
virtual void trace_event (const xtd::diagnostics::trace_event_cache &event_cache, const xtd::ustring &source, const xtd::diagnostics::trace_event_type &event_type, int id, const xtd::ustring &message)
 Writes trace information, a message, and event information to the listener specific output. More...
 
template<typename ... objects>
void trace_event (const xtd::diagnostics::trace_event_cache &event_cache, const xtd::ustring &source, const xtd::diagnostics::trace_event_type &event_type, int id, const xtd::ustring &format, const objects &... args)
 Writes trace information, a formatted array of objects and event information to the listener specific output. More...
 
const trace_optionstrace_output_options () const
 Gets the trace output options. More...
 
void trace_output_options (const trace_options &trace_output_options)
 Sets the trace output options. More...
 
template<typename activity_id_type >
void trace_transfer (const xtd::diagnostics::trace_event_cache &event_cache, const xtd::ustring &source, int id, const xtd::ustring &message, const activity_id_type &related_activity_id)
 Writes trace information, a message, a related activity identity and event information to the listener specific output. More...
 
template<typename object >
void write (const object &o)
 Writes the value of the object's ToString method to the listener you create when you implement the TraceListener class. More...
 
template<typename object >
void write (const object &o, const xtd::ustring &category)
 Writes a category name and the value of the object's ToString method to the listener you create when you implement the TraceListener class. More...
 
template<typename object >
void write_line (const object &o)
 Writes the value of the object's ToString method to the listener you create when you implement the TraceListener class. More...
 
template<typename object >
void write_line (const object &o, const xtd::ustring &category)
 Writes a category name and the value of the object's ToString method to the listener you create when you implement the TraceListener class. More...
 
- Public Member Functions inherited from xtd::object
 object ()=default
 Create a new instance of the ultimate base class object. More...
 
virtual bool equals (const object &obj) const noexcept
 Determines whether the specified object is equal to the current object. More...
 
virtual size_t get_hash_code () const noexcept
 Serves as a hash function for a particular type. More...
 
template<typename object_t >
std::unique_ptr< object_t > memberwise_clone () const
 Gets the type of the current instance. More...
 
virtual xtd::ustring to_string () const noexcept
 Returns a std::string that represents the current object. More...
 

Additional Inherited Members

- Static Public Member Functions inherited from xtd::object
static bool equals (const object &object_a, const object &object_b) noexcept
 Determines whether the specified object instances are considered equal. More...
 
static bool reference_equals (const object &object_a, const object &object_b) noexcept
 Determines whether the specified object instances are the same instance. More...
 
- Protected Member Functions inherited from xtd::diagnostics::trace_listener
bool need_indent () const
 Gets a value indicating whether to indent the output. More...
 
void need_indent (bool need_indent)
 Sets a value indicating whether to indent the output. More...
 
void thread_safe (bool thread_safe)
 Sets a value indicating whether the trace listener is thread safe. More...
 
virtual void write_indent ()
 Writes the indent to the listener you create when you implement this class, and resets the NeedIndent property to false. More...
 

Constructor & Destructor Documentation

◆ default_trace_listener()

xtd::diagnostics::default_trace_listener::default_trace_listener ( )

Initializes a new instance of the default_trace_listener class with "default" as its xtd::diagnostics::default_trace_listener::name property value.

Examples
The following code example removes the xtd::diagnostics::default_trace_listener provided by the application from the xtd::diagnostics::trace::listeners collection and then creates a new xtd::diagnostics::default_trace_listener and adds it to the xtd::diagnostics::trace::listeners collection.
// Remove the original default trace listener.
// Create and add a new default trace listener.
shared_ptr<default_trace_listener> default_listener = make_shared<default_trace_listener>();
trace::listeners().push_back(default_listener);
// Assign the log file specification from the command line, if entered.
if (args.size() >= 2)
default_listener->log_file_name(args[1]);

Member Function Documentation

◆ assert_ui_enabled() [1/2]

bool xtd::diagnostics::default_trace_listener::assert_ui_enabled ( )

Gets a value indicating whether the application is running in user-interface mode.

Returns
true if user-interface mode is enabled; otherwise, false.
Examples
The following code example calls a function that calls the xtd::diagnostics::default_trace_listener::fail method to log an error message if the function throws an exception. If the xtd::diagnostics::default_trace_listener::assert_ui_enabled property is false, the method also writes the error message to the console.
// Compute the next binomial coefficient and handle all exceptions.
result = calc_binomial(possibilities, iter);
} catch (const system_exception& ex) {
ustring fail_message = ustring::format("An exception was raised when calculating Binomial( {}, {} ).", possibilities, iter);
default_listener->fail(fail_message, ex.message());
if (!default_listener->assert_ui_enabled())
console::write_line(fail_message + "\n" + ex.message());
return;
}

◆ assert_ui_enabled() [2/2]

void xtd::diagnostics::default_trace_listener::assert_ui_enabled ( bool  assert_ui_enabled)

Sets a value indicating whether the application is running in user-interface mode.

Parameters
assert_ui_enabledtrue if user-interface mode is enabled; otherwise, false.
Examples
The following code example calls a function that calls the xtd::diagnostics::default_trace_listener::fail method to log an error message if the function throws an exception. If the xtd::diagnostics::default_trace_listener::assert_ui_enabled property is false, the method also writes the error message to the console.
// Compute the next binomial coefficient and handle all exceptions.
result = calc_binomial(possibilities, iter);
} catch (const system_exception& ex) {
ustring fail_message = ustring::format("An exception was raised when calculating Binomial( {}, {} ).", possibilities, iter);
default_listener->fail(fail_message, ex.message());
if (!default_listener->assert_ui_enabled())
console::write_line(fail_message + "\n" + ex.message());
return;
}

◆ close()

void xtd::diagnostics::default_trace_listener::close ( )
overridevirtual

When overridden in a derived class, closes the output stream so it no longer receives tracing or debugging output.

Remarks
Use this method when the output is going to a file, such as to the TextWriterTraceListener. After a call to this method, you must reinitialize the object.

Reimplemented from xtd::diagnostics::trace_listener.

◆ flush()

void xtd::diagnostics::default_trace_listener::flush ( )
overridevirtual

When overridden in a derived class, flushes the output buffer.

Reimplemented from xtd::diagnostics::trace_listener.

◆ log_file_name() [1/2]

xtd::ustring xtd::diagnostics::default_trace_listener::log_file_name ( ) const

Gets the name of a log file to write trace or debug messages to.

Returns
The name of a log file to write trace or debug messages to.
Examples
The following code example creates a new xtd::diagnostics::default_trace_listener, adds it to the xtd::diagnostics::trace::listeners collection, and sets the xtd::diagnostics::default_trace_listener::log_file_name property to the log file specified in the command-line arguments.
// Create and add a new default trace listener.
shared_ptr<default_trace_listener> default_listener = make_shared<default_trace_listener>();
trace::listeners().push_back(default_listener);
// Assign the log file specification from the command line, if entered.
if (args.size() >= 2)
default_listener->log_file_name(args[1]);

◆ log_file_name() [2/2]

void xtd::diagnostics::default_trace_listener::log_file_name ( const xtd::ustring  log_file_name)

Sets the name of a log file to write trace or debug messages to.

Parameters
log_file_nameThe name of a log file to write trace or debug messages to.
Examples
The following code example creates a new xtd::diagnostics::default_trace_listener, adds it to the xtd::diagnostics::trace::listeners collection, and sets the xtd::diagnostics::default_trace_listener::log_file_name property to the log file specified in the command-line arguments.
// Create and add a new default trace listener.
shared_ptr<default_trace_listener> default_listener = make_shared<default_trace_listener>();
trace::listeners().push_back(default_listener);
// Assign the log file specification from the command line, if entered.
if (args.size() >= 2)
default_listener->log_file_name(args[1]);

◆ write()

void xtd::diagnostics::default_trace_listener::write ( const xtd::ustring message)
overridevirtual

Writes the message to the listener you create when you implement the trace_listener class.

Parameters
messageA string you want to write.

Implements xtd::diagnostics::trace_listener.

◆ write_line()

void xtd::diagnostics::default_trace_listener::write_line ( const xtd::ustring message)
overridevirtual

Writes the message to the listener you create when you implement the trace_listener class followed by a line terminator.followed by a line terminator.

Parameters
messageA string you want to write.

Implements xtd::diagnostics::trace_listener.


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