helpers.h

Go to the documentation of this file.

#pragma once

#ifndef HELPERS_H
#define HELPERS_H


/**
    \file
    \brief Contains helper macros and functions.
*/




#include <string>
#include <cctype>

#include <stdint.h>




/*==============================================================================
    ARRAYLENGTH macro
==============================================================================*/


/// Calculates the number of elements in the array \p aa by dividing the size of \p aa by the size of each element.
#define ARRAYLENGTH( aa ) \
    ( sizeof( aa ) / sizeof( ( aa )[ 0 ] ) )




/*==============================================================================
    STDCALL macro
==============================================================================*/


#if defined( _WIN32 )
#define STDCALL __stdcall
#else
#define STDCALL
#endif    // _WIN32




/*==============================================================================
    ALIGN macro
==============================================================================*/


#if defined( __GNUC__ )
#define ALIGN( aa ) __attribute__(( aligned( aa ) ))
#elif defined( _WIN32 )
#define ALIGN( aa ) __declspec( align( aa ) )
#endif    // __GNUC__, _WIN32




/*==============================================================================
    Square helper function
==============================================================================*/


/// \brief Returns the square of its argument.
template< typename t_Type >
inline t_Type Square( t_Type const& value ) {

    return( value * value );
}




/*==============================================================================
    Cube helper function
==============================================================================*/


/// \brief Returns the cube of its argument.
template< typename t_Type >
inline t_Type Cube( t_Type const& value ) {

    return( value * value * value );
}




/*==============================================================================
    CollapseWhitespace helper function
==============================================================================*/


/**
    \brief Removes leading/trailing whitespace, and collapses internal whitespace.

    \param source  String in which to collapse whitespace.
    \param space   Character with which to replace internal stretches of whitespace.
    \return  String with leading/trailing whitespace removed, and internal whitespace collapsed.

    The purpose of this function is to make strings which may contain
    leading/trailing whitespace, and annoying stretches of internal space
    (including newlines and tabs), somewhat "cleaner" to print or display in a
    dialog. In addition to the removal of leading and trailing whitespace, all
    "stretches" of consecutive whitespace characters (found using \c
    std::isspace) in the interior of the string will be replaced with (one copy
    of) the given \p space character.
*/
inline std::string CollapseWhitespace( std::string const& source, char const space = ' ' ) {

    std::string result;

    std::string::const_iterator ii    = source.begin();
    std::string::const_iterator iiEnd = source.end();

    bool first = true;
    for ( ; ( ii != iiEnd ) && isspace( *ii ); ++ii );
    while ( ii != iiEnd ) {

        std::string::const_iterator lower = ii;
        for ( ; ( ii != iiEnd ) && ( ! isspace( *ii ) ); ++ii );

        if ( ! first )
            result.append( 1, space );
        result.append( lower, ii );
        first = false;

        for ( ; ( ii != iiEnd ) && isspace( *ii ); ++ii );
    }

    return result;
}




/*==============================================================================
    CountBits helper functions
==============================================================================*/


/// \brief Returns the number of set bits in an 8-bit integer.
inline uint8_t CountBits( uint8_t number ) {

    static_assert( ( sizeof( number ) == 1 ), "uint8_t should be one byte long" );
    number = ( number & 0x55 ) + ( ( number >> 1 ) & 0x55 );
    number = ( number & 0x33 ) + ( ( number >> 2 ) & 0x33 );
    number = ( number & 0x0f ) +   ( number >> 4 );
    return number;
}


/// \brief Returns the number of set bits in a 16-bit integer.
inline uint16_t CountBits( uint16_t number ) {

    static_assert( ( sizeof( number ) == 2 ), "uint16_t should be two bytes long" );
    number = ( number & 0x5555 ) + ( ( number >> 1 ) & 0x5555 );
    number = ( number & 0x3333 ) + ( ( number >> 2 ) & 0x3333 );
    number = ( number & 0x0f0f ) + ( ( number >> 4 ) & 0x0f0f );
    number = ( number & 0x00ff ) +   ( number >> 8 );
    return number;
}


/// \brief Returns the number of set bits in a 32-bit integer.
inline uint32_t CountBits( uint32_t number ) {

    static_assert( ( sizeof( number ) == 4 ), "uint32_t should be four bytes long" );
    number = ( number & 0x55555555 ) + ( ( number >>  1 ) & 0x55555555 );
    number = ( number & 0x33333333 ) + ( ( number >>  2 ) & 0x33333333 );
    number = ( number & 0x0f0f0f0f ) + ( ( number >>  4 ) & 0x0f0f0f0f );
    number = ( number & 0x00ff00ff ) + ( ( number >>  8 ) & 0x00ff00ff );
    number = ( number & 0x0000ffff ) +   ( number >> 16 );
    return number;
}


