CommonSources/commondefinitions.h

Go to the documentation of this file.

////////////////////////////////////////////////////////////////////////////////
///
/// \file
/// \author Gerald Fahrnholz
/// 
/// \brief
/// Macros and general definitions
///               - utility functions
///               - tracing
///               - simple error checks
///               - memory check using CRT
///               - Lint
///
////////////////////////////////////////////////////////////////////////////////

#pragma once


//************************************************************************
//      P r e c o m p i l e r   I n c l u d e   D i r e c t i v e s
//************************************************************************

#include <stdio.h>
#include <stdarg.h>
#include "OptionalIncludeForWindows.h"
#include <crtdbg.h>
#include <sstream>
#include <vector>
#include <string>

///\cond do not document

#pragma warning( push )
#pragma warning( disable : 4996 ) // vsprintf declared deprecated


namespace TestToolBox
{

    //************************************************************************
    //
    //      U t i l s
    //
    //************************************************************************


    // Macro which formats variable argument list
    // The macro will define the result variable formattedLine of type char[].
#define UTIL_GET_FORMATTED_LINE(in_formatStr)       \
    char formattedLine [4096];                      \
    va_list argPtr;                                 \
    va_start (argPtr, in_formatStr);                \
    vsprintf (formattedLine, in_formatStr, argPtr); \
    strcat(formattedLine,"\n");                     \
    va_end (argPtr);

#define UTIL_GET_FORMATTED_LINE_NO_NEWLINE(in_formatStr)       \
    char formattedLine [4096];                      \
    va_list argPtr;                                 \
    va_start (argPtr, in_formatStr);                \
    vsprintf (formattedLine, in_formatStr, argPtr); \
    va_end (argPtr);


    //************************************************************************
    //************************************************************************


    namespace OutputLevel
    {
        /// Extent of info written to stdout
        typedef enum 
        {
            eSILENT,       // no output at all
            eFATAL,        // only info about fatal failures
            eERROR,        // only info about (fatal and non fatal) errors
            eREGULAR,      // medium amount of output
            eVERBOUS       // maximum amount of infos
        } Enum;
    }


    //************************************************************************
    //************************************************************************

    // Convert a streamable type to a string
    template<class T>
    inline std::string ToString(const T& in_source)
    {
        std::ostringstream oss;
        // use cast to allow << overloads for ostream to work
        static_cast<std::ostream&>(oss) << in_source;
        return oss.str();
    }

    // Specialization for bool
    inline std::string ToString(const bool& in_source)
    {
        std::ostringstream oss;
        // use cast to allow << overloads for ostream to work
        static_cast<std::ostream&>(oss) << std::boolalpha << in_source;
        return oss.str();
    }

    // Remove white space from begin and end of a given string
    inline void TrimStr(std::string& io_str)
    {
        std::string::size_type pos = io_str.find_last_not_of(" \r\n");
        if(pos != std::string::npos)
        {
            io_str.erase(pos + 1);
            pos = io_str.find_first_not_of(" \r\n");
            if(pos != std::string::npos)
            {
                io_str.erase(0, pos);
            }
        }
        else
        {
            io_str.erase(io_str.begin(), io_str.end());
        }
    }

    /// Split the given string into parts using the given separators
    inline std::vector<std::string> SplitString(
        std::string const & in_string,
        std::string const & in_separators = ",")
    {
        std::vector<std::string> strList;

        std::string s = in_string;
        while (s.length() > 0)
        {
            std::string::size_type pos = s.find_first_of(in_separators);
            std::string part = s.substr(0,pos);
            if (part.length() > 0)
            {
                strList.push_back(part);
            }
            s.erase(0,pos);
            if (pos != std::string::npos) // a separator was found
            {
                // delete separator
                s.erase(0,1);
            }
        }

        return strList;

    } // SplitString


