ERC CISST - cisst software

---

Common Tools

---

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.

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>

Files

• file cmnConstants.h

  Declaration of various constants.
  

• file cmnLogger.h

  Declaration of cmnLogger amd macros for human readable logging.
  

• file cmnLogLoD.h

  Declaration of Levels of Detail for cmnLogger (human readable logging).
  

• file cmnPath.h

  Declaration of cmnPath.
  

• file cmnPortability.h

  Portability across compilers and operating systems tools.
  

• file cmnPrintf.h

  Declaration of cmnPrintf and cmnPrintfParser.
  

• file cmnRequiresDeepCopy.h

  Declaration of cmnRequiresDeepCopy.
  

• file cmnUnits.h

  Declaration of units and unit conversion methods.
  

Classes

• class cmnClassRegister

  Main register for classes. 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 cmnPrintf

  printf-like formatted output for streams More...
  

• class cmnPrintfParser

  Parser for cmnPrintf. 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...
  

Defines

• #define CMN_ASSERT(expr)

Functions

• int cmn_snprintf (char *destination, size_t size, const char *format,...)
• template<class _exceptionType> void cmnThrow (const _exceptionType &except, cmnLogLoD lod=CMN_LOG_LOD_INIT_ERROR) throw (_exceptionType)

---

Define Documentation

#define CMN_ASSERT

(

expr

)

Value:

if (!(expr)) { \
        std::stringstream messageBuffer; \
        messageBuffer << __FILE__ << ": Assertion '" << #expr \
                      << "' failed in: " << CMN_PRETTY_FUNCTION \
                      << ", line #" << __LINE__; \
        std::cerr << messageBuffer.str() << std::endl; \
        CMN_LOG_INIT_ERROR << messageBuffer.str() << std::endl; \
        abort(); \
    }

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 CMN_ASSERT_DISABLED and 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.

See also:

cmnThrow

Definition at line 131 of file cmnAssert.h.

