SimTKcommon/include/SimTKcommon/internal/common.h File Reference

Mandatory first inclusion for any Simbody source or header file. More...

Go to the source code of this file.

Classes
class	SimTK::Vec< M, ELT, STRIDE >
	This is a fixed-length column vector designed for no-overhead inline computation. More...
class	SimTK::Row< N, ELT, STRIDE >
	This is a fixed-length row vector designed for no-overhead inline computation. More...
class	SimTK::Mat< M, N, ELT, CS, RS >
	This class represents a small matrix whose size is known at compile time, containing elements of any Composite Numerical Type (CNT) and engineered to have no runtime overhead whatsoever. More...
class	SimTK::SymMat< M, ELT, RS >
	This is a small, fixed-size symmetric or Hermitian matrix designed for no-overhead inline computation. More...
struct	SimTK::Segment
	A convenient struct for anything requiring an offset and length to specify a segment of some larger sequence. More...
struct	SimTK::DontCopy
	This is a special type used for causing invocation of a particular constructor or method overload that will avoid making a copy of the source (that is, perform a "shallow" copy rather than a "deep" copy). More...
struct	SimTK::TrustMe
	This is a special type used for forcing invocation of a particularly dangerous constructor or method overload; don't use this unless you are an advanced user and know exactly what you're getting into. More...
struct	SimTK::FalseType
	This is a compile-time equivalent of "false", used in compile-time condition checking in templatized implementations. More...
struct	SimTK::TrueType
	This is a compile-time equivalent of "true", used in compile-time condition checking in templatized implementations. More...
struct	SimTK::AndOpType< L, R >
	This is an operator for and-ing compile-time truth types. More...
struct	SimTK::AndOpType< FalseType, FalseType >
struct	SimTK::AndOpType< FalseType, TrueType >
struct	SimTK::AndOpType< TrueType, FalseType >
struct	SimTK::AndOpType< TrueType, TrueType >
struct	SimTK::OrOpType< L, R >
	This is an operator for or-ing compile-time truth types. More...
struct	SimTK::OrOpType< FalseType, FalseType >
struct	SimTK::OrOpType< FalseType, TrueType >
struct	SimTK::OrOpType< TrueType, FalseType >
struct	SimTK::OrOpType< TrueType, TrueType >
struct	SimTK::XorOpType< L, R >
	This is an operator for exclusive or-ing compile-time truth types. More...
struct	SimTK::XorOpType< FalseType, FalseType >
struct	SimTK::XorOpType< FalseType, TrueType >
struct	SimTK::XorOpType< TrueType, FalseType >
struct	SimTK::XorOpType< TrueType, TrueType >
struct	SimTK::IsIntegralType< T >
	Compile-time type test: is this one of the built-in integral types?. More...
struct	SimTK::IsFloatingType< T >
	Compile-time type test: is this one of the built-in floating point types?. More...
struct	SimTK::IsVoidType< T >
	Compile-time type test: is this the void type?. More...
struct	SimTK::IsVoidType< void >
struct	SimTK::IsArithmeticType< T >
	Compile-time test: is this one of the built-in "arithmetic" types, meaning an integral or floating type? More...
struct	SimTK::Is64BitHelper< is64Bit >
struct	SimTK::Is64BitHelper< true >
struct	SimTK::Is64BitHelper< false >
struct	SimTK::NiceTypeName< T >
	In case you don't like the name you get from typeid(), you can specialize this class to provide a nicer name. More...

Namespaces
	SimTK
	This is the top-level SimTK namespace into which all SimTK names are placed to avoid collision with other symbols.
	SimTK::Exception
	This sub-namespace of SimTK is used for the exception types that are thrown by our error handing code.

Macros
#define	SimTK_DEFAULT_PRECISION   2
	This compile-time constant determines the default precision used everywhere in SimTK Core code. More...
