namespace dbg

Debugging utilities. More...

List of all Methods
Annotated List
Files
Globals
Hierarchy
Index

Public Types

Public Methods

Public Members


Detailed Description

The dbg namespace holds a number of C++ debugging utilities.

They allow you to include constraint checking in your code, and provide an integrated advanced stream-based logging facility.

The characteristics of this library are:

Enabling debugging

To use dbg in your program you must #include <dbg.h> and compile with the DBG_ENABLED flag set.

If you build without DBG_ENABLED you will have no debugging support (neither constraints nor logging). There is no overhead building a program using these utilities when DBG_ENABLED is not set. Well, actually there might be minimal overhead: there is no overhead when using gcc with a little optimisation (-O3). There is a few bytes overhead with optimisation disabled. (The -O1 level leaves almost no overhead.)

Either way, the rich debugging support is probably worth a few bytes.

Once your program is running, you will want to enable diagnostic levels with dbg::enable, and probably attach an ostream (perhaps cerr) to the diagnostic outputs. See the default states section below for information on the initial state of dbg.

Aside: The standard assert macro is an insidious little devil, a lower case macro. This library replaces it and builds much richer constraints in its place. However, because of it, we have to use an API name dbg::assertion, not dbg::assert - this makes me really cross, but I can't assume that the user does not #include <assert.h> when using <dbg.h> .

Using constraints

The dbg library constraints are very easy to use. Each debugging utility is documented fully to help you understand how they work. Here are some simple examples of library use for run-time constraint checking:


     void test_dbg()
     {
         dbg::trace trace(DBG_HERE);

         int  i   = 5;
         int *ptr = &i;

         dbg::assertion(DBG_ASSERTION(i != 6));
         dbg::check_ptr(ptr, DBG_HERE);

         if (i == 5)
         {
             return;
         }

         // Shouldn't get here
         dbg::sentinel(DBG_HERE);
     }

The constraints provided by dbg are:

You can modify constraint behaviour with:

See their individual documentation for further details on usage.

You can specify whether constraints merely report a warning, cause an exception to be thrown, or immediately abort the program (see dbg::assertion_behaviour).

For assertions that may fire many times in a tight loop, there is the facility to time-restrict output (see dbg::set_assertion_period)

Using logging

All the constraint checking shown above integrates with the dbg library stream logging mechanisms. These logging facilities are open for your use as well.

Here is a simple example of this:


     dbg::attach_ostream(dbg::info, cout);
     // now all 'info' messages go to cout

     dbg::out(dbg::info)    << "This is some info I want to print out\n";

     dbg::out(dbg::tracing) << dbg::indent()
                            << "This is output at 'tracing' level, indented "
                            << "to the same level as the current tracing "
                            << "indent.\n";

When you build without the DBG_ENABLED flag specified, these logging messages will compile out to nothing.

The logging is a very flexible system. You can attach multiple ostreams to any dbg output, so you can easily log to a file and log to the console, for example. The output can be formatted in a number of different ways to suit your needs.

The logging mechanisms provide you with the ability to prepend to all diagnostic output a standard prefix (see dbg::set_prefix), and also to add the diagnostic level and current time to the prefix (see dbg::enable_level_prefix and dbg::enable_time_prefix).

The logging facilities provide by dbg include:

The output formatting utilities include:

Diagnostic sources

The dbg library allows you to differentiate different "sources" of logging.

Each of the debug utilities has a second form in which you can supply a string describing the source of the diagnostic output (see dbg::dbg_source). This source may be a different software component, a separate file - whatever granularity you like!

If you don't specify a dbg::dbg_source then you are working with the ordinary "unnamed" source.

Using these forms you can filter out diagnostics from the different parts of your code. Each source can also be attached to a different set of streams (logging each component to a separate file, for example). The filtering is rich - you can selectively filter each different diagnostic dbg::level for each dbg::dbg_source. For example,


     dbg::enable(dbg::all, "foo-driver", true);
     dbg::enable(dbg::all, "bar-driver", false);

     int i = 5;
     dbg::assertion("foo-driver", DBG_ASSERTION(i != 6));
     dbg::assertion("bar-driver", DBG_ASSERTION(i != 6));

