Common.h

Go to the documentation of this file.

//==============================================================================
// Project uLib - User mode utility library.
//==============================================================================
//==============================================================================
//==============================================================================

#ifndef _uLib_Common_h_incl_
#define _uLib_Common_h_incl_

// PONDER: Make all functions explicitly WINAPI, unless they have var-args,
// in which case they should be explicitly __cdecl, or they have been
// designated __fastcall for some reason.

// TODO: Make sure all C functions are EXTERN_C,
// unless they are overloaded and hence unavailable in C.

//==============================================================================
//==============================================================================

//==----------------------------------------------------------------------------

#ifdef NT4_COMP
  #undef WINVER
  #define WINVER 0x400
  #ifdef __GNUC__ // GCC headers don't have 0x0400 conditionals
    #pragma message("ALERT: GCC headers don't have WINVER 0x0400 conditionals, so ...")
    #pragma message("ALERT: **YOU** must maintain NT4 compatibility, by not using NT5+ functions.")
  #endif
#endif

#ifndef WINVER
  // x601 == Win7
  // x600 == Vista
  // x501 == WinXP
  // x502 == Svr2003 & ReactOS
  //#define WINVER 0x502
  #define WINVER 0x600
#endif
#if (WINVER == 0x400)
#define NO_VERSION_WARNING // Legacy: For my patched NT4 SDK headers (not for you).
#endif

#ifndef _WIN32_IE
#define _WIN32_IE  WINVER
#endif
#ifndef _WIN32_WINNT
#define _WIN32_WINNT  WINVER // IsDebuggerPresent (& c...)
#endif
#ifndef _WIN32_WINDOWS
#define _WIN32_WINDOWS  WINVER //  -"-
#endif
#ifndef WIN32_LEAN_AND_MEAN
#define WIN32_LEAN_AND_MEAN 1 // Exclude rarely-used stuff from Windows headers
#endif

#ifndef STRICT
#define STRICT 1
#endif

#define TYPEDEF_STRINGS  1  // Use 0 to make them #defines instead of typedefs.

#ifndef NO_NDK_FILES // Define this if you don't have the NDK.
  #if defined(_WIN64) && (_WIN32_WINNT < 0x0502)
    #pragma message("[uLib] ALERT: NDK files excluded in x64 due to _WIN32_WINNT < 0x0502")
    // NOTA BENE: struct TEB, in <ndk/peb_teb.h>, is currently broken in x64
    // when _WIN32_WINNT < 0x0502 (i.e. NTDDI_VERSION < NTDDI_WS03).
    #define NO_NDK_FILES // Exclude the NDK.
  #endif
#endif

#ifndef NO_ULIB_BLDINFO
#include "BldInfo.h" // Programmer feedback
#else
  #define BLD_INFO(str)
#endif

#ifdef __GNUC__
//#define NO_NTSTATUS  // Comment out if you have it
//#define NO_WINTERNAL // -"-
#endif

//==----------------------------------------------------------------------------

#ifndef NO_NTSTATUS
  #pragma warning( disable: 4005 ) 
  // Squelch W4005 "re-definitions" in NtStatus.h visavi WinNT.h,
  // in case Windows.h et al was previosly included in the build process.
  #include <NtStatus.h> 
  #define WIN32_NO_STATUS // Prevent subsequent #define STATUS_xx clashes.

  #ifndef NT_SUCCESS 
  #define NT_SUCCESS(Status) ((NTSTATUS)(Status) >= 0)
  #endif

  #ifndef NT_ERROR 
  #define NT_ERROR(Status)  (((ULONG)(Status) >> 30) == 3)
  #endif
#endif

#include <Windows.h>
#include <WindowsX.h> /* Useful control class macros */
//#include <WinBase.h>
#include <WinError.h>
#include <WinNT.h> /* For IDE convenience (PopMenu: Open Document <...>) */
#include <Limits.h>
#ifndef NO_MATHRTL
  #include <Float.h> 
  #define _USE_MATH_DEFINES
  #include <Math.h>
  #include <ErrNo.h>
#endif
#include <StdDef.h>
#include <StdLib.h>
#include <StdIo.h>
#include <ConIo.h>
#include <CType.h>
#include <TChar.h>
#include <Lm.h> /* NetShareGetInfo */
#include <RichEdit.h>
#include <CommCtrl.h>
#include <CommDlg.h>
#include <CdErr.h>
#include <ShlObj.h>
#include <ShellApi.h>
#include <ShLwApi.h>
#include <OleCtl.h> /* OleLoadPicture */
#include <PsApi.h>
#ifdef _MSC_VER
  #include <CrtDbg.h>