#define	SimTK_DEBUG(s)   std::printf("DBG: " s)
#define	SimTK_DEBUG1(s, a1)   std::printf("DBG: " s,a1)
#define	SimTK_DEBUG2(s, a1, a2)   std::printf("DBG: " s,a1,a2)
#define	SimTK_DEBUG3(s, a1, a2, a3)   std::printf("DBG: " s,a1,a2,a3)
#define	SimTK_DEBUG4(s, a1, a2, a3, a4)   std::printf("DBG: " s,a1,a2,a3,a4)
#define	SimTK_SimTKCOMMON_EXPORT
#define	OVERRIDE_11
#define	FINAL_11
#define	SimTK_FORCE_INLINE   __attribute__((always_inline))
#define	SimTK_DEFINE_UNIQUE_INDEX_TYPE(NAME)
	Use this macro to define a unique "Index" type which is just a type-safe non-negative int, augmented with a "NaN" value given by the predefined int constant SimTK::InvalidIndex. More...
#define	SimTK_DEFINE_AND_EXPORT_UNIQUE_INDEX_TYPE(EXPORT, NAME)
	Define a global (that is, SimTK namespace level) Index class with a MS VC++ "export" specification for DLLs. More...
#define	SimTK_DEFINE_UNIQUE_LOCAL_INDEX_TYPE(PARENT, NAME)   SimTK_DEFINE_AND_EXPORT_UNIQUE_LOCAL_INDEX_TYPE(,PARENT,::,NAME)
	Define a local Index class within a Parent class. More...
#define	SimTK_DEFINE_AND_EXPORT_UNIQUE_LOCAL_INDEX_TYPE(EXPORT, PARENT, SEP, NAME)
	The most general form allows a MS VC++ "export" specification for DLLs, and a Parent class (with SEP=::) for local Index names. More...
#define	SimTK_DYNAMIC_CAST_DEBUG   dynamic_cast
	Use this macro to generate a cast that is dynamic_cast in Debug builds but static_cast in Release builds, for uses where you don't want to pay for the extra safety. More...
#define	SimTK_DOWNCAST(Derived, Parent)
	Add public static method declaration in class derived from an abstract parent to assist in downcasting objects of the parent type to the derived type. More...
#define	SimTK_DOWNCAST2(Derived, Helper, Parent)
	This is like SimTK_DOWNCAST except it allows for an intermediate "helper" class between Derived and Parent. More...
#define	SimTK_PIMPL_DOWNCAST(Derived, Parent)
	Similar to the above but for private implementation abstract classes, that is, abstract class hierarchies where the virtual function table is hidden on the library side. More...
#define	SimTK_SPECIALIZE_INTEGRAL_TYPE(T)
	This macro must be invoked once for each of the built-in integral types to specialize the IsIntegralType struct template for those types. More...
#define	SimTK_SPECIALIZE_FLOATING_TYPE(T)
	This macro must be invoked once for each of the built-in floating point types to specialize the IsFloatingType struct template for those types. More...
#define	SimTK_NICETYPENAME_LITERAL(T)
	This specializes the name of a type to be exactly the text you use to specify it, rather than whatever ugly thing might result on different platforms from resolution of typedefs, default template arguments, etc. More...

Typedefs
typedef double	SimTK_Real
	This type is for use in C; in C++ use SimTK::Real instead. More...
typedef SimTK_Real	SimTK::Real
	This is the default compiled-in floating point type for SimTK, either float or double. More...
typedef std::complex< Real >	SimTK::Complex
	This is the default complex type for SimTK, with precision for the real and imaginary parts set to the compiled-in Real type. More...
typedef std::complex< float >	SimTK::fComplex
	An abbreviation for std::complex<float> for consistency with others. More...
typedef std::complex< double >	SimTK::dComplex
	An abbreviation for std::complex<double> for consistency with others. More...
typedef Is64BitHelper < Is64BitPlatform >::Result	SimTK::Is64BitPlatformType

Functions
void	SimTK_version_SimTKcommon (int *major, int *minor, int *build)
	Obtain version information for the currently-loaded SimTKcommon library. More...