This will trigger an assertion for the "foo-driver" but not the "bar-driver".

There is no requirement to "register" a dbg::dbg_source. The first time you use it in any of the dbg APIs, it will be registered with the dbg library. It comes into an existence as a copy of the "default" debugging source, dbg::default_source.

The default source initially has all debug levels disabled. You can change that with this call. Note that this function only affects sources created after the call is made. Existing sources are unaffected.

If you don't know all of the dbg::dbg_source sources currently available, you can blanket enable/disable them with dbg::enable_all.

It can be tedious to specify the dbg_source in every dbg call in a source file. For this reason, you can specify the DBG_SOURCE compile time macro (wherever you specify DBG_ENABLED). When set, the calls automatically receive the source name via the DBG_HERE macro (see dbg::source_pos for details). If DBG_SOURCE is supplied but you call a dbg API with a specific named dbg_source, this name will override the underlying DBG_SOURCE name.

Overloads

Each constraint utility has a number of overloaded forms. This is to make using them more convenient. The most rich overload allows you to specify a diagnostic dbg::level and a dbg::dbg_source. There are other versions that omit one of these parameters, assuming a relevant default.

Default states

When your program first starts up the dbg library has all debugging levels switched off. You can enable debugging with dbg::enable. All of the possible dbg::dbg_source enables are also all off for all levels. You can enable these with dbg::enable, or dbg::enable_all.

Initially, the std::cerr stream is attached to the dbg::error and dbg::fatal diagnostic levels. You can attach ostreams to the other diagnostic levels with dbg::attach_ostream.

You can modify the "default state" of newly created debug sources. To do this use the special dbg::default_source source name in calls to dbg::enable, dbg::attach_ostream, and and detach_ostream. New sources take the setup from this template source.

All assertion levels are set to dbg::assertions_abort at first, like the standard library's assert macro. You can change this behaviour with dbg::set_assertion_behaviour. There are no timeout periods set - you can change this with dbg::set_assertion_period.

const int version

version

enum level { info, warning, error, fatal, tracing, debug, none, all }

level

The various predefined debugging levels. The dbg API calls use these levels as parameters, and allow the user to sift the less interesting debugging levels out through dbg::enable.

These levels (and their intended uses) are:

enum assertion_behaviour { assertions_abort, assertions_throw, assertions_continue }

assertion_behaviour

This enum type describes what happens when a debugging assertion fails. The behaviour can be:

The dbg library defaults to assertions_abort behaviour, like the standard C assert.

See also: set_assertion_behaviour

typedef const char * dbg_source

dbg_source

typedef for a string that describes the "source" of a diagnostic. If you are working on a large project with many small code modules you may only want to enable debugging from particular source modules. This typedef facilitates this.

Depending on the desired granularity of your dbg sources you will use different naming conventions. For example, your dbg_sources might be filenames, that way you can switch off all debugging output from a particular file quite easily. It might be device driver names, component names, library names, or even function names. It's up to you.

If you provide the DBG_SOURCE macro definition at compile time, then the DBG_HERE macro includes this source name, differentiating the sources for you automatically.

See also: enable_all, dbg_source, bool), dbg::enable_all

typedef const unsigned int line_no_t

line_no_t

Typedef used in the source_pos data structure.

Describes a line number in a source file.

See also: source_pos

typedef const char * func_name_t

func_name_t

Typedef used in the source_pos data structure.

Describes a function name in a source file. (Can be zero to indicate the function name cannot be ascertained on this compiler).

See also: source_pos

typedef const char * file_name_t

file_name_t

Typedef used in the source_pos data structure.

Describes a filename.

See also: source_pos

source_pos (struct)

source_pos

Data structure describing a position in the source file. That is,

To create a source_pos for the current position, you can use the DBG_HERE convenience macro.

There is an empty constructor that allows you to create a source_pos that represents 'no position specified'.

