src/include/eina_list.h

   1 /* EINA - EFL data type library
   2  * Copyright (C) 2002-2008 Carsten Haitzler, Vincent Torri, Jorge Luis Zapata Muga
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Lesser General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2.1 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Lesser General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General Public
  15  * License along with this library;
  16  * if not, see <http://www.gnu.org/licenses/>.
  17  */
  18
  19 #ifndef EINA_LIST_H_
  20 #define EINA_LIST_H_
  21
  22 #include <stdlib.h>
  23
  24 #include "eina_config.h"
  25
  26 #include "eina_types.h"
  27 #include "eina_iterator.h"
  28 #include "eina_accessor.h"
  29 #include "eina_magic.h"
  30
  31 /**
  32  * @page eina_list_01_example_page Adding elements to Eina_List
  33  * @dontinclude eina_list_01.c
  34  *
  35  * Creating an @ref Eina_List and adding elements to it is very easy and can be
  36  * understood from an example:
  37  * First thing is always to include Eina.h, for this example we also
  38  * include stdio.h so we can use printf.
  39  * @skip #include
  40  * @until Eina.h
  41  *
  42  * Just some boilerplate code, declaring some variable and initializing eina.
  43  * @until eina_init
  44  * Here we add a sequence of elements to our list. By using append we add
  45  * elements to the end of the list, so the list will look like this:@n
  46  * @htmlonly
  47  * <img src="eina_list_example_01_a.png" style="max-width: 100%;" />
  48  * <a href="eina_list_example_01_a.png">Full-size</a>
  49  * @endhtmlonly
  50  * @image rtf eina_list_example_01_a.png
  51  * @image latex eina_list_example_01_a.eps width=\textwidth
  52  * @until roslin
  53  * There are a couple of interesting things happening here, first is that we are
  54  * passing a NULL pointer to the first @ref eina_list_append() call, when this
  55  * is done a list is created. The other @b very important detail to notice is
  56  * that the return value is attributed to the @a list variable, this needs to
  57  * be done every time we use a a function that alters the contents of the list.
  58  *
  59  * Now that we have a list with some elements in it we can look at it's contents.
  60  * @until printf
  61  *
  62  * There are many ways of accessing elements in the list, including by it's
  63  * index:
  64  * @until nth
  65  * @note It should be noted that the index starts at 0.
  66  *
  67  * @ref eina_list_append() is not the only way to add elements to a a list. A
  68  * common requirement is to add an element in a specific position this can be
  69  * accomplished using @ref eina_list_append_relative() and
  70  * @ref eina_list_append_relative_list():
  71  * @until zarek
  72  * First @a "cain" is added after the second element(remember that indexes are
  73  * 0 based) and then we add @a "zarek" after @a "cain".
  74  *
  75  * @ref Eina_List also has prepend analogs to append functions we have used so
  76  * far:
  77  * @until lampkin
  78  * With this additions our list now looks like this:@n
  79  * @htmlonly
  80  * <img src="eina_list_example_01_b.png" style="max-width: 100%;" />
  81  * <a href="eina_list_example_01_b.png">Full-size</a>
  82  * @endhtmlonly
  83  * @image rtf eina_list_example_01_b.png
  84  * @image latex eina_list_example_01_b.eps width=\textwidth
  85  *
  86  * Once done using the list it needs to be freed, and since we are done with
  87  * eina that also need to be shutdown:
  88  * @until }
  89  *
  90  * The full source code can be found on the examples folder
  91  * on the @ref eina_list_01_c "eina_list_01.c" file.
  92  */
  93
  94 /**
  95  * @page eina_list_01_c Adding elements to Eina_List example
  96  *
  97  * @include eina_list_01.c
  98  * @example eina_list_01.c
  99  */
 100
 101 /**
 102  * @page eina_list_02_example_page Sorting Eina_List elements
 103  * @dontinclude eina_list_02.c
 104  *
 105  * If you don't know how to create lists see
 106  * @ref eina_list_01_example_page.
 107  *
 108  * @skip #include
 109  * @until boomer
 110  * This is the code we have already seen to create a list. Now if we need to
 111  * search the list we can do it like this:
 112  * @until return
 113  *
 114  * However if searching the list multiple times it probably is better to sort
 115  * the list since the sorted_search functions are much faster:
 116  * @until return
 117  *
 118  * Once the list is sorted it's not a good idea to use append/prepend functions
 119  * since that would add the element in the wrong place, instead elements should
 120  * be added with @ref eina_list_sorted_insert():
 121  * @until sorted_insert
 122  *
 123  * A noteworthy use case is adding an element to a list only if it doesn't exist
 124  * already, this can accomplished by searching for the element that is closest
 125  * to what is being added, and if that doesn't match add:
 126  * @until append
 127  * @note @ref eina_list_search_sorted_near_list() will tell you not only the
 128  * nearest node to what was searched for but how it compares to your term, this
 129  * way it is easy to know if you have to add before or after that node.
 130  *
 131  * It is sometimes useful to get a portion of the list as another list, here we
 132  * take every element that comes after "boomer" and split it into "other_list":
 133  * @until split_list
 134  *
 135  * It is also possible to add entire lists of elements using
 136  * @ref eina_list_sorted_merge():
 137  * @until sorted_merge
 138  *
 139  * And as always release memory and shutdown eina before ending:
 140  * @until }
 141  *
 142  * The full source code can be found on the examples folder
 143  * on the @ref eina_list_02_c "eina_list_02.c" file.
 144  */
 145
 146 /**
 147  * @page eina_list_02_c Sorting Eina_List elements example
 148  *
 149  * @include eina_list_02.c
 150  * @example eina_list_02.c
 151  */
 152
 153 /**
 154  * @page eina_list_03_example_page Reordering Eina_List elements
 155  * @dontinclude eina_list_03.c
 156  *
 157  * If you don't know how to create lists see
 158  * @ref eina_list_01_example_page.
 159  *
 160  * We start out with code that should be familiar by now:
 161  * @skip #include
 162  * @until gemenon
 163  *
 164  * You can move elements around in a list using @ref eina_list_move() or using
 165  * @ref eina_list_promote_list() and @ref eina_list_demote_list() which move a
 166  * list node to the head and end of the list respectevely:
 167  * @until demote
 168  *
 169  * Removing elements from a list can be done with ease:
 170  * @until sagitarius
 171  *
 172  * To replace an element in the list it is not necessary to remove it and then
 173  * add with the new value, it is possible to just change the value of a node:
 174  * @until aquarius
 175  *
 176  * We will now take a peek to see if the list still has the right number of
 177  * elements:
 178  * @until printf
 179  *
 180  * Now that the list is in alphabetical order let's create a copy of it in
 181  * reverse order and print every element to see if worked as expected:
 182  * @until iterator_free
 183  * @note Always remember to free your iterators when done using them.
 184  *
 185  * And as always release memory and shutdown eina before ending:
 186  * @until }
 187  *
 188  * The full source code can be found on the examples folder
 189  * on the @ref eina_list_03_c "eina_list_03.c" file.
 190  */
 191
 192 /**
 193  * @page eina_list_03_c Reordering Eina_List elements example
 194  *
 195  * @include eina_list_03.c
 196  * @example eina_list_03.c
 197  */
 198
 199 /**
 200  * @page eina_list_04_example_page Eina_List and memory allocation
 201  * @dontinclude eina_list_04.c
 202  *
 203  * If you don't know how to create lists see
 204  * @ref eina_list_01_example_page. In this example we also use
 205  * @ref Eina_Stringshare_Group, however it should be possible to understand the code
 206  * regardless of previous knowledge about it.
 207  *
 208  * Here we have the usual list creation code with a twist, now we are using as
 209  * data for the list memory that has to be freed later on.
 210  * @skip #include
 211  * @until Sharon
 212  *
 213  * This time we are going to iterate over our list in a different way:
 214  * @until printf
 215  *
 216  * And now we are going to iterate over the list backwards:
 217  * @until printf
 218  *
 219  * And now we need to free up the memory allocated during creation of the list:
 220  * @until stringshare_del
 221  * @note We don't need to use eina_list_free() since @ref EINA_LIST_FREE takes
 222  * care of that.
 223  *
 224  * And shut everything down:
 225  * @until }
 226  *
 227  * The full source code can be found on the examples folder
 228  * on the @ref eina_list_04_c "eina_list_04.c" file.
 229  */
 230
 231 /**
 232  * @page eina_list_04_c Eina_List and memory allocation example
 233  *
 234  * @include eina_list_04.c
 235  * @example eina_list_04.c
 236  */
 237
 238 /**
 239  * @addtogroup Eina_List_Group List
 240  *
 241  * @brief These functions provide double linked list management.
 242  *
 243  * Eina_List is a doubly linked list. It can store data of any type in the
 244  * form of void pointers. It has convenience functions to do all the common
 245  * operations which means it should rarely if ever be necessary to directly
 246  * access the struct's fields. Nevertheless it can be useful to understand the
 247  * inner workings of the data structure being used.
 248  *
 249  * @ref Eina_List nodes keep references to the previous node, the next node, its
 250  * data and to an accounting structure.
 251  *
 252  * @htmlonly
 253  * <img src="eina_list.png" style="max-width: 100%;" />
 254  * <a href="eina_list.png">Full-size</a>
 255  * @endhtmlonly
 256  * @image rtf eina_list.png
 257  * @image latex eina_list.eps width=5cm
 258  *
 259  * @ref Eina_List_Accounting is used to improve the performance of some
 260  * functions. It is private and <b>should not</b> be modified. It contains a
 261  * reference to the end of the list and the number of elements in the list.
 262  *
 263  * @note Every function that modifies the contents of the list returns a pointer
 264  * to the head of the list and it is essential that this be pointer be used in
 265  * any future references to the list.
 266  *
 267  * Most functions have two versions that have the same effect but operate on
 268  * different arguments, the @a plain functions operate over data(eg.:
 269  * @ref eina_list_append_relative, @ref eina_list_remove,
 270  * @ref eina_list_data_find), the @a list versions of these functions operate
 271  * on @ref Eina_List nodes.
 272  *
 273  * @warning You must @b always use the pointer to the first element of the list
 274  * as the list!
 275  * @warning You must @b never use a pointer to an element in the middle of the
 276  * list as the list!
 277  *
 278  * Here are some examples of @ref Eina_List usage:
 279  * @li @ref eina_list_01_example_page
 280  * @li @ref eina_list_02_example_page
 281  * @li @ref eina_list_03_example_page
 282  * @li @ref eina_list_04_example_page
 283  */
 284
 285 /**
 286  * @addtogroup Eina_Data_Types_Group Data Types
 287  *
 288  * @{
 289  */
 290
 291 /**
 292  * @addtogroup Eina_Containers_Group Containers
 293  *
 294  * @{
 295  */
 296
 297 /**
 298  * @defgroup Eina_List_Group List
 299  *
 300  * @{
 301  */
 302
 303 /**
 304  * @typedef Eina_List
 305  * Type for a generic double linked list.
 306  */
 307 typedef struct _Eina_List            Eina_List;
 308
 309 /**
 310  * @typedef Eina_List_Accounting
 311  * Cache used to store the last element of a list and the number of
 312  * elements, for fast access.
 313  */
 314 typedef struct _Eina_List_Accounting Eina_List_Accounting;
 315
 316 /**
 317  * @struct _Eina_List
 318  * Type for a generic double linked list.
 319  */
 320 struct _Eina_List
 321 {
 322    void                 *data; /**< Pointer to list element payload */
 323    Eina_List            *next; /**< Next member in the list */
 324    Eina_List            *prev; /**< Previous member in the list */
 325    Eina_List_Accounting *accounting; /**< Private list accounting info - don't touch */
 326
 327    EINA_MAGIC
 328 };
 329
 330 /**
 331  * @struct _Eina_List_Accounting
 332  * Cache used to store the last element of a list and the number of
 333  * elements, for fast access. It is for private used and must not be
 334  * touched.
 335  */
 336 struct _Eina_List_Accounting
 337 {
 338    Eina_List   *last; /**< Pointer to the last element of the list - don't touch */
 339    unsigned int count; /**< Number of elements of the list - don't touch */
 340    EINA_MAGIC
 341 };
 342
 343
 344 /**
 345  * @brief Append the given data to the given linked list.
 346  *
 347  * @param list The given list.
 348  * @param data The data to append.
 349  * @return A list pointer.
 350  *
 351  * This function appends @p data to @p list. If @p list is @c NULL, a
 352  * new list is returned. On success, a new list pointer that should be
 353  * used in place of the one given to this function is
 354  * returned. Otherwise, the old pointer is returned.
 355  *
 356  * The following example code demonstrates how to ensure that the
 357  * given data has been successfully appended.
 358  *
 359  * @code
 360  * Eina_List *list = NULL;
 361  * extern void *my_data;
 362  *
 363  * list = eina_list_append(list, my_data);
 364  * if (eina_error_get())
 365  *   {
 366  *     fprintf(stderr, "ERROR: Memory is low. List allocation failed.\n");
 367  *     exit(-1);
 368  *   }
 369  * @endcode
 370  *
 371  * @warning @p list must be a pointer to the first element of the list(or NULL).
 372  */
 373 EAPI Eina_List            *eina_list_append(Eina_List *list, const void *data) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
 374
 375
 376 /**
 377  * @brief Prepends the given data to the given linked list.
 378  *
 379  * @param list The given list.
 380  * @param data The data to prepend.
 381  * @return A list pointer.
 382  *
 383  * This function prepends @p data to @p list. If @p list is @c NULL, a
 384  * new list is returned. On success, a new list pointer that should be
 385  * used in place of the one given to this function is
 386  * returned. Otherwise, the old pointer is returned.
 387  *
 388  * The following example code demonstrates how to ensure that the
 389  * given data has been successfully prepended.
 390  *
 391  * Example:
 392  * @code
 393  * Eina_List *list = NULL;
 394  * extern void *my_data;
 395  *
 396  * list = eina_list_prepend(list, my_data);
 397  * if (eina_error_get())
 398  *   {
 399  *     fprintf(stderr, "ERROR: Memory is low. List allocation failed.\n");
 400  *     exit(-1);
 401  *   }
 402  * @endcode
 403  *
 404  * @warning @p list must be a pointer to the first element of the list.
 405  */
 406 EAPI Eina_List            *eina_list_prepend(Eina_List *list, const void *data) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
 407
 408
 409 /**
 410  * @brief Insert the given data into the given linked list after the specified data.
 411  *
 412  * @param list The given linked list.
 413  * @param data The data to insert.
 414  * @param relative The data to insert after.
 415  * @return A list pointer.
 416  *
 417  * This function inserts @p data to @p list after @p relative. If
 418  * @p relative is not in the list, @p data is appended to the end of
 419  * the list.  If @p list is @c NULL, a  new list is returned. If there
 420  * are multiple instances of @p relative in the list, @p data is
 421  * inserted after the first instance.On success, a new list pointer
 422  * that should be used in place of the one given to this function is
 423  * returned. Otherwise, the old pointer is returned.
 424  *
 425  * The following example code demonstrates how to ensure that the
 426  * given data has been successfully inserted.
 427  *
 428  * @code
 429  * Eina_List *list = NULL;
 430  * extern void *my_data;
 431  * extern void *relative_member;
 432  *
 433  * list = eina_list_append(list, relative_member);
 434  * if (eina_error_get())
 435  *   {
 436  *     fprintf(stderr, "ERROR: Memory is low. List allocation failed.\n");
 437  *     exit(-1);
 438  *   }
 439  * list = eina_list_append_relative(list, my_data, relative_member);
 440  * if (eina_error_get())
 441  *   {
 442  *     fprintf(stderr, "ERROR: Memory is low. List allocation failed.\n");
 443  *     exit(-1);
 444  *   }
 445  * @endcode
 446  *
 447  * @warning @p list must be a pointer to the first element of the list.
 448  */
 449 EAPI Eina_List            *eina_list_append_relative(Eina_List *list, const void *data, const void *relative) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
 450
 451
 452 /**
 453  * @brief Append a list node to a linked list after the specified member
 454  *
 455  * @param list The given linked list.
 456  * @param data The data to insert.
 457  * @param relative The list node to insert after.
 458  * @return A list pointer.
 459  *
 460  * This function inserts @p data to @p list after the list node
 461  * @p relative. If @p list or @p relative are @c NULL, @p data is just
 462  * appended to @p list using eina_list_append(). If @p list is
 463  * @c NULL, a  new list is returned. If there are multiple instances
 464  * of @p relative in the list, @p data is inserted after the first
 465  * instance. On success, a new list pointer that should be used in
 466  * place of the one given to this function is returned. Otherwise, the
 467  * old pointer is returned.
 468  *
 469  * @warning @p list must be a pointer to the first element of the list.
 470  */
 471 EAPI Eina_List            *eina_list_append_relative_list(Eina_List *list, const void *data, Eina_List *relative) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
 472
 473
 474 /**
 475  * @brief Prepend a data pointer to a linked list before the specified member
 476  *
 477  * @param list The given linked list.
 478  * @param data The data to insert.
 479  * @param relative The data to insert before.
 480  * @return A list pointer.
 481  *
 482  * This function inserts @p data to @p list before @p relative. If
 483  * @p relative is not in the list, @p data is prepended to the list
 484  * with eina_list_prepend(). If @p list is @c NULL, a  new list is
 485  * returned. If there are multiple instances of @p relative in the
 486  * list, @p data is inserted before the first instance. On success, a
 487  * new list pointer that should be used in place of the one given to
 488  * this function is returned. Otherwise, the old pointer is returned.
 489  *
 490  * The following code example demonstrates how to ensure that the
 491  * given data has been successfully inserted.
 492  *
 493  * @code
 494  * Eina_List *list = NULL;
 495  * extern void *my_data;
 496  * extern void *relative_member;
 497  *
 498  * list = eina_list_append(list, relative_member);
 499  * if (eina_error_get_error())
 500  *   {
 501  *     fprintf(stderr, "ERROR: Memory is low. List allocation failed.\n");
 502  *     exit(-1);
 503  *   }
 504  * list = eina_list_prepend_relative(list, my_data, relative_member);
 505  * if (eina_error_get())
 506  *   {
 507  *     fprintf(stderr, "ERROR: Memory is low. List allocation failed.\n");
 508  *     exit(-1);
 509  *   }
 510  * @endcode
 511  *
 512  * @warning @p list must be a pointer to the first element of the list.
 513  */
 514 EAPI Eina_List            *eina_list_prepend_relative(Eina_List *list, const void *data, const void *relative) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
 515
 516
 517 /**
 518  * @brief Prepend a list node to a linked list before the specified member
 519  *
 520  * @param list The given linked list.
 521  * @param data The data to insert.
 522  * @param relative The list node to insert before.
 523  * @return A list pointer.
 524  *
 525  * This function inserts @p data to @p list before the list node
 526  * @p relative. If @p list or @p relative are @c NULL, @p data is just
 527  * prepended to @p list using eina_list_prepend(). If @p list is
 528  * @c NULL, a  new list is returned. If there are multiple instances
 529  * of @p relative in the list, @p data is inserted before the first
 530  * instance. On success, a new list pointer that should be used in
 531  * place of the one given to this function is returned. Otherwise, the
 532  * old pointer is returned.
 533  *
 534  * @warning @p list must be a pointer to the first element of the list.
 535  */
 536 EAPI Eina_List            *eina_list_prepend_relative_list(Eina_List *list, const void *data, Eina_List *relative) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
 537
 538
 539 /**
 540  * @brief Insert a new node into a sorted list.
 541  *
 542  * @param list The given linked list, @b must be sorted.
 543  * @param func The function called for the sort.
 544  * @param data The data to insert sorted.
 545  * @return A list pointer.
 546  *
 547  * This function inserts values into a linked list assuming it was
 548  * sorted and the result will be sorted. If @p list is @c NULLL, a new
 549  * list is returned. On success, a new list pointer that should be
 550  * used in place of the one given to this function is
 551  * returned. Otherwise, the old pointer is returned. See eina_error_get().
 552  *
 553  * @note O(log2(n)) comparisons (calls to @p func) average/worst case
 554  * performance as it uses eina_list_search_sorted_near_list() and thus
 555  * is bounded to that. As said in eina_list_search_sorted_near_list(),
 556  * lists do not have O(1) access time, so walking to the correct node
 557  * can be costly, consider worst case to be almost O(n) pointer
 558  * dereference (list walk).
 559  *
 560  * @warning @p list must be a pointer to the first element of the list.
 561  */
 562 EAPI Eina_List            *eina_list_sorted_insert(Eina_List *list, Eina_Compare_Cb func, const void *data) EINA_ARG_NONNULL(2, 3) EINA_WARN_UNUSED_RESULT;
 563
 564
 565 /**
 566  * @brief Remove the first instance of the specified data from the given list.
 567  *
 568  * @param list The given list.
 569  * @param data The specified data.
 570  * @return A list pointer.
 571  *
 572  * This function removes the first instance of @p data from
 573  * @p list. If the specified data is not in the given list (this
 574  * includes the case where @p data is @c NULL), nothing is done and the
 575  * specified @p list returned. If @p list is @c NULL, @c NULL is returned,
 576  * otherwise a new list pointer that should be used in place of the one
 577  * passed to this function.
 578  *
 579  * @warning @p list must be a pointer to the first element of the list.
 580  */
 581 EAPI Eina_List            *eina_list_remove(Eina_List *list, const void *data) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
 582
 583
 584 /**
 585  * @brief Remove the specified list node.
 586  *
 587  * @param list The given linked list.
 588  * @param remove_list The list node which is to be removed.
 589  * @return A list pointer.
 590  *
 591  * This function removes the list node @p remove_list from @p list and
 592  * frees the list node structure @p remove_list. If @p list is
 593  * @c NULL, this function returns @c NULL. If @p remove_list is
 594  * @c NULL, it returns @p list, otherwise, a new list pointer that
 595  * should be used in place of the one passed to this function.
 596  *
 597  * The following code gives an example (notice we use EINA_LIST_FOREACH
 598  * instead of EINA_LIST_FOREACH_SAFE because we stop the loop after
 599  * removing the current node).
 600  *
 601  * @code
 602  * extern Eina_List *list;
 603  * Eina_List *l;
 604  * extern void *my_data;
 605  * void *data
 606  *
 607  * EINA_LIST_FOREACH(list, l, data)
 608  *   {
 609  *     if (data == my_data)
 610  *       {
 611  *         list = eina_list_remove_list(list, l);
 612  *         break;
 613  *       }
 614  *   }
 615  * @endcode
 616  *
 617  * @warning @p list must be a pointer to the first element of the list.
 618  */
 619 EAPI Eina_List            *eina_list_remove_list(Eina_List *list, Eina_List *remove_list) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
 620
 621
 622 /**
 623  * @brief Move the specified data to the head of the list.
 624  *
 625  * @param list The list handle to move the data.
 626  * @param move_list The list node to move.
 627  * @return A new list handle to replace the old one
 628  *
 629  * This function move @p move_list to the front of @p list. If list is
 630  * @c NULL, @c NULL is returned. If @p move_list is @c NULL,
 631  * @p list is returned. Otherwise, a new list pointer that should be
 632  * used in place of the one passed to this function.
 633  *
 634  * Example:
 635  * @code
 636  * extern Eina_List *list;
 637  * Eina_List *l;
 638  * extern void *my_data;
 639  * void *data;
 640  *
 641  * EINA_LIST_FOREACH(list, l, data)
 642  *   {
 643  *     if (data == my_data)
 644  *       {
 645  *         list = eina_list_promote_list(list, l);
 646  *         break;
 647  *       }
 648  *   }
 649  * @endcode
 650  *
 651  * @warning @p list must be a pointer to the first element of the list.
 652  */
 653 EAPI Eina_List            *eina_list_promote_list(Eina_List *list, Eina_List *move_list) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
 654
 655
 656 /**
 657  * @brief Move the specified data to the tail of the list.
 658  *
 659  * @param list The list handle to move the data.
 660  * @param move_list The list node to move.
 661  * @return A new list handle to replace the old one
 662  *
 663  * This function move @p move_list to the back of @p list. If list is
 664  * @c NULL, @c NULL is returned. If @p move_list is @c NULL,
 665  * @p list is returned. Otherwise, a new list pointer that should be
 666  * used in place of the one passed to this function.
 667  *
 668  * Example:
 669  * @code
 670  * extern Eina_List *list;
 671  * Eina_List *l;
 672  * extern void *my_data;
 673  * void *data;
 674  *
 675  * EINA_LIST_FOREACH(list, l, data)
 676  *   {
 677  *     if (data == my_data)
 678  *       {
 679  *         list = eina_list_demote_list(list, l);
 680  *         break;
 681  *       }
 682  *   }
 683  * @endcode
 684  *
 685  * @warning @p list must be a pointer to the first element of the list.
 686  */
 687 EAPI Eina_List            *eina_list_demote_list(Eina_List *list, Eina_List *move_list);
 688
 689
 690 /**
 691  * @brief Find a member of a list and return the member.
 692  *
 693  * @param list The list to search for a data.
 694  * @param data The data pointer to find in the list.
 695  * @return The found member data pointer if found, @c NULL otherwise.
 696  *
 697  * This function searches in @p list from beginning to end for the
 698  * first member whose data pointer is @p data. If it is found, @p data
 699  * will be returned, otherwise @c NULL will be returned.
 700  *
 701  * Example:
 702  * @code
 703  * extern Eina_List *list;
 704  * extern void *my_data;
 705  *
 706  * if (eina_list_data_find(list, my_data) == my_data)
 707  *   {
 708  *      printf("Found member %p\n", my_data);
 709  *   }
 710  * @endcode
 711  *
 712  * @warning @p list must be a pointer to the first element of the list.
 713  */
 714 EAPI void                 *eina_list_data_find(const Eina_List *list, const void *data) EINA_PURE EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
 715
 716 /**
 717  * @brief Find a member of a list and return the list node containing that member.
 718  *
 719  * @param list The list to search for data.
 720  * @param data The data pointer to find in the list.
 721  * @return The found members list node on success, @c NULL otherwise.
 722  *
 723  * This function searches in @p list from beginning to end for the
 724  * first member whose data pointer is @p data. If it is found, the
 725  * list node containing the specified member is returned, otherwise
 726  * @c NULL is returned.
 727  *
 728  * @warning @p list must be a pointer to the first element of the list.
 729  */
 730 EAPI Eina_List            *eina_list_data_find_list(const Eina_List *list, const void *data) EINA_PURE EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
 731
 732
 733 /**
 734  * @brief Move a data pointer from one list to another
 735  *
 736  * @param to The list to move the data to
 737  * @param from The list to move from
 738  * @param data The data to move
 739  * @return #EINA_TRUE on success, else #EINA_FALSE
 740  *
 741  * This function is a shortcut for doing the following:
 742  * to = eina_list_append(to, data);
 743  * from = eina_list_remove(from, data);
 744  *
 745  * @warning @p list must be a pointer to the first element of the list.
 746  */
 747 EAPI Eina_Bool             eina_list_move(Eina_List **to, Eina_List **from, void *data);
 748
 749 /**
 750  * @brief Move a list node from one list to another
 751  *
 752  * @param to The list to move the data to
 753  * @param from The list to move from
 754  * @param data The list node containing the data to move
 755  * @return #EINA_TRUE on success, else #EINA_FALSE
 756  *
 757  * This function is a shortcut for doing the following:
 758  * to = eina_list_append(to, data->data);
 759  * from = eina_list_remove_list(from, data);
 760  *
 761  * @warning @p list must be a pointer to the first element of the list.
 762  */
 763 EAPI Eina_Bool             eina_list_move_list(Eina_List **to, Eina_List **from, Eina_List *data);
 764
 765
 766 /**
 767  * @brief Free an entire list and all the nodes, ignoring the data contained.
 768
 769  * @param list The list to free
 770  * @return A @c NULL pointer
 771  *
 772  * This function frees all the nodes of @p list. It does not free the
 773  * data of the nodes. To free them, use #EINA_LIST_FREE.
 774  */
 775 EAPI Eina_List            *eina_list_free(Eina_List *list);
 776
 777
 778 /**
 779  * @brief Get the nth member's data pointer in a list.
 780  *
 781  * @param list The list to get the specified member number from.
 782  * @param n The number of the element (0 being the first).
 783  * @return The data pointer stored in the specified element.
 784  *
 785  * This function returns the data pointer of element number @p n, in
 786  * the @p list. The first element in the array is element number 0. If
 787  * the element number @p n does not exist, @c NULL is
 788  * returned. Otherwise, the data of the found element is returned.
 789  *
 790  * @note Worst case is O(n).
 791  *
 792  * @warning @p list must be a pointer to the first element of the list.
 793  */
 794 EAPI void                 *eina_list_nth(const Eina_List *list, unsigned int n) EINA_PURE EINA_WARN_UNUSED_RESULT;
 795
 796
 797 /**
 798  * @brief Get the nth member's list node in a list.
 799  *
 800  * @param list The list to get the specfied member number from.
 801  * @param n The number of the element (0 being the first).
 802  * @return The list node stored in the numbered element.
 803  *
 804  * This function returns the list node of element number @p n, in
 805  * @p list. The first element in the array is element number 0. If the
 806  * element number @p n does not exist or @p list is @c NULL or @p n is
 807  * greater than the count of elements in @p list minus 1, @c NULL is
 808  * returned. Otherwise the list node stored in the numbered element is
 809  * returned.
 810  *
 811  * @note Worst case is O(n).
 812  *
 813  * @warning @p list must be a pointer to the first element of the list.
 814  */
 815 EAPI Eina_List            *eina_list_nth_list(const Eina_List *list, unsigned int n) EINA_PURE EINA_WARN_UNUSED_RESULT;
 816
 817
 818 /**
 819  * @brief Reverse all the elements in the list.
 820  *
 821  * @param list The list to reverse.
 822  * @return The list head after it has been reversed.
 823  *
 824  * This function reverses the order of all elements in @p list, so the
 825  * last member is now first, and so on. If @p list is @c NULL, this
 826  * functon returns @c NULL.
 827  *
 828  * @note @b in-place: this will change the given list, so you should
 829  * now point to the new list head that is returned by this function.
 830  *
 831  * @warning @p list must be a pointer to the first element of the list.
 832  *
 833  * @see eina_list_reverse_clone()
 834  * @see eina_list_iterator_reversed_new()
 835  */
 836 EAPI Eina_List            *eina_list_reverse(Eina_List *list) EINA_WARN_UNUSED_RESULT;
 837
 838
 839 /**
 840  * @brief Clone (copy) all the elements in the list in reverse order.
 841  *
 842  * @param list The list to reverse.
 843  * @return The new list that has been reversed.
 844  *
 845  * This function reverses the order of all elements in @p list, so the
 846  * last member is now first, and so on. If @p list is @c NULL, this
 847  * functon returns @c NULL. This returns a copy of the given list.
 848  *
 849  * @note @b copy: this will copy the list and you should then
 850  * eina_list_free() when it is not required anymore.
 851  *
 852  * @warning @p list must be a pointer to the first element of the list.
 853  *
 854  * @see eina_list_reverse()
 855  * @see eina_list_clone()
 856  */
 857 EAPI Eina_List            *eina_list_reverse_clone(const Eina_List *list) EINA_WARN_UNUSED_RESULT;
 858
 859
 860 /**
 861  * @brief Clone (copy) all the elements in the list in exactly same order.
 862  *
 863  * @param list The list to clone.
 864  * @return The new list that has been cloned.
 865  *
 866  * This function clone in order of all elements in @p list. If @p list
 867  * is @c NULL, this functon returns @c NULL. This returns a copy of
 868  * the given list.
 869  *
 870  * @note @b copy: this will copy the list and you should then
 871  * eina_list_free() when it is not required anymore.
 872  *
 873  * @warning @p list must be a pointer to the first element of the list.
 874  *
 875  * @see eina_list_reverse_clone()
 876  */
 877 EAPI Eina_List            *eina_list_clone(const Eina_List *list) EINA_WARN_UNUSED_RESULT;
 878
 879
 880 /**
 881  * @brief Sort a list according to the ordering func will return.
 882  *
 883  * @param list The list handle to sort.
 884  * @param limit The maximum number of list elements to sort.
 885  * @param func A function pointer that can handle comparing the list data
 886  * nodes.
 887  * @return the new head of list.
 888  *
 889  * This function sorts @p list. @p size if the number of the first
 890  * element to sort. If @p limit is 0 or greater than the number of
 891  * elements in @p list, all the elements are sorted. @p func is used to
 892  * compare two elements of @p list. If @p list or @p func are @c NULL,
 893  * this function returns @c NULL.
 894  *
 895  * @note @b in-place: this will change the given list, so you should
 896  * now point to the new list head that is returned by this function.
 897  *
 898  * @note Worst case is O(n * log2(n)) comparisons (calls to func()).
 899  * That means that for 1,000,000 list sort will do 20,000,000 comparisons.
 900  *
 901  * Example:
 902  * @code
 903  * int
 904  * sort_cb(const void *d1, const void *d2)
 905  * {
 906  *    const char *txt = d1;
 907  *    const char *txt2 = d2;
 908  *
 909  *    if(!txt) return(1);
 910  *    if(!txt2) return(-1);
 911  *
 912  *    return(strcmp(txt, txt2));
 913  * }
 914  * extern Eina_List *list;
 915  *
 916  * list = eina_list_sort(list, eina_list_count(list), sort_cb);
 917  * @endcode
 918  *
 919  * @warning @p list must be a pointer to the first element of the list.
 920  */
 921 EAPI Eina_List            *eina_list_sort(Eina_List *list, unsigned int limit, Eina_Compare_Cb func) EINA_ARG_NONNULL(3) EINA_WARN_UNUSED_RESULT;
 922
 923
 924 /**
 925  * @brief Merge two list.
 926  *
 927  * @param left Head list to merge.
 928  * @param right Tail list to merge.
 929  * @return A new merged list.
 930  *
 931  * This function puts right at the end of left and returns the head.
 932  *
 933  * Both left and right do not exist anymore after the merge.
 934  *
 935  * @note merge cost is O(n), being @b n the size of the smallest
 936  * list. This is due the need to fix accounting of that segment,
 937  * making count and last access O(1).
 938  *
 939  * @warning @p list must be a pointer to the first element of the list.
 940  */
 941 EAPI Eina_List            *eina_list_merge(Eina_List *left, Eina_List *right) EINA_WARN_UNUSED_RESULT;
 942
 943
 944 /**
 945  * @brief Merge two sorted list according to the ordering func will return.
 946  *
 947  * @param left First list to merge.
 948  * @param right Second list to merge.
 949  * @param func A function pointer that can handle comparing the list data
 950  * nodes.
 951  * @return A new sorted list.
 952  *
 953  * This function compares the head of @p left and @p right, and choose the
 954  * smallest one to be head of the returned list. It will continue this process
 955  * for all entry of both list.
 956  *
 957  * Both left and right do not exist anymore after the merge.
 958  * If @p func is @c NULL, it will return @c NULL.
 959  *
 960  * Example:
 961  * @code
 962  * int
 963  * sort_cb(void *d1, void *d2)
 964  * {
 965  *   const char *txt = NULL;
 966  *    const char *txt2 = NULL;
 967  *
 968  *    if(!d1) return(1);
 969  *    if(!d2) return(-1);
 970  *
 971  *    return(strcmp((const char*)d1, (const char*)d2));
 972  * }
 973  * extern Eina_List *sorted1;
 974  * extern Eina_List *sorted2;
 975  *
 976  * list = eina_list_sorted_merge(sorted1, sorted2, sort_cb);
 977  * @endcode
 978  *
 979  * @warning @p list must be a pointer to the first element of the list.
 980  */
 981 EAPI Eina_List            *eina_list_sorted_merge(Eina_List *left, Eina_List *right, Eina_Compare_Cb func) EINA_ARG_NONNULL(3) EINA_WARN_UNUSED_RESULT;
 982
 983
 984 /**
 985  * @brief Split a list into 2 lists.
 986  *
 987  * @param list List to split.
 988  * @param relative The list will be split after @p relative.
 989  * @param right The head of the new right list.
 990  * @return The new left list
 991  *
 992  * This function splits @p list into two lists ( left and right ) after the node @p relative. @p Relative
 993  * will become the last node of the left list. If @p list or @p right are @c NULL list is returns.
 994  * If @p relative is NULL right is set to @p list and @c NULL is returns.
 995  * If @p relative is the last node of @p list list is returns and @p right is set to @c NULL.
 996  *
 997  * list does not exist anymore after the split.
 998  *
 999  * @warning @p list must be a pointer to the first element of the list.
1000  */
1001 EAPI Eina_List            *eina_list_split_list(Eina_List *list, Eina_List *relative, Eina_List **right) EINA_WARN_UNUSED_RESULT;
1002
1003
1004 /**
1005  * @brief Returns node nearest to data is in the sorted list.
1006  *
1007  * @param list The list to search for data, @b must be sorted.
1008  * @param func A function pointer that can handle comparing the list data nodes.
1009  * @param data reference value to search.
1010  * @param result_cmp if provided returns the result of
1011  * func(node->data, data) node being the last (returned) node. If node
1012  * was found (exact match), then it is 0. If returned node is smaller
1013  * than requested data, it is less than 0 and if it's bigger it's
1014  * greater than 0. It is the last value returned by func().
1015  * @return the nearest node, @c NULL if not found.
1016  *
1017  * This function searches for a node containing @p data as it's data in @p list,
1018  * if such a node exists it will be returned and @p result_cmp will be @p 0. If
1019  * the data of no node in @p list is equal to @p data, the node with the nearest
1020  * value to that will be returned and @p result_cmp will be the return value of
1021  * @p func with @p data and the returned node's data as arguments.
1022  *
1023  * This function is useful for inserting an element in the list only in case it
1024  * isn't already present in the list, the naive way of doing this would be:
1025  * @code
1026  * void *ptr = eina_list_data_find(list, "my data");
1027  * if (!ptr)
1028  *   eina_list_sorted_insert(list, "my data");
1029  * @endcode
1030  *
1031  * However this has the downside of walking through the list twice, once to
1032  * check if the data is already present and another to insert the element in the
1033  * corret position. This can be done more eficiently:
1034  * @code
1035  * int cmp_result;
1036  * l = eina_list_search_sorted_near_list(list, cmp_func, "my data",
1037  *                                       &cmp_result);
1038  * if (cmp_result > 0)
1039  *   list = eina_list_prepend_relative_list(list, "my data", l);
1040  * else if (cmp_result < 0)
1041  *   list = eina_list_append_relative_list(list, "my data", l);
1042  * @endcode
1043  *
1044  * If @a cmp_result is 0 the element is already in the list and we need not
1045  * insert it, if @a cmp_result is greater than zero @a "my @a data" needs to
1046  * come after @a l(the nearest node present), if less than zero before.
1047  *
1048  * @note O(log2(n)) average/worst case performance, for 1,000,000
1049  * elements it will do a maximum of 20 comparisons. This is much
1050  * faster than the 1,000,000 comparisons made naively walking the list
1051  * from head to tail, so depending on the number of searches and
1052  * insertions, it may be worth to eina_list_sort() the list and do the
1053  * searches later. As lists do not have O(1) access time, walking to
1054  * the correct node can be costly, consider worst case to be almost
1055  * O(n) pointer dereference (list walk).
1056  *
1057  * @warning @p list must be a pointer to the first element of the list.
1058  *
1059  * @see eina_list_search_sorted_list()
1060  * @see eina_list_sort()
1061  * @see eina_list_sorted_merge()
1062  */
1063 EAPI Eina_List            *eina_list_search_sorted_near_list(const Eina_List *list, Eina_Compare_Cb func, const void *data, int *result_cmp);
1064
1065
1066 /**
1067  * @brief Returns node if data is in the sorted list.
1068  *
1069  * @param list The list to search for data, @b must be sorted.
1070  * @param func A function pointer that can handle comparing the list data nodes.
1071  * @param data reference value to search.
1072  * @return the node if func(node->data, data) == 0, @c NULL if not found.
1073  *
1074  * This can be used to check if some value is inside the list and get
1075  * the container node in this case. It should be used when list is
1076  * known to be sorted as it will do binary search for results.
1077  *
1078  * Example: imagine user gives a string, you check if it's in the list
1079  * before duplicating its contents.
1080  *
1081  * @note O(log2(n)) average/worst case performance, for 1,000,000
1082  * elements it will do a maximum of 20 comparisons. This is much
1083  * faster than the 1,000,000 comparisons made by
1084  * eina_list_search_unsorted_list(), so depending on the number of
1085  * searches and insertions, it may be worth to eina_list_sort() the
1086  * list and do the searches later. As said in
1087  * eina_list_search_sorted_near_list(), lists do not have O(1) access
1088  * time, so walking to the correct node can be costly, consider worst
1089  * case to be almost O(n) pointer dereference (list walk).
1090  *
1091  * @warning @p list must be a pointer to the first element of the list.
1092  *
1093  * @see eina_list_search_sorted()
1094  * @see eina_list_sort()
1095  * @see eina_list_sorted_merge()
1096  * @see eina_list_search_unsorted_list()
1097  * @see eina_list_search_sorted_near_list()
1098  */
1099 EAPI Eina_List            *eina_list_search_sorted_list(const Eina_List *list, Eina_Compare_Cb func, const void *data);
1100
1101
1102 /**
1103  * @brief Returns node data if it is in the sorted list.
1104  *
1105  * @param list The list to search for data, @b must be sorted.
1106  * @param func A function pointer that can handle comparing the list data nodes.
1107  * @param data reference value to search.
1108  * @return the node value (@c node->data) if func(node->data, data) == 0,
1109  * NULL if not found.
1110  *
1111  * This can be used to check if some value is inside the list and get
1112  * the existing instance in this case. It should be used when list is
1113  * known to be sorted as it will do binary search for results.
1114  *
1115  * Example: imagine user gives a string, you check if it's in the list
1116  * before duplicating its contents.
1117  *
1118  * @note O(log2(n)) average/worst case performance, for 1,000,000
1119  * elements it will do a maximum of 20 comparisons. This is much
1120  * faster than the 1,000,000 comparisons made by
1121  * eina_list_search_unsorted(), so depending on the number of
1122  * searches and insertions, it may be worth to eina_list_sort() the
1123  * list and do the searches later. As said in
1124  * eina_list_search_sorted_near_list(), lists do not have O(1) access
1125  * time, so walking to the correct node can be costly, consider worst
1126  * case to be almost O(n) pointer dereference (list walk).
1127  *
1128  * @warning @p list must be a pointer to the first element of the list.
1129  *
1130  * @see eina_list_search_sorted_list()
1131  * @see eina_list_sort()
1132  * @see eina_list_sorted_merge()
1133  * @see eina_list_search_unsorted_list()
1134  */
1135 EAPI void                 *eina_list_search_sorted(const Eina_List *list, Eina_Compare_Cb func, const void *data);
1136
1137
1138 /**
1139  * @brief Returns node if data is in the unsorted list.
1140  *
1141  * @param list The list to search for data, may be unsorted.
1142  * @param func A function pointer that can handle comparing the list data nodes.
1143  * @param data reference value to search.
1144  * @return the node if func(node->data, data) == 0, @c NULL if not found.
1145  *
1146  * This can be used to check if some value is inside the list and get
1147  * the container node in this case.
1148  *
1149  * Example: imagine user gives a string, you check if it's in the list
1150  * before duplicating its contents.
1151  *
1152  * @note this is expensive and may walk the whole list, it's order-N,
1153  * that is for 1,000,000 elements list it may walk and compare
1154  * 1,000,000 nodes.
1155  *
1156  * @warning @p list must be a pointer to the first element of the list.
1157  *
1158  * @see eina_list_search_sorted_list()
1159  * @see eina_list_search_unsorted()
1160  */
1161 EAPI Eina_List            *eina_list_search_unsorted_list(const Eina_List *list, Eina_Compare_Cb func, const void *data);
1162
1163
1164 /**
1165  * @brief Returns node data if it is in the unsorted list.
1166  *
1167  * @param list The list to search for data, may be unsorted.
1168  * @param func A function pointer that can handle comparing the list data nodes.
1169  * @param data reference value to search.
1170  * @return the node value (@c node->data) if func(node->data, data) == 0,
1171  * @c NULL if not found.
1172  *
1173  * This can be used to check if some value is inside the list and get
1174  * the existing instance in this case.
1175  *
1176  * Example: imagine user gives a string, you check if it's in the list
1177  * before duplicating its contents.
1178  *
1179  * @note this is expensive and may walk the whole list, it's order-N,
1180  * that is for 1,000,000 elements list it may walk and compare
1181  * 1,000,000 nodes.
1182  *
1183  * @warning @p list must be a pointer to the first element of the list.
1184  *
1185  * @see eina_list_search_sorted()
1186  * @see eina_list_search_unsorted_list()
1187  */
1188 EAPI void                 *eina_list_search_unsorted(const Eina_List *list, Eina_Compare_Cb func, const void *data);
1189
1190 /**
1191  * @brief Get the last list node in the list.
1192  *
1193  * @param list The list to get the last list node from.
1194  * @return The last list node in the list.
1195  *
1196  * This function returns the last list node in the list @p list. If
1197  * @p list is @c NULL or empty, @c NULL is returned.
1198  *
1199  * This is a order-1 operation (it takes the same short time
1200  * regardless of the length of the list).
1201  *
1202  * @warning @p list must be a pointer to the first element of the list.
1203  */
1204 static inline Eina_List   *eina_list_last(const Eina_List *list) EINA_PURE EINA_WARN_UNUSED_RESULT;
1205
1206 /**
1207  * @brief Get the next list node after the specified list node.
1208  *
1209  * @param list The list node to get the next list node from
1210  * @return The next list node on success, @c NULL otherwise.
1211  *
1212  * This function returns the next list node after the current one in
1213  * @p list. It is equivalent to list->next. If @p list is @c NULL or
1214  * if no next list node exists, it returns @c NULL.
1215  *
1216  * @warning @p list must be a pointer to the first element of the list.
1217  */
1218 static inline Eina_List   *eina_list_next(const Eina_List *list) EINA_PURE EINA_WARN_UNUSED_RESULT;
1219
1220 /**
1221  * @brief Get the previous list node before the specified list node.
1222  *
1223  * @param list The list node to get the previous list node from.
1224  * @return The previous list node o success, @c NULL otherwise.
1225  * if no previous list node exists
1226  *
1227  * This function returns the previous list node before the current one
1228  * in @p list. It is equivalent to list->prev. If @p list is @c NULL or
1229  * if no previous list node exists, it returns @c NULL.
1230  *
1231  * @warning @p list must be a pointer to the first element of the list.
1232  */
1233 static inline Eina_List   *eina_list_prev(const Eina_List *list) EINA_PURE EINA_WARN_UNUSED_RESULT;
1234
1235 /**
1236  * @brief Get the list node data member.
1237  *
1238  * @param list The list node to get the data member of.
1239  * @return The data member from the list node.
1240  *
1241  * This function returns the data member of the specified list node @p
1242  * list. It is equivalent to list->data. If @p list is @c NULL, this
1243  * function returns @c NULL.
1244  *
1245  * @warning @p list must be a pointer to the first element of the list.
1246  */
1247 static inline void        *eina_list_data_get(const Eina_List *list) EINA_PURE EINA_WARN_UNUSED_RESULT;
1248
1249 /**
1250  * @brief Set the list node data member.
1251  *
1252  * @param list The list node to get the data member of.
1253  * @param data The data member to the list node.
1254  * @return The previous data value.
1255  *
1256  * This function set the data member @p data of the specified list node
1257  * @p list. It returns the previous data of the node. If @p list is
1258  * @c NULL, this function returns @c NULL.
1259  *
1260  * @warning @p list must be a pointer to the first element of the list.
1261  */
1262 static inline void        *eina_list_data_set(Eina_List *list, const void *data);
1263
1264 /**
1265  * @brief Get the count of the number of items in a list.
1266  *
1267  * @param list The list whose count to return.
1268  * @return The number of members in the list.
1269  *
1270  * This function returns how many members @p list contains. If the
1271  * list is @c NULL, @c 0 is returned.
1272  *
1273  * NB: This is an order-1 operation and takes the same time regardless
1274  * of the length of the list.
1275  *
1276  * @warning @p list must be a pointer to the first element of the list.
1277  */
1278 static inline unsigned int eina_list_count(const Eina_List *list) EINA_PURE;
1279
1280
1281 /**
1282  * @brief Returned a new iterator associated to a list.
1283  *
1284  * @param list The list.
1285  * @return A new iterator.
1286  *
1287  * This function returns a newly allocated iterator associated to @p
1288  * list. If @p list is @c NULL or the count member of @p list is less
1289  * or equal than 0, this function still returns a valid iterator that
1290  * will always return false on eina_iterator_next(), thus keeping API
1291  * sane.
1292  *
1293  * If the memory can not be allocated, NULL is returned
1294  * and #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator
1295  * is returned.
1296  *
1297  * @warning @p list must be a pointer to the first element of the list.
1298  *
1299  * @warning if the list structure changes then the iterator becomes
1300  *    invalid! That is, if you add or remove nodes this iterator
1301  *    behavior is undefined and your program may crash!
1302  */
1303 EAPI Eina_Iterator        *eina_list_iterator_new(const Eina_List *list) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
1304
1305
1306 /**
1307  * @brief Returned a new reversed iterator associated to a list.
1308  *
1309  * @param list The list.
1310  * @return A new iterator.
1311  *
1312  * This function returns a newly allocated iterator associated to @p
1313  * list. If @p list is @c NULL or the count member of @p list is less
1314  * or equal than 0, this function still returns a valid iterator that
1315  * will always return false on eina_iterator_next(), thus keeping API
1316  * sane.
1317  *
1318  * Unlike eina_list_iterator_new(), this will walk the list backwards.
1319  *
1320  * If the memory can not be allocated, NULL is returned
1321  * and #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator
1322  * is returned.
1323  *
1324  * @warning @p list must be a pointer to the first element of the list.
1325  *
1326  * @warning if the list structure changes then the iterator becomes
1327  *    invalid! That is, if you add or remove nodes this iterator
1328  *    behavior is undefined and your program may crash!
1329  */
1330 EAPI Eina_Iterator        *eina_list_iterator_reversed_new(const Eina_List *list) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
1331
1332
1333 /**
1334  * @brief Returned a new accessor associated to a list.
1335  *
1336  * @param list The list.
1337  * @return A new accessor.
1338  *
1339  * This function returns a newly allocated accessor associated to
1340  * @p list. If @p list is @c NULL or the count member of @p list is
1341  * less or equal than 0, this function returns @c NULL. If the memory can
1342  * not be allocated, @c NULL is returned and #EINA_ERROR_OUT_OF_MEMORY is
1343  * set. Otherwise, a valid accessor is returned.
1344  *
1345  * @warning @p list must be a pointer to the first element of the list.
1346  */
1347 EAPI Eina_Accessor        *eina_list_accessor_new(const Eina_List *list) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
1348
1349 /**
1350  * @def EINA_LIST_FOREACH
1351  * @brief Macro to iterate over a list.
1352  *
1353  * @param list The list to iterate over.
1354  * @param l A list that is used as an iterator and points to the current node.
1355  * @param data Current item's data.
1356  *
1357  * This macro iterates over @p list from the first element to
1358  * the last. @p data is the data related to the current element.
1359  * @p l is an #Eina_List used as the list iterator.
1360  *
1361  * The following diagram ilustrates this macro iterating over a list of four
1362  * elements("one", "two", "three" and "four"):
1363  * @htmlonly
1364  * <img src="eina-list-foreach.png" style="max-width: 100%;" />
1365  * <a href="eina-list-foreach.png">Full-size</a>
1366  * @endhtmlonly
1367  * @image latex eina-list-foreach.eps width=\textwidth
1368  *
1369  * It can be used to free list data, as in the following example:
1370  *
1371  * @code
1372  * Eina_List *list;
1373  * Eina_List *l;
1374  * char      *data;
1375  *
1376  * // list is already filled,
1377  * // its elements are just duplicated strings,
1378  * // EINA_LIST_FOREACH will be used to free those strings
1379  *
1380  * EINA_LIST_FOREACH(list, l, data)
1381  *   free(data);
1382  * eina_list_free(list);
1383  * @endcode
1384  *
1385  * @note This is not the optimal way to release memory allocated to
1386  *       a list, since it iterates over the list twice.
1387  *       For an optimized algorithm, use EINA_LIST_FREE().
1388  *
1389  * @warning @p list must be a pointer to the first element of the list.
1390  *
1391  * @warning Be careful when deleting list nodes.
1392  *          If you remove the current node and continue iterating,
1393  *          the code will fail because the macro will not be able
1394  *          to get the next node. Notice that it's OK to remove any
1395  *          node if you stop the loop after that.
1396  *          For destructive operations such as this, consider
1397  *          using EINA_LIST_FOREACH_SAFE().
1398  */
1399 #define EINA_LIST_FOREACH(list, l, data) \
1400   for (l = list,                         \
1401        data = eina_list_data_get(l);     \
1402        l;                                \
1403        l = eina_list_next(l),            \
1404        data = eina_list_data_get(l))
1405
1406 /**
1407  * @def EINA_LIST_REVERSE_FOREACH
1408  * @brief Macro to iterate over a list in the reverse order.
1409  *
1410  * @param list The list to iterate over.
1411  * @param l A list that is used as an iterator and points to the current node.
1412  * @param data Current item's data.
1413  *
1414  * This macro works like EINA_LIST_FOREACH, but iterates from the
1415  * last element of a list to the first.
1416  * @p data is the data related to the current element, while @p l
1417  * is an #Eina_List that is used as the list iterator.
1418  *
1419  * The following diagram ilustrates this macro iterating over a list of four
1420  * elements("one", "two", "three" and "four"):
1421  * @htmlonly
1422  * <img src="eina-list-reverse-foreach.png" style="max-width: 100%;" />
1423  * <a href="eina-list-reverse-foreach.png">Full-size</a>
1424  * @endhtmlonly
1425  * @image latex eina-list-reverse-foreach.eps width=\textwidth
1426  *
1427  * It can be used to free list data, as in the following example:
1428  *
1429  * @code
1430  * Eina_List *list;
1431  * Eina_List *l;
1432  * char      *data;
1433  *
1434  * // list is already filled,
1435  * // its elements are just duplicated strings,
1436  * // EINA_LIST_REVERSE_FOREACH will be used to free those strings
1437  *
1438  * EINA_LIST_REVERSE_FOREACH(list, l, data)
1439  *   free(data);
1440  * eina_list_free(list);
1441  * @endcode
1442  *
1443  * @note This is not the optimal way to release memory allocated to
1444  *       a list, since it iterates over the list twice.
1445  *       For an optimized algorithm, use EINA_LIST_FREE().
1446  *
1447  * @warning @p list must be a pointer to the first element of the list.
1448  *
1449  * @warning Be careful when deleting list nodes.
1450  *          If you remove the current node and continue iterating,
1451  *          the code will fail because the macro will not be able
1452  *          to get the next node. Notice that it's OK to remove any
1453  *          node if you stop the loop after that.
1454  *          For destructive operations such as this, consider
1455  *          using EINA_LIST_REVERSE_FOREACH_SAFE().
1456  */
1457 #define EINA_LIST_REVERSE_FOREACH(list, l, data) \
1458   for (l = eina_list_last(list),                 \
1459        data = eina_list_data_get(l);             \
1460        l;                                        \
1461        l = eina_list_prev(l),                    \
1462        data = eina_list_data_get(l))
1463
1464 /**
1465  * @def EINA_LIST_FOREACH_SAFE
1466  * @brief Macro to iterate over a list with support for node deletion.
1467  *
1468  * @param list The list to iterate over.
1469  * @param l A list that is used as an iterator and points to the current node.
1470  * @param l_next A list that is used as an iterator and points to the next node.
1471  * @param data Current item's data.
1472  *
1473  * This macro iterates over @p list from the first element to
1474  * the last. @p data is the data related to the current element.
1475  * @p l is an #Eina_List used as the list iterator.
1476  *
1477  * Since this macro stores a pointer to the next list node in @p l_next,
1478  * deleting the current node and continuing looping is safe.
1479  *
1480  * The following diagram ilustrates this macro iterating over a list of four
1481  * elements("one", "two", "three" and "four"):
1482  * @htmlonly
1483  * <img src="eina-list-foreach-safe.png" style="max-width: 100%;" />
1484  * <a href="eina-list-foreach-safe.png">Full-size</a>
1485  * @endhtmlonly
1486  * @image latex eina-list-foreach-safe.eps width=\textwidth
1487  *
1488  * This macro can be used to free list nodes, as in the following example:
1489  *
1490  * @code
1491  * Eina_List *list;
1492  * Eina_List *l;
1493  * Eina_List *l_next;
1494  * char      *data;
1495  *
1496  * // list is already filled,
1497  * // its elements are just duplicated strings,
1498  * // EINA_LIST_FOREACH_SAFE will be used to free elements that match "key".
1499  *
1500  * EINA_LIST_FOREACH_SAFE(list, l, l_next, data)
1501  *   if (strcmp(data, "key") == 0) {
1502  *      free(data);
1503  *      list = eina_list_remove_list(list, l);
1504  *   }
1505  * @endcode
1506  *
1507  * @warning @p list must be a pointer to the first element of the list.
1508  */
1509 #define EINA_LIST_FOREACH_SAFE(list, l, l_next, data) \
1510   for (l = list,                                      \
1511        l_next = eina_list_next(l),                    \
1512        data = eina_list_data_get(l);                  \
1513        l;                                             \
1514        l = l_next,                                    \
1515        l_next = eina_list_next(l),                    \
1516        data = eina_list_data_get(l))
1517
1518 /**
1519  * @def EINA_LIST_REVERSE_FOREACH_SAFE
1520  * @brief Macro to iterate over a list in the reverse order with support
1521  *        for deletion.
1522  *
1523  * @param list The list to iterate over.
1524  * @param l A list that is used as an iterator and points to the current node.
1525  * @param l_prev A list that is used as an iterator and points to the previous node.
1526  * @param data Current item's data.
1527  *
1528  * This macro works like EINA_LIST_FOREACH_SAFE, but iterates from the
1529  * last element of a list to the first.
1530  * @p data is the data related to the current element, while @p l
1531  * is an #Eina_List that is used as the list iterator.
1532  *
1533  * Since this macro stores a pointer to the previous list node in @p l_prev,
1534  * deleting the current node and continuing looping is safe.
1535  *
1536  * The following diagram ilustrates this macro iterating over a list of four
1537  * elements("one", "two", "three" and "four"):
1538  * @htmlonly
1539  * <img src="eina-list-reverse-foreach-safe.png" style="max-width: 100%;" />
1540  * <a href="eina-list-reverse-foreach-safe.png">Full-size</a>
1541  * @endhtmlonly
1542  * @image latex eina-list-reverse-foreach-safe.eps width=\textwidth
1543  *
1544  * This macro can be used to free list nodes, as in the following example:
1545  *
1546  * @code
1547  * Eina_List *list;
1548  * Eina_List *l;
1549  * Eina_List *l_prev;
1550  * char       *data;
1551  *
1552  * // list is already filled,
1553  * // its elements are just duplicated strings,
1554  * // EINA_LIST_REVERSE_FOREACH_SAFE will be used to free elements that match "key".
1555  *
1556  * EINA_LIST_REVERSE_FOREACH_SAFE(list, l, l_prev, data)
1557  *   if (strcmp(data, "key") == 0) {
1558  *      free(data);
1559  *      list = eina_list_remove_list(list, l);
1560  *   }
1561  * @endcode
1562  *
1563  * @warning @p list must be a pointer to the first element of the list.
1564  */
1565 #define EINA_LIST_REVERSE_FOREACH_SAFE(list, l, l_prev, data) \
1566   for (l = eina_list_last(list),                              \
1567        l_prev = eina_list_prev(l),                            \
1568        data = eina_list_data_get(l);                          \
1569        l;                                                     \
1570        l = l_prev,                                            \
1571        l_prev = eina_list_prev(l),                            \
1572        data = eina_list_data_get(l))
1573
1574 /**
1575  * @def EINA_LIST_FREE
1576  * @brief Macro to remove each list node while having access to each node's data.
1577  *
1578  * @param list The list that will be cleared.
1579  * @param data Current node's data.
1580  *
1581  * This macro will call #eina_list_remove_list for each list node, and store
1582  * the data contained in the current node in @p data.
1583  *
1584  * The following diagram ilustrates this macro iterating over a list of four
1585  * elements("one", "two", "three" and "four"):
1586  * @htmlonly
1587  * <img src="eina-list-free.png" style="max-width: 100%;" />
1588  * <a href="eina-list-free.png">Full-size</a>
1589  * @endhtmlonly
1590  * @image latex eina-list-free.eps width=\textwidth
1591  *
1592  * If you do not need to release node data, it is easier to call #eina_list_free().
1593  *
1594  * @code
1595  * Eina_List *list;
1596  * char      *data;
1597  *
1598  * // list is already filled,
1599  * // its elements are just duplicated strings,
1600  *
1601  * EINA_LIST_FREE(list, data)
1602  *   free(data);
1603  * @endcode
1604  *
1605  * @warning @p list must be a pointer to the first element of the list.
1606  *
1607  * @see eina_list_free()
1608  */
1609 #define EINA_LIST_FREE(list, data)               \
1610   for (data = eina_list_data_get(list);          \
1611        list;                                     \
1612        list = eina_list_remove_list(list, list), \
1613        data = eina_list_data_get(list))
1614
1615 #include "eina_inline_list.x"
1616
1617 /**
1618  * @}
1619  */
1620
1621 /**
1622  * @}
1623  */
1624
1625 /**
1626  * @}
1627  */
1628
1629 #endif /* EINA_LIST_H_ */