common.h

Go to the documentation of this file.

#ifndef SimTK_SimTKCOMMON_COMMON_H_
#define SimTK_SimTKCOMMON_COMMON_H_

/* -------------------------------------------------------------------------- *
 *                      SimTK Core: SimTKcommon                               *
 * -------------------------------------------------------------------------- *
 * This is part of the SimTK Core biosimulation toolkit originating from      *
 * Simbios, the NIH National Center for Physics-Based Simulation of           *
 * Biological Structures at Stanford, funded under the NIH Roadmap for        *
 * Medical Research, grant U54 GM072970. See https://simtk.org.               *
 *                                                                            *
 * Portions copyright (c) 2005-7 Stanford University and the Authors.         *
 * Authors: Michael Sherman                                                   *
 * Contributors:                                                              *
 *                                                                            *
 * Permission is hereby granted, free of charge, to any person obtaining a    *
 * copy of this software and associated documentation files (the "Software"), *
 * to deal in the Software without restriction, including without limitation  *
 * the rights to use, copy, modify, merge, publish, distribute, sublicense,   *
 * and/or sell copies of the Software, and to permit persons to whom the      *
 * Software is furnished to do so, subject to the following conditions:       *
 *                                                                            *
 * The above copyright notice and this permission notice shall be included in *
 * all copies or substantial portions of the Software.                        *
 *                                                                            *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR *
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,   *
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL    *
 * THE AUTHORS, CONTRIBUTORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,    *
 * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR      *
 * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE  *
 * USE OR OTHER DEALINGS IN THE SOFTWARE.                                     *
 * -------------------------------------------------------------------------- */

/*****************************/
/* ANSI-C COMPATIBLE SECTION */
/*****************************/

/* Set up a few compile-time options that affect all SimTK Core headers. */

/* 
 * 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.
 */
#ifndef SimTK_DEFAULT_PRECISION
#   define SimTK_DEFAULT_PRECISION 2
#endif

/* This type is for use in C. In C++ use SimTK::Real instead. */
#if   (SimTK_DEFAULT_PRECISION == 1)
    typedef float SimTK_Real;
#elif (SimTK_DEFAULT_PRECISION == 2)
    typedef double SimTK_Real;
#elif (SimTK_DEFAULT_PRECISION == 4)
    typedef long double SimTK_Real;
#else
    #error ILLEGAL VALUE FOR DEFAULT PRECISION
#endif

#ifndef NDEBUG
    #if defined(__cplusplus)
        #include <cstdio>
        #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)
    #else
        #include <stdio.h>
        #define SimTK_DEBUG(s) printf("DBG: " s)
        #define SimTK_DEBUG1(s,a1) printf("DBG: " s,a1) 
        #define SimTK_DEBUG2(s,a1,a2) printf("DBG: " s,a1,a2)   
        #define SimTK_DEBUG3(s,a1,a2,a3) printf("DBG: " s,a1,a2,a3) 
        #define SimTK_DEBUG4(s,a1,a2,a3,a4) printf("DBG: " s,a1,a2,a3,a4)
    #endif
#else
    #define SimTK_DEBUG(s)
    #define SimTK_DEBUG1(s,a1)
    #define SimTK_DEBUG2(s,a1,a2)
    #define SimTK_DEBUG3(s,a1,a2,a3)    
    #define SimTK_DEBUG4(s,a1,a2,a3,a4)
#endif