#endif
#ifndef NO_WINTERNAL
  #ifndef NO_NDK_FILES
    #include <uLib/NtTypes.h> /* Requires <ndk/Nnn.h> access to the NDK. */
  #else
    #include <WInternl.h> /* NT internals we may officially use in user mode. */
    typedef NTSTATUS*  PNTSTATUS; /* Forgotten in WInternl.h */
  #endif
  #ifndef _NTSECAPI_
    // As a cheat, define _NTDEF_ before including NtSecApi.h, to avoid
    // UNICODE_STRING clash. It's normally defined in NtDef.h, which can't
    // be coerced to coexist with WinNT.h et alumni in user mode.
    #define _NTDEF_
    #include <NtSecApi.h> // These LSA can coexist with user mode SDK stuff.
    #undef _NTDEF_
  #endif//ndef _NTSECAPI_
#else
  typedef LONG  NTSTATUS, *PNTSTATUS;
#endif

//==----------------------------------------------------------------------------

#ifdef __cplusplus
  #define BEGIN_EXTERN_C        extern "C" {
  #define END_EXTERN_C          } // extern "C"
  #define BEGIN_EXTERN_CPP      extern "C++" {
  #define END_EXTERN_CPP        } // extern "C++"
  #define BEGIN_NAMESPACE(name) namespace name {
  #define END_NAMESPACE(name)   } // namespace name
  #define BEGIN_ANONYMOUS       namespace { // anonymous
  #define END_ANONYMOUS         } // anonymous namespace
#else // C lacks those features..
  #define BEGIN_EXTERN_C
  #define END_EXTERN_C
  #define BEGIN_EXTERN_CPP
  #define END_EXTERN_CPP
  #define BEGIN_NAMESPACE(name)
  #define END_NAMESPACE(name)
  #define BEGIN_ANONYMOUS
  #define END_ANONYMOUS
#endif

#ifdef __cplusplus 
  #define DEF_(x) = x
#else
  #define DEF_(x) /* C doesn't have that feature */
#endif

//==----------------------------------------------------------------------------
//==----------------------------------------------------------------------------

#ifndef _in // Useful where lower case is more readable than the old IN/OUT ones.
  #define _in       
  #define _out      
  #define _inout    
  #define _opt      
  #define _optin    
  #define _optout   
  #define _optio    
#endif
#ifndef INOUT // Supplements to classic annotations (when you prefer upper case)
  #define INOUT     
  #define OPTIN     
  #define OPTOUT    
  #define OPTIO     
#endif

//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
//~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

extern HINSTANCE hInstance;  
extern HWND      hMainWnd;   
extern HWND      hCurrDlg;   
extern HACCEL    hMainAcc;   
extern HWND      hMdiClient; 

extern SECURITY_ATTRIBUTES DefSec; //= { sizeof(DefSec), NULL, TRUE };

extern SECURITY_DESCRIPTOR DefSecDesc; //= { 0,0,0,NULL,NULL,NULL,NULL };

#define USE_STATIC_SECDESC_INIT  0


//==----------------------------------------------------------------------------
//==----------------------------------------------------------------------------

//#ifdef WANT_LOCASE_TYPES
  #include <uLib/Types.h>
//#endif

#ifdef __DOXYGEN__
typedef bool bool_t; 
#endif

//+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
//+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

#ifndef CSTR // Transmutable (TCHAR) strings
  //rescinded//#define PSTR LPTSTR  // Changable ptr to changable char.
  #define TSTR      LPTSTR  
  #define CSTR      LPCTSTR 
#endif

#ifndef CCSTR
typedef const CSTR  CCSTR;
#endif

#ifndef PCUCHAR 
  #define PCUCHAR const unsigned char*
#endif

#ifndef ASTR // Explicit ANSI (or MultiByte) strings
#if TYPEDEF_STRINGS
typedef char*       ASTR;   
typedef const char* ACSTR;  
#else
  #define ASTR      LPSTR   
  #define ACSTR     LPCSTR  
#endif
typedef const ACSTR CCASTR; 
#endif

#ifndef MBSTR // Explicit MBCS strings (sometimes unsigned is mandated)
#if TYPEDEF_STRINGS
typedef UCHAR*       MBSTR;  
typedef const UCHAR* MBCSTR; 
#else
  #define MBSTR      PUCHAR
  #define MBCSTR     PCUCHAR
#endif
typedef const MBCSTR CCMBSTR; 
#endif

#ifndef WSTR // Explicit UNICODE strings
#if TYPEDEF_STRINGS
typedef wchar_t*        WSTR;  
typedef const wchar_t*  WCSTR; 
#else
  #define WSTR      LPWSTR     
  #define WCSTR     LPCWSTR    