Referenced by mtsQueueGeneric::Allocate(), vctQuaternionRotation3Base< vctFixedSizeVector< double, 4 > >::ApplyInverseTo(), vctMatrixRotation3ConstBase< vctFixedSizeMatrix< double, 3, 3, _rowMajor > >::ApplyInverseTo(), vctMatrixRotation2Base< vctFixedSizeMatrix< _elementType, 2, 2 > >::ApplyInverseTo(), vctFrameBase< _rotationType >::ApplyInverseTo(), vctQuaternionRotation3Base< vctFixedSizeVector< double, 4 > >::ApplyTo(), vctMatrixRotation3ConstBase< vctFixedSizeMatrix< double, 3, 3, _rowMajor > >::ApplyTo(), vctMatrixRotation2Base< vctFixedSizeMatrix< _elementType, 2, 2 > >::ApplyTo(), vctFrameBase< _rotationType >::ApplyTo(), mtsStateArray< mtsGenericObjectProxyFinalType >::Create(), vctFixedSizeVectorBase< _size, 1, svlPoint2D, vctFixedSizeVectorTraits< svlPoint2D, _size, 1 >::array >::CrossProductOf(), vctDynamicVectorBase< vctDynamicVectorOwner< svlFilterSourceVideoCapture::_ImageFormat >, svlFilterSourceVideoCapture::_ImageFormat >::CrossProductOf(), vctMatrixRotation3Base< vctFixedSizeMatrix< double, 3, 3, _rowMajor > >::FromRaw(), vctMatrixRotation2Base< vctFixedSizeMatrix< _elementType, 2, 2 > >::FromRaw(), vctMatrixRotation3Base< vctFixedSizeMatrix< double, 3, 3, _rowMajor > >::InverseOf(), mtsCommandWriteGeneric< _classType >::mtsCommandWriteGeneric(), mtsQueueGeneric::mtsQueueGeneric(), nmrInverse(), nmrLSqLin(), nmrLU(), nmrPInverse(), nmrSVD(), vctQuaternionRotation3Base< vctFixedSizeVector< double, 4 > >::NormalizedOf(), vctMatrixRotation3Base< vctFixedSizeMatrix< double, 3, 3, _rowMajor > >::NormalizedOf(), vctQuaternionRotation3Base< vctFixedSizeVector< double, 4 > >::operator *(), nmrMultiVariablePowerBasis::SetImplicitVarIndex(), nmrMultiVariablePowerBasis::SetVariable(), vctDynamicNArrayRef< _elementType, _dimension >::SubarrayOf(), vctDynamicConstNArrayRef< _elementType, _dimension >::SubarrayOf(), vctFixedSizeMatrix< double, 4, 4, _rowMajor >::vctFixedSizeMatrix(), vctFixedSizeVector< svlImageProcessing::Internals, SVL_MAX_CHANNELS >::vctFixedSizeVector(), vctFixedStrideMatrixConstIterator< _elementType, _columnStride, _numColumns, _rowStride >::vctFixedStrideMatrixConstIterator(), vctFixedSizeVectorBase< _size, 1, svlPoint2D, vctFixedSizeVectorTraits< svlPoint2D, _size, 1 >::array >::W(), vctFixedSizeConstVectorBase< _size, _stride, int, vctFixedSizeVectorTraits< int, _size, 1 >::array >::W(), vctDynamicVectorBase< vctDynamicVectorOwner< svlFilterSourceVideoCapture::_ImageFormat >, svlFilterSourceVideoCapture::_ImageFormat >::W(), vctDynamicConstVectorBase< vctDynamicVectorOwner< svlFilterSourceVideoCapture::_ImageFormat >, svlFilterSourceVideoCapture::_ImageFormat >::W(), vctFixedSizeVectorBase< _size, 1, svlPoint2D, vctFixedSizeVectorTraits< svlPoint2D, _size, 1 >::array >::X(), vctFixedSizeConstVectorBase< _size, _stride, int, vctFixedSizeVectorTraits< int, _size, 1 >::array >::X(), vctDynamicVectorBase< vctDynamicVectorOwner< svlFilterSourceVideoCapture::_ImageFormat >, svlFilterSourceVideoCapture::_ImageFormat >::X(), vctDynamicConstVectorBase< vctDynamicVectorOwner< svlFilterSourceVideoCapture::_ImageFormat >, svlFilterSourceVideoCapture::_ImageFormat >::X(), vctFixedSizeVectorBase< _size, 1, svlPoint2D, vctFixedSizeVectorTraits< svlPoint2D, _size, 1 >::array >::XW(), vctFixedSizeConstVectorBase< _size, _stride, int, vctFixedSizeVectorTraits< int, _size, 1 >::array >::XW(), vctDynamicVectorBase< vctDynamicVectorOwner< svlFilterSourceVideoCapture::_ImageFormat >, svlFilterSourceVideoCapture::_ImageFormat >::XW(), vctDynamicConstVectorBase< vctDynamicVectorOwner< svlFilterSourceVideoCapture::_ImageFormat >, svlFilterSourceVideoCapture::_ImageFormat >::XW(), vctFixedSizeVectorBase< _size, 1, svlPoint2D, vctFixedSizeVectorTraits< svlPoint2D, _size, 1 >::array >::XY(), vctFixedSizeConstVectorBase< _size, _stride, int, vctFixedSizeVectorTraits< int, _size, 1 >::array >::XY(), vctDynamicVectorBase< vctDynamicVectorOwner< svlFilterSourceVideoCapture::_ImageFormat >, svlFilterSourceVideoCapture::_ImageFormat >::XY(), vctDynamicConstVectorBase< vctDynamicVectorOwner< svlFilterSourceVideoCapture::_ImageFormat >, svlFilterSourceVideoCapture::_ImageFormat >::XY(), vctFixedSizeVectorBase< _size, 1, svlPoint2D, vctFixedSizeVectorTraits< svlPoint2D, _size, 1 >::array >::XYZ(), vctFixedSizeConstVectorBase< _size, _stride, int, vctFixedSizeVectorTraits< int, _size, 1 >::array >::XYZ(), vctDynamicVectorBase< vctDynamicVectorOwner< svlFilterSourceVideoCapture::_ImageFormat >, svlFilterSourceVideoCapture::_ImageFormat >::XYZ(), vctDynamicConstVectorBase< vctDynamicVectorOwner< svlFilterSourceVideoCapture::_ImageFormat >, svlFilterSourceVideoCapture::_ImageFormat >::XYZ(), vctFixedSizeVectorBase< _size, 1, svlPoint2D, vctFixedSizeVectorTraits< svlPoint2D, _size, 1 >::array >::XYZW(), vctFixedSizeConstVectorBase< _size, _stride, int, vctFixedSizeVectorTraits< int, _size, 1 >::array >::XYZW(), vctDynamicVectorBase< vctDynamicVectorOwner< svlFilterSourceVideoCapture::_ImageFormat >, svlFilterSourceVideoCapture::_ImageFormat >::XYZW(), vctDynamicConstVectorBase< vctDynamicVectorOwner< svlFilterSourceVideoCapture::_ImageFormat >, svlFilterSourceVideoCapture::_ImageFormat >::XYZW(), vctFixedSizeVectorBase< _size, 1, svlPoint2D, vctFixedSizeVectorTraits< svlPoint2D, _size, 1 >::array >::XZ(), vctFixedSizeConstVectorBase< _size, _stride, int, vctFixedSizeVectorTraits< int, _size, 1 >::array >::XZ(), vctDynamicVectorBase< vctDynamicVectorOwner< svlFilterSourceVideoCapture::_ImageFormat >, svlFilterSourceVideoCapture::_ImageFormat >::XZ(), vctDynamicConstVectorBase< vctDynamicVectorOwner< svlFilterSourceVideoCapture::_ImageFormat >, svlFilterSourceVideoCapture::_ImageFormat >::XZ(), vctFixedSizeVectorBase< _size, 1, svlPoint2D, vctFixedSizeVectorTraits< svlPoint2D, _size, 1 >::array >::Y(), vctFixedSizeConstVectorBase< _size, _stride, int, vctFixedSizeVectorTraits< int, _size, 1 >::array >::Y(), vctDynamicVectorBase< vctDynamicVectorOwner< svlFilterSourceVideoCapture::_ImageFormat >, svlFilterSourceVideoCapture::_ImageFormat >::Y(), vctDynamicConstVectorBase< vctDynamicVectorOwner< svlFilterSourceVideoCapture::_ImageFormat >, svlFilterSourceVideoCapture::_ImageFormat >::Y(), vctFixedSizeVectorBase< _size, 1, svlPoint2D, vctFixedSizeVectorTraits< svlPoint2D, _size, 1 >::array >::YW(), vctFixedSizeConstVectorBase< _size, _stride, int, vctFixedSizeVectorTraits< int, _size, 1 >::array >::YW(), vctDynamicVectorBase< vctDynamicVectorOwner< svlFilterSourceVideoCapture::_ImageFormat >, svlFilterSourceVideoCapture::_ImageFormat >::YW(), vctDynamicConstVectorBase< vctDynamicVectorOwner< svlFilterSourceVideoCapture::_ImageFormat >, svlFilterSourceVideoCapture::_ImageFormat >::YW(), vctFixedSizeVectorBase< _size, 1, svlPoint2D, vctFixedSizeVectorTraits< svlPoint2D, _size, 1 >::array >::YZ(), vctFixedSizeConstVectorBase< _size, _stride, int, vctFixedSizeVectorTraits< int, _size, 1 >::array >::YZ(), vctDynamicVectorBase< vctDynamicVectorOwner< svlFilterSourceVideoCapture::_ImageFormat >, svlFilterSourceVideoCapture::_ImageFormat >::YZ(), vctDynamicConstVectorBase< vctDynamicVectorOwner< svlFilterSourceVideoCapture::_ImageFormat >, svlFilterSourceVideoCapture::_ImageFormat >::YZ(), vctFixedSizeVectorBase< _size, 1, svlPoint2D, vctFixedSizeVectorTraits< svlPoint2D, _size, 1 >::array >::YZW(), vctFixedSizeConstVectorBase< _size, _stride, int, vctFixedSizeVectorTraits< int, _size, 1 >::array >::YZW(), vctDynamicVectorBase< vctDynamicVectorOwner< svlFilterSourceVideoCapture::_ImageFormat >, svlFilterSourceVideoCapture::_ImageFormat >::YZW(), vctDynamicConstVectorBase< vctDynamicVectorOwner< svlFilterSourceVideoCapture::_ImageFormat >, svlFilterSourceVideoCapture::_ImageFormat >::YZW(), vctFixedSizeVectorBase< _size, 1, svlPoint2D, vctFixedSizeVectorTraits< svlPoint2D, _size, 1 >::array >::Z(), vctFixedSizeConstVectorBase< _size, _stride, int, vctFixedSizeVectorTraits< int, _size, 1 >::array >::Z(), vctDynamicVectorBase< vctDynamicVectorOwner< svlFilterSourceVideoCapture::_ImageFormat >, svlFilterSourceVideoCapture::_ImageFormat >::Z(), vctDynamicConstVectorBase< vctDynamicVectorOwner< svlFilterSourceVideoCapture::_ImageFormat >, svlFilterSourceVideoCapture::_ImageFormat >::Z(), vctFixedSizeVectorBase< _size, 1, svlPoint2D, vctFixedSizeVectorTraits< svlPoint2D, _size, 1 >::array >::ZW(), vctFixedSizeConstVectorBase< _size, _stride, int, vctFixedSizeVectorTraits< int, _size, 1 >::array >::ZW(), vctDynamicVectorBase< vctDynamicVectorOwner< svlFilterSourceVideoCapture::_ImageFormat >, svlFilterSourceVideoCapture::_ImageFormat >::ZW(), and vctDynamicConstVectorBase< vctDynamicVectorOwner< svlFilterSourceVideoCapture::_ImageFormat >, svlFilterSourceVideoCapture::_ImageFormat >::ZW().