/*
 * Shared libraries are messy in Visual Studio. We have to distinguish three
 * cases:
 *   (1) this header is being used to build the SimTKcommon shared library (dllexport)
 *   (2) this header is being used by a *client* of the SimTKcommon shared
 *       library (dllimport)
 *   (3) we are building the SimTKcommon static library, or the client is
 *       being compiled with the expectation of linking with the
 *       SimTKcommon static library (nothing special needed)
 * In the CMake script for building this library, we define one of the symbols
 *     SimTK_SimTKCOMMON_BUILDING_{SHARED|STATIC}_LIBRARY
 * Client code normally has no special symbol defined, in which case we'll
 * assume it wants to use the shared library. However, if the client defines
 * the symbol SimTK_USE_STATIC_LIBRARIES we'll suppress the dllimport so
 * that the client code can be linked with static libraries. Note that
 * the client symbol is not library dependent, while the library symbols
 * affect only the SimTKcommon library, meaning that other libraries can
 * be clients of this one. However, we are assuming all-static or all-shared.
 */

#ifdef WIN32
    #if defined(SimTK_SimTKCOMMON_BUILDING_SHARED_LIBRARY)
        #define SimTK_SimTKCOMMON_EXPORT __declspec(dllexport)
    #elif defined(SimTK_SimTKCOMMON_BUILDING_STATIC_LIBRARY) || defined(SimTK_USE_STATIC_LIBRARIES)
        #define SimTK_SimTKCOMMON_EXPORT
    #else
        #define SimTK_SimTKCOMMON_EXPORT __declspec(dllimport)   // i.e., a client of a shared library
    #endif
#else
    #define SimTK_SimTKCOMMON_EXPORT // Linux, Mac
#endif

/* Every SimTK Core library must provide these two routines, with the library
 * name appearing after the "version_" and "about_".
 */
#if defined(__cplusplus)
extern "C" {
#endif
    SimTK_SimTKCOMMON_EXPORT void SimTK_version_SimTKcommon(int* major, int* minor, int* build);
    SimTK_SimTKCOMMON_EXPORT void SimTK_about_SimTKcommon(const char* key, int maxlen, char* value);
#if defined(__cplusplus)
}
#endif

/************************************/
/* END OF ANSI-C COMPATIBLE SECTION */
/************************************/

#if defined(__cplusplus)

#include <cstddef>
#include <cassert>
#include <complex>
#include <limits>

namespace SimTK {
    static const int InvalidIndex = -1111111111;
}

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

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

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

