1 /* 2 LICENSE INFORMATION: 3 This program is free software; you can redistribute it and/or 4 modify it under the terms of the GNU General Public 5 License as published by the Free Software Foundation; either 6 version 2 of the License, or (at your option) any later version. 7 8 This program is distributed in the hope that it will be useful, 9 but WITHOUT ANY WARRANTY; without even the implied warranty of 10 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 11 General Public License for more details. 12 13 You should have received a copy of the GNU General Public 14 License along with this program; if not, write to the Free Software 15 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 16 Copyright (c) 2002 Bruno T. C. de Oliveira 17 18 INFORMA��ES DE LICEN�A: 19 Este programa � um software de livre distribui��o; voc� pode 20 redistribu�-lo e/ou modific�-lo sob os termos da GNU General 21 Public License, conforme publicado pela Free Software Foundation, 22 pela vers�o 2 da licen�a ou qualquer vers�o posterior. 23 24 Este programa � distribu�do na esperan�a de que ele ser� �til 25 aos seus usu�rios, por�m, SEM QUAISQUER GARANTIAS; sem sequer 26 a garantia impl�cita de COMERCIABILIDADE ou DE ADEQUA��O A 27 QUALQUER FINALIDADE ESPEC�FICA. Consulte a GNU General Public 28 License para obter mais detalhes (uma c�pia acompanha este 29 programa, armazenada no arquivo COPYING). 30 */ 31 32 #ifndef btco_bores_darray_h 33 #define btco_bores_darray_h 34 35 /* opaque dynamic array type */ 36 struct DArray_; 37 typedef struct DArray_ DArray; 38 39 /* creates a new dynamic array of default initial capacity and no 40 * value destroyer function. */ 41 DArray* darray_create(); 42 43 /* creates a new dynamic array of initial capacity cap (must be positive) 44 * and value destroyer function f. The value destroyer is a function 45 * called whenever a value stored in the array must be destroyed or 46 * will be overwritten. */ 47 DArray* darray_create_ex(int cap, void (*vd)(void*)); 48 49 /* destroys the given dynamic array. The value destroyer function will 50 * be called for all non-NULL values in the array at this point. */ 51 void darray_destroy(DArray*); 52 53 /* obtains the length of a dynamic array. This is NOT the capacity. The 54 * length is how many elements are actually there. You should not be 55 * interested in the capacity, since it is internally managed. */ 56 int darray_len(DArray*); 57 58 /* obtains the item from the array whose index is i. If i is out of 59 * bounds, NULL is returned (and no error occurs). PLEASE notice 60 * that this function is for consultation only, the value will still 61 * be owned by the darray (and thus can be destroyed at any moment 62 * by the value destroyer function). If you want to gain ownership 63 * over the value you get, use darray_snatch instead. */ 64 void* darray_get(DArray*, int i); 65 66 /* sets the value of item index i to NULL, without calling the value 67 * destroyer function for it. Returns the value the item had before 68 * being set to NULL. If the index i is out of bounds, nothing is done 69 * and NULL is returned. */ 70 void* darray_snatch(DArray*, int i); 71 72 /* sets the value of item index i to v. If the item had a non-NULL value 73 * before, the value destroyer function will be called for it before 74 * it is overwritten. If the index is out of bounds and positive, the 75 * array will be dynamically expanded to make it valid. If it is 76 * negative a fatal error occurs. 77 * 78 * If i is out of bounds and v is NULL, this function does absolutely 79 * nothing, because expanding the array to put a NULL value is 80 * really the same as just leaving it as it is, because darray_get 81 * returns NULL if you pass it an out-of-bounds index. 82 * 83 * Whenever the array expands, the newly created items are set to NULL, 84 * that is, they are not left with trash in them. 85 */ 86 void darray_set(DArray*, int i, const void *v); 87 88 /* Same as darray_set(da, darray_len(da), v) */ 89 void darray_append(DArray*, const void *v); 90 91 /* removes item i from array, shifting all others up */ 92 void darray_remove(DArray*, int i); 93 94 #endif 95 96