2 * This program is free software; you can redistribute it and/or modify
3 * it under the terms of the GNU General Public License as published by
4 * the Free Software Foundation; either version 2 of the License, or
5 * (at your option) any later version.
6 * Please read the file COPYING, README and AUTHORS for more information.
8 * libarray - dynamically allocate arrays.
9 * Copyright (c) 2005 Florian Westphal (westphal@foo.fh-furtwangen.de)
12 #ifndef array_h_included
13 #define array_h_included
17 * Functions to dynamically allocate arrays (header).
28 /* allocated: mem != NULL, used >= 0 && used <= allocated, allocated > 0
29 unallocated: mem == NULL, allocated == 0, used == 0 */
31 #define array_unallocated(x) (array_bytes(x)==0)
32 #define INIT_ARRAY { NULL, 0, 0 }
34 /* set all variables in a to 0 */
35 extern void array_init PARAMS((array *a));
37 /* allocates space for at least nmemb+1 elements of size bytes each.
38 return pointer to elem at pos, or NULL if realloc() fails */
39 extern void * array_alloc PARAMS((array *a, size_t size, size_t pos));
41 /* returns the number of initialized BYTES in a. */
42 #define array_bytes(array) ( (array)->used )
44 /* returns the number of initialized ELEMS in a. */
45 extern size_t array_length PARAMS((const array* const a, size_t elemsize));
47 /* _copy functions: copy src to dest.
48 return true if OK, else false (e. g. realloc failure, invalid src/dest
49 array, ...). In that case dest is left unchanged. */
51 /* copy array src to dest */
52 extern bool array_copy PARAMS((array* dest, const array* const src));
54 /* copy len bytes from src to array dest. */
55 extern bool array_copyb PARAMS((array* dest, const char* src, size_t len));
57 /* copy string to dest */
58 extern bool array_copys PARAMS((array* dest, const char* src));
60 /* _cat functions: append src to dest.
61 return true if OK, else false (e. g. realloc failure, invalid src/dest
62 array, ...). In that case dest is left unchanged. */
64 /* append len bytes from src to array dest. */
65 extern bool array_catb PARAMS((array* dest, const char* src, size_t len));
67 /* append string to dest */
68 extern bool array_cats PARAMS((array* dest, const char* src));
70 /* append NUL byte to dest */
71 extern bool array_cat0 PARAMS((array* dest));
73 /* append NUL byte to dest, but do not count null byte */
74 extern bool array_cat0_temporary PARAMS((array* dest));
76 /* append contents of array src to array dest. */
77 extern bool array_cat PARAMS((array* dest, const array* const src));
79 /* return pointer to element at pos.
80 return NULL if the array is unallocated or if pos is larger than the number
81 of elements stored int the array. */
82 extern void* array_get PARAMS((array* a, size_t membersize, size_t pos));
84 /* free the contents of this array. */
85 extern void array_free PARAMS((array* a));
87 /* overwrite array with zeros before free */
88 extern void array_free_wipe PARAMS((array* a));
90 /* return pointer to first element in this array */
91 extern void* array_start PARAMS((const array* const a));
93 /* reset this array (the memory is not free'd */
94 extern void array_trunc PARAMS((array* a));
96 /* set number of used elements in this array to len */
97 extern void array_truncate PARAMS((array* a, size_t membersize, size_t len));
99 /* move elements starting at pos to beginning of array */
100 extern void array_moveleft PARAMS((array* a, size_t membersize, size_t pos));