#define SimTK_DEFINE_AND_EXPORT_UNIQUE_LOCAL_INDEX_TYPE(EXPORT,PARENT,SEP,NAME)   \
class EXPORT NAME {                         \
    int ix;                                 \
public:                                     \
    NAME() : ix(SimTK::InvalidIndex) { }       \
    explicit NAME(int i) : ix(i)      {assert(i>=0 || i==SimTK::InvalidIndex);} \
    explicit NAME(long l): ix((int)l) {assert(canStoreInNonnegativeInt(l));}    \
    explicit NAME(unsigned int  u)  : ix((int)u)  {assert(canStoreInInt(u));}   \
    explicit NAME(unsigned long ul) : ix((int)ul) {assert(canStoreInInt(ul));}  \
    operator int() const {return ix;}               \
    bool isValid() const {return ix>=0;}            \
    bool isValidExtended() const {return ix>=-1;}   \
    void invalidate(){ix=SimTK::InvalidIndex;}      \
    \
    bool operator==(int  i) const {assert(isValidExtended() && isValidExtended(i)); return ix==i;}    \
    bool operator==(long l) const {assert(isValidExtended() && isValidExtended(l)); return ix==(int)l;}  \
    bool operator==(unsigned int  u)  const {assert(isValidExtended() && isValid(u)); return ix==(int)u;}   \
    bool operator==(unsigned long ul) const {assert(isValidExtended() && isValid(ul)); return ix==(int)ul;} \
    bool operator!=(int  i)           const {return !operator==(i);}    \
    bool operator!=(long l)           const {return !operator==(l);}    \
    bool operator!=(unsigned int  u)  const {return !operator==(u);}    \
    bool operator!=(unsigned long ul) const {return !operator==(ul);}   \
    \
    bool operator< (int  i) const {assert(isValidExtended() && isValidExtended(i)); return ix<i;}        \
    bool operator< (long l) const {assert(isValidExtended() && isValidExtended(l)); return ix<(int)l;}   \
    bool operator< (unsigned int  u)  const {assert(isValidExtended() && isValid(u));  return ix<(int)u;}    \
    bool operator< (unsigned long ul) const {assert(isValidExtended() && isValid(ul)); return ix<(int)ul;}   \
    bool operator>=(int  i)           const {return !operator<(i);}    \
    bool operator>=(long l)           const {return !operator<(l);}    \
    bool operator>=(unsigned int  u)  const {return !operator<(u);}    \
    bool operator>=(unsigned long ul) const {return !operator<(ul);}   \
    \
    bool operator> (int  i) const {assert(isValidExtended() && isValidExtended(i)); return ix>i;}        \
    bool operator> (long l) const {assert(isValidExtended() && isValidExtended(l)); return ix>(int)l;}   \
    bool operator> (unsigned int  u)  const {assert(isValidExtended() && isValid(u));  return ix>(int)u;}    \
    bool operator> (unsigned long ul) const {assert(isValidExtended() && isValid(ul)); return ix>(int)ul;}   \
    bool operator<=(int  i)           const {return !operator>(i);}    \
    bool operator<=(long l)           const {return !operator>(l);}    \
    bool operator<=(unsigned int  u)  const {return !operator>(u);}    \
    bool operator<=(unsigned long ul) const {return !operator>(ul);}   \
    \
    const NAME& operator++() {assert(isValid()); ++ix; return *this;}       /*prefix */   \
    NAME operator++(int)     {assert(isValid()); ++ix; return NAME(ix-1);}  /*postfix*/   \
    const NAME& operator--() {assert(isValid()); --ix; return *this;}       /*prefix */   \
    NAME operator--(int)     {assert(isValid()); --ix; return NAME(ix+1);}  /*postfix*/   \
    \
    NAME& operator+=(int i)  {assert(isValid() && isValidExtended(ix+i)); ix+=i; return *this;}     \
    NAME& operator-=(int i)  {assert(isValid() && isValidExtended(ix-i)); ix-=i; return *this;}     \
    NAME& operator+=(long l) {assert(isValid() && canStoreInInt(l) && isValidExtended(ix+(int)l)); ix+=(int)l; return *this;}     \
    NAME& operator-=(long l) {assert(isValid() && canStoreInInt(l) && isValidExtended(ix-(int)l)); ix-=(int)l; return *this;}     \
    NAME& operator+=(unsigned int  u)  {assert(isValid()&& canStoreInInt(u)  && isValid(ix+(int)u));  ix+=(int)u;  return *this;}  \
    NAME& operator-=(unsigned int  u)  {assert(isValid()&& canStoreInInt(u)  && isValidExtended(ix-(int)u));  ix-=(int)u;  return *this;}  \
    NAME& operator+=(unsigned long ul) {assert(isValid()&& canStoreInInt(ul) && isValid(ix+(int)ul)); ix+=(int)ul; return *this;}  \
    NAME& operator-=(unsigned long ul) {assert(isValid()&& canStoreInInt(ul) && isValidExtended(ix-(int)ul)); ix-=(int)ul; return *this;}  \
    \
    static const NAME& Invalid() {static const NAME invalid; return invalid;}       \
    static bool isValid(int  i) {return i>=0;}                                      \
    static bool isValid(long l) {return canStoreInNonnegativeInt(l);}               \
    static bool isValid(unsigned int  u)  {return canStoreInInt(u);}                \
    static bool isValid(unsigned long ul) {return canStoreInInt(ul);}               \
    static bool isValidExtended(int  i) {return i>=-1;}                             \
    static bool isValidExtended(long l) {return canStoreInInt(l) && l>=-1;}         \
};

