cisstCommon

Files
file	tmp/cisst-saw/cisst/cisstCommon/cmnConstants.h
	Declaration of various constants.
file	tmp/cisst-saw/cisst/cisstCommon/cmnLogger.h
	Declaration of cmnLogger amd macros for human readable logging.
file	tmp/cisst-saw/cisst/cisstCommon/cmnLogLoD.h
	Declaration of Levels of Detail for cmnLogger (human readable logging).
file	tmp/cisst-saw/cisst/cisstCommon/cmnPath.h
	Declaration of cmnPath.
file	tmp/cisst-saw/cisst/cisstCommon/cmnPortability.h
	Portability across compilers and operating systems tools.
file	tmp/cisst-saw/cisst/cisstCommon/cmnPrintf.h
	Declaration of cmnPrintf and cmnPrintfParser.
file	tmp/cisst-saw/cisst/cisstCommon/cmnRequiresDeepCopy.h
	Declaration of cmnRequiresDeepCopy.
file	tmp/cisst-saw/cisst/cisstCommon/cmnUnits.h
	Declaration of units and unit conversion methods.

Classes
class	cmnClassRegister
	Main register for classes. More...
class	cmnCommandLineOptions
	Set command line options and parse command line arguments. More...
class	cmnDeSerializer
	De-serialization utility class. More...
class	cmnGenericObject
	Base class for high level objects. More...
class	cmnLogger
	Class to glue the class register, the output multiplexer and the message level of detail to form the logging entity of cisst. More...
class	cmnNamedMap< _elementType >
class	cmnObjectRegister
	Object Register. More...
class	cmnPath
	Search path to find a file. This class contains a list of directories used to locate a file. More...
class	cmnRandomSequence
	Provide an interface to a reproducible random sequence. More...
class	cmnSerializer
	Serialization utility class. More...
class	cmnTypeTraits< _elementType >
	A collection of useful information about the C++ basic types, represented in a generic programming way. More...

Macros
#define	CMN_ASSERT_IS_DEFINED   1

Functions
	cmnPrintf (const std::string &formatStr)
	printf-like formatted output for streams
int	cmn_snprintf (char *destination, size_t size, const char *format,...)
template<class _exceptionType>
void	cmnThrow (const _exceptionType &except, cmnLogLevel lod=CMN_LOG_LEVEL_INIT_ERROR)

Detailed Description

Common tools used for most CISST applications. The main features of cisstCommon are:

• A log system. There is a set of classes and macros which allows the user to log some text information to any c++ stream, including a file or stdout. For further details, see cmnLogger, cmnClassRegister and cmnClassServices.
• A random sequence generator. For more information, see cmnRandomSequence.
• A type trait class used to define common values for different types (e.g. default tolerance for float, double, int). See cmnTypeTraits.
• A path search class, see cmnPath.
• XML Path wrappers using either LibXML2 (preferred) or Qt XML. See cmnXMLPath.

Note

All the classes and global functions of cisstCommon start with the prefix cmn. To use cisstCommon, you can either include a specific file with:

#include <cisstCommon/cmnXyz.h>

or include all the files with:

#include <cisstCommon.h>

Macro Definition Documentation

CMN_ASSERT_IS_DEFINED

#define CMN_ASSERT_IS_DEFINED   1

Assert a condition. This macro should be used whenever one needs to assert a condition.

This macro has two main advantages over the system assert:

• The error message is log using CMN_LOG (level of detail 1).

• CMN_ASSERT behavior can be modified using the defined variables CISST_CMN_ASSERT_DISABLED and CISST_CMN_ASSERT_THROWS_EXCEPTION. The first variable allows to not compile the assertion. It is similar to the NDEBUG for the standard assert .
  The second variable allows to throw an exception (of type std::logic_error) instead of using the system abort. This can be convenient if the libraries are wrapped for an interpreted language such as Python. In this case, an abort() has the annoying effect of aborting the interpreter itself.
  Both these variables can be modified using the CMake advanced mode.

Note

When compiling on linux make sure ulimit -c is unlimited! Otherwise, no core file will be generated with abort() . By default, Redhat and Debian are set to prevent any core dump.

On windows abort() uses stderr in console apps, message box API with OK button for release builds and message box API with "Abort, Ignore, Retry" for debug builds.

To determine if CMN_ASSERT is defined, CMN_ASSERT_IS_DEFINED is define as 1, 0 otherwise. This can be used to conditionally declare variables that are only used by CMN_ASSERT and avoid compiler warnings regarding unused variables.

See also

cmnThrow

Function Documentation

cmn_snprintf()