    // Generate a string containing the given filename and line number which allows
    // automatic jumping to the source code location
    inline void AddFileNameAndLineNumber (
        std::ostringstream& in_rOutStr,
        const char*         in_fileName,
        const long          in_lineNum)
    {
        if (in_fileName)
        {
            in_rOutStr << in_fileName << " (" << in_lineNum << "): ";
        }

    } // AddFileNameAndLineNumber


    //************************************************************************
    // STL helpers
    //************************************************************************

    template<class T>
    int NumElements (T const & in_container)
    {
        return static_cast<int>(in_container.size());
    }

    template<class T>
    int LastIndex (T const & in_container)
    {
        return static_cast<int>(in_container.size()) -1;
    }


    //************************************************************************
    //
    //      T R A C E  (simple output utility based on OutputDebugString)
    //
    //************************************************************************

    // The name of the SW module (main app, DLL) as used within tracing.
    // The full module name may be abbreviated if desired.
    // The value is set with TTB_TRC_DEF_GLOBALS
    extern char const* TRC_theModuleName;

    // The trace level as used by the SW module.
    // The initial value is set using macro TTB_TRC_DEF_GLOBALS.
    // In addition the level can be adjusted to command line options
    // with use of TTB_TRC_SET_TRACE_LEVEL_FROM_COMMANDLINE().
    extern int TRC_theTraceLevel;


    // empty macro, only the paranthesis after the macro is needed!
    // e.g. TRC (TLDEBUG, ...)
#define TRC

    // Remark:
    // The following routine is not optimized for performance.
    // Ways to improve performance:
    //  - fewer trace statements or running at a lower trace level
    //  - reduce the info given within the following function
    //  - think of asynchronous formatting within a separate thread
    //    (most strings are constant, for them its sufficient to store the
    //    char* pointer)
    //  - storing traces within memory ring buffer
    inline int SimpleTraceOutput(
        unsigned int in_traceLevel,
        const char*  in_fileName,
        const char*  in_functionName,
        const char*  in_objectName,
        const char*  in_traceStr, ...)
    {
        char outLine [4096];
        UTIL_GET_FORMATTED_LINE(in_traceStr);

        // display only filename, no path
        char const * pFileNameWithoutPath = strrchr(in_fileName,'\\');
        pFileNameWithoutPath = pFileNameWithoutPath ? pFileNameWithoutPath + 1 : in_fileName;

        // display only method name, suppress class name if given
        char const * pFunctionNameWithoutClass = strrchr(in_functionName,':');
        pFunctionNameWithoutClass = pFunctionNameWithoutClass ? pFunctionNameWithoutClass + 1 : in_functionName;

        if (in_objectName)
        {
            sprintf(outLine, "%-15s;  %d;  %x;  %x;  %-20s;  %-20s;  %s: %s",
                TRC_theModuleName,
                in_traceLevel,
                GetCurrentThreadId(),
                GetCurrentProcessId(),
                pFileNameWithoutPath,
                pFunctionNameWithoutClass,
                in_objectName,
                formattedLine);
        }
        else // no objectName available
        {
            sprintf(outLine, "%-15s;  %d;  %x;  %x;  %-20s;  %-20s;  %s",
                TRC_theModuleName,
                in_traceLevel,
                GetCurrentThreadId(),
                GetCurrentProcessId(),
                pFileNameWithoutPath,
                pFunctionNameWithoutClass,
                formattedLine);
        }
        OutputDebugStringA(outLine);
        return 0;
    }


    // TraceLevel
    // using global variable which is specific for the component (EXE/DLL)
    // the value can be set using TTB_TRC_SET_TRACE_LEVEL_FROM_COMMANDLINE
    // Possible extensions:
    // A comfortable viewer may have the possibility to change the level value
    // when running the program. Furthermore it is possible to think of
    // file specific trace levels.
#define TRACE_LEVEL TestToolBox::TRC_theTraceLevel

