1 /** 2 * @namespace biewlib 3 * @file biewlib/biewlib.h 4 * @brief This file contains extensions of standard C library, that needed 5 * for BIEW project. 6 * @version - 7 * @remark this source file is part of Binary vIEW project (BIEW). 8 * The Binary vIEW (BIEW) is copyright (C) 1995 Nickols_K. 9 * All rights reserved. This software is redistributable under the 10 * licence given in the file "Licence.en" ("Licence.ru" in russian 11 * translation) distributed in the BIEW archive. 12 * @note Requires POSIX compatible development system 13 * 14 * @author Nickols_K 15 * @since 1995 16 * @note Development, fixes and improvements 17 **/ 18 #ifndef __BIEWLIB_H 19 #define __BIEWLIB_H 1 20 21 typedef enum { False = 0, True = 1 }tBool; /**< This is the data type used to represent boolean objects */ 22 23 #ifndef __NORECURSIVE 24 #ifndef __SYS_DEP_H 25 #include "biewlib/sysdep/_sys_dep.h" 26 #endif 27 28 #ifndef __OS_DEP_H 29 #include "biewlib/sysdep/__os_dep.h" 30 #endif 31 32 #ifndef __HRD_INF_H 33 #include "biewlib/sysdep/_hrd_inf.h" 34 #endif 35 36 #endif 37 38 #ifdef __cplusplus 39 extern "C" { 40 #endif 41 42 #define TESTFLAG(x,y) (((x) & (y)) == (y)) /**< Test y bits in x */ 43 #define UNUSED(x) ((void)(x)) /**< Removes warning about unused arguments */ 44 45 typedef int tCompare; /**< This is the data type used to represent comparition results */ 46 47 /** Pointer to a user supplied function that compares array elements. 48 * @return tCompare value indicated relationship between elements of array: 49 if e1 < e2, return < 0 50 if e1 > e2, return > 0 51 if e1 == e2, return = 0 52 * @param e1,e2 pointers to array elements 53 **/ 54 typedef tCompare (__FASTCALL__ *func_compare)(const void __HUGE__ *e1,const void __HUGE__ *e2); 55 56 /** Implements quick sort algorithm. 57 * @return none 58 * @param base specifies array being sorted 59 * @param num specifies number of elements in array 60 * @param width specifies with (in bytes) of one element of array 61 * @param fcompare specifies pointer to user defined function 62 * @warning After function call the original array 63 * is overwritten with sorted array in 64 * ascending order. 65 * @note Using own code for qsort and bsearch 66 * functions is guarantee of stable work 67 * @see HLFind HLFindNearest 68 **/ 69 extern void __FASTCALL__ HQSort(void __HUGE__ *base, unsigned long num, unsigned width, 70 func_compare fcompare); 71 72 /** Performs a quick search on a sorted array. 73 * @return pointer to the first matching element if found, otherwise NULL is returned 74 * @param key pointer to the key 75 * @param base specifies array being sorted 76 * @param nelem specifies number of elements in array 77 * @param width specifies with (in bytes) of one element of array 78 * @param fcompare specifies pointer to user defined function 79 * @warning Function can to cause infinity loop 80 * if array is unsorted 81 * @note Using own code for qsort and bsearch 82 * functions is guarantee of stable work 83 * @see HQSort HLFindNearest 84 **/ 85 extern void __HUGE__ * __FASTCALL__ HLFind(const void *key, 86 void __HUGE__ *base, 87 unsigned long nelem,unsigned width, 88 func_compare fcompare); 89 90 /** Performs a quick search on a sorted array of nearest element. 91 * @return index of nearest element of array toward zero. 92 * @param key pointer to the key 93 * @param base specifies array being sorted 94 * @param nelem specifies number of elements in array 95 * @param width specifies with (in bytes) of one element of array 96 * @param fcompare specifies pointer to user defined function 97 * @warning Function can to cause infinity loop 98 * if array is unsorted 99 * @note Using own code for qsort and bsearch 100 * functions is guarantee of stable work 101 * @see HQSort HLFind 102 **/ 103 extern unsigned long __FASTCALL__ HLFindNearest(const void *key, 104 void __HUGE__ *base, 105 unsigned long nelem,unsigned width, 106 func_compare fcompare); 107 108 /** Tests wether character is a separator 109 * @return True if given character is separator 110 * @param ch character to be tested 111 * @note returns true if character is space 112 * or punctuator 113 **/ 114 extern tBool __FASTCALL__ isseparate(int ch); 115 116 /** ASCIIZ string extended support */ 117 118 /** Removes all trailing spaces from string 119 * @return number of removed spaces 120 * @param str pointer to string to be trimmed 121 * @see szTrimLeadingSpace szKillSpaceAround 122 **/ 123 extern int __FASTCALL__ szTrimTrailingSpace(char *str); 124 125 /** Removes all leading spaces from string 126 * @return number of removed spaces 127 * @param str pointer to string to be trimmed 128 * @see szTrimTrailingSpace szKillSpaceAround 129 **/ 130 extern int __FASTCALL__ szTrimLeadingSpace(char *str); 131 132 /** Converts space into tabulation characters 133 * @return none 134 * @param dest pointer to string where will be placed result 135 * @param src pointer to source string 136 * @see szTab2Space 137 **/ 138 extern void __FASTCALL__ szSpace2Tab(char *dest,const char *src); 139 140 /** Expands all tabulation characters with spaces 141 * @return length of new string 142 * @param dest pointer to string where will be placed result 143 * @param src pointer to source string 144 * @see szSpace2Tab 145 **/ 146 extern int __FASTCALL__ szTab2Space(char *dest,const char *src); 147 148 /** Removes all spaces around given position 149 * @return pointer onto next non space character 150 * @param str pointer to string to be converted 151 * @param point_to specifies position to be unspaced 152 * @see szTrimLeadingSpace szTrimTrailingSpace 153 **/ 154 extern char *__FASTCALL__ szKillSpaceAround(char *str,char *point_to); 155 156 /** Prints formatted message into standard error stream 157 * @return number of printed characters 158 * @param str pointer to formatted string 159 * @warning Only this function must be used 160 * for error reporting. (do not use 161 * printf, fprintf, etc. !) 162 **/ 163 extern int printm(const char *str,...); 164 165 /** Internal structure of Linear memory container */ 166 typedef struct tag_linearArray 167 { 168 unsigned long nItems; /**< Number of stored items */ 169 void __HUGE__ * data; /**< Pointer into linear array */ 170 unsigned long nSize; /**< Size of linear array (May differ from nItems) */ 171 unsigned itemSize; /**< Size of one item in linear array */ 172 }linearArray; 173 174 /** Builds linear arrays 175 * @return pointer to builded array or NULL if error 176 * @param maxitems specifies maximal number of item that can be stored in array. 0 - indicates dynamic change of size 177 * @param size_of_item specifies size of each array element. 178 * @param mem_out specifies user-defined function to be called when low-memory. May be NULL. 179 * @note Linear array consist from elements 180 * same width. 181 * @see la_Destroy la_IterDestroy 182 **/ 183 extern linearArray *__FASTCALL__ la_Build( unsigned long maxitems,unsigned size_of_item, 184 void (__FASTCALL__ *mem_out)(const char *)); 185 186 /** Adds new element to linear array 187 * @return location of new element or NULL if no memory 188 * @param obj specifies linear array where new element will be stored 189 * @param data specifies new element 190 * @param mem_out specifies user-defined function to be called when low-memory. May be NULL. 191 * @see la_Build la_Find 192 **/ 193 extern void __HUGE__*__FASTCALL__ la_AddData(linearArray *obj,const void *data,void (__FASTCALL__ *mem_out)(const char *)); 194 195 /** Removes given element from linear array 196 * @param obj specifies linear array where element will be removed 197 * @param idx specifies index of element to be removed 198 * @param mem_out specifies user-defined function to be called when low-memory. May be NULL. 199 * @see la_Build la_Find 200 **/ 201 extern void __FASTCALL__ la_DeleteData(linearArray *obj,unsigned long idx); 202 203 /** Destroys of linear array 204 * @return none 205 * @param obj specifies linear array to be destroyed 206 * @warning if elements contain pointers to 207 * dynamically allocated memory, then 208 * it will be lost 209 * @see la_Build la_IterDestroy 210 **/ 211 extern void __FASTCALL__ la_Destroy(linearArray *obj); 212 213 /** Destroys of linear array and calls "destructor" for each element of array. 214 * @return none 215 * @param obj specifies linear array to be destroyed 216 * @param del_func specifies user-defined function, that will be used as destructor 217 * @note Before freeing memory of linear array 218 * will be called user-defined function 219 * with pointer onto each elemet as 220 * arguments 221 * @see la_Build la_Destroy 222 **/ 223 extern void __FASTCALL__ la_IterDestroy(linearArray *obj,void (__FASTCALL__ *del_func)(void __HUGE__ *)); 224 225 /** Calls the given iterator function on each array element 226 * @return none 227 * @param obj specifies linear array to be destroyed 228 * @param iter_func specifies iterator function which is to be called for each array element 229 * @see la_IterDestroy 230 **/ 231 extern void __FASTCALL__ la_ForEach(linearArray *obj,void (__FASTCALL__ *iter_func)(void __HUGE__ *)); 232 233 /** Implements quick sort algorithm for linear array 234 * @return none 235 * @param obj specifies linear array to be destroyed 236 * @param fcompare specifies pointer to user defined function 237 * @warning After function call the original array 238 * is overwritten with sorted array in 239 * ascending order. 240 * @note Based on HQSort function 241 * @see la_Find la_FindNearest 242 **/ 243 extern void __FASTCALL__ la_Sort(linearArray *obj,func_compare fcompare); 244 245 /** Performs a quick search on a sorted linear array. 246 * @return pointer to the first matching element if found, otherwise NULL is returned 247 * @param key pointer to the key 248 * @param fcompare specifies pointer to user defined function 249 * @warning Function can to cause infinity loop 250 * if array is unsorted 251 * @note Based on HLFind function 252 * functions is guarantee of stable work 253 * @see la_Sort la_FindNearest 254 **/ 255 extern void __HUGE__ *__FASTCALL__ la_Find(linearArray *obj,const void *key, 256 func_compare fcompare); 257 258 /** Performs a quick search on a sorted linear array of nearest element. 259 * @return index of nearest element of array toward zero. 260 * @param key pointer to the key 261 * @param fcompare specifies pointer to user defined function 262 * @warning Function can to cause infinity loop 263 * if array is unsorted 264 * @note Based on HLFindNearest function 265 * @see HQSort HLFind 266 **/ 267 extern unsigned long __FASTCALL__ la_FindNearest(linearArray *obj, const void *key, 268 func_compare fcompare); 269 270 #ifdef __cplusplus 271 } 272 #endif 273 274 #endif 275 276 277 278 279