xtd 0.2.0
xtd::diagnostics::boolean_switch Class Reference

Definition

Provides a simple on/off switch that controls debugging and tracing output.

class core_export_ boolean_switch : public xtd::diagnostics::switch_base
Inheritance
xtd::objectxtd::diagnostics::switch_basextd::diagnostics::boolean_switch
Header
#include <xtd/diagnostics/boolean_switch>
Namespace
xtd::diagnostics
Library
xtd.core
Remarks
You can use a boolean trace switch to enable or disable messages based on their importance. Use the xtd::diagnostics::boolean_switch::enabled property to get the current value of the switch.
You can create a xtd::diagnostics::boolean_switch in your code and set the xtd::diagnostics::boolean_switch::enabled property directly to instrument a specific section of code.
Examples
This example configuration section defines a xtd::diagnostics::boolean_switch with the xtd::diagnostics::boolean_switch::display_name property set to my_switch and the xtd::diagnostics::boolean_switch::enabled value set to true. Within your application, you can use the configured switch value by creating a xtd::diagnostics::boolean_switch with the same name, as shown in the following code example.
private:
inline static xtd::diagnostics::boolean_switch boolean_switch("my_switch", "This is my switch");
public:
static auto main() {
//...
console.write_line("Boolean switch {0} configured as {1}", boolean_switch.display_name(), boolean_switch.enabled());
if (boolean_switch.enabled()) {
//...
}
}
Remarks
You must enable tracing or debugging to use a switch. The syntax is compiler specific. If you use other than cmake to manage your build, refer to the documentation of your build manager.
  • To enable debug mode with cmake, add the add_definitions(-DDEBUG) command line in the CMakeLists.txt of your project, or you can add #define DEBUG to the top of your file.
  • To enable trace mode with cmake, add the add_definitions(-DTRACE) command line in the CMakeLists.txt of your project, or you can add #define TRACE to the top of your file.
Note
These debug and trace compiler switches are not required when using the xtd::diagnostics::boolean_switch class in isolation. They are only required in conjunction with xtd::diagnostics::trace or xtd::diagnostics::debug methods that are conditionally compiled.
Remarks
For more information on instrumenting your application, see xtd::diagnostics::debug and xtd::diagnostics::trace.
Note
To improve performance, you can make xtd::diagnostics::boolean_switch members static in your class.

Constructors

 boolean_switch (const xtd::ustring &display_name, const xtd::ustring &description)
 Initializes a new instance of the xtd::diagnostics::boolean_switch class with the specified display name and description. More...
 
 boolean_switch (const xtd::ustring &display_name, const xtd::ustring &description, const xtd::ustring &default_switch_value)
 Initializes a new instance of the xtd::diagnostics::boolean_switch class with the specified display name, description, and default switch value. More...
 

Properties

bool enabled () const
 Gets a value indicating whether the switch is enabled or disabled. More...
 
void enabled (bool enabled)
 Sets a value indicating whether the switch is enabled or disabled. More...
 

Protected methods

void on_value_changed () override
 Determines whether the new value of the Value property can be parsed as a Boolean value. More...
 

Additional Inherited Members

- Public Member Functions inherited from xtd::diagnostics::switch_base
const std::map< xtd::ustring, xtd::ustring > & attributes () const noexcept
 Gets the custom switch attributes nA StringDictionary containing the case-insensitive custom attributes for the trace switch. More...
 
std::map< xtd::ustring, xtd::ustring > & attributes () noexcept
 Gets the custom switch attributes. More...
 
void attributes (const std::map< xtd::ustring, xtd::ustring > &attributes) noexcept
 Sets the custom switch attributes. More...
 
const xtd::ustringdescription () const noexcept
 Gets a description of the switch. More...
 
const xtd::ustringdisplay_name () const noexcept
 Gets a name used to identify the switch. More...
 
bool equals (const switch_base &value) const noexcept override
 
- Public Member Functions inherited from xtd::object
 object ()=default
 Create a new instance of the ultimate base class object. More...
 
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...
 
virtual type_object get_type () const noexcept
 Gets the type of the current instance. More...
 
template<typename object_t >
std::unique_ptr< object_t > memberwise_clone () const noexcept
 Creates a shallow copy of the current object. More...
 
virtual xtd::ustring to_string () const noexcept
 Returns a sxd::ustring that represents the current object. More...
 
- Public Member Functions inherited from xtd::iequatable< switch_base >
virtual bool equals (const switch_base &) const noexcept=0
 Indicates whether the current object is equal to another object of the same type. More...
 
