1 /*************************************************************************** 2 $RCSfile$ 3 ------------------- 4 cvs : $Id$ 5 begin : Thu Apr 03 2003 6 copyright : (C) 2003 by Martin Preuss 7 email : martin@libchipcard.de 8 9 *************************************************************************** 10 * * 11 * This library is free software; you can redistribute it and/or * 12 * modify it under the terms of the GNU Lesser General Public * 13 * License as published by the Free Software Foundation; either * 14 * version 2.1 of the License, or (at your option) any later version. * 15 * * 16 * This library is distributed in the hope that it will be useful, * 17 * but WITHOUT ANY WARRANTY; without even the implied warranty of * 18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * 19 * Lesser General Public License for more details. * 20 * * 21 * You should have received a copy of the GNU Lesser General Public * 22 * License along with this library; if not, write to the Free Software * 23 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, * 24 * MA 02111-1307 USA * 25 * * 26 ***************************************************************************/ 27 28 #ifndef GWENHYWFAR_STRINGLIST_H 29 #define GWENHYWFAR_STRINGLIST_H 30 31 #include <gwenhywfar/gwenhywfarapi.h> 32 33 34 #ifdef __cplusplus 35 extern "C" { 36 #endif 37 38 39 typedef enum { 40 /** case-insensitive, i.e. using strcasecmp(3). */ 41 GWEN_StringList_SortModeNoCase=0, 42 /** case-sensitive, i.e. using strcmp(3). */ 43 GWEN_StringList_SortModeCase, 44 /** handle string list entries as integers (-> correct sorting of ASCII 45 * coded values like "10", "1") */ 46 GWEN_StringList_SortModeInt 47 } 48 GWEN_STRINGLIST_SORT_MODE; 49 50 51 typedef struct GWEN_STRINGLISTENTRYSTRUCT GWEN_STRINGLISTENTRY; 52 53 54 typedef struct GWEN_STRINGLISTSTRUCT GWEN_STRINGLIST; 55 56 57 GWENHYWFAR_API GWEN_STRINGLIST *GWEN_StringList_new(void); 58 59 GWENHYWFAR_API GWEN_STRINGLIST *GWEN_StringList_fromTabString(const char *s, int checkDup); 60 61 GWENHYWFAR_API void GWEN_StringList_free(GWEN_STRINGLIST *sl); 62 GWENHYWFAR_API 63 GWEN_STRINGLIST *GWEN_StringList_dup(const GWEN_STRINGLIST *sl); 64 GWENHYWFAR_API void GWEN_StringList_Clear(GWEN_STRINGLIST *sl); 65 66 /** Returns the number of elements in this list. */ 67 GWENHYWFAR_API 68 unsigned int GWEN_StringList_Count(const GWEN_STRINGLIST *sl); 69 70 GWENHYWFAR_API GWEN_STRINGLISTENTRY *GWEN_StringListEntry_new(const char *s, 71 int take); 72 GWENHYWFAR_API void GWEN_StringListEntry_ReplaceString(GWEN_STRINGLISTENTRY *e, 73 const char *s, 74 int take); 75 GWENHYWFAR_API void GWEN_StringListEntry_free(GWEN_STRINGLISTENTRY *sl); 76 GWENHYWFAR_API void GWEN_StringList_AppendEntry(GWEN_STRINGLIST *sl, 77 GWEN_STRINGLISTENTRY *se); 78 GWENHYWFAR_API void GWEN_StringList_RemoveEntry(GWEN_STRINGLIST *sl, 79 GWEN_STRINGLISTENTRY *se); 80 GWENHYWFAR_API 81 GWEN_STRINGLISTENTRY *GWEN_StringList_FirstEntry(const GWEN_STRINGLIST *sl); 82 GWENHYWFAR_API 83 GWEN_STRINGLISTENTRY *GWEN_StringListEntry_Next(const GWEN_STRINGLISTENTRY *se); 84 85 GWENHYWFAR_API 86 const char *GWEN_StringListEntry_Data(const GWEN_STRINGLISTENTRY *se); 87 88 GWENHYWFAR_API 89 void GWEN_StringListEntry_SetData(GWEN_STRINGLISTENTRY *se, 90 const char *s); 91 92 /** 93 * Normally this group of functions ignores cases when comparing two strings. 94 * You can change this behaviour here. 95 * @param sl string list 96 * @param i if 0 then cases are ignored 97 */ 98 GWENHYWFAR_API 99 void GWEN_StringList_SetSenseCase(GWEN_STRINGLIST *sl, int i); 100 101 /** 102 * Normally this group of functions ignores reference counters on stringlist 103 * entries when removing a string via @ref GWEN_StringList_RemoveString. 104 * You can change this behaviour here. 105 * @param sl string list 106 * @param i if 0 then reference counters are honoured 107 */ 108 GWENHYWFAR_API 109 void GWEN_StringList_SetIgnoreRefCount(GWEN_STRINGLIST *sl, int i); 110 111 /** 112 * Appends a string. 113 * @return 0 if not appended, !=0 if appended 114 * @param take if true then the StringList takes over ownership of the string 115 * @param checkDouble if true the the string will only be appended if it 116 * does not already exist 117 */ 118 GWENHYWFAR_API int GWEN_StringList_AppendString(GWEN_STRINGLIST *sl, 119 const char *s, 120 int take, 121 int checkDouble); 122 123 /** 124 * Inserts a string. 125 * @return 0 if not inserted, !=0 if inserted 126 * @param take if true then the StringList takes over ownership of the string 127 * @param checkDouble if true the the string will only be appended if it 128 * does not already exist 129 */ 130 GWENHYWFAR_API int GWEN_StringList_InsertString(GWEN_STRINGLIST *sl, 131 const char *s, 132 int take, 133 int checkDouble); 134 135 /** 136 * Removes a given string from the stringlist. 137 * @return 0 if not found, !=0 if found and removed 138 */ 139 GWENHYWFAR_API int GWEN_StringList_RemoveString(GWEN_STRINGLIST *sl, 140 const char *s); 141 142 /** 143 * Removes the first string from the stringlist (if any). 144 */ 145 GWENHYWFAR_API void GWEN_StringList_RemoveFirstString(GWEN_STRINGLIST *sl); 146 147 148 /** 149 * Checks whether the given string already exists within in the 150 * string list. 151 * @return !=0 if found, 0 otherwise 152 */ 153 GWENHYWFAR_API int GWEN_StringList_HasString(const GWEN_STRINGLIST *sl, 154 const char *s); 155 156 /** 157 * Returns the position of the given string within the stringlist. 158 * 159 * @return position, -1 if not found 160 */ 161 GWENHYWFAR_API int GWEN_StringList_GetStringPos(const GWEN_STRINGLIST *sl, const char *s); 162 163 164 /** 165 * Returns the first stringlist entry which contains the given string 166 * @return string list entry containing the given string, NULL otherwise 167 */ 168 GWENHYWFAR_API GWEN_STRINGLISTENTRY *GWEN_StringList_FindStringEntry(const GWEN_STRINGLIST *sl, const char *s); 169 170 171 /** Traverses the list, calling the callback function 'func' on 172 * each list element. Traversal will stop when 'func' returns a 173 * non-NULL value, and the routine will return with that 174 * value. Otherwise the routine will return NULL. 175 * @param l The list to traverse. 176 * @param func The function to be called with each list element. 177 * @param user_data A pointer passed on to the function 'func'. 178 * @return The non-NULL pointer returned by 'func' as soon as it 179 * returns one. Otherwise (i.e. 'func' always returns NULL) 180 * returns NULL. 181 */ 182 GWENHYWFAR_API 183 void *GWEN_StringList_ForEach(const GWEN_STRINGLIST *l, 184 void *(*func)(const char *s, void *u), 185 void *user_data); 186 187 /** Returns the first string in this list. */ 188 GWENHYWFAR_API 189 const char *GWEN_StringList_FirstString(const GWEN_STRINGLIST *l); 190 191 GWENHYWFAR_API 192 const char *GWEN_StringList_StringAt(const GWEN_STRINGLIST *l, int idx); 193 194 195 /** Sorts this list. Internally this uses qsort(3), so the sorting 196 * should be reasonably fast even for large lists. 197 * 198 * @param l The list to sort. 199 * 200 * @param ascending If non-zero, the list is sorted ascending, 201 * i.e. smallest string first, according to strcmp(3) rules. If zero, 202 * the list is sorted descending. 203 * 204 * @param sortMode See @ref GWEN_StringList_SortModeNoCase and following 205 */ 206 GWENHYWFAR_API 207 void GWEN_StringList_Sort(GWEN_STRINGLIST *l, 208 int ascending, 209 GWEN_STRINGLIST_SORT_MODE sortMode); 210 211 GWENHYWFAR_API 212 GWEN_STRINGLIST *GWEN_StringList_fromString(const char *str, const char *delimiters, int checkDouble); 213 214 #ifdef __cplusplus 215 } 216 #endif 217 218 #endif 219 220 221