#endif
typedef const WCSTR CCWSTR;    
#endif

#ifndef TCHAR_SIZE 
  #define TCHAR_SIZE  sizeof(TCHAR)
#endif
#ifndef WCHAR_SIZE 
  #define WCHAR_SIZE  sizeof(WCHAR)
#endif

#define _TBYTES( cch )  (cch * TCHAR_SIZE) 
#define _WBYTES( cch )  (cch * WCHAR_SIZE) 

#ifndef PTR_SIZE 
  #define PTR_SIZE  sizeof(void*)
#endif

//+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
//+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

// Note: The oddball reverse order of some type id declarations are due to doxygen's parser.

#ifndef UINT64
#if defined(_MSC_VER)
  typedef unsigned __int64   UINT64, *PUINT64;
  typedef signed __int64     INT64, *PINT64;
#elif defined(__GNUC__)
  typedef unsigned long long UINT64, *PUINT64;
  typedef signed long long   INT64,  *PINT64;
#else
  #error("Please add INT64/UINT64 declarations for Your compiler..")
  //.. or add your compiler to one of the previous clauses, if applicable.
#endif
#endif

#ifndef BYTE
typedef unsigned char   BYTE, *PBYTE;
typedef unsigned short  WORD, *PWORD;
typedef unsigned long   DWORD, *PDWORD;
#endif

#ifndef QWORD
typedef UINT64          QWORD, *PQWORD;
#endif

// Not really integers, but treated as such, and I don't want yet another group.

#ifndef NO_CONST_HANDLES
typedef const HANDLE    CHANDLE; 
typedef const HWND      CHWND;   
#endif

#ifndef __cplusplus
#ifndef __bool_defined
  #if 0
    typedef enum { false, true } bool; 
    //typedef enum : char { false, true } bool; //<< Alas.. Sizing requires C++
  #else
    typedef char  bool; 
    #define true  (1==1)
    #define false (1==0)
  #endif
  #define __bool_defined 1
#endif
#endif

//+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
//+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

#ifndef TWOCC 
typedef WORD  *PTWOCC, TWOCC;
#define MK_TWOCC( S2 )  (*(PTWOCC)(S2))
#endif

#ifndef FOURCC 
typedef DWORD  *PFOURCC, FOURCC;
#define MK_FOURCC( S4 ) (*(PFOURCC)(S4))
#endif

#ifndef EIGHTCC 
typedef QWORD  *PEIGHTCC, EIGHTCC;
#define MK_EIGHTCC( S8 )  (*(PEIGHTCC)(S8))
#endif

//+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
//+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

#ifndef LPCSIZE 
  typedef const SIZE *LPCSIZE;
#endif

// The quaint "plural" naming of the following two structs
// are dictated by compliance with the naming of POINTS (small point).

#pragma pack( push,2 )
#ifndef RECTS 
typedef struct _RECTS {
    SHORT  left;
    SHORT  top;
    SHORT  right;
    SHORT  bottom;
} *PRECTS, *LPRECTS, RECTS;
typedef const RECTS *LPCRECTS;
#endif

#ifndef SIZES 
typedef struct _SIZES {
    SHORT   cx;
    SHORT   cy;
} *PSIZES, *LPSIZES, SIZES;
typedef const SIZES *LPCSIZES;
#endif
#pragma pack( pop )

//==----------------------------------------------------------------------------
// compat Compiler/RTL Compatibility Issues
//==----------------------------------------------------------------------------

// PONDER: Migrate compatibility issues and other build options to separate file.
// e.g. #include <uLib/BuildCfg.h>

#if defined(_M_MRX000) || defined(_M_ALPHA) || defined(_M_PPC) || defined(_M_IA64) || defined(_M_AMD64)
  #define CPU_NEED_ALIGNMENT  1  // A good thing to know, lest things go sour.
#else
  #define CPU_NEED_ALIGNMENT  0
#endif

#if defined(_MSC_VER) //........................................................

  #define __thread_local  __declspec(thread) // In thread-local storage.
  #define __end_except    // Part of GCC SEH kludge.
  #define __end_finally   // Part of GCC SEH kludge.

  #define HAVE_STRUCTURED_EH // Have proper SEH support, a.k.a. Borland SEH.
  #define HAVE_SAFE_CSTRINGS // The nnn_s'es.
  //#define HAVE_SCALECOLOR_ASM // FIXME: ScaleColorRef (in _gradcolor.asm)

  // Debug versions of MSVC byte swappers are very inefficient,
  // so I rolled my own in _bswap.asm.

  #ifdef _DEBUG
    #define HAVE_BSWAP16_INTRINSIC  0
    #define HAVE_BSWAP32_INTRINSIC  0
    #define HAVE_BSWAP64_INTRINSIC  0
    #define HAVE_ASM_BSWAP          1
  #else
    #define HAVE_BSWAP16_INTRINSIC  1
    #define HAVE_BSWAP32_INTRINSIC  1
    #define HAVE_BSWAP64_INTRINSIC  1
  #endif