/// \brief Returns the number of set bits in a 64-bit integer.
inline uint64_t CountBits( uint64_t number ) {

    static_assert( ( sizeof( number ) == 8 ), "uint64_t should be eight bytes long" );
    number = ( number & 0x5555555555555555ull ) + ( ( number >>  1 ) & 0x5555555555555555ull );
    number = ( number & 0x3333333333333333ull ) + ( ( number >>  2 ) & 0x3333333333333333ull );
    number = ( number & 0x0f0f0f0f0f0f0f0full ) + ( ( number >>  4 ) & 0x0f0f0f0f0f0f0f0full );
    number = ( number & 0x00ff00ff00ff00ffull ) + ( ( number >>  8 ) & 0x00ff00ff00ff00ffull );
    number = ( number & 0x0000ffff0000ffffull ) + ( ( number >> 16 ) & 0x0000ffff0000ffffull );
    number = ( number & 0x00000000ffffffffull ) +   ( number >> 32 );
    return number;
}




/*==============================================================================
    CountLowBits helper functions
==============================================================================*/


/// \brief Returns the number of bits required to represent the given 8-bit integer. The number of bits required to represent 0 is taken to be 0.
inline unsigned int CountLowBits( uint8_t number ) {

    static_assert( ( sizeof( number ) == 1 ), "uint8_t should be one byte long" );

    unsigned int bits = 0;

    if ( number & 0xf0 ) {

        bits += 4;
        number >>= 4;
    }

    if ( number & 0x0c ) {

        bits += 2;
        number >>= 2;
    }

    if ( number & 0x02 )
        bits += 2;
    else if ( number & 0x01 )
        ++bits;

    return bits;
}


/// \brief Returns the number of bits required to represent the given 16-bit integer. The number of bits required to represent 0 is taken to be 0.
inline unsigned int CountLowBits( uint16_t number ) {

    static_assert( ( sizeof( number ) == 2 ), "uint16_t should be two bytes long" );

    unsigned int bits = 0;

    if ( number & 0xff00 ) {

        bits += 8;
        number >>= 8;
    }

    if ( number & 0x00f0 ) {

        bits += 4;
        number >>= 4;
    }

    if ( number & 0x000c ) {

        bits += 2;
        number >>= 2;
    }

    if ( number & 0x0002 )
        bits += 2;
    else if ( number & 0x0001 )
        ++bits;

    return bits;
}


/// \brief Returns the number of bits required to represent the given 32-bit integer. The number of bits required to represent 0 is taken to be 0.
inline unsigned int CountLowBits( uint32_t number ) {

    static_assert( ( sizeof( number ) == 4 ), "uint32_t should be four bytes long" );

    unsigned int bits = 0;

    if ( number & 0xffff0000 ) {

        bits += 16;
        number >>= 16;
    }

    if ( number & 0x0000ff00 ) {

        bits += 8;
        number >>= 8;
    }

    if ( number & 0x000000f0 ) {

        bits += 4;
        number >>= 4;
    }

    if ( number & 0x0000000c ) {

        bits += 2;
        number >>= 2;
    }

    if ( number & 0x00000002 )
        bits += 2;
    else if ( number & 0x00000001 )
        ++bits;

    return bits;
}


/// \brief Returns the number of bits required to represent the given 64-bit integer. The number of bits required to represent 0 is taken to be 0.
inline unsigned int CountLowBits( uint64_t number ) {

    static_assert( ( sizeof( number ) == 8 ), "uint64_t should be eight bytes long" );

    unsigned int bits = 0;

    if ( number & 0xffffffff00000000ull ) {

        bits += 32;
        number >>= 32;
    }

    if ( number & 0x00000000ffff0000ull ) {

        bits += 16;
        number >>= 16;
    }

    if ( number & 0x000000000000ff00ull ) {

        bits += 8;
        number >>= 8;
    }

    if ( number & 0x00000000000000f0ull ) {

        bits += 4;
        number >>= 4;
    }

    if ( number & 0x000000000000000cull ) {

        bits += 2;
        number >>= 2;
    }

    if ( number & 0x0000000000000002ull )
        bits += 2;
    else if ( number & 0x0000000000000001ull )
        ++bits;

    return bits;
}




#endif    // HELPERS_H