This structure should only be used in dbg library API calls.

You can print a source_pos using the usual stream manipulator syntax.

typedef std::clock_t dbgclock_t

dbgclock_t

The dbgclock_t typedef is an unfortunate workaround for compatibility purposes. One (unnamed) popular compiler platform supplies a header file, but this header does NOT place the contents into the std namespace.

This typedef is the most elegant work around for that problem. It is conditionally set to the appropriate clock_t definition.

In an ideal world this would not exist.

This is the version for sane, standards-compliant platforms.

typedef clock_t dbgclock_t

dbgclock_t

See dbgclock_t documentation above. This is the version for broken compiler platforms.

dbg_exception (struct)

dbg_exception

The base type of exception thrown by dbg assertions (and other dbg library constraint checks) if the assertion_behaviour is set to assertions_throw.

The exception keeps a record of the source position of the trigger for this exception.

assertion_exception (struct)

assertion_exception

The type of exception thrown by assertion.

See also: assertion

sentinel_exception (struct)

sentinel_exception

The type of exception thrown by sentinel.

See also: sentinel

unimplemented_exception (struct)

unimplemented_exception

The type of exception thrown by unimplemented.

See also: unimplemented

check_ptr_exception (struct)

check_ptr_exception

The type of exception thrown by check_ptr.

See also: check_ptr

extern dbg_source default_source

default_source

void  enable (level lvl, bool enabled)

enable

Enables or disables a particular debugging level. The affects dbg library calls which don't specify a dbg_source, i.e. from the unnamed source.

Enabling affects both constraint checking and diagnostic log output.

If you enable a debugging level twice you only need to disable it once.

All diagnostic output is initially disabled. You can easily enable output in your main() thus:


     dbg::enable(dbg::all, true);

Note that if dbg library calls do specify a dbg_source, or you provide a definition for the DBG_SOURCE macro on compilation, then you will instead need to enable output for that particular source. Use the overloaded version of enable. This version of enable doesn't affect these other dbg_source calls.

Parameters:
lvlDiagnostic level to enable/disable
enabledtrue to enable this diagnostic level, false to disable it

See also: enable_all, out, attach_ostream

void  enable (level lvl, dbg_source src, bool enabled)

enable

In addition to the above enable function, this overloaded version is used when you use dbg APIs with a dbg_source specified. For these versions of the APIs no debugging will be performed unless you enable it with this API.

To enable debugging for the "foobar" diagnostic source at the info level you need to do the following:


     dbg::enable(dbg::info, "foobar", true);

If you enable a level for a particular dbg_source twice you only need to disable it once.

Parameters:
lvlDiagnostic level to enable/disable for the dbg_source
srcString describing the diagnostic source
enabledtrue to enable this diagnostic level, false to disable it

See also: out

void  enable_all (level lvl, bool enabled)

enable_all

You may not know every single dbg_source that is generating debugging in a particular code base. However, using this function you can enable a diagnostic level for all currently registered sources in one fell swoop.

For example,


     dbg::enable_all(dbg::all, true);

std::ostream & out (level lvl, dbg_source src)

out

Returns an ostream suitable for sending diagnostic messages to. Each diagnostic level has a different logging ostream which can be enabled/disabled independently. In addition, each dbg_source has separate enables/disables for each diagnostic level.

This overloaded version of out is used when you are creating diagnostics that are tied to a particular dbg_source.

It allows you to write code like this:


     dbg::out(dbg::info, "foobar") << "The foobar is flaky\n";

If you want to prefix your diagnostics with the standard dbg library prefix (see set_prefix) then use the prefix or indent stream manipulators.

Parameters:
lvlDiagnostic level get get ostream for
srcString describing the diagnostic source

inline std::ostream & out (level lvl)

out

Returns an ostream suitable for sending diagnostic messages to. Each diagnostic level has a different logging ostream which can be enabled/disabled independently.

You use this version of out when you are creating diagnostics that aren't tidied to a particular dbg_source.

