forked from enlightenment/efl
eina: Improve eina_array function documentation
Summary: Define return values when errors occur. Eliminate use of the term 'vector' to avoid confusion with eina_vector. Cleanup grammar throughout. Reviewers: cedric, Hermet Reviewed By: Hermet Subscribers: #committers, zmike Tags: #efl Differential Revision: https://phab.enlightenment.org/D6043 Reviewed-by: Cedric BAIL <cedric@osg.samsung.com>
This commit is contained in:
parent
a0db6b351a
commit
6ba44f9006
|
@ -49,7 +49,7 @@
|
|||
* Before we can start using any array function we need to initialize eina:
|
||||
* @until eina_init
|
||||
*
|
||||
* So now to actually create our array. The only interesting thing here is the
|
||||
* So now to actually create our array. The interesting thing here is the
|
||||
* argument given to the eina_array_new() function. This argument sets how fast
|
||||
* the array grows.
|
||||
* @until array_new
|
||||
|
@ -101,8 +101,8 @@
|
|||
* @skip #include
|
||||
* @until Eina.h
|
||||
*
|
||||
* This the callback we are going to use to decide which strings stay on the
|
||||
* array and which will be removed. We use something simple, but this can be as
|
||||
* This is the callback we are going to use to decide which strings stay on the
|
||||
* array and which will be removed. We use something simple, but this can be as
|
||||
* complex as you like:
|
||||
* @until }
|
||||
*
|
||||
|
@ -144,10 +144,10 @@
|
|||
* @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 position, the Eina @ref Eina_List_Group is the correct container
|
||||
* to use.
|
||||
* 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 arbitrary positions, 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 no more eina array functions are used,
|
||||
|
@ -156,9 +156,9 @@
|
|||
* 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 frees the memory used by the Eina_Array
|
||||
* itself, but does not free any memory used to store the data of each element.
|
||||
* itself, but does not free any memory used to store the data of each element.
|
||||
* To free that memory you must iterate over the array and free each data element
|
||||
* individually. A convenient way to do that is by using #EINA_ARRAY_ITER_NEXT.
|
||||
* individually. A convenient way to do that is by using #EINA_ARRAY_ITER_NEXT.
|
||||
* An example of that pattern is given in the description of @ref EINA_ARRAY_ITER_NEXT.
|
||||
*
|
||||
* @warning Functions do not check if the used array is valid or not. It's up to
|
||||
|
@ -171,15 +171,12 @@
|
|||
* eina_array_data_get(). The number of elements can be retrieved with
|
||||
* eina_array_count().
|
||||
*
|
||||
* 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 from an
|
||||
* array it @b may shrink.
|
||||
*
|
||||
* Allocating memory is expensive, so when the array needs to grow it allocates
|
||||
* enough memory to hold @p step additional elements, not just the element
|
||||
* currently being added. Similarly if you remove elements, it won't free space
|
||||
* until you have removed @p step elements.
|
||||
* An Eina_Array differs most notably from a conventional C array in that it can
|
||||
* grow and shrink dynamically as elements are added and removed.
|
||||
* Since allocating memory is expensive, when the array needs to grow it adds
|
||||
* enough memory to hold @p step additional elements, not just the element
|
||||
* currently being added. Similarly when elements are removed, it won't deallocate
|
||||
* until @p step elements are removed.
|
||||
*
|
||||
* The following image illustrates how an Eina_Array grows:
|
||||
*
|
||||
|
@ -214,7 +211,7 @@
|
|||
|
||||
/**
|
||||
* @typedef Eina_Array
|
||||
* Type for a generic vector.
|
||||
* Type for a generic one-dimensional linear data structure.
|
||||
*/
|
||||
typedef struct _Eina_Array Eina_Array;
|
||||
|
||||
|
@ -233,10 +230,10 @@ struct _Eina_Array
|
|||
#define EINA_ARRAY_VERSION 1
|
||||
int version; /**< Should match EINA_ARRAY_VERSION used when compiled your apps, provided for ABI compatibility */
|
||||
|
||||
void **data; /**< Pointer to a vector of pointer to payload */
|
||||
unsigned int total; /**< Number of allocated slots in the vector */
|
||||
unsigned int count; /**< Number of slots in the vector that actually point to data */
|
||||
unsigned int step; /**< Number of slots to grow or shrink the vector */
|
||||
void **data; /**< Pointer to a C array of pointers to payloads */
|
||||
unsigned int total; /**< Number of allocated slots in @p data */
|
||||
unsigned int count; /**< Number of used slots in @p data that point to valid payloads */
|
||||
unsigned int step; /**< Number of slots to grow or shrink @p data */
|
||||
EINA_MAGIC
|
||||
};
|
||||
|
||||
|
@ -248,7 +245,7 @@ struct _Eina_Array
|
|||
* @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
|
||||
* allocates @p step elements. When that buffer is full, 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
|
||||
|
@ -261,12 +258,12 @@ EAPI Eina_Array *eina_array_new(unsigned int step) EINA_WARN_UNUSED_RESULT EINA_
|
|||
*
|
||||
* @param[in] array The array to free.
|
||||
*
|
||||
* This function frees @p array. It calls first eina_array_flush() then
|
||||
* frees the memory of the pointer. It does not free the memory
|
||||
* allocated for the elements of @p array. To free them, walk the array with
|
||||
* #EINA_ARRAY_ITER_NEXT.
|
||||
* This function finalizes @p array by flushing (see
|
||||
* eina_array_flush()), and then freeing the memory of the pointer. It
|
||||
* does not free the memory allocated for the elements of @p array. To
|
||||
* free them, walk the array with #EINA_ARRAY_ITER_NEXT.
|
||||
*/
|
||||
EAPI void eina_array_free(Eina_Array *array);
|
||||
EAPI void eina_array_free(Eina_Array *array);
|
||||
|
||||
/**
|
||||
* @brief Sets the step of an array.
|
||||
|
@ -285,24 +282,24 @@ EAPI void eina_array_step_set(Eina_Array *array,
|
|||
unsigned int sizeof_eina_array,
|
||||
unsigned int step) EINA_ARG_NONNULL(1);
|
||||
/**
|
||||
* @brief Cleans an array.
|
||||
* @brief Clears an array of its elements, without deallocating memory.
|
||||
*
|
||||
* @param[in,out] 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 and
|
||||
* 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.
|
||||
* This function sets the @p array's member count to 0 without freeing
|
||||
* memory. This facilitates emptying an array and quickly refilling it
|
||||
* with new elements. 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);
|
||||
|
||||
/**
|
||||
* @brief Flushes an array.
|
||||
* @brief Clears an array's elements and deallocates the memory.
|
||||
*
|
||||
* @param[in,out] 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,
|
||||
* This function sets the count and total members of @p array to 0, and
|
||||
* frees its data member and sets it to NULL. For performance reasons,
|
||||
* there is no check of @p array. If it is @c NULL or invalid, the
|
||||
* program may crash.
|
||||
*/
|
||||
|
@ -329,32 +326,30 @@ EAPI Eina_Bool eina_array_remove(Eina_Array * array,
|
|||
void *gdata) EINA_ARG_NONNULL(1, 2);
|
||||
|
||||
/**
|
||||
* @brief Appends a data to an array.
|
||||
* @brief Appends a data item to an array.
|
||||
*
|
||||
* @param[in,out] array The array.
|
||||
* @param[in] data The data to add.
|
||||
* @return #EINA_TRUE on success, #EINA_FALSE otherwise.
|
||||
* @return #EINA_TRUE on success, #EINA_FALSE if allocation is necessary
|
||||
* and fails or if @p data is @c NULL.
|
||||
*
|
||||
* 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 @p data is @c NULL, or if an
|
||||
* allocation is necessary and fails, #EINA_FALSE is returned
|
||||
* Otherwise, #EINA_TRUE is returned.
|
||||
* invalid, the program may crash.
|
||||
*/
|
||||
static inline Eina_Bool eina_array_push(Eina_Array *array,
|
||||
const void *data) EINA_ARG_NONNULL(1, 2);
|
||||
|
||||
/**
|
||||
* @brief Removes the last data of an array.
|
||||
* @brief Removes the last data item in an array.
|
||||
*
|
||||
* @param[in,out] array The array.
|
||||
* @return The retrieved data.
|
||||
* @return The retrieved data, or @c NULL if there are no remaining items.
|
||||
*
|
||||
* This function removes the last data of @p array, decreases the count
|
||||
* of @p array and returns the data. 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.
|
||||
* This function removes the last data item from @p array, decreases the
|
||||
* length of @p array and returns the data item. For performance reasons,
|
||||
* there is no check of @p array, so if it is @c NULL or invalid, the
|
||||
* program may crash.
|
||||
*/
|
||||
static inline void *eina_array_pop(Eina_Array *array) EINA_ARG_NONNULL(1);
|
||||
|
||||
|
@ -367,7 +362,8 @@ static inline void *eina_array_pop(Eina_Array *array) EINA_ARG_NONNULL(1);
|
|||
*
|
||||
* This function returns the data at the position @p idx in @p
|
||||
* array. For performance reasons, there is no check of @p array or @p
|
||||
* idx. If it is @c NULL or invalid, the program may crash.
|
||||
* idx. If @p array is @c NULL or invalid, or if @p idx is larger than
|
||||
* the array's size, the program may crash.
|
||||
*/
|
||||
static inline void *eina_array_data_get(const Eina_Array *array,
|
||||
unsigned int idx) EINA_ARG_NONNULL(1);
|
||||
|
@ -378,15 +374,17 @@ static inline void *eina_array_data_get(const Eina_Array *array,
|
|||
* @param[in] idx The position of the data to set.
|
||||
* @param[in] 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, you
|
||||
* 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.
|
||||
* This function sets the data at the position @p idx in @p array to @p
|
||||
* data, this effectively replaces the previously held data, you 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 @p
|
||||
* array is @c NULL or invalid, or if @p idx is larger than the array's
|
||||
* size, the program may crash.
|
||||
*/
|
||||
static inline void eina_array_data_set(const Eina_Array *array,
|
||||
unsigned int idx,
|
||||
const void *data) EINA_ARG_NONNULL(1);
|
||||
|
||||
/**
|
||||
* @deprecated use eina_array_count()
|
||||
* @brief Returns the number of elements in an array.
|
||||
|
@ -395,7 +393,7 @@ static inline void eina_array_data_set(const Eina_Array *array,
|
|||
* @return The number of elements.
|
||||
*
|
||||
* This function returns the number of elements in @p array (array->count). For
|
||||
* performance reasons, there is no check of @p array. If it is
|
||||
* performance reasons, there is no check of @p array, so if it is
|
||||
* @c NULL or invalid, the program may crash.
|
||||
*
|
||||
*/
|
||||
|
@ -408,7 +406,7 @@ static inline unsigned int eina_array_count_get(const Eina_Array *array) EINA_AR
|
|||
* @return The number of elements.
|
||||
*
|
||||
* This function returns the number of elements in @p array (array->count). For
|
||||
* performance reasons, there is no check of @p array. If it is
|
||||
* performance reasons, there is no check of @p array, so if it is
|
||||
* @c NULL or invalid, the program may crash.
|
||||
*/
|
||||
static inline unsigned int eina_array_count(const Eina_Array *array) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
|
||||
|
@ -417,12 +415,14 @@ static inline unsigned int eina_array_count(const Eina_Array *array) EINA_ARG_NO
|
|||
* @brief Gets a new iterator associated with an array.
|
||||
*
|
||||
* @param[in] array The array.
|
||||
* @return A new iterator.
|
||||
* @return A new iterator, or @c NULL if @p array is @c NULL or has no
|
||||
* items, or if memory could not be allocated.
|
||||
*
|
||||
* 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 @c NULL. If the memory can
|
||||
* not be allocated, @c NULL is returned. Otherwise, a valid iterator is returned.
|
||||
* This function allocates a new iterator associated with @p array.
|
||||
* Use EINA_ARRAY_ITER_NEXT() to iterate through the array's data items
|
||||
* in order of entry.
|
||||
*
|
||||
* @see Eina_Iterator_Group
|
||||
*/
|
||||
EAPI Eina_Iterator *eina_array_iterator_new(const Eina_Array *array) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
|
||||
|
||||
|
@ -430,27 +430,28 @@ EAPI Eina_Iterator *eina_array_iterator_new(const Eina_Array *array) EINA
|
|||
* @brief Gets a new accessor associated with an array.
|
||||
*
|
||||
* @param[in] array The array.
|
||||
* @return A new accessor.
|
||||
* @return A new accessor, or @c NULL if @p array is @c NULL or has no
|
||||
* items, or if memory could not be allocated.
|
||||
*
|
||||
* 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 @c NULL. If the memory can
|
||||
* not be allocated, @c NULL is returned. Otherwise, a valid accessor is
|
||||
* returned.
|
||||
* This function returns a newly allocated accessor associated with
|
||||
* @p array. Accessors differ from iterators in that they permit
|
||||
* random access.
|
||||
*
|
||||
* @see Eina_Accessor_Group
|
||||
*/
|
||||
EAPI Eina_Accessor *eina_array_accessor_new(const Eina_Array *array) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
|
||||
|
||||
/**
|
||||
* @brief Provides a safe way to iterate over an array.
|
||||
* @brief Iterates over an array using a callback function.
|
||||
*
|
||||
* @param[in] array The array to iterate over.
|
||||
* @param[in] cb The callback to call for each item.
|
||||
* @param[in] cb The callback to invoke for each item.
|
||||
* @param[in] fdata The user data to pass to the callback.
|
||||
* @return #EINA_TRUE if it successfully iterated all items of the array.
|
||||
*
|
||||
* This function provides a safe way to iterate over an array. @p cb should
|
||||
* return #EINA_TRUE as long as you want the function to continue iterating.
|
||||
* If @p cb returns #EINA_FALSE, iterations will stop and the function will also
|
||||
* This function iterates over an array in order, calling @p cb for each
|
||||
* item. @p cb should return #EINA_TRUE if the loop should continue, or
|
||||
* #EINA_FALSE to exit the loop, in which case eina_array_foreach() will
|
||||
* return #EINA_FALSE.
|
||||
*/
|
||||
static inline Eina_Bool eina_array_foreach(Eina_Array *array,
|
||||
|
@ -458,20 +459,18 @@ static inline Eina_Bool eina_array_foreach(Eina_Array *array,
|
|||
void *fdata);
|
||||
/**
|
||||
* @def EINA_ARRAY_ITER_NEXT
|
||||
* @brief Definition for the macro to iterate over an array easily.
|
||||
* @brief Iterates through an array's elements.
|
||||
*
|
||||
* @param[in] array The array to iterate over.
|
||||
* @param[out] index The integer number that is increased while iterating.
|
||||
* @param[out] item The data
|
||||
* @param[in,out] iterator The iterator
|
||||
* @param[in,out] iterator The #Eina_Array_Iterator.
|
||||
*
|
||||
* This macro allows the iteration over @p array in an easy way. It
|
||||
* iterates from the first element to the last one. @p index is an
|
||||
* integer that increases from 0 to the number of elements. @p item is
|
||||
* the data of each element of @p array, so it is a pointer to a type
|
||||
* chosen by the user. @p iterator is of type #Eina_Array_Iterator.
|
||||
* This macro iterates over @p array in order, increasing @p index from
|
||||
* the first to last element and setting @p item to each element's data
|
||||
* item in turn.
|
||||
*
|
||||
* This macro can be used for freeing the data of an array, like in
|
||||
* This macro can be used for freeing the data of an array, such as
|
||||
* the following example:
|
||||
*
|
||||
* @code
|
||||
|
|
Loading…
Reference in New Issue