diff --git a/legacy/eina/src/include/eina_accessor.h b/legacy/eina/src/include/eina_accessor.h index 4bfa14dbd5..99a2a9ca26 100644 --- a/legacy/eina/src/include/eina_accessor.h +++ b/legacy/eina/src/include/eina_accessor.h @@ -277,4 +277,8 @@ EAPI Eina_Bool eina_accessor_unlock(Eina_Accessor *accessor) EINA_ARG_NONNULL(1) * @} */ +/** + * @} + */ + #endif diff --git a/legacy/eina/src/include/eina_array.h b/legacy/eina/src/include/eina_array.h index e8ca73fa45..5a0fe86429 100644 --- a/legacy/eina/src/include/eina_array.h +++ b/legacy/eina/src/include/eina_array.h @@ -29,6 +29,134 @@ #include "eina_accessor.h" #include "eina_magic.h" + +/** + * @page tutorial_array_page Array Tutorial + * + * The Array data type is allow the storage of data like a C array. + * It is designed such that the access to its element is very fast. + * But the addition or removal can be done only at the end of the + * array. To add or remove an element at any location, the Eina + * @ref Eina_List_Group is the correct container is the correct one. + * + * @section tutorial_error_basic_usage Basic Usage + * + * An array must created with eina_array_new(). That function + * takes an integer as parameter, which is the count of pointers to + * add when increasing the array size. Once the array is not used + * anymore, it must be destroyed with eina_array_free(). + * + * To append data at the end of the array, the function + * eina_array_push() must be used. To remove the data at the end of + * the array, eina_array_pop() must be used. Once the array is filled, + * one can check its elements by iterating over it. A while loop and + * eina_array_data_get() can be used, or else one can use the + * predefined macro EINA_ARRAY_ITER_NEXT(). To free all the elements, + * a while loop can be used with eina_array_count_get(). Here is an + * example of use: + * + * @code + * #include + * #include + * #include + * + * #include + * + * int main(void) + * { + * const char *strings[] = { + * "first string", + * "second string", + * "third string", + * "fourth string" + * }; + * Eina_Array *array; + * char *item; + * Eina_Array_Iterator iterator; + * unsigned int i; + * + * if (!eina_init()) + * { + * printf ("Error during the initialization of eina\n"); + * return EXIT_FAILURE; + * } + * + * array = eina_array_new(16); + * if (!array) + * goto shutdown; + * + * for (i = 0; i < 4; i++) + * { + * eina_array_push(array, strdup(strings[i])); + * } + * + * printf("array count: %d\n", eina_array_count_get(array)); + * EINA_ARRAY_ITER_NEXT(array, i, item, iterator) + * { + * printf("item #%d: %s\n", i, item); + * } + * + * while (eina_array_count_get(array)) + * { + * void *data; + * + * data = eina_array_pop(array); + * free(data); + * } + * + * eina_array_free(array); + * eina_shutdown(); + * + * return EXIT_SUCCESS; + * + * shutdown: + * eina_shutdown(); + * + * return EXIT_FAILURE; + * } + * @endcode + * + * To be continued + */ + +/** + * @addtogroup Eina_Array_Group Array + * + * @brief These functions provide array management. + * + * The Array data type in Eina is designed to have a 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 container + * to use. + * + * To use the array data type, eina_init() must be called before any + * other array functions. When eina is no more array function is used, + * eina_shutdown() must be called to free all the resources. + * + * An array must be created with eina_array_new(). It allocated 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 All the other 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 positin, use + * eina_array_data_get(). The number of elements can be retrieved with + * eina_array_count_get(). + * + * For more information, you can look at the @ref tutorial_array_page. + * + * @{ + */ + /** * @addtogroup Eina_Data_Types_Group Data Types * @@ -75,13 +203,82 @@ struct _Eina_Array 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 of @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; + +/** + * @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); + +/** + * @brief Set the step of an array. + * + * @param array The array. + * @param sizeof_eina_array Should be the value returned by sizeof(Eina_Array). + * @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. This function should be called when + * the array is not initialized. + */ EAPI void eina_array_step_set(Eina_Array *array, unsigned int sizeof_eina_array, unsigned int step) 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); + +/** + * @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. @p gdata 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. + * + * This function always return a valid array. 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, Eina_Bool (*keep)(void *data, void *gdata), void *gdata) EINA_ARG_NONNULL(1, 2); @@ -94,7 +291,33 @@ static inline void eina_array_data_set(const Eina_Array *array, unsigned int idx, const void *data) EINA_ARG_NONNULL(1); static inline unsigned int eina_array_count_get(const Eina_Array *array) EINA_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; + +/** + * @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; static inline Eina_Bool eina_array_foreach(Eina_Array *array, Eina_Each_Cb cb, @@ -146,6 +369,11 @@ static inline Eina_Bool eina_array_foreach(Eina_Array *array, * @} */ +/** + * @} + */ + + /** * @} */ diff --git a/legacy/eina/src/lib/eina_accessor.c b/legacy/eina/src/lib/eina_accessor.c index e8b0e05ff9..aec44ef9ca 100644 --- a/legacy/eina/src/lib/eina_accessor.c +++ b/legacy/eina/src/lib/eina_accessor.c @@ -174,7 +174,3 @@ eina_accessor_unlock(Eina_Accessor *accessor) return accessor->unlock(accessor); return EINA_TRUE; } - -/** - * @} - */ diff --git a/legacy/eina/src/lib/eina_array.c b/legacy/eina/src/lib/eina_array.c index 3bf6d73a92..c2980cbfca 100644 --- a/legacy/eina/src/lib/eina_array.c +++ b/legacy/eina/src/lib/eina_array.c @@ -17,95 +17,6 @@ */ -/** - * @page tutorial_array_page Array Tutorial - * - * The Array data type is allow the storage of data like a C array. - * It is designed such that the access to its element is very fast. - * But the addition or removal can be done only at the end of the - * array. To add or remove an element at any location, the Eina - * @ref Eina_List_Group is the correct container is the correct one. - * - * @section tutorial_error_basic_usage Basic Usage - * - * An array must created with eina_array_new(). That function - * takes an integer as parameter, which is the count of pointers to - * add when increasing the array size. Once the array is not used - * anymore, it must be destroyed with eina_array_free(). - * - * To append data at the end of the array, the function - * eina_array_push() must be used. To remove the data at the end of - * the array, eina_array_pop() must be used. Once the array is filled, - * one can check its elements by iterating over it. A while loop and - * eina_array_data_get() can be used, or else one can use the - * predefined macro EINA_ARRAY_ITER_NEXT(). To free all the elements, - * a while loop can be used with eina_array_count_get(). Here is an - * example of use: - * - * @code - * #include - * #include - * #include - * - * #include - * - * int main(void) - * { - * const char *strings[] = { - * "first string", - * "second string", - * "third string", - * "fourth string" - * }; - * Eina_Array *array; - * char *item; - * Eina_Array_Iterator iterator; - * unsigned int i; - * - * if (!eina_init()) - * { - * printf ("Error during the initialization of eina\n"); - * return EXIT_FAILURE; - * } - * - * array = eina_array_new(16); - * if (!array) - * goto shutdown; - * - * for (i = 0; i < 4; i++) - * { - * eina_array_push(array, strdup(strings[i])); - * } - * - * printf("array count: %d\n", eina_array_count_get(array)); - * EINA_ARRAY_ITER_NEXT(array, i, item, iterator) - * { - * printf("item #%d: %s\n", i, item); - * } - * - * while (eina_array_count_get(array)) - * { - * void *data; - * - * data = eina_array_pop(array); - * free(data); - * } - * - * eina_array_free(array); - * eina_shutdown(); - * - * return EXIT_SUCCESS; - * - * shutdown: - * eina_shutdown(); - * - * return EXIT_FAILURE; - * } - * @endcode - * - * To be continued - */ - #ifdef HAVE_CONFIG_H # include "config.h" #endif @@ -262,6 +173,7 @@ eina_array_accessor_free(Eina_Accessor_Array *it) MAGIC_FREE(it); } +/* used from eina_inline_array.x, thus a needed symbol */ EAPI Eina_Bool eina_array_grow(Eina_Array *array) { @@ -349,58 +261,6 @@ eina_array_shutdown(void) * API * *============================================================================*/ -/** - * @addtogroup Eina_Array_Group Array - * - * @brief These functions provide array management. - * - * The Array data type in Eina is designed to have a 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 container - * to use. - * - * To use the array data type, eina_init() must be called before any - * other array functions. When eina is no more array function is used, - * eina_shutdown() must be called to free all the resources. - * - * An array must be created with eina_array_new(). It allocated 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 All the other 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 positin, use - * eina_array_data_get(). The number of elements can be retrieved with - * eina_array_count_get(). - * - * For more information, you can look at the @ref tutorial_array_page. - * - * @{ - */ - -/** - * @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 of @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) { @@ -425,17 +285,6 @@ eina_array_new(unsigned int step) return array; } -/** - * @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) { @@ -446,18 +295,6 @@ eina_array_free(Eina_Array *array) MAGIC_FREE(array); } -/** - * @brief Set the step of an array. - * - * @param array The array. - * @param sizeof_eina_array Should be the value returned by sizeof(Eina_Array). - * @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. This function should be called when - * the array is not initialized. - */ EAPI void eina_array_step_set(Eina_Array *array, unsigned int sizeof_eina_array, @@ -483,16 +320,6 @@ eina_array_step_set(Eina_Array *array, EINA_MAGIC_SET(array, EINA_MAGIC_ARRAY); } -/** - * @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) { @@ -509,23 +336,6 @@ eina_array_flush(Eina_Array *array) array->data = NULL; } -/** - * @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. @p gdata 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. - * - * This function always return a valid array. 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, Eina_Bool (*keep)(void *data, void *gdata), @@ -620,18 +430,6 @@ eina_array_remove(Eina_Array *array, Eina_Bool (*keep)(void *data, return EINA_TRUE; } -/** - * @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) { @@ -662,18 +460,6 @@ eina_array_iterator_new(const Eina_Array *array) return &it->iterator; } -/** - * @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) { @@ -703,7 +489,3 @@ eina_array_accessor_new(const Eina_Array *array) return &ac->accessor; } - -/** - * @} - */