    // Trace level to be used for all statements which
    // handle unusual events ("errors").
    // Assume that this level is always active. During
    // regular processing none of these traces should
    // occure. But in case of unusual situation as many
    // traces are allowed as are needed to analyze system behaviour.
    // Assume that this level will persist in "production" code.
    // and may be available e.g. within bugreports.
#define TL_VAL_ERROR 2

    // Trace level to be used for the most important
    // statements of regular processing.
    // Assume that this level will persist in "production" code.
    // and may be available e.g. within bugreports.
#define TL_VAL_PROD  4

    // Trace level to be used for detailed output.
    // This level may be widely used and is usually deactivated.
    // Assume that this level is only activated when a specific
    // error situation within a component is analyzed.
#define TL_VAL_DEBUG 6


#ifdef  TRACE_IS_ON
#define TRCF(x)        static const char *trace_fct=x;

#define TRC0(Level, Msg)                   TRC(Level,Msg);
#define TRC1(Level, Msg,p1)                TRC(Level,Msg,p1);
#define TRC2(Level, Msg,p1,p2)             TRC(Level,Msg,p1,p2);
#define TRC3(Level, Msg,p1,p2,p3)          TRC(Level,Msg,p1,p2,p3);
#define TRC4(Level, Msg,p1,p2,p3,p4)       TRC(Level,Msg,p1,p2,p3,p4);
#define TRC5(Level, Msg,p1,p2,p3,p4,p5)    TRC(Level,Msg,p1,p2,p3,p4,p5);

#define TL_DEBUG                        TRACE_LEVEL>=TL_VAL_DEBUG)      && TestToolBox::SimpleTraceOutput(TL_VAL_DEBUG, __FILE__, trace_fct, 0
#define TL_ERROR                        TRACE_LEVEL>=TL_VAL_ERROR)      && TestToolBox::SimpleTraceOutput(TL_VAL_ERROR, __FILE__, trace_fct, 0
#define TL_PROD                         TRACE_LEVEL>=TL_VAL_PROD)       && TestToolBox::SimpleTraceOutput(TL_VAL_PROD,  __FILE__, trace_fct, 0

#define TL_DEBUGN                       TRACE_LEVEL>=TL_VAL_DEBUG)      && TestToolBox::SimpleTraceOutput(TL_VAL_DEBUG, __FILE__, trace_fct, m_traceName
#define TL_ERRORN                       TRACE_LEVEL>=TL_VAL_ERROR)      && TestToolBox::SimpleTraceOutput(TL_VAL_ERROR, __FILE__, trace_fct, m_traceName
#define TL_PRODN                        TRACE_LEVEL>=TL_VAL_PROD)       && TestToolBox::SimpleTraceOutput(TL_VAL_PROD,  __FILE__, trace_fct, m_traceName

#else // trace is switched off via preprocessor

#define TRCF(x)

#define TRC0(Level, Msg)
#define TRC1(Level, Msg,p1)
#define TRC2(Level, Msg,p1,p2)
#define TRC3(Level, Msg,p1,p2,p3)
#define TRC4(Level, Msg,p1,p2,p3,p4)
#define TRC5(Level, Msg,p1,p2,p3,p4,p5)

#define TL_DEBUG                        0)      && SimpleTraceOutput(0, __FILE__, "", 0
#define TL_ERROR                        0)      && SimpleTraceOutput(0, __FILE__, "", 0
#define TL_PROD                         0)      && SimpleTraceOutput(0, __FILE__, "", 0

#define TL_DEBUGN                       0)      && SimpleTraceOutput(0, __FILE__, "", m_traceName
#define TL_ERRORN                       0)      && SimpleTraceOutput(0, __FILE__, "", m_traceName
#define TL_PRODN                        0)      && SimpleTraceOutput(0, __FILE__, "", m_traceName

#endif


    // Helper macro to make simple use of existing tracename
    // This makro can be used e.g. within printf() statements.
    // Example: printf(TN("val = %d"), val) -> "MyObjName: val = 34"
    // Remark: For tracing prefer use of makros with suffix "N"
    // (TL_ERRORN, TL_DEBUGN, TL_PRODN)
#define TN(formatStr) "%s: " formatStr, m_traceName