int cmn_snprintf ( char * destination, size_t size, const char * format, ... )

inline

cmnPrintf()

cmnPrintf

(

const std::string &

formatStr

)

printf-like formatted output for streams

This is the user interface for output formatting with C++ streams after the fashion of printf.

A usage example:

std::cout << cmnPrintf("Hello %.4f World\n") << 12.345;

prints the text (followed by a
newline)

  Hello 12.3450 World

cmnPrintf can be "streamed" into any object derived from the std::ostream base class. The formatting rules are the same as in the standard C routines printf, sprintf, etc. Note that if a cmnPrintf object is streamed out, the rest of the expression no longer behaves like an ordinary "ostream <<", but the cmnPrintf object takes precedence.

In behavior, the format string is parsed and whenever a '' sequence is encountered, a single object is fetched from the corresponding '<<'. That object is formatted and printed. If there are more inputs in the '<<' sequence than `' sequences in the format string, then only the objects that correspond to '' sequences are printed, and the rest are ignored. For example,

std::cout << cmnPrintf("One (%d), two and a half (%f), text (%s)")
          << 1 << 2.5 << "text-input" << 10;

will print:

  One (1), two and a half (2.5), text (text-input)

and ignore the input 10.

If there are fewer inputs in the '<<' sequence, then the formatting occurs until the '' sequence that follows the last input object, and stops there. For example,

std::cout << cmnPrintf("One (%d), two and a half (%f), text (%s)")
          << 1 << 2.5;

will print:

  One (1), two and a half (2.5), text(

Default formatting is provided for the types double ("%f"), int ("%d") and const char * ("%s"). Other basic types are automatically converted by the compiler to one of these and printed. However, the model can be extended to include more output types. See the documentation of cmnPrintfParser for more information.

Note that special ios manipulators and functions, such as endl, flush, setw, setprecision, etc., have no '' sequence, and therefore CANNOT be used with with cmnPrintf. To print a newline (without flush), one may, for example, include a '
' character in the format stream, as done with the C printf function. To flush, a flush method must be called outside of the cmnPrintf expression.

cmnPrintf is stateless, which means that it does not affect any of the state variables in the output stream, such as width, precision, etc. All the output is done through conversion to character strings.

The allocated space for each output element is defined in #cmnPrintfParser::BUFFER_SIZE. If the length of the formatted element is larger than this number, then the output is truncated, and the text '(truncated)' is appended following the first BUFFER_SIZE characters. Unfortunately, there is no standard way to compute the length of a formatted string (snprintf is not portable to Visual Studio), and hence to way for our code to know how much memory to allocate for the result of the formatting.

Implementation-wise, this is a dummy class that just stores a copy of the format string. The real work is done by a cmnPrintfParser object which is returned from operator <<.

The expression

std::cout << cmnPrintf("something")

creates a cmnPrintf object, which is streamed into std::cout. The result of the expression is an invisible cmnPrintfParser object, into which all the following elements are streamed. The cmnPrintfParser object parses the format string, formats the streamed objects, and forwards the formatted result to std::cout. */ class CISST_EXPORT cmnPrintf { public: /*! Create a cmnPrintf object and provide a format string following the printf specification. The cmnPrintf object stores a copy of the format string.

cmnThrow()

template<class _exceptionType>

void cmnThrow ( const _exceptionType & except, cmnLogLevel lod = CMN_LOG_LEVEL_INIT_ERROR )

inline

Throw an exception. This templated function should be used to throw any exception.

One of the advantages of this function over the default throw is that if the exception is of type std::exception, the message is logged (using the what method).
This function attempts to dynamically cast the exception. If the cast succeeds, the cmnThrow will log the message using CMN_LOG (level of detail). If the cast fails, cmnThrow will log a less informative message anyway.
Once the message has been logged, cmnThrow simply uses throw to throw the exception.

Using this function systematically within the cisst packages also allows some system wide configuration:

• In some special cases such as real-time programming, exceptions can be somewhat impractical. If the variable CISST_CMN_THROW_DOES_ABORT is defined at compilation time, cmnThrow doesn't throw an exception but uses the abort function. This is a very special case and the vast majority of users should not use this option.
  Using the CMake advanced mode, it is possible to define CISST_CMN_THROW_DOES_ABORT for the whole cisst package. It is important to note that this option will break many of the cisst package tests programs (tests based on try and catch).

• This function might be used later on to provide a nice debug breakpoint. Indeed, cmnThrow is called before the exception is actually throw and the stack unwinding.

See also

CMN_ASSERT

Note

The type of exception thrown would ideally derived from std::exception but this is not a requirement.