#define SimTK_DOWNCAST(Derived,Parent) \
    static bool isA(const Parent& p)                        \
        { return dynamic_cast<const Derived*>(&p) != 0; }   \
    static const Derived& downcast(const Parent& p)         \
        { return dynamic_cast<const Derived&>(p); }         \
    static Derived& downcast(Parent& p)                     \
        { return dynamic_cast<Derived&>(p); }

#define SimTK_DOWNCAST2(Derived,Helper,Parent) \
    static bool isA(const Parent& p)                                        \
        { return Helper::isA(p); }                                          \
    static const Derived& downcast(const Parent& p)                         \
        { return reinterpret_cast<const Derived&>(Helper::downcast(p)); }   \
    static Derived& downcast(Parent& p)                                     \
        { return reinterpret_cast<Derived&>(Helper::downcast(p)); }


// 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_PIMPL_DOWNCAST(Derived, Parent)           \
    static bool           isInstanceOf(const Parent&);  \
    static const Derived& downcast(const Parent&);      \
    static Derived&       updDowncast(Parent&)

namespace SimTK {
    
namespace Options { }
namespace Exception { }

typedef SimTK_Real              Real;
typedef std::complex<Real>      Complex;

struct Segment {
    Segment() : length(0), offset(0) { }
    explicit Segment(int l, int ofs=0) : length(l), offset(ofs) { 
        assert(l>=0 && ofs>=0);
    }
    // default copy, assignment, destructor
    int length;
    int offset;
};  

template <class T> class TypeInfo {
public:
    static const char* name() {return typeid(T).name();}
};

#define SimTK_TYPEINFO_SPECIALIZE(T)            \
template <> class TypeInfo< T > {               \
public:                                         \
    static const char* name() { return #T; }    \
};
// Built-in types
SimTK_TYPEINFO_SPECIALIZE(bool);            SimTK_TYPEINFO_SPECIALIZE(signed char); 
SimTK_TYPEINFO_SPECIALIZE(char);            SimTK_TYPEINFO_SPECIALIZE(unsigned char);
SimTK_TYPEINFO_SPECIALIZE(short);           SimTK_TYPEINFO_SPECIALIZE(int); 
SimTK_TYPEINFO_SPECIALIZE(long);
SimTK_TYPEINFO_SPECIALIZE(unsigned short);  SimTK_TYPEINFO_SPECIALIZE(unsigned int); 
SimTK_TYPEINFO_SPECIALIZE(unsigned long);
SimTK_TYPEINFO_SPECIALIZE(float);           SimTK_TYPEINFO_SPECIALIZE(double); 
SimTK_TYPEINFO_SPECIALIZE(long double);
SimTK_TYPEINFO_SPECIALIZE(std::complex<float>);
SimTK_TYPEINFO_SPECIALIZE(std::complex<double>); 
SimTK_TYPEINFO_SPECIALIZE(std::complex<long double>); 


} // namespace SimTK

namespace SimTKimpl {

typedef void*       (*IndexT)(void* tp, int n);
typedef const void* (*IndexConstT)(const void* tp, int n);
typedef void*       (*CreateOneT)(const void* iptr);
typedef void        (*DestructOneT)(void*& tvptr);  
typedef void        (*AssignArrayOfT)(void* dest, const void* src, int n);
typedef void        (*SetT)(void* dest, const void* valuep, int n);
typedef void*       (*CreateArrayOfT)(int n, const void* iptr);
typedef void        (*DestructArrayOfT)(void*& tvptr);

struct TypeManipulatorT {
    TypeManipulatorT(int z, IndexT it, IndexConstT ict,
                     CreateOneT c1t, DestructOneT d1t, AssignArrayOfT aat, SetT st,
                     CreateArrayOfT cat, DestructArrayOfT dat)
        : sizeOfT(z), indexT(it), indexConstT(ict), 
          createOneT(c1t), destructOneT(d1t), assignArrayOfT(aat), setT(st),
          createArrayOfT(cat), destructArrayOfT(dat)
    { }
    
