UTMisc.h

Go to the documentation of this file.

//==================================================================================================
// Copyright (C) 2010  Brian Tietz    sdbtietz at yahoo dot com
//
// This program is free software; you can redistribute it and/or modify it under the terms of the
// GNU General Public License as published by the Free Software Foundation, version 2.0 of the
// License.
//
// This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without
// even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
// General Public License for more details.
//
// You should have received a copy of the GNU General Public License along with this program; if
// not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
// 02110-1301, USA.
//
// For commercial software, the copyright holder (Brian Tietz, email sdbtietz at yahoo dot com)
// reserves the right and is willing to waive the proprietary source code disclosure aspects of that
// license as applied to the UT library in exchange for either substantial contributions to the
// development of the UT library or other forms of compensation.  Any such waiver must be
// established in writing between the copyright holder and the commercial entity obtaining such a
// waiver.
//==================================================================================================


#ifndef _UT_H_
#error "DO NOT INCLUDE THIS FILE - INCLUDE UT.h INSTEAD"
#endif


EXTERN_C_BEGIN


//==================================================================================================
//=== Basic types
//==================================================================================================

typedef unsigned int        uint;

typedef unsigned char       uint8;

typedef signed char         int8;

typedef unsigned short int  uint16;

typedef signed short int    int16;

typedef unsigned int        uint32;     // Note: long int is 64-bits with gcc for x86_64

typedef signed int          int32;      // Note: long int is 64-bits with gcc for x86_64

typedef unsigned long long  uint64;

typedef signed long long    int64;

typedef uint8               byte;

typedef uint8               ascii7;

typedef uint8               utf8;

typedef const char          stringliteral;

#if POINTER_IS_32_BIT
typedef uint32              ptr_as_uint_t;
#elif POINTER_IS_64_BIT
typedef uint64              ptr_as_uint_t;
#else
#error "UT target platform header must define POINTER_IS_32_BIT or POINTER_IS_64_BIT"
#endif


//==================================================================================================
//=== Simple value manipulation macros
//==================================================================================================

#ifndef min
#define min( a, b )                                     ( ( (a) < (b) ) ? (a) : (b) )
#endif

#ifndef max
#define max( a, b )                                     ( ( (a) > (b) ) ? (a) : (b) )
#endif

#ifndef abs
#define abs(value)                                      ( ( (value) > 0 ) ? (value) : -(value) )
#endif

#define div_round( numer, denom )                       ( ( (numer) + (denom)/2 ) / (denom) )

#define div_round_up( numer, denom )                    ( ( (numer) + (denom) - 1 ) / (denom) )

#define four_cc( a, b, c, d )                           ( (a<<24) | (b<<16) | (c<<8) | (d) )

#define sizeof_array_element(object)                    (sizeof(object[2]) / 2)


//==================================================================================================
//=== Self documentation aids
//==================================================================================================

#define takes

#define gives

#define out


//==================================================================================================
//=== Convenience macros for typical mode_t uses
//==================================================================================================

#define S_IRWUSR (S_IRUSR | S_IWUSR)

#define S_IRWGRP (S_IRGRP | S_IWGRP)

#define S_IRWOTH (S_IROTH | S_IWOTH)


//==================================================================================================
//=== Cleaner way to distinguish prefix and postfix (++i or i++) with operator overloading
//==================================================================================================

#define postfix int


//==================================================================================================
//=== System performance information
//==================================================================================================

extern UT_EXPORT void get_memory_info(  out uint32* total_phys_kb,
                                        out uint32* total_virt_kb,
                                        out uint32* free_phys_kb,
                                        out uint32* free_virt_kb );

extern UT_EXPORT void get_cpu_utilization( out int* highest_of_any_one_core, out int* aggregate );


//==================================================================================================
//=== Improved time functions
//==================================================================================================

typedef struct
{
    uint16 year;            
    uint8  month;           
    uint8  day_of_week;     
    uint8  day;             
    uint8  hour;            
    uint8  minute;          
    uint8  second;          
    uint32 microsecond;     
} DateTime_t;


