exception reference

See the User's Guide for more explaination.

exception (const char* module, const char* name, const char* fname, int line)

constructor, public

The constructor takes the essential information contained in the exception object. See the User’s Guide for examples and an overview of the concept.

The module parameter should match the name of the library or other component. The file name and line number is not unique, because different projects can contain similarly named files. So this argument is designed to take the identification a step farther. All exceptions created in the same component should use the same string here.

The fname and line parameters identify the location of the exception. You should (ultimatly) use __FILE__ and __LINE__ to supply these values.

The name parameter is a short label identifying the nature of the problem.

~exception()

destructor, virtual, public

void operator+= (const ustring& val)

public

This function adds free text to the exception object.

void operator() (const char* module, const char* name, const char* fname, int line)

public

This function adds a new stanza to the exception. It’s designed to look just like the constructor, which creates the first stanza. Example,

catch (exception& X) {
   X ("module", "An Error", __FILE__, __LINE__);
   X += "Here is some more specific information.";
   throw;
   }

void add_key (const wchar_t* key, const ustring& value)

void add_key (const wchar_t* key, int value)

public

These functions add a named value to the exception object.

void default_show_function (const exception&)

static, public

This formats the exception and sends it to the standard error file.

string& get_internal_data()

const wstring get_internal_data() const

public

These functions return a reference to the internal data. It’s used to implement operator+=. Try using value instead.

class iterator

type, public

This nested class is used to access the information in the exception object in a structured manner. See the class index or the Iterator User’s Guide for more information.

void (*setup_hook) (exception* self, const ustring& module, const ustring& name, const ustring& fname, int line)

static, public, data

This pointer is used by the constructor and operator() function too do all the work of populating the normal values. If this pointer is defined, the function is called and must do all the work. The supplied function may call normal_setup to do the basics, and supply additional code. Or, it may do everything itself and not call normal_setup.

If setup_hook is null, then normal_setup is called implicitly.

For example, a main program could contain:

int error_count= 0;
std::wstring docname= "<untitled-1>";
static void my_setup_hook (classics::exception* self, const classics::ustring& module, const classics::ustring& name, const classics::ustring& fname, int line)
 {
 ++error_count;  // count how many times I'm called.  (each stanza actually)
 // do all the normal stuff first.
 classics::exception::normal_setup (self, module, name, fname, line);
 // automatically add a time stamp
 wchar_t timecode[17];
 _i64tow(ratwin::GetSystemTimeAsFileTime(), timecode, 16);
 self->add_key (L"timestamp", timecode);
 // add the document name
 self->add_key (L"docname", docname);
 }

and then call

 classics::exception::setup_hook= my_setup_hook;

from main().

See also: exception::register_callback class for another mechanism.

void show() const

virtual, public

This function is used to present the information in the exception to the user. The default implementation is to call (*show_function). An overriding function shouldn't change how the information is presented (use show_function for that) but can be used as a hook to finalize data before presenting it.

void (*show_function)(const exception&)

static, public

ustring value() const

public

This returns the complete description of the error as a string.

The string is returned as a ustring so that it may easily be obtained in any desired flavor, but internally the data is kept as a single wstring value.

The format of the string is described using the non-printing delimiter characters.

Stanzas are separated by Split3. Multiple whole exceptions written to a text log should be separated by Split4, but this character will not appear (in the top level) in this string.

Named attributes within the string are delimited by Open1/Close1 brackets, and free text has no delimitation.

It is better to manipulate the exception object using the iterator class, but the structure of the data is precicely defined so you can rely on this if you need to.