Each diagnostic dbg_source has a separate set of streams. This function returns the stream for the "unnamed" source. Use the overload below to obtain the stream for a named source.

It allows you to write code like this:


     dbg::out(dbg::info) << "The code is flaky\n";

If you want to prefix your diagnostics with the standard dbg library prefix (see set_prefix) then use the prefix or indent stream manipulators.

Parameters:
lvlDiagnostic level get get ostream for

void  attach_ostream (level lvl, std::ostream &o)

attach_ostream

Attaches the specified ostream to the given diagnostic level for the "unnamed" debug source. Now when diagnostics are produced at that level, this ostream will receive a copy.

You can attach multiple ostreams to a diagnostic level. Be careful that they don't go to the same place (e.g. cout and cerr both going to your console) - this might confuse you!

If you attach a ostream multiple times it will only receive one copy of the diagnostics, and you will only need to call detach_ostream once.

Remember, don't destroy the ostream without first removing it from dbg library, or Bad Things will happen.

Parameters:
lvlDiagnostic level
oostream to attach

See also: detach_ostream, detach_all_ostreams

void  attach_ostream (level lvl, dbg_source src, std::ostream &o)

attach_ostream

Attaches the specified ostream to the given diagnostic level for the specified debug source. Otherwise, similar to dbg::attach_ostream above.

Parameters:
lvlDiagnostic level
srcDebug source
oostream to attach

See also: detach_ostream, detach_all_ostreams

void  detach_ostream (level lvl, std::ostream &o)

detach_ostream

Detaches the specified ostream from the given diagnostic level.

If the ostream was not attached then no error is generated.

If you attached the ostream twice, one call to detach_ostream will remove it completely.

Parameters:
lvlDiagnostic level
oostream to detach

See also: attach_ostream, detach_all_ostreams

void  detach_ostream (level lvl, dbg_source src, std::ostream &o)

detach_ostream

Detaches the specified ostream from the given diagnostic level for the specified debug source. Otherwise, similar to dbg::detach_ostream above.

Parameters:
lvlDiagnostic level
srcDebug source
oostream to detach

See also: attach_ostream, detach_all_ostreams

void  detach_all_ostreams (level lvl)

detach_all_ostreams

Detaches all attached ostreams from the specified diagnostic level for the "unnamed" diagnostic source.

Parameters:
lvlDiagnostic level

See also: attach_ostream, detach_ostream

void  detach_all_ostreams (level lvl, dbg_source src)

detach_all_ostreams

Detaches all attached ostreams from the specified diagnostic level for the specified debug source. Otherwise, similar to dbg::detach_all_ostreams above.

Parameters:
lvlDiagnostic level

See also: attach_ostream, detach_ostream

inline std::ostream & info_out ()

info_out

Convenience function that returns the ostream for the info dbg::level for the "unnamed" source.

See also: out

inline std::ostream & warning_out ()

warning_out

Convenience function that returns the ostream for the warning dbg::level for the "unnamed" source.

See also: out

inline std::ostream & error_out ()

error_out

Convenience function that returns the ostream for the error dbg::level for the "unnamed" source.

See also: out

inline std::ostream & fatal_out ()

fatal_out

Convenience function that returns the ostream for the fatal dbg::level for the "unnamed" source.

See also: out

inline std::ostream & trace_out ()

trace_out

Convenience function that returns the ostream for the tracing dbg::level for the "unnamed" source.

See also: out

void  set_prefix (const char *prefix)

set_prefix

Sets the debugging prefix - the characters printed before any diagnostic output. Defaults to "*** ".

Parameters:
prefixNew prefix string

See also: prefix, enable_level_prefix, enable_time_prefix

void  enable_level_prefix (bool enabled)

enable_level_prefix

The dbg library can add to the prefix the name of the used diagnostic level (e.g. info, fatal, etc).

By default, this facility is disabled. This function allows you to enable the facility.

Parameters:
enabledtrue to enable level prefixing, false to disable

See also: set_prefix, enable_time_prefix

void  enable_time_prefix (bool enabled)

enable_time_prefix