#elif defined(__GNUC__) //......................................................

  #define __thread_local __thread /* version specific? */

  #ifndef __forceinline
  #define __forceinline  __attribute__((always_inline))
  #endif

  #if (__GNUC__ >= 5)
  #define HAVE_SAFE_CSTRINGS
  #endif

  #ifndef HAVE_SAFE_CSTRINGS
  #pragma message("[uLib] ALERT: Circumventig safe string functions :ALERT")
  #define wcscpy_s( dst,dim,src )           wcscpy( dst,src )
  #define strcpy_s( dst,dim,src )           strcpy( dst,src )
  #define _tcscpy_s( dst,dim,src )          _tcscpy( dst,src )
  #define _tcsncpy_s( dst,dim,src,n )       _tcsncpy( dst,src,n )
  #define _stprintf_s( dst,dim,fmt, ... )   _stprintf( dst,fmt, __VA_ARGS__ )
  #define _vstprintf_s( dst,dim,fmt,va )    _vstprintf( dst,fmt,va )
  #define vsprintf_s( dst,dim,fmt,va )      vsprintf( dst,fmt,va )
  #define vswprintf_s( dst,dim,fmt,va )     vswprintf( dst,fmt,va )
  #define swprintf_s( dst,dim,fmt, ... )    swprintf( dst,fmt, __VA_ARGS__ )
  #endif

  #ifndef _ASSERTE
    #include <assert.h>
    #define _ASSERTE(e) assert(e)
  #endif

  #undef __STRICT_ANSI__ // MinGW tucks _strnicmp away behind STRICT_ANSI

  #if ((__GNUC__ >= 4) && (__GNUC_MINOR__ >= 8))
    #define HAVE_BSWAP16_INTRINSIC  1
    #define _byteswap_ushort  __builtin_bswap16
  #else
    #define HAVE_BSWAP16_INTRINSIC  0
    #define _byteswap_ushort  _bswap16
    #define __builtin_bswap16 _bswap16
  #endif

  #define HAVE_BSWAP32_INTRINSIC  1
  #define HAVE_BSWAP64_INTRINSIC  1
  #define _byteswap_ulong   __builtin_bswap32
  #define _byteswap_uint64  __builtin_bswap64

  #define HAVE_ASM_BSWAP  0 // I haven't written a GCC _bswapXX asm implementation

  // In case you really don't know, SEH is a method (invented by Borland) to
  // vector CPU fault interrupts to high level C++ code in user mode, and has
  // absolutely nothing to do with C++ try/catch (which is little more than
  // a compiler supported setjmp/longjmp user mode mechanism).
  //
  // GCC folks: Borland's previous patent on SEH has now been rescinded,
  // so you are free to include and improve C.Hornstrups implementation!

  #if 0 // Transparently (well.. almost) use GCC kludge for SEH.
    // Sorry: So far, I can't get PSEH or other to work with any of my GCC's.
    // Until I (or some contributor) can, SEH is only available with MSVC or
    // Borland builds, which means f.ex the kill-safe Thread is not available
    // in GCC builds. PONDER: Can clang get it right ?
    #include <pseh/pseh3.h>
    //#include <excpt.h>
    #define HAVE_STRUCTURED_EH

    #define __try         _SEH3_TRY
    #define __except      _SEH3_EXCEPT
    #define __finally     _SEH3_FINALLY
    #define __end_except  _SEH3_END     // GCC kludge
    #define __end_finally _SEH3_END     // -"-
    #define __leave       _SEH3_LEAVE

    #ifndef GetExceptionCode
    #define GetExceptionCode() _exception_code()
    #endif
    #ifndef GetExceptionInformation
    #define GetExceptionInformation() (PEXCEPTION_POINTERS)_exception_info()
    #endif
  #else
    #undef HAVE_STRUCTURED_EH
  #endif

#else
  #error("Please add __thread_local definition for your compiler")
#endif

//==----------------------------------------------------------------------------
//==----------------------------------------------------------------------------

#if defined(HAVE_STRUCTURED_EH)
  #define __except_execute  __except( EXCEPTION_EXECUTE_HANDLER )
#endif

// NOTE: These two are not really dependent on SEH availability.
// They might be used with RaiseException() as well.