- 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::switch_base
 switch_base (const xtd::ustring &display_name, const xtd::ustring &description)
 Initializes a new instance of the switch_base class. More...
 
 switch_base (const xtd::ustring &display_name, const xtd::ustring &description, const xtd::ustring &default_switch_value)
 Initializes a new instance of the switch_base class. More...
 
int32 switch_setting () const noexcept
 Gets the current setting for this switch. More...
 
void switch_setting (int32 switch_setting)
 Sets the current setting for this switch. More...
 
const xtd::ustringvalue () const noexcept
 Gets the value of the switch. More...
 
void value (const xtd::ustring &value)
 Sets the value of the switch. More...
 
virtual std::vector< xtd::ustringget_supported_attributes () const noexcept
 Gets the custom attributes supported by the switch. More...
 
virtual void on_switch_setting_changed ()
 Invoked when the switch_setting property is changed. More...
 

Constructor & Destructor Documentation

◆ boolean_switch() [1/2]

xtd::diagnostics::boolean_switch::boolean_switch ( const xtd::ustring display_name,
const xtd::ustring description 
)

Initializes a new instance of the xtd::diagnostics::boolean_switch class with the specified display name and description.

Parameters
display_nameThe name to display on a user interface.
descriptionThe description of the switch.
Examples
The following example creates a xtd::diagnostics::boolean_switch and uses the switch to determine whether to print an error message. The switch is created at the class level. The Main method passes its location to MyMethod, which prints an error message and where the error occurred.
/* Class level declaration.*/
private:
// Create a BooleanSwitch for data.
inline static xtd::diagnostics::boolean_switch data_switch("data", "data_access module");
public:
static void my_method(const xtd::ustring& location) {
// Insert code here to handle processing.
if (data_switch.enabled())
console::write_line("Error happened at {}", location);
}
static auto main(const std::vector<xtd::ustring>& args) {
//Run the method which writes an error message specifying the location of the error.
my_method("in Main");
}
Remarks
When you create a xtd::diagnostics::boolean_switch, the display_name parameter is used to find initial switch settings. If the constructor cannot find initial settings, the xtd::diagnostics::boolean_switch::enabled property is set to false (disabled).
The switches you created should be static.

◆ boolean_switch() [2/2]

xtd::diagnostics::boolean_switch::boolean_switch ( const xtd::ustring display_name,
const xtd::ustring description,
const xtd::ustring default_switch_value 
)

Initializes a new instance of the xtd::diagnostics::boolean_switch class with the specified display name, description, and default switch value.

Parameters
display_nameThe name to display on a user interface.
descriptionThe description of the switch.
default_switch_valueThe default value of the switch.
Remarks
The display_name parameter is used to set the value of the xtd::diagnostics::boolean_switch::display_name property, and the description parameter is use to set the value of the xtd::diagnostics::boolean_switch::description property. The default_switch_value parameter is saved as a field and used to initialize the xtd::diagnostics::boolean_switch::value property on first reference. For more information about constructor use, see the xtd::diagnostics::boolean_switch::booleanswitch(std::string, xtd::ustring) constructor.

Member Function Documentation

◆ enabled() [1/2]

bool xtd::diagnostics::boolean_switch::enabled ( ) const

Gets a value indicating whether the switch is enabled or disabled.

Returns
true if the switch is enabled; otherwise, false. The default is false.
Remarks
By default, this field is set to false (disabled). To enable the switch, assign this field the value of true. To disable the switch, assign the value to false. The value of this property is determined by the value of the base class property xtd::diagnostics::boolean_switch::switch_setting.

◆ enabled() [2/2]

void xtd::diagnostics::boolean_switch::enabled ( bool  enabled)

Sets a value indicating whether the switch is enabled or disabled.

Parameters
enabledtrue if the switch is enabled; otherwise, false. The default is false.
Remarks
By default, this field is set to false (disabled). To enable the switch, assign this field the value of true. To disable the switch, assign the value to false. The value of this property is determined by the value of the base class property xtd::diagnostics::boolean_switch::switch_setting.

◆ on_value_changed()

void xtd::diagnostics::boolean_switch::on_value_changed ( )
overrideprotectedvirtual

Determines whether the new value of the Value property can be parsed as a Boolean value.

Remarks
The xtd::diagnostics::boolean_switch::on_value_changed method determines whether the new value is a valid string representation of a boolean value ("false" or "true"). If so, the method sets the xtd::diagnostics::boolean_switch::switch_setting property to 0 or 1. Otherwise, the base method is called, which converts the string value to an integer value, which is then used to set the xtd::diagnostics::boolean_switch::switch_setting property.

Reimplemented from xtd::diagnostics::switch_base.


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