The dbg library can add to the prefix the current time. This can be useful when debugging systems which remain active for long periods of time.

By default, this facility is disabled. This function allows you to enable the facility.

The time is produced in the format of the standard library ctime function.

Parameters:
enabledtrue to enable time prefixing, false to disable

See also: set_prefix, enable_level_prefix

prefix (struct)

prefix

Used so that you can produce a prefix in your diagnostic output in the same way that the debugging library does.

You can use it in one of two ways: with or without a diagnostic level. For the latter, if level prefixing is enabled (see enable_level_prefix) then produces a prefix including the specified diagnostic level text.

Examples of use:


     dbg::out(dbg::info) << dbg::prefix()
                         << "A Bad Thing happened\n";

     dbg::out(dbg::info) << dbg::prefix(dbg::info)
                         << "A Bad Thing happened\n";

See also: indent, set_prefix, enable_level_prefix, enable_time_prefix

std::ostream & operator<< (std::ostream &s, const prefix &p)

operator<<

This is called when you use the prefix stream manipulator.

See also: prefix

indent (struct)

indent

Used so that you can indent your diagnostic output to the same level as the debugging library. This also produces the prefix output.

Examples of use:


     dbg::out(dbg::info) << dbg::indent()
                         << "A Bad Thing happened\n";

     dbg::out(dbg::info) << dbg::indent(dbg::info)
                         << "A Bad Thing happened\n";

See also: prefix, set_prefix, enable_level_prefix, enable_time_prefix

std::ostream & operator<< (std::ostream &s, const indent &i)

operator<<

This is called when you use the indent stream manipulator.

See also: indent

std::ostream & operator<< (std::ostream &s, const source_pos &pos)

operator<<

This is called when you send a source_pos to a diagnostic output. You can use this to easily check the flow of execution in your program.

For example,


     dbg::out(dbg::tracing) << DBG_HERE << std::endl;

Take care that you only send DBG_HERE to the diagnostic outputs (obtained with dbg::out) and not "ordinary" streams like std::cout.

In non debug builds, DBG_HERE is a "no-op" doing nothing, and so no useful output will be produced on cout.

See also: indent

void  set_assertion_behaviour (level lvl, assertion_behaviour behaviour)

set_assertion_behaviour

Sets what happens when assertions (or other constraints) trigger. There will always be diagnostic output. Assertions have 'abort' behaviour by default - like the ISO C standard, they cause an abort.

If an assertion is encountered at the fatal level, the debugging library will abort the program regardless of this behaviour setting.

If a diagnostic level is not enabled (see enable) then the assertion_behaviour is not enacted, and no output is produced.

Parameters:
lvlDiagnostic level to set behaviour for
behaviourAssertion behaviour

See also: set_assertion_period, enable, assertion, sentinel, unimplemented, check_ptr

void  set_assertion_period (dbgclock_t period)

set_assertion_period

You may want an assertion to trigger once only and then for subsequent calls to remain inactive. For example, if there is an assertion in a loop you may not want diagnostics produced for each loop iteration.

To do this, you do the following:


      // Prevent several thousand diagnostic print outs
      dbg::set_assertion_period(CLOCKS_PER_SEC);

      // Example loop
      int array[LARGE_VALUE];
      put_stuff_in_array(array);
      for(unsigned int n = 0; n < LARGE_VALUE; n++)
      {
          dbg::assertion(DBG_ASSERT(array[n] != 0));
          do_something(array[n]);
      }

set_assertion_period forces a certain time period between triggers of a particular constraint. The assertion in the example above will only be triggered once a second (despite the fact that the constraint condition will be broken thousands of times a second). This will not affect any other assertion - they will each have their own timeout periods.

Setting a period of zero disables any constraint period.

The default behaviour is to have no period.

If a period is set then diagnostic printouts will include the number of times each constraint has been triggered (since the period was set). Using this, even if diagnostics don't always appear on the attached ostreams you have some indication of how often each constraint is triggered.

This call only really makes sense if the assertion_behaviour is set to assertions_continue.