#define FACILITY_ULIB     0x800  // Sets bit 27


#define MAKE_SOFTEXCEPTION( Severity, Facility, Exception ) \
    ((DWORD) ( \
    /* Severity code */     ((Severity)  <<  0) | \
    /* MS(0) or Cust(1) */  (1           << 29) | \
    /* Reserved(0) */       (0           << 28) | \
    /* Facility code */     ((Facility)  << 16) | \
    /* Exception code */    ((Exception) <<  0)))

//==----------------------------------------------------------------------------
// Boiler plate stuff and assembly language speed demons
//==----------------------------------------------------------------------------

#ifndef _WIN64
  #ifndef __assembly 
  #define __assembly  __declspec(naked)
  #endif
#endif

BEGIN_EXTERN_C
//+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
//+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

#if HAVE_BSWAP16_INTRINSIC
  #define _bswap16  _byteswap_ushort
#else 
  UINT16 __cdecl _bswap16( UINT16 Val );
  #define _byteswap_ushort _bswap16
  //BLD_INFO("[uLib] Using custom _bswap16 implementation.")
#endif

#if HAVE_BSWAP32_INTRINSIC
  #define _bswap32  _byteswap_ulong
#else 
  UINT32 __cdecl _bswap32( UINT32 Val );
  #define _byteswap_ulong  _bswap32
  //BLD_INFO("[uLib] Using custom _bswap32 implementation.")
#endif

#if HAVE_BSWAP64_INTRINSIC
  #ifndef _bswap64
    #define _bswap64  _byteswap_uint64
  #endif
#else 
  UINT64 __cdecl _bswap64( UINT64 Val );
  #define _byteswap_uint64 _bswap64
  //BLD_INFO("[uLib] Using custom _bswap64 implementation.")
#endif

//+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
//+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
#ifdef _MSC_VER

// Rotate left.. (_asmop.asm)

BYTE  __stdcall _rol8( BYTE value, BYTE bits ); 
WORD  __stdcall _rol16( WORD value, BYTE bits ); 
DWORD __stdcall _rol32( DWORD value, BYTE bits ); 
QWORD __stdcall _rol64( QWORD value, BYTE bits );

// Rotate right.. (_asmop.asm)

BYTE  __stdcall _ror8( BYTE value, BYTE bits ); 
WORD  __stdcall _ror16( WORD value, BYTE bits ); 
DWORD __stdcall _ror32( DWORD value, BYTE bits ); 
QWORD __stdcall _ror64( QWORD value, BYTE bits );

#else

  // Sorry; No GCC/GAS/NASM implementation, nor any C fallback yet...
  // <intrin.h> has some rotators...

#endif//def _MSC_VER
END_EXTERN_C

//==----------------------------------------------------------------------------
// bool_cast
//==----------------------------------------------------------------------------

#ifdef _MSC_VER
  #define DISABLE_BOOLCAST_WARNING  __pragma( warning( disable: 4800 ))
  #define REENABLE_BOOLCAST_WARNING __pragma( warning( default: 4800 ))
#else
  #define DISABLE_BOOLCAST_WARNING
  #define REENABLE_BOOLCAST_WARNING
#endif

#ifndef __bool_cast_defined
  DISABLE_BOOLCAST_WARNING // Warning 4800 is totally unwarranted here.


  bool __forceinline bool_cast( BOOL B52 ) { return (bool) B52; }
  //bool __forceinline bool_cast( BOOL B52 ) { return !!B52; } //<-- PONDER this cute idea..

  #define __bool_cast_defined
  REENABLE_BOOLCAST_WARNING
#endif

//==----------------------------------------------------------------------------
//==----------------------------------------------------------------------------

#define IS_WINNT(getver)    (DWORD( getver ) < 0x80000000) 
#define MAJ_WINVER(getver)  LOBYTE(LOWORD( getver )) 
#define MIN_WINVER(getver)  HIBYTE(LOWORD( getver )) 

BEGIN_EXTERN_C


bool IsWinVer( BYTE vMajor, BYTE vMinor, bool WinNT DEF_(true) );

bool IsWin7();      
bool IsWinVista();  
bool IsWinXP();     
bool IsWin2000();   
bool IsWinNT();     
bool IsWin98();     
bool IsWin95();     

bool IsWin64Bit();  


bool IsWow64();


void GetWinSystemInfo( SYSTEM_INFO* si );

END_EXTERN_C

//==----------------------------------------------------------------------------
//==----------------------------------------------------------------------------

BEGIN_EXTERN_C

long map( long x, long xMin, long xMax, long toMin, long toMax );

