From b73180cd011e7fbee2b79e033b2d3353a7de0080 Mon Sep 17 00:00:00 2001 From: Vincent Torri Date: Sun, 7 Sep 2008 19:12:49 +0000 Subject: [PATCH] * add array doc * eina_array_push() returns now a bool * fix compilation SVN revision: 35871 --- legacy/eina/doc/Doxyfile | 6 +- legacy/eina/src/include/eina_array.h | 48 ++++-- legacy/eina/src/include/eina_inline_array.x | 76 ++++++++- legacy/eina/src/include/eina_private.h | 2 + legacy/eina/src/lib/eina_array.c | 174 +++++++++++++++++--- legacy/eina/src/lib/eina_error.c | 5 +- legacy/eina/src/lib/eina_inlist.c | 1 + 7 files changed, 270 insertions(+), 42 deletions(-) diff --git a/legacy/eina/doc/Doxyfile b/legacy/eina/doc/Doxyfile index e5f01fe155..4ad25749b4 100644 --- a/legacy/eina/doc/Doxyfile +++ b/legacy/eina/doc/Doxyfile @@ -278,7 +278,7 @@ EXTRACT_PRIVATE = NO # If the EXTRACT_STATIC tag is set to YES all static members of a file # will be included in the documentation. -EXTRACT_STATIC = NO +EXTRACT_STATIC = YES # If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) # defined locally in source files will be included in the documentation. @@ -367,7 +367,7 @@ INLINE_INFO = YES # alphabetically by member name. If set to NO the members will appear in # declaration order. -SORT_MEMBER_DOCS = YES +SORT_MEMBER_DOCS = NO # If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the # brief documentation of file, namespace and class members alphabetically @@ -530,7 +530,7 @@ INPUT_ENCODING = UTF-8 # *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx # *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm *.py *.f90 -FILE_PATTERNS = +FILE_PATTERNS = *.c *.h *.x # The RECURSIVE tag can be used to turn specify whether or not subdirectories # should be searched for input files as well. Possible values are YES and NO. diff --git a/legacy/eina/src/include/eina_array.h b/legacy/eina/src/include/eina_array.h index 6030936318..b35cfeb937 100644 --- a/legacy/eina/src/include/eina_array.h +++ b/legacy/eina/src/include/eina_array.h @@ -22,37 +22,57 @@ #include #include "eina_types.h" +#include "eina_error.h" #include "eina_iterator.h" #include "eina_accessor.h" -typedef struct _Eina_Array Eina_Array; /**< A generic vector */ -typedef void** Eina_Array_Iterator; +/** + * @defgroup Eina_Array_Group Array Functions + * + * @{ + */ -struct _Eina_Array /** An array of data */ +/** + * @typedef Eina_Array + * Type for generic vector. + */ +typedef struct _Eina_Array Eina_Array; + +/** + * @typedef Eina_Array_Iterator + * Type for an iterator oon arrays. + */ +typedef void **Eina_Array_Iterator; + +/** + * @struct _Eina_Array + * Type for an array of data. + */ +struct _Eina_Array { void **data; /**< Pointer to a vector of pointer to payload */ unsigned int total; /**< Total number of slot in the vector */ unsigned int count; /**< Number of activ slot 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 */ }; EAPI int eina_array_init (void); EAPI int eina_array_shutdown (void); -EAPI Eina_Array * eina_array_new (unsigned int step); -EAPI void eina_array_setup (Eina_Array *array, unsigned int step); +EAPI Eina_Array *eina_array_new (unsigned int step); EAPI void eina_array_free (Eina_Array *array); +EAPI void eina_array_step_set (Eina_Array *array, unsigned int step); EAPI void eina_array_clean (Eina_Array *array); EAPI void eina_array_flush (Eina_Array *array); EAPI void eina_array_remove (Eina_Array *array, Eina_Bool (*keep)(void *data, void *gdata), void *gdata); -EAPI Eina_Iterator *eina_array_iterator_new(const Eina_Array *array); -EAPI Eina_Accessor *eina_array_accessor_new(const Eina_Array *array); +static inline Eina_Bool eina_array_push (Eina_Array *array, const void *data); +static inline void *eina_array_pop (Eina_Array *array); +static inline void *eina_array_get (const Eina_Array *array, unsigned int index); +static inline unsigned int eina_array_count (const Eina_Array *array); -static inline void * eina_array_get (const Eina_Array *array, unsigned int index); -static inline void eina_array_push (Eina_Array *array, const void *data); -static inline void * eina_array_pop (Eina_Array *array); -static inline unsigned int eina_array_count (const Eina_Array *array); +EAPI Eina_Iterator *eina_array_iterator_new (const Eina_Array *array); +EAPI Eina_Accessor *eina_array_accessor_new (const Eina_Array *array); #define EINA_ARRAY_ITER_NEXT(array, index, item, iterator) \ for (index = 0, iterator = (array)->data, item = iterator != NULL ? *(iterator) : NULL; \ @@ -61,4 +81,8 @@ static inline unsigned int eina_array_count (const Eina_Array *array); #include "eina_inline_array.x" +/** + * @} + */ + #endif diff --git a/legacy/eina/src/include/eina_inline_array.x b/legacy/eina/src/include/eina_inline_array.x index 7a9fa22a62..a0aa9b5d47 100644 --- a/legacy/eina/src/include/eina_inline_array.x +++ b/legacy/eina/src/include/eina_inline_array.x @@ -25,6 +25,10 @@ # define UNLIKELY(x) (x) #endif +/** + * @cond LOCAL + */ + static inline Eina_Bool eina_array_grow(Eina_Array *array) { @@ -32,8 +36,12 @@ eina_array_grow(Eina_Array *array) unsigned int total; total = array->total + array->step; + eina_error_set(0); tmp = realloc(array->data, sizeof (void*) * total); - if (UNLIKELY(!tmp)) return 0; + if (UNLIKELY(!tmp)) { + eina_error_set(EINA_ERROR_OUT_OF_MEMORY); + return 0; + } array->total = total; array->data = tmp; @@ -41,15 +49,52 @@ eina_array_grow(Eina_Array *array) return 1; } -static inline void +/** + * @endcond + */ + +/** + * @addtogroup Eina_Array_Group Array Functions + * + * @brief These functions provide array management. + * + * @{ + */ + +/** + * @brief Append a data to an array. + * + * @param array The array. + * @param data The data to add. + * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * + * This function appends @p data to @p array. For performance + * reasons, there is no check of @p array. If it is @c NULL or + * invalid, the program may crash. if an allocation is necessary and + * fails, #EINA_FALSE is returned and #EINA_ERROR_OUT_OF_MEMORY is + * set. Otherwise, #EINA_TRUE is returned. + */ +static inline Eina_Bool eina_array_push(Eina_Array *array, const void *data) { if (UNLIKELY((array->count + array->step) > array->total)) - if (!eina_array_grow(array)) return ; + if (!eina_array_grow(array)) return EINA_FALSE; array->data[array->count++] = (void*) data; + return EINA_TRUE; } +/** + * @brief Remove the last data of an array. + * + * @param array The array. + * @return The retrieved data. + * + * This function removes the last data of @p array and returns it. For + * performance reasons, there is no check of @p array. If it is + * @c NULL or invalid, the program may crash. If the count member is + * less or equal than 0, @c NULL is returned. + */ static inline void * eina_array_pop(Eina_Array *array) { @@ -57,16 +102,41 @@ eina_array_pop(Eina_Array *array) return array->data[--array->count]; } +/** + * @brief Return the data at a given position in an array. + * + * @param array The array. + * @param index The potition of the data to retrieve. + * @return The retrieved data. + * + * This function returns the data at the position @p index in @p + * array. For performance reasons, there is no check of @p array or @p + * index. If it is @c NULL or invalid, the program may crash. + */ static inline void * eina_array_get(const Eina_Array *array, unsigned int index) { return array->data[index]; } +/** + * @brief Return the number of elements in the array. + * + * @param array The array. + * @return The number of elements. + * + * This function returns the number of elements in @p array. For + * performance reasons, there is no check of @p array. If it is + * @c NULL or invalid, the program may crash. + */ static inline unsigned int eina_array_count(const Eina_Array *array) { return array->count; } +/** + * @} + */ + #endif diff --git a/legacy/eina/src/include/eina_private.h b/legacy/eina/src/include/eina_private.h index acc8e0f171..5286207af9 100644 --- a/legacy/eina/src/include/eina_private.h +++ b/legacy/eina/src/include/eina_private.h @@ -19,6 +19,8 @@ #ifndef EINA_PRIVATE_H_ #define EINA_PRIVATE_H_ +#include + #include "eina_iterator.h" #include "eina_accessor.h" diff --git a/legacy/eina/src/lib/eina_array.c b/legacy/eina/src/lib/eina_array.c index 3edf6aa92f..997dc64ec2 100644 --- a/legacy/eina/src/lib/eina_array.c +++ b/legacy/eina/src/lib/eina_array.c @@ -36,6 +36,10 @@ * Local * *============================================================================*/ +/** + * @cond LOCAL + */ + typedef struct _Eina_Iterator_Array Eina_Iterator_Array; struct _Eina_Iterator_Array { @@ -98,6 +102,11 @@ eina_array_accessor_free(Eina_Accessor_Array *it) free(it); } +/** + * @endcond + */ + + /*============================================================================* * Global * *============================================================================*/ @@ -106,40 +115,61 @@ eina_array_accessor_free(Eina_Accessor_Array *it) * API * *============================================================================*/ +/** + * @addtogroup Eina_Array_Group Array Functions + * + * @brief These functions provide array management. + * + * @{ + */ + +/** + * @brief Initialize the array module. + * + * @return 1 or greater on success, 0 on error. + * + * This function just sets up the error module or Eina. It is also + * called by eina_init(). It returns 0 on failure, otherwise it + * returns the number of times eina_error_init() has already been + * called. + */ EAPI int eina_array_init(void) { return eina_error_init(); } +/** + * @brief Shut down the array module. + * + * @return 0 when the error module is completely shut down, 1 or + * greater otherwise. + * + * This function just shut down the error module set up by + * eina_array_init(). It is also called by eina_shutdown(). It returns + * 0 when it is called the same number of times than + * eina_error_init(). + */ EAPI int eina_array_shutdown(void) { return eina_error_shutdown(); } -EAPI void -eina_array_clean(Eina_Array *array) -{ - array->count = 0; -} - -EAPI void -eina_array_setup(Eina_Array *array, unsigned int step) -{ - array->step = step; -} - -EAPI void -eina_array_flush(Eina_Array *array) -{ - array->count = 0; - array->total = 0; - - if (array->data) free(array->data); - array->data = NULL; -} - +/** + * @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 hat case, the error is set to + * #EINA_ERROR_OUT_OF_MEMORY. + */ EAPI Eina_Array * eina_array_new(unsigned int step) { @@ -160,6 +190,15 @@ eina_array_new(unsigned int step) return array; } +/** + * @brief Free an array. + * + * @param array The array to free. + * + * This function free @p array. It calls first eina_array_flush() then + * free the memory of the pointeur. It's up to the user to free the + * memory allocated for the elements of @p array. + */ EAPI void eina_array_free(Eina_Array *array) { @@ -167,6 +206,69 @@ eina_array_free(Eina_Array *array) free(array); } +/** + * @brief Set the step of an array. + * + * @param array The array. + * @param step The count of pointers to add when increasing the array size. + * + * This function set 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. + */ +EAPI void +eina_array_step_set(Eina_Array *array, unsigned int step) +{ + array->step = step; +} + +/** + * @brief Clean an array. + * + * @param array The array to clean. + * + * This function set the count member of @p array to 0. 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_clean(Eina_Array *array) +{ + array->count = 0; +} + +/** + * @brief Flush an array. + * + * @param array The array to flush. + * + * This function set 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) +{ + array->count = 0; + array->total = 0; + + if (array->data) free(array->data); + 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. + * + * 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. + */ EAPI void eina_array_remove(Eina_Array *array, Eina_Bool (*keep)(void *data, void *gdata), void *gdata) { @@ -244,6 +346,18 @@ eina_array_remove(Eina_Array *array, Eina_Bool (*keep)(void *data, void *gdata), array->count = total; } +/** + * @brief Returned a new iterator asociated 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) { @@ -268,6 +382,18 @@ eina_array_iterator_new(const Eina_Array *array) return &it->iterator; } +/** + * @brief Returned a new accessor asociated 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) { @@ -291,3 +417,7 @@ eina_array_accessor_new(const Eina_Array *array) return &it->accessor; } +/** + * @} + */ + diff --git a/legacy/eina/src/lib/eina_error.c b/legacy/eina/src/lib/eina_error.c index 4c92eab239..d922e7a79f 100644 --- a/legacy/eina/src/lib/eina_error.c +++ b/legacy/eina/src/lib/eina_error.c @@ -415,7 +415,7 @@ static char *_colors[EINA_ERROR_LEVELS] = { /** * @addtogroup Eina_Error_Group Error Functions * - * @brief These functions provide error management for porjects. + * @brief These functions provide error management for projects. * * The error system must be initialized with eina_error_init() and * shut down with eina_error_shutdown(). The most generic way to print @@ -593,7 +593,8 @@ EAPI const char * eina_error_msg_get(Eina_Error error) * * @return The last error. * - * This function returns the last error set by eina_error_set(). + * This function returns the last error set by eina_error_set(). The + * description of the message is returned by eina_error_msg_get(). */ EAPI Eina_Error eina_error_get(void) { diff --git a/legacy/eina/src/lib/eina_inlist.c b/legacy/eina/src/lib/eina_inlist.c index 05067d800b..ac895bd09d 100644 --- a/legacy/eina/src/lib/eina_inlist.c +++ b/legacy/eina/src/lib/eina_inlist.c @@ -24,6 +24,7 @@ #include #include "eina_inlist.h" +#include "eina_error.h" #include "eina_private.h" /* FIXME: TODO please, refactor this :) */