    //************************************************************************
    // Macros for using trace
    //************************************************************************


    // Define the name of the module (main app, DLL) and set the initial
    // trace level. Possible trace level values are TL_VAL_ERROR, TL_VAL_PROD,
    // TL_VAL_DEBUG.
#define TTB_TRC_DEF_GLOBALS(moduleName,traceLevel)             \
    char const * TestToolBox::TRC_theModuleName = moduleName;  \
    int TestToolBox::TRC_theTraceLevel = traceLevel;

    // Set the trace level according to commandline options
    // A valid trace option has the syntax -trace <moduleName>.<level>
    // (e.g. -trace TestServer.4).
    // The trace level is set if the given module name is the same as given
    // in TTB_TRC_DEF_GLOBALS().  Not matching options are ignored.

    // TODO: MAKRO LOESCHEN!!!????
#define TTB_TRC_SET_TRACE_LEVEL_FROM_COMMANDLINE ()                     \
    \
    char*       pCmdLine = GetCommandLineA();                           \
    const char* OPT_TRACE = "-trace";                                   \
    size_t      lenTraceParam;                                          \
    char        traceParam [200];                                       \
    \
    char* pTraceToken = strstr(pCmdLine, OPT_TRACE);                    \
    while (pTraceToken)                                                 \
    {                                                                   \
        pCmdLine = pTraceToken + strlen (OPT_TRACE);                    \
        pCmdLine += strspn(pCmdLine, " \t");                            \
        lenTraceParam = strcspn(pCmdLine," \t");                        \
        strncpy(traceParam, pCmdLine, lenTraceParam);                   \
        traceParam[lenTraceParam] = '\0';                               \
        pCmdLine += lenTraceParam;                                      \
                                                                        \
        char moduleName    [200];                                       \
        char traceLevelStr [200];                                       \
        char* pLevel = strrchr(traceParam,'.');                         \
        if (pLevel)                                                     \
        {                                                               \
            size_t lenModName    = pLevel - traceParam;                 \
            size_t lenTraceLevel = strlen(traceParam) - lenModName - 1; \
            strncpy(moduleName, traceParam, lenModName);                \
            moduleName[lenModName] = '\0';                              \
            strncpy(traceLevelStr, pLevel+1, lenTraceLevel);            \
            traceLevelStr[lenTraceLevel] = '\0';                        \
            if (!strcmp(moduleName, TRC_theModuleName))                 \
            {                                                           \
                TRC_theTraceLevel = atoi(traceLevelStr);                \
                TRC(TL_PROD,                                            \
                    "TraceLevel set to %d (according commandline)",     \
                    TRC_theTraceLevel);                                 \
            }                                                           \
        }                                                               \
                                                                        \
        pTraceToken = strstr(pCmdLine, OPT_TRACE);                      \
    }

    inline void SetTraceLevelFromCommandLine(void)
    {
        TRCF("SetTraceLevelFromCommandLine");

        char*       pCmdLine = GetCommandLineA();
        const char* OPT_TRACE = "-trace";
        size_t      lenTraceParam;
        char        traceParam [200];

        char* pTraceToken = strstr(pCmdLine, OPT_TRACE);
        while (pTraceToken)
        {
            pCmdLine = pTraceToken + strlen (OPT_TRACE);
            pCmdLine += strspn(pCmdLine, " \t");
            lenTraceParam = strcspn(pCmdLine," \t");
            strncpy(traceParam, pCmdLine, lenTraceParam);
            traceParam[lenTraceParam] = '\0';
            pCmdLine += lenTraceParam;

            char moduleName    [200];
            char traceLevelStr [200];
            char* pLevel = strrchr(traceParam,'.');
            if (pLevel)
            {
                size_t lenModName    = pLevel - traceParam;
                size_t lenTraceLevel = strlen(traceParam) - lenModName - 1;
                strncpy(moduleName, traceParam, lenModName);
                moduleName[lenModName] = '\0';
                strncpy(traceLevelStr, pLevel+1, lenTraceLevel);
                traceLevelStr[lenTraceLevel] = '\0';
                if (!strcmp(moduleName, TRC_theModuleName))
                {
                    TRC_theTraceLevel = atoi(traceLevelStr);
                    TRC(TL_PROD,
                        "TraceLevel set to %d (according commandline)",
                        TRC_theTraceLevel);
                }
            }

            pTraceToken = strstr(pCmdLine, OPT_TRACE);
        }
    }