long constrain( long x, long lo, long hi );

short random( short iMin, short iMax );

void randomize();

long runningAvg( long Avg, long X, unsigned int Period );

ulong  ipow2( ushort expo );
uint64 ipow2x( ushort expo );

ushort ilog2( ulong X );
ushort ilog2x( uint64 X ); 

ushort ilog10( ulong X );
ushort ilog10x( uint64 X ); 

long double _root( long double base, long double X );

long double _log( long double base, long double X );

double _round( double x, unsigned char ndecimals );

bool _isprime( unsigned long X );

long double EngUnits( long double Value, int* pExpo );
// (UtilFunc.cpp)

END_EXTERN_C

#ifdef __cplusplus

// A few function templates. (I normally prefer not to template due to bloat-risk).
// Note the disambiguating underscore in each one.


template <typename T>
    T map_( T x, T xMin, T xMax, T toMin, T toMax )
    {
        return toMin + ((x - xMin) * (toMax - toMin)) / (xMax - xMin);
        // I.e: toMin + xRelative * toRange / fromRange
        // ---> toMin + mulDiv_<T>( x - xMin, toMax - toMin, xMax - xMin );
    }


template <typename T>
    T constrain_( T x, T lo, T hi )
    {
        return (x > hi ? hi : (x < lo ? lo : x));
    }

template <typename T> T min_( T a, T b ) { return (a < b ? a : b); }
template <typename T> T max_( T a, T b ) { return (a > b ? a : b); }


template <typename T>
    T runningAvg_( T Avg, T X, unsigned int Period )
    {
        return (X + (Avg * ((T)Period-1))) / (T)Period;
    }


template <typename T>
    T mulDiv_( const T X, const T Mu, const T Dv )
    {
        return X * Mu / Dv;
    }

#endif//def __cplusplus

#ifdef NOMINMAX // Located here, for proximity with min_/max_ above.
  // Let's treat this case a bit more radical than <windef.h>
  #undef min
  #undef max
#else
  #ifndef min
    #define min(a,b) ((a)<(b)?(a):(b))
  #endif
  #ifndef max
    #define max(a,b) ((a)>(b)?(a):(b))
  #endif
#endif

//==----------------------------------------------------------------------------
// Macros
//==----------------------------------------------------------------------------


#define dimof(x)  (sizeof(x)/sizeof(x[0]))

#if 1
  #ifndef offsetof
    #ifdef __cplusplus
      #define offsetof( stype,field ) ((size_t)&reinterpret_cast<char const volatile&>((((stype*)0)->field)))
    #else
      #define offsetof( stype,field ) ((size_t)&(((stype*)0)->field))
    #endif
  #endif
  #ifndef structof 
    #define structof( faddr,stype,field ) ((stype*)( (ULONG_PTR)(faddr) - (ULONG_PTR)offsetof(stype,field)))
    #define fieldsize( stype,field )     sizeof(((stype*)0)->field) 
  #endif
  #define struct_subsize( stype,field )    (offsetof( stype,field ) + fieldsize( stype,field ))
#endif

#define LITERAL(type,x)     (*((type*)&(x))) 
#define UNUSED(x)           ((void)&(x))     
#define ZEROMEM(var)        memset( &(var),0,sizeof(var) ) 
#define YIELD()             SleepEx( 0, true ) 

#define SWAP_INPLACE(a,b)   a ^= b ^= a ^= b 


#ifndef ROUND_UP 
#define ROUND_UP(x,chunk)   (((UINT_PTR(x) + (chunk) - 1) / (chunk)) * (chunk))
#define ROUND_DOWN(x,chunk) ((UINT_PTR(x) / (chunk)) * (chunk))
#endif

#ifndef ROUND_UP2 
#define ROUND_UP2(x,chunk)   ((UINT_PTR(x)+((chunk)-1)) & -(chunk))
#define ROUND_DOWN2(x,chunk) (UINT_PTR(x) & -(chunk))
#endif

#ifndef ALIGN_VALUE 
#define ALIGN_VALUE(x,aln) (INT_PTR(x) + ((~INT_PTR(x)+1) & (aln-1)))
#endif

#define DELETE_ARRAY(A)     if (A) { delete[] (A); (A) = NULL; }
#define DELETE_OBJ(Obj)     if (Obj) { delete (Obj); (Obj) = NULL; }
#define RELEASE_OBJ(Ifc)    if (Ifc) { (Ifc)->Release(); (Ifc) = NULL; }
#define COMTASK_FREE(Obj)   if (Obj) { CoTaskMemFree( PVOID(Obj) ); (Obj) = NULL; }

#define _BAD_HANDLE         INVALID_HANDLE_VALUE 