void	SimTK_about_SimTKcommon (const char *key, int maxlen, char *value)
	Obtain "about" information for the currently-loaded SimTKcommon library. More...
bool	SimTK::canStoreInInt (bool)
bool	SimTK::canStoreInInt (char)
bool	SimTK::canStoreInInt (unsigned char)
bool	SimTK::canStoreInInt (signed char)
bool	SimTK::canStoreInInt (short)
bool	SimTK::canStoreInInt (int)
bool	SimTK::canStoreInInt (unsigned int u)
bool	SimTK::canStoreInInt (long i)
bool	SimTK::canStoreInInt (unsigned long u)
bool	SimTK::canStoreInInt (long long i)
bool	SimTK::canStoreInInt (unsigned long long u)
bool	SimTK::canStoreInNonnegativeInt (bool)
bool	SimTK::canStoreInNonnegativeInt (char c)
bool	SimTK::canStoreInNonnegativeInt (unsigned char)
bool	SimTK::canStoreInNonnegativeInt (signed char c)
bool	SimTK::canStoreInNonnegativeInt (short s)
bool	SimTK::canStoreInNonnegativeInt (unsigned short)
bool	SimTK::canStoreInNonnegativeInt (int i)
bool	SimTK::canStoreInNonnegativeInt (long l)
bool	SimTK::canStoreInNonnegativeInt (long long l)
bool	SimTK::canStoreInNonnegativeInt (unsigned int u)
bool	SimTK::canStoreInNonnegativeInt (unsigned long u)
bool	SimTK::canStoreInNonnegativeInt (unsigned long long u)
bool	SimTK::isSizeInRange (char sz, char mx)
bool	SimTK::isSizeInRange (signed char sz, signed char mx)
bool	SimTK::isSizeInRange (short sz, short mx)
bool	SimTK::isSizeInRange (int sz, int mx)
bool	SimTK::isSizeInRange (long sz, long mx)
bool	SimTK::isSizeInRange (long long sz, long long mx)
bool	SimTK::isSizeInRange (unsigned char sz, unsigned char mx)
bool	SimTK::isSizeInRange (unsigned short sz, unsigned short mx)
bool	SimTK::isSizeInRange (unsigned int sz, unsigned int mx)
bool	SimTK::isSizeInRange (unsigned long sz, unsigned long mx)
bool	SimTK::isSizeInRange (unsigned long long sz, unsigned long long mx)
bool	SimTK::isIndexInRange (char ix, char sz)
bool	SimTK::isIndexInRange (signed char ix, signed char sz)
bool	SimTK::isIndexInRange (short ix, short sz)
bool	SimTK::isIndexInRange (int ix, int sz)
bool	SimTK::isIndexInRange (long ix, long sz)
bool	SimTK::isIndexInRange (long long ix, long long sz)
bool	SimTK::isIndexInRange (unsigned char ix, unsigned char sz)
bool	SimTK::isIndexInRange (unsigned short ix, unsigned short sz)
bool	SimTK::isIndexInRange (unsigned int ix, unsigned int sz)
bool	SimTK::isIndexInRange (unsigned long ix, unsigned long sz)
bool	SimTK::isIndexInRange (unsigned long long ix, unsigned long long sz)
bool	SimTK::isNonnegative (bool)
bool	SimTK::isNonnegative (char n)
bool	SimTK::isNonnegative (signed char n)
bool	SimTK::isNonnegative (short n)
bool	SimTK::isNonnegative (int n)
bool	SimTK::isNonnegative (long n)
bool	SimTK::isNonnegative (long long n)
bool	SimTK::isNonnegative (unsigned char)
bool	SimTK::isNonnegative (unsigned short)
bool	SimTK::isNonnegative (unsigned long)
bool	SimTK::isNonnegative (unsigned long long)
	SimTK::SimTK_SPECIALIZE_INTEGRAL_TYPE (bool)
	SimTK::SimTK_SPECIALIZE_INTEGRAL_TYPE (char)
	SimTK::SimTK_SPECIALIZE_INTEGRAL_TYPE (signed char)
	SimTK::SimTK_SPECIALIZE_INTEGRAL_TYPE (unsigned char)
	SimTK::SimTK_SPECIALIZE_INTEGRAL_TYPE (short)
	SimTK::SimTK_SPECIALIZE_INTEGRAL_TYPE (int)
	SimTK::SimTK_SPECIALIZE_INTEGRAL_TYPE (long)
	SimTK::SimTK_SPECIALIZE_INTEGRAL_TYPE (unsigned long long)
	SimTK::SimTK_SPECIALIZE_FLOATING_TYPE (float)
	SimTK::SimTK_SPECIALIZE_FLOATING_TYPE (double)
	SimTK::SimTK_SPECIALIZE_FLOATING_TYPE (long double)