    //************************************************************************
    //
    // Support for simple error handling
    //
    //************************************************************************
    //
    // Assume that there is an error handling mechanism which allows creating
    // of error objects which are handled by an corresponding component
    // ("ErrorHandler"). Each function may create such errors. The caller is
    // informed by an appropriate return value which is either 0 (no error)
    // or a handle value (ErrorId) which allows access to the error object
    // within the ErrorHandler.
    // Remark: It is assumed that exceptions are not used within the calls.
    //
    // Example:
    //
    // ErrorId MyFunction (void)
    // {
    //     DEF_ERRID;
    //     if (CALL_FAILED (OtherFunction()))
    //     {
    //         ReactOnError();
    //     }
    //
    //     for (int i =1; i<= 10; ++i)
    //     {
    //         BREAK_ON_ERROR (SomeFunctionA(i));
    //         BREAK_ON_ERROR (SomeFunctionB(i));
    //         BREAK_ON_ERROR (SomeFunctionC(i));
    //     }
    //     return errId;
    // }

#define DEF_ERRID ErrorId errId = 0;

#define CALL_FAILED(FunctionCall) \
    0 != (errId = ((FunctionCall)))

    // Macro for simple checking of return values
    // If the function fails an assert will cause a simple file/line message
#define ASSERT_ON_ERROR(FunctionCall) \
    errId = ((FunctionCall)); assert(0 == errId)

#define BREAK_ON_ERROR(FunctionCall) \
    errId = ((FunctionCall)); if (errId){break;}

    // assumes a function which sends an error to the GUI
#define SEND_ON_ERROR(FunctionCall) \
    errId = ((FunctionCall)); if (errId){SendErrorToGui(errId);}


    //************************************************************************
    //
    //      M e m C h e c k (CRT)
    //
    //************************************************************************
    // Macros to control memory checks for debug version
    // (for description see online help on "_CrtDumpMemoryLeaks/_CrtCheckMemory")

#ifdef   _DEBUG
#define  SET_CRT_DEBUG_FIELD(a) \
    _CrtSetDbgFlag((a) | _CrtSetDbgFlag(_CRTDBG_REPORT_FLAG))
#define  CLEAR_CRT_DEBUG_FIELD(a) \
    _CrtSetDbgFlag(~(a) & _CrtSetDbgFlag(_CRTDBG_REPORT_FLAG))
#else
#define  SET_CRT_DEBUG_FIELD(a)   ((void) 0)
#define  CLEAR_CRT_DEBUG_FIELD(a) ((void) 0)
#endif


    //************************************************************************
    //
    //      L i n t
    //
    //************************************************************************
    // Solve Lint problems with unused function arguments (e.g. when using
    // some CASE tool the param name cannot be suppressed as in standard C/C++)

    // Ignore the given param (used to deactivate warnings when
    // compiling at warning level 4)
#define IGNORE_PARAM(p) p = p


    //************************************************************************
    //
    //      Generation
    //
    //************************************************************************
    // Switch to use the implementation code of TestToolBox (as found in files
    // of type <name>Impl.h) as inline code (to be included in each cpp file)
    // or as regular functions to be compiled within a lib or e.g. within
    // stdafx.cpp
#ifdef TTB_NOT_INLINE
#define TTB_INLINE
#else
#define TTB_INLINE inline
#endif

}

#pragma warning( pop )

///\endcond

---