Parameters:
periodTime between triggerings of each assertion, or zero to disable

See also: set_assertion_behaviour, assertion, sentinel, unimplemented, check_ptr

assert_info (struct)

assert_info

Describes an assertion.

This is an internal data structure, you do not need to create it directly. Use the DBG_ASSERTION macro to create it.

See also: assertion

void  assertion (level lvl, dbg_source src, const assert_info &ai)

assertion

Used to assert a constraint in your code. Use the DBG_ASSERTION macro to generate the third parameter.

This version creates an assertion bound to a particular dbg_source.

The assertion is the most general constraint utility - there are others which have more specific purposes (like check_ptr to ensure a pointer is non-null). assertion allows you to test any boolean expression.

To use assertion for a dbg_source "foobar" you write code like:


     int i = 0;
     dbg::assertion(info, "foobar", DBG_ASSERTION(i != 0));

If you build with debugging enabled (see dbg) the program will produce diagnostic output to the relevant output stream if the constraint fails, and the appropriate assertion_behaviour is enacted.

Since in non-debug builds the expression in the DBG_ASSERTION macro will not be evaluated, it is important that the expression has no side effects.

Parameters:
lvlDiagnostic level to assert at
srcString describing the diagnostic source
aiassert_info structure created with DBG_ASSERTION

inline void  assertion (level lvl, const assert_info &ai)

assertion

Overloaded version of assertion that is not bound to a particular dbg_source.

Parameters:
lvlDiagnostic level to assert at
aiassert_info structure created with DBG_ASSERTION

inline void  assertion (dbg_source src, const assert_info &ai)

assertion

Overloaded version of assertion that defaults to the warning level.

Parameters:
srcString describing the diagnostic source
aiassert_info structure created with DBG_ASSERTION

inline void  assertion (const assert_info &ai)

assertion

Overloaded version of assertion that defaults to the warning level and is not bound to a particular dbg_source.

Parameters:
aiassert_info structure created with DBG_ASSERTION

void  sentinel (level lvl, dbg_source src, const source_pos &here)

sentinel

You should put this directly after a "should never get here" comment.


      int i = 5;
      if (i == 5)
      {
          std::cout << "Correct program behaviour\n";
      }
      else
      {
          dbg::sentinel(dbg::error, "foobar", DBG_HERE);
      }

Parameters:
lvlDiagnostic level to assert at
srcString describing the diagnostic source
hereSupply DBG_HERE

inline void  sentinel (level lvl, const source_pos &here)

sentinel

Overloaded version of sentinel that is not bound to a particular dbg_source.

Parameters:
lvlDiagnostic level to assert at
hereSupply DBG_HERE

inline void  sentinel (dbg_source src, const source_pos &here)

sentinel

Overloaded version of sentinel that defaults to the warning level and is not bound to a particular dbg_source.

Parameters:
srcString describing the diagnostic source
hereSupply DBG_HERE

inline void  sentinel (const source_pos &here)

sentinel

Overloaded version of sentinel that defaults to the warning level and is not bound to a particular dbg_source.

Parameters:
hereSupply DBG_HERE

void  unimplemented (level lvl, dbg_source src, const source_pos &here)

unimplemented

You should put this directly after a "this has not been implemented (yet)" comment.


      switch (variable)
      {
          ...
          case SOMETHING:
          {
              dbg::unimplemented(dbg::warning, "foobar", DBG_HERE);
              break;
          }
          ...
      }

Note the "break;" above - if the assertion_behaviour is non-fatal then execution will continue. You wouldn't want unintentional fall-through.

Parameters:
lvlDiagnostic level to assert at
srcString describing the diagnostic source
hereSupply DBG_HERE

inline void  unimplemented (level lvl, const source_pos &here)

unimplemented

Overloaded version of unimplemented that is not bound to a particular dbg_source.

Parameters:
lvlDiagnostic level to assert at
hereSupply DBG_HERE

inline void  unimplemented (dbg_source src, const source_pos &here)

unimplemented

Overloaded version of unimplemented that defaults to the warning level.

