| eina_array.h | | eina_array.h | |
|---|
| | | | |
| skipping to change at line 33 | | skipping to change at line 33 | |
|---|
| | | | |
| #include "eina_config.h" | | #include "eina_config.h" | |
| | | | |
| #include "eina_types.h" | | #include "eina_types.h" | |
| #include "eina_error.h" | | #include "eina_error.h" | |
| #include "eina_iterator.h" | | #include "eina_iterator.h" | |
| #include "eina_accessor.h" | | #include "eina_accessor.h" | |
| #include "eina_magic.h" | | #include "eina_magic.h" | |
| | | | |
| /** | | /** | |
|
| | | * @page array_01_example_page Basic array usage | |
| | | * @dontinclude eina_array_01.c | |
| | | * | |
| | | * For this example we add stdlib.h, stdio.h and string.h for some | |
| | | * convenience functions. The first thing to do to be able to use an | |
| | | * @ref Eina_Array is to include Eina.h: | |
| | | * @skip #include | |
| | | * @until Eina.h | |
| | | * | |
| | | * Here we have a callback that prints the element given to it: | |
| | | * @until } | |
| | | * | |
| | | * Now we create our entry point and declare some variables, nothing especi | |
| | | al: | |
| | | * @until unsigned | |
| | | * | |
| | | * Before we can start using any array function we need to initialize eina: | |
| | | * @until eina_init | |
| | | * | |
| | | * So now to actually creating our array. The only interesting thing here i | |
| | | s the | |
| | | * argument given to the eina_array_new() function, this argument sets how | |
| | | fast | |
| | | * the array grows. | |
| | | * @until array_new | |
| | | * | |
| | | * If you know before hand how big the array will need to be you should set | |
| | | the | |
| | | * step to that. In our case we can set it to the number of string we have | |
| | | and | |
| | | * since we didn't do that in the eina_array_new() we can do it now: | |
| | | * @until array_step_set | |
| | | * | |
| | | * Now let us populate our array with some strings: | |
| | | * @until push | |
| | | * @note Notice we use strdup, so we will have to free that memory later on | |
| | | . | |
| | | * | |
| | | * Now lets check the size of the array: | |
| | | * @until printf | |
| | | * | |
| | | * And now we call a function on every member of our array to print it: | |
| | | * @until foreach | |
| | | * | |
| | | * One of the strenghts of @ref Eina_Array over @ref Eina_List is that it h | |
| | | as | |
| | | * very fast random access to elements, so this is very efficient: | |
| | | * @until printf | |
| | | * | |
| | | * And now we free up the memory allocated with the strdup()s: | |
| | | * @until free | |
| | | * | |
| | | * And the array memory itself: | |
| | | * @until array_free | |
| | | * | |
| | | * And finally shutdown eina and exit: | |
| | | * @until } | |
| | | * | |
| | | * The full source code can be found on the examples folder | |
| | | * on the @ref eina_array_01_c "eina_array_01.c" file. | |
| | | */ | |
| | | | |
| | | /** | |
| | | * @page eina_array_01_c Basic array usage example | |
| | | * | |
| | | * @include eina_array_01.c | |
| | | * @example eina_array_01.c | |
| | | */ | |
| | | | |
| | | /** | |
| | | * @page array_02_example_page Removing array elements | |
| | | * @dontinclude eina_array_02.c | |
| | | * | |
| | | * Just the usual includes: | |
| | | * @skip #include | |
| | | * @until Eina.h | |
| | | * | |
| | | * This the callback we are going to use to decide which strings stay on th | |
| | | e | |
| | | * array and which will be removed, we use something simple, but this can b | |
| | | e as | |
| | | * complex as you like: | |
| | | * @until } | |
| | | * | |
| | | * This is the same code we used before to populate the list with the sligh | |
| | | t | |
| | | * difference of not using strdup: | |
| | | * @until array_push | |
| | | * | |
| | | * So we have added all our elements to the array, but it turns out that is | |
| | | not | |
| | | * the elements we wanted, so let's empty the array and add the correct str | |
| | | ings: | |
| | | * @until array_push | |
| | | * | |
| | | * It seems we made a little mistake in one of our strings so we need to re | |
| | | place | |
| | | * it, here is how: | |
| | | * @until data_set | |
| | | * | |
| | | * Now that there is a populated array we can remove elements from it easil | |
| | | y: | |
| | | * @until array_remove | |
| | | * | |
| | | * And check that the elements were actually removed: | |
| | | * @until printf | |
| | | * | |
| | | * Since this time we didn't use strdup we don't need to free each string: | |
| | | * @until } | |
| | | * | |
| | | * The full source code can be found on the examples folder | |
| | | * on the @ref eina_array_02_c "eina_array_02.c" file. | |
| | | */ | |
| | | | |
| | | /** | |
| | | * @page eina_array_02_c Basic array usage example | |
| | | * | |
| | | * @include eina_array_02.c | |
| | | * @example eina_array_02.c | |
| | | */ | |
| | | | |
| | | /** | |
| | | * @addtogroup Eina_Array_Group Array | |
| | | * | |
| | | * @brief These functions provide array management. | |
| | | * | |
| | | * The Array data type in Eina is designed to have very fast access to | |
| | | * its data (compared to the Eina @ref Eina_List_Group). On the other hand, | |
| | | * data can be added or removed only at the end of the array. To insert | |
| | | * data at any place, the Eina @ref Eina_List_Group is the correct containe | |
| | | r | |
| | | * to use. | |
| | | * | |
| | | * To use the array data type, eina_init() must be called before any | |
| | | * other array functions. When no more eina array functions are used, | |
| | | * eina_shutdown() must be called to free all the resources. | |
| | | * | |
| | | * An array must be created with eina_array_new(). It allocates all | |
| | | * the necessary data for an array. When not needed anymore, an array | |
| | | * is freed with eina_array_free(). This function does not free any | |
| | | * allocated memory used to store the data of each element. For that, | |
| | | * just iterate over the array to free them. A convenient way to do | |
| | | * that is by using #EINA_ARRAY_ITER_NEXT. An example of code is given | |
| | | * in the description of this macro. | |
| | | * | |
| | | * @warning Functions do not check if the used array is valid or not. It's | |
| | | up to | |
| | | * the user to be sure of that. It is designed like that for performance | |
| | | * reasons. | |
| | | * | |
| | | * The usual features of an array are classic ones: to append an | |
| | | * element, use eina_array_push() and to remove the last element, use | |
| | | * eina_array_pop(). To retrieve the element at a given position, use | |
| | | * eina_array_data_get(). The number of elements can be retrieved with | |
| | | * eina_array_count_get(). | |
| | | * | |
| | | * Eina_Array is different from a conventional C array in a number of ways, | |
| | | most | |
| | | * importantly they grow and shrink dynamically, this means that if you add | |
| | | an | |
| | | * element to a full array it grows and that when you remove an element fro | |
| | | m an | |
| | | * array it @b may shrink. | |
| | | * | |
| | | * When the array needs to grow it allocates memory not just for the elemen | |
| | | t | |
| | | * currently being added since that would mean allocating memory(which is | |
| | | * computationally expensive) often, instead it grows to be able to hold @p | |
| | | step | |
| | | * more elements. Similarly if you remove elements in such a way that that | |
| | | the | |
| | | * array is left holding its capacity - @p step elements it will shrink. | |
| | | * | |
| | | * The following image illustrates how an Eina_Array grows: | |
| | | * | |
| | | * @image html eina_array-growth.png | |
| | | * @image latex eina_array-growth.eps width=\textwidth | |
| | | * | |
| | | * Eina_Array only stores pointers but it can store data of any type in the | |
| | | form | |
| | | * of void pointers. | |
| | | * | |
| | | * See here some examples: | |
| | | * @li @ref array_01_example_page | |
| | | * @li @ref array_02_example_page | |
| | | */ | |
| | | | |
| | | /** | |
| * @addtogroup Eina_Data_Types_Group Data Types | | * @addtogroup Eina_Data_Types_Group Data Types | |
| * | | * | |
| * @{ | | * @{ | |
| */ | | */ | |
| | | | |
| /** | | /** | |
| * @addtogroup Eina_Containers_Group Containers | | * @addtogroup Eina_Containers_Group Containers | |
| * | | * | |
| * @{ | | * @{ | |
| */ | | */ | |
| | | | |
| skipping to change at line 78 | | skipping to change at line 243 | |
|---|
| #define EINA_ARRAY_VERSION 1 | | #define EINA_ARRAY_VERSION 1 | |
| int version; /**< Should match EINA_ARRAY_VERSION used when com
piled your apps, provided for ABI compatibility */ | | int version; /**< Should match EINA_ARRAY_VERSION used when com
piled your apps, provided for ABI compatibility */ | |
| | | | |
| void **data; /**< Pointer to a vector of pointer to payload */ | | void **data; /**< Pointer to a vector of pointer to payload */ | |
| unsigned int total; /**< Total number of slots in the vector */ | | unsigned int total; /**< Total number of slots in the vector */ | |
| unsigned int count; /**< Number of active slots in the vector */ | | unsigned int count; /**< Number of active slots in the vector */ | |
| unsigned int step; /**< How much must we grow the vector when it is full
*/ | | unsigned int step; /**< How much must we grow the vector when it is full
*/ | |
| EINA_MAGIC | | EINA_MAGIC | |
| }; | | }; | |
| | | | |
|
| | | /** | |
| | | * @brief Create a new array. | |
| | | * | |
| | | * @param step The count of pointers to add when increasing the array size. | |
| | | * @return @c NULL on failure, non @c NULL otherwise. | |
| | | * | |
| | | * This function creates a new array. When adding an element, the array | |
| | | * allocates @p step elements. When that buffer is full, then adding | |
| | | * another element will increase the buffer by @p step elements again. | |
| | | * | |
| | | * This function return a valid array on success, or @c NULL if memory | |
| | | * allocation fails. In that case, the error is set to | |
| | | * #EINA_ERROR_OUT_OF_MEMORY. | |
| | | */ | |
| EAPI Eina_Array *eina_array_new(unsigned int step) EINA_WARN_UNUSED_RESULT
EINA_MALLOC EINA_WARN_UNUSED_RESULT; | | EAPI Eina_Array *eina_array_new(unsigned int step) EINA_WARN_UNUSED_RESULT
EINA_MALLOC EINA_WARN_UNUSED_RESULT; | |
|
| | | | |
| | | /** | |
| | | * @brief Free an array. | |
| | | * | |
| | | * @param array The array to free. | |
| | | * | |
| | | * This function frees @p array. It calls first eina_array_flush() then | |
| | | * free the memory of the pointer. It does not free the memory | |
| | | * allocated for the elements of @p array. To free them, use | |
| | | * #EINA_ARRAY_ITER_NEXT. For performance reasons, there is no check | |
| | | * of @p array. | |
| | | */ | |
| EAPI void eina_array_free(Eina_Array *array) EINA_ARG_NONNULL(1); | | EAPI void eina_array_free(Eina_Array *array) EINA_ARG_NONNULL(1); | |
|
| | | | |
| | | /** | |
| | | * @brief Set the step of an array. | |
| | | * | |
| | | * @param array The array. | |
| | | * @param sizeof_eina_array Should be the value returned by sizeof(Eina_Arr | |
| | | ay). | |
| | | * @param step The count of pointers to add when increasing the array size. | |
| | | * | |
| | | * This function sets the step of @p array to @p step. For performance | |
| | | * reasons, there is no check of @p array. If it is @c NULL or | |
| | | * invalid, the program may crash. | |
| | | * | |
| | | * @warning This function can @b only be called on uninitialized arrays. | |
| | | */ | |
| EAPI void eina_array_step_set(Eina_Array *array, | | EAPI void eina_array_step_set(Eina_Array *array, | |
| unsigned int sizeof_eina_array, | | unsigned int sizeof_eina_array, | |
| unsigned int step) EINA_ARG_NONNULL(1)
; | | unsigned int step) EINA_ARG_NONNULL(1)
; | |
|
| | | /** | |
| | | * @brief Clean an array. | |
| | | * | |
| | | * @param array The array to clean. | |
| | | * | |
| | | * This function sets the count member of @p array to 0, however it doesn't | |
| | | free | |
| | | * any space. This is particularly useful if you need to empty the array an | |
| | | d | |
| | | * add lots of elements quickly. For performance reasons, there is no check | |
| | | of | |
| | | * @p array. If it is @c NULL or invalid, the program may crash. | |
| | | */ | |
| static inline void eina_array_clean(Eina_Array *array) EINA_ARG_NONNULL(1); | | static inline void eina_array_clean(Eina_Array *array) EINA_ARG_NONNULL(1); | |
|
| | | | |
| | | /** | |
| | | * @brief Flush an array. | |
| | | * | |
| | | * @param array The array to flush. | |
| | | * | |
| | | * This function sets the count and total members of @p array to 0, | |
| | | * frees and set to NULL its data member. For performance reasons, | |
| | | * there is no check of @p array. If it is @c NULL or invalid, the | |
| | | * program may crash. | |
| | | */ | |
| EAPI void eina_array_flush(Eina_Array *array) EINA_ARG_NONNULL(1); | | EAPI void eina_array_flush(Eina_Array *array) EINA_ARG_NONNULL(1); | |
|
| | | | |
| | | /** | |
| | | * @brief Rebuild an array by specifying the data to keep. | |
| | | * | |
| | | * @param array The array. | |
| | | * @param keep The functions which selects the data to keep. | |
| | | * @param gdata The data to pass to the function keep. | |
| | | * @return #EINA_TRUE on success, #EINA_FALSE oterwise. | |
| | | * | |
| | | * This function rebuilds @p array be specifying the elements to keep with | |
| | | the | |
| | | * function @p keep. No empty/invalid fields are left in the array. @p gdat | |
| | | a is | |
| | | * an additional data to pass to @p keep. For performance reasons, there is | |
| | | no | |
| | | * check of @p array. If it is @c NULL or invalid, the program may crash. | |
| | | * | |
| | | * If it wasn't able to remove items due to an allocation failure, it will | |
| | | * return #EINA_FALSE and the error is set to #EINA_ERROR_OUT_OF_MEMORY. | |
| | | */ | |
| EAPI Eina_Bool eina_array_remove(Eina_Array * array, | | EAPI Eina_Bool eina_array_remove(Eina_Array * array, | |
| Eina_Bool (*keep)(void *data, void *gdata)
, | | Eina_Bool (*keep)(void *data, void *gdata)
, | |
| void *gdata) EINA_ARG_NONNULL(1, 2); | | void *gdata) EINA_ARG_NONNULL(1, 2); | |
| static inline Eina_Bool eina_array_push(Eina_Array *array, | | static inline Eina_Bool eina_array_push(Eina_Array *array, | |
| const void *data) EINA_ARG_NONNULL(
1, 2); | | const void *data) EINA_ARG_NONNULL(
1, 2); | |
| static inline void *eina_array_pop(Eina_Array *array) EINA_ARG_NONNULL(
1); | | static inline void *eina_array_pop(Eina_Array *array) EINA_ARG_NONNULL(
1); | |
| static inline void *eina_array_data_get(const Eina_Array *array, | | static inline void *eina_array_data_get(const Eina_Array *array, | |
| unsigned int idx) EINA_ARG
_NONNULL(1); | | unsigned int idx) EINA_ARG
_NONNULL(1); | |
|
| | | /** | |
| | | * @brief Set the data at a given position in an array. | |
| | | * | |
| | | * @param array The array. | |
| | | * @param idx The potition of the data to set. | |
| | | * @param data The data to set. | |
| | | * | |
| | | * This function sets the data at the position @p idx in @p | |
| | | * array to @p data, this effectively replaces the previously held data, yo | |
| | | u | |
| | | * must therefore get a pointer to it first if you need to free it. For | |
| | | * performance reasons, there is no check of @p array or @p idx. If it is @ | |
| | | c | |
| | | * NULL or invalid, the program may crash. | |
| | | */ | |
| static inline void eina_array_data_set(const Eina_Array *array, | | static inline void eina_array_data_set(const Eina_Array *array, | |
| unsigned int idx, | | unsigned int idx, | |
| const void *data) EINA_AR
G_NONNULL(1); | | const void *data) EINA_AR
G_NONNULL(1); | |
| static inline unsigned int eina_array_count_get(const Eina_Array *array) EI
NA_ARG_NONNULL(1); | | static inline unsigned int eina_array_count_get(const Eina_Array *array) EI
NA_ARG_NONNULL(1); | |
|
| | | | |
| | | /** | |
| | | * @brief Returned a new iterator associated to an array. | |
| | | * | |
| | | * @param array The array. | |
| | | * @return A new iterator. | |
| | | * | |
| | | * This function returns a newly allocated iterator associated to | |
| | | * @p array. If @p array is @c NULL or the count member of @p array is | |
| | | * less or equal than 0, this function returns NULL. If the memory can | |
| | | * not be allocated, NULL is returned and #EINA_ERROR_OUT_OF_MEMORY is | |
| | | * set. Otherwise, a valid iterator is returned. | |
| | | */ | |
| EAPI Eina_Iterator *eina_array_iterator_new(const Eina_Array *array)
EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; | | EAPI Eina_Iterator *eina_array_iterator_new(const Eina_Array *array)
EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; | |
|
| | | | |
| | | /** | |
| | | * @brief Returned a new accessor associated to an array. | |
| | | * | |
| | | * @param array The array. | |
| | | * @return A new accessor. | |
| | | * | |
| | | * This function returns a newly allocated accessor associated to | |
| | | * @p array. If @p array is @c NULL or the count member of @p array is | |
| | | * less or equal than 0, this function returns NULL. If the memory can | |
| | | * not be allocated, NULL is returned and #EINA_ERROR_OUT_OF_MEMORY is | |
| | | * set. Otherwise, a valid accessor is returned. | |
| | | */ | |
| EAPI Eina_Accessor *eina_array_accessor_new(const Eina_Array *array)
EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; | | EAPI Eina_Accessor *eina_array_accessor_new(const Eina_Array *array)
EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; | |
|
| | | /** | |
| | | * @brief Provide a safe way to iterate over an array | |
| | | * | |
| | | * @param array The array to iterate over. | |
| | | * @param cb The callback to call for each item. | |
| | | * @param fdata The user data to pass to the callback. | |
| | | * @return EINA_TRUE if it successfully iterate all items of the array. | |
| | | * | |
| | | * This function provide a safe way to iterate over an array. @p cb should | |
| | | * return EINA_TRUE as long as you want the function to continue iterating, | |
| | | * by returning EINA_FALSE it will stop and return EINA_FALSE as a result. | |
| | | */ | |
| static inline Eina_Bool eina_array_foreach(Eina_Array *array, | | static inline Eina_Bool eina_array_foreach(Eina_Array *array, | |
| Eina_Each_Cb cb, | | Eina_Each_Cb cb, | |
| void *data); | | void *data); | |
| /** | | /** | |
| * @def EINA_ARRAY_ITER_NEXT | | * @def EINA_ARRAY_ITER_NEXT | |
| * @brief Macro to iterate over an array easily. | | * @brief Macro to iterate over an array easily. | |
| * | | * | |
| * @param array The array to iterate over. | | * @param array The array to iterate over. | |
| * @param index The integer number that is increased while itareting. | | * @param index The integer number that is increased while itareting. | |
| * @param item The data | | * @param item The data | |
| | | | |
| End of changes. 11 change blocks. |
|---|
| 0 lines changed or deleted | | 326 lines changed or added | |
|---|
|
| eina_file.h | | eina_file.h | |
|---|
| /* EINA - EFL data type library | | /* EINA - EFL data type library | |
| * Copyright (C) 2007-2008 Jorge Luis Zapata Muga | | * Copyright (C) 2007-2008 Jorge Luis Zapata Muga | |
|
| | | * 2011 Cedric Bail | |
| * | | * | |
| * This library is free software; you can redistribute it and/or | | * This library is free software; you can redistribute it and/or | |
| * modify it under the terms of the GNU Lesser General Public | | * modify it under the terms of the GNU Lesser General Public | |
| * License as published by the Free Software Foundation; either | | * License as published by the Free Software Foundation; either | |
| * version 2.1 of the License, or (at your option) any later version. | | * version 2.1 of the License, or (at your option) any later version. | |
| * | | * | |
| * This library is distributed in the hope that it will be useful, | | * This library is distributed in the hope that it will be useful, | |
| * but WITHOUT ANY WARRANTY; without even the implied warranty of | | * but WITHOUT ANY WARRANTY; without even the implied warranty of | |
| * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
| * Lesser General Public License for more details. | | * Lesser General Public License for more details. | |
| * | | * | |
| * You should have received a copy of the GNU Lesser General Public | | * You should have received a copy of the GNU Lesser General Public | |
| * License along with this library; | | * License along with this library; | |
| * if not, see <http://www.gnu.org/licenses/>. | | * if not, see <http://www.gnu.org/licenses/>. | |
| */ | | */ | |
| | | | |
| #ifndef EINA_FILE_H_ | | #ifndef EINA_FILE_H_ | |
| #define EINA_FILE_H_ | | #define EINA_FILE_H_ | |
| | | | |
| #include <limits.h> | | #include <limits.h> | |
|
| | | #include <time.h> | |
| | | | |
| #include "eina_types.h" | | #include "eina_types.h" | |
| #include "eina_array.h" | | #include "eina_array.h" | |
| #include "eina_iterator.h" | | #include "eina_iterator.h" | |
| | | | |
| /** | | /** | |
|
| | | * @page eina_file_example_01_page | |
| | | * @dontinclude eina_file_01.c | |
| | | * | |
| | | * For brevity includes, variable declarations and initialization was omitt | |
| | | ed | |
| | | * from this page, however the full source code can be seen @ref | |
| | | * eina_file_example_01 "here". | |
| | | * | |
| | | * Here we have a simple callback to print the name of a file and the path | |
| | | that | |
| | | * contains it: | |
| | | * @skip static | |
| | | * @until } | |
| | | * | |
| | | * We can use this callback in the following call: | |
| | | * @skipline eina_file_dir_list | |
| | | * | |
| | | * The above was a way to print the files in a directory, but it is not the | |
| | | only | |
| | | * one: | |
| | | * @until iterator_free | |
| | | * | |
| | | * And now two ways to get more information than just file names: | |
| | | * @until iterator_free | |
| | | * @until iterator_free | |
| | | * | |
| | | * The above ways of getting files on a list may produce the same output, b | |
| | | ut | |
| | | * they have an important difference, eina_file_direct_ls() will @b not cal | |
| | | l | |
| | | * stat, this means that on some systems it might not have file type | |
| | | * information. On the other hand it might be faster than eina_file_stat_ls | |
| | | (). | |
| | | */ | |
| | | /** | |
| | | * @page eina_file_example_01 | |
| | | * @include eina_file_01.c | |
| | | * @example eina_file_01.c | |
| | | */ | |
| | | /** | |
| * @addtogroup Eina_Tools_Group Tools | | * @addtogroup Eina_Tools_Group Tools | |
| * | | * | |
| * @{ | | * @{ | |
| */ | | */ | |
|
| | | | |
| /** | | /** | |
|
| * @defgroup Eina_File_Group File | | * @addtogroup Eina_File_Group File | |
| | | * | |
| | | * @brief Functions to handle files and directories. | |
| | | * | |
| | | * This functions make it easier to do a number o file and directory operat | |
| | | ions | |
| | | * such as getting the list of files in a directory, spliting paths and fin | |
| | | ding | |
| | | * out file size and type. | |
| | | * | |
| | | * @warning All functions in this group are @b blocking which means they ma | |
| | | ke | |
| | | * take a long time to return, use them carefully. | |
| | | * | |
| | | * See an example @ref eina_file_example_01_page "here". | |
| * | | * | |
| * @{ | | * @{ | |
| */ | | */ | |
| | | | |
| /** | | /** | |
| * @typedef Eina_File_Direct_Info | | * @typedef Eina_File_Direct_Info | |
| * A typedef to #_Eina_File_Direct_Info. | | * A typedef to #_Eina_File_Direct_Info. | |
| */ | | */ | |
| typedef struct _Eina_File_Direct_Info Eina_File_Direct_Info; | | typedef struct _Eina_File_Direct_Info Eina_File_Direct_Info; | |
| | | | |
| /** | | /** | |
| * @typedef Eina_File_Dir_List_Cb | | * @typedef Eina_File_Dir_List_Cb | |
| * Type for a callback to be called when iterating over the files of a | | * Type for a callback to be called when iterating over the files of a | |
| * directory. | | * directory. | |
|
| * @param The file name EXCLUDING the path | | | |
| * @param path The path passed to eina_file_dir_list() | | | |
| * @param data The data passed to eina_file_dir_list() | | | |
| */ | | */ | |
| typedef void (*Eina_File_Dir_List_Cb)(const char *name, const char *path, v
oid *data); | | typedef void (*Eina_File_Dir_List_Cb)(const char *name, const char *path, v
oid *data); | |
| | | | |
| /** | | /** | |
| * @typedef Eina_File_Type | | * @typedef Eina_File_Type | |
| * file type in Eina_File_Direct_Info. | | * file type in Eina_File_Direct_Info. | |
| */ | | */ | |
| typedef enum { | | typedef enum { | |
| EINA_FILE_UNKNOWN, /**< Unknown file type. */ | | EINA_FILE_UNKNOWN, /**< Unknown file type. */ | |
| EINA_FILE_FIFO, /**< Named pipe (FIFO) type (unused on Windows). */ | | EINA_FILE_FIFO, /**< Named pipe (FIFO) type (unused on Windows). */ | |
| EINA_FILE_CHR, /**< Character device type (unused on Windows). */ | | EINA_FILE_CHR, /**< Character device type (unused on Windows). */ | |
| EINA_FILE_DIR, /**< Directory type. */ | | EINA_FILE_DIR, /**< Directory type. */ | |
| EINA_FILE_BLK, /**< Block device type (unused on Windows). */ | | EINA_FILE_BLK, /**< Block device type (unused on Windows). */ | |
| EINA_FILE_REG, /**< Regular file type. */ | | EINA_FILE_REG, /**< Regular file type. */ | |
| EINA_FILE_LNK, /**< Symbolic link type. */ | | EINA_FILE_LNK, /**< Symbolic link type. */ | |
| EINA_FILE_SOCK, /**< UNIX domain socket type (unused on Windows). */ | | EINA_FILE_SOCK, /**< UNIX domain socket type (unused on Windows). */ | |
| EINA_FILE_WHT /**< Whiteout file type (unused on Windows). */ | | EINA_FILE_WHT /**< Whiteout file type (unused on Windows). */ | |
| } Eina_File_Type; | | } Eina_File_Type; | |
| | | | |
|
| | | typedef struct _Eina_File Eina_File; | |
| | | | |
| | | typedef enum { | |
| | | EINA_FILE_RANDOM, /**< Advise random memory access to the mapped memo | |
| | | ry. */ | |
| | | EINA_FILE_SEQUENTIAL, /**< Advise sequential memory access to the mapped | |
| | | memory. */ | |
| | | EINA_FILE_WILLNEED, /**< Advise need for all the mapped memory. */ | |
| | | EINA_FILE_POPULATE /**< Request all the mapped memory. */ | |
| | | } Eina_File_Populate; | |
| | | | |
| /* Why do this? Well PATH_MAX may vary from when eina itself is compiled | | /* Why do this? Well PATH_MAX may vary from when eina itself is compiled | |
| * to when the app using eina is compiled. exposing the path buffer below | | * to when the app using eina is compiled. exposing the path buffer below | |
|
| * cant safely and portably vary based on how/when you compile. it should | | * can't safely and portably vary based on how/when you compile. it should | |
| * always be the same for both eina inside AND for apps outside that use ei
na | | * always be the same for both eina inside AND for apps outside that use ei
na | |
| * so define this to 8192 - most PATH_MAX values are like 4096 or 1024 (wit
h | | * so define this to 8192 - most PATH_MAX values are like 4096 or 1024 (wit
h | |
| * windows i think being 260), so 8192 should cover almost all cases. there | | * windows i think being 260), so 8192 should cover almost all cases. there | |
| * is a possibility that PATH_MAX could be more than 8192. if anyone spots | | * is a possibility that PATH_MAX could be more than 8192. if anyone spots | |
| * a path_max that is bigger - let us know, but, for now we will assume | | * a path_max that is bigger - let us know, but, for now we will assume | |
| * it never happens */ | | * it never happens */ | |
| #define EINA_PATH_MAX 8192 | | #define EINA_PATH_MAX 8192 | |
| /** | | /** | |
| * @struct _Eina_File_Direct_Info | | * @struct _Eina_File_Direct_Info | |
| * A structure to store informations of a path. | | * A structure to store informations of a path. | |
| | | | |
| skipping to change at line 105 | | skipping to change at line 157 | |
|---|
| /** | | /** | |
| * @def EINA_FILE_DIR_LIST_CB | | * @def EINA_FILE_DIR_LIST_CB | |
| * @brief cast to an #Eina_File_Dir_List_Cb. | | * @brief cast to an #Eina_File_Dir_List_Cb. | |
| * | | * | |
| * @param function The function to cast. | | * @param function The function to cast. | |
| * | | * | |
| * This macro casts @p function to Eina_File_Dir_List_Cb. | | * This macro casts @p function to Eina_File_Dir_List_Cb. | |
| */ | | */ | |
| #define EINA_FILE_DIR_LIST_CB(function) ((Eina_File_Dir_List_Cb)function) | | #define EINA_FILE_DIR_LIST_CB(function) ((Eina_File_Dir_List_Cb)function) | |
| | | | |
|
| | | /** | |
| | | * @brief List all files on the directory calling the function for every fi | |
| | | le found. | |
| | | * | |
| | | * @param dir The directory name. | |
| | | * @param recursive Iterate recursively in the directory. | |
| | | * @param cb The callback to be called. | |
| | | * @param data The data to pass to the callback. | |
| | | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | |
| | | * | |
| | | * This function calls @p cb for each file that is in @p dir. To have @p cb | |
| | | * called on files that are in subdirectories of @p dir @p recursive should | |
| | | be | |
| | | * EINA_TRUE. In other words if @p recursive is EINA_FALSE, only direct chi | |
| | | ldren | |
| | | * of @p dir will be operated on, if @p recursive is EINA_TRUE the entire t | |
| | | ree | |
| | | * of files that is below @p dir will be operated on. | |
| | | * | |
| | | * If @p cb or @p dir are @c NULL, or if @p dir is a string of size 0, | |
| | | * or if @p dir can not be opened, this function returns #EINA_FALSE | |
| | | * immediately. otherwise, it returns #EINA_TRUE. | |
| | | */ | |
| EAPI Eina_Bool eina_file_dir_list(const char *dir, | | EAPI Eina_Bool eina_file_dir_list(const char *dir, | |
| Eina_Bool recursive, | | Eina_Bool recursive, | |
| Eina_File_Dir_List_Cb cb, | | Eina_File_Dir_List_Cb cb, | |
| void *data) EINA_ARG_NONN
ULL(1, 3); | | void *data) EINA_ARG_NONN
ULL(1, 3); | |
|
| | | | |
| | | /** | |
| | | * @brief Split a path according to the delimiter of the filesystem. | |
| | | * | |
| | | * @param path The path to split. | |
| | | * @return An array of the parts of the path to split. | |
| | | * | |
| | | * This function splits @p path according to the delimiter of the used | |
| | | * filesystem. If @p path is @c NULL or if the array can not be | |
| | | * created, @c NULL is returned, otherwise, an array with each part of @p p | |
| | | ath | |
| | | * is returned. | |
| | | */ | |
| EAPI Eina_Array *eina_file_split(char *path) EINA_WARN_UNUSED_RESULT EIN
A_ARG_NONNULL(1) EINA_MALLOC; | | EAPI Eina_Array *eina_file_split(char *path) EINA_WARN_UNUSED_RESULT EIN
A_ARG_NONNULL(1) EINA_MALLOC; | |
|
| | | | |
| | | /** | |
| | | * @brief Get an iterator to list the content of a directory. | |
| | | * | |
| | | * @param dir The name of the directory to list | |
| | | * @return Return an Eina_Iterator that will walk over the files and direct | |
| | | ories | |
| | | * in @p dir. On failure it will return NULL. | |
| | | * | |
| | | * Returns an iterator for shared strings, the name of each file in @p dir | |
| | | will | |
| | | * only be fetched when advancing the iterator, which means there is very l | |
| | | ittle | |
| | | * cost associated with creating the list and stopping halfway through it. | |
| | | * | |
| | | * @warning The iterator will hand the user a stringshared value with the f | |
| | | ull | |
| | | * path. The user must free the string using eina_stringshare_del() on it. | |
| | | * | |
| | | * @note The container for the iterator is of type DIR*. | |
| | | * @note The iterator will walk over '.' and '..' without returning them. | |
| | | * | |
| | | * @see eina_file_direct_ls() | |
| | | */ | |
| EAPI Eina_Iterator *eina_file_ls(const char *dir) EINA_WARN_UNUSED_RESULT E
INA_ARG_NONNULL(1) EINA_MALLOC; | | EAPI Eina_Iterator *eina_file_ls(const char *dir) EINA_WARN_UNUSED_RESULT E
INA_ARG_NONNULL(1) EINA_MALLOC; | |
|
| | | | |
| | | /** | |
| | | * @brief Get an iterator to list the content of a directory, with direct | |
| | | * information. | |
| | | * | |
| | | * @param dir The name of the directory to list | |
| | | * | |
| | | * @return Return an Eina_Iterator that will walk over the files and | |
| | | * directory in the pointed directory. On failure it will | |
| | | * return NULL. | |
| | | * | |
| | | * Returns an iterator for Eina_File_Direct_Info, the name of each file in | |
| | | @p | |
| | | * dir will only be fetched when advancing the iterator, which means there | |
| | | is | |
| | | * cost associated with creating the list and stopping halfway through it. | |
| | | * | |
| | | * @warning The Eina_File_Direct_Info returned by the iterator <b>must not< | |
| | | /b> | |
| | | * be modified in any way. | |
| | | * @warning When the iterator is advanced or deleted the Eina_File_Direct_I | |
| | | nfo | |
| | | * returned is no longer valid. | |
| | | * | |
| | | * @note The container for the iterator is of type DIR*. | |
| | | * @note The iterator will walk over '.' and '..' without returning them. | |
| | | * @note The difference between this function ahd eina_file_direct_ls() is | |
| | | that | |
| | | * it guarantees the file type information will be correct incurring | |
| | | a | |
| | | * possible performance penalty. | |
| | | * | |
| | | * @see eina_file_direct_ls() | |
| | | */ | |
| EAPI Eina_Iterator *eina_file_stat_ls(const char *dir) EINA_WARN_UNUSED_RES
ULT EINA_ARG_NONNULL(1) EINA_MALLOC; | | EAPI Eina_Iterator *eina_file_stat_ls(const char *dir) EINA_WARN_UNUSED_RES
ULT EINA_ARG_NONNULL(1) EINA_MALLOC; | |
|
| | | | |
| | | /** | |
| | | * @brief Get an iterator to list the content of a directory, with direct | |
| | | * information. | |
| | | * | |
| | | * @param dir The name of the directory to list | |
| | | * | |
| | | * @return Return an Eina_Iterator that will walk over the files and | |
| | | * directory in the pointed directory. On failure it will | |
| | | * return NULL. | |
| | | * | |
| | | * Returns an iterator for Eina_File_Direct_Info, the name of each file in | |
| | | @p | |
| | | * dir will only be fetched when advancing the iterator, which means there | |
| | | is | |
| | | * cost associated with creating the list and stopping halfway through it. | |
| | | * | |
| | | * @warning If readdir_r doesn't contain file type information file type wi | |
| | | ll | |
| | | * be DT_UNKNOW. | |
| | | * @warning The Eina_File_Direct_Info returned by the iterator <b>must not< | |
| | | /b> | |
| | | * be modified in any way. | |
| | | * @warning When the iterator is advanced or deleted the Eina_File_Direct_I | |
| | | nfo | |
| | | * returned is no longer valid. | |
| | | * | |
| | | * @note The container for the iterator is of type DIR*. | |
| | | * @note The iterator will walk over '.' and '..' without returning them. | |
| | | * @note The difference between this function ahd eina_file_stat_ls() is th | |
| | | at | |
| | | * it may not get the file type information however it is likely to b | |
| | | e | |
| | | * faster. | |
| | | * | |
| | | * @see eina_file_ls() | |
| | | */ | |
| EAPI Eina_Iterator *eina_file_direct_ls(const char *dir) EINA_WARN_UNUSED_R
ESULT EINA_ARG_NONNULL(1) EINA_MALLOC; | | EAPI Eina_Iterator *eina_file_direct_ls(const char *dir) EINA_WARN_UNUSED_R
ESULT EINA_ARG_NONNULL(1) EINA_MALLOC; | |
| | | | |
| /** | | /** | |
|
| | | * @brief Sanitize file path. | |
| | | * | |
| | | * @param path The path to sanitize | |
| | | * | |
| | | * @return an allocated string with the sanitized path. | |
| | | * | |
| | | * This function take care of adding the current working directory if it's | |
| | | a | |
| | | * relative path and also remove all '..' and '//' reference in the origina | |
| | | l | |
| | | * path. | |
| | | * | |
| | | * @since 1.1 | |
| | | */ | |
| | | EAPI char *eina_file_path_sanitize(const char *path); | |
| | | | |
| | | /** | |
| | | * @brief Get a read-only handler to a file. | |
| | | * | |
| | | * @param name Filename to open | |
| | | * @param shared Requested a shm | |
| | | * | |
| | | * Opens a file in read-only mode. @p name should be an absolute path. An | |
| | | * Eina_File handle can be shared among multiple instances if @p shared is | |
| | | * EINA_TRUE. | |
| | | * | |
| | | * @since 1.1 | |
| | | */ | |
| | | EAPI Eina_File *eina_file_open(const char *name, Eina_Bool shared) EINA_WAR | |
| | | N_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; | |
| | | | |
| | | /** | |
| | | * @brief Unref file handler. | |
| | | * | |
| | | * @param file File handler to unref. | |
| | | * | |
| | | * Decremente file's refcount and if it reaches zero close it. | |
| | | * | |
| | | * @since 1.1 | |
| | | */ | |
| | | EAPI void eina_file_close(Eina_File *file); | |
| | | | |
| | | /** | |
| | | * @brief Get file size at open time. | |
| | | * | |
| | | * @param file The file handler to request the size from. | |
| | | * @return The length of the file. | |
| | | * | |
| | | * @since 1.1 | |
| | | */ | |
| | | EAPI size_t eina_file_size_get(Eina_File *file); | |
| | | | |
| | | /** | |
| | | * @brief Get the last modification time of an open file. | |
| | | * | |
| | | * @param file The file handler to request the modification time from. | |
| | | * @return The last modification time. | |
| | | * | |
| | | * @since 1.1 | |
| | | */ | |
| | | EAPI time_t eina_file_mtime_get(Eina_File *file); | |
| | | | |
| | | /** | |
| | | * @brief Get the filename of an open file. | |
| | | * | |
| | | * @param file The file handler to request the name from. | |
| | | * @return Stringshared filename of the file. | |
| | | * | |
| | | * @since 1.1 | |
| | | */ | |
| | | EAPI const char *eina_file_filename_get(Eina_File *file); | |
| | | | |
| | | /** | |
| | | * @brief Map all the file to a buffer. | |
| | | * | |
| | | * @param file The file handler to map in memory | |
| | | * @param rule The rule to apply to the mapped memory | |
| | | * @return A pointer to a buffer that map all the file content. @c NULL if | |
| | | it fail. | |
| | | * | |
| | | * @since 1.1 | |
| | | */ | |
| | | EAPI void *eina_file_map_all(Eina_File *file, Eina_File_Populate rule); | |
| | | | |
| | | /** | |
| | | * @brief Map a part of the file. | |
| | | * | |
| | | * @param file The file handler to map in memory | |
| | | * @param rule The rule to apply to the mapped memory | |
| | | * @param offset The offset inside the file | |
| | | * @param length The length of the memory to map | |
| | | * @return A valid pointer to the system memory with @p length valid byte i | |
| | | n it. And @c NULL if not inside the file or anything else goes wrong. | |
| | | * | |
| | | * This does handle refcounting so it will share map that target the same m | |
| | | emory area. | |
| | | * | |
| | | * @since 1.1 | |
| | | */ | |
| | | EAPI void *eina_file_map_new(Eina_File *file, Eina_File_Populate rule, | |
| | | unsigned long int offset, unsigned long int le | |
| | | ngth); | |
| | | | |
| | | /** | |
| | | * @brief Unref and unmap memory if possible. | |
| | | * | |
| | | * @param file The file handler to unmap memory from. | |
| | | * @param map Memory map to unref and unmap. | |
| | | * | |
| | | * @since 1.1 | |
| | | */ | |
| | | EAPI void eina_file_map_free(Eina_File *file, void *map); | |
| | | | |
| | | /** | |
| * @} | | * @} | |
| */ | | */ | |
| | | | |
| /** | | /** | |
| * @} | | * @} | |
| */ | | */ | |
| | | | |
| #endif /* EINA_FILE_H_ */ | | #endif /* EINA_FILE_H_ */ | |
| | | | |
| End of changes. 14 change blocks. |
|---|
| 6 lines changed or deleted | | 314 lines changed or added | |
|---|
|
| eina_hash.h | | eina_hash.h | |
|---|
| | | | |
| skipping to change at line 27 | | skipping to change at line 27 | |
|---|
| * if not, see <http://www.gnu.org/licenses/>. | | * if not, see <http://www.gnu.org/licenses/>. | |
| */ | | */ | |
| | | | |
| #ifndef EINA_HASH_H_ | | #ifndef EINA_HASH_H_ | |
| #define EINA_HASH_H_ | | #define EINA_HASH_H_ | |
| | | | |
| #include "eina_types.h" | | #include "eina_types.h" | |
| #include "eina_iterator.h" | | #include "eina_iterator.h" | |
| | | | |
| /** | | /** | |
|
| | | * @page hash_01_example_page Eina_Hash in action | |
| | | * @dontinclude eina_hash_01.c | |
| | | * | |
| | | * We are going to store some tuples into our table, that will map each @a | |
| | | name | |
| | | * to a @a number. The cost to access a given number from the name should b | |
| | | e | |
| | | * very small, even with many entries in our table. This is the initial dat | |
| | | a: | |
| | | * @skip _Phone_Entry | |
| | | * @until // _start_entries | |
| | | * | |
| | | * Before starting to play with the hash, let's write a callback that will | |
| | | be | |
| | | * used to free the elements from it. Since we are just storing strduped | |
| | | * strings, we just need to free them: | |
| | | * | |
| | | * @skip static | |
| | | * @until } | |
| | | * | |
| | | * We also need a callback to iterate over the elements of the list later, | |
| | | so | |
| | | * we are defining it now: | |
| | | * | |
| | | * @skip Eina_Bool | |
| | | * @until } | |
| | | * | |
| | | * Now let's create our @ref Eina_Hash using @ref | |
| | | * eina_hash_string_superfast_new : | |
| | | * | |
| | | * @skip eina_init | |
| | | * @until phone_book | |
| | | * | |
| | | * Now we add the keys and data to the hash using @ref eina_hash_add . This | |
| | | * means that the key is copied inside the table, together with the pointer | |
| | | to | |
| | | * the data (phone numbers). | |
| | | * | |
| | | * @skip for | |
| | | * @until } | |
| | | * | |
| | | * Some basic manipulations with the hash, like finding a value given a key | |
| | | , | |
| | | * deleting an entry, modifying an entry are exemplified in the following l | |
| | | ines. | |
| | | * Notice that the @ref eina_hash_modify function returns the old value sto | |
| | | red | |
| | | * in that entry, and it needs to be freed, while the @ref eina_hash_del | |
| | | * function already calls our free callback: | |
| | | * | |
| | | * @skip Look for | |
| | | * @until free( | |
| | | * | |
| | | * The @ref eina_hash_set function can be used to set a key-value entry to | |
| | | the | |
| | | * table if it doesn't exist, or to modify an existent entry. It returns th | |
| | | e old | |
| | | * entry if it was already set, and NULL otherwise. But since it will | |
| | | * return NULL on error too, we need to check if an error has occurred: | |
| | | * | |
| | | * @skip Modify | |
| | | * @until printf("\n"); | |
| | | * | |
| | | * There are different ways of iterate over the entries of a hash. Here we | |
| | | show | |
| | | * two of them: using @ref eina_hash_foreach and @ref Eina_Iterator . | |
| | | * | |
| | | * @skip List of phones | |
| | | * @until eina_iterator_free(it); | |
| | | * | |
| | | * It's also possible to change the key for a specific entry, without havin | |
| | | g to | |
| | | * remove the entry from the table and adding it again: | |
| | | * | |
| | | * @skipline eina_hash_move | |
| | | * | |
| | | * We can remove all the elements from the table without free the table its | |
| | | elf: | |
| | | * | |
| | | * @skip Empty the phone book | |
| | | * @until eina_hash_population | |
| | | * | |
| | | * Or free the the entire table with its content: | |
| | | * | |
| | | * @skipline eina_hash_free | |
| | | * | |
| | | * | |
| | | * The full code for this example can be seen here: @ref eina_hash_01_c | |
| | | */ | |
| | | | |
| | | /** | |
| | | * @page eina_hash_01_c Hash table in action | |
| | | * | |
| | | * @include eina_hash_01.c | |
| | | * @example eina_hash_01.c | |
| | | */ | |
| | | | |
| | | /** | |
| | | * @page hash_02_example_page Different types of tables | |
| | | * | |
| | | * This example shows two more types of hash tables that can be created usi | |
| | | ng | |
| | | * @ref Eina_Hash . For more types, consult the reference documentation of | |
| | | @ref | |
| | | * eina_hash_new. | |
| | | * @include eina_hash_02.c | |
| | | * @example eina_hash_02.c | |
| | | */ | |
| | | | |
| | | /** | |
| | | * @example eina_hash_03.c | |
| | | * Same example as @ref hash_01_example_page but using a "string small" has | |
| | | h | |
| | | * table instead of "string superfast". | |
| | | */ | |
| | | | |
| | | /** | |
| | | * @example eina_hash_04.c | |
| | | * Same example as @ref hash_01_example_page but using a "string djb2" hash | |
| | | * table instead of "string superfast". | |
| | | */ | |
| | | | |
| | | /** | |
| | | * @example eina_hash_05.c | |
| | | * Same example as @ref hash_01_example_page but using a "int32" hash | |
| | | * table instead of "string superfast". | |
| | | */ | |
| | | | |
| | | /** | |
| | | * @example eina_hash_06.c | |
| | | * Same example as @ref hash_01_example_page but using a "int64" hash | |
| | | * table instead of "string superfast". | |
| | | */ | |
| | | | |
| | | /** | |
| | | * @example eina_hash_07.c | |
| | | * Same example as @ref hash_01_example_page but using a "pointer" hash | |
| | | * table instead of "string superfast". | |
| | | */ | |
| | | | |
| | | /** | |
| | | * @example eina_hash_08.c | |
| | | * This example shows the the usage of eina_hash_add(), eina_hash_add_by_ha | |
| | | sh(), | |
| | | * eina_hash_direct_add_by_hash(), eina_hash_del(), eina_hash_del_by_key_ha | |
| | | sh(), | |
| | | * eina_hash_del_by_key(), eina_hash_del_by_data(), eina_hash_find_by_hash( | |
| | | ) and | |
| | | * eina_hash_modify_by_hash(). | |
| | | */ | |
| | | | |
| | | /** | |
| | | * @addtogroup Eina_Hash_Group Hash Table | |
| | | * | |
| | | * @brief Hash table management. Useful for mapping keys to values. | |
| | | * | |
| | | * The hash table is useful for when one wants to implement a table that ma | |
| | | ps | |
| | | * keys (usually strings) to data, and have relatively fast access time. Th | |
| | | e | |
| | | * performance is proportional to the load factor of the table (number of | |
| | | * elements / number of buckets). See @ref hashtable_algo for implementatio | |
| | | n | |
| | | * details. | |
| | | * | |
| | | * Different implementations exists depending on what kind of key will be u | |
| | | sed | |
| | | * to access the data: strings, integers, pointers, stringshared or your ow | |
| | | n. | |
| | | * | |
| | | * Eina hash tables can copy the keys when using eina_hash_add() or not whe | |
| | | n | |
| | | * using eina_hash_direct_add(). | |
| | | * | |
| | | * @section hashtable_algo Algorithm | |
| | | * | |
| | | * The Eina_Hash is implemented using an array of N "buckets", where each | |
| | | * bucket is a pointer to a structure that is the head of a <a | |
| | | * href="http://en.wikipedia.org/wiki/Red-black_tree">red-black tree</a>. T | |
| | | he | |
| | | * array can then be indexed by the [hash_of_element mod N]. The | |
| | | * hash_of_element is calculated using the hashing function, passed as | |
| | | * parameter to the @ref eina_hash_new function. N is the number of buckets | |
| | | * (array positions), and is calculated based on the buckets_power_size | |
| | | * (argument of @ref eina_hash_new too). The following picture ilustrates t | |
| | | he | |
| | | * basic idea: | |
| | | * | |
| | | * @htmlonly | |
| | | * <img src="01_hash-table.png" width="500" /> | |
| | | * @endhtmlonly | |
| | | * @image latex 01_hash-table.eps | |
| | | * | |
| | | * Adding an element to the hash table is made of: | |
| | | * @li calculating the hash for that key (using the specified hash function | |
| | | ); | |
| | | * @li calculate the array position [hash mod N]; | |
| | | * @li add the element to the rbtree on that position. | |
| | | * | |
| | | * The two first steps have constant time, proportional to the hash functio | |
| | | n | |
| | | * being used. Adding the key to the rbtree will be proportional on the num | |
| | | ber | |
| | | * of keys on that bucket. | |
| | | * | |
| | | * The average cost of lookup depends on the number of keys per | |
| | | * bucket (load factor) of the table, if the distribution of keys is | |
| | | * sufficiently uniform. | |
| | | * | |
| | | * @section hashtable_perf Performance | |
| | | * | |
| | | * As said before, the performance depends on the load factor. So trying to | |
| | | keep | |
| | | * the load factor as small as possible will improve the hash table perform | |
| | | ance. But | |
| | | * increasing the buckets_power_size will also increase the memory consumpt | |
| | | ion. | |
| | | * The default hash table creation functions already have a good number of | |
| | | * buckets, enough for most cases. Particularly for strings, if just a few | |
| | | keys | |
| | | * (less than 30) will be added to the hash table, @ref | |
| | | * eina_hash_string_small_new should be used, since it will reduce the memo | |
| | | ry | |
| | | * consumption for the buckets, and you still won't have many collisions. | |
| | | * However, @ref eina_hash_string_small_new still uses the same hash calcul | |
| | | ation | |
| | | * function that @ref eina_hash_string_superfast_new, which is more complex | |
| | | than | |
| | | * @ref eina_hash_string_djb2_new. The latter has a faster hash computation | |
| | | * function, but that will imply on a not so good distribution. But if just | |
| | | a | |
| | | * few keys are being added, this is not a problem, it will still have not | |
| | | many | |
| | | * collisions and be faster to calculate the hash than in a hash created wi | |
| | | th | |
| | | * @ref eina_hash_string_small_new and @ref eina_hash_string_superfast_new. | |
| | | * | |
| | | * A simple comparison between them would be: | |
| | | * | |
| | | * @li @c djb2 - faster hash function - 256 buckets (higher memory consumpt | |
| | | ion) | |
| | | * @li @c string_small - slower hash function but less collisions - 32 buck | |
| | | ets | |
| | | * (lower memory consumption) | |
| | | * @li @c string_superfast - slower hash function but less collisions - 256 | |
| | | buckets | |
| | | * (higher memory consumption) | |
| | | * | |
| | | * Basically for a very small number of keys (10 or less), @c djb2 should b | |
| | | e | |
| | | * used, or @c string_small if you have a restriction on memory usage. And | |
| | | for a | |
| | | * higher number of keys, @c string_superfast should be always preferred. | |
| | | * | |
| | | * If just stringshared keys are being added, use @ref | |
| | | * eina_hash_stringshared_new. If a lot of keys will be added to the hash t | |
| | | able | |
| | | * (e.g. more than 1000), then it's better to increase the buckets_power_si | |
| | | ze. | |
| | | * See @ref eina_hash_new for more details. | |
| | | * | |
| | | * When adding a new key to a hash table, use @ref eina_hash_add or @ref | |
| | | * eina_hash_direct_add (the latter if this key is already stored elsewhere | |
| | | ). If | |
| | | * the key may be already inside the hash table, instead of checking with | |
| | | * @ref eina_hash_find and then doing @ref eina_hash_add, one can use just | |
| | | @ref | |
| | | * eina_hash_set (this will change the data pointed by this key if it was | |
| | | * already present in the table). | |
| | | * | |
| | | * @section hashtable_tutorial Tutorial | |
| | | * | |
| | | * These examples show many Eina_Hash functions in action: | |
| | | * <ul> | |
| | | * <li> @ref hash_01_example_page | |
| | | * <li> @ref hash_02_example_page | |
| | | * <li> Different types of hash in use: | |
| | | * <ul> | |
| | | * <li> @ref eina_hash_03.c "string small" | |
| | | * <li> @ref eina_hash_04.c "string djb2" | |
| | | * <li> @ref eina_hash_05.c "int32" | |
| | | * <li> @ref eina_hash_06.c "int64" | |
| | | * <li> @ref eina_hash_07.c "pointer" | |
| | | * </ul> | |
| | | * <li> @ref eina_hash_08.c "Different add and delete functions" | |
| | | * </ul> | |
| | | */ | |
| | | | |
| | | /** | |
| * @addtogroup Eina_Data_Types_Group Data Types | | * @addtogroup Eina_Data_Types_Group Data Types | |
| * | | * | |
| * @{ | | * @{ | |
| */ | | */ | |
| | | | |
| /** | | /** | |
| * @addtogroup Eina_Containers_Group Containers | | * @addtogroup Eina_Containers_Group Containers | |
| * | | * | |
| * @{ | | * @{ | |
| */ | | */ | |
| | | | |
| skipping to change at line 67 | | skipping to change at line 306 | |
|---|
| }; | | }; | |
| | | | |
| typedef unsigned int (*Eina_Key_Length)(const void *key); | | typedef unsigned int (*Eina_Key_Length)(const void *key); | |
| #define EINA_KEY_LENGTH(Function) ((Eina_Key_Length)Function) | | #define EINA_KEY_LENGTH(Function) ((Eina_Key_Length)Function) | |
| typedef int (*Eina_Key_Cmp)(const void *key1, int key1_length, con
st void *key2, int key2_length); | | typedef int (*Eina_Key_Cmp)(const void *key1, int key1_length, con
st void *key2, int key2_length); | |
| #define EINA_KEY_CMP(Function) ((Eina_Key_Cmp)Function) | | #define EINA_KEY_CMP(Function) ((Eina_Key_Cmp)Function) | |
| typedef int (*Eina_Key_Hash)(const void *key, int key_length); | | typedef int (*Eina_Key_Hash)(const void *key, int key_length); | |
| #define EINA_KEY_HASH(Function) ((Eina_Key_Hash)Function) | | #define EINA_KEY_HASH(Function) ((Eina_Key_Hash)Function) | |
| typedef Eina_Bool (*Eina_Hash_Foreach)(const Eina_Hash *hash, const void
*key, void *data, void *fdata); | | typedef Eina_Bool (*Eina_Hash_Foreach)(const Eina_Hash *hash, const void
*key, void *data, void *fdata); | |
| | | | |
|
| | | /** | |
| | | * @brief Create a new hash table. | |
| | | * | |
| | | * @param key_length_cb The function called when getting the size of the ke | |
| | | y. | |
| | | * @param key_cmp_cb The function called when comparing the keys. | |
| | | * @param key_hash_cb The function called when getting the values. | |
| | | * @param data_free_cb The function called on each value when the hash tabl | |
| | | e is | |
| | | * freed, or when an item is deleted from it. @c NULL can be passed as | |
| | | * callback. | |
| | | * @param buckets_power_size The size of the buckets. | |
| | | * @return The new hash table. | |
| | | * | |
| | | * This function creates a new hash table using user-defined callbacks | |
| | | * to manage the hash table. On failure, @c NULL is returned and | |
| | | * #EINA_ERROR_OUT_OF_MEMORY is set. If @p key_cmp_cb or @p key_hash_cb | |
| | | * are @c NULL, @c NULL is returned. If @p buckets_power_size is | |
| | | * smaller or equal than 2, or if it is greater or equal than 17, | |
| | | * @c NULL is returned. | |
| | | * | |
| | | * The number of buckets created will be 2 ^ @p buckets_power_size. This me | |
| | | ans | |
| | | * that if @p buckets_power_size is 5, there will be created 32 buckets. fo | |
| | | r a | |
| | | * @p buckets_power_size of 8, there will be 256 buckets. | |
| | | * | |
| | | * Pre-defined functions are available to create a hash table. See | |
| | | * eina_hash_string_djb2_new(), eina_hash_string_superfast_new(), | |
| | | * eina_hash_string_small_new(), eina_hash_int32_new(), | |
| | | * eina_hash_int64_new(), eina_hash_pointer_new() and | |
| | | * eina_hash_stringshared_new(). | |
| | | */ | |
| EAPI Eina_Hash *eina_hash_new(Eina_Key_Length key_length_cb, | | EAPI Eina_Hash *eina_hash_new(Eina_Key_Length key_length_cb, | |
| Eina_Key_Cmp key_cmp_cb, | | Eina_Key_Cmp key_cmp_cb, | |
| Eina_Key_Hash key_hash_cb, | | Eina_Key_Hash key_hash_cb, | |
| Eina_Free_Cb data_free_cb, | | Eina_Free_Cb data_free_cb, | |
| int buckets_power_size) EINA_MALL
OC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(2, 3); | | int buckets_power_size) EINA_MALL
OC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(2, 3); | |
|
| | | | |
| | | /** | |
| | | * @brief Redefine the callback that clean the data of a hash | |
| | | * | |
| | | * @param hash The given hash table | |
| | | * @param data_free_cb The function called on each value when the hash | |
| | | * table is freed, or when an item is deleted from it. @c NULL can be passe | |
| | | d as | |
| | | * callback. | |
| | | * @since 1.1 | |
| | | * See @ref eina_hash_new. | |
| | | */ | |
| | | EAPI void eina_hash_free_cb_set(Eina_Hash *hash, Eina_Free_Cb data_free_cb) | |
| | | EINA_ARG_NONNULL(1); | |
| | | | |
| | | /** | |
| | | * @brief Create a new hash table using the djb2 algorithm. | |
| | | * | |
| | | * @param data_free_cb The function called on each value when the hash tabl | |
| | | e | |
| | | * is freed, or when an item is deleted from it. @c NULL can be passed as | |
| | | * callback. | |
| | | * @return The new hash table. | |
| | | * | |
| | | * This function creates a new hash table using the djb2 algorithm for | |
| | | * table management and strcmp() to compare the keys. Values can then | |
| | | * be looked up with pointers other than the original key pointer that | |
| | | * was used to add values. On failure, this function returns @c NULL. | |
| | | */ | |
| EAPI Eina_Hash *eina_hash_string_djb2_new(Eina_Free_Cb data_free_cb); | | EAPI Eina_Hash *eina_hash_string_djb2_new(Eina_Free_Cb data_free_cb); | |
|
| | | | |
| | | /** | |
| | | * @brief Create a new hash table for use with strings. | |
| | | * | |
| | | * @param data_free_cb The function called on each value when the hash tabl | |
| | | e | |
| | | * is freed, or when an item is deleted from it. @c NULL can be passed as | |
| | | * callback. | |
| | | * @return The new hash table. | |
| | | * | |
| | | * This function creates a new hash table using the superfast algorithm | |
| | | * for table management and strcmp() to compare the keys. Values can | |
| | | * then be looked up with pointers other than the original key pointer | |
| | | * that was used to add values. On failure, this function returns | |
| | | * @c NULL. | |
| | | */ | |
| EAPI Eina_Hash *eina_hash_string_superfast_new(Eina_Free_Cb data_free_cb); | | EAPI Eina_Hash *eina_hash_string_superfast_new(Eina_Free_Cb data_free_cb); | |
|
| | | | |
| | | /** | |
| | | * @brief Create a new hash table for use with strings with small bucket si | |
| | | ze. | |
| | | * | |
| | | * @param data_free_cb The function called on each value when the hash tab | |
| | | le | |
| | | * is freed, or when an item is deleted from it. @c NULL can be passed as | |
| | | * callback. | |
| | | * @return The new hash table. | |
| | | * | |
| | | * This function creates a new hash table using the superfast algorithm | |
| | | * for table management and strcmp() to compare the keys, but with a | |
| | | * smaller bucket size (compared to eina_hash_string_superfast_new()) | |
| | | * which will minimize the memory used by the returned hash | |
| | | * table. Values can then be looked up with pointers other than the | |
| | | * original key pointer that was used to add values. On failure, this | |
| | | * function returns @c NULL. | |
| | | */ | |
| EAPI Eina_Hash *eina_hash_string_small_new(Eina_Free_Cb data_free_cb); | | EAPI Eina_Hash *eina_hash_string_small_new(Eina_Free_Cb data_free_cb); | |
|
| | | | |
| | | /** | |
| | | * @brief Create a new hash table for use with 32bit integers. | |
| | | * | |
| | | * @param data_free_cb The function called on each value when the hash tab | |
| | | le | |
| | | * is freed, or when an item is deleted from it. @c NULL can be passed as | |
| | | * callback. | |
| | | * @return The new hash table. | |
| | | * | |
| | | * This function creates a new hash table where keys are 32bit integers. | |
| | | * When adding or looking up in the hash table, pointers to 32bit integers | |
| | | * must be passed. They can be addresses on the stack if you let the | |
| | | * eina_hash copy the key. Values can then | |
| | | * be looked up with pointers other than the original key pointer that was | |
| | | * used to add values. This method is not suitable to match string keys as | |
| | | * it would only match the first character. | |
| | | * On failure, this function returns @c NULL. | |
| | | */ | |
| EAPI Eina_Hash *eina_hash_int32_new(Eina_Free_Cb data_free_cb); | | EAPI Eina_Hash *eina_hash_int32_new(Eina_Free_Cb data_free_cb); | |
|
| | | | |
| | | /** | |
| | | * @brief Create a new hash table for use with 64bit integers. | |
| | | * | |
| | | * @param data_free_cb The function called on each value when the hash tab | |
| | | le | |
| | | * is freed, or when an item is deleted from it. @c NULL can be passed as | |
| | | * callback. | |
| | | * @return The new hash table. | |
| | | * | |
| | | * This function creates a new hash table where keys are 64bit integers. | |
| | | * When adding or looking up in the hash table, pointers to 64bit integers | |
| | | * must be passed. They can be addresses on the stack. Values can then | |
| | | * be looked up with pointers other than the original key pointer that was | |
| | | * used to add values. This method is not suitable to match string keys as | |
| | | * it would only match the first character. | |
| | | * On failure, this function returns @c NULL. | |
| | | */ | |
| EAPI Eina_Hash *eina_hash_int64_new(Eina_Free_Cb data_free_cb); | | EAPI Eina_Hash *eina_hash_int64_new(Eina_Free_Cb data_free_cb); | |
|
| | | | |
| | | /** | |
| | | * @brief Create a new hash table for use with pointers. | |
| | | * | |
| | | * @param data_free_cb The function called on each value when the hash tab | |
| | | le | |
| | | * is freed, or when an item is deleted from it. @c NULL can be passed as | |
| | | * callback. | |
| | | * @return The new hash table. | |
| | | * | |
| | | * This function creates a new hash table using the int64/int32 algorithm f | |
| | | or | |
| | | * table management and dereferenced pointers to compare the | |
| | | * keys. Values can then be looked up with pointers other than the | |
| | | * original key pointer that was used to add values. This method may | |
| | | * appear to be able to match string keys, actually it only matches | |
| | | * the first character. On failure, this function returns @c NULL. | |
| | | */ | |
| EAPI Eina_Hash *eina_hash_pointer_new(Eina_Free_Cb data_free_cb); | | EAPI Eina_Hash *eina_hash_pointer_new(Eina_Free_Cb data_free_cb); | |
|
| | | | |
| | | /** | |
| | | * @brief Create a new hash table optimized for stringshared values. | |
| | | * | |
| | | * @param data_free_cb The function called on each value when the hash tab | |
| | | le | |
| | | * is freed, or when an item is deleted from it. @c NULL can be passed as | |
| | | * callback. | |
| | | * @return The new hash table. | |
| | | * | |
| | | * This function creates a new hash table optimized for stringshared | |
| | | * values. Values CAN NOT be looked up with pointers not | |
| | | * equal to the original key pointer that was used to add a value. On failu | |
| | | re, | |
| | | * this function returns @c NULL. | |
| | | * | |
| | | * Excerpt of code that will NOT work with this type of hash: | |
| | | * | |
| | | * @code | |
| | | * extern Eina_Hash *hash; | |
| | | * extern const char *value; | |
| | | * const char *a = eina_stringshare_add("key"); | |
| | | * | |
| | | * eina_hash_add(hash, a, value); | |
| | | * eina_hash_find(hash, "key") | |
| | | * @endcode | |
| | | */ | |
| EAPI Eina_Hash *eina_hash_stringshared_new(Eina_Free_Cb data_free_cb); | | EAPI Eina_Hash *eina_hash_stringshared_new(Eina_Free_Cb data_free_cb); | |
|
| | | | |
| | | /** | |
| | | * @brief Add an entry to the given hash table. | |
| | | * | |
| | | * @param hash The given hash table. Cannot be @c NULL. | |
| | | * @param key A unique key. Cannot be @c NULL. | |
| | | * @param data Data to associate with the string given by @p key. Cannot be | |
| | | @c | |
| | | * NULL. | |
| | | * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. | |
| | | * | |
| | | * This function adds @p key to @p hash. @p key is | |
| | | * expected to be unique within the hash table. Key uniqueness varies | |
| | | * depending on the type of @p hash: a stringshared @ref Eina_Hash | |
| | | * need to have unique pointers (which implies unique strings). | |
| | | * All other string hash types require the strings | |
| | | * themselves to be unique. Pointer, int32 and int64 hashes need to have th | |
| | | ese | |
| | | * values as unique. Failure to use sufficient uniqueness will | |
| | | * result in unexpected results when inserting data pointers accessed | |
| | | * with eina_hash_find(), and removed with eina_hash_del(). Key | |
| | | * strings are case sensitive. If an error occurs, eina_error_get() | |
| | | * should be used to determine if an allocation error occurred during | |
| | | * this function. This function returns #EINA_FALSE if an error | |
| | | * occurred, #EINA_TRUE otherwise. | |
| | | */ | |
| EAPI Eina_Bool eina_hash_add(Eina_Hash *hash, | | EAPI Eina_Bool eina_hash_add(Eina_Hash *hash, | |
| const void *key, | | const void *key, | |
| const void *data) EINA_ARG_NONNULL(1, 2, 3); | | const void *data) EINA_ARG_NONNULL(1, 2, 3); | |
|
| | | | |
| | | /** | |
| | | * @brief Add an entry to the given hash table without duplicating the stri | |
| | | ng | |
| | | * key. | |
| | | * | |
| | | * @param hash The given hash table. Cannot be @c NULL. | |
| | | * @param key A unique key. Cannot be @c NULL. | |
| | | * @param data Data to associate with the string given by @p key. Cannot be | |
| | | @c | |
| | | * NULL | |
| | | * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. | |
| | | * | |
| | | * This function adds @p key to @p hash. @p key is | |
| | | * expected to be unique within the hash table. Key uniqueness varies | |
| | | * depending on the type of @p hash: a stringshared @ref Eina_Hash | |
| | | * need have unique pointers (which implies unique strings). | |
| | | * All other string hash types require the strings | |
| | | * themselves to be unique. Pointer, int32 and int64 hashes need to have th | |
| | | ese | |
| | | * values as unique. Failure to use sufficient uniqueness will | |
| | | * result in unexpected results when inserting data pointers accessed | |
| | | * with eina_hash_find(), and removed with eina_hash_del(). This | |
| | | * function does not make a copy of @p key, so it must be a string | |
| | | * constant or stored elsewhere ( in the object being added). Key | |
| | | * strings are case sensitive. If an error occurs, eina_error_get() | |
| | | * should be used to determine if an allocation error occurred during | |
| | | * this function. This function returns #EINA_FALSE if an error | |
| | | * occurred, #EINA_TRUE otherwise. | |
| | | */ | |
| EAPI Eina_Bool eina_hash_direct_add(Eina_Hash *hash, | | EAPI Eina_Bool eina_hash_direct_add(Eina_Hash *hash, | |
| const void *key, | | const void *key, | |
| const void *data) EINA_ARG_NONNULL(1, 2
, 3); | | const void *data) EINA_ARG_NONNULL(1, 2
, 3); | |
|
| | | | |
| | | /** | |
| | | * @brief Remove the entry identified by a key or a data from the given | |
| | | * hash table. | |
| | | * | |
| | | * @param hash The given hash table. | |
| | | * @param key The key. | |
| | | * @param data The data pointer to remove if the key is @c NULL. | |
| | | * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. | |
| | | * | |
| | | * This function removes the entry identified by @p key or @p data | |
| | | * from @p hash. If a free function was given to the | |
| | | * callback on creation, it will be called for the data being | |
| | | * deleted. If @p hash is @c NULL, the functions returns immediately | |
| | | * #EINA_FALSE. If @p key is @c NULL, then @p data is used to find the a | |
| | | * match to remove, otherwise @p key is used and @p data is not | |
| | | * required and can be @c NULL. This function returns #EINA_FALSE if | |
| | | * an error occurred, #EINA_TRUE otherwise. | |
| | | * | |
| | | * @note if you know you already have the key, use | |
| | | * eina_hash_del_by_key() or eina_hash_del_by_key_hash(). If you | |
| | | * know you don't have the key, use eina_hash_del_by_data() | |
| | | * directly. | |
| | | */ | |
| EAPI Eina_Bool eina_hash_del(Eina_Hash *hash, | | EAPI Eina_Bool eina_hash_del(Eina_Hash *hash, | |
| const void *key, | | const void *key, | |
| const void *data) EINA_ARG_NONNULL(1); | | const void *data) EINA_ARG_NONNULL(1); | |
|
| | | | |
| | | /** | |
| | | * @brief Retrieve a specific entry in the given hash table. | |
| | | * | |
| | | * @param hash The given hash table. | |
| | | * @param key The key of the entry to find. | |
| | | * @return The data pointer for the stored entry on success, @c NULL | |
| | | * otherwise. | |
| | | * | |
| | | * This function retrieves the entry associated to @p key in | |
| | | * @p hash. If @p hash is @c NULL, this function returns immediately | |
| | | * @c NULL. This function returns the data pointer on success, @c NULL | |
| | | * otherwise. | |
| | | */ | |
| EAPI void *eina_hash_find(const Eina_Hash *hash, | | EAPI void *eina_hash_find(const Eina_Hash *hash, | |
|
| const void *key) EINA_ARG_NONNULL(2); | | const void *key) EINA_ARG_NONNULL(1, 2); | |
| | | | |
| | | /** | |
| | | * @brief Modify the entry pointer at the specified key and return the old | |
| | | * entry. | |
| | | * @param hash The given hash table. | |
| | | * @param key The key of the entry to modify. | |
| | | * @param data The data to replace the old entry. | |
| | | * @return The data pointer for the old stored entry on success, or | |
| | | * @c NULL otherwise. | |
| | | * | |
| | | * This function modifies the data of @p key with @p data in @p | |
| | | * hash. If no entry is found, nothing is added to @p hash. On success | |
| | | * this function returns the old entry, otherwise it returns @c NULL. | |
| | | */ | |
| EAPI void *eina_hash_modify(Eina_Hash *hash, | | EAPI void *eina_hash_modify(Eina_Hash *hash, | |
| const void *key, | | const void *key, | |
| const void *data) EINA_ARG_NONNULL(1, 2, 3); | | const void *data) EINA_ARG_NONNULL(1, 2, 3); | |
|
| | | | |
| | | /** | |
| | | * @brief Modify the entry pointer at the specified key and return the | |
| | | * old entry or add the entry if not found. | |
| | | * | |
| | | * @param hash The given hash table. | |
| | | * @param key The key of the entry to modify. | |
| | | * @param data The data to replace the old entry | |
| | | * @return The data pointer for the old stored entry, or @c NULL | |
| | | * otherwise. | |
| | | * | |
| | | * This function modifies the data of @p key with @p data in @p | |
| | | * hash. If no entry is found, @p data is added to @p hash with the | |
| | | * key @p key. On success this function returns the old entry, | |
| | | * otherwise it returns @c NULL. To check for errors, use | |
| | | * eina_error_get(). | |
| | | */ | |
| EAPI void *eina_hash_set(Eina_Hash *hash, | | EAPI void *eina_hash_set(Eina_Hash *hash, | |
| const void *key, | | const void *key, | |
|
| const void *data) EINA_ARG_NONNULL(1, 2, 3); | | const void *data) EINA_ARG_NONNULL(1, 2); | |
| | | | |
| | | /** | |
| | | * @brief Change the key associated with a data without triggering the | |
| | | * free callback. | |
| | | * | |
| | | * @param hash The given hash table. | |
| | | * @param old_key The current key associated with the data | |
| | | * @param new_key The new key to associate data with | |
| | | * @return EINA_FALSE in any case but success, EINA_TRUE on success. | |
| | | * | |
| | | * This function allows for the move of data from one key to another, | |
| | | * but does not call the Eina_Free_Cb associated with the hash table | |
| | | * when destroying the old key. | |
| | | */ | |
| EAPI Eina_Bool eina_hash_move(Eina_Hash *hash, | | EAPI Eina_Bool eina_hash_move(Eina_Hash *hash, | |
| const void *old_key, | | const void *old_key, | |
| const void *new_key) EINA_ARG_NONNULL(1, 2, 3
); | | const void *new_key) EINA_ARG_NONNULL(1, 2, 3
); | |
|
| | | | |
| | | /** | |
| | | * Free the given hash table resources. | |
| | | * | |
| | | * @param hash The hash table to be freed. | |
| | | * | |
| | | * This function frees up all the memory allocated to storing @p hash, | |
| | | * and call the free callback if it has been passed to the hash table | |
| | | * at creation time. If no free callback has been passed, any entries | |
| | | * in the table that the program has no more pointers for elsewhere | |
| | | * may now be lost, so this should only be called if the program has | |
| | | * already freed any allocated data in the hash table or has the | |
| | | * pointers for data in the table stored elsewhere as well. If @p hash | |
| | | * is @c NULL, the function returns immediately. | |
| | | * | |
| | | * Example: | |
| | | * @code | |
| | | * extern Eina_Hash *hash; | |
| | | * | |
| | | * eina_hash_free(hash); | |
| | | * hash = NULL; | |
| | | * @endcode | |
| | | */ | |
| EAPI void eina_hash_free(Eina_Hash *hash) EINA_ARG_NONNULL(1); | | EAPI void eina_hash_free(Eina_Hash *hash) EINA_ARG_NONNULL(1); | |
|
| | | | |
| | | /** | |
| | | * Free the given hash table buckets resources. | |
| | | * | |
| | | * @param hash The hash table whose buckets have to be freed. | |
| | | * | |
| | | * This function frees up all the memory allocated to storing the | |
| | | * buckets of @p hash, and calls the free callback on all hash table | |
| | | * buckets if it has been passed to the hash table at creation time, | |
| | | * then frees the buckets. If no free callback has been passed, no | |
| | | * buckets value will be freed. If @p hash is @c NULL, the function | |
| | | * returns immediately. | |
| | | */ | |
| EAPI void eina_hash_free_buckets(Eina_Hash *hash) EINA_ARG_NONNULL(1); | | EAPI void eina_hash_free_buckets(Eina_Hash *hash) EINA_ARG_NONNULL(1); | |
|
| | | | |
| | | /** | |
| | | * @brief Returns the number of entries in the given hash table. | |
| | | * | |
| | | * @param hash The given hash table. | |
| | | * @return The number of entries in the hash table. | |
| | | * | |
| | | * This function returns the number of entries in @p hash, or 0 on | |
| | | * error. If @p hash is @c NULL, 0 is returned. | |
| | | */ | |
| EAPI int eina_hash_population(const Eina_Hash *hash) EINA_ARG_NONNULL
(1); | | EAPI int eina_hash_population(const Eina_Hash *hash) EINA_ARG_NONNULL
(1); | |
|
| | | | |
| | | /** | |
| | | * @brief Add an entry to the given hash table. | |
| | | * | |
| | | * @param hash The given hash table. Cannot be @c NULL. | |
| | | * @param key A unique key. Cannot be @c NULL. | |
| | | * @param key_length The length of the key. | |
| | | * @param key_hash The hash that will always match key. | |
| | | * @param data The data to associate with the string given by the key. Cann | |
| | | ot be | |
| | | * @c NULL. | |
| | | * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. | |
| | | * | |
| | | * This function adds @p key to @p hash. @p hash, @p key and @p data | |
| | | * cannot be @c NULL, in that case #EINA_FALSE is returned. @p key is | |
| | | * expected to be a unique within the hash table. Otherwise, | |
| | | * one cannot be sure which inserted data pointer will be accessed | |
| | | * with @ref eina_hash_find, and removed with @ref eina_hash_del. Do | |
| | | * not forget to count '\\0' for string when setting the value of | |
| | | * @p key_length. @p key_hash is expected to always match | |
| | | * @p key. Otherwise, one cannot be sure to find it again with @ref | |
| | | * eina_hash_find_by_hash. Key strings are case sensitive. If an error | |
| | | * occurs, eina_error_get() should be used to determine if an | |
| | | * allocation error occurred during this function. This function | |
| | | * returns #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. | |
| | | * | |
| | | * @see eina_hash_add() | |
| | | */ | |
| EAPI Eina_Bool eina_hash_add_by_hash(Eina_Hash *hash, | | EAPI Eina_Bool eina_hash_add_by_hash(Eina_Hash *hash, | |
| const void *key, | | const void *key, | |
| int key_length, | | int key_length, | |
| int key_hash, | | int key_hash, | |
| const void *data) EINA_ARG_NONNULL(1,
2, 5); | | const void *data) EINA_ARG_NONNULL(1,
2, 5); | |
|
| | | | |
| | | /** | |
| | | * @brief Add an entry to the given hash table and do not duplicate the str | |
| | | ing | |
| | | * key. | |
| | | * | |
| | | * @param hash The given hash table. Cannot be @c NULL. | |
| | | * @param key A unique key. Cannot be @c NULL. | |
| | | * @param key_length Should be the length of @p key (don't forget to count | |
| | | * '\\0' for string). | |
| | | * @param key_hash The hash that will always match key. | |
| | | * @param data Data to associate with the string given by @p key. Cannot be | |
| | | @c | |
| | | * NULL. | |
| | | * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. | |
| | | * | |
| | | * This function adds @p key to @p hash. @p hash, @p key and @p data | |
| | | * can be @c NULL, in that case #EINA_FALSE is returned. @p key is | |
| | | * expected to be unique within the hash table. Otherwise, | |
| | | * one cannot be sure which inserted data pointer will be accessed | |
| | | * with @ref eina_hash_find, and removed with @ref eina_hash_del. This | |
| | | * function does not make a copy of @p key so it must be a string | |
| | | * constant or stored elsewhere (in the object being added). Do | |
| | | * not forget to count '\\0' for string when setting the value of | |
| | | * @p key_length. @p key_hash is expected to always match | |
| | | * @p key. Otherwise, one cannot be sure to find it again with @ref | |
| | | * eina_hash_find_by_hash. Key strings are case sensitive. If an error | |
| | | * occurs, eina_error_get() should be used to determine if an | |
| | | * allocation error occurred during this function. This function | |
| | | * returns #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. | |
| | | * | |
| | | * @see eina_hash_direct_add() | |
| | | */ | |
| EAPI Eina_Bool eina_hash_direct_add_by_hash(Eina_Hash *hash, | | EAPI Eina_Bool eina_hash_direct_add_by_hash(Eina_Hash *hash, | |
| const void *key, | | const void *key, | |
| int key_length, | | int key_length, | |
| int key_hash, | | int key_hash, | |
| const void *data) EINA_ARG_NONN
ULL(1, 2, 5); | | const void *data) EINA_ARG_NONN
ULL(1, 2, 5); | |
|
| | | | |
| | | /** | |
| | | * @brief Remove the entry identified by a key and a key hash from the give | |
| | | n | |
| | | * hash table. | |
| | | * | |
| | | * @param hash The given hash table. Cannot be @c NULL. | |
| | | * @param key The key. Cannot be @c NULL. | |
| | | * @param key_length The length of the key. | |
| | | * @param key_hash The hash that always match the key. | |
| | | * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. | |
| | | * | |
| | | * This function removes the entry identified by @p key and | |
| | | * @p key_hash from @p hash. If a free function was given to the | |
| | | * callback on creation, it will be called for the data being | |
| | | * deleted. Do not forget to count '\\0' for string when setting the | |
| | | * value of @p key_length. If @p hash or @p key are @c NULL, the | |
| | | * functions returns immediately #EINA_FALSE. This function returns | |
| | | * #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. | |
| | | * | |
| | | * @note if you don't have the key_hash, use eina_hash_del_by_key() instead | |
| | | . | |
| | | * @note if you don't have the key, use eina_hash_del_by_data() instead. | |
| | | */ | |
| EAPI Eina_Bool eina_hash_del_by_key_hash(Eina_Hash *hash, | | EAPI Eina_Bool eina_hash_del_by_key_hash(Eina_Hash *hash, | |
| const void *key, | | const void *key, | |
| int key_length, | | int key_length, | |
| int key_hash) EINA_ARG_NON
NULL(1, 2); | | int key_hash) EINA_ARG_NON
NULL(1, 2); | |
|
| | | | |
| | | /** | |
| | | * @brief Remove the entry identified by a key from the given hash table. | |
| | | * | |
| | | * This version will calculate key length and hash by using functions | |
| | | * provided to hash creation function. | |
| | | * | |
| | | * @param hash The given hash table. Cannot be @c NULL. | |
| | | * @param key The key. Cannot be @c NULL. | |
| | | * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. | |
| | | * | |
| | | * This function removes the entry identified by @p key from @p | |
| | | * hash. The key length and hash will be calculated automatically by | |
| | | * using functiond provided to has creation function. If a free | |
| | | * function was given to the callback on creation, it will be called | |
| | | * for the data being deleted. If @p hash or @p key are @c NULL, the | |
| | | * functions returns immediately #EINA_FALSE. This function returns | |
| | | * #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. | |
| | | * | |
| | | * @note if you already have the key_hash, use eina_hash_del_by_key_hash() | |
| | | * instead. | |
| | | * @note if you don't have the key, use eina_hash_del_by_data() instead. | |
| | | */ | |
| EAPI Eina_Bool eina_hash_del_by_key(Eina_Hash *hash, | | EAPI Eina_Bool eina_hash_del_by_key(Eina_Hash *hash, | |
| const void *key) EINA_ARG_NONNULL(1, 2)
; | | const void *key) EINA_ARG_NONNULL(1, 2)
; | |
|
| | | | |
| | | /** | |
| | | * @brief Remove the entry identified by a data from the given hash table. | |
| | | * | |
| | | * This version is slow since there is no quick access to nodes based on da | |
| | | ta. | |
| | | * | |
| | | * @param hash The given hash table. Cannot be @c NULL. | |
| | | * @param data The data value to search and remove. Cannot be @c NULL. | |
| | | * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. | |
| | | * thing goes fine. | |
| | | * | |
| | | * This function removes the entry identified by @p data from @p | |
| | | * hash. If a free function was given to the callback on creation, it | |
| | | * will be called for the data being deleted. If @p hash or @p data | |
| | | * are @c NULL, the functions returns immediately #EINA_FALSE. This | |
| | | * function returns #EINA_FALSE if an error occurred, #EINA_TRUE | |
| | | * otherwise. | |
| | | * | |
| | | * @note if you already have the key, use eina_hash_del_by_key() or | |
| | | * eina_hash_del_by_key_hash() instead. | |
| | | */ | |
| EAPI Eina_Bool eina_hash_del_by_data(Eina_Hash *hash, | | EAPI Eina_Bool eina_hash_del_by_data(Eina_Hash *hash, | |
| const void *data) EINA_ARG_NONNULL(1,
2); | | const void *data) EINA_ARG_NONNULL(1,
2); | |
|
| | | | |
| | | /** | |
| | | * @brief Remove the entry identified by a key and a key hash or a | |
| | | * data from the given hash table. | |
| | | * | |
| | | * If @p key is @c NULL, then @p data is used to find a match to | |
| | | * remove. | |
| | | * | |
| | | * @param hash The given hash table. Cannot be @c NULL. | |
| | | * @param key The key. | |
| | | * @param key_length The length of the key. | |
| | | * @param key_hash The hash that always match the key. | |
| | | * @param data The data pointer to remove if the key is @c NULL. | |
| | | * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. | |
| | | * | |
| | | * This function removes the entry identified by @p key and | |
| | | * @p key_hash, or @p data, from @p hash. If a free function was given to | |
| | | * the callback on creation, it will be called for the data being | |
| | | * deleted. If @p hash is @c NULL, the functions returns immediately | |
| | | * #EINA_FALSE. If @p key is @c NULL, then @p key_length and @p key_hash | |
| | | * are ignored and @p data is used to find a match to remove, | |
| | | * otherwise @p key and @p key_hash are used and @p data is not | |
| | | * required and can be @c NULL. Do not forget to count '\\0' for | |
| | | * string when setting the value of @p key_length. This function | |
| | | * returns #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. | |
| | | * | |
| | | * @note if you know you already have the key, use eina_hash_del_by_key_has | |
| | | h(), | |
| | | * if you know you don't have the key, use eina_hash_del_by_data() | |
| | | * directly. | |
| | | */ | |
| EAPI Eina_Bool eina_hash_del_by_hash(Eina_Hash *hash, | | EAPI Eina_Bool eina_hash_del_by_hash(Eina_Hash *hash, | |
| const void *key, | | const void *key, | |
| int key_length, | | int key_length, | |
| int key_hash, | | int key_hash, | |
| const void *data) EINA_ARG_NONNULL(1); | | const void *data) EINA_ARG_NONNULL(1); | |
|
| | | | |
| | | /** | |
| | | * @brief Retrieve a specific entry in the given hash table. | |
| | | * | |
| | | * @param hash The given hash table. Cannot be @c NULL. | |
| | | * @param key The key of the entry to find. | |
| | | * @param key_length The length of the key. | |
| | | * @param key_hash The hash that always match the key | |
| | | * @return The data pointer for the stored entry on success, @c NULL | |
| | | * otherwise. | |
| | | * | |
| | | * This function retrieves the entry associated to @p key of length | |
| | | * @p key_length in @p hash. @p key_hash is the hash that always match | |
| | | * @p key. It is ignored if @p key is @c NULL. Do not forget to count | |
| | | * '\\0' for string when setting the value of @p key_length. If | |
| | | * @p hash is @c NULL, this function returns immediately @c NULL. This | |
| | | * function returns the data pointer on success, @c NULL otherwise. | |
| | | */ | |
| EAPI void *eina_hash_find_by_hash(const Eina_Hash *hash, | | EAPI void *eina_hash_find_by_hash(const Eina_Hash *hash, | |
| const void *key, | | const void *key, | |
| int key_length, | | int key_length, | |
| int key_hash) EINA_ARG_NONNU
LL(1, 2); | | int key_hash) EINA_ARG_NONNU
LL(1, 2); | |
|
| | | | |
| | | /** | |
| | | * @brief Modify the entry pointer at the specified key and returns | |
| | | * the old entry. | |
| | | * | |
| | | * @param hash The given hash table. | |
| | | * @param key The key of the entry to modify. | |
| | | * @param key_length Should be the length of @p key (don't forget to count | |
| | | * '\\0' for string). | |
| | | * @param key_hash The hash that always match the key. Ignored if @p key is | |
| | | * @c NULL. | |
| | | * @param data The data to replace the old entry, if it exists. | |
| | | * @return The data pointer for the old stored entry, or @c NULL if not | |
| | | * found. If an existing entry is not found, nothing is added to t | |
| | | he | |
| | | * hash. | |
| | | */ | |
| EAPI void *eina_hash_modify_by_hash(Eina_Hash *hash, | | EAPI void *eina_hash_modify_by_hash(Eina_Hash *hash, | |
| const void *key, | | const void *key, | |
| int key_length, | | int key_length, | |
| int key_hash, | | int key_hash, | |
| const void *data) EINA_ARG_NONNULL(1, 2
, 5); | | const void *data) EINA_ARG_NONNULL(1, 2
, 5); | |
|
| | | | |
| | | /** | |
| | | * @brief Returned a new iterator associated to hash keys. | |
| | | * | |
| | | * @param hash The hash. | |
| | | * @return A new iterator. | |
| | | * | |
| | | * This function returns a newly allocated iterator associated to @p | |
| | | * hash. If @p hash is not populated, this function still returns a | |
| | | * valid iterator that will always return false on | |
| | | * eina_iterator_next(), thus keeping API sane. | |
| | | * | |
| | | * If the memory can not be allocated, NULL is returned and | |
| | | * #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is | |
| | | * returned. | |
| | | * | |
| | | * @warning if the hash structure changes then the iterator becomes | |
| | | * invalid! That is, if you add or remove items this iterator | |
| | | * behavior is undefined and your program may crash! | |
| | | */ | |
| EAPI Eina_Iterator *eina_hash_iterator_key_new(const Eina_Hash *hash) EINA_
MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; | | EAPI Eina_Iterator *eina_hash_iterator_key_new(const Eina_Hash *hash) EINA_
MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; | |
|
| | | | |
| | | /** | |
| | | * @brief Returned a new iterator associated to hash data. | |
| | | * | |
| | | * @param hash The hash. | |
| | | * @return A new iterator. | |
| | | * | |
| | | * This function returns a newly allocated iterator associated to | |
| | | * @p hash. If @p hash is not populated, this function still returns a | |
| | | * valid iterator that will always return false on | |
| | | * eina_iterator_next(), thus keeping API sane. | |
| | | * | |
| | | * If the memory can not be allocated, @c NULL is returned and | |
| | | * #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is | |
| | | * returned. | |
| | | * | |
| | | * @warning if the hash structure changes then the iterator becomes | |
| | | * invalid. That is, if you add or remove items this iterator behavior | |
| | | * is undefined and your program may crash. | |
| | | */ | |
| EAPI Eina_Iterator *eina_hash_iterator_data_new(const Eina_Hash *hash) EINA
_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; | | EAPI Eina_Iterator *eina_hash_iterator_data_new(const Eina_Hash *hash) EINA
_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; | |
|
| | | | |
| | | /** | |
| | | * @brief Returned a new iterator associated to hash keys and data. | |
| | | * | |
| | | * @param hash The hash. | |
| | | * @return A new iterator. | |
| | | * | |
| | | * This function returns a newly allocated iterator associated to @p | |
| | | * hash. If @p hash is not populated, this function still returns a | |
| | | * valid iterator that will always return false on | |
| | | * eina_iterator_next(), thus keeping API sane. | |
| | | * | |
| | | * If the memory can not be allocated, NULL is returned and | |
| | | * #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is | |
| | | * returned. | |
| | | * | |
| | | * @note iterator data will provide values as Eina_Hash_Tuple that should n | |
| | | ot | |
| | | * be modified! | |
| | | * | |
| | | * @warning if the hash structure changes then the iterator becomes | |
| | | * invalid! That is, if you add or remove items this iterator | |
| | | * behavior is undefined and your program may crash! | |
| | | */ | |
| EAPI Eina_Iterator *eina_hash_iterator_tuple_new(const Eina_Hash *hash) EIN
A_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; | | EAPI Eina_Iterator *eina_hash_iterator_tuple_new(const Eina_Hash *hash) EIN
A_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; | |
|
| | | | |
| | | /** | |
| | | * @brief Call a function on every member stored in the hash table | |
| | | * | |
| | | * @param hash The hash table whose members will be walked | |
| | | * @param func The function to call on each parameter | |
| | | * @param fdata The data pointer to pass to the function being called | |
| | | * | |
| | | * This function goes through every entry in the hash table @p hash and cal | |
| | | ls | |
| | | * the function @p func on each member. The function should @b not modify t | |
| | | he | |
| | | * hash table contents if it returns 1. @b If the hash table contents are | |
| | | * modified by this function or the function wishes to stop processing it m | |
| | | ust | |
| | | * return 0, otherwise return 1 to keep processing. | |
| | | * | |
| | | * Example: | |
| | | * @code | |
| | | * extern Eina_Hash *hash; | |
| | | * | |
| | | * Eina_Bool hash_fn(const Eina_Hash *hash, const void *key, | |
| | | * void *data, void *fdata) | |
| | | * { | |
| | | * printf("Func data: %s, Hash entry: %s / %p\n", | |
| | | * fdata, (const char *)key, data); | |
| | | * return 1; | |
| | | * } | |
| | | * | |
| | | * int main(int argc, char **argv) | |
| | | * { | |
| | | * char *hash_fn_data; | |
| | | * | |
| | | * hash_fn_data = strdup("Hello World"); | |
| | | * eina_hash_foreach(hash, hash_fn, hash_fn_data); | |
| | | * free(hash_fn_data); | |
| | | * } | |
| | | * @endcode | |
| | | */ | |
| EAPI void eina_hash_foreach(const Eina_Hash *hash, | | EAPI void eina_hash_foreach(const Eina_Hash *hash, | |
| Eina_Hash_Foreach cb, | | Eina_Hash_Foreach cb, | |
| const void *fdata) EINA_ARG_NON
NULL(1, 2); | | const void *fdata) EINA_ARG_NON
NULL(1, 2); | |
| /* Paul Hsieh (http://www.azillionmonkeys.com/qed/hash.html) hash function
used by WebCore (http://webkit.org/blog/8/hashtables-part-2/) */ | | /* Paul Hsieh (http://www.azillionmonkeys.com/qed/hash.html) hash function
used by WebCore (http://webkit.org/blog/8/hashtables-part-2/) */ | |
| EAPI int eina_hash_superfast(const char *key, | | EAPI int eina_hash_superfast(const char *key, | |
| int len) EINA_ARG_NONNULL(1); | | int len) EINA_ARG_NONNULL(1); | |
| /* Hash function first reported by dan bernstein many years ago in comp.lan
g.c */ | | /* Hash function first reported by dan bernstein many years ago in comp.lan
g.c */ | |
| static inline int eina_hash_djb2(const char *key, | | static inline int eina_hash_djb2(const char *key, | |
| int len) EINA_ARG_NONNULL(1); | | int len) EINA_ARG_NONNULL(1); | |
| static inline int eina_hash_djb2_len(const char *key, | | static inline int eina_hash_djb2_len(const char *key, | |
| int *plen) EINA_ARG_NONNULL(1,
2); | | int *plen) EINA_ARG_NONNULL(1,
2); | |
| /* Hash function from http://www.concentric.net/~Ttwang/tech/inthash.htm */ | | /* Hash function from http://www.concentric.net/~Ttwang/tech/inthash.htm */ | |
| static inline int eina_hash_int32(const unsigned int *pkey, | | static inline int eina_hash_int32(const unsigned int *pkey, | |
| int len) EINA_ARG_NONNULL
(1); | | int len) EINA_ARG_NONNULL
(1); | |
| static inline int eina_hash_int64(const unsigned long int *pkey, | | static inline int eina_hash_int64(const unsigned long int *pkey, | |
| int len) EINA_ARG_NO
NNULL(1); | | int len) EINA_ARG_NO
NNULL(1); | |
|
| | | /* http://sites.google.com/site/murmurhash/ */ | |
| | | static inline int eina_hash_murmur3(const char *key, | |
| | | int len) EINA_ARG_NONNULL(1); | |
| #include "eina_inline_hash.x" | | #include "eina_inline_hash.x" | |
| | | | |
| /** | | /** | |
| * @} | | * @} | |
| */ | | */ | |
| | | | |
| /** | | /** | |
| * @} | | * @} | |
| */ | | */ | |
| | | | |
| | | | |
| End of changes. 32 change blocks. |
|---|
| 3 lines changed or deleted | | 957 lines changed or added | |
|---|
|
| eina_inlist.h | | eina_inlist.h | |
|---|
| | | | |
| skipping to change at line 28 | | skipping to change at line 28 | |
|---|
| | | | |
| #ifndef EINA_INLIST_H_ | | #ifndef EINA_INLIST_H_ | |
| #define EINA_INLIST_H_ | | #define EINA_INLIST_H_ | |
| | | | |
| #include "eina_types.h" | | #include "eina_types.h" | |
| #include "eina_iterator.h" | | #include "eina_iterator.h" | |
| #include "eina_accessor.h" | | #include "eina_accessor.h" | |
| #include <stddef.h> | | #include <stddef.h> | |
| | | | |
| /** | | /** | |
|
| | | * @page inlist_01_example_page Eina_Inlist basic usage | |
| | | * @dontinclude eina_inlist_01.c | |
| | | * | |
| | | * To see the full source for this example, click here: @ref | |
| | | * eina_inlist_01_c | |
| | | * | |
| | | * As explained before, inline lists mean its nodes pointers are part of sa | |
| | | me | |
| | | * memory block/blob. This is done by using the macro @ref EINA_INLIST insi | |
| | | de the | |
| | | * data structure that will be used: | |
| | | * | |
| | | * @skip struct | |
| | | * @until }; | |
| | | * | |
| | | * The resulting node representing this struct can be exemplified by the | |
| | | * following picture: | |
| | | * | |
| | | * @image html eina_inlist-node_eg1-my-struct.png | |
| | | * @image rtf eina_inlist-node_eg1-my-struct.png | |
| | | * @image latex eina_inlist-node_eg1-my-struct.eps | |
| | | * | |
| | | * Let's define a comparison function that will be used later during the | |
| | | * sorting of the list: | |
| | | * | |
| | | * @skip int | |
| | | * @until } | |
| | | * | |
| | | * The @ref Eina_Inlist can be used exactly the same way as @ref Eina_List | |
| | | when | |
| | | * appending, prepending and removing items. But since we already have the | |
| | | node | |
| | | * pointers inside the structure, they need to be retrieved with the macro | |
| | | @ref | |
| | | * EINA_INLIST_GET : | |
| | | * | |
| | | * @skip malloc | |
| | | * @until append | |
| | | * | |
| | | * Notice that @ref eina_inlist_append always receives the head of the list | |
| | | as | |
| | | * first argument, and its return value should be used as the list pointer | |
| | | * (head): | |
| | | * | |
| | | * @skip malloc | |
| | | * @until append | |
| | | * | |
| | | * After appending 3 items, the list now should look similar to this: | |
| | | * | |
| | | * @image html eina_inlist-node_eg1-inlist.png | |
| | | * @image rtf eina_inlist-node_eg1-inlist.png | |
| | | * @image latex eina_inlist-node_eg1-inlist.eps width=\textwidth | |
| | | * | |
| | | * The macro @ref EINA_INLIST_FOREACH can be used to iterate over the list: | |
| | | * | |
| | | * @skip printf | |
| | | * @until cur->a | |
| | | * | |
| | | * @ref eina_inlist_promote(), @ref eina_inlist_demote(), @ref | |
| | | * eina_inlist_append_relative() and similar functions all work in the same | |
| | | way | |
| | | * as the @ref Eina_List : | |
| | | * | |
| | | * @skip eina_inlist_promote | |
| | | * @until eina_inlist_demote | |
| | | * | |
| | | * Now let's use the @c sort_cb function declared above to sort our list: | |
| | | * | |
| | | * @skipline eina_inlist_sort | |
| | | * | |
| | | * Removing an element from the inlist is also similar to @ref Eina_List : | |
| | | * | |
| | | * @skip inlist_remove | |
| | | * @until free | |
| | | * | |
| | | * Another way of walking through the inlist. | |
| | | * | |
| | | * @skip for | |
| | | * @until } | |
| | | * | |
| | | * Notice that in the previous piece of code, since we only have the pointe | |
| | | rs to | |
| | | * the inlist nodes, we have to use the @ref EINA_INLIST_CONTAINER_GET macr | |
| | | o | |
| | | * that will return the pointer to the entire structure. Of course, in this | |
| | | case | |
| | | * it is the same as the list pointer, since the @ref EINA_INLIST macro was | |
| | | used | |
| | | * in the beginning of the structure. | |
| | | * | |
| | | * Now to finish this example, lets delete this list: | |
| | | * | |
| | | * @skip while | |
| | | * @until } | |
| | | */ | |
| | | | |
| | | /** | |
| | | * @page inlist_02_example_page Eina_Inlist advanced usage - lists and inli | |
| | | sts | |
| | | * @dontinclude eina_inlist_02.c | |
| | | * | |
| | | * This example describes the usage of @ref Eina_Inlist mixed with @ref | |
| | | * Eina_List . We create and add elements to an inlist, and the even member | |
| | | s | |
| | | * are also added to a normal list. Later we remove the elements divisible | |
| | | by 3 | |
| | | * from this normal list. | |
| | | * | |
| | | * The struct that is going to be used is the same used in @ref | |
| | | * inlist_01_example_page , since we still need the @ref EINA_INLIST macro | |
| | | to | |
| | | * declare the inlist node info: | |
| | | * | |
| | | * @skip struct | |
| | | * @until }; | |
| | | * | |
| | | * The resulting node representing this struct can be exemplified by the | |
| | | * following picture: | |
| | | * | |
| | | * @image html eina_inlist-node_eg2-my-struct.png | |
| | | * @image rtf eina_inlist-node_eg2-my-struct.png | |
| | | * @image latex eina_inlist-node_eg2-my-struct.eps | |
| | | * | |
| | | * Now we need some pointers and auxiliar variables that will help us itera | |
| | | te on | |
| | | * the lists: | |
| | | * | |
| | | * @skip struct | |
| | | * @until l_next; | |
| | | * | |
| | | * Allocating 100 elements and putting them into an inlist, and the even | |
| | | * elements also go to the normal list: | |
| | | * | |
| | | * @skip for | |
| | | * @until } | |
| | | * | |
| | | * After this point, what we have are two distinct lists that share some | |
| | | * elements. The first list (inlist) is defined by the pointers inside the | |
| | | * elements data structure, while the second list (normal list) has its own | |
| | | node | |
| | | * data structure that is kept outside of the elements. | |
| | | * | |
| | | * The two lists, sharing some elements, can be represented by the followin | |
| | | g | |
| | | * picture: | |
| | | * | |
| | | * @htmlonly | |
| | | * <img src="eina_inlist-node_eg2-list-inlist.png" style="max-width: 100%;" | |
| | | /> | |
| | | * @endhtmlonly | |
| | | * @image rtf eina_inlist-node_eg2-list-inlist.png | |
| | | * @image latex eina_inlist-node_eg2-list-inlist.eps width=\textwidth | |
| | | * | |
| | | * Accessing both lists is done normally, as if they didn't have any elemen | |
| | | ts in | |
| | | * common: | |
| | | * | |
| | | * @skip printf | |
| | | * @until eina_list_count | |
| | | * | |
| | | * We can remove elements from the normal list, but we just don't free them | |
| | | * because they are still stored in the inlist: | |
| | | * | |
| | | * @skip EINA_LIST_FOREACH_SAFE | |
| | | * @until eina_list_count | |
| | | * | |
| | | * To finish this example, we want to free both lists, we can't just free a | |
| | | ll | |
| | | * elements on the second list (normal list) because they are still being u | |
| | | sed | |
| | | * in the inlist. So we first discard the normal list without freeing its | |
| | | * elements, then we free all elements in the inlist (that contains all ele | |
| | | ments | |
| | | * allocated until now): | |
| | | * | |
| | | * @skip eina_list_free | |
| | | * @until } | |
| | | * | |
| | | * Here is the full source code for this example: @ref eina_inlist_02_c | |
| | | */ | |
| | | | |
| | | /** | |
| | | * @page inlist_03_example_page Eina_Inlist advanced usage - multi-inlists | |
| | | * @dontinclude eina_inlist_03.c | |
| | | * | |
| | | * This example describes the usage of multiple inlists storing the same da | |
| | | ta. | |
| | | * It means that some data may appear in more than one inlist at the same t | |
| | | ime. | |
| | | * We will demonstrate this by creating an inlist with 100 numbers, and add | |
| | | ing | |
| | | * the odd numbers to the second inlist, then remove the numbers divisible | |
| | | by 3 | |
| | | * from the second list. | |
| | | * | |
| | | * To accomplish this, it is necessary to have two inlist pointers in the s | |
| | | truct | |
| | | * that is going to be stored. We are using the default inlist member @ref | |
| | | * EINA_INLIST, and adding another member @c even that is of type @ref | |
| | | * Eina_Inlist too: | |
| | | * | |
| | | * @skip struct | |
| | | * @until }; | |
| | | * | |
| | | * The representation for this struct is: | |
| | | * | |
| | | * @image html eina_inlist-node_eg3-my-struct.png | |
| | | * @image rtf eina_inlist-node_eg3-my-struct.png | |
| | | * @image latex eina_inlist-node_eg3-my-struct.eps | |
| | | * | |
| | | * And we will define some convenience macros that are equivalent to @ref | |
| | | * EINA_INLIST_GET and @ref EINA_INLIST_CONTAINER_GET : | |
| | | * | |
| | | * @skip define | |
| | | * @until offsetof | |
| | | * | |
| | | * We need two pointers, one for each list, and a pointer that will be used | |
| | | as | |
| | | * an iterator: | |
| | | * | |
| | | * @skipline Eina_Inlist | |
| | | * | |
| | | * Now we allocate and add to the first list every number from 0 to 99. The | |
| | | se | |
| | | * nodes data also have the @ref Eina_Inlist node info for the second list | |
| | | (@c | |
| | | * even). We will use them to add just the even numbers to the second list, | |
| | | the | |
| | | * @c list_even. Also notice that we are using our macro @c EVEN_INLIST_GET | |
| | | to | |
| | | * get the pointer to the even list node info: | |
| | | * | |
| | | * @skip for | |
| | | * @until } | |
| | | * | |
| | | * And the resulting lists will be as follow: | |
| | | * | |
| | | * @htmlonly | |
| | | * <img src="eina_inlist-node_eg3-two-inlists.png" style="max-width: 100%;" | |
| | | /> | |
| | | * @endhtmlonly | |
| | | * @image rtf eina_inlist-node_eg3-two-inlists.png | |
| | | * @image latex eina_inlist-node_eg3-two-inlists.eps width=\textwidth | |
| | | * | |
| | | * For the first list, we can use the macro @ref EINA_INLIST_FOREACH to ite | |
| | | rate | |
| | | * over its elements: | |
| | | * | |
| | | * @skip FOREACH | |
| | | * @until printf | |
| | | * | |
| | | * But for the second list, we have to do it manually. Of course we could c | |
| | | reate | |
| | | * a similar macro to @ref EINA_INLIST_FOREACH, but since this macro is mor | |
| | | e | |
| | | * complex than the other two and we are using it only once, it's better to | |
| | | just | |
| | | * do it manually: | |
| | | * | |
| | | * @skip for | |
| | | * @until } | |
| | | * | |
| | | * Let's just check that the two lists have the expected number of elements | |
| | | : | |
| | | * | |
| | | * @skip list count | |
| | | * @until list_even count | |
| | | * | |
| | | * And removing the numbers divisible by 3 only from the second list: | |
| | | * | |
| | | * @skip itr | |
| | | * @until list_even count | |
| | | * | |
| | | * Now that we don't need the two lists anymore, we can just free all the i | |
| | | tems. | |
| | | * Since all of the allocated data was put into the first list, and both li | |
| | | sts | |
| | | * are made of pointers to inside the data structures, we can free only the | |
| | | * first list (that contains all the elements) and the second list will be | |
| | | gone | |
| | | * with it: | |
| | | * | |
| | | * @skip while | |
| | | * @until free | |
| | | * | |
| | | * To see the full source code for this example, click here: @ref | |
| | | * eina_inlist_03_c | |
| | | * | |
| | | */ | |
| | | | |
| | | /** | |
| | | * @page eina_inlist_01_c eina_inlist_01.c Eina_Inlist basic usage source | |
| | | * @include eina_inlist_01.c | |
| | | */ | |
| | | | |
| | | /** | |
| | | * @page eina_inlist_02_c eina_inlist_02.c Eina_Inlist advanced usage - lis | |
| | | ts and inlists source | |
| | | * @include eina_inlist_02.c | |
| | | */ | |
| | | | |
| | | /** | |
| | | * @page eina_inlist_03_c eina_inlist_03.c Eina_Inlist advanced usage - mul | |
| | | ti-inlists source | |
| | | * @include eina_inlist_03.c | |
| | | */ | |
| | | | |
| | | /** | |
| | | * @addtogroup Eina_Inline_List_Group Inline List | |
| | | * | |
| | | * @brief These functions provide inline list management. | |
| | | * | |
| | | * Inline lists mean its nodes pointers are part of same memory as | |
| | | * data. This has the benefit of fragmenting memory less and avoiding | |
| | | * @c node->data indirection, but has the drawback of higher cost for some | |
| | | * common operations like count and sort. | |
| | | * | |
| | | * It is possible to have inlist nodes to be part of regular lists, created | |
| | | with | |
| | | * @ref eina_list_append() or @ref eina_list_prepend(). It's also possible | |
| | | to | |
| | | * have a structure with two inlist pointers, thus be part of two different | |
| | | * inlists at the same time, but the current convenience macros provided wo | |
| | | n't | |
| | | * work for both of them. Consult @ref inlist_advanced for more info. | |
| | | * | |
| | | * Inline lists have their purposes, but if you don't know what those purpo | |
| | | ses are, go with | |
| | | * regular lists instead. | |
| | | * | |
| | | * Tip: When using inlists in more than one place (that is, passing them ar | |
| | | ound | |
| | | * functions or keeping a pointer to them in a structure) it's more correct | |
| | | * to keep a pointer to the first container, and not a pointer to the first | |
| | | * inlist item (mostly they are the same, but that's not always correct). | |
| | | * This lets the compiler to do type checking and let the programmer know | |
| | | * exactly what type this list is. | |
| | | * | |
| | | * A simple example demonstrating the basic usage of an inlist can be found | |
| | | * here: @ref inlist_01_example_page | |
| | | * | |
| | | * @section inlist_algo Algorithm | |
| | | * | |
| | | * The basic structure can be represented by the following picture: | |
| | | * | |
| | | * @image html eina_inlist-node.png | |
| | | * @image rtf eina_inlist-node.png | |
| | | * @image latex eina_inlist-node.eps | |
| | | * | |
| | | * One data structure will also have the node information, with three point | |
| | | ers: | |
| | | * @a prev, @a next and @a last. The @a last pointer is just valid for the | |
| | | first | |
| | | * element (the list head), otherwise each insertion in the list would have | |
| | | to | |
| | | * be done updating every node with the correct pointer. This means that it | |
| | | 's | |
| | | * always very important to keep a pointer to the first element of the list | |
| | | , | |
| | | * since it is the only one that has the correct information to allow a pro | |
| | | per | |
| | | * O(1) append to the list. | |
| | | * | |
| | | * @section inlist_perf Performance | |
| | | * | |
| | | * Due to the nature of the inlist, there's no accounting information, and | |
| | | no | |
| | | * easy access to the last element from each list node. This means that @re | |
| | | f | |
| | | * eina_inlist_count() is order-N, while @ref eina_list_count() is order-1 | |
| | | (constant | |
| | | * time). | |
| | | * | |
| | | * For the same reasons, @ref eina_inlist_sort() is slower than @ref | |
| | | * eina_list_sort() . If the list is intended to have faster access, be | |
| | | * sorted/merged frequently, or needs to have other complex operations, con | |
| | | sider | |
| | | * using @ref Eina_List instead. | |
| | | * | |
| | | * @section inlist_advanced Advanced Usage | |
| | | * | |
| | | * The basic usage considers a struct that will have the user data, and als | |
| | | o | |
| | | * have an inlist node information (prev, next and last pointers) created w | |
| | | ith | |
| | | * @ref EINA_INLIST during the struct declaration. This allows one to use t | |
| | | he | |
| | | * convenience macros @ref EINA_INLIST_GET(), @ref EINA_INLIST_CONTAINER_GE | |
| | | T(), | |
| | | * @ref EINA_INLIST_FOREACH() and so. This happens because the @ref EINA_IN | |
| | | LIST | |
| | | * macro declares a struct member with the name @a __inlist, and all the ot | |
| | | her | |
| | | * macros assume that this struct member has this name. | |
| | | * | |
| | | * It may be the case that someone needs to have some inlist nodes added to | |
| | | a | |
| | | * @ref Eina_List too. If this happens, the inlist nodes can be added to th | |
| | | e | |
| | | * @ref Eina_List without any problems. This example demonstrates this case | |
| | | : | |
| | | * @ref inlist_02_example_page | |
| | | * | |
| | | * It's also possible to have some data that is part of two different inlis | |
| | | ts. | |
| | | * If this is the case, then it won't be possible to use the convenience ma | |
| | | cros | |
| | | * to both of the lists. It will be necessary to create a new set of macros | |
| | | that | |
| | | * will allow access to the second list node info. An example for this usag | |
| | | e can | |
| | | * be found here: | |
| | | * @ref inlist_03_example_page | |
| | | * | |
| | | * List of examples: | |
| | | * @li @ref inlist_01_example_page | |
| | | * @li @ref inlist_02_example_page | |
| | | * @li @ref inlist_03_example_page | |
| | | */ | |
| | | | |
| | | /** | |
| * @addtogroup Eina_Data_Types_Group Data Types | | * @addtogroup Eina_Data_Types_Group Data Types | |
| * | | * | |
| * @{ | | * @{ | |
| */ | | */ | |
| | | | |
| /** | | /** | |
| * @addtogroup Eina_Containers_Group Containers | | * @addtogroup Eina_Containers_Group Containers | |
| * | | * | |
| * @{ | | * @{ | |
| */ | | */ | |
| | | | |
| skipping to change at line 52 | | skipping to change at line 401 | |
|---|
| * @{ | | * @{ | |
| */ | | */ | |
| | | | |
| /** | | /** | |
| * @typedef Eina_Inlist | | * @typedef Eina_Inlist | |
| * Inlined list type. | | * Inlined list type. | |
| */ | | */ | |
| typedef struct _Eina_Inlist Eina_Inlist; | | typedef struct _Eina_Inlist Eina_Inlist; | |
| | | | |
| /** | | /** | |
|
| | | * @typedef Eina_Inlist_Sorted_State | |
| | | * @since 1.1.0 | |
| | | * State of sorted Eina_Inlist | |
| | | */ | |
| | | typedef struct _Eina_Inlist_Sorted_State Eina_Inlist_Sorted_State; | |
| | | | |
| | | /** | |
| * @struct _Eina_Inlist | | * @struct _Eina_Inlist | |
| * Inlined list type. | | * Inlined list type. | |
| */ | | */ | |
| struct _Eina_Inlist | | struct _Eina_Inlist | |
| { | | { | |
| Eina_Inlist *next; /**< next node */ | | Eina_Inlist *next; /**< next node */ | |
| Eina_Inlist *prev; /**< previous node */ | | Eina_Inlist *prev; /**< previous node */ | |
| Eina_Inlist *last; /**< last node */ | | Eina_Inlist *last; /**< last node */ | |
| }; | | }; | |
| /** Used for declaring an inlist member in a struct */ | | /** Used for declaring an inlist member in a struct */ | |
| #define EINA_INLIST Eina_Inlist __in_list | | #define EINA_INLIST Eina_Inlist __in_list | |
| /** Utility macro to get the inlist object of a struct */ | | /** Utility macro to get the inlist object of a struct */ | |
| #define EINA_INLIST_GET(Inlist) (& ((Inlist)->__in_list)) | | #define EINA_INLIST_GET(Inlist) (& ((Inlist)->__in_list)) | |
| /** Utility macro to get the container object of an inlist */ | | /** Utility macro to get the container object of an inlist */ | |
| #define EINA_INLIST_CONTAINER_GET(ptr, \ | | #define EINA_INLIST_CONTAINER_GET(ptr, \ | |
| type) ((type *)((char *)ptr - \ | | type) ((type *)((char *)ptr - \ | |
| offsetof(type, __in_list)
)) | | offsetof(type, __in_list)
)) | |
| | | | |
|
| | | /** | |
| | | * Add a new node to end of a list. | |
| | | * | |
| | | * @note this code is meant to be fast: appends are O(1) and do not | |
| | | * walk @a list. | |
| | | * | |
| | | * @note @a new_l is considered to be in no list. If it was in another | |
| | | * list before, eina_inlist_remove() it before adding. No | |
| | | * check of @a new_l prev and next pointers is done, so it's safe | |
| | | * to have them uninitialized. | |
| | | * | |
| | | * @param list existing list head or NULL to create a new list. | |
| | | * @param new_l new list node, must not be NULL. | |
| | | * | |
| | | * @return the new list head. Use it and not @a list anymore. | |
| | | */ | |
| EAPI Eina_Inlist *eina_inlist_append(Eina_Inlist *in_list, | | EAPI Eina_Inlist *eina_inlist_append(Eina_Inlist *in_list, | |
| Eina_Inlist *in_item) EINA_ARG_NONNULL
(2) EINA_WARN_UNUSED_RESULT; | | Eina_Inlist *in_item) EINA_ARG_NONNULL
(2) EINA_WARN_UNUSED_RESULT; | |
|
| | | | |
| | | /** | |
| | | * Add a new node to beginning of list. | |
| | | * | |
| | | * @note this code is meant to be fast: appends are O(1) and do not | |
| | | * walk @a list. | |
| | | * | |
| | | * @note @a new_l is considered to be in no list. If it was in another | |
| | | * list before, eina_inlist_remove() it before adding. No | |
| | | * check of @a new_l prev and next pointers is done, so it's safe | |
| | | * to have them uninitialized. | |
| | | * | |
| | | * @param list existing list head or NULL to create a new list. | |
| | | * @param new_l new list node, must not be NULL. | |
| | | * | |
| | | * @return the new list head. Use it and not @a list anymore. | |
| | | */ | |
| EAPI Eina_Inlist *eina_inlist_prepend(Eina_Inlist *in_list, | | EAPI Eina_Inlist *eina_inlist_prepend(Eina_Inlist *in_list, | |
| Eina_Inlist *in_item) EINA_ARG_NONNUL
L(2) EINA_WARN_UNUSED_RESULT; | | Eina_Inlist *in_item) EINA_ARG_NONNUL
L(2) EINA_WARN_UNUSED_RESULT; | |
|
| | | | |
| | | /** | |
| | | * Add a new node after the given relative item in list. | |
| | | * | |
| | | * @note this code is meant to be fast: appends are O(1) and do not | |
| | | * walk @a list. | |
| | | * | |
| | | * @note @a new_l is considered to be in no list. If it was in another | |
| | | * list before, eina_inlist_remove() it before adding. No | |
| | | * check of @a new_l prev and next pointers is done, so it's safe | |
| | | * to have them uninitialized. | |
| | | * | |
| | | * @note @a relative is considered to be inside @a list, no checks are | |
| | | * done to confirm that and giving nodes from different lists | |
| | | * will lead to problems. Giving NULL @a relative is the same as | |
| | | * eina_list_append(). | |
| | | * | |
| | | * @param list existing list head or NULL to create a new list. | |
| | | * @param new_l new list node, must not be NULL. | |
| | | * @param relative reference node, @a new_l will be added after it. | |
| | | * | |
| | | * @return the new list head. Use it and not @a list anymore. | |
| | | */ | |
| EAPI Eina_Inlist *eina_inlist_append_relative(Eina_Inlist *in_list, | | EAPI Eina_Inlist *eina_inlist_append_relative(Eina_Inlist *in_list, | |
| Eina_Inlist *in_item, | | Eina_Inlist *in_item, | |
| Eina_Inlist *in_relative) EIN
A_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; | | Eina_Inlist *in_relative) EIN
A_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; | |
|
| | | | |
| | | /** | |
| | | * Add a new node before the given relative item in list. | |
| | | * | |
| | | * @note this code is meant to be fast: appends are O(1) and do not | |
| | | * walk @a list. | |
| | | * | |
| | | * @note @a new_l is considered to be in no list. If it was in another | |
| | | * list before, eina_inlist_remove() it before adding. No | |
| | | * check of @a new_l prev and next pointers is done, so it's safe | |
| | | * to have them uninitialized. | |
| | | * | |
| | | * @note @a relative is considered to be inside @a list, no checks are | |
| | | * done to confirm that and giving nodes from different lists | |
| | | * will lead to problems. Giving NULL @a relative is the same as | |
| | | * eina_list_prepend(). | |
| | | * | |
| | | * @param list existing list head or NULL to create a new list. | |
| | | * @param new_l new list node, must not be NULL. | |
| | | * @param relative reference node, @a new_l will be added before it. | |
| | | * | |
| | | * @return the new list head. Use it and not @a list anymore. | |
| | | */ | |
| EAPI Eina_Inlist *eina_inlist_prepend_relative(Eina_Inlist *in_list, | | EAPI Eina_Inlist *eina_inlist_prepend_relative(Eina_Inlist *in_list, | |
| Eina_Inlist *in_item, | | Eina_Inlist *in_item, | |
| Eina_Inlist *in_relative) EI
NA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; | | Eina_Inlist *in_relative) EI
NA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; | |
|
| | | | |
| | | /** | |
| | | * Remove node from list. | |
| | | * | |
| | | * @note this code is meant to be fast: appends are O(1) and do not | |
| | | * walk @a list. | |
| | | * | |
| | | * @note @a item is considered to be inside @a list, no checks are | |
| | | * done to confirm that and giving nodes from different lists | |
| | | * will lead to problems, especially if @a item is the head since | |
| | | * it will be different from @a list and the wrong new head will | |
| | | * be returned. | |
| | | * | |
| | | * @param list existing list head, must not be NULL. | |
| | | * @param item existing list node, must not be NULL. | |
| | | * | |
| | | * @return the new list head. Use it and not @a list anymore. | |
| | | */ | |
| EAPI Eina_Inlist *eina_inlist_remove(Eina_Inlist *in_list, | | EAPI Eina_Inlist *eina_inlist_remove(Eina_Inlist *in_list, | |
| Eina_Inlist *in_item) EINA_ARG_NONNU
LL(1, 2) EINA_WARN_UNUSED_RESULT; | | Eina_Inlist *in_item) EINA_ARG_NONNU
LL(1, 2) EINA_WARN_UNUSED_RESULT; | |
|
| | | | |
| | | /** | |
| | | * Find given node in list, returns itself if found, NULL if not. | |
| | | * | |
| | | * @warning this is an expensive call and has O(n) cost, possibly | |
| | | * walking the whole list. | |
| | | * | |
| | | * @param list existing list to search @a item in, must not be NULL. | |
| | | * @param item what to search for, must not be NULL. | |
| | | * | |
| | | * @return @a item if found, NULL if not. | |
| | | */ | |
| EAPI Eina_Inlist *eina_inlist_find(Eina_Inlist *in_list, | | EAPI Eina_Inlist *eina_inlist_find(Eina_Inlist *in_list, | |
| Eina_Inlist *in_item) EINA_ARG_NONNULL
(2) EINA_WARN_UNUSED_RESULT; | | Eina_Inlist *in_item) EINA_ARG_NONNULL
(2) EINA_WARN_UNUSED_RESULT; | |
|
| | | | |
| | | /** | |
| | | * Move existing node to beginning of list. | |
| | | * | |
| | | * @note this code is meant to be fast: appends are O(1) and do not | |
| | | * walk @a list. | |
| | | * | |
| | | * @note @a item is considered to be inside @a list. No checks are | |
| | | * done to confirm this, and giving nodes from different lists | |
| | | * will lead to problems. | |
| | | * | |
| | | * @param list existing list head or NULL to create a new list. | |
| | | * @param item list node to move to beginning (head), must not be NULL. | |
| | | * | |
| | | * @return the new list head. Use it and not @a list anymore. | |
| | | */ | |
| EAPI Eina_Inlist *eina_inlist_promote(Eina_Inlist *list, | | EAPI Eina_Inlist *eina_inlist_promote(Eina_Inlist *list, | |
| Eina_Inlist *item) EINA_ARG_NONNULL
(1, 2) EINA_WARN_UNUSED_RESULT; | | Eina_Inlist *item) EINA_ARG_NONNULL
(1, 2) EINA_WARN_UNUSED_RESULT; | |
|
| | | | |
| | | /** | |
| | | * Move existing node to end of list. | |
| | | * | |
| | | * @note this code is meant to be fast: appends are O(1) and do not | |
| | | * walk @a list. | |
| | | * | |
| | | * @note @a item is considered to be inside @a list. No checks are | |
| | | * done to confirm this, and giving nodes from different lists | |
| | | * will lead to problems. | |
| | | * | |
| | | * @param list existing list head or NULL to create a new list. | |
| | | * @param item list node to move to end (tail), must not be NULL. | |
| | | * | |
| | | * @return the new list head. Use it and not @a list anymore. | |
| | | */ | |
| EAPI Eina_Inlist *eina_inlist_demote(Eina_Inlist *list, | | EAPI Eina_Inlist *eina_inlist_demote(Eina_Inlist *list, | |
| Eina_Inlist *item) EINA_ARG_NONNULL(
1, 2) EINA_WARN_UNUSED_RESULT; | | Eina_Inlist *item) EINA_ARG_NONNULL(
1, 2) EINA_WARN_UNUSED_RESULT; | |
|
| | | | |
| | | /** | |
| | | * @brief Get the count of the number of items in a list. | |
| | | * | |
| | | * @param list The list whose count to return. | |
| | | * @return The number of members in the list. | |
| | | * | |
| | | * This function returns how many members @p list contains. If the | |
| | | * list is @c NULL, 0 is returned. | |
| | | * | |
| | | * @warning This is an order-N operation and so the time will depend | |
| | | * on the number of elements on the list, so, it might become | |
| | | * slow for big lists! | |
| | | */ | |
| EAPI unsigned int eina_inlist_count(const Eina_Inlist *list) EINA_WARN_UN
USED_RESULT; | | EAPI unsigned int eina_inlist_count(const Eina_Inlist *list) EINA_WARN_UN
USED_RESULT; | |
| | | | |
|
| | | /** | |
| | | * @brief Returns a new iterator associated to @a list. | |
| | | * | |
| | | * @param list The list. | |
| | | * @return A new iterator. | |
| | | * | |
| | | * This function returns a newly allocated iterator associated to @p | |
| | | * list. If @p list is @c NULL or the count member of @p list is less | |
| | | * or equal than 0, this function still returns a valid iterator that | |
| | | * will always return false on eina_iterator_next(), thus keeping API | |
| | | * sane. | |
| | | * | |
| | | * If the memory can not be allocated, NULL is returned and | |
| | | * #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is | |
| | | * returned. | |
| | | * | |
| | | * @warning if the list structure changes then the iterator becomes | |
| | | * invalid, and if you add or remove nodes iterator | |
| | | * behavior is undefined, and your program may crash! | |
| | | */ | |
| EAPI Eina_Iterator *eina_inlist_iterator_new(const Eina_Inlist *in_list) EI
NA_MALLOC EINA_WARN_UNUSED_RESULT; | | EAPI Eina_Iterator *eina_inlist_iterator_new(const Eina_Inlist *in_list) EI
NA_MALLOC EINA_WARN_UNUSED_RESULT; | |
|
| | | | |
| | | /** | |
| | | * @brief Returns a new accessor associated to a list. | |
| | | * | |
| | | * @param list The list. | |
| | | * @return A new accessor. | |
| | | * | |
| | | * This function returns a newly allocated accessor associated to | |
| | | * @p list. If @p list is @c NULL or the count member of @p list is | |
| | | * less or equal than 0, this function returns NULL. If the memory can | |
| | | * not be allocated, NULL is returned and #EINA_ERROR_OUT_OF_MEMORY is | |
| | | * set. Otherwise, a valid accessor is returned. | |
| | | */ | |
| EAPI Eina_Accessor *eina_inlist_accessor_new(const Eina_Inlist *in_list) EI
NA_MALLOC EINA_WARN_UNUSED_RESULT; | | EAPI Eina_Accessor *eina_inlist_accessor_new(const Eina_Inlist *in_list) EI
NA_MALLOC EINA_WARN_UNUSED_RESULT; | |
| | | | |
|
| | | /** | |
| | | * @brief Insert a new node into a sorted list. | |
| | | * | |
| | | * @param list The given linked list, @b must be sorted. | |
| | | * @param item list node to insert, must not be NULL. | |
| | | * @param func The function called for the sort. | |
| | | * @return A list pointer. | |
| | | * @since 1.1.0 | |
| | | * | |
| | | * This function inserts item into a linked list assuming it was | |
| | | * sorted and the result will be sorted. If @p list is @c NULLL, item | |
| | | * is returned. On success, a new list pointer that should be | |
| | | * used in place of the one given to this function is | |
| | | * returned. Otherwise, the old pointer is returned. See eina_error_get(). | |
| | | * | |
| | | * @note O(log2(n)) comparisons (calls to @p func) average/worst case | |
| | | * performance. As said in eina_list_search_sorted_near_list(), | |
| | | * lists do not have O(1) access time, so walking to the correct node | |
| | | * can be costly, consider worst case to be almost O(n) pointer | |
| | | * dereference (list walk). | |
| | | */ | |
| | | EAPI Eina_Inlist *eina_inlist_sorted_insert(Eina_Inlist *list, Eina_Inlist | |
| | | *item, Eina_Compare_Cb func) EINA_ARG_NONNULL(2, 3) EINA_WARN_UNUSED_RESULT | |
| | | ; | |
| | | | |
| | | /** | |
| | | * @brief Create state with valid data in it. | |
| | | * | |
| | | * @return A valid Eina_Inlist_Sorted_State. | |
| | | * @since 1.1.0 | |
| | | * | |
| | | * See eina_inlist_sorted_state_insert() for more information. | |
| | | */ | |
| | | EAPI Eina_Inlist_Sorted_State *eina_inlist_sorted_state_new(void); | |
| | | | |
| | | /** | |
| | | * @brief Force an Eina_Inlist_Sorted_State to match the content of a list. | |
| | | * | |
| | | * @param state The state to update | |
| | | * @param list The list to match | |
| | | * @return The number of item in the actually in the list | |
| | | * @since 1.1.0 | |
| | | * | |
| | | * See eina_inlist_sorted_state_insert() for more information. This functio | |
| | | n is | |
| | | * usefull if you didn't use eina_inlist_sorted_state_insert() at some poin | |
| | | t, but | |
| | | * still think you have a sorted list. It will only correctly work on a sor | |
| | | ted list. | |
| | | */ | |
| | | EAPI int eina_inlist_sorted_state_init(Eina_Inlist_Sorted_State *state, Ein | |
| | | a_Inlist *list); | |
| | | | |
| | | /** | |
| | | * @brief Free an Eina_Inlist_Sorted_State. | |
| | | * | |
| | | * @param state The state to destroy | |
| | | * @since 1.1.0 | |
| | | * | |
| | | * See eina_inlist_sorted_state_insert() for more information. | |
| | | */ | |
| | | EAPI void eina_inlist_sorted_state_free(Eina_Inlist_Sorted_State *state); | |
| | | | |
| | | /** | |
| | | * @brief Insert a new node into a sorted list. | |
| | | * | |
| | | * @param list The given linked list, @b must be sorted. | |
| | | * @param item list node to insert, must not be NULL. | |
| | | * @param func The function called for the sort. | |
| | | * @param state The current array for initial dichotomic search | |
| | | * @return A list pointer. | |
| | | * @since 1.1.0 | |
| | | * | |
| | | * This function inserts item into a linked list assuming @p state match | |
| | | * the exact content order of the list. It use @p state to do a fast | |
| | | * first step dichotomic search before starting to walk the inlist itself. | |
| | | * This make this code much faster than eina_inlist_sorted_insert() as it | |
| | | * doesn't need to walk the list at all. The result is of course a sorted | |
| | | * list with an updated state.. If @p list is @c NULLL, item | |
| | | * is returned. On success, a new list pointer that should be | |
| | | * used in place of the one given to this function is | |
| | | * returned. Otherwise, the old pointer is returned. See eina_error_get(). | |
| | | * | |
| | | * @note O(log2(n)) comparisons (calls to @p func) average/worst case | |
| | | * performance. As said in eina_list_search_sorted_near_list(), | |
| | | * lists do not have O(1) access time, so walking to the correct node | |
| | | * can be costly, but this version try to minimize that by making it a | |
| | | * O(log2(n)) for number small number. After n == 256, it start to add a | |
| | | * linear cost again. Consider worst case to be almost O(n) pointer | |
| | | * dereference (list walk). | |
| | | */ | |
| | | EAPI Eina_Inlist *eina_inlist_sorted_state_insert(Eina_Inlist *list, | |
| | | Eina_Inlist *item, | |
| | | Eina_Compare_Cb func, | |
| | | Eina_Inlist_Sorted_State * | |
| | | state); | |
| | | /** | |
| | | * @brief Sort a list according to the ordering func will return. | |
| | | * | |
| | | * @param list The list handle to sort. | |
| | | * @param func A function pointer that can handle comparing the list data | |
| | | * nodes. | |
| | | * @return the new head of list. | |
| | | * | |
| | | * This function sorts all the elements of @p list. @p func is used to | |
| | | * compare two elements of @p list. If @p list or @p func are @c NULL, | |
| | | * this function returns @c NULL. | |
| | | * | |
| | | * @note @b in-place: this will change the given list, so you should | |
| | | * now point to the new list head that is returned by this function. | |
| | | * | |
| | | * @note worst case is O(n * log2(n)) comparisons (calls to func()), | |
| | | * O(n) comparisons average case. That means that for 1,000,000 list | |
| | | * elements, sort will usually do 1,000,000 comparisons, but may do up | |
| | | * to 20,000,000. | |
| | | * | |
| | | * Example: | |
| | | * @code | |
| | | * typedef struct _Sort_Ex Sort_Ex; | |
| | | * struct _Sort_Ex | |
| | | * { | |
| | | * INLIST; | |
| | | * const char *text; | |
| | | * }; | |
| | | * | |
| | | * int | |
| | | * sort_cb(const Inlist *l1, const Inlist *l2) | |
| | | * { | |
| | | * const Sort_Ex *x1; | |
| | | * const Sort_Ex *x2; | |
| | | * | |
| | | * x1 = EINA_INLIST_CONTAINER_GET(l1, Sort_Ex); | |
| | | * x2 = EINA_INLIST_CONTAINER_GET(l2, Sort_Ex); | |
| | | * | |
| | | * return(strcmp(x1->text, x2->text)); | |
| | | * } | |
| | | * extern Eina_Inlist *list; | |
| | | * | |
| | | * list = eina_inlist_sort(list, sort_cb); | |
| | | * @endcode | |
| | | */ | |
| | | EAPI Eina_Inlist *eina_inlist_sort(Eina_Inlist *head, Eina_Compare_Cb func) | |
| | | ; | |
| | | | |
| /* This two macros are helpers for the _FOREACH ones, don't use them */ | | /* This two macros are helpers for the _FOREACH ones, don't use them */ | |
| #define _EINA_INLIST_OFFSET(ref) ((char *)&(ref)->__in_list - (char
*)(ref)) | | #define _EINA_INLIST_OFFSET(ref) ((char *)&(ref)->__in_list - (char
*)(ref)) | |
|
| | | | |
| | | #if !defined(__cplusplus) | |
| #define _EINA_INLIST_CONTAINER(ref, ptr) (void *)((char *)(ptr) - \ | | #define _EINA_INLIST_CONTAINER(ref, ptr) (void *)((char *)(ptr) - \ | |
| _EINA_INLIST_OFFSET(ref)) | | _EINA_INLIST_OFFSET(ref)) | |
|
| | | #else | |
| | | /* | |
| | | * In C++ we can't assign a "type*" pointer to void* so we rely on GCC's ty | |
| | | peof | |
| | | * operator. | |
| | | */ | |
| | | #define _EINA_INLIST_CONTAINER(ref, ptr) (typeof(ref))((char *)(ptr) - \ | |
| | | _EINA_INLIST_OFFSET(ref)) | |
| | | #endif | |
| | | | |
| #define EINA_INLIST_FOREACH(list, l) \ | | #define EINA_INLIST_FOREACH(list, l) \ | |
| for (l = NULL, l = (list ? _EINA_INLIST_CONTAINER(l, list) : NULL); l; \ | | for (l = NULL, l = (list ? _EINA_INLIST_CONTAINER(l, list) : NULL); l; \ | |
| l = (EINA_INLIST_GET(l)->next ? _EINA_INLIST_CONTAINER(l, EINA_INLIS
T_GET(l)->next) : NULL)) | | l = (EINA_INLIST_GET(l)->next ? _EINA_INLIST_CONTAINER(l, EINA_INLIS
T_GET(l)->next) : NULL)) | |
|
| | | #define EINA_INLIST_FOREACH_SAFE(list, list2, l) \ | |
| | | for (l = (list ? _EINA_INLIST_CONTAINER(l, list) : NULL), list2 = l ? (( | |
| | | EINA_INLIST_GET(l) ? EINA_INLIST_GET(l)->next : NULL)) : NULL; \ | |
| | | l; \ | |
| | | l = _EINA_INLIST_CONTAINER(l, list2), list2 = list2 ? list2->next : | |
| | | NULL) | |
| #define EINA_INLIST_REVERSE_FOREACH(list, l)
\ | | #define EINA_INLIST_REVERSE_FOREACH(list, l)
\ | |
| for (l = NULL, l = (list ? _EINA_INLIST_CONTAINER(l, list->last) : NULL);
\ | | for (l = NULL, l = (list ? _EINA_INLIST_CONTAINER(l, list->last) : NULL);
\ | |
| l; l = (EINA_INLIST_GET(l)->prev ? _EINA_INLIST_CONTAINER(l, EINA_IN
LIST_GET(l)->prev) : NULL)) | | l; l = (EINA_INLIST_GET(l)->prev ? _EINA_INLIST_CONTAINER(l, EINA_IN
LIST_GET(l)->prev) : NULL)) | |
| | | | |
| /** | | /** | |
| * @} | | * @} | |
| */ | | */ | |
| | | | |
| /** | | /** | |
| * @} | | * @} | |
| | | | |
| End of changes. 17 change blocks. |
|---|
| 0 lines changed or deleted | | 777 lines changed or added | |
|---|
|
| eina_list.h | | eina_list.h | |
|---|
| | | | |
| skipping to change at line 32 | | skipping to change at line 32 | |
|---|
| #include <stdlib.h> | | #include <stdlib.h> | |
| | | | |
| #include "eina_config.h" | | #include "eina_config.h" | |
| | | | |
| #include "eina_types.h" | | #include "eina_types.h" | |
| #include "eina_iterator.h" | | #include "eina_iterator.h" | |
| #include "eina_accessor.h" | | #include "eina_accessor.h" | |
| #include "eina_magic.h" | | #include "eina_magic.h" | |
| | | | |
| /** | | /** | |
|
| | | * @page list_01_example_page Adding elements to Eina_List | |
| | | * @dontinclude eina_list_01.c | |
| | | * | |
| | | * Creating an @ref Eina_List and adding elements to it is very easy and ca | |
| | | n be | |
| | | * understood from an example: | |
| | | * First thing is always to include Eina.h, for this example we also | |
| | | * include stdio.h so we can use printf. | |
| | | * @skip #include | |
| | | * @until Eina.h | |
| | | * | |
| | | * Just some boilerplate code, declaring some variable and initializing ein | |
| | | a. | |
| | | * @until eina_init | |
| | | * Here we add a sequence of elements to our list. By using append we add | |
| | | * elements to the end of the list, so the list will look like this:@n | |
| | | * @htmlonly | |
| | | * <img src="eina_list_example_01_a.png" style="max-width: 100%;" /> | |
| | | * <a href="eina_list_example_01_a.png">Full-size</a> | |
| | | * @endhtmlonly | |
| | | * @image rtf eina_list_example_01_a.png | |
| | | * @image latex eina_list_example_01_a.eps width=\textwidth | |
| | | * @until roslin | |
| | | * There are a couple of interesting things happening here, first is that w | |
| | | e are | |
| | | * passing a NULL pointer to the first @ref eina_list_append() call, when t | |
| | | his | |
| | | * is done a list is created. The other @b very important detail to notice | |
| | | is | |
| | | * that the return value is attributed to the @a list variable, this needs | |
| | | to | |
| | | * be done every time we use a a function that alters the contents of the l | |
| | | ist. | |
| | | * | |
| | | * Now that we have a list we some elements in it we can look at it's conte | |
| | | nts. | |
| | | * @until printf | |
| | | * | |
| | | * There are many ways of accessing elements in the list, including by it's | |
| | | * index: | |
| | | * @until nth | |
| | | * @note It should be noted that the index starts at 0. | |
| | | * | |
| | | * @ref eina_list_append() is not the only way to add elements to a a list. | |
| | | A | |
| | | * common requirement is to add an element in a specific position this can | |
| | | be | |
| | | * accomplished using @ref eina_list_append_relative() and | |
| | | * @ref eina_list_append_relative_list(): | |
| | | * @until zarek | |
| | | * First @a "cain" is added after the second element(remember that indexes | |
| | | are | |
| | | * 0 based) and then we add @a "zarek" after @a "cain". | |
| | | * | |
| | | * @ref Eina_List also has prepend analogs to append functions we have used | |
| | | so | |
| | | * far: | |
| | | * @until lampkin | |
| | | * With this additions our list now looks like this:@n | |
| | | * @htmlonly | |
| | | * <img src="eina_list_example_01_b.png" style="max-width: 100%;" /> | |
| | | * <a href="eina_list_example_01_b.png">Full-size</a> | |
| | | * @endhtmlonly | |
| | | * @image rtf eina_list_example_01_b.png | |
| | | * @image latex eina_list_example_01_b.eps width=\textwidth | |
| | | * | |
| | | * Once done using the list it needs to be freed, and since we are done wit | |
| | | h | |
| | | * eina that also need to be shutdown: | |
| | | * @until } | |
| | | * | |
| | | * The full source code can be found on the examples folder | |
| | | * on the @ref eina_list_01_c "eina_list_01.c" file. | |
| | | */ | |
| | | | |
| | | /** | |
| | | * @page eina_list_01_c Adding elements to Eina_List example | |
| | | * | |
| | | * @include eina_list_01.c | |
| | | * @example eina_list_01.c | |
| | | */ | |
| | | | |
| | | /** | |
| | | * @page list_02_example_page Sorting Eina_List elements | |
| | | * @dontinclude eina_list_02.c | |
| | | * | |
| | | * If you don't know how to create lists see | |
| | | * @ref list_01_example_page. | |
| | | * | |
| | | * @skip #include | |
| | | * @until boomer | |
| | | * This is the code we have already seen to create a list. Now if we need t | |
| | | o | |
| | | * search the list we can do it like this: | |
| | | * @until return | |
| | | * | |
| | | * However if searching the list multiple times it probably is better to so | |
| | | rt | |
| | | * the list since the sorted_search functions are much faster: | |
| | | * @until return | |
| | | * | |
| | | * Once the list is sorted it's not a good idea to use append/prepend funct | |
| | | ions | |
| | | * since that would add the element in the wrong place, instead elements sh | |
| | | ould | |
| | | * be added with @ref eina_list_sorted_insert(): | |
| | | * @until sorted_insert | |
| | | * | |
| | | * A noteworthy use case is adding an element to a list only if it doesn't | |
| | | exist | |
| | | * already, this can accomplished by searching for the element that is clos | |
| | | est | |
| | | * to what is being added, and if that doesn't match add: | |
| | | * @until append | |
| | | * @note @ref eina_list_search_sorted_near_list() will tell you not only th | |
| | | e | |
| | | * nearest node to what was searched for but how it compares to your term, | |
| | | this | |
| | | * way it is easy to know if you have to add before or after that node. | |
| | | * | |
| | | * It is sometimes useful to get a portion of the list as another list, her | |
| | | e we | |
| | | * take every element that comes after "boomer" and split it into "other_li | |
| | | st": | |
| | | * @until split_list | |
| | | * | |
| | | * It is also possible to add entire lists of elements using | |
| | | * @ref eina_list_sorted_merge(): | |
| | | * @until sorted_merge | |
| | | * | |
| | | * And as always release memory and shutdown eina before ending: | |
| | | * @until } | |
| | | * | |
| | | * The full source code can be found on the examples folder | |
| | | * on the @ref eina_list_02_c "eina_list_02.c" file. | |
| | | */ | |
| | | | |
| | | /** | |
| | | * @page eina_list_02_c Sorting Eina_List elements example | |
| | | * | |
| | | * @include eina_list_02.c | |
| | | * @example eina_list_02.c | |
| | | */ | |
| | | | |
| | | /** | |
| | | * @page list_03_example_page Reordering Eina_List elments | |
| | | * @dontinclude eina_list_03.c | |
| | | * | |
| | | * If you don't know how to create lists see | |
| | | * @ref list_01_example_page. | |
| | | * | |
| | | * We start out with code that should be familiar by now: | |
| | | * @skip #include | |
| | | * @until gemenon | |
| | | * | |
| | | * You can move elements around in a list using @ref eina_list_move() or us | |
| | | ing | |
| | | * @ref eina_list_promote_list() and @ref eina_list_demote_list() which mov | |
| | | e a | |
| | | * list node to the head and end of the list respectevely: | |
| | | * @until demote | |
| | | * | |
| | | * Removing elements from a list can be done with ease: | |
| | | * @until sagitarius | |
| | | * | |
| | | * To replace an element in the list it is not necessary to remove it and t | |
| | | hen | |
| | | * add with the new value, it is possible to just change the value of a nod | |
| | | e: | |
| | | * @until aquarius | |
| | | * | |
| | | * We will now take a peek to see if the list still has the right number of | |
| | | * elements: | |
| | | * @until printf | |
| | | * | |
| | | * Now that the list is in alphabetical order let's create a copy of it in | |
| | | * reverse order and print every element to see if worked as expected: | |
| | | * @until iterator_free | |
| | | * @note Always remember to free your iterators when done using them. | |
| | | * | |
| | | * And as always release memory and shutdown eina before ending: | |
| | | * @until } | |
| | | * | |
| | | * The full source code can be found on the examples folder | |
| | | * on the @ref eina_list_03_c "eina_list_03.c" file. | |
| | | */ | |
| | | | |
| | | /** | |
| | | * @page eina_list_03_c Reordering Eina_List elments example | |
| | | * | |
| | | * @include eina_list_03.c | |
| | | * @example eina_list_03.c | |
| | | */ | |
| | | | |
| | | /** | |
| | | * @page list_04_example_page Eina_List and memory allocation | |
| | | * @dontinclude eina_list_04.c | |
| | | * | |
| | | * If you don't know how to create lists see | |
| | | * @ref list_01_example_page. In this example we also use | |
| | | * @ref eina_stringshare, however it should be possible to understand the c | |
| | | ode | |
| | | * regardless of previous knowledge about it. | |
| | | * | |
| | | * Here we have the usual list creation code with a twist, now we are using | |
| | | as | |
| | | * data for the list memory that has to be freed later on. | |
| | | * @skip #include | |
| | | * @until Sharon | |
| | | * | |
| | | * This time we are going to iterate over our list in a different way: | |
| | | * @until printf | |
| | | * | |
| | | * And now we are going to iterate over the list backwards: | |
| | | * @until printf | |
| | | * | |
| | | * And now we need to free up the memory allocated during creation of the l | |
| | | ist: | |
| | | * @until stringshare_del | |
| | | * @note We don't need to use eina_list_free() since @ref EINA_LIST_FREE ta | |
| | | kes | |
| | | * care of that. | |
| | | * | |
| | | * And shut everything down: | |
| | | * @until } | |
| | | * | |
| | | * The full source code can be found on the examples folder | |
| | | * on the @ref eina_list_04_c "eina_list_04.c" file. | |
| | | */ | |
| | | | |
| | | /** | |
| | | * @page eina_list_04_c Eina_List and memory allocation example | |
| | | * | |
| | | * @include eina_list_04.c | |
| | | * @example eina_list_04.c | |
| | | */ | |
| | | | |
| | | /** | |
| | | * @addtogroup Eina_List_Group List | |
| | | * | |
| | | * @brief These functions provide double linked list management. | |
| | | * | |
| | | * Eina_List is a doubly linked list. It can store data of any type in the | |
| | | * form of void pointers. It has convenience functions to do all the common | |
| | | * operations which means it should rarely if ever be necessary to directly | |
| | | * access the struct's fields. Nevertheless it can be useful to understand | |
| | | the | |
| | | * inner workings of the data structure being used. | |
| | | * | |
| | | * @ref Eina_List nodes keep references to the previous node, the next node | |
| | | , its | |
| | | * data and to an accounting structure. | |
| | | * | |
| | | * @htmlonly | |
| | | * <img src="eina_list.png" style="max-width: 100%;" /> | |
| | | * <a href="eina_list.png">Full-size</a> | |
| | | * @endhtmlonly | |
| | | * @image rtf eina_list.png | |
| | | * @image latex eina_list.eps width=5cm | |
| | | * | |
| | | * @ref Eina_List_Accounting is used to improve the performance of some | |
| | | * functions. It is private and <b>should not</b> be modified. It contains | |
| | | a | |
| | | * reference to the end of the list and the number of elements in the list. | |
| | | * | |
| | | * @note Every function that modifies the contents of the list returns a po | |
| | | inter | |
| | | * to the head of the list and it is essential that this be pointer be used | |
| | | in | |
| | | * any future references to the list. | |
| | | * | |
| | | * Most functions have two versions that have the same effect but operate o | |
| | | n | |
| | | * different arguments, the @a plain functions operate over data(eg.: | |
| | | * @ref eina_list_append_relative, @ref eina_list_remove, | |
| | | * @ref eina_list_data_find), the @a list versions of these functions opera | |
| | | te | |
| | | * on @ref Eina_List nodes. | |
| | | * | |
| | | * @warning You must @b always use the pointer to the first element of the | |
| | | list | |
| | | * as the list! | |
| | | * @warning You must @b never use a pointer to an element in the middle of | |
| | | the | |
| | | * list as the list! | |
| | | * | |
| | | * Here are some examples of @ref Eina_List usage: | |
| | | * @li @ref list_01_example_page | |
| | | * @li @ref list_02_example_page | |
| | | * @li @ref list_03_example_page | |
| | | * @li @ref list_04_example_page | |
| | | */ | |
| | | | |
| | | /** | |
| * @addtogroup Eina_Data_Types_Group Data Types | | * @addtogroup Eina_Data_Types_Group Data Types | |
| * | | * | |
| * @{ | | * @{ | |
| */ | | */ | |
| | | | |
| /** | | /** | |
| * @addtogroup Eina_Containers_Group Containers | | * @addtogroup Eina_Containers_Group Containers | |
| * | | * | |
| * @{ | | * @{ | |
| */ | | */ | |
| | | | |
| skipping to change at line 89 | | skipping to change at line 343 | |
|---|
| * elements, for fast access. It is for private used and must not be | | * elements, for fast access. It is for private used and must not be | |
| * touched. | | * touched. | |
| */ | | */ | |
| struct _Eina_List_Accounting | | struct _Eina_List_Accounting | |
| { | | { | |
| Eina_List *last; /**< Pointer to the last element of the list - don't
touch */ | | Eina_List *last; /**< Pointer to the last element of the list - don't
touch */ | |
| unsigned int count; /**< Number of elements of the list - don't touch */ | | unsigned int count; /**< Number of elements of the list - don't touch */ | |
| EINA_MAGIC | | EINA_MAGIC | |
| }; | | }; | |
| | | | |
|
| | | /** | |
| | | * @brief Append the given data to the given linked list. | |
| | | * | |
| | | * @param list The given list. | |
| | | * @param data The data to append. | |
| | | * @return A list pointer. | |
| | | * | |
| | | * This function appends @p data to @p list. If @p list is @c NULL, a | |
| | | * new list is returned. On success, a new list pointer that should be | |
| | | * used in place of the one given to this function is | |
| | | * returned. Otherwise, the old pointer is returned. | |
| | | * | |
| | | * The following example code demonstrates how to ensure that the | |
| | | * given data has been successfully appended. | |
| | | * | |
| | | * @code | |
| | | * Eina_List *list = NULL; | |
| | | * extern void *my_data; | |
| | | * | |
| | | * list = eina_list_append(list, my_data); | |
| | | * if (eina_error_get()) | |
| | | * { | |
| | | * fprintf(stderr, "ERROR: Memory is low. List allocation failed.\n"); | |
| | | * exit(-1); | |
| | | * } | |
| | | * @endcode | |
| | | * | |
| | | * @warning @p list must be a pointer to the first element of the list(or N | |
| | | ULL). | |
| | | */ | |
| EAPI Eina_List *eina_list_append(Eina_List *list, const void *da
ta) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; | | EAPI Eina_List *eina_list_append(Eina_List *list, const void *da
ta) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; | |
| | | | |
|
| | | /** | |
| | | * @brief Prepends the given data to the given linked list. | |
| | | * | |
| | | * @param list The given list. | |
| | | * @param data The data to prepend. | |
| | | * @return A list pointer. | |
| | | * | |
| | | * This function prepends @p data to @p list. If @p list is @c NULL, a | |
| | | * new list is returned. On success, a new list pointer that should be | |
| | | * used in place of the one given to this function is | |
| | | * returned. Otherwise, the old pointer is returned. | |
| | | * | |
| | | * The following example code demonstrates how to ensure that the | |
| | | * given data has been successfully prepended. | |
| | | * | |
| | | * Example: | |
| | | * @code | |
| | | * Eina_List *list = NULL; | |
| | | * extern void *my_data; | |
| | | * | |
| | | * list = eina_list_prepend(list, my_data); | |
| | | * if (eina_error_get()) | |
| | | * { | |
| | | * fprintf(stderr, "ERROR: Memory is low. List allocation failed.\n"); | |
| | | * exit(-1); | |
| | | * } | |
| | | * @endcode | |
| | | * | |
| | | * @warning @p list must be a pointer to the first element of the list. | |
| | | */ | |
| EAPI Eina_List *eina_list_prepend(Eina_List *list, const void *d
ata) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; | | EAPI Eina_List *eina_list_prepend(Eina_List *list, const void *d
ata) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; | |
| | | | |
|
| | | /** | |
| | | * @brief Insert the given data into the given linked list after the specif | |
| | | ied data. | |
| | | * | |
| | | * @param list The given linked list. | |
| | | * @param data The data to insert. | |
| | | * @param relative The data to insert after. | |
| | | * @return A list pointer. | |
| | | * | |
| | | * This function inserts @p data to @p list after @p relative. If | |
| | | * @p relative is not in the list, @p data is appended to the end of | |
| | | * the list. If @p list is @c NULL, a new list is returned. If there | |
| | | * are multiple instances of @p relative in the list, @p data is | |
| | | * inserted after the first instance.On success, a new list pointer | |
| | | * that should be used in place of the one given to this function is | |
| | | * returned. Otherwise, the old pointer is returned. | |
| | | * | |
| | | * The following example code demonstrates how to ensure that the | |
| | | * given data has been successfully inserted. | |
| | | * | |
| | | * @code | |
| | | * Eina_List *list = NULL; | |
| | | * extern void *my_data; | |
| | | * extern void *relative_member; | |
| | | * | |
| | | * list = eina_list_append(list, relative_member); | |
| | | * if (eina_error_get()) | |
| | | * { | |
| | | * fprintf(stderr, "ERROR: Memory is low. List allocation failed.\n"); | |
| | | * exit(-1); | |
| | | * } | |
| | | * list = eina_list_append_relative(list, my_data, relative_member); | |
| | | * if (eina_error_get()) | |
| | | * { | |
| | | * fprintf(stderr, "ERROR: Memory is low. List allocation failed.\n"); | |
| | | * exit(-1); | |
| | | * } | |
| | | * @endcode | |
| | | * | |
| | | * @warning @p list must be a pointer to the first element of the list. | |
| | | */ | |
| EAPI Eina_List *eina_list_append_relative(Eina_List *list, const
void *data, const void *relative) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RES
ULT; | | EAPI Eina_List *eina_list_append_relative(Eina_List *list, const
void *data, const void *relative) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RES
ULT; | |
| | | | |
|
| | | /** | |
| | | * @brief Append a list node to a linked list after the specified member | |
| | | * | |
| | | * @param list The given linked list. | |
| | | * @param data The data to insert. | |
| | | * @param relative The list node to insert after. | |
| | | * @return A list pointer. | |
| | | * | |
| | | * This function inserts @p data to @p list after the list node | |
| | | * @p relative. If @p list or @p relative are @c NULL, @p data is just | |
| | | * appended to @p list using eina_list_append(). If @p list is | |
| | | * @c NULL, a new list is returned. If there are multiple instances | |
| | | * of @p relative in the list, @p data is inserted after the first | |
| | | * instance. On success, a new list pointer that should be used in | |
| | | * place of the one given to this function is returned. Otherwise, the | |
| | | * old pointer is returned. | |
| | | * | |
| | | * @warning @p list must be a pointer to the first element of the list. | |
| | | */ | |
| 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; | | 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; | |
| | | | |
|
| | | /** | |
| | | * @brief Prepend a data pointer to a linked list before the specified memb | |
| | | er | |
| | | * | |
| | | * @param list The given linked list. | |
| | | * @param data The data to insert. | |
| | | * @param relative The data to insert before. | |
| | | * @return A list pointer. | |
| | | * | |
| | | * This function inserts @p data to @p list before @p relative. If | |
| | | * @p relative is not in the list, @p data is prepended to the list | |
| | | * with eina_list_prepend(). If @p list is @c NULL, a new list is | |
| | | * returned. If there are multiple instances of @p relative in the | |
| | | * list, @p data is inserted before the first instance. On success, a | |
| | | * new list pointer that should be used in place of the one given to | |
| | | * this function is returned. Otherwise, the old pointer is returned. | |
| | | * | |
| | | * The following code example demonstrates how to ensure that the | |
| | | * given data has been successfully inserted. | |
| | | * | |
| | | * @code | |
| | | * Eina_List *list = NULL; | |
| | | * extern void *my_data; | |
| | | * extern void *relative_member; | |
| | | * | |
| | | * list = eina_list_append(list, relative_member); | |
| | | * if (eina_error_get_error()) | |
| | | * { | |
| | | * fprintf(stderr, "ERROR: Memory is low. List allocation failed.\n"); | |
| | | * exit(-1); | |
| | | * } | |
| | | * list = eina_list_prepend_relative(list, my_data, relative_member); | |
| | | * if (eina_error_get()) | |
| | | * { | |
| | | * fprintf(stderr, "ERROR: Memory is low. List allocation failed.\n"); | |
| | | * exit(-1); | |
| | | * } | |
| | | * @endcode | |
| | | * | |
| | | * @warning @p list must be a pointer to the first element of the list. | |
| | | */ | |
| EAPI Eina_List *eina_list_prepend_relative(Eina_List *list, cons
t void *data, const void *relative) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RE
SULT; | | EAPI Eina_List *eina_list_prepend_relative(Eina_List *list, cons
t void *data, const void *relative) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RE
SULT; | |
| | | | |
|
| | | /** | |
| | | * @brief Prepend a list node to a linked list before the specified member | |
| | | * | |
| | | * @param list The given linked list. | |
| | | * @param data The data to insert. | |
| | | * @param relative The list node to insert before. | |
| | | * @return A list pointer. | |
| | | * | |
| | | * This function inserts @p data to @p list before the list node | |
| | | * @p relative. If @p list or @p relative are @c NULL, @p data is just | |
| | | * prepended to @p list using eina_list_prepend(). If @p list is | |
| | | * @c NULL, a new list is returned. If there are multiple instances | |
| | | * of @p relative in the list, @p data is inserted before the first | |
| | | * instance. On success, a new list pointer that should be used in | |
| | | * place of the one given to this function is returned. Otherwise, the | |
| | | * old pointer is returned. | |
| | | * | |
| | | * @warning @p list must be a pointer to the first element of the list. | |
| | | */ | |
| EAPI Eina_List *eina_list_prepend_relative_list(Eina_List *list,
const void *data, Eina_List *relative) EINA_ARG_NONNULL(2) EINA_WARN_UNUSE
D_RESULT; | | EAPI Eina_List *eina_list_prepend_relative_list(Eina_List *list,
const void *data, Eina_List *relative) EINA_ARG_NONNULL(2) EINA_WARN_UNUSE
D_RESULT; | |
| | | | |
|
| | | /** | |
| | | * @brief Insert a new node into a sorted list. | |
| | | * | |
| | | * @param list The given linked list, @b must be sorted. | |
| | | * @param func The function called for the sort. | |
| | | * @param data The data to insert sorted. | |
| | | * @return A list pointer. | |
| | | * | |
| | | * This function inserts values into a linked list assuming it was | |
| | | * sorted and the result will be sorted. If @p list is @c NULLL, a new | |
| | | * list is returned. On success, a new list pointer that should be | |
| | | * used in place of the one given to this function is | |
| | | * returned. Otherwise, the old pointer is returned. See eina_error_get(). | |
| | | * | |
| | | * @note O(log2(n)) comparisons (calls to @p func) average/worst case | |
| | | * performance as it uses eina_list_search_sorted_near_list() and thus | |
| | | * is bounded to that. As said in eina_list_search_sorted_near_list(), | |
| | | * lists do not have O(1) access time, so walking to the correct node | |
| | | * can be costly, consider worst case to be almost O(n) pointer | |
| | | * dereference (list walk). | |
| | | * | |
| | | * @warning @p list must be a pointer to the first element of the list. | |
| | | */ | |
| EAPI Eina_List *eina_list_sorted_insert(Eina_List *list, Eina_Co
mpare_Cb func, const void *data) EINA_ARG_NONNULL(2, 3) EINA_WARN_UNUSED_RE
SULT; | | EAPI Eina_List *eina_list_sorted_insert(Eina_List *list, Eina_Co
mpare_Cb func, const void *data) EINA_ARG_NONNULL(2, 3) EINA_WARN_UNUSED_RE
SULT; | |
| | | | |
|
| | | /** | |
| | | * @brief Remove the first instance of the specified data from the given li | |
| | | st. | |
| | | * | |
| | | * @param list The given list. | |
| | | * @param data The specified data. | |
| | | * @return A list pointer. | |
| | | * | |
| | | * This function removes the first instance of @p data from | |
| | | * @p list. If the specified data is not in the given list (tihis | |
| | | * include the case where @p data is @c NULL), nothing is done. If | |
| | | * @p list is @c NULL, @c NULL is returned, otherwise a new list | |
| | | * pointer that should be used in place of the one passed to this | |
| | | * function. | |
| | | * | |
| | | * @warning @p list must be a pointer to the first element of the list. | |
| | | */ | |
| EAPI Eina_List *eina_list_remove(Eina_List *list, const void *da
ta) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; | | EAPI Eina_List *eina_list_remove(Eina_List *list, const void *da
ta) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; | |
| | | | |
|
| | | /** | |
| | | * @brief Remove the specified data. | |
| | | * | |
| | | * @param list The given linked list. | |
| | | * @param remove_list The list node which is to be removed. | |
| | | * @return A list pointer. | |
| | | * | |
| | | * This function removes the list node @p remove_list from @p list and | |
| | | * frees the list node structure @p remove_list. If @p list is | |
| | | * @c NULL, this function returns @c NULL. If @p remove_list is | |
| | | * @c NULL, it returns @p list, otherwise, a new list pointer that | |
| | | * should be used in place of the one passed to this function. | |
| | | * | |
| | | * The following code gives an example (notice we use EINA_LIST_FOREACH | |
| | | * instead of EINA_LIST_FOREACH_SAFE because we stop the loop after | |
| | | * removing the current node). | |
| | | * | |
| | | * @code | |
| | | * extern Eina_List *list; | |
| | | * Eina_List *l; | |
| | | * extern void *my_data; | |
| | | * void *data | |
| | | * | |
| | | * EINA_LIST_FOREACH(list, l, data) | |
| | | * { | |
| | | * if (data == my_data) | |
| | | * { | |
| | | * list = eina_list_remove_list(list, l); | |
| | | * break; | |
| | | * } | |
| | | * } | |
| | | * @endcode | |
| | | * | |
| | | * @warning @p list must be a pointer to the first element of the list. | |
| | | */ | |
| EAPI Eina_List *eina_list_remove_list(Eina_List *list, Eina_List
*remove_list) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; | | EAPI Eina_List *eina_list_remove_list(Eina_List *list, Eina_List
*remove_list) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; | |
| | | | |
|
| | | /** | |
| | | * @brief Move the specified data to the head of the list. | |
| | | * | |
| | | * @param list The list handle to move the data. | |
| | | * @param move_list The list node to move. | |
| | | * @return A new list handle to replace the old one | |
| | | * | |
| | | * This function move @p move_list to the front of @p list. If list is | |
| | | * @c NULL, @c NULL is returned. If @p move_list is @c NULL, | |
| | | * @p list is returned. Otherwise, a new list pointer that should be | |
| | | * used in place of the one passed to this function. | |
| | | * | |
| | | * Example: | |
| | | * @code | |
| | | * extern Eina_List *list; | |
| | | * Eina_List *l; | |
| | | * extern void *my_data; | |
| | | * void *data; | |
| | | * | |
| | | * EINA_LIST_FOREACH(list, l, data) | |
| | | * { | |
| | | * if (data == my_data) | |
| | | * { | |
| | | * list = eina_list_promote_list(list, l); | |
| | | * break; | |
| | | * } | |
| | | * } | |
| | | * @endcode | |
| | | * | |
| | | * @warning @p list must be a pointer to the first element of the list. | |
| | | */ | |
| EAPI Eina_List *eina_list_promote_list(Eina_List *list, Eina_Lis
t *move_list) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; | | EAPI Eina_List *eina_list_promote_list(Eina_List *list, Eina_Lis
t *move_list) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; | |
| | | | |
|
| | | /** | |
| | | * @brief Move the specified data to the tail of the list. | |
| | | * | |
| | | * @param list The list handle to move the data. | |
| | | * @param move_list The list node to move. | |
| | | * @return A new list handle to replace the old one | |
| | | * | |
| | | * This function move @p move_list to the back of @p list. If list is | |
| | | * @c NULL, @c NULL is returned. If @p move_list is @c NULL, | |
| | | * @p list is returned. Otherwise, a new list pointer that should be | |
| | | * used in place of the one passed to this function. | |
| | | * | |
| | | * Example: | |
| | | * @code | |
| | | * extern Eina_List *list; | |
| | | * Eina_List *l; | |
| | | * extern void *my_data; | |
| | | * void *data; | |
| | | * | |
| | | * EINA_LIST_FOREACH(list, l, data) | |
| | | * { | |
| | | * if (data == my_data) | |
| | | * { | |
| | | * list = eina_list_demote_list(list, l); | |
| | | * break; | |
| | | * } | |
| | | * } | |
| | | * @endcode | |
| | | * | |
| | | * @warning @p list must be a pointer to the first element of the list. | |
| | | */ | |
| EAPI Eina_List *eina_list_demote_list(Eina_List *list, Eina_List
*move_list); | | EAPI Eina_List *eina_list_demote_list(Eina_List *list, Eina_List
*move_list); | |
| | | | |
|
| | | /** | |
| | | * @brief Find a member of a list and return the member. | |
| | | * | |
| | | * @param list The list to search for a data. | |
| | | * @param data The data pointer to find in the list. | |
| | | * @return The found member data pointer if found, @c NULL otherwise. | |
| | | * | |
| | | * This function searches in @p list from beginning to end for the | |
| | | * first member whose data pointer is @p data. If it is found, @p data | |
| | | * will be returned, otherwise NULL will be returned. | |
| | | * | |
| | | * Example: | |
| | | * @code | |
| | | * extern Eina_List *list; | |
| | | * extern void *my_data; | |
| | | * | |
| | | * if (eina_list_data_find(list, my_data) == my_data) | |
| | | * { | |
| | | * printf("Found member %p\n", my_data); | |
| | | * } | |
| | | * @endcode | |
| | | * | |
| | | * @warning @p list must be a pointer to the first element of the list. | |
| | | */ | |
| EAPI void *eina_list_data_find(const Eina_List *list, const
void *data) EINA_PURE EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; | | EAPI void *eina_list_data_find(const Eina_List *list, const
void *data) EINA_PURE EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; | |
|
| | | | |
| | | /** | |
| | | * @brief Find a member of a list and return the list node containing that | |
| | | member. | |
| | | * | |
| | | * @param list The list to search for data. | |
| | | * @param data The data pointer to find in the list. | |
| | | * @return The found members list node on success, @c NULL otherwise. | |
| | | * | |
| | | * This function searches in @p list from beginning to end for the | |
| | | * first member whose data pointer is @p data. If it is found, the | |
| | | * list node containing the specified member is returned, otherwise | |
| | | * @c NULL is returned. | |
| | | * | |
| | | * @warning @p list must be a pointer to the first element of the list. | |
| | | */ | |
| 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; | | 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; | |
|
| | | | |
| | | /** | |
| | | * @brief Move a data pointer from one list to another | |
| | | * | |
| | | * @param to The list to move the data to | |
| | | * @param from The list to move from | |
| | | * @param data The data to move | |
| | | * @return #EINA_TRUE on success, else #EINA_FALSE | |
| | | * | |
| | | * This function is a shortcut for doing the following: | |
| | | * to = eina_list_append(to, data); | |
| | | * from = eina_list_remove(from, data); | |
| | | * | |
| | | * @warning @p list must be a pointer to the first element of the list. | |
| | | */ | |
| | | EAPI Eina_Bool eina_list_move(Eina_List **to, Eina_List **from, | |
| | | void *data); | |
| | | | |
| | | /** | |
| | | * @brief Move a list node from one list to another | |
| | | * | |
| | | * @param to The list to move the data to | |
| | | * @param from The list to move from | |
| | | * @param data The list node containing the data to move | |
| | | * @return #EINA_TRUE on success, else #EINA_FALSE | |
| | | * | |
| | | * This function is a shortcut for doing the following: | |
| | | * to = eina_list_append(to, data->data); | |
| | | * from = eina_list_remove_list(from, data); | |
| | | * | |
| | | * @warning @p list must be a pointer to the first element of the list. | |
| | | */ | |
| | | EAPI Eina_Bool eina_list_move_list(Eina_List **to, Eina_List ** | |
| | | from, Eina_List *data); | |
| | | | |
| | | /** | |
| | | * @brief Free an entire list and all the nodes, ignoring the data containe | |
| | | d. | |
| | | | |
| | | * @param list The list to free | |
| | | * @return A NULL pointer | |
| | | * | |
| | | * This function frees all the nodes of @p list. It does not free the | |
| | | * data of the nodes. To free them, use #EINA_LIST_FREE. | |
| | | */ | |
| EAPI Eina_List *eina_list_free(Eina_List *list); | | EAPI Eina_List *eina_list_free(Eina_List *list); | |
| | | | |
|
| | | /** | |
| | | * @brief Get the nth member's data pointer in a list. | |
| | | * | |
| | | * @param list The list to get the specified member number from. | |
| | | * @param n The number of the element (0 being the first). | |
| | | * @return The data pointer stored in the specified element. | |
| | | * | |
| | | * This function returns the data pointer of element number @p n, in | |
| | | * the @p list. The first element in the array is element number 0. If | |
| | | * the element number @p n does not exist, @c NULL is | |
| | | * returned. Otherwise, the data of the found element is returned. | |
| | | * | |
| | | * @note Worst case is O(n). | |
| | | * | |
| | | * @warning @p list must be a pointer to the first element of the list. | |
| | | */ | |
| EAPI void *eina_list_nth(const Eina_List *list, unsigned in
t n) EINA_PURE EINA_WARN_UNUSED_RESULT; | | EAPI void *eina_list_nth(const Eina_List *list, unsigned in
t n) EINA_PURE EINA_WARN_UNUSED_RESULT; | |
| | | | |
|
| | | /** | |
| | | * @brief Get the nth member's list node in a list. | |
| | | * | |
| | | * @param list The list to get the specfied member number from. | |
| | | * @param n The number of the element (0 being the first). | |
| | | * @return The list node stored in the numbered element. | |
| | | * | |
| | | * This function returns the list node of element number @p n, in | |
| | | * @p list. The first element in the array is element number 0. If the | |
| | | * element number @p n does not exist or @p list is @c NULL or @p n is | |
| | | * greater than the count of elements in @p list minus 1, @c NULL is | |
| | | * returned. Otherwise the list node stored in the numbered element is | |
| | | * returned. | |
| | | * | |
| | | * @note Worst case is O(n). | |
| | | * | |
| | | * @warning @p list must be a pointer to the first element of the list. | |
| | | */ | |
| EAPI Eina_List *eina_list_nth_list(const Eina_List *list, unsign
ed int n) EINA_PURE EINA_WARN_UNUSED_RESULT; | | EAPI Eina_List *eina_list_nth_list(const Eina_List *list, unsign
ed int n) EINA_PURE EINA_WARN_UNUSED_RESULT; | |
| | | | |
|
| | | /** | |
| | | * @brief Reverse all the elements in the list. | |
| | | * | |
| | | * @param list The list to reverse. | |
| | | * @return The list head after it has been reversed. | |
| | | * | |
| | | * This function reverses the order of all elements in @p list, so the | |
| | | * last member is now first, and so on. If @p list is @c NULL, this | |
| | | * functon returns @c NULL. | |
| | | * | |
| | | * @note @b in-place: this will change the given list, so you should | |
| | | * now point to the new list head that is returned by this function. | |
| | | * | |
| | | * @warning @p list must be a pointer to the first element of the list. | |
| | | * | |
| | | * @see eina_list_reverse_clone() | |
| | | * @see eina_list_iterator_reversed_new() | |
| | | */ | |
| EAPI Eina_List *eina_list_reverse(Eina_List *list) EINA_WARN_UNU
SED_RESULT; | | EAPI Eina_List *eina_list_reverse(Eina_List *list) EINA_WARN_UNU
SED_RESULT; | |
| | | | |
|
| | | /** | |
| | | * @brief Clone (copy) all the elements in the list in reverse order. | |
| | | * | |
| | | * @param list The list to reverse. | |
| | | * @return The new list that has been reversed. | |
| | | * | |
| | | * This function reverses the order of all elements in @p list, so the | |
| | | * last member is now first, and so on. If @p list is @c NULL, this | |
| | | * functon returns @c NULL. This returns a copy of the given list. | |
| | | * | |
| | | * @note @b copy: this will copy the list and you should then | |
| | | * eina_list_free() when it is not required anymore. | |
| | | * | |
| | | * @warning @p list must be a pointer to the first element of the list. | |
| | | * | |
| | | * @see eina_list_reverse() | |
| | | * @see eina_list_clone() | |
| | | */ | |
| EAPI Eina_List *eina_list_reverse_clone(const Eina_List *list) E
INA_WARN_UNUSED_RESULT; | | EAPI Eina_List *eina_list_reverse_clone(const Eina_List *list) E
INA_WARN_UNUSED_RESULT; | |
| | | | |
|
| | | /** | |
| | | * @brief Clone (copy) all the elements in the list in exactly same order. | |
| | | * | |
| | | * @param list The list to clone. | |
| | | * @return The new list that has been cloned. | |
| | | * | |
| | | * This function clone in order of all elements in @p list. If @p list | |
| | | * is @c NULL, this functon returns @c NULL. This returns a copy of | |
| | | * the given list. | |
| | | * | |
| | | * @note @b copy: this will copy the list and you should then | |
| | | * eina_list_free() when it is not required anymore. | |
| | | * | |
| | | * @warning @p list must be a pointer to the first element of the list. | |
| | | * | |
| | | * @see eina_list_reverse_clone() | |
| | | */ | |
| EAPI Eina_List *eina_list_clone(const Eina_List *list) EINA_WARN
_UNUSED_RESULT; | | EAPI Eina_List *eina_list_clone(const Eina_List *list) EINA_WARN
_UNUSED_RESULT; | |
| | | | |
|
| | | /** | |
| | | * @brief Sort a list according to the ordering func will return. | |
| | | * | |
| | | * @param list The list handle to sort. | |
| | | * @param size The length of the list to sort. | |
| | | * @param func A function pointer that can handle comparing the list data | |
| | | * nodes. | |
| | | * @return the new head of list. | |
| | | * | |
| | | * This function sorts @p list. @p size if the number of the first | |
| | | * element to sort. If @p size is 0 or greater than the number of | |
| | | * elements in @p list, all the elements are sorted. @p func is used to | |
| | | * compare two elements of @p list. If @p list or @p func are @c NULL, | |
| | | * this function returns @c NULL. | |
| | | * | |
| | | * @note @b in-place: this will change the given list, so you should | |
| | | * now point to the new list head that is returned by this function. | |
| | | * | |
| | | * @note worst case is O(n * log2(n)) comparisons (calls to func()), | |
| | | * O(n) comparisons average case. That means that for 1,000,000 list | |
| | | * elements, sort will usually do 1,000,000 comparisons, but may do up | |
| | | * to 20,000,000. | |
| | | * | |
| | | * Example: | |
| | | * @code | |
| | | * int | |
| | | * sort_cb(const void *d1, const void *d2) | |
| | | * { | |
| | | * const char *txt = d1; | |
| | | * const char *txt2 = d2; | |
| | | * | |
| | | * if(!txt) return(1); | |
| | | * if(!txt2) return(-1); | |
| | | * | |
| | | * return(strcmp(txt, txt2)); | |
| | | * } | |
| | | * extern Eina_List *list; | |
| | | * | |
| | | * list = eina_list_sort(list, eina_list_count(list), sort_cb); | |
| | | * @endcode | |
| | | * | |
| | | * @warning @p list must be a pointer to the first element of the list. | |
| | | */ | |
| EAPI Eina_List *eina_list_sort(Eina_List *list, unsigned int siz
e, Eina_Compare_Cb func) EINA_ARG_NONNULL(3) EINA_WARN_UNUSED_RESULT; | | EAPI Eina_List *eina_list_sort(Eina_List *list, unsigned int siz
e, Eina_Compare_Cb func) EINA_ARG_NONNULL(3) EINA_WARN_UNUSED_RESULT; | |
| | | | |
|
| | | /** | |
| | | * @brief Merge two list. | |
| | | * | |
| | | * @param left Head list to merge. | |
| | | * @param right Tail list to merge. | |
| | | * @return A new merged list. | |
| | | * | |
| | | * This function puts right at the end of left and return the head. | |
| | | * | |
| | | * Both left and right does not exist anymore after the merge. | |
| | | * | |
| | | * @note merge cost is O(n), being @b n the size of the smallest | |
| | | * list. This is due the need to fix accounting of that segment, | |
| | | * making count and last access O(1). | |
| | | * | |
| | | * @warning @p list must be a pointer to the first element of the list. | |
| | | */ | |
| EAPI Eina_List *eina_list_merge(Eina_List *left, Eina_List *righ
t) EINA_WARN_UNUSED_RESULT; | | EAPI Eina_List *eina_list_merge(Eina_List *left, Eina_List *righ
t) EINA_WARN_UNUSED_RESULT; | |
| | | | |
|
| | | /** | |
| | | * @brief Merge two sorted list according to the ordering func will return. | |
| | | * | |
| | | * @param left First list to merge. | |
| | | * @param right Second list to merge. | |
| | | * @param func A function pointer that can handle comparing the list data | |
| | | * nodes. | |
| | | * @return A new sorted list. | |
| | | * | |
| | | * This function compares the head of @p left and @p right, and choose the | |
| | | * smallest one to be head of the returned list. It will continue this proc | |
| | | ess | |
| | | * for all entry of both list. | |
| | | * | |
| | | * Both left and right does not exist anymore after the merge. | |
| | | * If @p func is NULL, it will return NULL. | |
| | | * | |
| | | * Example: | |
| | | * @code | |
| | | * int | |
| | | * sort_cb(void *d1, void *d2) | |
| | | * { | |
| | | * const char *txt = NULL; | |
| | | * const char *txt2 = NULL; | |
| | | * | |
| | | * if(!d1) return(1); | |
| | | * if(!d2) return(-1); | |
| | | * | |
| | | * return(strcmp((const char*)d1, (const char*)d2)); | |
| | | * } | |
| | | * extern Eina_List *sorted1; | |
| | | * extern Eina_List *sorted2; | |
| | | * | |
| | | * list = eina_list_sorted_merge(sorted1, sorted2, sort_cb); | |
| | | * @endcode | |
| | | * | |
| | | * @warning @p list must be a pointer to the first element of the list. | |
| | | */ | |
| EAPI Eina_List *eina_list_sorted_merge(Eina_List *left, Eina_Lis
t *right, Eina_Compare_Cb func) EINA_ARG_NONNULL(3) EINA_WARN_UNUSED_RESULT
; | | EAPI Eina_List *eina_list_sorted_merge(Eina_List *left, Eina_Lis
t *right, Eina_Compare_Cb func) EINA_ARG_NONNULL(3) EINA_WARN_UNUSED_RESULT
; | |
| | | | |
|
| | | /** | |
| | | * @brief Split a list into 2 lists. | |
| | | * | |
| | | * @param list List to split. | |
| | | * @param relative The list will be split after @p relative. | |
| | | * @param right The head of the new right list. | |
| | | * @return The new left list | |
| | | * | |
| | | * This function splits @p list into two lists ( left and right ) after the | |
| | | node @p relative. @p Relative | |
| | | * will become the last node of the left list. If @p list or @p right are N | |
| | | ULL list is returns. | |
| | | * If @p relative is NULL right is set to @p list and NULL is returns. | |
| | | * If @p relative is the last node of @p list list is returns and @p right | |
| | | is set to NULL. | |
| | | * | |
| | | * list does not exist anymore after the split. | |
| | | * | |
| | | * @warning @p list must be a pointer to the first element of the list. | |
| | | */ | |
| EAPI Eina_List *eina_list_split_list(Eina_List *list, Eina_List
*relative, Eina_List **right) EINA_WARN_UNUSED_RESULT; | | EAPI Eina_List *eina_list_split_list(Eina_List *list, Eina_List
*relative, Eina_List **right) EINA_WARN_UNUSED_RESULT; | |
| | | | |
|
| | | /** | |
| | | * @brief Returns node nearest to data is in the sorted list. | |
| | | * | |
| | | * @param list The list to search for data, @b must be sorted. | |
| | | * @param func A function pointer that can handle comparing the list data n | |
| | | odes. | |
| | | * @param data reference value to search. | |
| | | * @param result_cmp if provided returns the result of | |
| | | * func(node->data, data) node being the last (returned) node. If node | |
| | | * was found (exact match), then it is 0. If returned node is smaller | |
| | | * than requested data, it is less than 0 and if it's bigger it's | |
| | | * greater than 0. It is the last value returned by func(). | |
| | | * @return the nearest node, NULL if not found. | |
| | | * | |
| | | * This function searches for a node containing @p data as it's data in @p | |
| | | list, | |
| | | * if such a node exists it will be returned and @p result_cmp will be @p 0 | |
| | | . If | |
| | | * the data of no node in @p list is equal to @p data, the node with the ne | |
| | | arest | |
| | | * value to that will be returned and @p result_cmp will be the return valu | |
| | | e of | |
| | | * @p func with @p data and the returned node's data as arguments. | |
| | | * | |
| | | * This function is useful for inserting an element in the list only in cas | |
| | | e it | |
| | | * isn't already present in the list, the naive way of doing this would be: | |
| | | * @code | |
| | | * void *ptr = eina_list_data_find(list, "my data"); | |
| | | * if (!ptr) | |
| | | * eina_list_sorted_insert(list, "my data"); | |
| | | * @endcode | |
| | | * | |
| | | * However this has the downside of walking through the list twice, once to | |
| | | * check if the data is already present and another to insert the element i | |
| | | n the | |
| | | * corret position. This can be done more eficiently: | |
| | | * @code | |
| | | * int cmp_result; | |
| | | * l = eina_list_search_sorted_near_list(list, cmp_func, "my data", | |
| | | * &cmp_result); | |
| | | * if (cmp_result > 0) | |
| | | * list = eina_list_prepend_relative_list(list, "my data", l); | |
| | | * else if (cmp_result < 0) | |
| | | * list = eina_list_append_relative_list(list, "my data", l); | |
| | | * @endcode | |
| | | * | |
| | | * If @a cmp_result is 0 the element is already in the list and we need not | |
| | | * insert it, if @a cmp_result is greater than zero @a "my @a data" needs t | |
| | | o | |
| | | * come after @a l(the nearest node present), if less than zero before. | |
| | | * | |
| | | * @note O(log2(n)) average/worst case performance, for 1,000,000 | |
| | | * elements it will do a maximum of 20 comparisons. This is much | |
| | | * faster than the 1,000,000 comparisons made naively walking the list | |
| | | * from head to tail, so depending on the number of searches and | |
| | | * insertions, it may be worth to eina_list_sort() the list and do the | |
| | | * searches later. As lists do not have O(1) access time, walking to | |
| | | * the correct node can be costly, consider worst case to be almost | |
| | | * O(n) pointer dereference (list walk). | |
| | | * | |
| | | * @warning @p list must be a pointer to the first element of the list. | |
| | | * | |
| | | * @see eina_list_search_sorted_list() | |
| | | * @see eina_list_sort() | |
| | | * @see eina_list_sorted_merge() | |
| | | */ | |
| EAPI Eina_List *eina_list_search_sorted_near_list(const Eina_Lis
t *list, Eina_Compare_Cb func, const void *data, int *result_cmp); | | EAPI Eina_List *eina_list_search_sorted_near_list(const Eina_Lis
t *list, Eina_Compare_Cb func, const void *data, int *result_cmp); | |
| | | | |
|
| | | /** | |
| | | * @brief Returns node if data is in the sorted list. | |
| | | * | |
| | | * @param list The list to search for data, @b must be sorted. | |
| | | * @param func A function pointer that can handle comparing the list data n | |
| | | odes. | |
| | | * @param data reference value to search. | |
| | | * @return the node if func(node->data, data) == 0, NULL if not found. | |
| | | * | |
| | | * This can be used to check if some value is inside the list and get | |
| | | * the container node in this case. It should be used when list is | |
| | | * known to be sorted as it will do binary search for results. | |
| | | * | |
| | | * Example: imagine user gives a string, you check if it's in the list | |
| | | * before duplicating its contents. | |
| | | * | |
| | | * @note O(log2(n)) average/worst case performance, for 1,000,000 | |
| | | * elements it will do a maximum of 20 comparisons. This is much | |
| | | * faster than the 1,000,000 comparisons made by | |
| | | * eina_list_search_unsorted_list(), so depending on the number of | |
| | | * searches and insertions, it may be worth to eina_list_sort() the | |
| | | * list and do the searches later. As said in | |
| | | * eina_list_search_sorted_near_list(), lists do not have O(1) access | |
| | | * time, so walking to the correct node can be costly, consider worst | |
| | | * case to be almost O(n) pointer dereference (list walk). | |
| | | * | |
| | | * @warning @p list must be a pointer to the first element of the list. | |
| | | * | |
| | | * @see eina_list_search_sorted() | |
| | | * @see eina_list_sort() | |
| | | * @see eina_list_sorted_merge() | |
| | | * @see eina_list_search_unsorted_list() | |
| | | * @see eina_list_search_sorted_near_list() | |
| | | */ | |
| EAPI Eina_List *eina_list_search_sorted_list(const Eina_List *li
st, Eina_Compare_Cb func, const void *data); | | EAPI Eina_List *eina_list_search_sorted_list(const Eina_List *li
st, Eina_Compare_Cb func, const void *data); | |
| | | | |
|
| | | /** | |
| | | * @brief Returns node data if it is in the sorted list. | |
| | | * | |
| | | * @param list The list to search for data, @b must be sorted. | |
| | | * @param func A function pointer that can handle comparing the list data n | |
| | | odes. | |
| | | * @param data reference value to search. | |
| | | * @return the node value (@c node->data) if func(node->data, data) == 0, | |
| | | * NULL if not found. | |
| | | * | |
| | | * This can be used to check if some value is inside the list and get | |
| | | * the existing instance in this case. It should be used when list is | |
| | | * known to be sorted as it will do binary search for results. | |
| | | * | |
| | | * Example: imagine user gives a string, you check if it's in the list | |
| | | * before duplicating its contents. | |
| | | * | |
| | | * @note O(log2(n)) average/worst case performance, for 1,000,000 | |
| | | * elements it will do a maximum of 20 comparisons. This is much | |
| | | * faster than the 1,000,000 comparisons made by | |
| | | * eina_list_search_unsorted(), so depending on the number of | |
| | | * searches and insertions, it may be worth to eina_list_sort() the | |
| | | * list and do the searches later. As said in | |
| | | * eina_list_search_sorted_near_list(), lists do not have O(1) access | |
| | | * time, so walking to the correct node can be costly, consider worst | |
| | | * case to be almost O(n) pointer dereference (list walk). | |
| | | * | |
| | | * @warning @p list must be a pointer to the first element of the list. | |
| | | * | |
| | | * @see eina_list_search_sorted_list() | |
| | | * @see eina_list_sort() | |
| | | * @see eina_list_sorted_merge() | |
| | | * @see eina_list_search_unsorted_list() | |
| | | */ | |
| EAPI void *eina_list_search_sorted(const Eina_List *list, E
ina_Compare_Cb func, const void *data); | | EAPI void *eina_list_search_sorted(const Eina_List *list, E
ina_Compare_Cb func, const void *data); | |
| | | | |
|
| | | /** | |
| | | * @brief Returns node if data is in the unsorted list. | |
| | | * | |
| | | * @param list The list to search for data, may be unsorted. | |
| | | * @param func A function pointer that can handle comparing the list data n | |
| | | odes. | |
| | | * @param data reference value to search. | |
| | | * @return the node if func(node->data, data) == 0, NULL if not found. | |
| | | * | |
| | | * This can be used to check if some value is inside the list and get | |
| | | * the container node in this case. | |
| | | * | |
| | | * Example: imagine user gives a string, you check if it's in the list | |
| | | * before duplicating its contents. | |
| | | * | |
| | | * @note this is expensive and may walk the whole list, it's order-N, | |
| | | * that is for 1,000,000 elements list it may walk and compare | |
| | | * 1,000,000 nodes. | |
| | | * | |
| | | * @warning @p list must be a pointer to the first element of the list. | |
| | | * | |
| | | * @see eina_list_search_sorted_list() | |
| | | * @see eina_list_search_unsorted() | |
| | | */ | |
| EAPI Eina_List *eina_list_search_unsorted_list(const Eina_List *
list, Eina_Compare_Cb func, const void *data); | | EAPI Eina_List *eina_list_search_unsorted_list(const Eina_List *
list, Eina_Compare_Cb func, const void *data); | |
| | | | |
|
| | | /** | |
| | | * @brief Returns node data if it is in the unsorted list. | |
| | | * | |
| | | * @param list The list to search for data, may be unsorted. | |
| | | * @param func A function pointer that can handle comparing the list data n | |
| | | odes. | |
| | | * @param data reference value to search. | |
| | | * @return the node value (@c node->data) if func(node->data, data) == 0, | |
| | | * NULL if not found. | |
| | | * | |
| | | * This can be used to check if some value is inside the list and get | |
| | | * the existing instance in this case. | |
| | | * | |
| | | * Example: imagine user gives a string, you check if it's in the list | |
| | | * before duplicating its contents. | |
| | | * | |
| | | * @note this is expensive and may walk the whole list, it's order-N, | |
| | | * that is for 1,000,000 elements list it may walk and compare | |
| | | * 1,000,000 nodes. | |
| | | * | |
| | | * @warning @p list must be a pointer to the first element of the list. | |
| | | * | |
| | | * @see eina_list_search_sorted() | |
| | | * @see eina_list_search_unsorted_list() | |
| | | */ | |
| EAPI void *eina_list_search_unsorted(const Eina_List *list,
Eina_Compare_Cb func, const void *data); | | EAPI void *eina_list_search_unsorted(const Eina_List *list,
Eina_Compare_Cb func, const void *data); | |
| | | | |
|
| | | /** | |
| | | * @brief Get the last list node in the list. | |
| | | * | |
| | | * @param list The list to get the last list node from. | |
| | | * @return The last list node in the list. | |
| | | * | |
| | | * This function returns the last list node in the list @p list. If | |
| | | * @p list is @c NULL or empty, @c NULL is returned. | |
| | | * | |
| | | * This is a order-1 operation (it takes the same short time | |
| | | * regardless of the length of the list). | |
| | | * | |
| | | * @warning @p list must be a pointer to the first element of the list. | |
| | | */ | |
| static inline Eina_List *eina_list_last(const Eina_List *list) EINA_PURE
EINA_WARN_UNUSED_RESULT; | | static inline Eina_List *eina_list_last(const Eina_List *list) EINA_PURE
EINA_WARN_UNUSED_RESULT; | |
| | | | |
|
| | | /** | |
| | | * @brief Get the next list node after the specified list node. | |
| | | * | |
| | | * @param list The list node to get the next list node from | |
| | | * @return The next list node on success, @c NULL otherwise. | |
| | | * | |
| | | * This function returns the next list node after the current one in | |
| | | * @p list. It is equivalent to list->next. If @p list is @c NULL or | |
| | | * if no next list node exists, it returns @c NULL. | |
| | | * | |
| | | * @warning @p list must be a pointer to the first element of the list. | |
| | | */ | |
| static inline Eina_List *eina_list_next(const Eina_List *list) EINA_PURE
EINA_WARN_UNUSED_RESULT; | | static inline Eina_List *eina_list_next(const Eina_List *list) EINA_PURE
EINA_WARN_UNUSED_RESULT; | |
| | | | |
|
| | | /** | |
| | | * @brief Get the previous list node before the specified list node. | |
| | | * | |
| | | * @param list The list node to get the previous list node from. | |
| | | * @return The previous list node o success, @c NULL otherwise. | |
| | | * if no previous list node exists | |
| | | * | |
| | | * This function returns the previous list node before the current one | |
| | | * in @p list. It is equivalent to list->prev. If @p list is @c NULL or | |
| | | * if no previous list node exists, it returns @c NULL. | |
| | | * | |
| | | * @warning @p list must be a pointer to the first element of the list. | |
| | | */ | |
| static inline Eina_List *eina_list_prev(const Eina_List *list) EINA_PURE
EINA_WARN_UNUSED_RESULT; | | static inline Eina_List *eina_list_prev(const Eina_List *list) EINA_PURE
EINA_WARN_UNUSED_RESULT; | |
| | | | |
|
| | | /** | |
| | | * @brief Get the list node data member. | |
| | | * | |
| | | * @param list The list node to get the data member of. | |
| | | * @return The data member from the list node. | |
| | | * | |
| | | * This function returns the data member of the specified list node @p | |
| | | * list. It is equivalent to list->data. If @p list is @c NULL, this | |
| | | * function returns @c NULL. | |
| | | * | |
| | | * @warning @p list must be a pointer to the first element of the list. | |
| | | */ | |
| static inline void *eina_list_data_get(const Eina_List *list) EINA_P
URE EINA_WARN_UNUSED_RESULT; | | static inline void *eina_list_data_get(const Eina_List *list) EINA_P
URE EINA_WARN_UNUSED_RESULT; | |
| | | | |
|
| | | /** | |
| | | * @brief Set the list node data member. | |
| | | * | |
| | | * @param list The list node to get the data member of. | |
| | | * @param data The data member to the list node. | |
| | | * @return The previous data value. | |
| | | * | |
| | | * This function set the data member @p data of the specified list node | |
| | | * @p list. It returns the previous data of the node. If @p list is | |
| | | * @c NULL, this function returns @c NULL. | |
| | | * | |
| | | * @warning @p list must be a pointer to the first element of the list. | |
| | | */ | |
| | | static inline void *eina_list_data_set(Eina_List *list, const void * | |
| | | data); | |
| | | | |
| | | /** | |
| | | * @brief Get the count of the number of items in a list. | |
| | | * | |
| | | * @param list The list whose count to return. | |
| | | * @return The number of members in the list. | |
| | | * | |
| | | * This function returns how many members @p list contains. If the | |
| | | * list is @c NULL, 0 is returned. | |
| | | * | |
| | | * NB: This is an order-1 operation and takes the same time regardless | |
| | | * of the length of the list. | |
| | | * | |
| | | * @warning @p list must be a pointer to the first element of the list. | |
| | | */ | |
| static inline unsigned int eina_list_count(const Eina_List *list) EINA_PURE
; | | static inline unsigned int eina_list_count(const Eina_List *list) EINA_PURE
; | |
| | | | |
|
| | | /** | |
| | | * @brief Returned a new iterator associated to a list. | |
| | | * | |
| | | * @param list The list. | |
| | | * @return A new iterator. | |
| | | * | |
| | | * This function returns a newly allocated iterator associated to @p | |
| | | * list. If @p list is @c NULL or the count member of @p list is less | |
| | | * or equal than 0, this function still returns a valid iterator that | |
| | | * will always return false on eina_iterator_next(), thus keeping API | |
| | | * sane. | |
| | | * | |
| | | * If the memory can not be allocated, NULL is returned and | |
| | | * #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is | |
| | | * returned. | |
| | | * | |
| | | * @warning @p list must be a pointer to the first element of the list. | |
| | | * | |
| | | * @warning if the list structure changes then the iterator becomes | |
| | | * invalid! That is, if you add or remove nodes this iterator | |
| | | * behavior is undefined and your program may crash! | |
| | | */ | |
| EAPI Eina_Iterator *eina_list_iterator_new(const Eina_List *list) EI
NA_MALLOC EINA_WARN_UNUSED_RESULT; | | EAPI Eina_Iterator *eina_list_iterator_new(const Eina_List *list) EI
NA_MALLOC EINA_WARN_UNUSED_RESULT; | |
| | | | |
|
| | | /** | |
| | | * @brief Returned a new reversed iterator associated to a list. | |
| | | * | |
| | | * @param list The list. | |
| | | * @return A new iterator. | |
| | | * | |
| | | * This function returns a newly allocated iterator associated to @p | |
| | | * list. If @p list is @c NULL or the count member of @p list is less | |
| | | * or equal than 0, this function still returns a valid iterator that | |
| | | * will always return false on eina_iterator_next(), thus keeping API | |
| | | * sane. | |
| | | * | |
| | | * Unlike eina_list_iterator_new(), this will walk the list backwards. | |
| | | * | |
| | | * If the memory can not be allocated, NULL is returned and | |
| | | * #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is | |
| | | * returned. | |
| | | * | |
| | | * @warning @p list must be a pointer to the first element of the list. | |
| | | * | |
| | | * @warning if the list structure changes then the iterator becomes | |
| | | * invalid! That is, if you add or remove nodes this iterator | |
| | | * behavior is undefined and your program may crash! | |
| | | */ | |
| EAPI Eina_Iterator *eina_list_iterator_reversed_new(const Eina_List
*list) EINA_MALLOC EINA_WARN_UNUSED_RESULT; | | EAPI Eina_Iterator *eina_list_iterator_reversed_new(const Eina_List
*list) EINA_MALLOC EINA_WARN_UNUSED_RESULT; | |
| | | | |
|
| | | /** | |
| | | * @brief Returned a new accessor associated to a list. | |
| | | * | |
| | | * @param list The list. | |
| | | * @return A new accessor. | |
| | | * | |
| | | * This function returns a newly allocated accessor associated to | |
| | | * @p list. If @p list is @c NULL or the count member of @p list is | |
| | | * less or equal than 0, this function returns NULL. If the memory can | |
| | | * not be allocated, NULL is returned and #EINA_ERROR_OUT_OF_MEMORY is | |
| | | * set. Otherwise, a valid accessor is returned. | |
| | | * | |
| | | * @warning @p list must be a pointer to the first element of the list. | |
| | | */ | |
| EAPI Eina_Accessor *eina_list_accessor_new(const Eina_List *list) EI
NA_MALLOC EINA_WARN_UNUSED_RESULT; | | EAPI Eina_Accessor *eina_list_accessor_new(const Eina_List *list) EI
NA_MALLOC EINA_WARN_UNUSED_RESULT; | |
| | | | |
| /** | | /** | |
| * @def EINA_LIST_FOREACH | | * @def EINA_LIST_FOREACH | |
| * @brief Macro to iterate over a list. | | * @brief Macro to iterate over a list. | |
| * | | * | |
| * @param list The list to iterate over. | | * @param list The list to iterate over. | |
| * @param l A list that is used as an iterator and points to the current no
de. | | * @param l A list that is used as an iterator and points to the current no
de. | |
| * @param data Current item's data. | | * @param data Current item's data. | |
| * | | * | |
| * This macro iterates over @p list from the first element to | | * This macro iterates over @p list from the first element to | |
| * the last. @p data is the data related to the current element. | | * the last. @p data is the data related to the current element. | |
| * @p l is an #Eina_List used as the list iterator. | | * @p l is an #Eina_List used as the list iterator. | |
| * | | * | |
|
| | | * The following diagram ilustrates this macro iterating over a list of fou | |
| | | r | |
| | | * elements("one", "two", "three" and "four"): | |
| | | * @htmlonly | |
| | | * <img src="eina-list-foreach.png" style="max-width: 100%;" /> | |
| | | * <a href="eina-list-foreach.png">Full-size</a> | |
| | | * @endhtmlonly | |
| | | * @image latex eina-list-foreach.eps width=\textwidth | |
| | | * | |
| * It can be used to free list data, as in the following example: | | * It can be used to free list data, as in the following example: | |
| * | | * | |
| * @code | | * @code | |
| * Eina_List *list; | | * Eina_List *list; | |
| * Eina_List *l; | | * Eina_List *l; | |
| * char *data; | | * char *data; | |
| * | | * | |
| * // list is already filled, | | * // list is already filled, | |
| * // its elements are just duplicated strings, | | * // its elements are just duplicated strings, | |
| * // EINA_LIST_FOREACH will be used to free those strings | | * // EINA_LIST_FOREACH will be used to free those strings | |
| * | | * | |
| * EINA_LIST_FOREACH(list, l, data) | | * EINA_LIST_FOREACH(list, l, data) | |
| * free(data); | | * free(data); | |
| * eina_list_free(list); | | * eina_list_free(list); | |
| * @endcode | | * @endcode | |
| * | | * | |
| * @note This is not the optimal way to release memory allocated to | | * @note This is not the optimal way to release memory allocated to | |
| * a list, since it iterates over the list twice. | | * a list, since it iterates over the list twice. | |
| * For an optimized algorithm, use EINA_LIST_FREE(). | | * For an optimized algorithm, use EINA_LIST_FREE(). | |
| * | | * | |
|
| | | * @warning @p list must be a pointer to the first element of the list. | |
| | | * | |
| * @warning Be careful when deleting list nodes. | | * @warning Be careful when deleting list nodes. | |
| * If you remove the current node and continue iterating, | | * If you remove the current node and continue iterating, | |
| * the code will fail because the macro will not be able | | * the code will fail because the macro will not be able | |
| * to get the next node. Notice that it's OK to remove any | | * to get the next node. Notice that it's OK to remove any | |
| * node if you stop the loop after that. | | * node if you stop the loop after that. | |
| * For destructive operations such as this, consider | | * For destructive operations such as this, consider | |
| * using EINA_LIST_FOREACH_SAFE(). | | * using EINA_LIST_FOREACH_SAFE(). | |
| */ | | */ | |
| #define EINA_LIST_FOREACH(list, l, data) \ | | #define EINA_LIST_FOREACH(list, l, data) \ | |
| for (l = list, \ | | for (l = list, \ | |
| | | | |
| skipping to change at line 219 | | skipping to change at line 1390 | |
|---|
| * | | * | |
| * @param list The list to iterate over. | | * @param list The list to iterate over. | |
| * @param l A list that is used as an iterator and points to the current no
de. | | * @param l A list that is used as an iterator and points to the current no
de. | |
| * @param data Current item's data. | | * @param data Current item's data. | |
| * | | * | |
| * This macro works like EINA_LIST_FOREACH, but iterates from the | | * This macro works like EINA_LIST_FOREACH, but iterates from the | |
| * last element of a list to the first. | | * last element of a list to the first. | |
| * @p data is the data related to the current element, while @p l | | * @p data is the data related to the current element, while @p l | |
| * is an #Eina_List that is used as the list iterator. | | * is an #Eina_List that is used as the list iterator. | |
| * | | * | |
|
| | | * The following diagram ilustrates this macro iterating over a list of fou | |
| | | r | |
| | | * elements("one", "two", "three" and "four"): | |
| | | * @htmlonly | |
| | | * <img src="eina-list-reverse-foreach.png" style="max-width: 100%;" /> | |
| | | * <a href="eina-list-reverse-foreach.png">Full-size</a> | |
| | | * @endhtmlonly | |
| | | * @image latex eina-list-reverse-foreach.eps width=\textwidth | |
| | | * | |
| * It can be used to free list data, as in the following example: | | * It can be used to free list data, as in the following example: | |
| * | | * | |
| * @code | | * @code | |
| * Eina_List *list; | | * Eina_List *list; | |
| * Eina_List *l; | | * Eina_List *l; | |
| * char *data; | | * char *data; | |
| * | | * | |
| * // list is already filled, | | * // list is already filled, | |
| * // its elements are just duplicated strings, | | * // its elements are just duplicated strings, | |
| * // EINA_LIST_REVERSE_FOREACH will be used to free those strings | | * // EINA_LIST_REVERSE_FOREACH will be used to free those strings | |
| * | | * | |
| * EINA_LIST_REVERSE_FOREACH(list, l, data) | | * EINA_LIST_REVERSE_FOREACH(list, l, data) | |
| * free(data); | | * free(data); | |
| * eina_list_free(list); | | * eina_list_free(list); | |
| * @endcode | | * @endcode | |
| * | | * | |
| * @note This is not the optimal way to release memory allocated to | | * @note This is not the optimal way to release memory allocated to | |
| * a list, since it iterates over the list twice. | | * a list, since it iterates over the list twice. | |
| * For an optimized algorithm, use EINA_LIST_FREE(). | | * For an optimized algorithm, use EINA_LIST_FREE(). | |
| * | | * | |
|
| | | * @warning @p list must be a pointer to the first element of the list. | |
| | | * | |
| * @warning Be careful when deleting list nodes. | | * @warning Be careful when deleting list nodes. | |
| * If you remove the current node and continue iterating, | | * If you remove the current node and continue iterating, | |
| * the code will fail because the macro will not be able | | * the code will fail because the macro will not be able | |
| * to get the next node. Notice that it's OK to remove any | | * to get the next node. Notice that it's OK to remove any | |
| * node if you stop the loop after that. | | * node if you stop the loop after that. | |
| * For destructive operations such as this, consider | | * For destructive operations such as this, consider | |
| * using EINA_LIST_REVERSE_FOREACH_SAFE(). | | * using EINA_LIST_REVERSE_FOREACH_SAFE(). | |
| */ | | */ | |
| #define EINA_LIST_REVERSE_FOREACH(list, l, data) \ | | #define EINA_LIST_REVERSE_FOREACH(list, l, data) \ | |
| for (l = eina_list_last(list), \ | | for (l = eina_list_last(list), \ | |
| | | | |
| skipping to change at line 270 | | skipping to change at line 1451 | |
|---|
| * @param l_next A list that is used as an iterator and points to the next
node. | | * @param l_next A list that is used as an iterator and points to the next
node. | |
| * @param data Current item's data. | | * @param data Current item's data. | |
| * | | * | |
| * This macro iterates over @p list from the first element to | | * This macro iterates over @p list from the first element to | |
| * the last. @p data is the data related to the current element. | | * the last. @p data is the data related to the current element. | |
| * @p l is an #Eina_List used as the list iterator. | | * @p l is an #Eina_List used as the list iterator. | |
| * | | * | |
| * Since this macro stores a pointer to the next list node in @p l_next, | | * Since this macro stores a pointer to the next list node in @p l_next, | |
| * deleting the current node and continuing looping is safe. | | * deleting the current node and continuing looping is safe. | |
| * | | * | |
|
| | | * The following diagram ilustrates this macro iterating over a list of fou | |
| | | r | |
| | | * elements("one", "two", "three" and "four"): | |
| | | * @htmlonly | |
| | | * <img src="eina-list-foreach-safe.png" style="max-width: 100%;" /> | |
| | | * <a href="eina-list-foreach-safe.png">Full-size</a> | |
| | | * @endhtmlonly | |
| | | * @image latex eina-list-foreach-safe.eps width=\textwidth | |
| | | * | |
| * This macro can be used to free list nodes, as in the following example: | | * This macro can be used to free list nodes, as in the following example: | |
| * | | * | |
| * @code | | * @code | |
| * Eina_List *list; | | * Eina_List *list; | |
| * Eina_List *l; | | * Eina_List *l; | |
| * Eina_List *l_next; | | * Eina_List *l_next; | |
| * char *data; | | * char *data; | |
| * | | * | |
| * // list is already filled, | | * // list is already filled, | |
| * // its elements are just duplicated strings, | | * // its elements are just duplicated strings, | |
| * // EINA_LIST_FOREACH_SAFE will be used to free elements that match "key"
. | | * // EINA_LIST_FOREACH_SAFE will be used to free elements that match "key"
. | |
| * | | * | |
| * EINA_LIST_FOREACH_SAFE(list, l, l_next, data) | | * EINA_LIST_FOREACH_SAFE(list, l, l_next, data) | |
| * if (strcmp(data, "key") == 0) { | | * if (strcmp(data, "key") == 0) { | |
| * free(data); | | * free(data); | |
| * list = eina_list_remove_list(list, l); | | * list = eina_list_remove_list(list, l); | |
| * } | | * } | |
| * @endcode | | * @endcode | |
|
| | | * | |
| | | * @warning @p list must be a pointer to the first element of the list. | |
| */ | | */ | |
| #define EINA_LIST_FOREACH_SAFE(list, l, l_next, data) \ | | #define EINA_LIST_FOREACH_SAFE(list, l, l_next, data) \ | |
| for (l = list, \ | | for (l = list, \ | |
| l_next = eina_list_next(l), \ | | l_next = eina_list_next(l), \ | |
| data = eina_list_data_get(l); \ | | data = eina_list_data_get(l); \ | |
| l; \ | | l; \ | |
| l = l_next, \ | | l = l_next, \ | |
| l_next = eina_list_next(l), \ | | l_next = eina_list_next(l), \ | |
| data = eina_list_data_get(l)) | | data = eina_list_data_get(l)) | |
| | | | |
| | | | |
| skipping to change at line 316 | | skipping to change at line 1507 | |
|---|
| * @param data Current item's data. | | * @param data Current item's data. | |
| * | | * | |
| * This macro works like EINA_LIST_FOREACH_SAFE, but iterates from the | | * This macro works like EINA_LIST_FOREACH_SAFE, but iterates from the | |
| * last element of a list to the first. | | * last element of a list to the first. | |
| * @p data is the data related to the current element, while @p l | | * @p data is the data related to the current element, while @p l | |
| * is an #Eina_List that is used as the list iterator. | | * is an #Eina_List that is used as the list iterator. | |
| * | | * | |
| * Since this macro stores a pointer to the previous list node in @p l_prev
, | | * Since this macro stores a pointer to the previous list node in @p l_prev
, | |
| * deleting the current node and continuing looping is safe. | | * deleting the current node and continuing looping is safe. | |
| * | | * | |
|
| | | * The following diagram ilustrates this macro iterating over a list of fou | |
| | | r | |
| | | * elements("one", "two", "three" and "four"): | |
| | | * @htmlonly | |
| | | * <img src="eina-list-reverse-foreach-safe.png" style="max-width: 100%;" / | |
| | | > | |
| | | * <a href="eina-list-reverse-foreach-safe.png">Full-size</a> | |
| | | * @endhtmlonly | |
| | | * @image latex eina-list-reverse-foreach-safe.eps width=\textwidth | |
| | | * | |
| * This macro can be used to free list nodes, as in the following example: | | * This macro can be used to free list nodes, as in the following example: | |
| * | | * | |
| * @code | | * @code | |
| * Eina_List *list; | | * Eina_List *list; | |
| * Eina_List *l; | | * Eina_List *l; | |
| * Eina_List *l_prev; | | * Eina_List *l_prev; | |
| * char *data; | | * char *data; | |
| * | | * | |
| * // list is already filled, | | * // list is already filled, | |
| * // its elements are just duplicated strings, | | * // its elements are just duplicated strings, | |
| * // EINA_LIST_REVERSE_FOREACH_SAFE will be used to free elements that mat
ch "key". | | * // EINA_LIST_REVERSE_FOREACH_SAFE will be used to free elements that mat
ch "key". | |
| * | | * | |
| * EINA_LIST_REVERSE_FOREACH_SAFE(list, l, l_prev, data) | | * EINA_LIST_REVERSE_FOREACH_SAFE(list, l, l_prev, data) | |
| * if (strcmp(data, "key") == 0) { | | * if (strcmp(data, "key") == 0) { | |
| * free(data); | | * free(data); | |
| * list = eina_list_remove_list(list, l); | | * list = eina_list_remove_list(list, l); | |
| * } | | * } | |
| * @endcode | | * @endcode | |
|
| | | * | |
| | | * @warning @p list must be a pointer to the first element of the list. | |
| */ | | */ | |
| #define EINA_LIST_REVERSE_FOREACH_SAFE(list, l, l_prev, data) \ | | #define EINA_LIST_REVERSE_FOREACH_SAFE(list, l, l_prev, data) \ | |
| for (l = eina_list_last(list), \ | | for (l = eina_list_last(list), \ | |
| l_prev = eina_list_prev(l), \ | | l_prev = eina_list_prev(l), \ | |
| data = eina_list_data_get(l); \ | | data = eina_list_data_get(l); \ | |
| l; \ | | l; \ | |
| l = l_prev, \ | | l = l_prev, \ | |
| l_prev = eina_list_prev(l), \ | | l_prev = eina_list_prev(l), \ | |
| data = eina_list_data_get(l)) | | data = eina_list_data_get(l)) | |
| | | | |
| /** | | /** | |
| * @def EINA_LIST_FREE | | * @def EINA_LIST_FREE | |
| * @brief Macro to remove each list node while having access to each node's
data. | | * @brief Macro to remove each list node while having access to each node's
data. | |
| * | | * | |
| * @param list The list that will be cleared. | | * @param list The list that will be cleared. | |
| * @param data Current node's data. | | * @param data Current node's data. | |
| * | | * | |
| * This macro will call #eina_list_remove_list for each list node, and stor
e | | * This macro will call #eina_list_remove_list for each list node, and stor
e | |
| * the data contained in the current node in @p data. | | * the data contained in the current node in @p data. | |
| * | | * | |
|
| | | * The following diagram ilustrates this macro iterating over a list of fou | |
| | | r | |
| | | * elements("one", "two", "three" and "four"): | |
| | | * @htmlonly | |
| | | * <img src="eina-list-free.png" style="max-width: 100%;" /> | |
| | | * <a href="eina-list-free.png">Full-size</a> | |
| | | * @endhtmlonly | |
| | | * @image latex eina-list-free.eps width=\textwidth | |
| | | * | |
| * If you do not need to release node data, it is easier to call #eina_list
_free(). | | * If you do not need to release node data, it is easier to call #eina_list
_free(). | |
| * | | * | |
| * @code | | * @code | |
| * Eina_List *list; | | * Eina_List *list; | |
| * char *data; | | * char *data; | |
| * | | * | |
| * // list is already filled, | | * // list is already filled, | |
| * // its elements are just duplicated strings, | | * // its elements are just duplicated strings, | |
| * | | * | |
| * EINA_LIST_FREE(list, data) | | * EINA_LIST_FREE(list, data) | |
| * free(data); | | * free(data); | |
| * @endcode | | * @endcode | |
| * | | * | |
|
| | | * @warning @p list must be a pointer to the first element of the list. | |
| | | * | |
| * @see eina_list_free() | | * @see eina_list_free() | |
| */ | | */ | |
| #define EINA_LIST_FREE(list, data) \ | | #define EINA_LIST_FREE(list, data) \ | |
| for (data = eina_list_data_get(list); \ | | for (data = eina_list_data_get(list); \ | |
| list; \ | | list; \ | |
| list = eina_list_remove_list(list, list), \ | | list = eina_list_remove_list(list, list), \ | |
| data = eina_list_data_get(list)) | | data = eina_list_data_get(list)) | |
| | | | |
| #include "eina_inline_list.x" | | #include "eina_inline_list.x" | |
| | | | |
| | | | |
| End of changes. 47 change blocks. |
|---|
| 0 lines changed or deleted | | 1282 lines changed or added | |
|---|
|
| eina_log.h | | eina_log.h | |
|---|
| | | | |
| skipping to change at line 41 | | skipping to change at line 41 | |
|---|
| #define EINA_COLOR_GREEN "\033[32;1m" | | #define EINA_COLOR_GREEN "\033[32;1m" | |
| #define EINA_COLOR_YELLOW "\033[33;1m" | | #define EINA_COLOR_YELLOW "\033[33;1m" | |
| #define EINA_COLOR_ORANGE "\033[0;33m" | | #define EINA_COLOR_ORANGE "\033[0;33m" | |
| #define EINA_COLOR_WHITE "\033[37;1m" | | #define EINA_COLOR_WHITE "\033[37;1m" | |
| #define EINA_COLOR_LIGHTCYAN "\033[36;1m" | | #define EINA_COLOR_LIGHTCYAN "\033[36;1m" | |
| #define EINA_COLOR_CYAN "\033[36m" | | #define EINA_COLOR_CYAN "\033[36m" | |
| #define EINA_COLOR_RESET "\033[0m" | | #define EINA_COLOR_RESET "\033[0m" | |
| #define EINA_COLOR_HIGH "\033[1m" | | #define EINA_COLOR_HIGH "\033[1m" | |
| | | | |
| /** | | /** | |
|
| | | * @page tutorial_log_page Log Tutorial | |
| | | * | |
| | | * @section tutorial_log_introduction Introduction | |
| | | * | |
| | | * The Eina Log module provides logging facilities for libraries and | |
| | | * applications. It provides colored logging, basic logging levels (error, | |
| | | * warning, debug, info, critical) and loggers - called logging domains - | |
| | | * which will be covered on next sections. | |
| | | * | |
| | | * @section tutorial_log_basic_usage Basic Usage | |
| | | * | |
| | | * Log messages can be displayed using the following macros: | |
| | | * | |
| | | * @li EINA_LOG_ERR(), | |
| | | * @li EINA_LOG_INFO(), | |
| | | * @li EINA_LOG_WARN(), | |
| | | * @li EINA_LOG_DBG(). | |
| | | * | |
| | | * Here is an example: | |
| | | * | |
| | | * @include eina_log_02.c | |
| | | * | |
| | | * If you compiled Eina without debug mode, execution will yield only one l | |
| | | og | |
| | | * message, which is "argument is negative". | |
| | | * | |
| | | * Here we introduce the concept of logging domains (or loggers), which mig | |
| | | ht | |
| | | * already be familiar to readers. It is basically a way to separate a set | |
| | | of | |
| | | * log messages into a context (e.g. a module) and provide a way of control | |
| | | ling | |
| | | * this set as a whole. | |
| | | * | |
| | | * For example, suppose you have 3 different modules on your application an | |
| | | d you | |
| | | * want to get logging only from one of them (e.g. create some sort of filt | |
| | | er). | |
| | | * For achieving that, all you need to do is create a logging domain for ea | |
| | | ch | |
| | | * module so that all logging inside a module can be considered as a whole. | |
| | | * | |
| | | * Logging domains are specified by a name, color applied to the name and t | |
| | | he | |
| | | * level. The first two (name and color) are set through code, that is, ins | |
| | | ide | |
| | | * your application/module/library. | |
| | | * | |
| | | * The level is used for controlling which messages should appear. It | |
| | | * specifies the lowest level that should be displayed (e.g. a message | |
| | | * with level 11 being logged on a domain with level set to 10 would be | |
| | | * displayed, while a message with level 9 wouldn't). | |
| | | * | |
| | | * The domain level is set during runtime (in contrast with the name and | |
| | | * color) through the environment variable EINA_LOG_LEVELS. This variable | |
| | | * expects a list in the form domain_name1:level1,domain_name2:level2,... . | |
| | | For | |
| | | * example: | |
| | | * | |
| | | * @verbatim EINA_LOG_LEVELS=mymodule1:5,mymodule2:2,mymodule3:0 ./myapp@en | |
| | | dverbatim | |
| | | * | |
| | | * This line would set mymodule1 level to 5, mymodule2 level to 2 and mymod | |
| | | ule3 | |
| | | * level to 0. | |
| | | * | |
| | | * There's also a global logger to which EINA_LOG_(ERR, DBG, INFO, CRIT, WA | |
| | | RN) | |
| | | * macros do log on. It is a logger that is created internally by Eina Log | |
| | | with | |
| | | * an empty name and can be used for general logging (where logging domains | |
| | | do | |
| | | * not apply). | |
| | | * | |
| | | * Since this global logger doesn't have a name, you can't set its level th | |
| | | rough | |
| | | * EINA_LOG_LEVELS variable. Here we introduce a second environment variabl | |
| | | e | |
| | | * that is a bit more special: EINA_LOG_LEVEL. | |
| | | * | |
| | | * This variable specifies the level of the global logging domain and the l | |
| | | evel | |
| | | * of domains that haven't been set through EINA_LOG_LEVELS. Here's an exam | |
| | | ple: | |
| | | * | |
| | | * @verbatim EINA_LOG_LEVEL=3 EINA_LOG_LEVELS=module1:10,module3:2 ./myapp@ | |
| | | endverbatim | |
| | | * | |
| | | * Supposing you have modules named "module1", "module2" and "module3", thi | |
| | | s | |
| | | * line would result in module1 with level 10, module2 with level 3 and mod | |
| | | ule3 | |
| | | * with level 2. Note that module2's level wasn't specified, so it's level | |
| | | is | |
| | | * set to the global level. This way we can easily apply filters to multipl | |
| | | e | |
| | | * domains with only one parameter (EINA_LOG_LEVEL=num). | |
| | | * | |
| | | * The global level (EINA_LOG_LEVEL) can also be set through code, using | |
| | | * eina_log_level_set() function. | |
| | | * | |
| | | * While developing your libraries or applications, you may notice that | |
| | | * EINA_LOG_DOM_(ERR, DBG, INFO, CRIT, WARN) macros also print out | |
| | | * messages from eina itself. Here we introduce another environment variabl | |
| | | e | |
| | | * that is a bit more special: EINA_LOG_LEVELS_GLOB. | |
| | | * | |
| | | * This variable allows you to disable the logging of any/all code in eina | |
| | | itself. | |
| | | * This is useful when developing your libraries or applications so that yo | |
| | | u can | |
| | | * see your own domain's messages easier without having to sift through a l | |
| | | ot of | |
| | | * internal eina debug messages. Here's an example: | |
| | | * | |
| | | * @verbatim EINA_LOG_LEVEL=3 EINA_LOG_LEVELS_GLOB=eina_*:0 ./myapp@endverb | |
| | | atim | |
| | | * | |
| | | * This will disable eina_log output from all internal eina code thus allow | |
| | | ing | |
| | | * you to see your own domain messages easier. | |
| | | * | |
| | | * @section tutorial_log_advanced_display Advanced usage of print callbacks | |
| | | * | |
| | | * The log module allows the user to change the way | |
| | | * eina_log_print() displays the messages. It suffices to pass to | |
| | | * eina_log_print_cb_set() the function used to display the | |
| | | * message. That function must be of type #Eina_Log_Print_Cb. As a | |
| | | * custom data can be passed to that callback, powerful display | |
| | | * messages can be displayed. | |
| | | * | |
| | | * It is suggested to not use __FILE__, __FUNCTION__ or __LINE__ when | |
| | | * writing that callback, but when defining macros (like | |
| | | * EINA_LOG_ERR() and other macros). | |
| | | * | |
| | | * Here is an example of custom callback, whose behavior can be | |
| | | * changed at runtime: | |
| | | * | |
| | | * @include eina_log_03.c | |
| | | * @example eina_log_02.c | |
| | | * @example eina_log_03.c | |
| | | */ | |
| | | | |
| | | /** | |
| | | * @addtogroup Eina_Log_Group Log | |
| | | * | |
| | | * @brief Full-featured logging system. | |
| | | * | |
| | | * Eina provides eina_log_print(), a standard function to manage all | |
| | | * logging messages. This function may be called directly or using the | |
| | | * helper macros such as EINA_LOG_DBG(), EINA_LOG_ERR() or those that | |
| | | * take a specific domain as argument EINA_LOG_DOM_DBG(), | |
| | | * EINA_LOG_DOM_ERR(). Internally, eina_log_print() will call the | |
| | | * function defined with eina_log_print_cb_set(), that defaults to | |
| | | * eina_log_print_cb_stderr(), but may be changed to do whatever you | |
| | | * need, such as networking or syslog logging. | |
| | | * | |
| | | * The logging system is thread safe once initialized with | |
| | | * eina_log_threads_enable(). The thread that calls this function | |
| | | * first is considered "main thread" and other threads will have their | |
| | | * thread id (pthread_self()) printed in the log message so it is easy | |
| | | * to detect from where it is coming. | |
| | | * | |
| | | * Log domains is the Eina way to differentiate messages. There might | |
| | | * be different domains to represent different modules, different | |
| | | * feature-set, different categories and so on. Filtering can be | |
| | | * applied to domain names by means of @c EINA_LOG_LEVELS environment | |
| | | * variable or eina_log_domain_level_set(). | |
| | | * | |
| | | * The different logging levels serve to customize the amount of | |
| | | * debugging one want to take and may be used to automatically call | |
| | | * abort() once some given level message is printed. This is | |
| | | * controlled by environment variable @c EINA_LOG_ABORT and the level | |
| | | * to be considered critical with @c EINA_LOG_ABORT_LEVEL. These can | |
| | | * be changed with eina_log_abort_on_critical_set() and | |
| | | * eina_log_abort_on_critical_level_set(). | |
| | | * | |
| | | * The default maximum level to print is defined by environment | |
| | | * variable @c EINA_LOG_LEVEL, but may be set per-domain with @c | |
| | | * EINA_LOG_LEVELS. It will default to #EINA_LOG_ERR. This can be | |
| | | * changed with eina_log_level_set(). | |
| | | * | |
| | | * To use the log system Eina must be initialized with eina_init() and | |
| | | * later shut down with eina_shutdown(). Here is a straightforward | |
| | | * example: | |
| | | * | |
| | | * @include eina_log_01.c | |
| | | * | |
| | | * Compile this code with the following command: | |
| | | * | |
| | | * @verbatim gcc -Wall -o eina_log_01 eina_log_01.c `pkg-config --cflags -- | |
| | | libs eina`@endverbatim | |
| | | * | |
| | | * Now execute the program with: | |
| | | * | |
| | | * @verbatim EINA_LOG_LEVEL=2 ./eina_log_01@endverbatim | |
| | | * | |
| | | * You should see a message displayed in the terminal. | |
| | | * | |
| | | * For more information, you can look at the @ref tutorial_log_page. | |
| | | * | |
| | | * @example eina_log_01.c | |
| | | */ | |
| | | | |
| | | /** | |
| * @addtogroup Eina_Tools_Group Tools | | * @addtogroup Eina_Tools_Group Tools | |
| * | | * | |
| * @{ | | * @{ | |
| */ | | */ | |
| | | | |
| /** | | /** | |
| * @defgroup Eina_Log_Group Log | | * @defgroup Eina_Log_Group Log | |
| * | | * | |
| * @{ | | * @{ | |
| */ | | */ | |
| | | | |
| skipping to change at line 242 | | skipping to change at line 416 | |
|---|
| { | | { | |
| int level; /**< Max level to log */ | | int level; /**< Max level to log */ | |
| const char *domain_str; /**< Formatted string with color to print */ | | const char *domain_str; /**< Formatted string with color to print */ | |
| const char *name; /**< Domain name */ | | const char *name; /**< Domain name */ | |
| size_t namelen; /**< strlen(name) */ | | size_t namelen; /**< strlen(name) */ | |
| | | | |
| /* Private */ | | /* Private */ | |
| Eina_Bool deleted : 1; /**< Flags deletion of domain, a free slot */ | | Eina_Bool deleted : 1; /**< Flags deletion of domain, a free slot */ | |
| }; | | }; | |
| | | | |
|
| | | /** | |
| | | * Enable logging module to handle threads. | |
| | | * | |
| | | * There is no disable option on purpose, if it is enabled, there is | |
| | | * no way back until you call the last eina_shutdown(). | |
| | | * | |
| | | * There is no function to retrieve if threads are enabled as one is | |
| | | * not supposed to know this from outside. | |
| | | * | |
| | | * After this call is executed at least once, if Eina was compiled | |
| | | * with threads support then logging will lock around debug messages | |
| | | * and threads that are not the main thread will have its identifier | |
| | | * printed. | |
| | | * | |
| | | * The main thread is considered the thread where the first | |
| | | * eina_init() was called. | |
| | | */ | |
| EAPI void eina_log_threads_enable(void); | | EAPI void eina_log_threads_enable(void); | |
| | | | |
| /** | | /** | |
| * @enum _Eina_Log_Level | | * @enum _Eina_Log_Level | |
| * List of available logging levels. | | * List of available logging levels. | |
| */ | | */ | |
| typedef enum _Eina_Log_Level | | typedef enum _Eina_Log_Level | |
| { | | { | |
| EINA_LOG_LEVEL_CRITICAL, /**< Critical log level */ | | EINA_LOG_LEVEL_CRITICAL, /**< Critical log level */ | |
| EINA_LOG_LEVEL_ERR, /**< Error log level */ | | EINA_LOG_LEVEL_ERR, /**< Error log level */ | |
| | | | |
| skipping to change at line 271 | | skipping to change at line 462 | |
|---|
| * Type for print callbacks. | | * Type for print callbacks. | |
| */ | | */ | |
| typedef void (*Eina_Log_Print_Cb)(const Eina_Log_Domain *d, | | typedef void (*Eina_Log_Print_Cb)(const Eina_Log_Domain *d, | |
| Eina_Log_Level level, | | Eina_Log_Level level, | |
| const char *file, const char *fnc, int li
ne, | | const char *file, const char *fnc, int li
ne, | |
| const char *fmt, void *data, va_list args
); | | const char *fmt, void *data, va_list args
); | |
| | | | |
| /* | | /* | |
| * Customization | | * Customization | |
| */ | | */ | |
|
| | | | |
| | | /** | |
| | | * Sets logging method to use. | |
| | | * | |
| | | * @param cb The callback to call when printing a log. | |
| | | * @param data The data to pass to the callback. | |
| | | * | |
| | | * By default, eina_log_print_cb_stderr() is used. | |
| | | * | |
| | | * @note MT: safe to call from any thread. | |
| | | * | |
| | | * @note MT: given function @a cb will be called protected by mutex. | |
| | | * This means you're safe from other calls but you should never | |
| | | * call eina_log_print(), directly or indirectly. | |
| | | */ | |
| EAPI void eina_log_print_cb_set(Eina_Log_Print_Cb cb, void *data) EINA_ARG_
NONNULL(1); | | EAPI void eina_log_print_cb_set(Eina_Log_Print_Cb cb, void *data) EINA_ARG_
NONNULL(1); | |
| | | | |
|
| | | /** | |
| | | * @brief Set the default log level. | |
| | | * | |
| | | * @param level The log level. | |
| | | * | |
| | | * This function sets the log level @p level. It is used in | |
| | | * eina_log_print(). | |
| | | * | |
| | | * @note this is initially set to envvar EINA_LOG_LEVEL by eina_init(). | |
| | | * | |
| | | * @see eina_log_level_get() | |
| | | */ | |
| EAPI void eina_log_level_set(int level); | | EAPI void eina_log_level_set(int level); | |
|
| | | | |
| | | /** | |
| | | * @brief Get the default log level. | |
| | | * | |
| | | * @return the log level that limits eina_log_print(). | |
| | | * | |
| | | * @see eina_log_level_set() | |
| | | */ | |
| EAPI int eina_log_level_get(void) EINA_WARN_UNUSED_RESULT; | | EAPI int eina_log_level_get(void) EINA_WARN_UNUSED_RESULT; | |
| | | | |
|
| static inline Eina_Bool | | static inline Eina_Bool eina_log_level_check(int level); | |
| eina_log_level_check(int level); | | | |
| | | | |
|
| | | /** | |
| | | * Checks if current thread is the main thread. | |
| | | * | |
| | | * @return #EINA_TRUE if threads were enabled and the current thread | |
| | | * is the one that called eina_log_threads_init(). If there is | |
| | | * no thread support (compiled with --disable-pthreads) or | |
| | | * they were not enabled, then #EINA_TRUE is also | |
| | | * returned. The only case where #EINA_FALSE is returned is | |
| | | * when threads were successfully enabled but the current | |
| | | * thread is not the main (one that called | |
| | | * eina_log_threads_init()). | |
| | | */ | |
| EAPI Eina_Bool eina_log_main_thread_check(void) EINA_CONST EINA_WA
RN_UNUSED_RESULT; | | EAPI Eina_Bool eina_log_main_thread_check(void) EINA_CONST EINA_WA
RN_UNUSED_RESULT; | |
| | | | |
|
| | | /** | |
| | | * @brief Set if color logging should be disabled. | |
| | | * | |
| | | * @param disabled if #EINA_TRUE, color logging should be disabled. | |
| | | * | |
| | | * @note this is initially set to envvar EINA_LOG_COLOR_DISABLE by eina_ini | |
| | | t(). | |
| | | * | |
| | | * @see eina_log_color_disable_get() | |
| | | */ | |
| EAPI void eina_log_color_disable_set(Eina_Bool disabled); | | EAPI void eina_log_color_disable_set(Eina_Bool disabled); | |
|
| | | | |
| | | /** | |
| | | * @brief Get if color logging should be disabled. | |
| | | * | |
| | | * @return if #EINA_TRUE, color logging should be disabled. | |
| | | * | |
| | | * @see eina_log_color_disable_set() | |
| | | */ | |
| EAPI Eina_Bool eina_log_color_disable_get(void) EINA_WARN_UNUSED_R
ESULT; | | EAPI Eina_Bool eina_log_color_disable_get(void) EINA_WARN_UNUSED_R
ESULT; | |
|
| | | | |
| | | /** | |
| | | * @brief Set if originating file name logging should be disabled. | |
| | | * | |
| | | * @param disabled if #EINA_TRUE, file name logging should be disabled. | |
| | | * | |
| | | * @note this is initially set to envvar EINA_LOG_FILE_DISABLE by eina_init | |
| | | (). | |
| | | * | |
| | | * @see eina_log_file_disable_get() | |
| | | */ | |
| EAPI void eina_log_file_disable_set(Eina_Bool disabled); | | EAPI void eina_log_file_disable_set(Eina_Bool disabled); | |
|
| | | | |
| | | /** | |
| | | * @brief Get if originating file name logging should be disabled. | |
| | | * | |
| | | * @return if #EINA_TRUE, file name logging should be disabled. | |
| | | * | |
| | | * @see eina_log_file_disable_set() | |
| | | */ | |
| EAPI Eina_Bool eina_log_file_disable_get(void) EINA_WARN_UNUSED_RE
SULT; | | EAPI Eina_Bool eina_log_file_disable_get(void) EINA_WARN_UNUSED_RE
SULT; | |
|
| | | | |
| | | /** | |
| | | * @brief Set if originating function name logging should be disabled. | |
| | | * | |
| | | * @param disabled if #EINA_TRUE, function name logging should be disabled. | |
| | | * | |
| | | * @note this is initially set to envvar EINA_LOG_FUNCTION_DISABLE by | |
| | | * eina_init(). | |
| | | * | |
| | | * @see eina_log_function_disable_get() | |
| | | */ | |
| EAPI void eina_log_function_disable_set(Eina_Bool disabled); | | EAPI void eina_log_function_disable_set(Eina_Bool disabled); | |
|
| | | | |
| | | /** | |
| | | * @brief Get if originating function name logging should be disabled. | |
| | | * | |
| | | * @return if #EINA_TRUE, function name logging should be disabled. | |
| | | * | |
| | | * @see eina_log_function_disable_set() | |
| | | */ | |
| EAPI Eina_Bool eina_log_function_disable_get(void) EINA_WARN_UNUSE
D_RESULT; | | EAPI Eina_Bool eina_log_function_disable_get(void) EINA_WARN_UNUSE
D_RESULT; | |
|
| | | | |
| | | /** | |
| | | * @brief Set if critical messages should abort the program. | |
| | | * | |
| | | * @param abort_on_critical if #EINA_TRUE, messages with level equal | |
| | | * or smaller than eina_log_abort_on_critical_level_get() will | |
| | | * abort the program. | |
| | | * | |
| | | * @note this is initially set to envvar EINA_LOG_ABORT by | |
| | | * eina_init(). | |
| | | * | |
| | | * @see eina_log_abort_on_critical_get() | |
| | | * @see eina_log_abort_on_critical_level_set() | |
| | | */ | |
| EAPI void eina_log_abort_on_critical_set(Eina_Bool abort_on_c
ritical); | | EAPI void eina_log_abort_on_critical_set(Eina_Bool abort_on_c
ritical); | |
|
| | | | |
| | | /** | |
| | | * @brief Get if critical messages should abort the program. | |
| | | * | |
| | | * @return if #EINA_TRUE, any messages with level equal or smaller | |
| | | * than eina_log_abort_on_critical_level_get() will abort the | |
| | | * program. | |
| | | * | |
| | | * @see eina_log_abort_on_critical_set() | |
| | | * @see eina_log_abort_on_critical_level_set() | |
| | | */ | |
| EAPI Eina_Bool eina_log_abort_on_critical_get(void) EINA_WARN_UNUS
ED_RESULT; | | EAPI Eina_Bool eina_log_abort_on_critical_get(void) EINA_WARN_UNUS
ED_RESULT; | |
|
| | | | |
| | | /** | |
| | | * @brief Set level that triggers abort if abort-on-critical is set. | |
| | | * | |
| | | * @param critical_level levels equal or smaller than the given value | |
| | | * will trigger program abortion if | |
| | | * eina_log_abort_on_critical_get() returns #EINA_TRUE. | |
| | | * | |
| | | * @note this is initially set to envvar EINA_LOG_ABORT_LEVEL by | |
| | | * eina_init(). | |
| | | * | |
| | | * @see eina_log_abort_on_critical_level_get() | |
| | | * @see eina_log_abort_on_critical_get() | |
| | | */ | |
| EAPI void eina_log_abort_on_critical_level_set(int critical_l
evel); | | EAPI void eina_log_abort_on_critical_level_set(int critical_l
evel); | |
|
| | | | |
| | | /** | |
| | | * @brief Get level that triggers abort if abort-on-critical is set. | |
| | | * | |
| | | * @return critical level equal or smaller than value will trigger | |
| | | * program abortion if eina_log_abort_on_critical_get() returns | |
| | | * #EINA_TRUE. | |
| | | * | |
| | | * @see eina_log_abort_on_critical_level_set() | |
| | | * @see eina_log_abort_on_critical_get() | |
| | | */ | |
| EAPI int eina_log_abort_on_critical_level_get(void) EINA_WAR
N_UNUSED_RESULT; | | EAPI int eina_log_abort_on_critical_level_get(void) EINA_WAR
N_UNUSED_RESULT; | |
| | | | |
|
| | | /** | |
| | | * Set the domain level given its name. | |
| | | * | |
| | | * This call has the same effect as setting | |
| | | * EINA_LOG_LEVELS=<@p domain_name>:<@p level> | |
| | | * | |
| | | * @param domain_name domain name to change the level. It may be of a | |
| | | * still not registered domain. If the domain is not registered | |
| | | * yet, it will be saved as a pending set and applied upon | |
| | | * registration. | |
| | | * @param level level to use to limit eina_log_print() for given domain. | |
| | | */ | |
| EAPI void eina_log_domain_level_set(const char *domain_name,
int level) EINA_ARG_NONNULL(1); | | EAPI void eina_log_domain_level_set(const char *domain_name,
int level) EINA_ARG_NONNULL(1); | |
|
| | | | |
| | | /** | |
| | | * Get the domain level given its name. | |
| | | * | |
| | | * @param domain_name domain name to retrieve the level. It may be of | |
| | | * a still not registered domain. If the domain is not | |
| | | * registered yet, but there is a pending value, either from | |
| | | * eina_log_domain_level_set(),EINA_LOG_LEVELS environment | |
| | | * variable or from EINA_LOG_LEVELS_GLOB, these are | |
| | | * returned. If nothing else was found, then the global/default | |
| | | * level (eina_log_level_get()) is returned. | |
| | | * | |
| | | * @return level to use to limit eina_log_print() for given | |
| | | * domain. On error (@p domain_name == NULL), | |
| | | * EINA_LOG_LEVEL_UNKNOWN is returned. | |
| | | * | |
| | | * @see eina_log_domain_level_set() | |
| | | * @see eina_log_domain_registered_level_get() | |
| | | */ | |
| EAPI int eina_log_domain_level_get(const char *domain_name)
EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); | | EAPI int eina_log_domain_level_get(const char *domain_name)
EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); | |
|
| | | | |
| | | /** | |
| | | * Get the domain level given its identifier. | |
| | | * | |
| | | * @param domain identifier, so it must be previously registered with | |
| | | * eina_log_domain_register(). It's a much faster version of | |
| | | * eina_log_domain_level_get(), but relies on domain being | |
| | | * present. | |
| | | * | |
| | | * @return level to use to limit eina_log_print() for given domain. On | |
| | | * error EINA_LOG_LEVEL_UNKNOWN is returned. | |
| | | */ | |
| EAPI int eina_log_domain_registered_level_get(int domain) EI
NA_WARN_UNUSED_RESULT; | | EAPI int eina_log_domain_registered_level_get(int domain) EI
NA_WARN_UNUSED_RESULT; | |
|
| | | | |
| static inline Eina_Bool eina_log_domain_level_check(int domain, int level); | | static inline Eina_Bool eina_log_domain_level_check(int domain, int level); | |
| | | | |
| /* | | /* | |
| * Logging domains | | * Logging domains | |
| */ | | */ | |
|
| | | | |
| | | /** | |
| | | * @param name Domain name | |
| | | * @param color Color of the domain name | |
| | | * | |
| | | * @return Domain index that will be used as the DOMAIN parameter on log | |
| | | * macros. A negative return value means an log occurred. | |
| | | * | |
| | | * @note MT: safe to call from any thread. | |
| | | */ | |
| EAPI int eina_log_domain_register(const char *name, const char *color) EIN
A_ARG_NONNULL(1); | | EAPI int eina_log_domain_register(const char *name, const char *color) EIN
A_ARG_NONNULL(1); | |
|
| | | | |
| | | /** | |
| | | * Forget about a logging domain registered by eina_log_domain_register() | |
| | | * | |
| | | * @param domain domain identifier as reported by eina_log_domain_register( | |
| | | ), | |
| | | * must be >= 0. | |
| | | * | |
| | | * @note MT: safe to call from any thread. | |
| | | */ | |
| EAPI void eina_log_domain_unregister(int domain); | | EAPI void eina_log_domain_unregister(int domain); | |
| | | | |
| /* | | /* | |
| * Logging functions. | | * Logging functions. | |
| */ | | */ | |
|
| | | | |
| | | /** | |
| | | * Print out log message using given domain and level. | |
| | | * | |
| | | * @note Usually you'll not use this function directly but the helper | |
| | | * macros EINA_LOG(), EINA_LOG_DOM_CRIT(), EINA_LOG_CRIT() and | |
| | | * so on. See eina_log.h | |
| | | * | |
| | | * @param domain logging domain to use or @c EINA_LOG_DOMAIN_GLOBAL if | |
| | | * you registered none. It is recommended that modules and | |
| | | * applications have their own logging domain. | |
| | | * @param level message level, those with level greater than user | |
| | | * specified value (eina_log_level_set() or environment | |
| | | * variables EINA_LOG_LEVEL, EINA_LOG_LEVELS) will be ignored. | |
| | | * @param file filename that originated the call, must @b not be @c NULL. | |
| | | * @param fnc function that originated the call, must @b not be @c NULL. | |
| | | * @param line originating line in @a file. | |
| | | * @param fmt printf-like format to use. Should not provide trailing | |
| | | * '\n' as it is automatically included. | |
| | | * | |
| | | * @note MT: this function may be called from different threads if | |
| | | * eina_log_threads_enable() was called before. | |
| | | */ | |
| EAPI void eina_log_print(int domain, | | EAPI void eina_log_print(int domain, | |
| Eina_Log_Level level, | | Eina_Log_Level level, | |
| const char *file, | | const char *file, | |
| const char *function, | | const char *function, | |
| int line, | | int line, | |
| const char *fmt, | | const char *fmt, | |
| ...) EINA_ARG_NONNULL(3, 4, 6) EINA_PRINTF(6, 7) E
INA_NOINSTRUMENT; | | ...) EINA_ARG_NONNULL(3, 4, 6) EINA_PRINTF(6, 7) E
INA_NOINSTRUMENT; | |
|
| | | | |
| | | /** | |
| | | * Print out log message using given domain and level. | |
| | | * | |
| | | * @note Usually you'll not use this function directly but the helper | |
| | | * macros EINA_LOG(), EINA_LOG_DOM_CRIT(), EINA_LOG_CRIT() and | |
| | | * so on. See eina_log.h | |
| | | * | |
| | | * @param domain logging domain to use or @c EINA_LOG_DOMAIN_GLOBAL if | |
| | | * you registered none. It is recommended that modules and | |
| | | * applications have their own logging domain. | |
| | | * @param level message level, those with level greater than user | |
| | | * specified value (eina_log_level_set() or environment | |
| | | * variables EINA_LOG_LEVEL, EINA_LOG_LEVELS) will be ignored. | |
| | | * @param file filename that originated the call, must @b not be @c NULL. | |
| | | * @param fnc function that originated the call, must @b not be @c NULL. | |
| | | * @param line originating line in @a file. | |
| | | * @param fmt printf-like format to use. Should not provide trailing | |
| | | * '\n' as it is automatically included. | |
| | | * @param args the arguments needed by the format. | |
| | | * | |
| | | * @note MT: this function may be called from different threads if | |
| | | * eina_log_threads_enable() was called before. | |
| | | * | |
| | | * @see eina_log_print() | |
| | | */ | |
| EAPI void eina_log_vprint(int domain, | | EAPI void eina_log_vprint(int domain, | |
| Eina_Log_Level level, | | Eina_Log_Level level, | |
| const char *file, | | const char *file, | |
| const char *fnc, | | const char *fnc, | |
| int line, | | int line, | |
| const char *fmt, | | const char *fmt, | |
| va_list args) EINA_ARG_NONNULL(3, 4, 6) EI
NA_NOINSTRUMENT; | | va_list args) EINA_ARG_NONNULL(3, 4, 6) EI
NA_NOINSTRUMENT; | |
| | | | |
| /* | | /* | |
| * Logging methods (change how logging is done). | | * Logging methods (change how logging is done). | |
| */ | | */ | |
|
| | | | |
| | | /** | |
| | | * Alternative logging method, this will output to standard output stream. | |
| | | * | |
| | | * @param d The domain. | |
| | | * @param level The level. | |
| | | * @param file The file which is logged. | |
| | | * @param fnc The function which is logged. | |
| | | * @param line The line which is logged. | |
| | | * @param fmt The ouptut format to use. | |
| | | * @param data Not used. | |
| | | * @param args The arguments needed by the format. | |
| | | * | |
| | | * This method will colorize output based on domain provided color and | |
| | | * message logging level. To disable color, set environment variable | |
| | | * EINA_LOG_COLOR_DISABLE=1. Similarly, to disable file and line | |
| | | * information, set EINA_LOG_FILE_DISABLE=1 or | |
| | | * EINA_LOG_FUNCTION_DISABLE=1 to avoid function name in output. It is | |
| | | * not acceptable to have both EINA_LOG_FILE_DISABLE and | |
| | | * EINA_LOG_FUNCTION_DISABLE at the same time, in this case just | |
| | | * EINA_LOG_FUNCTION_DISABLE will be considered and file information | |
| | | * will be printed anyways. | |
| | | * | |
| | | * @note MT: if threads are enabled, this function is called within locks. | |
| | | * @note MT: Threads different from main thread will have thread id | |
| | | * appended to domain name. | |
| | | */ | |
| EAPI void eina_log_print_cb_stdout(const Eina_Log_Domain *d, | | EAPI void eina_log_print_cb_stdout(const Eina_Log_Domain *d, | |
| Eina_Log_Level level, | | Eina_Log_Level level, | |
| const char *file, | | const char *file, | |
| const char *fnc, | | const char *fnc, | |
| int line, | | int line, | |
| const char *fmt, | | const char *fmt, | |
| void *data, | | void *data, | |
| va_list args); | | va_list args); | |
|
| | | | |
| | | /** | |
| | | * Default logging method, this will output to standard error stream. | |
| | | * | |
| | | * This method will colorize output based on domain provided color and | |
| | | * message logging level. | |
| | | * | |
| | | * To disable color, set environment variable | |
| | | * EINA_LOG_COLOR_DISABLE=1. To enable color, even if directing to a | |
| | | * file or when using a non-supported color terminal, use | |
| | | * EINA_LOG_COLOR_DISABLE=0. If EINA_LOG_COLOR_DISABLE is unset (or | |
| | | * -1), then Eina will disable color if terminal ($TERM) is | |
| | | * unsupported or if redirecting to a file. | |
| | | | |
| | | . Similarly, to disable file and line | |
| | | * information, set EINA_LOG_FILE_DISABLE=1 or | |
| | | * EINA_LOG_FUNCTION_DISABLE=1 to avoid function name in output. It is | |
| | | * not acceptable to have both EINA_LOG_FILE_DISABLE and | |
| | | * EINA_LOG_FUNCTION_DISABLE at the same time, in this case just | |
| | | * EINA_LOG_FUNCTION_DISABLE will be considered and file information | |
| | | * will be printed anyways. | |
| | | * | |
| | | * @note MT: if threads are enabled, this function is called within locks. | |
| | | * @note MT: Threads different from main thread will have thread id | |
| | | * appended to domain name. | |
| | | */ | |
| EAPI void eina_log_print_cb_stderr(const Eina_Log_Domain *d, | | EAPI void eina_log_print_cb_stderr(const Eina_Log_Domain *d, | |
| Eina_Log_Level level, | | Eina_Log_Level level, | |
| const char *file, | | const char *file, | |
| const char *fnc, | | const char *fnc, | |
| int line, | | int line, | |
| const char *fmt, | | const char *fmt, | |
| void *data, | | void *data, | |
| va_list args); | | va_list args); | |
|
| | | | |
| | | /** | |
| | | * Alternative logging method, this will output to given file stream. | |
| | | * | |
| | | * @param d The domain. | |
| | | * @param level Not used. | |
| | | * @param file The file which is logged. | |
| | | * @param fnc The function which is logged. | |
| | | * @param line The line which is logged. | |
| | | * @param fmt The ouptut format to use. | |
| | | * @param data The file which will store the output (as a FILE *). | |
| | | * @param args The arguments needed by the format. | |
| | | * | |
| | | * This method will never output color. | |
| | | * | |
| | | * @note MT: if threads are enabled, this function is called within locks. | |
| | | * @note MT: Threads different from main thread will have thread id | |
| | | * appended to domain name. | |
| | | */ | |
| EAPI void eina_log_print_cb_file(const Eina_Log_Domain *d, | | EAPI void eina_log_print_cb_file(const Eina_Log_Domain *d, | |
| Eina_Log_Level level, | | Eina_Log_Level level, | |
| const char *file, | | const char *file, | |
| const char *fnc, | | const char *fnc, | |
| int line, | | int line, | |
| const char *fmt, | | const char *fmt, | |
| void *data, | | void *data, | |
| va_list args); | | va_list args); | |
| | | | |
| #include "eina_inline_log.x" | | #include "eina_inline_log.x" | |
| | | | |
| End of changes. 28 change blocks. |
|---|
| 2 lines changed or deleted | | 561 lines changed or added | |
|---|
|
| eina_matrixsparse.h | | eina_matrixsparse.h | |
|---|
| | | | |
| skipping to change at line 31 | | skipping to change at line 31 | |
|---|
| | | | |
| #include <stdlib.h> | | #include <stdlib.h> | |
| | | | |
| #include "eina_config.h" | | #include "eina_config.h" | |
| | | | |
| #include "eina_types.h" | | #include "eina_types.h" | |
| #include "eina_iterator.h" | | #include "eina_iterator.h" | |
| #include "eina_accessor.h" | | #include "eina_accessor.h" | |
| | | | |
| /** | | /** | |
|
| | | * @addtogroup Eina_Matrixsparse_Group Sparse Matrix | |
| | | * | |
| | | * @brief These functions provide matrix sparse management. | |
| | | * | |
| | | * For more information, you can look at the @ref tutorial_matrixsparse_pag | |
| | | e. | |
| | | */ | |
| | | | |
| | | /** | |
| * @addtogroup Eina_Data_Types_Group Data Types | | * @addtogroup Eina_Data_Types_Group Data Types | |
| * | | * | |
| * @{ | | * @{ | |
| */ | | */ | |
| | | | |
| /** | | /** | |
| * @addtogroup Eina_Containers_Group Containers | | * @addtogroup Eina_Containers_Group Containers | |
| * | | * | |
| * @{ | | * @{ | |
| */ | | */ | |
| | | | |
| skipping to change at line 67 | | skipping to change at line 75 | |
|---|
| */ | | */ | |
| typedef struct _Eina_Matrixsparse_Row Eina_Matrixsparse_Row; | | typedef struct _Eina_Matrixsparse_Row Eina_Matrixsparse_Row; | |
| | | | |
| /** | | /** | |
| * @typedef Eina_Matrixsparse_Cell | | * @typedef Eina_Matrixsparse_Cell | |
| * Type for a generic sparse matrix cell, opaque for users. | | * Type for a generic sparse matrix cell, opaque for users. | |
| */ | | */ | |
| typedef struct _Eina_Matrixsparse_Cell Eina_Matrixsparse_Cell; | | typedef struct _Eina_Matrixsparse_Cell Eina_Matrixsparse_Cell; | |
| | | | |
| /* constructors and destructors */ | | /* constructors and destructors */ | |
|
| | | | |
| | | /** | |
| | | * @brief Create a new Sparse Matrix. | |
| | | * | |
| | | * @param rows number of rows in matrix. Operations with rows greater than | |
| | | this | |
| | | * value will fail. | |
| | | * @param cols number of columns in matrix. Operations with columns greater | |
| | | * than this value will fail. | |
| | | * @param free_func used to delete cell data contents, used by | |
| | | * eina_matrixsparse_free(), eina_matrixsparse_size_set(), | |
| | | * eina_matrixsparse_row_idx_clear(), | |
| | | * eina_matrixsparse_column_idx_clear(), | |
| | | * eina_matrixsparse_cell_idx_clear() and possible others. | |
| | | * @param user_data given to @a free_func as first parameter. | |
| | | * | |
| | | * @return newly allocated matrix or NULL if allocation failed and eina_err | |
| | | or | |
| | | * is set. | |
| | | */ | |
| EAPI Eina_Matrixsparse *eina_matrixsparse_new(unsigned long rows, | | EAPI Eina_Matrixsparse *eina_matrixsparse_new(unsigned long rows, | |
| unsigned long cols, | | unsigned long cols, | |
| void (*free_func)(void *user_
data, | | void (*free_func)(void *user_
data, | |
| void *cell_
data), | | void *cell_
data), | |
| const void *user_data); | | const void *user_data); | |
|
| | | | |
| | | /** | |
| | | * @brief Free resources allocated to Sparse Matrix. | |
| | | * | |
| | | * @param m The Sparse Matrix instance to free, must @b not be @c NULL. | |
| | | */ | |
| EAPI void eina_matrixsparse_free(Eina_Matrixsparse *m); | | EAPI void eina_matrixsparse_free(Eina_Matrixsparse *m); | |
| | | | |
| /* size manipulation */ | | /* size manipulation */ | |
|
| | | | |
| | | /** | |
| | | * @brief Get the current size of Sparse Matrix. | |
| | | * | |
| | | * The given parameters are guaranteed to be set if they're not NULL, | |
| | | * even if this function fails (ie: @a m is not a valid matrix instance). | |
| | | * | |
| | | * @param m the sparse matrix to operate on. | |
| | | * @param rows returns the number of rows, may be NULL. If @a m is invalid, | |
| | | * returned value is zero, otherwise it's a positive integer. | |
| | | * @param cols returns the number of columns, may be NULL. If @a m is | |
| | | * invalid, returned value is zero, otherwise it's a positive intege | |
| | | r. | |
| | | */ | |
| EAPI void eina_matrixsparse_size_get(const Eina_Matrixsparse *m, | | EAPI void eina_matrixsparse_size_get(const Eina_Matrixsparse *m, | |
| unsigned long *rows, | | unsigned long *rows, | |
| unsigned long *cols); | | unsigned long *cols); | |
|
| | | | |
| | | /** | |
| | | * @brief Resize the Sparse Matrix. | |
| | | * | |
| | | * This will resize the sparse matrix, possibly freeing cells on rows | |
| | | * and columns that will cease to exist. | |
| | | * | |
| | | * @param m the sparse matrix to operate on. | |
| | | * @param rows the new number of rows, must be greater than zero. | |
| | | * @param cols the new number of columns, must be greater than zero. | |
| | | * @return 1 on success, 0 on failure. | |
| | | * | |
| | | * @warning cells, rows or columns are not reference counted and thus | |
| | | * after this call any reference might be invalid if instance were | |
| | | * freed. | |
| | | */ | |
| EAPI Eina_Bool eina_matrixsparse_size_set(Eina_Matrixsparse *m, | | EAPI Eina_Bool eina_matrixsparse_size_set(Eina_Matrixsparse *m, | |
| unsigned long rows, | | unsigned long rows, | |
| unsigned long cols); | | unsigned long cols); | |
| | | | |
| /* data getting */ | | /* data getting */ | |
|
| | | | |
| | | /** | |
| | | * Get the cell reference inside Sparse Matrix. | |
| | | * | |
| | | * @param m the sparse matrix to operate on. | |
| | | * @param row the new number of row to clear. | |
| | | * @param col the new number of column to clear. | |
| | | * @param cell pointer to return cell reference, if any exists. | |
| | | * | |
| | | * @return 1 on success, 0 on failure. It is considered success if did not | |
| | | * exist but index is inside matrix size, in this case @c *cell == NULL | |
| | | * | |
| | | * @see eina_matrixsparse_cell_data_get() | |
| | | * @see eina_matrixsparse_data_idx_get() | |
| | | */ | |
| EAPI Eina_Bool eina_matrixsparse_cell_idx_get(const Eina_Matrixsparse *m, u
nsigned long row, unsigned long col, Eina_Matrixsparse_Cell **cell); | | EAPI Eina_Bool eina_matrixsparse_cell_idx_get(const Eina_Matrixsparse *m, u
nsigned long row, unsigned long col, Eina_Matrixsparse_Cell **cell); | |
|
| | | | |
| | | /** | |
| | | * Get data associated with given cell reference. | |
| | | * | |
| | | * @param cell given cell reference, must @b not be @c NULL. | |
| | | * | |
| | | * @return data associated with given cell. | |
| | | * | |
| | | * @see eina_matrixsparse_cell_idx_get() | |
| | | * @see eina_matrixsparse_data_idx_get() | |
| | | */ | |
| EAPI void *eina_matrixsparse_cell_data_get(const Eina_Matrixsparse_Cell
*cell); | | EAPI void *eina_matrixsparse_cell_data_get(const Eina_Matrixsparse_Cell
*cell); | |
|
| | | | |
| | | /** | |
| | | * Get data associated with given cell given its indexes. | |
| | | * | |
| | | * @param m the sparse matrix to operate on. | |
| | | * @param row the new number of row to clear. | |
| | | * @param col the new number of column to clear. | |
| | | * | |
| | | * @return data associated with given cell or NULL if nothing is associated | |
| | | . | |
| | | * | |
| | | * @see eina_matrixsparse_cell_idx_get() | |
| | | * @see eina_matrixsparse_cell_data_get() | |
| | | */ | |
| EAPI void *eina_matrixsparse_data_idx_get(const Eina_Matrixsparse *m, u
nsigned long row, unsigned long col); | | EAPI void *eina_matrixsparse_data_idx_get(const Eina_Matrixsparse *m, u
nsigned long row, unsigned long col); | |
|
| | | | |
| | | /** | |
| | | * Get position (indexes) of the given cell. | |
| | | * | |
| | | * @param cell the cell reference, must @b not be @c NULL. | |
| | | * @param row where to store cell row number, may be @c NULL. | |
| | | * @param col where to store cell column number, may be @c NULL. | |
| | | * | |
| | | * @return 1 on success, 0 otherwise (@c cell is @c NULL). | |
| | | */ | |
| EAPI Eina_Bool eina_matrixsparse_cell_position_get(const Eina_Matrixsparse_
Cell *cell, unsigned long *row, unsigned long *col); | | EAPI Eina_Bool eina_matrixsparse_cell_position_get(const Eina_Matrixsparse_
Cell *cell, unsigned long *row, unsigned long *col); | |
| | | | |
| /* data setting */ | | /* data setting */ | |
|
| | | | |
| | | /** | |
| | | * Change cell reference value without freeing the possibly existing old va | |
| | | lue. | |
| | | * | |
| | | * @param cell the cell reference, must @b not be @c NULL. | |
| | | * @param data new data to set. | |
| | | * @param p_old returns the old value intact (not freed). | |
| | | * | |
| | | * @return 1 on success, 0 otherwise (@a cell is @c NULL). | |
| | | * | |
| | | * @see eina_matrixsparse_cell_data_set() | |
| | | * @see eina_matrixsparse_data_idx_replace() | |
| | | */ | |
| EAPI Eina_Bool eina_matrixsparse_cell_data_replace(Eina_Matrixsparse_Cell *
cell, const void *data, void **p_old); | | EAPI Eina_Bool eina_matrixsparse_cell_data_replace(Eina_Matrixsparse_Cell *
cell, const void *data, void **p_old); | |
|
| | | | |
| | | /** | |
| | | * Change cell value freeing the possibly existing old value. | |
| | | * | |
| | | * In contrast to eina_matrixsparse_cell_data_replace(), this function will | |
| | | * call @c free_func() on existing value. | |
| | | * | |
| | | * @param cell the cell reference, must @b not be @c NULL. | |
| | | * @param data new data to set. | |
| | | * | |
| | | * @return 1 on success, 0 otherwise (@a cell is @c NULL). | |
| | | * | |
| | | * @see eina_matrixsparse_cell_data_replace() | |
| | | * @see eina_matrixsparse_data_idx_set() | |
| | | */ | |
| EAPI Eina_Bool eina_matrixsparse_cell_data_set(Eina_Matrixsparse_Cell *cell
, const void *data); | | EAPI Eina_Bool eina_matrixsparse_cell_data_set(Eina_Matrixsparse_Cell *cell
, const void *data); | |
|
| | | | |
| | | /** | |
| | | * Change cell value without freeing the possibly existing old value, using | |
| | | * indexes. | |
| | | * | |
| | | * @param m the sparse matrix, must @b not be @c NULL. | |
| | | * @param row the row number to set the value. | |
| | | * @param col the column number to set the value. | |
| | | * @param data new data to set. | |
| | | * @param p_old returns the old value intact (not freed). | |
| | | * | |
| | | * @return 1 on success, 0 otherwise (@a m is @c NULL, indexes are not vali | |
| | | d). | |
| | | * | |
| | | * @see eina_matrixsparse_cell_data_replace() | |
| | | * @see eina_matrixsparse_data_idx_set() | |
| | | */ | |
| EAPI Eina_Bool eina_matrixsparse_data_idx_replace(Eina_Matrixsparse *m, uns
igned long row, unsigned long col, const void *data, void **p_old); | | EAPI Eina_Bool eina_matrixsparse_data_idx_replace(Eina_Matrixsparse *m, uns
igned long row, unsigned long col, const void *data, void **p_old); | |
|
| | | | |
| | | /** | |
| | | * Change cell value freeing the possibly existing old value, using | |
| | | * indexes. | |
| | | * | |
| | | * In contrast to eina_matrixsparse_data_idx_replace(), this function will | |
| | | * call @c free_func() on existing value. | |
| | | * | |
| | | * @param m the sparse matrix, must @b not be @c NULL. | |
| | | * @param row the row number to set the value. | |
| | | * @param col the column number to set the value. | |
| | | * @param data new data to set. | |
| | | * | |
| | | * @return 1 on success, 0 otherwise (@a m is @c NULL, indexes are not vali | |
| | | d). | |
| | | * | |
| | | * @see eina_matrixsparse_cell_data_replace() | |
| | | */ | |
| EAPI Eina_Bool eina_matrixsparse_data_idx_set(Eina_Matrixsparse *m, unsigne
d long row, unsigned long col, const void *data); | | EAPI Eina_Bool eina_matrixsparse_data_idx_set(Eina_Matrixsparse *m, unsigne
d long row, unsigned long col, const void *data); | |
| | | | |
| /* data deleting */ | | /* data deleting */ | |
|
| | | | |
| | | /** | |
| | | * Clear (erase all cells) of row given its index. | |
| | | * | |
| | | * Existing cells will be cleared with @c free_func() given to | |
| | | * eina_matrixsparse_new(). | |
| | | * | |
| | | * @param m the sparse matrix to operate on. | |
| | | * @param row the new number of row to clear. | |
| | | * | |
| | | * @return 1 on success, 0 on failure. It is considered success if row | |
| | | * had no cells filled. Failure is asking for clear row outside | |
| | | * matrix size. | |
| | | * | |
| | | * @warning cells, rows or columns are not reference counted and thus | |
| | | * after this call any reference might be invalid if instance were | |
| | | * freed. | |
| | | */ | |
| EAPI Eina_Bool eina_matrixsparse_row_idx_clear(Eina_Matrixsparse *m, unsign
ed long row); | | EAPI Eina_Bool eina_matrixsparse_row_idx_clear(Eina_Matrixsparse *m, unsign
ed long row); | |
|
| | | | |
| | | /** | |
| | | * Clear (erase all cells) of column given its index. | |
| | | * | |
| | | * Existing cells will be cleared with @c free_func() given to | |
| | | * eina_matrixsparse_new(). | |
| | | * | |
| | | * @param m the sparse matrix to operate on. | |
| | | * @param col the new number of column to clear. | |
| | | * | |
| | | * @return 1 on success, 0 on failure. It is considered success if column | |
| | | * had no cells filled. Failure is asking for clear column outside | |
| | | * matrix size. | |
| | | * | |
| | | * @warning cells, rows or columns are not reference counted and thus | |
| | | * after this call any reference might be invalid if instance were | |
| | | * freed. | |
| | | */ | |
| EAPI Eina_Bool eina_matrixsparse_column_idx_clear(Eina_Matrixsparse *m, uns
igned long col); | | EAPI Eina_Bool eina_matrixsparse_column_idx_clear(Eina_Matrixsparse *m, uns
igned long col); | |
|
| | | | |
| | | /** | |
| | | * Clear (erase) cell given its indexes. | |
| | | * | |
| | | * Existing cell will be cleared with @c free_func() given to | |
| | | * eina_matrixsparse_new(). | |
| | | * | |
| | | * @param m the sparse matrix to operate on. | |
| | | * @param row the new number of row to clear. | |
| | | * @param col the new number of column to clear. | |
| | | * | |
| | | * @return 1 on success, 0 on failure. It is considered success if did not | |
| | | * exist but index is inside matrix size. | |
| | | * | |
| | | * @warning cells, rows or columns are not reference counted and thus | |
| | | * after this call any reference might be invalid if instance were | |
| | | * freed. Note that this call might delete container column and | |
| | | * row if this cell was the last remainder. | |
| | | */ | |
| EAPI Eina_Bool eina_matrixsparse_cell_idx_clear(Eina_Matrixsparse *m, unsig
ned long row, unsigned long col); | | EAPI Eina_Bool eina_matrixsparse_cell_idx_clear(Eina_Matrixsparse *m, unsig
ned long row, unsigned long col); | |
|
| | | | |
| | | /** | |
| | | * Clear (erase) cell given its reference. | |
| | | * | |
| | | * @param cell the cell reference, must @b not be @c NULL. | |
| | | * | |
| | | * @return 1 on success, 0 on failure. | |
| | | * | |
| | | * @warning cells, rows or columns are not reference counted and thus | |
| | | * after this call any reference might be invalid if instance were | |
| | | * freed. Note that this call might delete container column and | |
| | | * row if this cell was the last remainder. | |
| | | */ | |
| EAPI Eina_Bool eina_matrixsparse_cell_clear(Eina_Matrixsparse_Cell *cell); | | EAPI Eina_Bool eina_matrixsparse_cell_clear(Eina_Matrixsparse_Cell *cell); | |
| | | | |
| /* iterators */ | | /* iterators */ | |
|
| | | | |
| | | /** | |
| | | * Creates a new iterator over existing matrix cells. | |
| | | * | |
| | | * This is a cheap walk, it will just report existing cells and holes | |
| | | * in the sparse matrix will be ignored. That means the reported | |
| | | * indexes will not be sequential. | |
| | | * | |
| | | * The iterator data will be the cell reference, one may query current | |
| | | * position with eina_matrixsparse_cell_position_get() and cell value | |
| | | * with eina_matrixsparse_cell_data_get(). | |
| | | * | |
| | | * @param m The Sparse Matrix reference, must @b not be @c NULL. | |
| | | * @return A new iterator. | |
| | | * | |
| | | * @warning if the matrix structure changes then the iterator becomes | |
| | | * invalid! That is, if you add or remove cells this iterator | |
| | | * behavior is undefined and your program may crash! | |
| | | */ | |
| EAPI Eina_Iterator *eina_matrixsparse_iterator_new(const Eina_Matrixsparse
*m); | | EAPI Eina_Iterator *eina_matrixsparse_iterator_new(const Eina_Matrixsparse
*m); | |
|
| | | | |
| | | /** | |
| | | * Creates a new iterator over all matrix cells. | |
| | | * | |
| | | * Unlike eina_matrixsparse_iterator_new() this one will report all | |
| | | * matrix cells, even those that are still empty (holes). These will | |
| | | * be reported as dummy cells that contains no data. | |
| | | * | |
| | | * Be aware that iterating a big matrix (1000x1000) will call your | |
| | | * function that number of times (1000000 times in that case) even if | |
| | | * your matrix have no elements at all! | |
| | | * | |
| | | * The iterator data will be the cell reference, one may query current | |
| | | * position with eina_matrixsparse_cell_position_get() and cell value | |
| | | * with eina_matrixsparse_cell_data_get(). If cell is empty then the | |
| | | * reference will be a dummy/placeholder, thus setting value with | |
| | | * eina_matrixsparse_cell_data_set() will leave pointer unreferenced. | |
| | | * | |
| | | * @param m The Sparse Matrix reference, must @b not be @c NULL. | |
| | | * @return A new iterator. | |
| | | * | |
| | | * @warning if the matrix structure changes then the iterator becomes | |
| | | * invalid! That is, if you add or remove cells this iterator | |
| | | * behavior is undefined and your program may crash! | |
| | | */ | |
| EAPI Eina_Iterator *eina_matrixsparse_iterator_complete_new(const Eina_Matr
ixsparse *m); | | EAPI Eina_Iterator *eina_matrixsparse_iterator_complete_new(const Eina_Matr
ixsparse *m); | |
| | | | |
| /** | | /** | |
| * @} | | * @} | |
| */ | | */ | |
| | | | |
| /** | | /** | |
| * @} | | * @} | |
| */ | | */ | |
| | | | |
| | | | |
| End of changes. 19 change blocks. |
|---|
| 0 lines changed or deleted | | 291 lines changed or added | |
|---|
|
| eina_str.h | | eina_str.h | |
|---|
| #ifndef _EINA_STR_H | | #ifndef _EINA_STR_H | |
| #define _EINA_STR_H | | #define _EINA_STR_H | |
| | | | |
| #include <stddef.h> | | #include <stddef.h> | |
| #include <string.h> | | #include <string.h> | |
| | | | |
| #include "eina_types.h" | | #include "eina_types.h" | |
| | | | |
| /** | | /** | |
|
| | | * @page tutorial_eina_string Eina String example | |
| | | * @dontinclude eina_str_01.c | |
| | | * | |
| | | * Whenever using eina we need to include it: | |
| | | * @skipline #include | |
| | | * @line #include | |
| | | * | |
| | | * In our main function we declare(and initialize) some variables and initi | |
| | | alize | |
| | | * eina: | |
| | | * @until eina_init | |
| | | * | |
| | | * It's frequentely necessary to split a string into its constituent parts, | |
| | | * eina_str_split() make's it easy to do so: | |
| | | * @until printf | |
| | | * | |
| | | * Another common need is to make a string uppercase or lowercase, so let's | |
| | | * create a string and make it uppercase and then make it lowercase again: | |
| | | * @until printf | |
| | | * @until printf | |
| | | * | |
| | | * Next we use eina to check if our @p names string starts or ends with som | |
| | | e | |
| | | * values: | |
| | | * @until Has | |
| | | * | |
| | | * When strings will be used in a terminal(or a number of other places) it | |
| | | * necessary to escape certain characters that appear in them: | |
| | | * @until printf | |
| | | * | |
| | | * Much as we previously split a string we will now join two strings: | |
| | | * @until printf | |
| | | * | |
| | | * With strlcpy() we can copy what portion of the @p prologue fits in @p st | |
| | | r and | |
| | | * be sure that it's still NULL terminated: | |
| | | * @until printf | |
| | | * | |
| | | * Since we are done with @p prologue and @p str we should free them: | |
| | | * @until free(str | |
| | | * | |
| | | * Finally we see strlcat in action: | |
| | | * @until printf(" | |
| | | * | |
| | | * And then shut eina down and exit: | |
| | | * @until } | |
| | | * @example eina_str_01.c | |
| | | */ | |
| | | /** | |
| | | * @addtogroup Eina_String_Group String | |
| | | * | |
| | | * @brief Provide useful functions for C string manipulation. | |
| | | * | |
| | | * This group of functions allow you to more easily manipulate strings, the | |
| | | y | |
| | | * provide functionality not available through string.h. | |
| | | * | |
| | | * @warning Since these functions modify the strings they can't be used wit | |
| | | h | |
| | | * shared strings(eina_stringshare). | |
| | | * | |
| | | * See an example @ref tutorial_eina_string "here". | |
| | | */ | |
| | | | |
| | | /** | |
| * @addtogroup Eina_Tools_Group Tools | | * @addtogroup Eina_Tools_Group Tools | |
| * | | * | |
|
| | | * For more information refer to the @ref tutorial_eina_string "string exam | |
| | | ple". | |
| | | * | |
| * @{ | | * @{ | |
| */ | | */ | |
| | | | |
| /** | | /** | |
| * @defgroup Eina_String_Group String | | * @defgroup Eina_String_Group String | |
| * | | * | |
| * @{ | | * @{ | |
| */ | | */ | |
| | | | |
| /* strlcpy implementation for libc's lacking it */ | | /* strlcpy implementation for libc's lacking it */ | |
|
| | | | |
| | | /** | |
| | | * @brief Copy a c-string to another. | |
| | | * | |
| | | * @param dst The destination string. | |
| | | * @param src The source string. | |
| | | * @param siz The size of the destination string. | |
| | | * @return The length of the source string. | |
| | | * | |
| | | * This function copies up to @p siz - 1 characters from the | |
| | | * NUL-terminated string @p src to @p dst, NUL-terminating the result | |
| | | * (unless @p siz is equal to 0). The returned value is the length of | |
| | | * @p src. If the returned value is greater than @p siz, truncation | |
| | | * occurred. | |
| | | * | |
| | | * @note The main difference between eina_strlcpy and strncpy is that this | |
| | | * ensures @p dst is NULL terminated even if no NULL byte is found in the f | |
| | | irst | |
| | | * @p siz bytes of src. | |
| | | */ | |
| EAPI size_t eina_strlcpy(char *dst, const char *src, size_t siz) E
INA_ARG_NONNULL(1, 2); | | EAPI size_t eina_strlcpy(char *dst, const char *src, size_t siz) E
INA_ARG_NONNULL(1, 2); | |
|
| | | | |
| | | /** | |
| | | * @brief Append a c-string. | |
| | | * | |
| | | * @param dst The destination string. | |
| | | * @param src The source string. | |
| | | * @param siz The size of the destination string. | |
| | | * @return The length of the source string plus MIN(siz, strlen(initial dst | |
| | | )) | |
| | | * | |
| | | * This function appends @p src to @p dst of size @p siz (unlike | |
| | | * strncat, @p siz is the full size of @p dst, not space left). At | |
| | | * most @p siz - 1 characters will be copied. Always NUL terminates | |
| | | * (unless @p siz <= strlen(dst)). This function returns strlen(src) + | |
| | | * MIN(siz, strlen(initial dst)). If the returned value is greater or | |
| | | * equal than @p siz, truncation occurred. | |
| | | */ | |
| EAPI size_t eina_strlcat(char *dst, const char *src, size_t siz) E
INA_ARG_NONNULL(1, 2); | | EAPI size_t eina_strlcat(char *dst, const char *src, size_t siz) E
INA_ARG_NONNULL(1, 2); | |
| | | | |
|
| | | /** | |
| | | * @brief Check if the given string has the given prefix. | |
| | | * | |
| | | * @param str The string to work with. | |
| | | * @param prefix The prefix to check for. | |
| | | * @return #EINA_TRUE if the string has the given prefix, #EINA_FALSE other | |
| | | wise. | |
| | | * | |
| | | * This function returns #EINA_TRUE if @p str has the prefix | |
| | | * @p prefix, #EINA_FALSE otherwise. If the length of @p prefix is | |
| | | * greater than @p str, #EINA_FALSE is returned. | |
| | | */ | |
| EAPI Eina_Bool eina_str_has_prefix(const char *str, const char *prefi
x) EINA_PURE EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT; | | EAPI Eina_Bool eina_str_has_prefix(const char *str, const char *prefi
x) EINA_PURE EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT; | |
|
| | | | |
| | | /** | |
| | | * @brief Check if the given string has the given suffix. | |
| | | * | |
| | | * @param str The string to work with. | |
| | | * @param suffix The suffix to check for. | |
| | | * @return #EINA_TRUE if the string has the given suffix, #EINA_FALSE other | |
| | | wise. | |
| | | * | |
| | | * This function returns #EINA_TRUE if @p str has the suffix | |
| | | * @p suffix, #EINA_FALSE otherwise. If the length of @p suffix is | |
| | | * greater than @p str, #EINA_FALSE is returned. | |
| | | */ | |
| EAPI Eina_Bool eina_str_has_suffix(const char *str, const char *suffi
x) EINA_PURE EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT; | | EAPI Eina_Bool eina_str_has_suffix(const char *str, const char *suffi
x) EINA_PURE EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT; | |
|
| | | | |
| | | /** | |
| | | * @brief Check if the given string has the given extension. | |
| | | * | |
| | | * @param str The string to work with. | |
| | | * @param ext The extension to check for. | |
| | | * @return #EINA_TRUE if the string has the given extension, #EINA_FALSE ot | |
| | | herwise. | |
| | | * | |
| | | * This function does the same as eina_str_has_suffix(), except it's case | |
| | | * insensitive. | |
| | | */ | |
| EAPI Eina_Bool eina_str_has_extension(const char *str, const char *ex
t) EINA_PURE EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT; | | EAPI Eina_Bool eina_str_has_extension(const char *str, const char *ex
t) EINA_PURE EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT; | |
| | | | |
|
| | | /** | |
| | | * @brief Split a string using a delimiter. | |
| | | * | |
| | | * @param str The string to split. | |
| | | * @param delim The string which specifies the places at which to split the | |
| | | string. | |
| | | * @param max_tokens The maximum number of strings to split string into. | |
| | | * @return A newly-allocated NULL-terminated array of strings or NULL if it | |
| | | * fails to allocate the array. | |
| | | * | |
| | | * This functin splits @p str into a maximum of @p max_tokens pieces, | |
| | | * using the given delimiter @p delim. @p delim is not included in any | |
| | | * of the resulting strings, unless @p max_tokens is reached. If | |
| | | * @p max_tokens is less than @c 1, the string is splitted completely. If | |
| | | * @p max_tokens is reached, the last string in the returned string | |
| | | * array contains the remainder of string. The returned value is a | |
| | | * newly allocated NULL-terminated array of strings or NULL if it fails to | |
| | | * allocate the array. To free it, free the first element of the array and | |
| | | the | |
| | | * array itself. | |
| | | * | |
| | | * @note If you need the number of elements in the returned array see | |
| | | * eina_str_split_full(). | |
| | | */ | |
| EAPI char **eina_str_split(const char *string, const char *delimit
er, int max_tokens) EINA_ARG_NONNULL(1, 2) EINA_MALLOC EINA_WARN_UNUSED_RES
ULT; | | EAPI char **eina_str_split(const char *string, const char *delimit
er, int max_tokens) EINA_ARG_NONNULL(1, 2) EINA_MALLOC EINA_WARN_UNUSED_RES
ULT; | |
|
| | | | |
| | | /** | |
| | | * @brief Split a string using a delimiter and returns number of elements. | |
| | | * | |
| | | * @param str The string to split. | |
| | | * @param delim The string which specifies the places at which to split the | |
| | | string. | |
| | | * @param max_tokens The maximum number of strings to split string into. | |
| | | * @param elements Where to return the number of elements in returned | |
| | | * array (not counting the terminating @c NULL). May be @c NULL. | |
| | | * @return A newly-allocated NULL-terminated array of strings or NULL if it | |
| | | * fails to allocate the array. | |
| | | * | |
| | | * This function splits @p str into a maximum of @p max_tokens pieces, | |
| | | * using the given delimiter @p delim. @p delim is not included in any | |
| | | * of the resulting strings, unless @p max_tokens is reached. If | |
| | | * @p max_tokens is less than @c 1, the string is splitted completely. If | |
| | | * @p max_tokens is reached, the last string in the returned string | |
| | | * array contains the remainder of string. The returned value is a | |
| | | * newly allocated NULL-terminated array of strings or NULL if it fails to | |
| | | * allocate the array. To free it, free the first element of the array and | |
| | | the | |
| | | * array itself. | |
| | | * | |
| | | * @see eina_str_split() | |
| | | */ | |
| EAPI char **eina_str_split_full(const char *string, const char *de
limiter, int max_tokens, unsigned int *elements) EINA_ARG_NONNULL(1, 2, 4)
EINA_MALLOC EINA_WARN_UNUSED_RESULT; | | EAPI char **eina_str_split_full(const char *string, const char *de
limiter, int max_tokens, unsigned int *elements) EINA_ARG_NONNULL(1, 2, 4)
EINA_MALLOC EINA_WARN_UNUSED_RESULT; | |
| | | | |
|
| | | /** | |
| | | * @brief Join two strings of known length. | |
| | | * | |
| | | * @param dst The buffer to store the result. | |
| | | * @param size Size (in byte) of the buffer. | |
| | | * @param sep The separator character to use. | |
| | | * @param a First string to use, before @p sep. | |
| | | * @param a_len length of @p a. | |
| | | * @param b Second string to use, after @p sep. | |
| | | * @param b_len length of @p b. | |
| | | * @return The number of characters printed. | |
| | | * | |
| | | * This function joins the strings @p a and @p b (in that order) and | |
| | | * separate them with @p sep. The result is stored in the buffer | |
| | | * @p dst and at most @p size - 1 characters will be written and the | |
| | | * string is NULL-terminated. @p a_len is the length of @p a (not | |
| | | * including '\\0') and @p b_len is the length of @p b (not including | |
| | | * '\\0'). This function returns the number of characters printed (not | |
| | | * including the trailing '\\0' used to end output to strings). Just | |
| | | * like snprintf(), it will not write more than @p size bytes, thus a | |
| | | * returned value of @p size or more means that the output was | |
| | | * truncated. | |
| | | * | |
| | | * @see eina_str_join() | |
| | | * @see eina_str_join_static() | |
| | | */ | |
| EAPI size_t eina_str_join_len(char *dst, size_t size, char sep, co
nst char *a, size_t a_len, const char *b, size_t b_len) EINA_ARG_NONNULL(1,
4, 6); | | EAPI size_t eina_str_join_len(char *dst, size_t size, char sep, co
nst char *a, size_t a_len, const char *b, size_t b_len) EINA_ARG_NONNULL(1,
4, 6); | |
| | | | |
|
| | | /** | |
| | | * @brief Use Iconv to convert a text string from one encoding to another. | |
| | | * | |
| | | * @param enc_from Encoding to convert from. | |
| | | * @param enc_to Encoding to convert to. | |
| | | * @param text The text to convert. | |
| | | * @return The converted text. | |
| | | * | |
| | | * This function converts @p text, encoded in @p enc_from. On success, | |
| | | * the converted text is returned and is encoded in @p enc_to. On | |
| | | * failure, @c NULL is returned. Iconv is used to convert @p text. If | |
| | | * Iconv is not available, @c NULL is returned. When not used anymore, | |
| | | * the returned value must be freed. | |
| | | */ | |
| EAPI char *eina_str_convert(const char *enc_from, const char *enc
_to, const char *text) EINA_WARN_UNUSED_RESULT EINA_MALLOC EINA_ARG_NONNULL
(1, 2, 3); | | EAPI char *eina_str_convert(const char *enc_from, const char *enc
_to, const char *text) EINA_WARN_UNUSED_RESULT EINA_MALLOC EINA_ARG_NONNULL
(1, 2, 3); | |
| | | | |
|
| | | /** | |
| | | * @brief Escape slashes, spaces and apostrophes in strings. | |
| | | * | |
| | | * @param str The string to escape. | |
| | | * @return The escaped string. | |
| | | * | |
| | | * Escaping is done by adding a slash "\" before any occurrence of slashes | |
| | | "\", | |
| | | * spaces " " or apostrophes "'". This function returns a newly allocated | |
| | | * escaped string on success, @c NULL on failure. When not used anymore, th | |
| | | e | |
| | | * returned value must be freed. | |
| | | */ | |
| EAPI char *eina_str_escape(const char *str) EINA_WARN_UNUSED_RESU
LT EINA_MALLOC EINA_ARG_NONNULL(1); | | EAPI char *eina_str_escape(const char *str) EINA_WARN_UNUSED_RESU
LT EINA_MALLOC EINA_ARG_NONNULL(1); | |
| | | | |
|
| | | /** | |
| | | * @brief Lowercase all the characters in range [A-Z] in the given string. | |
| | | * | |
| | | * @param str The string to lowercase. | |
| | | * | |
| | | * This function modifies the original string, changing all characters | |
| | | * in [A-Z] to lowercase. If @p str is @c NULL or is an empty string, | |
| | | * this function does nothing. | |
| | | */ | |
| EAPI void eina_str_tolower(char **str); | | EAPI void eina_str_tolower(char **str); | |
|
| | | | |
| | | /** | |
| | | * @brief Uppercase all the characters in range [a-z] in the given string. | |
| | | * | |
| | | * @param str The string to uppercase. | |
| | | * | |
| | | * This function modifies the original string, changing all characters | |
| | | * in [a-z] to uppercase. If @p str is @c NULL or is an empty string, | |
| | | * this function does nothing. | |
| | | */ | |
| EAPI void eina_str_toupper(char **str); | | EAPI void eina_str_toupper(char **str); | |
| | | | |
| static inline size_t eina_str_join(char *dst, size_t size, char sep, const
char *a, const char *b) EINA_ARG_NONNULL(1, 4, 5); | | static inline size_t eina_str_join(char *dst, size_t size, char sep, const
char *a, const char *b) EINA_ARG_NONNULL(1, 4, 5); | |
| | | | |
| /** | | /** | |
| * @def eina_str_join_static(dst, sep, a, b) | | * @def eina_str_join_static(dst, sep, a, b) | |
| * @brief Join two static strings and store the result in a static buffer. | | * @brief Join two static strings and store the result in a static buffer. | |
| * | | * | |
| * @param dst The buffer to store the result. | | * @param dst The buffer to store the result. | |
| * @param sep The separator character to use. | | * @param sep The separator character to use. | |
| | | | |
| End of changes. 14 change blocks. |
|---|
| 0 lines changed or deleted | | 264 lines changed or added | |
|---|
|
| eina_strbuf.h | | eina_strbuf.h | |
|---|
| #ifndef EINA_STRBUF_H | | #ifndef EINA_STRBUF_H | |
| #define EINA_STRBUF_H | | #define EINA_STRBUF_H | |
| | | | |
| #include <stddef.h> | | #include <stddef.h> | |
| #include <stdarg.h> | | #include <stdarg.h> | |
| | | | |
| #include "eina_types.h" | | #include "eina_types.h" | |
| | | | |
| /** | | /** | |
|
| | | * @page tutorial_strbuf Eina_Strbuf example | |
| | | * @dontinclude eina_strbuf_01.c | |
| | | * | |
| | | * First thing always is including Eina: | |
| | | * @skipline #include | |
| | | * @until #include | |
| | | * | |
| | | * Next we initialize eina and create a string buffer to play with: | |
| | | * @until strbuf_new | |
| | | * | |
| | | * Here you can see two different ways of creating a buffer with the same | |
| | | * contents. We could create them in simpler ways, but this gives us an | |
| | | * opportunity to demonstrate several functions in action: | |
| | | * @until strbuf_reset | |
| | | * @until strbuf_reset | |
| | | * | |
| | | * Next we use the printf family of functions to create a formated string, | |
| | | * add, remove and replace some content: | |
| | | * @until strbuf_string_get | |
| | | * @until strbuf_string_get | |
| | | * @until strbuf_string_get | |
| | | * | |
| | | * Once done we free our string buffer, shut down Eina and end the applicat | |
| | | ion: | |
| | | * @until } | |
| | | * | |
| | | * @example eina_strbuf_01.c | |
| | | */ | |
| | | /** | |
| | | * @addtogroup Eina_String_Buffer_Group String Buffer | |
| | | * | |
| | | * @brief These functions provide string buffers management. | |
| | | * | |
| | | * The String Buffer data type is designed to be a mutable string, | |
| | | * allowing to append, prepend or insert a string to a buffer. | |
| | | * | |
| | | * For more information see @ref tutorial_strbuf "this example". | |
| | | */ | |
| | | | |
| | | /** | |
| * @addtogroup Eina_Data_Types_Group Data Types | | * @addtogroup Eina_Data_Types_Group Data Types | |
| * | | * | |
| * @{ | | * @{ | |
| */ | | */ | |
| | | | |
| /** | | /** | |
| * @defgroup Eina_String_Buffer_Group String Buffer | | * @defgroup Eina_String_Buffer_Group String Buffer | |
| * | | * | |
| * @{ | | * @{ | |
| */ | | */ | |
| | | | |
| skipping to change at line 43 | | skipping to change at line 82 | |
|---|
| * returned and Eina error is set to #EINA_ERROR_OUT_OF_MEMORY. To | | * returned and Eina error is set to #EINA_ERROR_OUT_OF_MEMORY. To | |
| * free the resources, use eina_strbuf_free(). | | * free the resources, use eina_strbuf_free(). | |
| * | | * | |
| * @see eina_strbuf_free() | | * @see eina_strbuf_free() | |
| * @see eina_strbuf_append() | | * @see eina_strbuf_append() | |
| * @see eina_strbuf_string_get() | | * @see eina_strbuf_string_get() | |
| */ | | */ | |
| EAPI Eina_Strbuf *eina_strbuf_new(void) EINA_MALLOC EINA_WARN_UNUSED_RESULT
; | | EAPI Eina_Strbuf *eina_strbuf_new(void) EINA_MALLOC EINA_WARN_UNUSED_RESULT
; | |
| | | | |
| /** | | /** | |
|
| | | * @brief Create a new string buffer using the passed string. The passed | |
| | | * string is used directly as the buffer, it's somehow the opposite functio | |
| | | n of | |
| | | * @ref eina_strbuf_string_steal . The passed string must be malloced. | |
| | | * | |
| | | * @param str the string to manage | |
| | | * @return Newly allocated string buffer instance. | |
| | | * | |
| | | * This function creates a new string buffer. On error, @c NULL is | |
| | | * returned and Eina error is set to #EINA_ERROR_OUT_OF_MEMORY. To | |
| | | * free the resources, use eina_strbuf_free(). | |
| | | * | |
| | | * @see eina_strbuf_free() | |
| | | * @see eina_strbuf_append() | |
| | | * @see eina_strbuf_string_get() | |
| | | * @since 1.1.0 | |
| | | */ | |
| | | EAPI Eina_Strbuf *eina_strbuf_manage_new(char *str) EINA_MALLOC EINA_WARN_U | |
| | | NUSED_RESULT; | |
| | | | |
| | | /** | |
| * @brief Free a string buffer. | | * @brief Free a string buffer. | |
| * | | * | |
| * @param buf The string buffer to free. | | * @param buf The string buffer to free. | |
| * | | * | |
| * This function frees the memory of @p buf. @p buf must have been | | * This function frees the memory of @p buf. @p buf must have been | |
| * created by eina_strbuf_new(). | | * created by eina_strbuf_new(). | |
| */ | | */ | |
| EAPI void eina_strbuf_free(Eina_Strbuf *buf) EINA_ARG_NONNULL(1); | | EAPI void eina_strbuf_free(Eina_Strbuf *buf) EINA_ARG_NONNULL(1); | |
| | | | |
| /** | | /** | |
| | | | |
| skipping to change at line 87 | | skipping to change at line 145 | |
|---|
| */ | | */ | |
| EAPI Eina_Bool eina_strbuf_append(Eina_Strbuf *buf, const char *str) EINA_A
RG_NONNULL(1, 2); | | EAPI Eina_Bool eina_strbuf_append(Eina_Strbuf *buf, const char *str) EINA_A
RG_NONNULL(1, 2); | |
| | | | |
| /** | | /** | |
| * @brief Append an escaped string to a buffer, reallocating as necessary. | | * @brief Append an escaped string to a buffer, reallocating as necessary. | |
| * | | * | |
| * @param buf The string buffer to append to. | | * @param buf The string buffer to append to. | |
| * @param str The string to append. | | * @param str The string to append. | |
| * @return #EINA_TRUE on success, #EINA_FALSE on failure. | | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | |
| * | | * | |
|
| * This function appends the escaped string @p str to @p buf. If @p | | * This function escapes and then appends the string @p str to @p buf. If @ | |
| * str can not be appended, #EINA_FALSE is returned, otherwise, | | p str | |
| * #EINA_TRUE is returned. | | * can not be appended, #EINA_FALSE is returned, otherwise, #EINA_TRUE is | |
| | | * returned. | |
| */ | | */ | |
| EAPI Eina_Bool eina_strbuf_append_escaped(Eina_Strbuf *buf, const char *str
) EINA_ARG_NONNULL(1, 2); | | EAPI Eina_Bool eina_strbuf_append_escaped(Eina_Strbuf *buf, const char *str
) EINA_ARG_NONNULL(1, 2); | |
| | | | |
| /** | | /** | |
| * @brief Append a string to a buffer, reallocating as necessary, | | * @brief Append a string to a buffer, reallocating as necessary, | |
| * limited by the given length. | | * limited by the given length. | |
| * | | * | |
| * @param buf The string buffer to append to. | | * @param buf The string buffer to append to. | |
| * @param str The string to append. | | * @param str The string to append. | |
| * @param maxlen The maximum number of characters to append. | | * @param maxlen The maximum number of characters to append. | |
| * @return #EINA_TRUE on success, #EINA_FALSE on failure. | | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | |
| * | | * | |
| * This function appends at most @p maxlen characters of @p str to | | * This function appends at most @p maxlen characters of @p str to | |
|
| * @p buf. It can't appends more than the length of @p str. It | | * @p buf. It can't append more than the length of @p str. It | |
| * computes the length of @p str, so is slightly slower than | | * computes the length of @p str, so it is slightly slower than | |
| * eina_strbuf_append_length(). If the length is known beforehand, | | * eina_strbuf_append_length(). If the length is known beforehand, | |
| * consider using that variant (@p maxlen should then be checked so | | * consider using that variant (@p maxlen should then be checked so | |
| * that it is greater than the size of @p str). If @p str can not be | | * that it is greater than the size of @p str). If @p str can not be | |
| * appended, #EINA_FALSE is returned, otherwise, #EINA_TRUE is | | * appended, #EINA_FALSE is returned, otherwise, #EINA_TRUE is | |
| * returned. | | * returned. | |
| * | | * | |
| * @see eina_strbuf_append() | | * @see eina_strbuf_append() | |
| * @see eina_strbuf_append_length() | | * @see eina_strbuf_append_length() | |
| */ | | */ | |
| EAPI Eina_Bool eina_strbuf_append_n(Eina_Strbuf *buf, const char *str, size
_t maxlen) EINA_ARG_NONNULL(1, 2); | | EAPI Eina_Bool eina_strbuf_append_n(Eina_Strbuf *buf, const char *str, size
_t maxlen) EINA_ARG_NONNULL(1, 2); | |
| | | | |
| skipping to change at line 127 | | skipping to change at line 185 | |
|---|
| * @brief Append a string of exact length to a buffer, reallocating as nece
ssary. | | * @brief Append a string of exact length to a buffer, reallocating as nece
ssary. | |
| * | | * | |
| * @param buf The string buffer to append to. | | * @param buf The string buffer to append to. | |
| * @param str The string to append. | | * @param str The string to append. | |
| * @param length The exact length to use. | | * @param length The exact length to use. | |
| * @return #EINA_TRUE on success, #EINA_FALSE on failure. | | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | |
| * | | * | |
| * This function appends @p str to @p buf. @p str must be of size at | | * This function appends @p str to @p buf. @p str must be of size at | |
| * most @p length. It is slightly faster than eina_strbuf_append() as | | * most @p length. It is slightly faster than eina_strbuf_append() as | |
| * it does not compute the size of @p str. It is useful when dealing | | * it does not compute the size of @p str. It is useful when dealing | |
|
| * with strings of known size, such as eina_strngshare. If @p buf | | * with strings of known size, such as eina_stringshare. If @p buf | |
| * can't append it, #EINA_FALSE is returned, otherwise #EINA_TRUE is | | * can't append it, #EINA_FALSE is returned, otherwise #EINA_TRUE is | |
| * returned. | | * returned. | |
| * | | * | |
| * @see eina_stringshare_length() | | * @see eina_stringshare_length() | |
| * @see eina_strbuf_append() | | * @see eina_strbuf_append() | |
| * @see eina_strbuf_append_n() | | * @see eina_strbuf_append_n() | |
| */ | | */ | |
| EAPI Eina_Bool eina_strbuf_append_length(Eina_Strbuf *buf, const char *str,
size_t length) EINA_ARG_NONNULL(1, 2); | | EAPI Eina_Bool eina_strbuf_append_length(Eina_Strbuf *buf, const char *str,
size_t length) EINA_ARG_NONNULL(1, 2); | |
| | | | |
| /** | | /** | |
| | | | |
| skipping to change at line 157 | | skipping to change at line 215 | |
|---|
| */ | | */ | |
| EAPI Eina_Bool eina_strbuf_append_char(Eina_Strbuf *buf, char c) EINA_ARG_N
ONNULL(1); | | EAPI Eina_Bool eina_strbuf_append_char(Eina_Strbuf *buf, char c) EINA_ARG_N
ONNULL(1); | |
| | | | |
| /** | | /** | |
| * @brief Append a string to a buffer, reallocating as necessary. | | * @brief Append a string to a buffer, reallocating as necessary. | |
| * | | * | |
| * @param buf The string buffer to append to. | | * @param buf The string buffer to append to. | |
| * @param fmt The string to append. | | * @param fmt The string to append. | |
| * @return #EINA_TRUE on success, #EINA_FALSE on failure. | | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | |
| * | | * | |
|
| | | * This function appends the string defined by the format @p fmt to @p buf. | |
| | | @p | |
| | | * fmt must be of a valid format for printf family of functions. If it can' | |
| | | t | |
| | | * insert it, #EINA_FALSE is returned, otherwise #EINA_TRUE is returned. | |
| | | * | |
| * @see eina_strbuf_append() | | * @see eina_strbuf_append() | |
| */ | | */ | |
| EAPI Eina_Bool eina_strbuf_append_printf(Eina_Strbuf *buf, const char *fmt,
...) EINA_ARG_NONNULL(1, 2) EINA_PRINTF(2, 3); | | EAPI Eina_Bool eina_strbuf_append_printf(Eina_Strbuf *buf, const char *fmt,
...) EINA_ARG_NONNULL(1, 2) EINA_PRINTF(2, 3); | |
| | | | |
| /** | | /** | |
| * @brief Append a string to a buffer, reallocating as necessary. | | * @brief Append a string to a buffer, reallocating as necessary. | |
| * | | * | |
| * @param buf The string buffer to append to. | | * @param buf The string buffer to append to. | |
| * @param fmt The string to append. | | * @param fmt The string to append. | |
| * @param args The variable arguments. | | * @param args The variable arguments. | |
| * @return #EINA_TRUE on success, #EINA_FALSE on failure. | | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | |
| * | | * | |
|
| * @see eina_strbuf_append() | | * @see eina_strbuf_append_printf() | |
| */ | | */ | |
| EAPI Eina_Bool eina_strbuf_append_vprintf(Eina_Strbuf *buf, const char *fmt
, va_list args) EINA_ARG_NONNULL(1, 2); | | EAPI Eina_Bool eina_strbuf_append_vprintf(Eina_Strbuf *buf, const char *fmt
, va_list args) EINA_ARG_NONNULL(1, 2); | |
| | | | |
| /** | | /** | |
| * @brief Insert a string to a buffer, reallocating as necessary. | | * @brief Insert a string to a buffer, reallocating as necessary. | |
| * | | * | |
| * @param buf The string buffer to insert. | | * @param buf The string buffer to insert. | |
| * @param str The string to insert. | | * @param str The string to insert. | |
| * @param pos The position to insert the string. | | * @param pos The position to insert the string. | |
| * @return #EINA_TRUE on success, #EINA_FALSE on failure. | | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | |
| | | | |
| skipping to change at line 198 | | skipping to change at line 260 | |
|---|
| | | | |
| /** | | /** | |
| * @brief Insert an escaped string to a buffer, reallocating as | | * @brief Insert an escaped string to a buffer, reallocating as | |
| * necessary. | | * necessary. | |
| * | | * | |
| * @param buf The string buffer to insert to. | | * @param buf The string buffer to insert to. | |
| * @param str The string to insert. | | * @param str The string to insert. | |
| * @param pos The position to insert the string. | | * @param pos The position to insert the string. | |
| * @return #EINA_TRUE on success, #EINA_FALSE on failure. | | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | |
| * | | * | |
|
| * This function inserts the escaped string @p str to @p buf at | | * This function escapes and inserts the string @p str to @p buf at | |
| * position @p pos. If @p buf can't insert @p str, #EINA_FALSE is | | * position @p pos. If @p buf can't insert @p str, #EINA_FALSE is | |
| * returned, otherwise #EINA_TRUE is returned. | | * returned, otherwise #EINA_TRUE is returned. | |
| */ | | */ | |
| EAPI Eina_Bool eina_strbuf_insert_escaped(Eina_Strbuf *buf, const char *str
, size_t pos) EINA_ARG_NONNULL(1, 2); | | EAPI Eina_Bool eina_strbuf_insert_escaped(Eina_Strbuf *buf, const char *str
, size_t pos) EINA_ARG_NONNULL(1, 2); | |
| | | | |
| /** | | /** | |
| * @brief Insert a string to a buffer, reallocating as necessary. Limited b
y maxlen. | | * @brief Insert a string to a buffer, reallocating as necessary. Limited b
y maxlen. | |
| * | | * | |
| * @param buf The string buffer to insert to. | | * @param buf The string buffer to insert to. | |
| * @param str The string to insert. | | * @param str The string to insert. | |
| * @param maxlen The maximum number of chars to insert. | | * @param maxlen The maximum number of chars to insert. | |
| * @param pos The position to insert the string. | | * @param pos The position to insert the string. | |
| * @return #EINA_TRUE on success, #EINA_FALSE on failure. | | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | |
| * | | * | |
|
| * This function inserts @p str ot @p buf at position @p pos, with at | | * This function inserts @p str to @p buf at position @p pos, with at | |
| * most @p maxlen bytes. The number of inserted characters can not be | | * most @p maxlen bytes. The number of inserted characters can not be | |
| * greater than the length of @p str. It computes the length of | | * greater than the length of @p str. It computes the length of | |
| * @p str, so is slightly slower than eina_strbuf_insert_length(). If the | | * @p str, so is slightly slower than eina_strbuf_insert_length(). If the | |
| * length is known beforehand, consider using that variant (@p maxlen | | * length is known beforehand, consider using that variant (@p maxlen | |
| * should then be checked so that it is greater than the size of | | * should then be checked so that it is greater than the size of | |
| * @p str). If @p str can not be inserted, #EINA_FALSE is returned, | | * @p str). If @p str can not be inserted, #EINA_FALSE is returned, | |
| * otherwise, #EINA_TRUE is returned. | | * otherwise, #EINA_TRUE is returned. | |
| */ | | */ | |
| EAPI Eina_Bool eina_strbuf_insert_n(Eina_Strbuf *buf, const char *str, size
_t maxlen, size_t pos) EINA_ARG_NONNULL(1, 2); | | EAPI Eina_Bool eina_strbuf_insert_n(Eina_Strbuf *buf, const char *str, size
_t maxlen, size_t pos) EINA_ARG_NONNULL(1, 2); | |
| | | | |
| | | | |
| skipping to change at line 268 | | skipping to change at line 330 | |
|---|
| */ | | */ | |
| EAPI Eina_Bool eina_strbuf_insert_char(Eina_Strbuf *buf, char c, size_t pos
) EINA_ARG_NONNULL(1); | | EAPI Eina_Bool eina_strbuf_insert_char(Eina_Strbuf *buf, char c, size_t pos
) EINA_ARG_NONNULL(1); | |
| | | | |
| /** | | /** | |
| * @brief Insert a string to a buffer, reallocating as necessary. | | * @brief Insert a string to a buffer, reallocating as necessary. | |
| * | | * | |
| * @param buf The string buffer to insert. | | * @param buf The string buffer to insert. | |
| * @param fmt The string to insert. | | * @param fmt The string to insert. | |
| * @param pos The position to insert the string. | | * @param pos The position to insert the string. | |
| * @return #EINA_TRUE on success, #EINA_FALSE on failure. | | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | |
|
| | | * | |
| | | * This function insert a string as described by the format @p fmt to @p bu | |
| | | f at | |
| | | * the position @p pos. @p fmt must be of a valid format for printf family | |
| | | of | |
| | | * functions. If it can't insert it, #EINA_FALSE is returned, otherwise | |
| | | * #EINA_TRUE is returned. | |
| */ | | */ | |
| EAPI Eina_Bool eina_strbuf_insert_printf(Eina_Strbuf *buf, const char *fmt,
size_t pos, ...) EINA_ARG_NONNULL(1, 2) EINA_PRINTF(2, 4); | | EAPI Eina_Bool eina_strbuf_insert_printf(Eina_Strbuf *buf, const char *fmt,
size_t pos, ...) EINA_ARG_NONNULL(1, 2) EINA_PRINTF(2, 4); | |
| | | | |
| /** | | /** | |
| * @brief Insert a string to a buffer, reallocating as necessary. | | * @brief Insert a string to a buffer, reallocating as necessary. | |
| * | | * | |
| * @param buf The string buffer to insert. | | * @param buf The string buffer to insert. | |
| * @param fmt The string to insert. | | * @param fmt The string to insert. | |
| * @param pos The position to insert the string. | | * @param pos The position to insert the string. | |
| * @param args The variable arguments. | | * @param args The variable arguments. | |
| * @return #EINA_TRUE on success, #EINA_FALSE on failure. | | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | |
|
| | | * | |
| | | * @see eina_strbuf_insert_printf | |
| */ | | */ | |
| EAPI Eina_Bool eina_strbuf_insert_vprintf(Eina_Strbuf *buf, const char *fmt
, size_t pos, va_list args) EINA_ARG_NONNULL(1, 2); | | EAPI Eina_Bool eina_strbuf_insert_vprintf(Eina_Strbuf *buf, const char *fmt
, size_t pos, va_list args) EINA_ARG_NONNULL(1, 2); | |
| | | | |
| /** | | /** | |
| * @def eina_strbuf_prepend(buf, str) | | * @def eina_strbuf_prepend(buf, str) | |
| * @brief Prepend the given string to the given buffer | | * @brief Prepend the given string to the given buffer | |
| * | | * | |
| * @param buf The string buffer to prepend to. | | * @param buf The string buffer to prepend to. | |
| * @param str The string to prepend. | | * @param str The string to prepend. | |
| * @return #EINA_TRUE on success, #EINA_FALSE on failure. | | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | |
| * | | * | |
|
| * This macro is calling eina_strbuf_insert() at position 0.If @p buf | | * This macro is calling eina_strbuf_insert() at position 0. If @p buf | |
| * can't prepend it, #EINA_FALSE is returned, otherwise #EINA_TRUE is | | * can't prepend it, #EINA_FALSE is returned, otherwise #EINA_TRUE is | |
| * returned. | | * returned. | |
| */ | | */ | |
| #define eina_strbuf_prepend(buf, str) eina_strbuf_insert(buf
, str, 0) | | #define eina_strbuf_prepend(buf, str) eina_strbuf_insert(buf
, str, 0) | |
| | | | |
| /** | | /** | |
| * @def eina_strbuf_prepend_escaped(buf, str) | | * @def eina_strbuf_prepend_escaped(buf, str) | |
| * @brief Prepend the given escaped string to the given buffer | | * @brief Prepend the given escaped string to the given buffer | |
| * | | * | |
| * @param buf The string buffer to prepend to. | | * @param buf The string buffer to prepend to. | |
| | | | |
| skipping to change at line 409 | | skipping to change at line 478 | |
|---|
| | | | |
| /** | | /** | |
| * @brief Retrieve a pointer to the contents of a string buffer | | * @brief Retrieve a pointer to the contents of a string buffer | |
| * | | * | |
| * @param buf The string buffer. | | * @param buf The string buffer. | |
| * @return The current string in the string buffer. | | * @return The current string in the string buffer. | |
| * | | * | |
| * This function returns the string contained in @p buf. The returned | | * This function returns the string contained in @p buf. The returned | |
| * value must not be modified and will no longer be valid if @p buf is | | * value must not be modified and will no longer be valid if @p buf is | |
| * modified. In other words, any eina_strbuf_append() or similar will | | * modified. In other words, any eina_strbuf_append() or similar will | |
|
| * make that pointer invalid. | | * make that pointer invalid. The pointer returned by this function <b>must | |
| | | * not</b> be freed. | |
| * | | * | |
| * @see eina_strbuf_string_steal() | | * @see eina_strbuf_string_steal() | |
| */ | | */ | |
| EAPI const char *eina_strbuf_string_get(const Eina_Strbuf *buf) EINA_ARG_NO
NNULL(1) EINA_WARN_UNUSED_RESULT; | | EAPI const char *eina_strbuf_string_get(const Eina_Strbuf *buf) EINA_ARG_NO
NNULL(1) EINA_WARN_UNUSED_RESULT; | |
| | | | |
| /** | | /** | |
| * @brief Steal the contents of a string buffer. | | * @brief Steal the contents of a string buffer. | |
| * | | * | |
| * @param buf The string buffer to steal. | | * @param buf The string buffer to steal. | |
| * @return The current string in the string buffer. | | * @return The current string in the string buffer. | |
| | | | |
| skipping to change at line 450 | | skipping to change at line 520 | |
|---|
| /** | | /** | |
| * @brief Retrieve the length of the string buffer content. | | * @brief Retrieve the length of the string buffer content. | |
| * | | * | |
| * @param buf The string buffer. | | * @param buf The string buffer. | |
| * @return The current length of the string, in bytes. | | * @return The current length of the string, in bytes. | |
| * | | * | |
| * This function returns the length of @p buf. | | * This function returns the length of @p buf. | |
| */ | | */ | |
| EAPI size_t eina_strbuf_length_get(const Eina_Strbuf *buf) EINA_ARG_NONN
ULL(1) EINA_WARN_UNUSED_RESULT; | | EAPI size_t eina_strbuf_length_get(const Eina_Strbuf *buf) EINA_ARG_NONN
ULL(1) EINA_WARN_UNUSED_RESULT; | |
| | | | |
|
| | | /** | |
| | | * @brief Replace the n-th string with an other string. | |
| | | * | |
| | | * @param buf The string buffer to work with. | |
| | | * @param str The string to replace. | |
| | | * @param with The replaceing string. | |
| | | * @param n The number of the fitting string. | |
| | | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | |
| | | * | |
| | | * This function replaces the n-th occurrence of @p str in @p buf with | |
| | | * @p with. It returns #EINA_FALSE on failure, #EINA_TRUE otherwise. | |
| | | */ | |
| EAPI Eina_Bool eina_strbuf_replace(Eina_Strbuf *buf, const char *str, const
char *with, unsigned int n) EINA_ARG_NONNULL(1, 2, 3); | | EAPI Eina_Bool eina_strbuf_replace(Eina_Strbuf *buf, const char *str, const
char *with, unsigned int n) EINA_ARG_NONNULL(1, 2, 3); | |
| | | | |
| /** | | /** | |
| * @def eina_strbuf_replace_first(buf, str, with) | | * @def eina_strbuf_replace_first(buf, str, with) | |
| * @brief Prepend the given character to the given buffer | | * @brief Prepend the given character to the given buffer | |
| * | | * | |
| * @param buf The string buffer to work with. | | * @param buf The string buffer to work with. | |
| * @param str The string to replace. | | * @param str The string to replace. | |
| * @param with The replaceing string. | | * @param with The replaceing string. | |
| * @return #EINA_TRUE on success, #EINA_FALSE on failure. | | * @return #EINA_TRUE on success, #EINA_FALSE on failure. | |
| * | | * | |
| * This macro is calling eina_strbuf_replace() with the n-th occurrence | | * This macro is calling eina_strbuf_replace() with the n-th occurrence | |
| * equal to @c 1. If @p buf can't replace it, #EINA_FALSE is returned, | | * equal to @c 1. If @p buf can't replace it, #EINA_FALSE is returned, | |
| * otherwise #EINA_TRUE is returned. | | * otherwise #EINA_TRUE is returned. | |
| */ | | */ | |
| #define eina_strbuf_replace_first(buf, str, with) eina_strbuf_replace(buf,
str, with, 1) | | #define eina_strbuf_replace_first(buf, str, with) eina_strbuf_replace(buf,
str, with, 1) | |
| | | | |
|
| | | /** | |
| | | * @brief Replace all strings with an other string. | |
| | | | |
| | | * @param buf the string buffer to work with. | |
| | | * @param str The string to replace. | |
| | | * @param with The replaceing string. | |
| | | * @return How often the string was replaced. | |
| | | * | |
| | | * This function replaces all the occurrences of @p str in @p buf with | |
| | | * the string @p with. This function returns the number of times @p str | |
| | | * has been replaced. On failure, it returns 0. | |
| | | */ | |
| EAPI int eina_strbuf_replace_all(Eina_Strbuf *buf, const char *str, const c
har *with) EINA_ARG_NONNULL(1, 2, 3); | | EAPI int eina_strbuf_replace_all(Eina_Strbuf *buf, const char *str, const c
har *with) EINA_ARG_NONNULL(1, 2, 3); | |
| | | | |
| /** | | /** | |
|
| | | * @brief Trim the string buffer | |
| | | | |
| | | * @param buf the string buffer to work with. | |
| | | * | |
| | | * This function skips whitespaces in the beginning and the end of the buff | |
| | | er. | |
| | | */ | |
| | | EAPI void eina_strbuf_trim(Eina_Strbuf *buf) EINA_ARG_NONNULL(1); | |
| | | | |
| | | /** | |
| | | * @brief Left trim the string buffer | |
| | | | |
| | | * @param buf the string buffer to work with. | |
| | | * | |
| | | * This function skips whitespaces in the beginning of the buffer. | |
| | | */ | |
| | | EAPI void eina_strbuf_ltrim(Eina_Strbuf *buf) EINA_ARG_NONNULL(1); | |
| | | | |
| | | /** | |
| | | * @brief Right trim the string buffer | |
| | | | |
| | | * @param buf the string buffer to work with. | |
| | | * | |
| | | * This function skips whitespaces in the end of the buffer. | |
| | | */ | |
| | | EAPI void eina_strbuf_rtrim(Eina_Strbuf *buf) EINA_ARG_NONNULL(1); | |
| | | | |
| | | /** | |
| | | * @} | |
| | | */ | |
| | | | |
| | | /** | |
| * @} | | * @} | |
| */ | | */ | |
| | | | |
| /** | | /** | |
| * @} | | * @} | |
| */ | | */ | |
| | | | |
| #endif /* EINA_STRBUF_H */ | | #endif /* EINA_STRBUF_H */ | |
| | | | |
| End of changes. 16 change blocks. |
|---|
| 11 lines changed or deleted | | 145 lines changed or added | |
|---|
|