1/* 2 * "$Id: list.h,v 1.2 2004/11/28 15:59:29 rleigh Exp $" 3 * 4 * libgimpprint generic list type 5 * 6 * Copyright 1997-2000 Michael Sweet (mike@easysw.com), 7 * Robert Krawitz (rlk@alum.mit.edu) and Michael Natterer (mitch@gimp.org) 8 * Copyright 2002 Roger Leigh (rleigh@debian.org) 9 * 10 * This program is free software; you can redistribute it and/or modify it 11 * under the terms of the GNU General Public License as published by the Free 12 * Software Foundation; either version 2 of the License, or (at your option) 13 * any later version. 14 * 15 * This program is distributed in the hope that it will be useful, but 16 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY 17 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 18 * for more details. 19 * 20 * You should have received a copy of the GNU General Public License 21 * along with this program; if not, write to the Free Software 22 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. 23 */ 24 25/** 26 * @file gutenprint/list.h 27 * @brief Generic list functions. 28 */ 29 30/* 31 * This file must include only standard C header files. The core code must 32 * compile on generic platforms that don't support glib, gimp, gtk, etc. 33 */ 34 35#ifndef GUTENPRINT_LIST_H 36#define GUTENPRINT_LIST_H 37 38#ifdef __cplusplus 39extern "C" { 40#endif 41 42/** 43 * The list data type implements a fast generic doubly-linked list. 44 * It supports all of the operations you might want in a list (insert, 45 * remove, iterate over the list, copy whole lists), plus some 46 * (optional) less common features: finding items by index, name or 47 * long name, and sorting. These should also be fairly fast, due to 48 * caching in the list head. 49 * 50 * @defgroup list list 51 * @{ 52 */ 53 54 struct stp_list_item; 55 /** 56 * The list item opaque data type. 57 * This object is a node in the list. 58 */ 59 typedef struct stp_list_item stp_list_item_t; 60 61 struct stp_list; 62 /** 63 * The list opaque data type. 64 * This object represents the list as a whole. 65 */ 66 typedef struct stp_list stp_list_t; 67 68 /** 69 * A callback function to free the data a node contains. 70 * The parameter is a pointer to the node data. 71 */ 72 typedef void (*stp_node_freefunc)(void *); 73 74 /** 75 * A callback function to copy the data a node contains. 76 * The parameter is a pointer to the node data. 77 * The return value is a pointer to the new copy of the data. 78 */ 79 typedef void *(*stp_node_copyfunc)(const void *); 80 81 /** 82 * A callback function to get the name of a node. 83 * The parameter is a pointer to the node data. 84 * The return value is a pointer to the name of the 85 * node, or NULL if there is no name. 86 */ 87 typedef const char *(*stp_node_namefunc)(const void *); 88 89 /** 90 * A callback function to compare two nodes. 91 * The two parameters are pointers to node data. 92 * The return value is <0 if the first sorts before the 93 * second, 0 if they sort identically, and >0 if the 94 * first sorts after the second. 95 */ 96 typedef int (*stp_node_sortfunc)(const void *, const void *); 97 98 /** 99 * Free node data allocated with stp_malloc. 100 * This function is indended for use as an stp_node_freefunc, which 101 * uses stp_free to free the node data. 102 * @param item the node data to free 103 */ 104 extern void stp_list_node_free_data(void *item); 105 106 /** 107 * Create a new list object. 108 * @returns the newly created list object. 109 */ 110 extern stp_list_t *stp_list_create(void); 111 112 /** 113 * Copy and allocate a list object. 114 * list must be a valid list object previously created with 115 * stp_list_create(). 116 * @param list the list to copy. 117 * @returns a pointer to the new copy of the list. 118 */ 119 extern stp_list_t *stp_list_copy(const stp_list_t *list); 120 121 /** 122 * Destroy a list object. 123 * It is an error to destroy the list more than once. 124 * @param list the list to destroy. 125 * @returns 0 on success, 1 on failure. 126 */ 127 extern int stp_list_destroy(stp_list_t *list); 128 129 /** 130 * Find the first item in a list. 131 * @param list the list to use. 132 * @returns a pointer to the first list item, or NULL if the list is 133 * empty. 134 */ 135 extern stp_list_item_t *stp_list_get_start(const stp_list_t *list); 136 137 /** 138 * Find the last item in a list. 139 * @param list the list to use. 140 * @returns a pointer to the last list item, or NULL if the list is 141 * empty. 142 */ 143 extern stp_list_item_t *stp_list_get_end(const stp_list_t *list); 144 145 /** 146 * Find an item in a list by its index. 147 * @param list the list to use. 148 * @param idx the index to find. 149 * @returns a pointer to the list item, or NULL if the index is 150 * invalid or the list is empty. 151 */ 152 extern stp_list_item_t *stp_list_get_item_by_index(const stp_list_t *list, 153 int idx); 154 155 /** 156 * Find an item in a list by its name. 157 * @param list the list to use. 158 * @param name the name to find. 159 * @returns a pointer to the list item, or NULL if the name is 160 * invalid or the list is empty. 161 */ 162 extern stp_list_item_t *stp_list_get_item_by_name(const stp_list_t *list, 163 const char *name); 164 165 /** 166 * Find an item in a list by its long name. 167 * @param list the list to use. 168 * @param long_name the long name to find. 169 * @returns a pointer to the list item, or NULL if the long name is 170 * invalid or the list is empty. 171 */ 172 extern stp_list_item_t *stp_list_get_item_by_long_name(const stp_list_t *list, 173 const char *long_name); 174 175 /** 176 * Get the length of a list. 177 * @param list the list to use. 178 * @returns the list length (number of list items). 179 */ 180 extern int stp_list_get_length(const stp_list_t *list); 181 182 /** 183 * Set a list node free function. 184 * This callback function will be called whenever a list item is 185 * destroyed. Its intended use is for automatic object destruction 186 * and any other cleanup required. 187 * @param list the list to use. 188 * @param freefunc the function to set. 189 */ 190 extern void stp_list_set_freefunc(stp_list_t *list, 191 stp_node_freefunc freefunc); 192 193 /** 194 * Get a list node free function. 195 * @param list the list to use. 196 * @returns the function previously set with stp_list_set_freefunc, 197 * or NULL if no function has been set. 198 */ 199 extern stp_node_freefunc stp_list_get_freefunc(const stp_list_t *list); 200 201 /** 202 * Set a list node copy function. 203 * This callback function will be called whenever a list item is 204 * copied. Its intended use is for automatic object copying 205 * (since C lacks a copy constructor). 206 * @param list the list to use. 207 * @param copyfunc the function to set. 208 */ 209 extern void stp_list_set_copyfunc(stp_list_t *list, 210 stp_node_copyfunc copyfunc); 211 212 /** 213 * Get a list node copy function. 214 * @param list the list to use. 215 * @returns the function previously set with stp_list_set_copyfunc, 216 * or NULL if no function has been set. 217 */ 218 extern stp_node_copyfunc stp_list_get_copyfunc(const stp_list_t *list); 219 220 /** 221 * Set a list node name function. 222 * This callback function will be called whenever the name of a list 223 * item needs to be determined. This is used to find list items by 224 * name. 225 * @param list the list to use. 226 * @param namefunc the function to set. 227 */ 228 extern void stp_list_set_namefunc(stp_list_t *list, 229 stp_node_namefunc namefunc); 230 231 /** 232 * Get a list node name function. 233 * @param list the list to use. 234 * @returns the function previously set with stp_list_set_namefunc, 235 * or NULL if no function has been set. 236 */ 237 extern stp_node_namefunc stp_list_get_namefunc(const stp_list_t *list); 238 239 /** 240 * Set a list node long name function. 241 * This callback function will be called whenever the long name of a list 242 * item needs to be determined. This is used to find list items by 243 * long name. 244 * @param list the list to use. 245 * @param long_namefunc the function to set. 246 */ 247 extern void stp_list_set_long_namefunc(stp_list_t *list, 248 stp_node_namefunc long_namefunc); 249 250 /** 251 * Get a list node long name function. 252 * @param list the list to use. 253 * @returns the function previously set with 254 * stp_list_set_long_namefunc, or NULL if no function has been set. 255 */ 256 extern stp_node_namefunc stp_list_get_long_namefunc(const stp_list_t *list); 257 258 /** 259 * Set a list node sort function. 260 * This callback function will be called to determine the sort 261 * order for list items in sorted lists. 262 * @param list the list to use. 263 * @param sortfunc the function to set. 264 */ 265 extern void stp_list_set_sortfunc(stp_list_t *list, 266 stp_node_sortfunc sortfunc); 267 268 /** 269 * Get a list node sort function. 270 * @param list the list to use. 271 * @returns the function previously set with 272 * stp_list_set_sortfunc, or NULL if no function has been set. 273 */ 274 extern stp_node_sortfunc stp_list_get_sortfunc(const stp_list_t *list); 275 276 /** 277 * Create a new list item. 278 * @param list the list to use. 279 * @param next the next item in the list, or NULL to insert at the end of 280 * the list. 281 * @param data the data the list item will contain. 282 * @returns 0 on success, 1 on failure (if data is NULL, for example). 283 */ 284 extern int stp_list_item_create(stp_list_t *list, 285 stp_list_item_t *next, 286 const void *data); 287 288 /** 289 * Destroy a list item. 290 * @param list the list to use. 291 * @param item the item to destroy. 292 * @returns 0 on success, 1 on failure. 293 */ 294 extern int stp_list_item_destroy(stp_list_t *list, 295 stp_list_item_t *item); 296 297 /** 298 * Get the previous item in the list. 299 * @param item the item to start from. 300 * @returns a pointer to the list item prior to item, or NULL if 301 * item is the start of the list. 302 */ 303 extern stp_list_item_t *stp_list_item_prev(const stp_list_item_t *item); 304 305 /** 306 * Get the next item in the list. 307 * @param item the item to start from. 308 * @returns a pointer to the list item following from item, or NULL 309 * if item is the end of the list. 310 */ 311 extern stp_list_item_t *stp_list_item_next(const stp_list_item_t *item); 312 313 /** 314 * Get the data associated with a list item. 315 * @param item the list item to use. 316 * @returns the data associated with item. 317 */ 318 extern void *stp_list_item_get_data(const stp_list_item_t *item); 319 320 /** 321 * Set the data associated with a list item. 322 * @warning Note that if a sortfunc is in use, changing the data 323 * will NOT re-sort the list! 324 * @param item the list item to use. 325 * @param data the data to set. 326 * @returns 0 on success, 1 on failure (if data is NULL). 327 */ 328 extern int stp_list_item_set_data(stp_list_item_t *item, 329 void *data); 330 331 /** @} */ 332 333#ifdef __cplusplus 334 } 335#endif 336 337#endif /* GUTENPRINT_LIST_H */ 338