#define  M_STRDEF_INNER(x)     #x
#define  M_STRDEF(x)           M_STRDEF_INNER(x)

stringify the macro's argument _after_ substituing it, unlike the normal "#" C-preprocessor directive. As an example:

      #define  FOO       xyz
      #define  FOO1      M_STRDEF(FOO)
      #define  FOO2      #FOO

will define FOO1 as "xyz" and FOO2 as "FOO"..

#define  M_CONCAT_INNER(x,y)   x##y
#define  M_CONCAT(x,y)         M_CONCAT_INNER(x,y)

concatenate the macro's arguments _after_ substituing them, unlike the normal "##" C-preprocessor directive. As an example:

      #define  FOO       xyz
      #define  BAR       123
      #define  FOOBAR1   M_CONCAT(FOO,BAR)
      #define  FOOBAR2   FOO ## BAR

will define FOOBAR1 as "xyz123" and FOOBAR2 as "FOOBAR"

#ifdef __cplusplus
#  define  M_BEGIN_HEADER    extern "C" {
#else
#  define  M_BEGIN_HEADER    /* nothing */
#endif

this macro should be used to begin declarations in every public header file, in association with a M_END_HEADER at the end of the file. The role of these two macros is to ensure the proper inclusion of the file from a C++ program..

#ifdef __cplusplus
#  define  M_END_HEADER    }
#else
#  define  M_END_HEADER    /* nothing */
#endif

this macro should be used to end declarations in every public header file, in association with a M_BEGIN_HEADER at the start of the file. The role of these two macros is to ensure the proper inclusion of the file from a C++ program...

#ifdef __cplusplus
#  define  M_EXTERN(x)       extern "C" x
#else
#  define  M_EXTERN(x)       extern x
#endif

this macro is primarily used to declare an external C function or variable that might be called or accessed from other programs, especially C++ ones..

#define    M_BEGIN_STMNT     do {

this macro is used to define other macros containing multiple statements, in association with M_END_STMNT . they ensure that the new defined macro is always seen as a single statement by the C compiler, and can be followed by a semi-column.

As an example, consider the following macro definitions

      #define  MULTI1(x,y)  (x) = 0; (y) = 0

      #define  MULTI2(x,y)   M_BEGIN_STMNT  \
                               (x) = 0;     \
                               (y) = 0;     \
                             M_END_STMNT

using MULTI1 will result in incorrect behaviour and/or compilation in cases like:

      if (z)
        MULTI1(x1,y1);
      else
        MULTI1(x2,y2);

the problem doesn't happen with MULTI2

#define    M_END_STMNT       } while (0)

this macro is used to define other macros containing multiple statements, in association with M_BEGIN_STMNT . they ensure that the new defined macro is always seen as a single statement by the C compiler, and can be followed by a semi-column.

see the example described with M_BEGIN_STMNT

#define    M_DUMMY_STMNT     do { } while (0)

this macro is used to define other macros that should be considered as a statement even if they do not include code.

it's mostly used with conditional compilation in order to disable certain statements (e.g. logs and assertions)

#define    M_UNUSED(x)       (x)=(x)

this macro is used to indicate that a given function parameter or static variable is unused. Its purpose is to eliminate compiler warnings when using high warning levels.

it is typicaly used with conditional compilation as well as witthin callbacks that not always use all the parameters passed to the function..

We could have defined this macro as "(void)(x)", however a few ANSI compilers complain about this statement..

#define    M_UNUSED_CONST(x)       (void)(x)

this macro is used to indicate that a given _constant_ function parameter or static variable is unused. Its purpose is to eliminate compiler warnings when using high warning levels.

it is typicaly used with conditional compilation as well as witthin callbacks that not always use all the parameters passed to the function..

#define    M_SET_ERROR(x)  ((error = (x)) != 0)

this macro is used to define other macros. Its purpose is to perform a function call given by the "f" parameter and store its result in an _implicit_ variable named *error*.

it returns a boolean which is set to TRUE whenever an error occured, i.e. the value of *error* is not 0.

a typical developer should never use this macro directly..

#ifdef MLIB_BUILD_DLL
#  define  MLIB_API(x)     M_DLL_EXPORT(x)
#elif defined(MLIB_USE_DLL)
#  define  MLIB_API(x)     M_DLL_IMPORT(x)
#else
#  define  MLIB_API(x)     M_EXTERN(x)
#endif

this macro is used to _declare_ an MLib function. it defaults to M_EXTERN but can also be defined as M_DLL_EXPORT (when building the MLib DLL), or M_DLL_IMPORT (when using the MLib as a DLL)

#ifdef MLIB_BUILD_DLL
#  define  MLIB_APIDEF(x)     x
#elif defined(MLIB_USE_DLL)
#  define  MLIB_APIDEF(x)     M_EXTERN(x)  /* should not happen */
#else
#  define  MLIB_APIDEF(x)     M_EXTERN(x)
#endif

this macro is used to _define_ an MLib function. it defaults to M_EXTERN