Parameters:
srcString describing the diagnostic source
hereSupply DBG_HERE

inline void  unimplemented (const source_pos &here)

unimplemented

Overloaded version of unimplemented that defaults to the warning level and is not bound to a particular dbg_source.

Parameters:
hereSupply DBG_HERE

void  check_ptr (level lvl, dbg_source src, const void *p, const source_pos &here)

check_ptr

A diagnostic function to assert that a pointer is not zero.

To use it you write code like:


     void *p = 0;
     dbg::check_ptr(dbg::info, "foobar", p, DBG_HERE);

It's better to use this than a general purpose assertion. It reads far more intuitively in your code.

Parameters:
lvlDiagnostic level to assert at
srcString describing the diagnostic source
pPointer to check
hereSupply DBG_HERE

inline void  check_ptr (level lvl, const void *p, const source_pos &here)

check_ptr

Overloaded version of check_ptr that is not bound to a particular dbg_source.

Parameters:
lvlDiagnostic level to assert at
pPointer to check
hereSupply DBG_HERE

inline void  check_ptr (dbg_source src, const void *p, const source_pos &here)

check_ptr

Overloaded version of check_ptr that defaults to the warning level.

Parameters:
srcString describing the diagnostic source
pPointer to check
hereSupply DBG_HERE

inline void  check_ptr (const void *p, const source_pos &here)

check_ptr

Overloaded version of check_ptr that defaults to the warning level and is not bound to a particular dbg_source.

Parameters:
pPointer to check
hereSupply DBG_HERE

template inline unsigned int  array_size (T &array)

array_size

Utility that determines the number of elements in an array. Used by the check_bounds constraint utility function.

This is not available in non-debug versions, so do not use it directly.

Parameters:
arrayArray to determine size of

Returns: The number of elements in the array

void  check_bounds (level lvl, dbg_source src, int index, int bound, const source_pos &here)

check_bounds

A diagnostic function to assert that an array access is not out of bounds.

You probably want to use the more convenient check_bounds versions below if you are accessing an array whose definition is in scope - the compiler will then safely determine the size of the array for you.

Parameters:
lvlDiagnostic level to assert at
srcString describing the diagnostic source
indexTest index
boundBoundary value (index must be < bound, and >= 0)
hereSupply DBG_HERE

inline void  check_bounds (level lvl, dbg_source src, int index, int minbound, int maxbound, const source_pos &here)

check_bounds

A diagnostic function to assert that an array access is not out of bounds. With this version you can specify the minimum and maximum bound value.

You probably want to use the more convenient check_bounds version below if you are accessing an array whose definition is in scope - the compiler will then safely determine the size of the array for you.

