Annotation of gpl/axl/src/axl_list.c, revision 1.1
1.1 ! misho 1: /*
! 2: * LibAxl: Another XML library
! 3: * Copyright (C) 2006 Advanced Software Production Line, S.L.
! 4: *
! 5: * This program is free software; you can redistribute it and/or
! 6: * modify it under the terms of the GNU Lesser General Public License
! 7: * as published by the Free Software Foundation; either version 2.1 of
! 8: * the License, or (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 Lesser General Public License for more details.
! 14: *
! 15: * You should have received a copy of the GNU Lesser General Public
! 16: * License along with this program; if not, write to the Free
! 17: * Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
! 18: * 02111-1307 USA
! 19: *
! 20: * You may find a copy of the license under this software is released
! 21: * at COPYING file. This is LGPL software: you are welcome to
! 22: * develop proprietary applications using this library without any
! 23: * royalty or fee but returning back any change, improvement or
! 24: * addition in the form of source code, project image, documentation
! 25: * patches, etc.
! 26: *
! 27: * For commercial support on build XML enabled solutions contact us:
! 28: *
! 29: * Postal address:
! 30: * Advanced Software Production Line, S.L.
! 31: * Edificio Alius A, Oficina 102,
! 32: * C/ Antonio Suarez Nº 10,
! 33: * Alcalá de Henares 28802 Madrid
! 34: * Spain
! 35: *
! 36: * Email address:
! 37: * info@aspl.es - http://www.aspl.es/xml
! 38: */
! 39:
! 40: #include <axl_decl.h>
! 41: #include <axl_list.h>
! 42: #include <axl_log.h>
! 43: #include <axl_stream.h>
! 44:
! 45: #define LOG_DOMAIN "axl-list"
! 46:
! 47: typedef struct _axlListNode axlListNode;
! 48:
! 49: struct _axlList {
! 50: /* functions used by the list to properly order elements
! 51: * inside it and how they are destroyed */
! 52: axlEqualFunc are_equal;
! 53: axlDestroyFunc destroy_data;
! 54:
! 55: /* pointers to the list content */
! 56: axlListNode * first_node;
! 57: axlListNode * last_node;
! 58:
! 59: /* list length */
! 60: int length;
! 61:
! 62: /* memory management functions */
! 63: axlListNode ** preallocated;
! 64: int available;
! 65: int allocated;
! 66: };
! 67:
! 68: struct _axlListNode {
! 69: axlListNode * previous;
! 70: axlListNode * next;
! 71: axlPointer data;
! 72: };
! 73:
! 74: struct _axlListCursor {
! 75: axlList * list;
! 76: axlListNode * current;
! 77: };
! 78:
! 79: /**
! 80: * \defgroup axl_list_module Axl List: A configurable double-linked list used across the library.
! 81: */
! 82:
! 83: /**
! 84: * \addtogroup axl_list_module
! 85: * @{
! 86: */
! 87:
! 88: /**
! 89: * @internal
! 90: *
! 91: * Internal are equal handler implementation for the axl list module
! 92: * that always return 0.
! 93: */
! 94: int __axl_list_always_true (axlPointer a, axlPointer b)
! 95: {
! 96: return 0;
! 97: }
! 98:
! 99: /**
! 100: * @internal
! 101: *
! 102: * Preallocates nodes to be used to store data on the lists.
! 103: *
! 104: * @param list The list where the preallocation operation will be
! 105: * performed.
! 106: */
! 107: void __axl_list_allocate_nodes (axlList * list)
! 108: {
! 109: int iterator;
! 110:
! 111: list->available = 1;
! 112: list->allocated += list->available;
! 113:
! 114: /* allocate enough memory to hold all nodes already
! 115: * allocated */
! 116: if (list->preallocated == NULL)
! 117: list->preallocated = axl_new (axlListNode *, list->allocated);
! 118: else
! 119: list->preallocated = realloc (list->preallocated, (sizeof (axlListNode *)) * list->allocated);
! 120:
! 121: /* allocate a node for each available position */
! 122: for (iterator = 0; iterator < list->available; iterator++) {
! 123: list->preallocated[iterator] = axl_new (axlListNode, 1);
! 124: }
! 125:
! 126: return;
! 127: }
! 128:
! 129: /**
! 130: * @internal
! 131: *
! 132: * Disposes the node provided, reusing on the next operation
! 133: * requested.
! 134: */
! 135: void __axl_list_dispose_node (axlList * list, axlListNode * node)
! 136: {
! 137: /* store the node to be usable again */
! 138: list->preallocated [list->available] = node;
! 139:
! 140: /* increase current available nodes */
! 141: list->available++;
! 142:
! 143: return;
! 144: }
! 145:
! 146: /**
! 147: * @internal
! 148: *
! 149: * Returns a reference to an list node to be used.
! 150: */
! 151: axlListNode * __axl_list_get_next_node_available (axlList * list)
! 152: {
! 153: axlListNode * node;
! 154:
! 155: /* check that there are nodes available */
! 156: if (list->available == 0)
! 157: __axl_list_allocate_nodes (list);
! 158:
! 159: /* get the next node available */
! 160: node = list->preallocated[list->available - 1];
! 161: list->available--;
! 162:
! 163: /* clean node */
! 164: node->next = NULL;
! 165: node->previous = NULL;
! 166: node->data = NULL;
! 167:
! 168: return node;
! 169: }
! 170:
! 171:
! 172: /**
! 173: * @brief Creates a new \ref axlList, using provided handlers.
! 174: *
! 175: * An \ref axlList is a double linked list, with the hability to
! 176: * recognize elements inside its list by providing the \ref
! 177: * axlEqualFunc "are_equal" function and the ability to release
! 178: * memory allocated by the data stored by providing a \ref
! 179: * axlDestroyFunc "destroy_data" handler.
! 180: *
! 181: * The destroy handler is a optional value. If not provided, any
! 182: * automatic deallocation function will not provided.
! 183: *
! 184: * The "are equal" handler is not optinal. You must provide it to make
! 185: * the list work. In the case you don't like a ordering feature you
! 186: * can provide an are equal that just return 0 when elements are equal
! 187: * and always -1 for the rest of the cases if element should be
! 188: * appended or 1 if the element should be prepended.
! 189: *
! 190: * The list is not prepared to be managed at the same type by several
! 191: * threads. If the list is created and then used by several threads it
! 192: * will work properly. However, if several threads add and removes
! 193: * elements at the same time rainy days will come and you'll get funny
! 194: * behaviours.
! 195: *
! 196: * To create the list you must provide two function that performs some
! 197: * minimal functions required by the list o properly order the data
! 198: * inside the list and how this data is deallocated (this is
! 199: * optional).
! 200: *
! 201: * For example, to create a list that will hold strings dinamically
! 202: * allocated you can use:
! 203: * \code
! 204: * axlList * list = axl_list_new (axl_list_equal_string, axl_free);
! 205: * \endcode
! 206: *
! 207: * For a list that will holds integer values you can use: \ref
! 208: * axl_list_equal_int.
! 209: *
! 210: * Previous list will cause all strings inside to be deallocated once
! 211: * called to \ref axl_list_free. If you don't like this, do not
! 212: * provide the deallocation function.
! 213: *
! 214: * You can always use the following function to make the list to allways
! 215: * add all data at the end of the list: \ref axl_list_always_return_1,
! 216: * which, as its names indicates, allways return 1, causing the item
! 217: * to be added at the end of the list. See \ref axlEqualFunc
! 218: * documentation to know more about creating ordenation functions.
! 219: *
! 220: * Now you have your list created, you can use the following functions
! 221: * to add items:
! 222: *
! 223: * - \ref axl_list_add
! 224: * - \ref axl_list_add_at
! 225: * - \ref axl_list_prepend
! 226: * - \ref axl_list_append
! 227: *
! 228: * Once you have inserted some data, you can use the following piece
! 229: * of code to perform an iteration:
! 230: *
! 231: * \code
! 232: * int iterator = 0;
! 233: * while (iterator < axl_list_length (list)) {
! 234: * // get the data at the given position
! 235: * data = axl_list_get_nth (list, iterator);
! 236: *
! 237: * // update the iterator
! 238: * iterator++;
! 239: * }
! 240: * \endcode
! 241: *
! 242: * However, it is preferred to use the \ref axlListCursor, which is
! 243: * far more efficient. See the following function to get more
! 244: * information: \ref axl_list_cursor_new.
! 245: *
! 246: * In general, if you are going to perform a lookup for a single item
! 247: * you can use \ref axl_list_lookup (by providing a handler) or \ref
! 248: * axl_list_get_nth if you know the position.
! 249: *
! 250: *
! 251: * @param are_equal The equal function to be used by the list to find
! 252: * and order elements inside the list.
! 253: *
! 254: * @param destroy_data An optional handler to destroy nodes in the
! 255: * case the list is unrefered.
! 256: *
! 257: * @return A newly allocated list, that must be destroy by calling to
! 258: * \ref axl_list_free.
! 259: */
! 260: axlList * axl_list_new (axlEqualFunc are_equal, axlDestroyFunc destroy_data)
! 261: {
! 262: axlList * result;
! 263:
! 264: axl_return_val_if_fail (are_equal, NULL);
! 265:
! 266: result = axl_new (axlList, 1);
! 267: result->are_equal = are_equal;
! 268: result->destroy_data = destroy_data;
! 269:
! 270: /* preallocate memory for nodes */
! 271: /* __axl_list_allocate_nodes (result); */
! 272:
! 273: return result;
! 274: }
! 275:
! 276: /**
! 277: * @brief Allows to reconfigure the destroy function to be used on
! 278: * this list. This function can be useful to disable the destroy
! 279: * function associated to the list.
! 280: *
! 281: * @param list The list to reconfigure or disable (NULL) the destroy function.
! 282: *
! 283: * @param destroy_data The reference to the destroy function to be
! 284: * used or NULL to disable it.
! 285: */
! 286: void axl_list_set_destroy_func (axlList * list, axlDestroyFunc destroy_data)
! 287: {
! 288: axl_return_if_fail (list);
! 289: list->destroy_data = destroy_data;
! 290: return;
! 291: }
! 292:
! 293: /**
! 294: * @brief Allows to copy the provided list, returning a newly
! 295: * allocated structure.
! 296: *
! 297: * The copy process can also perform a deep copy for all data stored
! 298: * inside the \ref axlList. However, for this purpose it is required
! 299: * to provide a duplication function that is able to implement the
! 300: * duplication operation over the data received.
! 301: *
! 302: * This handler is optional, and in the case it is not provided, the
! 303: * list returned will be a copy having reference to the content
! 304: * stored.
! 305: *
! 306: * NOTE: the function also copy the destroy and equal function
! 307: * configured at \ref axl_list_new. If you want to disable destroy
! 308: * function on the copy returned you must use \ref
! 309: * axl_list_set_destroy_func, passing NULL as destroy handler.
! 310: *
! 311: * @param list The list to copy.
! 312: * @param func The duplication function used to perform a deep copy (optional handler).
! 313: *
! 314: * @return A newly allocated \ref axlList with the same configuration
! 315: * as the one provided.
! 316: */
! 317: axlList * axl_list_copy (axlList * list, axlDuplicateFunc func)
! 318: {
! 319: axlList * result;
! 320: int iterator;
! 321: axlPointer data;
! 322:
! 323: axl_return_val_if_fail (list, NULL);
! 324:
! 325: /* create a new axl list */
! 326: result = axl_list_new (list->are_equal, list->destroy_data);
! 327:
! 328: /* if the duplicate function is NULL, remove the destroy
! 329: * function */
! 330: if (func == NULL)
! 331: result->destroy_data = NULL;
! 332:
! 333: /* add all elements */
! 334: iterator = 0;
! 335: while (iterator < axl_list_length (list)) {
! 336: /* get data pointer from the list */
! 337: data = axl_list_get_nth (list, iterator);
! 338:
! 339: /* try to make a copy */
! 340: if (func != NULL)
! 341: data = func (data);
! 342:
! 343: /* add the data to the new list */
! 344: axl_list_add (result, data);
! 345:
! 346: /* update index */
! 347: iterator++;
! 348: }
! 349:
! 350: return result;
! 351: }
! 352:
! 353: /**
! 354: * @brief Equal function that is prepared to receive two strings a
! 355: * return if they are equal.
! 356: *
! 357: * This function is provided as a convenience implementation for the
! 358: * \ref axl_list_new function, allowing to store strings inside the
! 359: * given list.
! 360: *
! 361: * The function will return 0 if the string are equal and 1 if
! 362: * not. This will cause strings to be append at the end of the list.
! 363: *
! 364: * @param a The first string to compare.
! 365: * @param b The second string to compare.
! 366: */
! 367: int axl_list_equal_string (axlPointer a, axlPointer b)
! 368: {
! 369: int length;
! 370:
! 371: axl_return_val_if_fail (a, 1);
! 372: axl_return_val_if_fail (b, 1);
! 373:
! 374: /* get length */
! 375: length = strlen (a);
! 376:
! 377: /* check first that both strings have the same length */
! 378: if (length != strlen (b))
! 379: return 1;
! 380:
! 381: if (axl_stream_cmp (a, b, length))
! 382: return 0;
! 383: /* differs */
! 384: return 1;
! 385: }
! 386:
! 387: /**
! 388: * @brief Equal function that is preprated to receive to integers and
! 389: * return if they are equal.
! 390: *
! 391: * It is assumed that integers are stored in the list using the
! 392: * following:
! 393: * \code
! 394: * axl_list_add (list, INT_TO_PTR (integer));
! 395: * \endcode
! 396: *
! 397: * You can use this function to create an \ref axlList that stores
! 398: * integer values as follows:
! 399: * \code
! 400: * list = axl_list_new (axl_list_equal_int, NULL);
! 401: * \endcode
! 402: *
! 403: * The list created with this function will order data from litter to
! 404: * greater values.
! 405: *
! 406: *
! 407: * @param a A reference to the first integer.
! 408: * @param b A reference to the second integer.
! 409: *
! 410: * @return 0 if values received are equal, and 1 if b is greater than
! 411: * b. Otherwise -1 is returned.
! 412: */
! 413: int axl_list_equal_int (axlPointer a, axlPointer b)
! 414: {
! 415: /* especial case where a 0 is stored */
! 416: if (PTR_TO_INT (a) == PTR_TO_INT (b))
! 417: return 0;
! 418: else if (PTR_TO_INT (a) < PTR_TO_INT (b))
! 419: return -1;
! 420: else
! 421: return 1;
! 422: }
! 423:
! 424: /**
! 425: * @brief An equal function that could be used to make elements to be
! 426: * stored inside an \ref axlList at the end as the are added, without
! 427: * replacing any previously added item.
! 428: *
! 429: *
! 430: * If it is needed to create a list that stores elements at the end as
! 431: * they are added, this function could be used as the \ref
! 432: * axlEqualFunc, while calling to axl_list_new.
! 433: *
! 434: * @param a First item.
! 435: * @param b Second item.
! 436: *
! 437: * @return The function always return 1.
! 438: *
! 439: * NOTE: If you use this function and your intention is to remove
! 440: * items (without calling to axl_list_free) you must use \ref
! 441: * axl_list_remove_ptr or \ref axl_list_unlink_ptr since \ref
! 442: * axl_list_remove and \ref axl_list_unlink relays on the equal
! 443: * function to find and remove the item. Because this function never
! 444: * return 0, the item is never removed.
! 445: */
! 446: int axl_list_always_return_1 (axlPointer a, axlPointer b)
! 447: {
! 448: return 1;
! 449: }
! 450:
! 451: /**
! 452: * @brief Allows to store a new element inside the list, using the
! 453: * provided data.
! 454: *
! 455: * The function will fail to perform any action if a null reference is
! 456: * provided to the function.
! 457: *
! 458: * @param list The list where the element will be added.
! 459: *
! 460: * @param pointer The pointer to store.
! 461: *
! 462: * NOTE: The function uses the equal function defined at \ref
! 463: * axl_list_new. If the function shows that the item to be added is
! 464: * already added (because the equal function returns 0, then the item
! 465: * won't be added.
! 466: *
! 467: */
! 468: void axl_list_add (axlList * list, axlPointer pointer)
! 469: {
! 470: axlListNode * new_node;
! 471: axlListNode * node;
! 472: axlListNode * node2;
! 473:
! 474:
! 475: /* perform some environment checkings */
! 476: axl_return_if_fail (list);
! 477:
! 478: new_node = __axl_list_get_next_node_available (list);
! 479: new_node->data = pointer;
! 480:
! 481: /* check basic case */
! 482: if (list->first_node == NULL) {
! 483: list->first_node = new_node;
! 484: list->last_node = new_node;
! 485: list->length = 1;
! 486: return;
! 487: }
! 488:
! 489: /* complex case */
! 490: node = list->first_node;
! 491: node2 = list->last_node;
! 492:
! 493: /* lookup */
! 494: while ((node != NULL) || (node2 != NULL)) {
! 495: /* lookup the head */
! 496: if (node != NULL) {
! 497: switch (list->are_equal (node->data, pointer)) {
! 498: case -1:
! 499: /* the node should be added before node */
! 500: new_node->next = node;
! 501: new_node->previous = node->previous;
! 502: node->previous = new_node;
! 503:
! 504: /* if new previous is null do not update it */
! 505: if (new_node->previous != NULL)
! 506: new_node->previous->next = new_node;
! 507: else
! 508: list->first_node = new_node;
! 509:
! 510: /* update list length */
! 511: list->length ++;
! 512: return;
! 513: case 0:
! 514: /* the node found is equal, do not perform any operation */
! 515: return;
! 516: case 1:
! 517: default:
! 518: /* the node should be added after */
! 519: node = node->next;
! 520: break;
! 521: }
! 522: } /* end if */
! 523:
! 524: /* lookup from the tail */
! 525: if (node2 != NULL) {
! 526: switch (list->are_equal (node2->data, pointer)) {
! 527: case -1:
! 528: default:
! 529: /* the node should be added before node */
! 530: node2 = node2->previous;
! 531: break;
! 532: case 0:
! 533:
! 534: /* the node found is equal, do not perform any operation */
! 535: return;
! 536: case 1:
! 537: /* the node should be added after */
! 538: new_node->previous = node2;
! 539: new_node->next = node2->next;
! 540: node2->next = new_node;
! 541:
! 542: /* do not update if next is NULL */
! 543: if (new_node->next != NULL)
! 544: new_node->next->previous = new_node;
! 545: else
! 546: list->last_node = new_node;
! 547:
! 548: /* update length size */
! 549: list->length ++;
! 550: return;
! 551: }
! 552: } /* end if */
! 553: } /* end while */
! 554:
! 555: /* nothing more to do */
! 556: return;
! 557: }
! 558:
! 559: /**
! 560: * @brief Allows to adds the provided item to the given list at the
! 561: * selected position.
! 562: *
! 563: * The function will perform an indexed addition, using the value
! 564: * <b>position</b>, by-passing current list configuration (\ref
! 565: * axl_list_new).
! 566: *
! 567: * If the position is greater than the length of the list, the item is
! 568: * added at the end of the list. If the position is 0, the item is
! 569: * added at the begin (equivalent to call \ref axl_list_prepend).
! 570: *
! 571: * If an item is found at the provided position, the element is added
! 572: * before the already found.
! 573: *
! 574: * @param list The list where the addition operation will be performed.
! 575: *
! 576: * @param pointer The item to add to the list.
! 577: *
! 578: * @param position Position where the addition operation will be
! 579: * performed. Values allowed ranges from 0 up to list length - 1.
! 580: */
! 581: void axl_list_add_at (axlList * list, axlPointer pointer, int position)
! 582: {
! 583: int iterator;
! 584: axlListNode * node;
! 585: axlListNode * new_node;
! 586:
! 587: /* check incoming values */
! 588: axl_return_if_fail (list);
! 589:
! 590: /* check if we have a prepend operation */
! 591: if (position <= 0) {
! 592: __axl_log (LOG_DOMAIN, AXL_LEVEL_DEBUG, "adding item using prepend");
! 593: /* prepend */
! 594: axl_list_prepend (list, pointer);
! 595:
! 596: return;
! 597: }
! 598: /* check if we have an append operation */
! 599: if (position >= list->length) {
! 600: __axl_log (LOG_DOMAIN, AXL_LEVEL_DEBUG, "adding item using append (position=%d >= length=%d)",
! 601: position, list->length);
! 602: /* append */
! 603: axl_list_append (list, pointer);
! 604:
! 605: return;
! 606: }
! 607:
! 608: /* allocate a new node */
! 609: new_node = __axl_list_get_next_node_available (list);
! 610: new_node->data = pointer;
! 611:
! 612:
! 613: __axl_log (LOG_DOMAIN, AXL_LEVEL_DEBUG, "looking node position: %d", position);
! 614:
! 615: /* basic case isn't reached here (remove first and last
! 616: * cases) */
! 617: iterator = 1;
! 618: node = list->first_node->next;
! 619: while (iterator < position) {
! 620:
! 621: /* get the next element */
! 622: node = node->next;
! 623:
! 624: /* update the iterator */
! 625: iterator++;
! 626: }
! 627:
! 628: __axl_log (LOG_DOMAIN, AXL_LEVEL_DEBUG, "adding item at: %d", iterator);
! 629:
! 630: /* add the element */
! 631: new_node->previous = node->previous;
! 632: if (node->previous != NULL)
! 633: node->previous->next = new_node;
! 634:
! 635: new_node->next = node;
! 636: node->previous = new_node;
! 637:
! 638: /* update number of items inside */
! 639: list->length++;
! 640: return;
! 641: }
! 642:
! 643: /**
! 644: * @brief Allows to add a node to the provided list, at the first
! 645: * position, without taking into consideration current \ref axlList
! 646: * configuration (\ref axlEqualFunc at \ref axl_list_new).
! 647: *
! 648: * @param list The list where the data will be added at the first
! 649: * position.
! 650: *
! 651: * @param pointer The pointer to add.
! 652: */
! 653: void axl_list_prepend (axlList * list, axlPointer pointer)
! 654: {
! 655: axlListNode * new_node;
! 656:
! 657: axl_return_if_fail (list);
! 658:
! 659: /* simulate adding the node at the first position */
! 660: new_node = __axl_list_get_next_node_available (list);
! 661: new_node->data = pointer;
! 662:
! 663: /* make the new node the be the first one */
! 664: if (list->first_node == NULL) {
! 665: list->first_node = new_node;
! 666: list->last_node = new_node;
! 667: }else {
! 668: list->first_node->previous = new_node;
! 669: new_node->next = list->first_node;
! 670: list->first_node = new_node;
! 671: }
! 672:
! 673: /* update number of items inside */
! 674: list->length++;
! 675:
! 676: return;
! 677: }
! 678:
! 679:
! 680: /**
! 681: * @brief Allows to add a node to the provided list, at the last
! 682: * position, without taking into consideration current \ref axlList
! 683: * configuration (\ref axlEqualFunc at \ref axl_list_new).
! 684: *
! 685: * @param list The list where the data will be added at the last
! 686: * position.
! 687: *
! 688: * @param pointer The pointer to add.
! 689: */
! 690: void axl_list_append (axlList * list, axlPointer pointer)
! 691: {
! 692: axlListNode * new_node;
! 693:
! 694: axl_return_if_fail (list);
! 695:
! 696: /* simulate adding the node at the first position */
! 697: new_node = __axl_list_get_next_node_available (list);
! 698: new_node->data = pointer;
! 699:
! 700: /* make the new node the be the first one */
! 701: if (list->last_node == NULL) {
! 702: list->first_node = new_node;
! 703: list->last_node = new_node;
! 704: }else {
! 705: list->last_node->next = new_node;
! 706: new_node->previous = list->last_node;
! 707: list->last_node = new_node;
! 708: }
! 709:
! 710: /* update number of items inside */
! 711: list->length++;
! 712:
! 713: return;
! 714: }
! 715:
! 716: /**
! 717: * @internal Internal list lookup using a linear search, checking all
! 718: * items inside the list taking into considerations hints provided by
! 719: * equal function.
! 720: *
! 721: * @param list The list where the linear search will be performed.
! 722: * @param pointer The pointer that is being looked up.
! 723: *
! 724: * @return A reference to the internal axl list node containing the
! 725: * pointer.
! 726: */
! 727: axlListNode * axl_list_internal_linear_lookup (axlList * list,
! 728: axlPointer pointer)
! 729: {
! 730: axlListNode * node;
! 731:
! 732: axl_return_val_if_fail (list, NULL);
! 733:
! 734: /* complex case */
! 735: node = list->first_node;
! 736:
! 737: /* lookup */
! 738: while (node != NULL) {
! 739: if (list->are_equal (node->data, pointer) == 0)
! 740: return node;
! 741:
! 742: /* the node should be after this one */
! 743: node = node->next;
! 744:
! 745: } /* end while */
! 746:
! 747: return NULL;
! 748: }
! 749:
! 750: /**
! 751: * @internal Internal list lookup using a linear search, checking all
! 752: * items inside the list withtout taking into considerations hints
! 753: * provided by equal function (search by pointer).
! 754: *
! 755: * @param list The list where the linear search will be performed.
! 756: * @param pointer The pointer that is being looked up.
! 757: *
! 758: * @return A reference to the internal axl list node containing the
! 759: * pointer.
! 760: */
! 761: axlListNode * axl_list_internal_linear_lookup_ptr (axlList * list,
! 762: axlPointer pointer)
! 763: {
! 764: axlListNode * node;
! 765:
! 766: axl_return_val_if_fail (list, NULL);
! 767:
! 768: /* complex case */
! 769: node = list->first_node;
! 770:
! 771: /* lookup */
! 772: while (node && node->data != pointer) {
! 773: /* the node should be after this one */
! 774: node = node->next;
! 775: } /* end while */
! 776:
! 777: /* return current result */
! 778: return node;
! 779: }
! 780:
! 781: /**
! 782: * @internal
! 783: * @brief Internal lookup function to locate the axlListNode that contains the pointer.
! 784: *
! 785: *
! 786: * @param list The list where the lookup will be performed.
! 787: * @param pointer The pointer data to lookup.
! 788: *
! 789: * @return A reference to the \ref axlListNode or NULL if no pointer
! 790: * is found.
! 791: */
! 792: axlListNode * axl_list_internal_lookup (axlList * list, axlPointer pointer)
! 793: {
! 794: axlListNode * node;
! 795: axlListNode * node2;
! 796:
! 797: axl_return_val_if_fail (list, NULL);
! 798: axl_return_val_if_fail (pointer, NULL);
! 799:
! 800: /* complex case */
! 801: node = list->first_node;
! 802: node2 = list->last_node;
! 803:
! 804: /* lookup */
! 805: while ((node != NULL) || (node2 != NULL)) {
! 806: /* lookup the head */
! 807: if (node != NULL) {
! 808: switch (list->are_equal (node->data, pointer)) {
! 809: case -1:
! 810: default:
! 811: /* node should be before the node
! 812: * found. So we are not going to find
! 813: * a node that is lower, the element
! 814: * is not in the list.
! 815: */
! 816: return NULL;
! 817: case 0:
! 818: return node;
! 819: case 1:
! 820: /* the node should be after this one */
! 821: node = node->next;
! 822: break;
! 823: }
! 824: } /* end if */
! 825:
! 826: /* lookup from the tail */
! 827: if (node2 != NULL) {
! 828: switch (list->are_equal (node2->data, pointer)) {
! 829: case -1:
! 830: /* the node should be added before node */
! 831: node2 = node2->next;
! 832: break;
! 833: case 0:
! 834: return node2;
! 835: case 1:
! 836: default:
! 837: /* it seems that the node should be
! 838: * found after this node but this is
! 839: * not going to be possible. The node is not in the list.
! 840: */
! 841: return NULL;
! 842: }
! 843: } /* end if */
! 844: } /* end while */
! 845:
! 846: return NULL;
! 847: }
! 848:
! 849:
! 850: /**
! 851: * @internal
! 852: *
! 853: * @brief Allows to lookup the pointer stored, inside the provided
! 854: * list, on the given position.
! 855: *
! 856: * @param list The list where the operation will be performed.
! 857: * @param position The position to lookup for stored data.
! 858: *
! 859: * @return A reference or NULL if fails.
! 860: */
! 861: axlListNode * axl_list_internal_get_nth (axlList * list, int position)
! 862: {
! 863: axlListNode * node;
! 864: int iterator = 0;
! 865:
! 866: axl_return_val_if_fail (list, NULL);
! 867: axl_return_val_if_fail (position >= 0 && position < list->length, NULL);
! 868:
! 869: /* iterate until the node is found */
! 870: node = list->first_node;
! 871: while (node != NULL && (iterator != position)) {
! 872: iterator ++;
! 873: node = node->next;
! 874: }
! 875:
! 876: /* return data found */
! 877: if (iterator == position)
! 878: return node;
! 879: return NULL;
! 880: }
! 881:
! 882: /* remove the selected node */
! 883: void __axl_list_common_remove_selected_node (axlList * list, axlListNode * node,
! 884: axl_bool alsoRemove)
! 885: {
! 886: axlPointer pointer;
! 887:
! 888: /* do not remove anything if a null reference is received */
! 889: if (node == NULL)
! 890: return;
! 891:
! 892: /* get a reference to the pointer */
! 893: pointer = node->data;
! 894:
! 895: if (node->previous == NULL)
! 896: list->first_node = node->next;
! 897: else
! 898: node->previous->next = node->next;
! 899:
! 900: if (node->next == NULL)
! 901: list->last_node = node->previous;
! 902: else
! 903: node->next->previous = node->previous;
! 904:
! 905: /* release user space allocated memory
! 906: * if defined destroy function */
! 907: if (alsoRemove && (list->destroy_data != NULL))
! 908: list->destroy_data (pointer);
! 909:
! 910: /* release memory allocated by the node */
! 911: __axl_list_dispose_node (list, node);
! 912:
! 913: /* decrease list length */
! 914: list->length--;
! 915:
! 916: /* nothing more to do */
! 917: return;
! 918: }
! 919:
! 920: /**
! 921: * @internal
! 922: *
! 923: * Internal support for axl_list_remove and axl_list_unlink
! 924: * function. The function perform a node removing, the one that
! 925: * contains the node pointed by the provided pointer, and making a
! 926: * node deallocation according to the configuration of the
! 927: * <b>alsoRemove</b>.
! 928: *
! 929: * @param list The list where the operation will be performed.
! 930: *
! 931: * @param pointer The pointer to remove
! 932: *
! 933: * @param alsoRemove Also call to destroy function.
! 934: *
! 935: * @param byPtr Makes the linear search to be done by pointer.
! 936: */
! 937: void axl_list_common_remove (axlList * list, axlPointer pointer, axl_bool alsoRemove, axl_bool byPtr)
! 938: {
! 939: axlListNode * node;
! 940:
! 941: axl_return_if_fail (list);
! 942:
! 943: /* complex case */
! 944: if (byPtr)
! 945: node = axl_list_internal_linear_lookup_ptr (list, pointer);
! 946: else
! 947: node = axl_list_internal_linear_lookup (list, pointer);
! 948: if (node == NULL) {
! 949: __axl_log (LOG_DOMAIN, AXL_LEVEL_DEBUG, "unable to find item by pointer (0x%x)",
! 950: pointer);
! 951: return;
! 952: }
! 953:
! 954: /* remove the selected node */
! 955: __axl_list_common_remove_selected_node (list, node, alsoRemove);
! 956:
! 957: return;
! 958: }
! 959:
! 960:
! 961: /**
! 962: * @brief Allows to remove the given pointer from the list.
! 963: *
! 964: * The element referenced by <b>pointer</b> will be removed from the
! 965: * list, include the memory allocated if a destroy function were
! 966: * provided.
! 967: *
! 968: * If it is required to remove a pointer from the list, without
! 969: * calling to the destroy function, you can use \ref axl_list_unlink.
! 970: *
! 971: * The function will fail to work if references provided are NULL.
! 972: *
! 973: * @param list The list where the removal operation will be performed.
! 974: * @param pointer The pointer where the
! 975: *
! 976: * NOTE: The function uses the current equal function configured. A
! 977: * not properly configured equal function will make this function to
! 978: * not remove the item selected. If you are trying to remove by
! 979: * pointer, you can use \ref axl_list_remove_ptr.
! 980: */
! 981: void axl_list_remove (axlList * list, axlPointer pointer)
! 982: {
! 983:
! 984: /* perform a complete removing */
! 985: axl_list_common_remove (list, pointer,
! 986: /* alsoRemove */
! 987: axl_true,
! 988: /* byPtr */
! 989: axl_false);
! 990:
! 991: return;
! 992: }
! 993:
! 994: /**
! 995: * @internal Implementation that removes or unlinks a selected node at
! 996: * a particular position.
! 997: */
! 998: void __axl_list_remove_at_common (axlList * list, int position, axl_bool remove_node)
! 999: {
! 1000: axlListNode * node;
! 1001: int iterator = 0;
! 1002:
! 1003: axl_return_if_fail (list);
! 1004:
! 1005: /* find the item by position */
! 1006: node = list->first_node;
! 1007:
! 1008: /* lookup */
! 1009: while (node) {
! 1010: /* return selected node */
! 1011: if (iterator == position)
! 1012: break;
! 1013:
! 1014: /* the node should be after this one */
! 1015: node = node->next;
! 1016:
! 1017: /* next iterator */
! 1018: iterator++;
! 1019: } /* end while */
! 1020:
! 1021: if (node) {
! 1022: /* remove selected node */
! 1023: __axl_list_common_remove_selected_node (list, node, remove_node);
! 1024: } /* end if */
! 1025: return;
! 1026: }
! 1027:
! 1028: /**
! 1029: * @brief Allows to remove a particular item inside the list at a
! 1030: * selected position.
! 1031: *
! 1032: * This function also deallocates the memory used by the node located
! 1033: * at the particular position. In the case only a removal operation is
! 1034: * required use \ref axl_list_unlink_at.
! 1035: *
! 1036: * @param list The list where the remove operation will take place.
! 1037: *
! 1038: * @param position The position where the removal operation will take
! 1039: * place. Position values ranges from 0 up to (N - 1).
! 1040: */
! 1041: void axl_list_remove_at (axlList * list, int position)
! 1042: {
! 1043: /* call to common implementation */
! 1044: __axl_list_remove_at_common (list, position, axl_true);
! 1045: return;
! 1046: }
! 1047:
! 1048: /**
! 1049: * @brief Allows to remove the provided pointer from the list (calling
! 1050: * to the destroy function defined).
! 1051: *
! 1052: * Unlike \ref axl_list_remove, which removes the element selected by
! 1053: * using the equal function configured at \ref axl_list_new, this
! 1054: * function allows to perform a remove operation by pointer.
! 1055: *
! 1056: * @param list The list on which the operation is performed.
! 1057: *
! 1058: * @param pointer The pointer to remove from the list.
! 1059: */
! 1060: void axl_list_remove_ptr (axlList * list, axlPointer pointer)
! 1061: {
! 1062: /* perform a complete removing */
! 1063: axl_list_common_remove (list, pointer,
! 1064: /* alsoRemove */
! 1065: axl_true,
! 1066: /* byPtr */
! 1067: axl_true);
! 1068: }
! 1069:
! 1070: /**
! 1071: * @brief Removes the given pointer from the list, without calling the
! 1072: * destroy function, even when it is configured.
! 1073: *
! 1074: * @param list The list where the operation will be performed.
! 1075: *
! 1076: * @param pointer The pointer to remove.
! 1077: */
! 1078: void axl_list_unlink (axlList * list, axlPointer pointer)
! 1079: {
! 1080: /* perform a complete removing */
! 1081: axl_list_common_remove (list, pointer,
! 1082: /* alsoRemove */
! 1083: axl_false,
! 1084: /* byPtr */
! 1085: axl_false);
! 1086:
! 1087: return;
! 1088: }
! 1089:
! 1090: /**
! 1091: * @brief Allows to remove the provided item from the axl list
! 1092: * withtout using the equal function provided (remove by pointer) and
! 1093: * without calling to the associated destroy function.
! 1094: *
! 1095: * @param list The list where the operation will be implemented.
! 1096: *
! 1097: * @param pointer the pointer to remove from the list without calling
! 1098: * to the destroy function.
! 1099: */
! 1100: void axl_list_unlink_ptr (axlList * list, axlPointer pointer)
! 1101: {
! 1102:
! 1103: /* perform an unlink operation, without using equal
! 1104: * function */
! 1105: /* perform a complete removing */
! 1106: axl_list_common_remove (list, pointer,
! 1107: /* alsoRemove */
! 1108: axl_false,
! 1109: /* byPtr */
! 1110: axl_true);
! 1111:
! 1112: return;
! 1113: }
! 1114:
! 1115: /**
! 1116: * @brief Allows to unlink a particular item inside the list at a
! 1117: * selected position.
! 1118: *
! 1119: * This function DO NOT deallocates the memory used by the node located
! 1120: * at the particular position. In the case a complete removal operation is
! 1121: * required use \ref axl_list_remove_at.
! 1122: *
! 1123: * @param list The list where the unlink operation will take place.
! 1124: *
! 1125: * @param position The position where the unlink operation will take
! 1126: * place. Position values ranges from 0 up to (N - 1).
! 1127: */
! 1128: void axl_list_unlink_at (axlList * list, int position)
! 1129: {
! 1130: /* call to common implementation */
! 1131: __axl_list_remove_at_common (list, position, axl_false);
! 1132: return;
! 1133: }
! 1134:
! 1135:
! 1136: /**
! 1137: * @brief Allows to remove the first element, calling to the destroy
! 1138: * function if defined.
! 1139: *
! 1140: * @param list The list where the first element will be removed.
! 1141: */
! 1142: void axl_list_remove_first (axlList * list)
! 1143: {
! 1144:
! 1145: axl_return_if_fail (list);
! 1146:
! 1147: /* do not perform any operation if no node is stored */
! 1148: if (list->first_node == NULL)
! 1149: return;
! 1150:
! 1151: /* remove the selected node */
! 1152: __axl_list_common_remove_selected_node (list, list->first_node, axl_true);
! 1153:
! 1154: return;
! 1155: }
! 1156:
! 1157: /**
! 1158: * @brief Allows to remove the first element from the list without
! 1159: * calling to the destroy function, even with it is defined.
! 1160: *
! 1161: * @param list The list where the first element will be removed.
! 1162: */
! 1163: void axl_list_unlink_first (axlList * list)
! 1164: {
! 1165:
! 1166: axl_return_if_fail (list);
! 1167:
! 1168: /* do not perform any operation if no node is stored */
! 1169: if (list->first_node == NULL)
! 1170: return;
! 1171:
! 1172: /* remove the selected node */
! 1173: __axl_list_common_remove_selected_node (list, list->first_node, axl_false);
! 1174:
! 1175: return;
! 1176: }
! 1177:
! 1178: /**
! 1179: * @brief Allows to remove the last element, calling to the destroy
! 1180: * function if defined.
! 1181: *
! 1182: * @param list The list where the last element will be removed.
! 1183: */
! 1184: void axl_list_remove_last (axlList * list)
! 1185: {
! 1186: axl_return_if_fail (list);
! 1187:
! 1188: /* do not perform any operation if no node is stored */
! 1189: if (list->last_node == NULL)
! 1190: return;
! 1191:
! 1192: /* remove the selected node */
! 1193: __axl_list_common_remove_selected_node (list, list->last_node, axl_true);
! 1194:
! 1195: return;
! 1196: }
! 1197:
! 1198: /**
! 1199: * @brief Allows to remove the last element from the list without
! 1200: * calling to the destroy function, even with it is defined.
! 1201: *
! 1202: * @param list The list where the last element will be removed.
! 1203: */
! 1204: void axl_list_unlink_last (axlList * list)
! 1205: {
! 1206: axl_return_if_fail (list);
! 1207:
! 1208: /* do not perform any operation if no node is stored */
! 1209: if (list->last_node == NULL)
! 1210: return;
! 1211:
! 1212: /* remove the selected node */
! 1213: __axl_list_common_remove_selected_node (list, list->last_node, axl_false);
! 1214:
! 1215: return;
! 1216: }
! 1217:
! 1218: /**
! 1219: * @brief Allows to check if the given pointer is stored on the given
! 1220: * list.
! 1221: *
! 1222: * @param list The list where the lookup will be performed.
! 1223: *
! 1224: * @param pointer The pointer to lookup.
! 1225: *
! 1226: * @return \ref axl_true if the element is stored on the list,
! 1227: * otherwise axl_false is returned. The function will fail to lookup
! 1228: * if a NULL reference is received, either the list or the pointer.
! 1229: */
! 1230: axl_bool axl_list_exists (axlList * list, axlPointer pointer)
! 1231: {
! 1232: axl_return_val_if_fail (list, axl_false);
! 1233: axl_return_val_if_fail (pointer, axl_false);
! 1234:
! 1235: if (axl_list_internal_lookup (list, pointer) != NULL)
! 1236: return axl_true;
! 1237: return axl_false;
! 1238: }
! 1239:
! 1240: /**
! 1241: * @brief Allows to check if the provided list is empty (no element
! 1242: * stored).
! 1243: *
! 1244: * @param list The list to check for emptyness.
! 1245: *
! 1246: * @return axl_true if the list is empty, axl_false if not. The function
! 1247: * return axl_false in the case a null reference is provided.
! 1248: */
! 1249: axl_bool axl_list_is_empty (axlList * list)
! 1250: {
! 1251: axl_return_val_if_fail (list, axl_false);
! 1252:
! 1253: /* check if the first node is defined */
! 1254: return (list->first_node == NULL);
! 1255: }
! 1256:
! 1257: /**
! 1258: * @brief Allows to check if the given pointer is stored on the given position.
! 1259: *
! 1260: * @param list The list where the operation will be run.
! 1261: * @param pointer The pointer to check.
! 1262: * @param position The position where is expected to find the pointer.
! 1263: *
! 1264: * @return axl_true if the given data, referenced by the pointer, is
! 1265: * stored on the given position.
! 1266: */
! 1267: axl_bool axl_list_exists_at (axlList * list, axlPointer pointer, int position)
! 1268: {
! 1269: axlListNode * node;
! 1270:
! 1271: node = axl_list_internal_get_nth (list, position);
! 1272: if (node != NULL) {
! 1273: if (! list->are_equal (node->data, pointer))
! 1274: return axl_true;
! 1275: }
! 1276: return axl_false;
! 1277: }
! 1278:
! 1279: /**
! 1280: * @brief Returns the first element stored on the list.
! 1281: *
! 1282: *
! 1283: * @param list The list where the first element stored will be
! 1284: * returned.
! 1285: *
! 1286: * @return An \ref axlPointer containing the data stored on the list.
! 1287: */
! 1288: axlPointer axl_list_get_first (axlList * list)
! 1289: {
! 1290: axl_return_val_if_fail (list, NULL);
! 1291:
! 1292: if (list->first_node == NULL)
! 1293: return NULL;
! 1294: return list->first_node->data;
! 1295: }
! 1296:
! 1297: /**
! 1298: * @brief Returns the last element stored on the list.
! 1299: *
! 1300: * @param list The list where the last element will be returned.
! 1301: *
! 1302: * @return An \ref axlPointer reference containing the last stored
! 1303: * value.
! 1304: */
! 1305: axlPointer axl_list_get_last (axlList * list)
! 1306: {
! 1307: axl_return_val_if_fail (list, NULL);
! 1308:
! 1309: if (list->last_node == NULL)
! 1310: return NULL;
! 1311: return list->last_node->data;
! 1312: }
! 1313:
! 1314: /**
! 1315: * @brief Allows to get current pointer stored at the given position.
! 1316: *
! 1317: * @param list The list where the data will be retrieved.
! 1318: *
! 1319: * @param position A value ranging from 0 up to the the list lenght -
! 1320: * 1.
! 1321: *
! 1322: * @return The \ref axlPointer stored on the given position or NULL if
! 1323: * fail.
! 1324: */
! 1325: axlPointer axl_list_get_nth (axlList * list, int position)
! 1326: {
! 1327: axlListNode * node;
! 1328:
! 1329: node = axl_list_internal_get_nth (list, position);
! 1330: if (node != NULL)
! 1331: return node->data;
! 1332: return NULL;
! 1333: }
! 1334:
! 1335: /**
! 1336: * @brief Allows to perform a linear lookup on the list provided,
! 1337: * givin a function that is used to now the object to return due to
! 1338: * the lookup.
! 1339: *
! 1340: * The function can also be used as a foreach function. The following
! 1341: * example shows how to launch the function and perform a tasks on the
! 1342: * lookup function:
! 1343: * \code
! 1344: * // perform the lookup
! 1345: * return axl_list_lookup (list, __find_item, name);
! 1346: *
! 1347: * // the lookup function
! 1348: * axl_bool __find_item (axlPointer _element, axlPointer data)
! 1349: * {
! 1350: * SomeItem * element = _element;
! 1351: * char * name = data;
! 1352: *
! 1353: * // check the name
! 1354: * if (axl_cmp (element->name, name))
! 1355: * return axl_true;
! 1356: *
! 1357: * // it is not the element
! 1358: * return axl_false;
! 1359: * }
! 1360: * \endcode
! 1361: *
! 1362: * In the case you create a list to hold string values, you can use
! 1363: * \ref axl_list_find_string as lookup function predefined to perform
! 1364: * the search.
! 1365: *
! 1366: * @param list The list where the lookup will be performed.
! 1367: *
! 1368: * @param func The function to use to perform the lookup.
! 1369: *
! 1370: * @param data User defined data that will be passed to the func provided.
! 1371: *
! 1372: * @return A pointer to the object found or NULL if no item was found.
! 1373: */
! 1374: axlPointer axl_list_lookup (axlList * list, axlLookupFunc func, axlPointer data)
! 1375: {
! 1376: axlListNode * node;
! 1377: axl_return_val_if_fail (list, NULL);
! 1378: axl_return_val_if_fail (func, NULL);
! 1379:
! 1380: /* get the first pointer */
! 1381: node = list->first_node;
! 1382: do {
! 1383: /* if the next node to check is NULL, terminate the
! 1384: * lookup. */
! 1385: if (node == NULL)
! 1386: return NULL;
! 1387:
! 1388: /* check if the node found is the one looked up */
! 1389: if (func (node->data, data))
! 1390: return node->data;
! 1391:
! 1392: /* seems not, update to the next reference */
! 1393: node = node->next;
! 1394:
! 1395: }while (1);
! 1396:
! 1397: /* return no node found */
! 1398: return NULL;
! 1399: }
! 1400:
! 1401: /**
! 1402: * @brief Helper function that could be used at \ref axl_list_lookup if
! 1403: * the list created only contains strings.
! 1404: *
! 1405: * Use this function as a parameter for the lookup function at \ref
! 1406: * axl_list_lookup.
! 1407: *
! 1408: * @param element The element at the list, in this case, an string value.
! 1409: *
! 1410: * @param data The data provided at \ref axl_list_lookup, in this
! 1411: * case, the value we are looking.
! 1412: *
! 1413: * @return \ref axl_true if the string was found, \ref axl_false if not.
! 1414: */
! 1415: axl_bool axl_list_find_string (axlPointer element, axlPointer data)
! 1416: {
! 1417: /* if the string received is null, just return axl_false */
! 1418: if (data == NULL)
! 1419: return axl_false;
! 1420:
! 1421: /* return the comparison status */
! 1422: return axl_cmp ((char *) element, (char *) data);
! 1423: }
! 1424:
! 1425: /**
! 1426: * @brief Allows to get current list length.
! 1427: *
! 1428: * @param list The list to operate.
! 1429: *
! 1430: * @return The list length or -1 if fail (the list reference received
! 1431: * is null).
! 1432: */
! 1433: int axl_list_length (axlList * list)
! 1434: {
! 1435: axl_return_val_if_fail (list, -1);
! 1436: return list->length;
! 1437: }
! 1438:
! 1439: /**
! 1440: * @brief Allows to destroy the given list, and all user space
! 1441: * associated memory if a destroy handler was provided.
! 1442: *
! 1443: * @param list The list to destroy
! 1444: */
! 1445: void axl_list_free (axlList * list)
! 1446: {
! 1447: axlListNode * node;
! 1448: axlListNode * node2;
! 1449: int iterator;
! 1450:
! 1451: /* if a null reference is received do not oper */
! 1452: if (list == NULL)
! 1453: return;
! 1454:
! 1455: node = list->first_node;
! 1456: while (node != NULL) {
! 1457: if (list->destroy_data != NULL) {
! 1458: list->destroy_data (node->data);
! 1459: }
! 1460: node2 = node;
! 1461: node = node->next;
! 1462:
! 1463: axl_free (node2);
! 1464: }
! 1465:
! 1466: /* allocate a node for each available position */
! 1467: for (iterator = 0; iterator < list->available; iterator++) {
! 1468: axl_free (list->preallocated[iterator]);
! 1469: }
! 1470:
! 1471: /* free the array */
! 1472: axl_free (list->preallocated);
! 1473:
! 1474: /* free the list itself */
! 1475: axl_free (list);
! 1476:
! 1477: return;
! 1478: }
! 1479:
! 1480: /* @} */
! 1481:
! 1482: /**
! 1483: * \defgroup axl_list_cursor_module Axl List Cursor: Iterator support for the Axl List
! 1484: */
! 1485:
! 1486: /**
! 1487: * \addtogroup axl_list_cursor_module
! 1488: * @{
! 1489: */
! 1490:
! 1491: /**
! 1492: * @brief Allows to get a cursor to iterate the list in a linear and
! 1493: * efficient way.
! 1494: *
! 1495: * The \ref axlListCursor could be used to iterate an \ref axlList in
! 1496: * an efficient way because it stores current state (position). Then
! 1497: * using the following functions you can modify the state (current
! 1498: * position to get):
! 1499: *
! 1500: * - \ref axl_list_cursor_first
! 1501: * - \ref axl_list_cursor_last
! 1502: * - \ref axl_list_cursor_next
! 1503: * - \ref axl_list_cursor_previous
! 1504: *
! 1505: * Finally, a function is provided to get the data stored at a
! 1506: * particular position, pointed by the current status of the cursor:
! 1507: *
! 1508: * - \ref axl_list_cursor_get
! 1509: *
! 1510: * You are allowed to remove elements from the list (\ref axlList)
! 1511: * having a cursor created (\ref axlListCursor), using \ref
! 1512: * axl_list_cursor_unlink.
! 1513: *
! 1514: * Here is an example:
! 1515: * \code
! 1516: * axlPointer value;
! 1517: * axlListCursor * cursor;
! 1518: *
! 1519: * // create the cursor
! 1520: * cursor = axl_list_cursor_new (list);
! 1521: *
! 1522: * // while there are more elements
! 1523: * while (axl_list_cursor_has_item (cursor)) {
! 1524: *
! 1525: * // get the value
! 1526: * value = axl_list_cursor_get (cursor);
! 1527: *
! 1528: *
! 1529: * // get the next
! 1530: * axl_list_cursor_next (cursor);
! 1531: *
! 1532: * // update the iterator
! 1533: * iterator++;
! 1534: *
! 1535: * }
! 1536: *
! 1537: * // free the cursor
! 1538: * axl_list_cursor_free (cursor);
! 1539: * \endcode
! 1540: *
! 1541: * @param list The list that the new cursor (\ref axlListCursor) will
! 1542: * provide access.
! 1543: *
! 1544: * @return A newly created \ref axlListCursor used to iterate the
! 1545: * list. Once finished you must call to \ref axl_list_cursor_free.
! 1546: */
! 1547: axlListCursor * axl_list_cursor_new (axlList * list)
! 1548: {
! 1549: axlListCursor * cursor;
! 1550:
! 1551: axl_return_val_if_fail (list, NULL);
! 1552:
! 1553: /* create the cursor */
! 1554: cursor = axl_new (axlListCursor, 1);
! 1555:
! 1556: /* initial configuration */
! 1557: cursor->list = list;
! 1558: cursor->current = list->first_node;
! 1559:
! 1560: return cursor;
! 1561: }
! 1562:
! 1563: /**
! 1564: * @brief Allows to configure the cursor to point to the first item of
! 1565: * the list (if there are any).
! 1566: *
! 1567: * @param cursor The cursor that is required to be configured to point the first item.
! 1568: */
! 1569: void axl_list_cursor_first (axlListCursor * cursor)
! 1570: {
! 1571: axl_return_if_fail (cursor);
! 1572:
! 1573: if (cursor->list->length == 0) {
! 1574: cursor->current = NULL;
! 1575: return;
! 1576: } /* end if */
! 1577:
! 1578: /* set the first node */
! 1579: cursor->current = cursor->list->first_node;
! 1580:
! 1581: return;
! 1582: }
! 1583:
! 1584: /**
! 1585: * @brief Allows to configure the cursor to point to the last item of
! 1586: * the list (if there are any).
! 1587: *
! 1588: * @param cursor The cursor that is required to be configured to point
! 1589: * to the last item.
! 1590: */
! 1591: void axl_list_cursor_last (axlListCursor * cursor)
! 1592: {
! 1593: axl_return_if_fail (cursor);
! 1594:
! 1595: /* set the first node */
! 1596: cursor->current = cursor->list->last_node;
! 1597:
! 1598: return;
! 1599: }
! 1600:
! 1601: /**
! 1602: * @brief Allows to configure the cursor to point to the next item of
! 1603: * the list (if there are any).
! 1604: *
! 1605: * @param cursor The cursor that is required to be configured to point
! 1606: * to the next item.
! 1607: */
! 1608: void axl_list_cursor_next (axlListCursor * cursor)
! 1609: {
! 1610: axl_return_if_fail (cursor);
! 1611:
! 1612: /* set the next node */
! 1613: if (cursor->current != NULL)
! 1614: cursor->current = cursor->current->next;
! 1615:
! 1616: return;
! 1617: }
! 1618:
! 1619: /**
! 1620: * @brief Allows to configure the cursor to point to the previous item
! 1621: * of the list (if there are any).
! 1622: *
! 1623: * @param cursor The cursor that is required to be configured to point
! 1624: * to the previous item.
! 1625: */
! 1626: void axl_list_cursor_previous (axlListCursor * cursor)
! 1627: {
! 1628: axl_return_if_fail (cursor);
! 1629:
! 1630: /* set the next node */
! 1631: if (cursor->current != NULL)
! 1632: cursor->current = cursor->current->previous;
! 1633:
! 1634: return;
! 1635: }
! 1636:
! 1637: /**
! 1638: * @brief Allows to check if there are more elements next to the
! 1639: * current element pointed by the cursor.
! 1640: *
! 1641: * @param cursor The cursor that is required to return if there are
! 1642: * next items.
! 1643: *
! 1644: * @return \ref axl_true if more items are found, otherwise \ref axl_false is
! 1645: * returned.
! 1646: */
! 1647: axl_bool axl_list_cursor_has_next (axlListCursor * cursor)
! 1648: {
! 1649: axl_return_val_if_fail (cursor, axl_false);
! 1650:
! 1651: /* check for empty list */
! 1652: if (cursor->current == NULL)
! 1653: return axl_false;
! 1654:
! 1655: /* return if the next element isn't null */
! 1656: return (cursor->current->next != NULL);
! 1657: }
! 1658:
! 1659: /**
! 1660: * @brief Allows to check if there are more elements next to the
! 1661: * current element pointed by the cursor.
! 1662: *
! 1663: * @param cursor The cursor that is required to return if there are
! 1664: * next items.
! 1665: *
! 1666: * @return \ref axl_true if more items are found, otherwise \ref axl_false is
! 1667: * returned.
! 1668: */
! 1669: axl_bool axl_list_cursor_has_previous (axlListCursor * cursor)
! 1670: {
! 1671: axl_return_val_if_fail (cursor, axl_false);
! 1672:
! 1673: /* check for empty list */
! 1674: if (cursor->current == NULL)
! 1675: return axl_false;
! 1676:
! 1677: /* return if the next element isn't null */
! 1678: return (cursor->current->previous != NULL);
! 1679: }
! 1680:
! 1681: /**
! 1682: * @brief Allows to know if the current position has items.
! 1683: *
! 1684: * @param cursor The cursor that is requested to return if a call to
! 1685: * \ref axl_list_cursor_get will return data.
! 1686: *
! 1687: * @return \ref axl_true if the list that is iterated can return data at
! 1688: * the current position, otherwise \ref axl_false is returned.
! 1689: */
! 1690: axl_bool axl_list_cursor_has_item (axlListCursor * cursor)
! 1691: {
! 1692: axl_return_val_if_fail (cursor, axl_false);
! 1693:
! 1694: /* return if there are current */
! 1695: return (cursor->current != NULL);
! 1696: }
! 1697:
! 1698: /**
! 1699: * @brief Allows to remove current element pointed by the cursor,
! 1700: * maintainig internal state of the cursor.
! 1701: *
! 1702: * The function won't call to the destroy function asociated to the
! 1703: * list. If you want the item stored to be also destroyed call \ref
! 1704: * axl_list_cursor_remove.
! 1705: *
! 1706: * @param cursor The cursor pointing to the item inside the list that
! 1707: * must be removed.
! 1708: */
! 1709: void axl_list_cursor_unlink (axlListCursor * cursor)
! 1710: {
! 1711: axlListNode * node;
! 1712:
! 1713: axl_return_if_fail (cursor);
! 1714:
! 1715: /* if current cursor is pointing nowhere, just do nothing */
! 1716: if (cursor->current == NULL)
! 1717: return;
! 1718:
! 1719: /* remember node */
! 1720: node = cursor->current;
! 1721:
! 1722: /* configure the cursor to point to the next element (or the previous if the next element is null) */
! 1723: cursor->current = (node->next != NULL) ? node->next : node->previous;
! 1724:
! 1725: /* call to unlik */
! 1726: __axl_list_common_remove_selected_node (cursor->list, node, axl_false);
! 1727:
! 1728: return;
! 1729: }
! 1730:
! 1731: /**
! 1732: * @brief Allows to remove current element pointed by the cursor,
! 1733: * maintainig internal state of the cursor, calling to the destroy
! 1734: * function associated in the list.
! 1735: *
! 1736: * The function will call to the destroy function asociated to the
! 1737: * list. If you don't want the item stored to be also destroyed call \ref
! 1738: * axl_list_cursor_unlink.
! 1739: *
! 1740: * @param cursor The cursor pointing to the item inside the list that
! 1741: * must be removed.
! 1742: */
! 1743: void axl_list_cursor_remove (axlListCursor * cursor)
! 1744: {
! 1745: axlListNode * node;
! 1746:
! 1747: axl_return_if_fail (cursor);
! 1748:
! 1749: /* if current cursor is pointing nowhere, just do nothing */
! 1750: if (cursor->current == NULL)
! 1751: return;
! 1752:
! 1753: /* remember node */
! 1754: node = cursor->current;
! 1755:
! 1756: /* configure the cursor to point to the next element (or the previous if the next element is null) */
! 1757: cursor->current = (node->next != NULL) ? node->next : node->previous;
! 1758:
! 1759: /* call to remove */
! 1760: __axl_list_common_remove_selected_node (cursor->list, node, axl_true);
! 1761:
! 1762: return;
! 1763: }
! 1764:
! 1765: /**
! 1766: * @brief Allows to get current data at the current cursor state.
! 1767: *
! 1768: * @param cursor The cursor that will be used to return the data
! 1769: * located at the list, using cursor current state.
! 1770: */
! 1771: axlPointer axl_list_cursor_get (axlListCursor * cursor)
! 1772: {
! 1773: axl_return_val_if_fail (cursor, NULL);
! 1774:
! 1775: /* nothing to return if current is NULL */
! 1776: if (cursor->current == NULL)
! 1777: return NULL;
! 1778:
! 1779: /* return data */
! 1780: return cursor->current->data;
! 1781: }
! 1782:
! 1783: /**
! 1784: * @brief Allows to get the reference to the list that is associated
! 1785: * to the cursor received.
! 1786: *
! 1787: * @param cursor The cursor that is required to return the list associated.
! 1788: *
! 1789: * @return A reference to the list being iterated or NULL if fails.
! 1790: */
! 1791: axlList * axl_list_cursor_list (axlListCursor * cursor)
! 1792: {
! 1793: /* check incoming cursor */
! 1794: axl_return_val_if_fail (cursor, NULL);
! 1795:
! 1796: /* return the list */
! 1797: return cursor->list;
! 1798: }
! 1799:
! 1800: /**
! 1801: * @brief Deallocates memory used by the cursor.
! 1802: *
! 1803: * @param cursor The cursor to be deallocated.
! 1804: */
! 1805: void axl_list_cursor_free (axlListCursor * cursor)
! 1806: {
! 1807: axl_return_if_fail (cursor);
! 1808:
! 1809: /* free the cursor */
! 1810: axl_free (cursor);
! 1811:
! 1812: return;
! 1813: }
! 1814:
! 1815: /* @} */
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to axl_list.c CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / gpl / axl / src