comdef.h
=============================================================================

    Various utility inline functions, such as min(), max() and the bit
    array manipulation macros.


    MIN
    -------------------------------------------------------------------------

        Summary   Return the smaller of two elements

        Syntax    const Type& min(const Type &a, const Type &b);

        Remarks   This function uses templatized implementation to provide
                  type safety and also avoid the common pitfalls with the
                  standard macros. It returns a reference to the element
                  which is smaller of the two. Note that the returned value
                  cannot be used as a lvalue (i.e. in assignment statements)

        Return    Constant reference to smaller element


    MAX
    -------------------------------------------------------------------------

        Summary   Return the larger of two elements

        Syntax    const Type& max(const Type &a, const Type &b);

        Remarks   This function uses templatized implementation to provide
                  type safety and also avoid the common pitfalls with the
                  standard macros. It returns a reference to the element
                  which is larger of the two. Note that the returned value
                  cannot be used as a lvalue (i.e. in assignment statements)

        Return    Constant reference to larger element


    SWAP
    -------------------------------------------------------------------------

        Summary   Swaps two elements of any type

        Syntax    void swap(ClassType &a, ClassType &b);

        Remarks   Another templatized implementation. This function will
                  simply swap the values of 'a' and 'b'.

        Return    Nothing


    BIT MANIPULATION
    -------------------------------------------------------------------------

        Summary   Macros for manipulating individual bits in integral types

        Syntax    Boolean iTestBit(type value, int bitno);
                  void    iSetBit(type value, int bitno);
                  void    iClearBit(type value, int bitno);
                  void    iToggleBit(type value, int bitno);

        Remarks   These macros (although they look here like functions) can
                  be used for manipulating individual bits in any of the
                  integral types allowed in C++ (char, int, long, and any
                  of the sign variations). The 'value' parameter can be
                  any of these simple data types. The 'bitno' argument
                  specifies the bit number to perform the operation on. This
                  number varies from 0 to 31, depending on the type of the
                  'value' (chars range from 0 to 7, short ints from 0 to 15,
                  and long ints - from 0 to 31). Bits are numbered from right
                  to left.

                  iTestBit() tests whether the specified bit is ON or OFF;
                  iSetBit() sets the bit to ON regardless of current value;
                  iClearBit() sets the bit to OFF regardless of current value
                  iToggleBit() toggles the bit: ON becomes OFF and vice versa

        Return    iTestBit() returns True if the bit is ON, False otherwise


    BIT MANIPULATION FOR ARRAYS
    -------------------------------------------------------------------------

        Summary   Macros for manipulating individual bits in arrays of char

        Syntax    Boolean TestBit(char *array, int bitno);
                  void    SetBit(char *array, int bitno);
                  void    ClearBit(char *array, int bitno);
                  void    ToggleBit(char *array, int bitno);

        Remarks   These macros (although they look here like functions) can
                  be used for manipulating individual bits in arrays of 8-bit
                  chars. Bits in the array are numbered consecutively,
                  starting from 0, up to the number of chars in the array
                  multiplied by 8 minus 1 (an array of 10 chars will hold
                  80 bits, numbered from 0 to 79). The bits are numbered from
                  right to left withing the individual chars, and the chars -
                  from left to right. That is, bit number 2, would be in the
                  array[0] char, third bit from right to left. Conversely,
                  bit 13 would be in array[1] (second char), the 6th bit
                  from right to left. Since all this sounds confusing, the
                  utility of these macros should be appreciated.

                  TestBit() tests whether the specified bit is ON or OFF;
                  SetBit() sets the bit to ON regardless of current value;
                  ClearBit() sets the bit to OFF regardless of current value
                  ToggleBit() toggles the bit: ON becomes OFF and vice versa

        Return    TestBit() returns True if the bit is ON, False otherwise