Parameters:
lvlDiagnostic level to assert at
srcString describing the diagnostic source
indexTest index
minboundMinimum bound (index must be >= minbound
maxboundMinimum bound (index must be < maxbound)
hereSupply DBG_HERE

template void  check_bounds (level lvl, dbg_source src, int index, T &array, const source_pos &here)

check_bounds

Overloaded version of check_bounds that can automatically determine the size of an array if it within the current scope.

You use it like this:


     int a[10];
     int index = 10;
     dbg::check_bounds(dbg::error, index, a, DBG_HERE);
     a[index] = 5;

Parameters:
lvlDiagnostic level to assert at
srcString describing the diagnostic source
indexTest index
arrayArray index is applied to
hereSupply DBG_HERE

template void  check_bounds (level lvl, int index, T &array, const source_pos &here)

check_bounds

Overloaded version of check_bounds that is not bound to a particular dbg_source.

Parameters:
lvlDiagnostic level to assert at
indexTest index
arrayArray index is applied to
hereSupply DBG_HERE

template void  check_bounds (dbg_source src, int index, T &array, const source_pos &here)

check_bounds

Overloaded version of check_bounds that defaults to the warning level.

Parameters:
srcString describing the diagnostic source
indexTest index
arrayArray index is applied to
hereSupply DBG_HERE

template void  check_bounds (int index, T &array, const source_pos &here)

check_bounds

Overloaded version of check_bounds that defaults to the warning level and is not bound to a particular dbg_source.

Parameters:
indexTest index
arrayArray index is applied to
hereSupply DBG_HERE

trace (class)

trace

The trace class allows you to easily produce tracing diagnostics.

When the ctor is called, it prints "->" and the name of the function, increasing the indent level. When the object is deleted it prints "<-" followed again by the name of the function.

You can use the name of the current function gathered via the DBG_HERE macro, or some other tracing string you supply.

Diagnostics are produced at the tracing level.

For example, if you write the following code:


     void foo()
     {
         dbg::trace t1(DBG_HERE);
         // do some stuff
         {
             dbg::trace t2("sub block");
             // do some stuff
             dbg::out(tracing) << dbg::prefix() << "Hello!\n";
         }
         dbg::out(tracing) << dbg::prefix() << "Hello again!\n";
         // more stuff
     }

You will get the following tracing information:


     *** ->foo (0 in foo.cpp)
     ***   ->sub block
     ***     Hello!
     ***   <-sub block
     ***   Hello again!
     *** <-foo (0 in foo.cpp)

Don't forget to create named dbg::trace objects. If you create anonymous objects (i.e. you just wrote "dbg::trace(DBG_HERE);") then the destructor will be called immediately, rather than at the end of the block scope, causing invalid trace output.

Tracing does not cause assertions to trigger, therefore you will never generate an abort or exception using this object.

If you disable the tracing diagnostic level before the trace object's destructor is called you will still get the closing trace output. This is important, otherwise the indentation level of the library would get out of sync. In this case, the closing diagnostic output will have a "note" attached to indicate what has happened.

Similarly, if tracing diagnostics are off when the trace object is created, yet subsequently enabled before the destructor there will be no closing tracing output.

post_mem_fun (class)

post_mem_fun

A post condition class. This utility automates the checking of post conditions using assertion. It requires a member function with the signature:


     bool some_class::invariant() const;

When you create a post_mem_fun object you specify a post condition member function. When the post_mem_fun object is destroyed the postcondition is asserted.

This is useful for methods where there are a number of exit points which would make it tedious to put the same dbg::assertion in multiple places.

It is also handy when an exception might be thrown and propagated by a function, ensuring that a postcondition is first checked. Bear in mind that Bad Things can happen if the assertion_behaviour is assertions_throw and this is triggered via a propagating exception.

An example of usage, the do_test method below uses the post_mem_fun object:


     class test
     {
         public:
             test() : a(10) {}
             do_test()
             {
                 dbg::post_mem_fun
                    post(dbg::info, this, &test::invariant, DBG_HERE);
                 a = 9;
                 if (SOME_CONDITION)
                 {
                     return;                                      // (*)
                 }
                 else if (SOME_OTHER_CONDITION)
                 {
                     throw std::exception();                      // (*)
                 }
                                                                  // (*)
             }
         private:
             bool invariant()
             {
                 return a == 10;
             }
             int a;
     };

The post condition will be asserted at each point marked (*).

See also: post

post (class)

post

A post condition class. Unlike post_mem_fun, this class calls a non-member function with signature:


     bool some_function();

Otherwise, use it identically to the post_mem_fun.

See also: post_mem_fun

compile_assertion (class)

compile_assertion

If we need to assert a constraint that can be calculated at compile time, then it would be advantageous to do so - moving error detection to an earlier phase in development is always a Good Thing.

This utility allows you to do this. You use it like this:


     enum { foo = 4, bar = 6 };
     compile_assertion<(foo > bar)>();

There is a particular point to observe here. Although the expression is now a template parameter, it is important to contain it in parentheses. This is simply because the expression contains a ">" which otherwise would be taken by the compiler to be the closing of the template parameter. Although not all expressions require this, it is good practice to do it at all times.

const dbg_source default_source

default_source

null_stream (class)

null_stream

In non-debug versions, this class is used to replace an ostream so that code will compile away. Do not use it directly.