std::string	SimTK::demangle (const char *name)
	Attempt to demangle a type name as returned by typeid.name(), with the result hopefully suitable for meaningful display to a human. More...
	SimTK_NICETYPENAME_LITERAL (bool)
	SimTK_NICETYPENAME_LITERAL (char)
	SimTK_NICETYPENAME_LITERAL (signed char)
	SimTK_NICETYPENAME_LITERAL (unsigned char)
	SimTK_NICETYPENAME_LITERAL (short)
	SimTK_NICETYPENAME_LITERAL (int)
	SimTK_NICETYPENAME_LITERAL (long)
	SimTK_NICETYPENAME_LITERAL (unsigned long long)
	SimTK_NICETYPENAME_LITERAL (float)
	SimTK_NICETYPENAME_LITERAL (double)
	SimTK_NICETYPENAME_LITERAL (long double)
	SimTK_NICETYPENAME_LITERAL (std::string)
	SimTK_NICETYPENAME_LITERAL (std::complex< float >)
	SimTK_NICETYPENAME_LITERAL (std::complex< double >)
	SimTK_NICETYPENAME_LITERAL (std::complex< long double >)
	SimTK_NICETYPENAME_LITERAL (SimTK::FalseType)
	SimTK_NICETYPENAME_LITERAL (SimTK::TrueType)

Variables
static const int	SimTK::InvalidIndex = -1111111111
static const bool	SimTK::Is64BitPlatform = sizeof(size_t) > sizeof(int)
	Compile-time test: this typedef will be TrueType if this is a 64-bit platform, meaning that the size of a pointer is the same as the size of a long long; otherwise it will be FalseType and we have a 32-bit platform meaning that the size of a pointer is the same as an int. More...

Detailed Description

Mandatory first inclusion for any Simbody source or header file.

Every source and most header files using SimTK must include this header as its first inclusion. Declarations and definitions that must be available and compiler-and machine-specific issues are dealt with here.

This file must be includable from either C++ or ANSI C. It uses the ANSI-C++ macro "__cplusplus" for any code that will compile only under C++.

Macro Definition Documentation

#define SimTK_DEFAULT_PRECISION   2

This compile-time constant determines the default precision used everywhere in SimTK Core code.

Wherever a SimTK::Real, SimTK::Vector, SimTK::Matrix, etc. appears with no precision specified, it will have this underlying precision. We use 1==float, 2==double, 4==long double. Any other value will cause a compile time error. The default is 2, i.e., double precision.

#define SimTK_DEBUG

(

s

)

std::printf("DBG: " s)

#define SimTK_DEBUG1	(		s,
			a1
	)		std::printf("DBG: " s,a1)

#define SimTK_DEBUG2	(		s,
			a1,
			a2
	)		std::printf("DBG: " s,a1,a2)

#define SimTK_DEBUG3	(		s,
			a1,
			a2,
			a3
	)		std::printf("DBG: " s,a1,a2,a3)

#define SimTK_DEBUG4	(		s,
			a1,
			a2,
			a3,
			a4
	)		std::printf("DBG: " s,a1,a2,a3,a4)

#define SimTK_SimTKCOMMON_EXPORT

