1 /* 2 list.h - Part of psiconv, a PSION 5 file formats converter 3 Copyright (c) 1999-2014 Frodo Looijaard <frodo@frodo.looijaard.name> 4 5 This program is free software; you can redistribute it and/or modify 6 it under the terms of the GNU General Public License as published by 7 the Free Software Foundation; either version 2 of the License, or 8 (at your option) any later version. 9 10 This program is distributed in the hope that it will be useful, 11 but WITHOUT ANY WARRANTY; without even the implied warranty of 12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13 GNU General Public License for more details. 14 15 You should have received a copy of the GNU General Public License 16 along with this program; if not, write to the Free Software 17 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. 18 */ 19 20 /* A generic list type. In C++, this would be much neater. All elements must 21 be of the same size (solve it with pointers, if needed) */ 22 23 #ifndef PSICONV_LIST_H 24 #define PSICONV_LIST_H 25 26 #include <stddef.h> 27 #include <stdio.h> 28 29 #include <psiconv/general.h> 30 31 #ifdef __cplusplus 32 extern "C" { 33 #endif /* __cplusplus */ 34 35 /* Always use psiconv_list, never struct psiconv_list */ 36 /* No need to export the actual internal format */ 37 typedef struct psiconv_list_s *psiconv_list; 38 39 /* Before using a list, call list_new. It takes the size of a single element 40 as its argument. Always compute it with a sizeof() expression, just to be 41 safe. The returned list is empty. 42 If there is not enough memory available, NULL is returned. You should 43 always test for this explicitely, because the other functions do not 44 like a psiconv_list argument that is equal to NULL */ 45 extern psiconv_list psiconv_list_new(size_t element_size); 46 47 /* This frees the list. If elements contain pointers that need to be freed 48 separately, call list_free_el below. */ 49 extern void psiconv_list_free(psiconv_list l); 50 51 /* This calls free_el first for each element, before doing a list_free. 52 Note that you should *not* do 'free(el)' at any time; that is taken care of 53 automatically. */ 54 extern void psiconv_list_free_el(psiconv_list l, void free_el(void *el)); 55 56 /* Return the number of allocated elements */ 57 extern psiconv_u32 psiconv_list_length(const psiconv_list l); 58 59 /* Return 1 if the list is empty, 0 if not */ 60 extern int psiconv_list_is_empty(const psiconv_list l); 61 62 /* Empty a list. Note this does not reclaim any memory space! */ 63 extern void psiconv_list_empty(psiconv_list l); 64 65 /* Get an element from the list, and return a pointer to it. Note: you can 66 directly modify this element, but be careful not to write beyond the 67 element memory space. 68 If indx is out of range, NULL is returned. */ 69 extern void * psiconv_list_get(const psiconv_list l, psiconv_u32 indx); 70 71 /* Add an element at the end of the list. The element is copied from the 72 supplied element. Of course, this does not help if the element contains 73 pointers. 74 As the lists extends itself, it may be necessary to allocate new 75 memory. If this fails, a negative error-code is returned. If everything, 76 succeeds, 0 is returned. */ 77 extern int psiconv_list_add(psiconv_list l, const void *el); 78 79 /* Remove the last element from the list, and copy it to el. Note that 80 this will not reduce the amount of space reserved for the list. 81 An error code is returned, which will be 0 zero if everything 82 succeeded. It is your own responsibility to make sure enough 83 space is allocated to el. */ 84 extern int psiconv_list_pop(psiconv_list l, void *el); 85 86 /* Replace an element within the list. The element is copied from the 87 supplied element. Fails if you try to write at or after the end of 88 the list. */ 89 extern int psiconv_list_replace(psiconv_list l, psiconv_u32 indx, 90 const void *el); 91 92 /* Do some action for each element. Note: you can directly modify the 93 elements supplied to action, and they will be changed in the list, 94 but never try a free(el)! */ 95 extern void psiconv_list_foreach_el(psiconv_list l, void action(void *el)); 96 97 /* Clone the list, that is, copy it. If elements contain pointers, you 98 should call the next routine. If not enough memory is available, 99 NULL is returned. */ 100 extern psiconv_list psiconv_list_clone(const psiconv_list l); 101 102 /* Read upto size_t elements from file f, and put them at the end of list l. 103 Returned is the actual number of elements added. This assumes the file 104 layout and the memory layout of elements is the same. Note that if 105 not enough memory could be allocated, 0 is simply returned. */ 106 extern size_t psiconv_list_fread(psiconv_list l,size_t size, FILE *f); 107 108 /* Read the whole file f to list l. Returns 0 on succes, and an errorcode 109 on failure. */ 110 extern int psiconv_list_fread_all(psiconv_list l, FILE *f); 111 112 /* Write the whole list l to the opened file f. Returns 0 on succes, and 113 an errorcode on failure. */ 114 extern int psiconv_list_fwrite_all(const psiconv_list l, FILE *f); 115 116 /* Concatenate two lists. The element sized does not have to be the same, 117 but the result may be quite unexpected if it is not. */ 118 int psiconv_list_concat(psiconv_list l, const psiconv_list extra); 119 120 121 #ifdef __cplusplus 122 } 123 #endif /* __cplusplus */ 124 125 #endif 126