---

Function Documentation

template<class _exceptionType>

void cmnThrow	(	const _exceptionType &	except,
		cmnLogLoD	lod = CMN_LOG_LOD_INIT_ERROR
	)			throw (_exceptionType) [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 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 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.

Definition at line 77 of file cmnThrow.h.

References CMN_LOG.

Referenced by nmrLSqLinSolutionDynamic::Allocate(), vctFixedSizeVectorBase< _size, 1, svlPoint2D, vctFixedSizeVectorTraits< svlPoint2D, _size, 1 >::array >::Assign(), vctDynamicVectorBase< vctDynamicVectorOwner< svlFilterSourceVideoCapture::_ImageFormat >, svlFilterSourceVideoCapture::_ImageFormat >::Assign(), cmnDeSerializeRaw(), cmnDeSerializeSizeRaw(), cmnSerializeRaw(), cmnThrow(), vctDynamicVectorRef< CISSTNETLIB_DOUBLE >::DeSerializeRaw(), vctDynamicMatrixRef< CISSTNETLIB_DOUBLE >::DeSerializeRaw(), vctRodriguezRotation3Base< vctFixedSizeVector< _elementType, 3 > >::FromRaw(), nmrLUSolver::GetL(), nmrLUSolver::GetP(), nmrLUSolver::GetU(), nmrInverse(), nmrIsOrthonormal(), nmrLSqLin(), nmrLU(), nmrNNLS(), nmrPInverse(), nmrPInverseEconomy(), nmrSVD(), nmrSVDEconomy(), vctFixedSizeVectorBase< _size, 1, svlPoint2D, vctFixedSizeVectorTraits< svlPoint2D, _size, 1 >::array >::NormalizedSelf(), vctDynamicVectorBase< vctDynamicVectorOwner< svlFilterSourceVideoCapture::_ImageFormat >, svlFilterSourceVideoCapture::_ImageFormat >::NormalizedSelf(), vctDynamicMatrixBase< vctDynamicMatrixOwner< float >, float >::RowPointers(), vctDynamicConstMatrixBase< vctDynamicMatrixOwner< float >, float >::RowPointers(), vctFixedSizeVectorRef< _elementType, _size, _stride >::SetRef(), vctFixedSizeMatrixRef< _elementType, 3, 3, _rowStride, _colStride >::SetRef(), vctFixedSizeConstVectorRef< _elementType, _size, _stride >::SetRef(), vctFixedSizeConstMatrixRef< _elementType, 3, 3, _rowStride, _colStride >::SetRef(), vctDynamicVectorRef< CISSTNETLIB_DOUBLE >::SetRef(), vctDynamicMatrixRef< CISSTNETLIB_DOUBLE >::SetRef(), vctDynamicConstVectorRef< _elementType >::SetRef(), vctDynamicConstMatrixRef< _elementType >::SetRef(), nmrLSqLinSolutionDynamic::SetRef(), nmrSVDSolver::Solve(), nmrSVDRSSolver::Solve(), nmrNNLSSolver::Solve(), nmrLUSolver::Solve(), nmrLSSolver::Solve(), nmrLSNonLinSolver::Solve(), nmrLSNonLinJacobianSolver::Solve(), nmrLSEISolver::Solve(), nmrHFTISolver::Solve(), nmrFnSolver::Solve(), nmrFnJacobianSolver::Solve(), nmrFminSolver::Solve(), vctDynamicVectorLoopEngines::ThrowException(), vctFixedSizeMatrixLoopEngines::ThrowSharedPointersException(), vctDynamicMatrixLoopEngines::ThrowSharedPointersException(), vctDynamicNArrayLoopEngines< _dimension >::ThrowSizeMismatchException(), vctDynamicMatrixLoopEngines::ThrowSizeMismatchException(), vctRodriguezRotation3Base< vctFixedSizeVector< _elementType, 3 > >::ThrowUnlessIsNormalized(), vctQuaternionRotation3Base< vctFixedSizeVector< double, 4 > >::ThrowUnlessIsNormalized(), vctMatrixRotation3ConstBase< vctFixedSizeMatrix< double, 3, 3, _rowMajor > >::ThrowUnlessIsNormalized(), vctMatrixRotation2Base< vctFixedSizeMatrix< _elementType, 2, 2 > >::ThrowUnlessIsNormalized(), vctAxisAngleRotation3< _elementType >::ThrowUnlessIsNormalized(), vctAngleRotation2::ThrowUnlessIsNormalized(), nmrSVDEconomyDynamicData::ThrowUnlessOutputSizeIsCorrect(), nmrSVDDynamicData::ThrowUnlessOutputSizeIsCorrect(), nmrPInverseEconomyDynamicData::ThrowUnlessOutputSizeIsCorrect(), nmrPInverseDynamicData::ThrowUnlessOutputSizeIsCorrect(), nmrNNLSDynamicData::ThrowUnlessOutputSizeIsCorrect(), nmrLUDynamicData::ThrowUnlessOutputSizeIsCorrect(), nmrInverseDynamicData::ThrowUnlessPivotIndicesSizeIsCorrect(), vctDynamicConstMatrixBase< vctDynamicMatrixOwner< float >, float >::ThrowUnlessValidColIndex(), vctFastCopy::ThrowUnlessValidContainerSizes(), vctDynamicConstNArrayBase< vctDynamicNArrayRefOwner< _elementType, _dimension >, _elementType, _dimension >::ThrowUnlessValidDimensionIndex(), vctFixedSizeConstVectorBase< _size, _stride, int, vctFixedSizeVectorTraits< int, _size, 1 >::array >::ThrowUnlessValidIndex(), vctDynamicConstVectorBase< vctDynamicVectorOwner< svlFilterSourceVideoCapture::_ImageFormat >, svlFilterSourceVideoCapture::_ImageFormat >::ThrowUnlessValidIndex(), vctDynamicConstNArrayBase< vctDynamicNArrayRefOwner< _elementType, _dimension >, _elementType, _dimension >::ThrowUnlessValidIndex(), vctDynamicConstMatrixBase< vctDynamicMatrixOwner< float >, float >::ThrowUnlessValidIndex(), vctDynamicConstMatrixBase< vctDynamicMatrixOwner< float >, float >::ThrowUnlessValidRowIndex(), vctFastCopy::ThrowUnlessValidVectorSizes(), nmrSVDEconomyDynamicData::ThrowUnlessWorkspaceSizeIsCorrect(), nmrSVDDynamicData::ThrowUnlessWorkspaceSizeIsCorrect(), nmrPInverseEconomyDynamicData::ThrowUnlessWorkspaceSizeIsCorrect(), nmrPInverseDynamicData::ThrowUnlessWorkspaceSizeIsCorrect(), nmrIsOrthonormalDynamicData< _elementType >::ThrowUnlessWorkspaceSizeIsCorrect(), nmrInverseDynamicData::ThrowUnlessWorkspaceSizeIsCorrect(), nmrNNLSDynamicData::ThrowUnlessWorkspacesSizeIsCorrect(), nmrLUDynamicData::UpdateMatrixP(), nmrSVDEconomyDynamicData::UpdateMatrixS(), nmrSVDDynamicData::UpdateMatrixS(), and vctDynamicVector< svlSample * >::vctDynamicVector().

---