#define BAD_HANDLE(hnd)     ((hnd) == _BAD_HANDLE || !(hnd))
#define GOOD_HANDLE(hnd)    ((hnd) != _BAD_HANDLE && (hnd) != NULL)
#define CHK_HANDLE(hnd)     ((hnd) == _BAD_HANDLE ? NULL : (hnd))

#define _BAD_ATTRIBUTE      INVALID_FILE_ATTRIBUTES 


#define BITS_SET(bits,x)    (((x) & (bits)) == (bits))  
#define BITS_RST(bits,x)    (((x) & (bits)) == 0)      
#define HAVE_BITS(var,mask) BITS_SET( (mask),(var) )  

#define ALL_BITS            0xFFFFFFFF 
#define ALL_BITS64          0xFFFFFFFFFFFFFFFF 
#ifndef _BV
  #define _BV(bitNr)        (UINT_PTR(1) << (bitNr)) 
#endif

#ifndef PP_NSTR             
  #define PP_NSTR(x)        PP_NSTR_(x)
  #define PP_NSTR_(x)       #x
#endif

#ifndef PP_STR              
  #define PP_STR(x)         _T(#x)
#endif

#ifndef CCSTR_LENGTH        
  #define CCSTR_LENGTH( s ) (dimof(s) - sizeof(*s))
#endif

#ifndef CCH_AVAIL           
  #define CCH_AVAIL( buf,pz ) (dimof(buf) - (CSTR(pz) - CSTR(buf)))
#endif

#ifndef _ODS                
  #define _ODS( s )         OutputDebugString( s )
  #define _ODSA( s )        OutputDebugStringA( s )
  #define _ODSW( s )        OutputDebugStringW( s )
#endif


#ifndef _CASSERT
  #if _DEBUG
    #define _CASSERT(id,expr) typedef char __cassert_##id[ (expr) ? +1 : -1 ]
  #else
    #define _CASSERT(id,expr)
  #endif
#endif


#ifndef OFFSETOFCLASS // Borrowed from ShLwApi, who borrowed it from ATL.
#define OFFSETOFCLASS( base, derived ) \
    ((DWORD)(DWORD_PTR) (STATIC_CAST(base*)( (derived*)8 )) - 8)
#endif

//==----------------------------------------------------------------------------
//==----------------------------------------------------------------------------

#ifndef WINDOWPROC
  #define WINDOWPROC  LRESULT CALLBACK 
  #define DIALOGPROC  DRESULT CALLBACK 
  #ifdef _WIN64
    #define DRESULT   INT_PTR
  #else
    #define DRESULT   BOOL
  #endif
#endif

#ifndef WINHOOKPROC 
  #define WINHOOKPROC  LRESULT CALLBACK
  // Full signature: LRESULT (CALLBACK* HOOKPROC)( int code, WPARAM wp, LPARAM lp );
#endif

#ifndef THREADPROC 
  #define THREADPROC  DWORD WINAPI
#endif

#ifndef EXITPROC 
  #define EXITPROC    void __cdecl
#endif

//==----------------------------------------------------------------------------
//==----------------------------------------------------------------------------

#define GENERIC_RW      (GENERIC_READ | GENERIC_WRITE)
#define FILE_SHARE_NONE 0
#define FILE_SHARE_RW   (FILE_SHARE_READ | FILE_SHARE_WRITE)
#define FILE_SHARE_ALL  (FILE_SHARE_RW| FILE_SHARE_DELETE)

#define FILE_MAP_RW     (FILE_MAP_READ | FILE_MAP_WRITE)
#define KEY_RW          (KEY_READ | KEY_WRITE)

#ifndef GENERIC_ACCESS
  #define GENERIC_ACCESS  (GENERIC_RW | GENERIC_EXECUTE | GENERIC_ALL)
#endif

#ifndef ALL_SECURITY_INFORMATION
#define ALL_SECURITY_INFORMATION \
    ( OWNER_SECURITY_INFORMATION | GROUP_SECURITY_INFORMATION \
    | DACL_SECURITY_INFORMATION | SACL_SECURITY_INFORMATION )
#endif

#ifndef WINSTA_ALL
#define WINSTA_ALL \
    ( WINSTA_ENUMDESKTOPS | WINSTA_READATTRIBUTES | WINSTA_ACCESSCLIPBOARD \
    | WINSTA_CREATEDESKTOP | WINSTA_WRITEATTRIBUTES | WINSTA_ACCESSGLOBALATOMS \
    | WINSTA_EXITWINDOWS | WINSTA_ENUMERATE | WINSTA_READSCREEN \
    | STANDARD_RIGHTS_REQUIRED )