    bool operator==(const TypeManipulatorT& t) const
      { return sizeOfT==t.sizeOfT && indexT==t.indexT; }

    // THESE MUST NEVER CHANGE ORDER! This is effectively a compiler-independent
    // virtual function table. The first entry is a size in bytes and the rest have
    // type "pointer to function" so all the data should have a very predictable
    // and stable layout in memory.
    //
    // This is the one place in the SimTK API where the client
    // side and library side must agree on the physical layout of the class. 
    // It is safe to add new entries to the end of this list, but inserting earlier,
    // deleting or reordering anything already here will break binary compatibility.
    const int               sizeOfT;
    const IndexT            indexT;
    const IndexConstT       indexConstT;
    const CreateOneT        createOneT;
    const DestructOneT      destructOneT;
    const AssignArrayOfT    assignArrayOfT;
    const SetT              setT;
    const CreateArrayOfT    createArrayOfT;
    const DestructArrayOfT  destructArrayOfT;
};

template <class T> class MakeTypeManipulator {
public:
    MakeTypeManipulator() { }
    // default copy, assignment, destructor
    
    static const TypeManipulatorT& getTypeManipulatorT() { return manipT; }
    static T& updAs(void* v) 
      { assert(v); return *reinterpret_cast<T*>(v); }
    static const T& getAs(const void* v) 
      { assert(v); return *reinterpret_cast<const T*>(v); }

private:    
    static int sizeT() { return (int)sizeof(T); }
    
    static void* indexT(void* tp, int n)
        { return (void*)(reinterpret_cast<T*>(tp) + n); }
    static const void* indexConstT(const void* tp, int n)
        { return (const void*)(reinterpret_cast<const T*>(tp) + n); }

    static void* createOneT(const void* iptr=0)
    {
        T* tptr = new T;
        if (iptr) *tptr = *reinterpret_cast<const T*>(iptr);
        return tptr;
    }
    
    static void destructOneT(void*& tvptr)
    {
        T* tptr = reinterpret_cast<T*>(tvptr);
        delete tptr;
        tvptr = 0;
    }

    static void assignArrayOfT(void* dest, const void* src, int n)
    {   assert(n>=0);
        if (n==0) return;
        assert(dest && src);
        assert(indexT(dest,n) < src || indexConstT(src,n) < dest);      
        T*       d = reinterpret_cast<T*>(dest);
        const T* s = reinterpret_cast<const T*>(src);
        for (int i=0; i < n; ++i) *d++ = *s++;
    }
        
    static void setT(void* dest, const void* valuep, int n=1)
    {   assert(n>=0);
        if (n==0) return;
        assert(dest && valuep);
        T*       d = reinterpret_cast<T*>(dest);
        const T& v = *reinterpret_cast<const T*>(valuep);
        for (int i=0; i < n; ++i) *d++ = v; 
    }
    
    static void* createArrayOfT(int n, const void* iptr=0)
    {   assert(n>=0);
        if (n == 0) return 0;
        T* tptr = new T[n];
        if (iptr) {
            const T& init = *reinterpret_cast<const T*>(iptr);
            for (int i=0; i < n; ++i) tptr[i] = init;
        }       
        return tptr;
    }
    
    static void destructArrayOfT(void*& tvptr)
    {
        T* tptr = reinterpret_cast<T*>(tvptr);
        delete[] tptr;
        tvptr = 0;
    }
    
private:    
    static const TypeManipulatorT manipT;
};

/*static*/ template <class T> const TypeManipulatorT
MakeTypeManipulator<T>::manipT = TypeManipulatorT(
                                    (int)sizeof(T),indexT,indexConstT,
                                    createOneT, destructOneT, assignArrayOfT, setT, 
                                    createArrayOfT, destructArrayOfT);
} // namespace SimTKimpl


#endif /* C++ stuff */

#endif /* SimTK_SimTKCOMMON_COMMON_H_ */

---