#ifdef MLIB_BUILD_DLL
#  define  MLIB_API_VAR(x)     M_DLL_EXPORT(x)
#elif defined(MLIB_USE_DLL)
#  define  MLIB_API_VAR(x)     M_DLL_IMPORT(x)
#else
#  define  MLIB_API_VAR(x)     M_EXTERN(x)
#endif

this macro is used to _declare_ an MLib _constant_ variable. it defaults to M_EXTERN but can also be defined as M_DLL_EXPORT (when building the MLib DLL) or M_DLL_IMPORT (when using the MLib as a DLL)

#ifdef MLIB_BUILD_DLL
#  define  MLIB_API_VARDEF(x)     x
#elif defined(MLIB_USE_DLL)
#  define  MLIB_API_VARDEF(x)     x  /* should not happen */
#else
#  define  MLIB_API_VARDEF(x)     x
#endif

this macro is used to _define_ an MLib function variable. it defaults to M_EXTERN

#define  M_MIN(x,y)   ( (x) < (y) ?  (x) : (y) )

macro to return the generic minimum of two items

#define  M_MAX(x,y)   ( (x) > (y) ?  (x) : (y) )

macro to return the generic maximum of two items

#define  M_ABS(x)     ( (x) < 0   ? -(x) : (x) )

macro to return the generic absolute value of an item

#ifndef M_SIZEOF_INT
#  if   UINT_MAX == 0xFFFFFFFFU
#    define M_SIZEOF_INT  4
#  elif UINT_MAX == 0xFFFFU
#    define M_SIZEOF_INT  2
#  elif UINT_MAX > 0xFFFFFFFFU && UINT_MAX == 0xFFFFFFFFFFFFFFFFU
#    define M_SIZEOF_INT  8
#  else
#    error "Unsupported number of bytes in `int' type!"
#  endif
#endif

returns the number of bytes in an "int", normally 2, 4 or 8 depending on the system

#ifndef M_SIZEOF_LONG
#  if   ULONG_MAX == 0xFFFFFFFFU
#    define M_SIZEOF_LONG  4
#  elif ULONG_MAX > 0xFFFFFFFFU && ULONG_MAX == 0xFFFFFFFFFFFFFFFFU
#    define M_SIZEOF_LONG  8
#  else
#    error "Unsupported number of bytes in `long' type!"
#  endif
#endif

returns the number of bytes in an "long", normally 4 or 8 depending on the system

#ifndef   M_ALIGNMENT
#  define M_ALIGNMENT  8
#endif

preferred alignment values for data in memory. Must be at least 8 bytes for 64-bit systems..

#ifndef M_DLL_IMPORT
#  define  M_DLL_IMPORT(x)   extern x
#endif

a macro used to _declare_ a DLL entry point. Certain compilers need a special pragma or keyword to notify client applications that an external function is defined in a DLL.

You should not use this macro directly in your code. Rather, use it when defining your project-specific API export macros, as in the following fragment:

       #ifdef PROJECT_BUILD_DLL
       #
       #  define  PROJECT_API(x)     M_DLL_EXPORT(x)
       #  define  PROJECT_APIDEF(x)  x
       #
       #elif defined(PROJECT_USE_DLL)
       #
       #  define  PROJECT_API(x)     M_DLL_IMPORT(x)
       #  define  PROJECT_APIDEF(x)  x               // should not happen
       #
       #else // use static library
       #
       #  define  PROJECT_API(x)     M_EXTERN(x)
       #  define  PROJECT_APIDEF(x)  M_EXTERNDEF(x)
       #
       #endif

then, you can use PROJECT_API and PROJECT_APIDEF to respectively declare your exported functions (in public header files), or define them (in project private source files).

#ifndef M_DLL_EXPORT
#  define  M_DLL_EXPORT(x)   extern x
#endif

a macro used to _define_ a DLL entry point in your project private source code. Certain compilers need a special pragma or keyword to generate appropriate code when a dynamic library is built.

On certain platforms ( Windows &. OS/2 ), you'll need an additional .DEF file to build the DLL when this macro is used. The file is used to list the exported functions and their ordinal number.

a .DEF file is convenient because it lets you upgrade a DLL without running the risk of breaking all applications that use it.

#ifndef M_DLL_EXPORT_LAZY
#  define  M_DLL_EXPORT_LAZY(x)  extern  x
#endif

a macro used to _define_ a DLL entry point in your project's private source code. Certain compilers need a special pragma or keyword to generate appropriate code when a dynamic library is built.

this is a variant of M_DLL_EXPORT that can be used to avoid the need for a .DEF file when building a DLL on certain platforms (namely Windows and OS/2).

you should never use this macro directly. see the comments in M_DLL_IMPORT for more explanations..

be aware that if you do not use a .DEF file on Windows, you'll be unable to safely upgrade a DLL without breaking other programs that implicetly link to it..

generally speaking, M_DLL_EXPORT_LAZY should only be used when building DLLs that you fully control, not some that can be used by another application.

#ifndef  M__FUNC__
#  define  M__FUNC__  "unknown function"
#endif

returns a string containing the name of the current function. This is only supported with certain compilers, by default this macro will return "unknown function".

this is used by log and error messages