#endif

#ifndef DESKTOP_ALL
#define DESKTOP_ALL \
    ( DESKTOP_READOBJECTS | DESKTOP_CREATEWINDOW | DESKTOP_CREATEMENU \
    | DESKTOP_HOOKCONTROL | DESKTOP_JOURNALRECORD | DESKTOP_JOURNALPLAYBACK \
    | DESKTOP_ENUMERATE | DESKTOP_WRITEOBJECTS | DESKTOP_SWITCHDESKTOP \
    | STANDARD_RIGHTS_REQUIRED )
#endif

#ifndef NO_UNDOC_WINMSG
//==----------------------------------------------------------------------------
//==----------------------------------------------------------------------------

#ifndef WM_FULLSCREEN
    #define WM_FULLSCREEN           0x003A
    #define WM_CLIENTSHUTDOWN       0x003B
    #define WM_DDEMLEVENT           0x003C
#endif
#ifndef WM_CALCSCROLL
    #define WM_CALCSCROLL           0x003F 
#endif
#ifndef WM_SYNCPAINT
    #define WM_SYNCPAINT            0x0088
#endif
#ifndef WM_UAHDESTROYWINDOW         // Aero, undocumented
    #define WM_UAHDESTROYWINDOW     0x0090
    #define WM_UAHDRAWMENU          0x0091
    #define WM_UAHDRAWMENUITEM      0x0092
    #define WM_UAHINITMENU          0x0093
    #define WM_UAHMEASUREMENUITEM   0x0094
    #define WM_UAHNCPAINTMENUPOPUP  0x0095
    #define WM_UAHUPDATE            0x0096
#endif
#ifndef WM_NCUAHDRAWCAPTION         // Aero, undocumented
    #define WM_NCUAHDRAWCAPTION     0x00AE
    #define WM_NCUAHDRAWFRAME       0x00AF
#endif
#ifndef EM_MSGMAX
    #define EM_MSGMAX               0x00DA
#endif
#ifndef WM_SYSTIMER
    #define WM_SYSTIMER             0x0118 
#endif
#ifndef WM_GETISHELLBROWSER // Revealed by Ivo Beltcher. Thank You.
  #define WM_GETISHELLBROWSER       (WM_USER+7)
#endif

#endif//ndef NO_UNDOC_WINMSG
//==----------------------------------------------------------------------------
//==----------------------------------------------------------------------------

#define DOT       _T('.')
#define BSLASH    _T('\\')
#define SLASH     _T('/')
#define SPACE     _T(' ')
#define QUOTE     _T('"')
#define SQUOTE    _T('\'')
#define COLON     _T(':')
#define SEMICOLON _T(';')
#define COMMA     _T(',')
#define EQUALS    _T('=')
#define PERCENT   _T('%')
#define HASH      _T('#')
// Common control chars that have C escapes
#define TAB       _T('\t')
#define CR        _T('\r')
#define LF        _T('\n')
// Frequently needed short strings
#define DOTDOT    _T("..")
#define CRLF      _T("\r\n")
#define S_BLANK   _T("")

#ifndef NO_CONTROL_CHARS
//==----------------------------------------------------------------------------
//==----------------------------------------------------------------------------

#define _NUL    _T('\x00')  
// Start of keyboard range
#define _SOH    '\x01'  
#define _STX    '\x02'  
#define _ETX    '\x03'  
#define _EOT    '\x04'  
#define _ENQ    '\x05'  
#define _ACK    '\x06'  
#define _BEL    '\x07'  
#define _BS     '\x08'  
#define _HT     '\x09'  
#define _LF     '\x0A'  
#define _VT     '\x0B'  
#define _FF     '\x0C'  
#define _CR     '\x0D'  
#define _SO     '\x0E'  
#define _SI     '\x0F'  
#define _DLE    '\x10'  
#define _DC1    '\x11'  
#define _DC2    '\x12'  
#define _DC3    '\x13'  
#define _DC4    '\x14'  
#define _NAK    '\x15'  
#define _SYN    '\x16'  
#define _ETB    '\x17'  
#define _CAN    '\x18'  
#define _EM     '\x19'  
#define _SUB    '\x1A'  
// End of keyboard range
#define _ESC    '\x1B'  
#define _FS     '\x1C'  
#define _GS     '\x1D'  
#define _RS     '\x1E'  
#define _US     '\x1F'  

#define _XON    _DC1        
#define _XOFF   _DC3        
#define _EOF    _SUB        

#endif//ndef NO_CONTROL_CHARS
// end comn ==============================================================================
#endif //ndef _uLib_Common_h_incl_
// EOF