#define OVERRIDE_11

#define FINAL_11

#define SimTK_FORCE_INLINE   __attribute__((always_inline))

#define SimTK_DEFINE_UNIQUE_INDEX_TYPE

(

NAME

)

Value:

SimTK_DEFINE_AND_EXPORT_UNIQUE_LOCAL_INDEX_TYPE(,,,NAME)   \
    static const NAME Invalid ## NAME;

Use this macro to define a unique "Index" type which is just a type-safe non-negative int, augmented with a "NaN" value given by the predefined int constant SimTK::InvalidIndex.

We also allow the Index to take on the value -1 if that is produced by a subtraction operation acting on a previously-valid Index, since that can occur during loops which are processed from the end towards the beginning. -1 is then allowed in comparision operators but not in any other operations, including further decrementing.

No namespace is assumed for the newly-defined type; if you want the symbol in a namespace be sure to invoke the macro within that namespace. Make sure that the statement "#include <cassert>" appears somewhere before the point of invocation of this macro, because the defined Index type uses the assert() macro when in Debug mode.

For most uses it will behave like an int, and it has an implicit conversion to int. Importantly though, it has no implicit conversion from int so you can't pass some other kind of number where a particular kind of Index was expected. This is used to create Index types which can be used as array indices but which prevent accidental mixing of types. Examples: SubsystemIndex, ConstraintIndex.

If you create a type "ThingIndex" you will also get a constant of type ThingIndex named "InvalidThingIndex" which will be the initial value of any objects of type ThingIndex, and will have the same numerical value as SimTK::InvalidIndex. Define a global (that is, SimTK namespace level) Index class that is not exported in MS VC++ DLLs.

#define SimTK_DEFINE_AND_EXPORT_UNIQUE_INDEX_TYPE	(		EXPORT,
			NAME
	)

Value:

SimTK_DEFINE_AND_EXPORT_UNIQUE_LOCAL_INDEX_TYPE(EXPORT,,,NAME) \
    static const NAME Invalid ## NAME;

Define a global (that is, SimTK namespace level) Index class with a MS VC++ "export" specification for DLLs.

#define SimTK_DEFINE_UNIQUE_LOCAL_INDEX_TYPE	(		PARENT,
			NAME
	)		SimTK_DEFINE_AND_EXPORT_UNIQUE_LOCAL_INDEX_TYPE(,PARENT,::,NAME)

Define a local Index class within a Parent class.

#define SimTK_DEFINE_AND_EXPORT_UNIQUE_LOCAL_INDEX_TYPE	(		EXPORT,
			PARENT,
			SEP,
			NAME
	)

The most general form allows a MS VC++ "export" specification for DLLs, and a Parent class (with SEP=::) for local Index names.

#define SimTK_DYNAMIC_CAST_DEBUG   dynamic_cast

Use this macro to generate a cast that is dynamic_cast in Debug builds but static_cast in Release builds, for uses where you don't want to pay for the extra safety.

Caution: these are not necessarily equivalent for dynamic types that use multiple inheritance; don't use this macro in that case, and don't use it where you are using dynamic_cast on a pointer to check what type of derived object you're looking at.

#define SimTK_DOWNCAST	(		Derived,
			Parent
	)

Value:

static bool isA(const Parent& p)                            \
        { return dynamic_cast<const Derived*>(&p) != 0; }       \
    static const Derived& downcast(const Parent& p)             \
        { return SimTK_DYNAMIC_CAST_DEBUG<const Derived&>(p); } \
    static Derived& updDowncast(Parent& p)                      \
        { return SimTK_DYNAMIC_CAST_DEBUG<Derived&>(p); }        \
    static Derived& downcast(Parent& p)                         \
        { return SimTK_DYNAMIC_CAST_DEBUG<Derived&>(p); }

Add public static method declaration in class derived from an abstract parent to assist in downcasting objects of the parent type to the derived type.

#define SimTK_DOWNCAST2	(		Derived,
			Helper,
			Parent
	)