extern UT_EXPORT void get_date_time(out DateTime_t* date_time);

typedef int64 ustime_t;

extern UT_EXPORT ustime_t   system_time_us();

typedef int32 mstime_t;

extern UT_EXPORT mstime_t   system_time_ms();

typedef int32 roughtime_t;

extern UT_EXPORT roughtime_t    rough_time_ms();


//==================================================================================================
//=== Synchronization utilities
//==================================================================================================

extern UT_EXPORT int32 atomic_add( volatile int32* value_pointer, int32 add );

extern UT_EXPORT bool atomic_add_if_greater(    volatile int32* value_pointer,
                                                int32 add_value,
                                                int32 if_greater_than );

extern UT_EXPORT bool atomic_add_if_less(   volatile int32* value_pointer,
                                            int32 add_value,
                                            int32 if_less_than );


//==================================================================================================
//=== Automatically seeded random number generator
//==================================================================================================

extern UT_EXPORT int seeded_rand15();


extern UT_EXPORT int32 seeded_rand(int bits);


extern UT_EXPORT int32 seeded_rand_range( int32 from_val, int32 to_val );


extern UT_EXPORT int64 seeded_rand_range64( int64 from_val, int64 to_val );


//==================================================================================================
//=== Case-insensitive string functions, but which are safe with international characters
//==================================================================================================

extern UT_EXPORT int stricmp_utf8( stringliteral* a, stringliteral* b );


extern UT_EXPORT int strnicmp_utf8( stringliteral* a, stringliteral* b, int len );


extern UT_EXPORT stringliteral* stristr_utf8( stringliteral* haystack, stringliteral* needle );


extern UT_EXPORT stringliteral* strnistr_utf8(  stringliteral* haystack,
                                                int haystack_length,
                                                stringliteral* needle,
                                                int needle_length );


//==================================================================================================
//=== Bit masking, counting, and flipping functions
//==================================================================================================

extern UT_EXPORT uint8  mask_ls_bits_on8(uint on_bit_count);

extern UT_EXPORT uint16 mask_ls_bits_on16(uint on_bit_count);

extern UT_EXPORT uint32 mask_ls_bits_on32(uint on_bit_count);

extern UT_EXPORT uint64 mask_ls_bits_on64(uint on_bit_count);

extern UT_EXPORT uint8  mask_ms_bits_on8(uint on_bit_count);

extern UT_EXPORT uint16 mask_ms_bits_on16(uint on_bit_count);

extern UT_EXPORT uint32 mask_ms_bits_on32(uint on_bit_count);

extern UT_EXPORT uint64 mask_ms_bits_on64(uint on_bit_count);

extern UT_EXPORT uint   count_bits_on8(uint8 value);

extern UT_EXPORT uint   count_bits_on16(uint16 value);

extern UT_EXPORT uint   count_bits_on32(uint32 value);

extern UT_EXPORT uint   count_bits_on64(uint64 value);

extern UT_EXPORT int    ls_on_bit_index8(uint8 value);

extern UT_EXPORT int    ls_on_bit_index16(uint16 value);

extern UT_EXPORT int    ls_on_bit_index32(uint32 value);

extern UT_EXPORT int    ls_on_bit_index64(uint64 value);

extern UT_EXPORT int    ms_on_bit_index8(uint8 value);

extern UT_EXPORT int    ms_on_bit_index16(uint16 value);

extern UT_EXPORT int    ms_on_bit_index32(uint32 value);

extern UT_EXPORT int    ms_on_bit_index64(uint64 value);

extern UT_EXPORT uint8  flip_bit_order8(uint8 value);

extern UT_EXPORT uint16 flip_bit_order16(uint16 value);

extern UT_EXPORT uint32 flip_bit_order32(uint32 value);

extern UT_EXPORT uint64 flip_bit_order64(uint64 value);


EXTERN_C_END