src/include/eina_array.h

   1 /* EINA - EFL data type library
   2  * Copyright (C) 2008 Cedric Bail
   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_ARRAY_H_
  20 #define EINA_ARRAY_H_
  21
  22 #include <stdlib.h>
  23
  24 #include "eina_config.h"
  25
  26 #include "eina_types.h"
  27 #include "eina_error.h"
  28 #include "eina_iterator.h"
  29 #include "eina_accessor.h"
  30 #include "eina_magic.h"
  31
  32
  33 /**
  34  * @page eina_array_01_example_page Basic array usage
  35  * @dontinclude eina_array_01.c
  36  *
  37  * For this example we add stdlib.h, stdio.h and string.h for some
  38  * convenience functions. The first thing to do to be able to use an
  39  * @ref Eina_Array is to include Eina.h:
  40  * @skip #include
  41  * @until Eina.h
  42  *
  43  * Here we have a callback that prints the element given to it:
  44  * @until }
  45  *
  46  * Now we create our entry point and declare some variables, nothing especial:
  47  * @until unsigned
  48  *
  49  * Before we can start using any array function we need to initialize eina:
  50  * @until eina_init
  51  *
  52  * So now to actually creating our array. The only interesting thing here is the
  53  * argument given to the eina_array_new() function, this argument sets how fast
  54  * the array grows.
  55  * @until array_new
  56  *
  57  * If you know before hand how big the array will need to be you should set the
  58  * step to that. In our case we can set it to the number of string we have and
  59  * since we didn't do that in the eina_array_new() we can do it now:
  60  * @until array_step_set
  61  *
  62  * Now let us populate our array with some strings:
  63  * @until push
  64  * @note Notice we use strdup, so we will have to free that memory later on.
  65  *
  66  * Now lets check the size of the array:
  67  * @until printf
  68  *
  69  * And now we call a function on every member of our array to print it:
  70  * @until foreach
  71  *
  72  * One of the strengths of @ref Eina_Array over @ref Eina_List is that it has
  73  * very fast random access to elements, so this is very efficient:
  74  * @until printf
  75  *
  76  * And now we free up the memory allocated with the strdup()s:
  77  * @until free
  78  *
  79  * And the array memory itself:
  80  * @until array_free
  81  *
  82  * And finally shutdown eina and exit:
  83  * @until }
  84  *
  85  * The full source code can be found on the examples folder
  86  * on the @ref eina_array_01_c "eina_array_01.c" file.
  87  */
  88
  89 /**
  90  * @page eina_array_01_c Basic array usage example
  91  *
  92  * @include eina_array_01.c
  93  * @example eina_array_01.c
  94  */
  95
  96 /**
  97  * @page eina_array_02_example_page Removing array elements
  98  * @dontinclude eina_array_02.c
  99  *
 100  * Just the usual includes:
 101  * @skip #include
 102  * @until Eina.h
 103  *
 104  * This the callback we are going to use to decide which strings stay on the
 105  * array and which will be removed, we use something simple, but this can be as
 106  * complex as you like:
 107  * @until }
 108  *
 109  * This is the same code we used before to populate the list with the slight
 110  * difference of not using strdup:
 111  * @until array_push
 112  *
 113  * So we have added all our elements to the array, but it turns out that is not
 114  * the elements we wanted, so let's empty the array and add the correct strings:
 115  * @until array_push
 116  *
 117  * It seems we made a little mistake in one of our strings so we need to replace
 118  * it, here is how:
 119  * @until data_set
 120  *
 121  * Now that there is a populated array we can remove elements from it easily:
 122  * @until array_remove
 123  *
 124  * And check that the elements were actually removed:
 125  * @until printf
 126  *
 127  * Since this time we didn't use strdup we don't need to free each string:
 128  * @until }
 129  *
 130  * The full source code can be found on the examples folder
 131  * on the @ref eina_array_02_c "eina_array_02.c" file.
 132  */
 133
 134 /**
 135  * @page eina_array_02_c Basic array usage example
 136  *
 137  * @include eina_array_02.c
 138  * @example eina_array_02.c
 139  */
 140
 141 /**
 142  * @addtogroup Eina_Array_Group Array
 143  *
 144  * @brief These functions provide array management.
 145  *
 146  * The Array data type in Eina is designed to have very fast access to
 147  * its data (compared to the Eina @ref Eina_List_Group). On the other hand,
 148  * data can be added or removed only at the end of the array. To insert
 149  * data at any place, the Eina @ref Eina_List_Group is the correct container
 150  * to use.
 151  *
 152  * To use the array data type, eina_init() must be called before any
 153  * other array functions. When no more eina array functions are used,
 154  * eina_shutdown() must be called to free all the resources.
 155  *
 156  * An array must be created with eina_array_new(). It allocates all
 157  * the necessary data for an array. When not needed anymore, an array
 158  * is freed with eina_array_free(). This function does not free any
 159  * allocated memory used to store the data of each element. For that,
 160  * just iterate over the array to free them. A convenient way to do
 161  * that is by using #EINA_ARRAY_ITER_NEXT. An example of code is given
 162  * in the description of this macro.
 163  *
 164  * @warning Functions do not check if the used array is valid or not. It's up to
 165  * the user to be sure of that. It is designed like that for performance
 166  * reasons.
 167  *
 168  * The usual features of an array are classic ones: to append an
 169  * element, use eina_array_push() and to remove the last element, use
 170  * eina_array_pop(). To retrieve the element at a given position, use
 171  * eina_array_data_get(). The number of elements can be retrieved with
 172  * eina_array_count().
 173  *
 174  * Eina_Array is different from a conventional C array in a number of ways, most
 175  * importantly they grow and shrink dynamically, this means that if you add an
 176  * element to a full array it grows and that when you remove an element from an
 177  * array it @b may shrink.
 178  *
 179  * When the array needs to grow it allocates memory not just for the element
 180  * currently being added since that would mean allocating memory(which is
 181  * computationally expensive) often, instead it grows to be able to hold @p step
 182  * more elements. Similarly if you remove elements in such a way that that the
 183  * array is left holding its capacity - @p step elements it will shrink.
 184  *
 185  * The following image illustrates how an Eina_Array grows:
 186  *
 187  * @image html eina_array-growth.png
 188  * @image latex eina_array-growth.eps width=\textwidth
 189  *
 190  * Eina_Array only stores pointers but it can store data of any type in the form
 191  * of void pointers.
 192  *
 193  * See here some examples:
 194  * @li @ref eina_array_01_example_page
 195  * @li @ref eina_array_02_example_page
 196  */
 197
 198 /**
 199  * @addtogroup Eina_Data_Types_Group Data Types
 200  *
 201  * @{
 202  */
 203
 204 /**
 205  * @addtogroup Eina_Containers_Group Containers
 206  *
 207  * @{
 208  */
 209
 210 /**
 211  * @defgroup Eina_Array_Group Array
 212  *
 213  * @{
 214  */
 215
 216 /**
 217  * @typedef Eina_Array
 218  * Type for a generic vector.
 219  */
 220 typedef struct _Eina_Array Eina_Array;
 221
 222 /**
 223  * @typedef Eina_Array_Iterator
 224  * Type for an iterator on arrays, used with #EINA_ARRAY_ITER_NEXT.
 225  */
 226 typedef void **Eina_Array_Iterator;
 227
 228 /**
 229  * @struct _Eina_Array
 230  * Type for an array of data.
 231  */
 232 struct _Eina_Array
 233 {
 234 #define EINA_ARRAY_VERSION 1
 235    int          version; /**< Should match EINA_ARRAY_VERSION used when compiled your apps, provided for ABI compatibility */
 236
 237    void       **data; /**< Pointer to a vector of pointer to payload */
 238    unsigned int total; /**< Total number of slots in the vector */
 239    unsigned int count; /**< Number of active slots in the vector */
 240    unsigned int step; /**< How much must we grow the vector when it is full */
 241    EINA_MAGIC
 242 };
 243
 244
 245 /**
 246  * @brief Create a new array.
 247  *
 248  * @param step The count of pointers to add when increasing the array size.
 249  * @return @c NULL on failure, non @c NULL otherwise.
 250  *
 251  * This function creates a new array. When adding an element, the array
 252  * allocates @p step elements. When that buffer is full, then adding
 253  * another element will increase the buffer by @p step elements again.
 254  *
 255  * This function return a valid array on success, or @c NULL if memory
 256  * allocation fails. In that case, the error is set
 257  * to #EINA_ERROR_OUT_OF_MEMORY.
 258  */
 259 EAPI Eina_Array *eina_array_new(unsigned int step) EINA_WARN_UNUSED_RESULT EINA_MALLOC EINA_WARN_UNUSED_RESULT;
 260
 261 /**
 262  * @brief Free an array.
 263  *
 264  * @param array The array to free.
 265  *
 266  * This function frees @p array. It calls first eina_array_flush() then
 267  * free the memory of the pointer. It does not free the memory
 268  * allocated for the elements of @p array. To free them,
 269  * use #EINA_ARRAY_ITER_NEXT. For performance reasons, there is no check
 270  * of @p array.
 271  */
 272 EAPI void        eina_array_free(Eina_Array *array) EINA_ARG_NONNULL(1);
 273
 274 /**
 275  * @brief Set the step of an array.
 276  *
 277  * @param array The array.
 278  * @param sizeof_eina_array Should be the value returned by sizeof(Eina_Array).
 279  * @param step The count of pointers to add when increasing the array size.
 280  *
 281  * This function sets the step of @p array to @p step. For performance
 282  * reasons, there is no check of @p array. If it is @c NULL or
 283  * invalid, the program may crash.
 284  *
 285  * @warning This function can @b only be called on uninitialized arrays.
 286  */
 287 EAPI void        eina_array_step_set(Eina_Array  *array,
 288                                      unsigned int sizeof_eina_array,
 289                                      unsigned int step) EINA_ARG_NONNULL(1);
 290 /**
 291  * @brief Clean an array.
 292  *
 293  * @param array The array to clean.
 294  *
 295  * This function sets the count member of @p array to 0, however it doesn't free
 296  * any space. This is particularly useful if you need to empty the array and
 297  * add lots of elements quickly. For performance reasons, there is no check of
 298  * @p array. If it is @c NULL or invalid, the program may crash.
 299  */
 300 static inline void eina_array_clean(Eina_Array *array) EINA_ARG_NONNULL(1);
 301
 302 /**
 303  * @brief Flush an array.
 304  *
 305  * @param array The array to flush.
 306  *
 307  * This function sets the count and total members of @p array to 0,
 308  * frees and set to NULL its data member. For performance reasons,
 309  * there is no check of @p array. If it is @c NULL or invalid, the
 310  * program may crash.
 311  */
 312 EAPI void eina_array_flush(Eina_Array *array) EINA_ARG_NONNULL(1);
 313
 314 /**
 315  * @brief Rebuild an array by specifying the data to keep.
 316  *
 317  * @param array The array.
 318  * @param keep The functions which selects the data to keep.
 319  * @param gdata The data to pass to the function keep.
 320  * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
 321  *
 322  * This function rebuilds @p array be specifying the elements to keep with the
 323  * function @p keep. No empty/invalid fields are left in the array. @p gdata is
 324  * an additional data to pass to @p keep. For performance reasons, there is no
 325  * check of @p array. If it is @c NULL or invalid, the program may crash.
 326  *
 327  * If it wasn't able to remove items due to an allocation failure, it will
 328  * return #EINA_FALSE and the error is set to #EINA_ERROR_OUT_OF_MEMORY.
 329  */
 330 EAPI Eina_Bool eina_array_remove(Eina_Array * array,
 331                                  Eina_Bool (*keep)(void *data, void *gdata),
 332                                  void *gdata) EINA_ARG_NONNULL(1, 2);
 333 static inline Eina_Bool eina_array_push(Eina_Array *array,
 334                                         const void *data) EINA_ARG_NONNULL(1, 2);
 335 static inline void     *eina_array_pop(Eina_Array *array) EINA_ARG_NONNULL(1);
 336 static inline void     *eina_array_data_get(const Eina_Array *array,
 337                                             unsigned int      idx) EINA_ARG_NONNULL(1);
 338 /**
 339  * @brief Set the data at a given position in an array.
 340  *
 341  * @param array The array.
 342  * @param idx The position of the data to set.
 343  * @param data The data to set.
 344  *
 345  * This function sets the data at the position @p idx in @p
 346  * array to @p data, this effectively replaces the previously held data, you
 347  * must therefore get a pointer to it first if you need to free it. For
 348  * performance reasons, there is no check of @p array or @p idx. If it is @c
 349  * NULL or invalid, the program may crash.
 350 */
 351 static inline void      eina_array_data_set(const Eina_Array *array,
 352                                             unsigned int      idx,
 353                                             const void       *data) EINA_ARG_NONNULL(1);
 354 static inline unsigned int eina_array_count_get(const Eina_Array *array) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
 355 static inline unsigned int eina_array_count(const Eina_Array *array) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
 356
 357 /**
 358  * @brief Returned a new iterator associated to an array.
 359  *
 360  * @param array The array.
 361  * @return A new iterator.
 362  *
 363  * This function returns a newly allocated iterator associated to
 364  * @p array. If @p array is @c NULL or the count member of @p array is
 365  * less or equal than 0, this function returns @c NULL. If the memory can
 366  * not be allocated, NULL is returned and #EINA_ERROR_OUT_OF_MEMORY is
 367  * set. Otherwise, a valid iterator is returned.
 368  */
 369 EAPI Eina_Iterator        *eina_array_iterator_new(const Eina_Array *array) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
 370
 371 /**
 372  * @brief Returned a new accessor associated to an array.
 373  *
 374  * @param array The array.
 375  * @return A new accessor.
 376  *
 377  * This function returns a newly allocated accessor associated to
 378  * @p array. If @p array is @c NULL or the count member of @p array is
 379  * less or equal than 0, this function returns @c NULL. If the memory can
 380  * not be allocated, @c NULL is returned and #EINA_ERROR_OUT_OF_MEMORY is
 381  * set. Otherwise, a valid accessor is returned.
 382  */
 383 EAPI Eina_Accessor        *eina_array_accessor_new(const Eina_Array *array) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
 384 /**
 385  * @brief Provide a safe way to iterate over an array
 386  *
 387  * @param array The array to iterate over.
 388  * @param cb The callback to call for each item.
 389  * @param fdata The user data to pass to the callback.
 390  * @return #EINA_TRUE if it successfully iterate all items of the array.
 391  *
 392  * This function provide a safe way to iterate over an array. @p cb should
 393  * return #EINA_TRUE as long as you want the function to continue iterating,
 394  * by returning #EINA_FALSE it will stop and return #EINA_FALSE as a result.
 395  */
 396 static inline Eina_Bool    eina_array_foreach(Eina_Array  *array,
 397                                               Eina_Each_Cb cb,
 398                                               void        *fdata);
 399 /**
 400  * @def EINA_ARRAY_ITER_NEXT
 401  * @brief Macro to iterate over an array easily.
 402  *
 403  * @param array The array to iterate over.
 404  * @param index The integer number that is increased while iterating.
 405  * @param item The data
 406  * @param iterator The iterator
 407  *
 408  * This macro allows the iteration over @p array in an easy way. It
 409  * iterates from the first element to the last one. @p index is an
 410  * integer that increases from 0 to the number of elements. @p item is
 411  * the data of each element of @p array, so it is a pointer to a type
 412  * chosen by the user. @p iterator is of type #Eina_Array_Iterator.
 413  *
 414  * This macro can be used for freeing the data of an array, like in
 415  * the following example:
 416  *
 417  * @code
 418  * Eina_Array         *array;
 419  * char               *item;
 420  * Eina_Array_Iterator iterator;
 421  * unsigned int        i;
 422  *
 423  * // array is already filled,
 424  * // its elements are just duplicated strings,
 425  * // EINA_ARRAY_ITER_NEXT will be used to free those strings
 426  *
 427  * EINA_ARRAY_ITER_NEXT(array, i, item, iterator)
 428  *   free(item);
 429  * @endcode
 430  */
 431 #define EINA_ARRAY_ITER_NEXT(array, index, item, iterator)                  \
 432   for (index = 0, iterator = (array)->data;                                 \
 433        (index < eina_array_count(array)) && ((item = *((iterator)++)));     \
 434                                                   ++(index))
 435
 436 #include "eina_inline_array.x"
 437
 438 /**
 439  * @}
 440  */
 441
 442 /**
 443  * @}
 444  */
 445
 446 /**
 447  * @}
 448  */
 449
 450 #endif