Value:

static bool isA(const Parent& p)                                    \
        { return Helper::isA(p); }                                      \
    static const Derived& downcast(const Parent& p)                     \
        { return static_cast<const Derived&>(Helper::downcast(p)); }    \
    static Derived& updDowncast(Parent& p)                                \
        { return static_cast<Derived&>(Helper::downcast(p)); }            \
    static Derived& downcast(Parent& p)                                 \
        { return static_cast<Derived&>(Helper::downcast(p)); }

This is like SimTK_DOWNCAST except it allows for an intermediate "helper" class between Derived and Parent.

#define SimTK_PIMPL_DOWNCAST	(		Derived,
			Parent
	)

Value:

static bool           isInstanceOf(const Parent&);  \
    static const Derived& downcast(const Parent&);      \
    static Derived&       updDowncast(Parent&)

Similar to the above but for private implementation abstract classes, that is, abstract class hierarchies where the virtual function table is hidden on the library side.

#define SimTK_SPECIALIZE_INTEGRAL_TYPE

(

T

)

Value:

template<> struct IsIntegralType<T>         \
    {typedef TrueType Result; static const bool result = true;}

This macro must be invoked once for each of the built-in integral types to specialize the IsIntegralType struct template for those types.

#define SimTK_SPECIALIZE_FLOATING_TYPE

(

T

)

Value:

template<> struct IsFloatingType<T>         \
    {typedef TrueType Result; static const bool result = true;}

This macro must be invoked once for each of the built-in floating point types to specialize the IsFloatingType struct template for those types.

#define SimTK_NICETYPENAME_LITERAL

(

T

)

Value:

namespace SimTK {                                   \
    template <> struct NiceTypeName< T > {          \
        static std::string namestr() { return #T; } \
        static const char* name() { return #T; }    \
    };                                              \
}

This specializes the name of a type to be exactly the text you use to specify it, rather than whatever ugly thing might result on different platforms from resolution of typedefs, default template arguments, etc.

Note that this macro generates a template specialization that must be done in the SimTK namespace; consequently it opens and closes namespace SimTK and must not be invoked if you already have that namespace open.

Typedef Documentation

typedef double SimTK_Real

This type is for use in C; in C++ use SimTK::Real instead.

Function Documentation

void SimTK_version_SimTKcommon	(	int *	major,
		int *	minor,
		int *	build
	)

Obtain version information for the currently-loaded SimTKcommon library.

void SimTK_about_SimTKcommon	(	const char *	key,
		int	maxlen,
		char *	value
	)

Obtain "about" information for the currently-loaded SimTKcommon library.

Available keywords are "version" (major.minor.build), "library", "type" (shared or static), "copyright", "svn_revision", "authors", "debug" (debug or release).

SimTK_NICETYPENAME_LITERAL

(

bool

)

SimTK_NICETYPENAME_LITERAL

(

char

)

SimTK_NICETYPENAME_LITERAL

(

signed

char

)

SimTK_NICETYPENAME_LITERAL

(

unsigned

char

)

SimTK_NICETYPENAME_LITERAL

(

short

)

SimTK_NICETYPENAME_LITERAL

(

int

)

SimTK_NICETYPENAME_LITERAL

(

long

)

SimTK_NICETYPENAME_LITERAL

(

unsigned long

long

)

SimTK_NICETYPENAME_LITERAL

(

float

)

SimTK_NICETYPENAME_LITERAL

(

double

)

SimTK_NICETYPENAME_LITERAL

(

long

double

)

SimTK_NICETYPENAME_LITERAL

(

std::string

)

SimTK_NICETYPENAME_LITERAL

(

std::complex< float >

)

SimTK_NICETYPENAME_LITERAL

(

std::complex< double >

)

SimTK_NICETYPENAME_LITERAL

(

std::complex< long double >

)

SimTK_NICETYPENAME_LITERAL

(

SimTK::FalseType

)

SimTK_NICETYPENAME_LITERAL

(

SimTK::TrueType

)