Main Page | Modules | Alphabetical List | Data Structures | File List | Data Fields | Related Pages

blah.h

00001 /* 00002 00003 The BLAH library, a container library 00004 Copyright (C) 1997-2004 The CDG Team <cdg@nats.informatik.uni-hamburg.de> 00005 00006 This program is free software; you can redistribute it and/or modify 00007 it under the terms of the GNU General Public License as published by 00008 the Free Software Foundation; either version 2 of the License, or 00009 (at your option) any later version. 00010 00011 This program is distributed in the hope that it will be useful, 00012 but WITHOUT ANY WARRANTY; without even the implied warranty of 00013 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 00014 GNU General Public License for more details. 00015 00016 You should have received a copy of the GNU General Public License 00017 along with this program; if not, write to the Free Software 00018 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. 00019 00020 Contact: blah@nats.informatik.uni-hamburg.de 00021 00022 $Id: blah.h,v 1.11 2004/09/23 15:46:13 micha Exp $ 00023 00024 */ 00025 00026 /* ------------------------------------------------------------------- */ 00027 /** \mainpage The BLAH Reference Manual. 00028 00029 \author Ingo Schröder 00030 \author Kilian A. Foth 00031 \author Michael Daum 00032 00033 \section Introduction Introduction 00034 00035 This is the reference manual for the BLAH library for the C programming 00036 language. BLAH stands for bitstrings, lists, arrays and hashes --- admittedly a poorly 00037 chosen giving the set of container data types most usually used. Actually 00038 there are more data types than these but who cares if the name is funky enuf. 00039 00040 The BLAH library is copyright by The CDG Team; it is distributed under 00041 the GNU General Publice License Version 2. You should have received a 00042 copy of the GPL with the software. 00043 00044 The maintainers of this software can be contacted at the following 00045 email address: 00046 \verbatim blah@nats.informatik.uni-hamburg.de \endverbatim 00047 00048 \section Usage Usage 00049 00050 The BLAH library is installed as both shared and static versions of the 00051 library by default. In order to use it your C code must include the 00052 header file \code blah.h \endcode 00053 00054 For instance, if you installed the header file in a system directory, 00055 a minimal C program might look as follows: 00056 00057 \code 00058 #include <stdio.h> 00059 #include <blah.h> 00060 00061 int main(int argc, char **argv) 00062 { 00063 List squares=listNew(); 00064 int i; 00065 00066 for (i=0; i<100; i++) 00067 { 00068 squares=listPrependElement(squares, (Pointer)(i*i)); 00069 } 00070 printf("42th square is %d\n", (int)listNthElement(squares, 42)); 00071 listDelete(squares); 00072 } 00073 \endcode 00074 00075 You have to link against the BLAH library as well as the math library 00076 to create a binary: 00077 00078 \verbatim 00079 $ gcc -o blah-example -lblah -lm blah-example.c 00080 $ ./blah-example 00081 42th square is 3364 00082 $ 00083 \endverbatim 00084 00085 \section Overview Overview 00086 00087 The BLAH library defines the following container data types: 00088 00089 - \ref Array: 00090 An array stores information that is accessed using a number of indices. 00091 Arrays usually have two or more dimensions. The number of dimensions as 00092 well as the size of each dimension must be provided at creation time of 00093 the array and stay fixed. The required time to access a specific 00094 information given the corresponding indices is constant; the memory is 00095 proportional to the product of all dimension sizes. 00096 - \ref BitString: 00097 A bitstring stores a sequence of Booleans. The design emphasis is on 00098 memory efficiency. 00099 - \ref ByteVector: 00100 A bitvector also stores a sequence of Booleans. However, one byte is used 00101 to store a single Boolean. This data type is more time efficient than a 00102 bitstring. 00103 - \ref Hashtable: 00104 A hashtable stores key-value pairs. The key is used to access the 00105 actual information in the value. Access time is (almost) constant for 00106 arbitrary sizes of the hashtable and arbitrary keys. 00107 - \ref List: 00108 A list stores a sequence of objects. Access to the head of the list 00109 is efficiently possible while in general access to an arbitrary 00110 object requires linear time. 00111 - \ref ListAgenda: 00112 An agenda is created by sorting the items according to priority using 00113 a simple linked list as its storage medium. 00114 - \ref Memory: 00115 Some basic Operations with the memory are done in this module. 00116 - \ref Prime: 00117 Prime is a module that makes use of Rabin's Probablistic Primetest-Algorithm 00118 for generating the prime numbers equal to the Hash table entries. 00119 - \ref Ringbuffer: 00120 It is similar to the vector that stores a series of objects, though 00121 the head and the tail are attached inorder to enhance cyclic operations. 00122 - \ref String: 00123 Strings in C are represented by arrays of characters. The end of the string 00124 is marked with a special character, the null character, which is simply the 00125 character with the value 0. Whenever we write a string, enclosed in double 00126 quotes, C automatically creates an array of characters for us, containing that 00127 string, terminated by the \a NULL character. 00128 - \ref TreeAgenda: 00129 An agenda is created by sorting the items according to the order of the 00130 priority using an unbalanced binary tree. 00131 - \ref Vector: 00132 A vector stores objects at a given index. The size of the vector is 00133 linear in the largest used index. Time to access an object given the 00134 index is constant. 00135 */ 00136 00137 #ifndef BLAH_H 00138 #define BLAH_H 00139 00140 #include <stdarg.h> 00141 #include <stdlib.h> 00142 #include "config.h" 00143 00144 /* CONSTANTS ---------------------------------------------------------- */ 00145 #ifndef NULL 00146 #define NULL 0 00147 #endif 00148 00149 #ifndef TRUE 00150 #define TRUE 1 00151 #endif 00152 00153 #ifndef FALSE 00154 #define FALSE 0 00155 #endif 00156 00157 #ifndef max 00158 #define max(a, b) (a) > (b) ? (a) : (b) 00159 #endif 00160 00161 #ifndef min 00162 #define min(a, b) (a) < (b) ? (a) : (b) 00163 #endif 00164 00165 typedef unsigned char Boolean; 00166 typedef void *Pointer; 00167 00168 #ifndef SWIG 00169 typedef void VoidFunction (); 00170 typedef Boolean BooleanFunction (); 00171 typedef int IntFunction (); 00172 typedef Pointer PointerFunction (); 00173 #endif 00174 00175 00176 /* FORWARD DECLARATIONS ---------------------------------------------- */ 00177 struct ArrayStruct; 00178 typedef struct ArrayStruct ArrayStruct, *Array; 00179 struct BitStringStruct; 00180 typedef struct BitStringStruct BitStringStruct, *BitString; 00181 struct ByteVectorStruct; 00182 typedef struct ByteVectorStruct ByteVectorStruct, *ByteVector; 00183 struct HashtableEntryStruct; 00184 typedef struct HashtableEntryStruct HashtableEntryStruct, *HashtableEntry; 00185 struct HashtableStruct; 00186 typedef struct HashtableStruct HashtableStruct, *Hashtable; 00187 struct HashIteratorStruct; 00188 typedef struct HashIteratorStruct HashIteratorStruct, *HashIterator; 00189 struct ListAgendaEntryStruct; 00190 typedef struct ListAgendaEntryStruct ListAgendaEntryStruct, *ListAgendaEntry; 00191 struct ListAgendaEntryStruct; 00192 typedef struct ListAgendaStruct ListAgendaStruct, *ListAgenda; 00193 struct ListStruct; 00194 typedef struct ListStruct ListStruct, *List; 00195 typedef List ListAgendaIterator; 00196 struct RingBufferStruct; 00197 typedef struct RingBufferStruct RingBufferStruct, *RingBuffer; 00198 typedef char *String; 00199 struct TANodeStruct; 00200 typedef struct TANodeStruct TANodeStruct, *TANode; 00201 struct TreeAgendaStruct; 00202 typedef struct TreeAgendaStruct TreeAgendaStruct, *TreeAgenda; 00203 struct TreeAgendaIteratorStruct; 00204 typedef struct TreeAgendaIteratorStruct TreeAgendaIteratorStruct, *TreeAgendaIterator; 00205 struct VectorStruct; 00206 typedef struct VectorStruct VectorStruct, *Vector; 00207 00208 /* MODULES ----------------------------------------------------------- */ 00209 00210 /* MAIN -------------------------------------------------------------- */ 00211 void blahInitialize(void); 00212 void blahFinalize(void); 00213 00214 /* AGENDA ------------------------------------------------------------ */ 00215 #ifndef SWIG 00216 #ifdef TREEAGENDA 00217 #define AgendaStruct TreeAgendaStruct 00218 #define Agenda TreeAgenda 00219 00220 #define agNew taNew 00221 #define agSetVerbosity taSetVerbosity 00222 #define agVerbosity taVerbosity 00223 #define agSize taSize 00224 #define agMaxSize taMaxSize 00225 #define agMaxSizeSoFar taMaxSizeSoFar 00226 #define agIsEmpty taIsEmpty 00227 #define agIsTruncated taIsTruncated 00228 #define agResetTruncated taResetTruncated 00229 #define agInsert taInsert 00230 #define agBest taBest 00231 #define agRemoveBest taRemoveBest 00232 #define agDelete taDelete 00233 00234 #define AgendaIterator TreeAgendaIterator 00235 00236 #define agIteratorNew taIteratorNew 00237 #define agIteratorNextElement taIteratorNextElement 00238 #define agIteratorDelete taIteratorDelete 00239 00240 #else 00241 00242 #define AgendaStruct ListAgendaStruct 00243 #define Agenda ListAgenda 00244 00245 #define agNew laNew 00246 #define agSetVerbosity laSetVerbosity 00247 #define agVerbosity laVerbosity 00248 #define agSize laSize 00249 #define agMaxSize laMaxSize 00250 #define agMaxSizeSoFar laMaxSizeSoFar 00251 #define agIsEmpty laIsEmpty 00252 #define agIsTruncated laIsTruncated 00253 #define agResetTruncated laResetTruncated 00254 #define agInsert laInsert 00255 #define agBest laBest 00256 #define agRemoveBest laRemoveBest 00257 #define agDelete laDelete 00258 00259 #define AgendaIterator ListAgendaIterator 00260 00261 #define agIteratorNew laIteratorNew 00262 #define agIteratorNextElement laIteratorNextElement 00263 #define agIteratorDelete laIteratorDelete 00264 00265 #endif 00266 #endif 00267 00268 00269 /* ARRAY ------------------------------------------------------------- */ 00270 #ifndef SWIG 00271 extern Array arrayNew(int i, ...); 00272 extern Pointer arraySetElement(Array a, Pointer element, ...); 00273 extern Pointer arrayElement(Array a, ...); 00274 #endif 00275 00276 extern Array arrayClone(Array a); 00277 extern void arrayDelete(Array a); 00278 extern void arraySetAllElements(Array a, Pointer element); 00279 extern int arrayDimension(Array a, int dim); 00280 00281 00282 /* BITSTRING --------------------------------------------------------- */ 00283 extern BitString bitNew(int size); 00284 extern BitString bitClone(BitString bs); 00285 extern BitString bitCopy(BitString dst, BitString src); 00286 extern void bitDelete(BitString bs); 00287 extern int bitSize(BitString bs); 00288 extern void bitPrint(BitString bs); 00289 extern void bitSet(BitString a, int no); 00290 extern void bitClear(BitString a, int no); 00291 extern void bitSetAll(BitString a); 00292 extern void bitClearAll(BitString a); 00293 extern BitString bitAnd(BitString a, BitString b); 00294 extern BitString bitOr(BitString a, BitString b); 00295 extern Boolean bitCheck(BitString a, BitString b); 00296 extern Boolean bitGet(BitString bs, int no); 00297 extern Boolean bitIsAllCleared(BitString bs); 00298 extern Boolean bitIsAllSet(BitString bs); 00299 00300 /* BITVECTOR --------------------------------------------------------- */ 00301 extern ByteVector bvNew(int capacity); 00302 extern void bvDelete(ByteVector a); 00303 extern int bvAddElement(ByteVector v, char element); 00304 extern char bvElement(ByteVector v, int index); 00305 extern char bvRemoveElement(ByteVector v, int index); 00306 extern char bvInsertElement(ByteVector v, char element, int index); 00307 extern char bvSetElement(ByteVector v, char element, int index); 00308 extern void bvSetElements(ByteVector v, char element, int from, int to); 00309 extern void bvSetAllElements(ByteVector v, char element); 00310 extern int bvCapacity(ByteVector v); 00311 extern int bvSize(ByteVector v); 00312 extern Boolean bvIsEmpty(ByteVector v); 00313 extern ByteVector bvCopy(ByteVector dst, ByteVector src); 00314 extern ByteVector bvClone(ByteVector v); 00315 extern char bvAndElement(ByteVector v, char element, int index); 00316 extern char bvOrElement(ByteVector v, char element, int index); 00317 extern char bvNotElement(ByteVector v, int index); 00318 00319 /* HASHTABLE --------------------------------------------------------- */ 00320 extern Hashtable hashNew(int capacity, 00321 double loadFactor, 00322 IntFunction *hashFunction, 00323 IntFunction *keyEqualFunction); 00324 extern void hashDelete(Hashtable ht); 00325 extern void hashForEach(Hashtable ht, VoidFunction *f); 00326 extern void hashForEachWithData(Hashtable ht, VoidFunction *f, Pointer data); 00327 extern void hashForEachFree(Hashtable ht, VoidFunction *f); 00328 extern void hashForEachFreeValue(Hashtable ht, VoidFunction *f); 00329 extern Pointer hashSet(Hashtable ht, Pointer key, Pointer value); 00330 extern Pointer hashGet(Hashtable ht, Pointer key); 00331 extern Pointer hashRemove(Hashtable ht, Pointer key); 00332 extern int hashSize(Hashtable ht); 00333 extern Boolean hashIsEmpty(Hashtable ht); 00334 extern Boolean hashContainsKey(Hashtable ht, Pointer key); 00335 extern Boolean hashContainsValue(Hashtable ht, Pointer value); 00336 extern List hashListOfKeys(Hashtable ht); 00337 extern HashIterator hashIteratorNew(Hashtable ht); 00338 extern Pointer hashIteratorNextKey(HashIterator hi); 00339 extern Pointer hashIteratorNextValue(HashIterator hi); 00340 extern void hashIteratorDelete(HashIterator hi); 00341 extern int hashStringHashFunction(char *s); 00342 extern int hashStringEqualFunction(char *s, char *t); 00343 00344 /* LIST -------------------------------------------------------------- */ 00345 extern List listNew(); 00346 extern Pointer listElement(List l); 00347 extern Pointer listSetElement(List l, Pointer value); 00348 extern Pointer listSetNext(List l, List m); 00349 extern List listNext(List l); 00350 extern List listClone(List l); 00351 extern List listDeepClone(List l, PointerFunction *p); 00352 extern List listCopy(List dst, List src); 00353 extern List listAppendList(List front, List rear); 00354 extern List listAddUniqueElement(List l, Pointer item); 00355 extern List listAppendElement(List l, Pointer item); 00356 extern List listPrependElement(List l, Pointer item); 00357 extern List listInsertSorted(List l, Pointer item, BooleanFunction *f); 00358 extern List listInsertSortedWithData(List l, Pointer item, BooleanFunction *f, Pointer data); 00359 extern List listSort(List l, BooleanFunction *f); 00360 extern List listSortWithData(List l, BooleanFunction *f, void *data); 00361 extern int listSize(List l); 00362 extern Pointer listNthElement(List l, int n); 00363 extern Pointer listLastElement(List l); 00364 extern Boolean listContains(List l, Pointer item); 00365 extern void listForEach(List l, VoidFunction *f); 00366 extern void listForEachDelete(List l, VoidFunction *f); 00367 extern List listFilter(List l, BooleanFunction *f); 00368 extern void listDelete(List l); 00369 extern List listDeleteElement(List l, Pointer item); 00370 extern List listDeleteLastElement(List l); 00371 extern Vector listToVector(List l); 00372 extern int listIndex(List l, Pointer item); 00373 extern List listReverse(List l); 00374 extern Boolean listIsEqual(List l1, List l2); 00375 00376 /* LISTAGENDA -------------------------------------------------------- */ 00377 extern ListAgenda laNew(int, VoidFunction *f); 00378 extern Boolean laSetVerbosity(ListAgenda, Boolean); 00379 extern Boolean laVerbosity(ListAgenda); 00380 extern int laSize(ListAgenda); 00381 extern int laMaxSize(ListAgenda); 00382 extern int laMaxSizeSoFar(ListAgenda); 00383 extern Boolean laIsEmpty(ListAgenda); 00384 extern Boolean laIsTruncated(ListAgenda); 00385 extern Boolean laResetTruncated(ListAgenda); 00386 extern Boolean laInsert(ListAgenda, double, Pointer); 00387 extern Pointer laBest(ListAgenda); 00388 extern Pointer laRemoveBest(ListAgenda); 00389 extern void laDelete(ListAgenda); 00390 extern ListAgendaIterator laIteratorNew(ListAgenda); 00391 extern Pointer laIteratorNextElement(ListAgendaIterator); 00392 extern void laIteratorDelete(ListAgendaIterator); 00393 00394 00395 00396 /* MEMORY ------------------------------------------------------------ */ 00397 #ifndef SWIG 00398 #ifdef MEMTEST 00399 /* 00400 * I don't want to include mem_test_user.h because I want to define 00401 * my own macros. 00402 * Therefore, I have to declare the functions I want to use. 00403 */ 00404 extern void *limalloc (unsigned int size, char *file_name, int line_number); 00405 extern void *lirealloc (void *ptr, unsigned int size, char *file_name, int line_number); 00406 extern void lifree (void *ptr, char *file_name, int line_number); 00407 #define memMalloc(size) memMallocCheck(limalloc(size, __FILE__, __LINE__), __FILE__, __LINE__) 00408 #define memRealloc(ptr, size) memMallocCheck(lirealloc(ptr, size, __FILE__, __LINE__), __FILE__, __LINE__) 00409 #define memFree(ptr) lifree(ptr, __FILE__, __LINE__) 00410 #else 00411 #ifdef GC 00412 #if GC_DEBUG 00413 #define memMalloc(size) memMallocCheck(GC_debug_malloc(size, __FILE__, __LINE__), __FILE__, __LINE__) 00414 #define memFree(size) GC_debug_free(size) 00415 #else 00416 #define memMalloc(size) memMallocCheck(GC_malloc(size), __FILE__, __LINE__) 00417 #define memFree(ptr) GC_free(ptr) 00418 #endif 00419 #include <gc.h> 00420 #else 00421 #ifdef NO_MALLOCCHECK 00422 #define memMalloc(size) malloc(size) 00423 #define memRealloc(ptr, size) realloc(ptr, size) 00424 #define memFree(ptr) free(ptr) 00425 #else 00426 #define memMalloc(size) memMallocCheck(malloc(size), __FILE__, __LINE__) 00427 #define memRealloc(ptr, size) memMallocCheck(realloc(ptr, size), __FILE__, __LINE__) 00428 #define memFree(ptr) free(ptr) 00429 #endif 00430 #endif 00431 #endif 00432 #endif 00433 00434 extern void *memMallocCheck(void *, char*, int); 00435 extern void memFreeFunction(void *); 00436 00437 /* PRIMES ------------------------------------------------------------ */ 00438 int primeRabin(unsigned long number, unsigned long times); 00439 unsigned long primeNext(unsigned long number, unsigned long times); 00440 00441 /* RINGBUFFER -------------------------------------------------------- */ 00442 extern RingBuffer rbNew(int capacity); 00443 extern void rbDelete(RingBuffer rb); 00444 extern int rbAddTopElement(RingBuffer rb, Pointer element); 00445 extern int rbAddBottomElement(RingBuffer rb, Pointer element); 00446 extern Boolean rbIsEmpty(RingBuffer rb); 00447 extern Boolean rbIsFull(RingBuffer rb); 00448 extern Pointer rbTopPeek(RingBuffer rb); 00449 extern int rbSize(RingBuffer rb); 00450 extern int rbCapacity(RingBuffer rb); 00451 extern Pointer rbBottomPeek(RingBuffer rb); 00452 extern Pointer rbRemoveTopElement(RingBuffer rb); 00453 extern Pointer rbRemoveBottomElement(RingBuffer rb); 00454 extern Boolean rbContains(RingBuffer rb, Pointer element); 00455 extern RingBuffer rbCopy(RingBuffer dst, RingBuffer src); 00456 extern RingBuffer rbClone(RingBuffer src); 00457 extern void rbForEachWithData(RingBuffer rb, 00458 VoidFunction *f, 00459 Pointer clientData); 00460 extern void rbClear(RingBuffer rb); 00461 00462 /* STRING ------------------------------------------------------------ */ 00463 extern void strInitialize(void); 00464 extern void strFinalize(void); 00465 extern void strDelete(String); 00466 extern String strRegister(const String); 00467 extern String strCopy(String s); 00468 extern String strCat(String a, String b); 00469 extern String strFromList(List list); 00470 #ifndef SWIG 00471 extern String strAppend(String head, ...); 00472 extern String strPrintf(String fmt, ...); 00473 extern String strVPrintf(String fmt, va_list); 00474 #endif 00475 extern int strStoreSize(void); 00476 extern String strDecode(String word); 00477 00478 /* TREEAGENDA ---------------------------------------------------------*/ 00479 extern TreeAgenda taNew(int, VoidFunction *); 00480 extern Boolean taSetVerbosity(TreeAgenda, Boolean); 00481 extern Boolean taVerbosity(TreeAgenda); 00482 extern int taSize(TreeAgenda); 00483 extern int taMaxSize(TreeAgenda); 00484 extern int taMaxSizeSoFar(TreeAgenda); 00485 extern Boolean taIsEmpty(TreeAgenda); 00486 extern Boolean taIsTruncated(TreeAgenda); 00487 extern Boolean taResetTruncated(TreeAgenda); 00488 extern Boolean taInsert(TreeAgenda, double, Pointer); 00489 extern Pointer taBest(TreeAgenda); 00490 extern Pointer taRemoveBest(TreeAgenda); 00491 extern void taDelete(TreeAgenda); 00492 extern TreeAgendaIterator taIteratorNew(TreeAgenda); 00493 extern Pointer taIteratorNextElement(TreeAgendaIterator); 00494 extern void taIteratorDelete(TreeAgendaIterator); 00495 00496 /* VECTOR ------------------------------------------------------------ */ 00497 extern Vector vectorNew(int capacity); 00498 extern void vectorDelete(Vector a); 00499 extern int vectorAddElement(Vector v, void *element); 00500 extern void *vectorElement(Vector v, int index); 00501 extern void *vectorRemoveElementAt(Vector v, int index); 00502 extern int vectorRemoveElement(Vector v, void *element); 00503 extern void *vectorInsertElement (Vector v, void *element, int index); 00504 extern void *vectorSetElement(Vector v, void *element, int index); 00505 extern void vectorSetElements(Vector v, void *element, int from, int to); 00506 extern void vectorSetAllElements(Vector v, void *element); 00507 extern int vectorIndexOf(Vector v, void *element, int index); 00508 extern int vectorCapacity (Vector v); 00509 extern int vectorSize(Vector v); 00510 extern Boolean vectorIsEmpty(Vector v); 00511 extern Boolean vectorContains(Vector v, void *element); 00512 extern Vector vectorCopy(Vector dst, Vector src); 00513 extern Vector vectorClone(Vector v); 00514 extern Vector vectorSort(Vector v, BooleanFunction *f); 00515 extern Vector vectorSortWithData(Vector v, BooleanFunction *f, void *data); 00516 extern List vectorToList(Vector v); 00517 00518 /* ------------------------------------------------------------------- */ 00519 #endif /* #ifndef BLAH_H */ 00520

BLAH 0.95 (20 Oct 2004)