* @page eina_inarray_example_01 Eina inline array usage
* @dontinclude eina_inarray_01.c
*
- * This example will create an inline array of chars, add some elements, print
- * it, re-purpose the array to store ints, add some elements and print that.
+ * This example creates an inline array of chars, adds some elements, prints
+ * them, re-purposes the array to store ints, adds some elements and print that.
*
- * We'll start with a function to compare ints we need this because the '>'
+ * We are going to start with a function to compare ints. We need this because the '>'
* operator is not a function and can't be used where Eina_Compare_Cb is needed.
* @skip int
* @until }
* want to store:
* @until inarray_new
* @note The second parameter(the step) is left at zero which means that eina
- * will choose an appropriate value, this should @b only be changed if it's
- * known, beforehand, how many elements the array will have.
+ * chooses an appropriate value, this should @b only be changed if it's
+ * known, beforehand, that how many elements the array has.
*
* Once we have an array we can start adding elements to it. Because the
- * insertion function expect a memory address we have to put the value we want
- * to store in a variable(this should be no problem since in real world usage
- * that's usually where the value will be anyways):
+ * insertion function expects a memory address we have to put the value we want
+ * to store in a variable(this should be no problem since in the real world usage
+ * that's usually where the value is anyways):
* @until push
* @note Because the inline array copies the value given to it we can later
* change @c ch, which we do, without affecting the contents of the array.
* @until push
* @until push
*
- * We will then iterate over our array and print every position of it. The thing
- * to note here is not so much the values which will be the expected 'a', 'b',
- * 'c' and 'd', but rather the memory address of these values, they are
+ * We then iterate over our array and print every position of it. The thing
+ * to note here is not so much the values, which are the expected 'a', 'b',
+ * 'c', and 'd', but rather the memory address of these values, they are
* sequential:
* @until printf
* @until printf
*
- * We'll now use our array to store ints, so we need to first erase every member
+ * We are now going to use our array to store ints, so we need to first erase every member
* currently on the array:
* @until _flush
*
- * And then to be able to store a different type on the same array we use the
+ * And then to be able to store a different type on the same array, we use the
* eina_inarray_step_set() function, which is just like the eina_inarray_new()
- * function except it receives already allocated memory. This time we're going
- * to ask eina to use a step of size 4 because that's how many elements we'll be
- * putting on the array:
+ * function except it receives an already allocated memory. This time we're going
+ * to ask eina to use a step of size 4 because that's how many elements we are going to
+ * put in the array:
* @until _step_set
* @note Strictly speaking the reason to call eina_inarray_step_set() is not
- * because we're storing different type, but rather because our types have
+ * because we're storing a different type, but because our types have
* different sizes. Eina inline arrays don't actually know anything about types,
- * they only deal in blocks of memory of a given size.
- * @note Since eina_inarray_step_set() receives already allocated memory you can(and
- * it is in fact good practice) use inline arrays not declared as pointers:
+ * they only deal with blocks of memory of a given size.
+ * @note Since eina_inarray_step_set() receives already allocated memory, you can(and
+ * it is in fact a good practice) use inline arrays that are not declared as pointers:
* @code
* Eina_Inarray arr;
* eina_inarray_step_set(&arr, sizeof(arr), sizeof(int), 4);
* @until push
* @until push
*
- * Just to change things up a bit we've left out the 99 value, but will still
- * add it in such a way to keep the array ordered. There are many ways to do
+ * Just to change things up a bit we've left out the 99 value, but we still
+ * add it in such a way that it keeps the array ordered. There are many ways to do
* this, we could use eina_inarray_insert_at(), or we could change the value
* of the last member using eina_inarray_replace_at() and then append the values
* in the right order, but for no particular reason we're going to use
* @page eina_inarray_example_02 Eina inline array of strings
* @dontinclude eina_inarray_02.c
*
- * This example will create an inline array of strings, add some elements and
- * then print them. This example is based on @ref eina_array_01_example_page and
+ * This example creates an inline array of strings, adds some elements, and
+ * then prints them. This example is based on @ref eina_array_01_example_page and
* @ref eina_inarray_example_01.
*
* We start with some variable declarations and eina initialization:
* We then create the array much like we did on @ref eina_inarray_example_01 :
* @until inarray_new
*
- * The point were this example significantly differs from the first eina inline
- * array example. We'll not be adding the strings themselves to the array since
- * their size varies, we'll store pointer to the strings instead. We therefore
+ * The point is this example significantly differs from the first eina inline
+ * array example. We are not going to add the strings themselves to the array since
+ * their size varies, we are going to store a pointer to the strings instead. We therefore
* use @c char** to populate our inline array:
* @until }
*
*/
/**
- * @addtogroup Eina_Data_Types_Group Data Types
- *
+ * @defgroup Eina_Inline_Array_Group Inline Array
+ * @ingroup Eina_Containers_Group
* @since 1.2
*
- * @{
- */
-
-/**
- * @addtogroup Eina_Containers_Group Containers
+ * @brief Inline array is a container that stores the data itself, not the pointers to the data.
*
- * @{
- */
-
-/**
- * @defgroup Eina_Inline_Array_Group Inline Array
- *
- * Inline array is a container that stores the data itself not pointers to data,
- * this means there is no memory fragmentation, also for small data types(such
- * as char, short, int, etc.) it's more memory efficient.
+ * This means there is no memory fragmentation, also for small data types(such
+ * as char, short, int, and so on) it's more memory efficient.
*
* Usage of the inline array is very similar to that of other
* @ref Eina_Containers_Group, like all arrays adding elements to the beginning
/**
* @typedef Eina_Inarray
- * Inlined array type.
+ * @brief Type for the inlined array.
*
* @since 1.2
*/
typedef struct _Eina_Inarray Eina_Inarray;
/**
- * Inline array structure, use #Eina_Inarray typedef instead.
+ * @brief Inline array structure.
+ *
+ * @note Use #Eina_Inarray instead.
*
- * Do not modify these fields directly, use eina_inarray_step_set() or
- * eina_inarray_new() instead.
+ * @note Do not modify these fields directly, use eina_inarray_step_set() or
+ * eina_inarray_new() instead.
*
* @since 1.2
*/
struct _Eina_Inarray
{
#define EINA_ARRAY_VERSION 1
- int version; /**< Should match EINA_ARRAY_VERSION used when compiled your apps, provided for ABI compatibility */
+ int version; /**< Should match the EINA_ARRAY_VERSION used when compiling your apps, provided for ABI compatibility */
- unsigned int member_size; /**< byte size of each entry in members */
- unsigned int len; /**< number of elements used in members */
- unsigned int max; /**< number of elements allocated in members */
- unsigned int step; /**< amount to grow number of members allocated */
- void *members; /**< actual array of elements */
+ unsigned int member_size; /**< Byte size of each entry in the members */
+ unsigned int len; /**< Number of elements used by the members */
+ unsigned int max; /**< Number of elements allocated to the members */
+ unsigned int step; /**< Amount to grow the number of members allocated */
+ void *members; /**< Actual array of elements */
EINA_MAGIC
};
/**
- * @brief Create new inline array.
+ * @brief Creates a new inline array.
*
- * @param member_size size of each member in the array.
- * @param step when resizing the array, do this using the following
- * extra amount.
- * @return The new inline array table or @c NULL on failure.
+ * @param[in] member_size The size of each member in the array
+ * @param[in] step The step size by which to resize the array, do this using the following
+ * extra amount
+ * @return The new inline array table, otherwise @c NULL on failure
*
- * Create a new array where members are inlined in a sequence. Each
- * member has @a member_size bytes.
+ * @details This creates a new array where members are inlined in a sequence. Each
+ * member has @a member_size bytes.
*
- * If the @a step is 0, then a safe default is chosen.
+ * @note If the @a step is @c 0, then a safe default is chosen.
*
- * On failure, @c NULL is returned. If @a member_size is zero, then @c NULL
- * is returned.
+ * @note On failure, @c NULL is returned. If @p member_size is zero, then @c NULL is returned.
*
* @see eina_inarray_free()
*
unsigned int step) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
/**
- * @brief Free array and its members.
- * @param array array object
+ * @brief Frees an array and its members.
+ *
+ * @param[in] array The array object
*
* @see eina_inarray_flush()
*
EAPI void eina_inarray_free(Eina_Inarray *array) EINA_ARG_NONNULL(1);
/**
- * @brief Initialize inline array.
- * @param array array object to initialize.
- * @param sizeof_eina_inarray the initial size of the array.
- * @param member_size size of each member in the array.
- * @param step when resizing the array, do this using the following
- * extra amount.
+ * @brief Initializes an inline array.
+ *
+ * @param[in] array The array object to initialize
+ * @param[in] sizeof_eina_inarray The size of array object
+ * @param[in] member_size The size of each member in the array
+ * @param[in] step The step size by which to resize the array, do this using the following
+ * extra amount
*
- * Initialize array. If the @a step is @c 0, then a safe default is
- * chosen.
+ * @details This initializes an array. If the @p step is @c 0, then a safe default is
+ * chosen.
*
- * This is useful for arrays inlined into other structures or
- * allocated at stack.
+ * @note This is useful for arrays inlined into other structures or
+ * allocated to a stack.
*
* @see eina_inarray_flush()
*
unsigned int step) EINA_ARG_NONNULL(1);
/**
- * @brief Remove every member from array.
- * @param array array object
+ * @brief Removes every member from the array.
+ *
+ *
+ * @param[in] array The array object
*
* @since 1.2
*/
EAPI void eina_inarray_flush(Eina_Inarray *array) EINA_ARG_NONNULL(1);
/**
- * @brief Copy the data as the last member of the array.
- * @param array array object
- * @param data data to be copied at the end
- * @return the index of the new member or -1 on errors.
+ * @brief Copies the data as the last member of the array.
*
- * Copies the given pointer contents at the end of the array. The
- * pointer is not referenced, instead its contents is copied to the
- * members array using the previously defined @c member_size.
+ * @param[in] array The array object
+ * @param[in] data The data to be copied at the end
+ * @return The index of the new member, otherwise @c -1 on errors
*
- * @see eina_inarray_insert_at().
+ * @details This copies the given pointer contents at the end of the array. The
+ * pointer is not referenced, instead its contents are copied to the
+ * members array using the previously defined @c member_size.
+ *
+ * @see eina_inarray_insert_at()
*
* @since 1.2
*/
/**
* @brief Allocate new item at the end of the array.
- * @param array array object
- * @param size number of new item to allocate
*
- * The returned pointer is only valid until you use any other eina_inarray
- * function.
+ * @param[in] array The array object
+ * @param[in] size The number of new item to allocate
+ *
+ * @note The returned pointer is only valid until you use any other eina_inarray
+ * function.
*
* @since 1.8
*/
EAPI void *eina_inarray_grow(Eina_Inarray *array, unsigned int size);
/**
- * @brief Copy the data to array at position found by comparison function
- * @param array array object
- * @param data data to be copied
- * @param compare compare function
- * @return the index of the new member or @c -1 on errors.
+ * @brief Copies the data to the array at a position found by the comparison function.
*
- * Copies the given pointer contents at the array position defined by
- * given @a compare function. The pointer is not referenced, instead
- * its contents is copied to the members array using the previously
- * defined @c member_size.
+ * @param[in] array The array object
+ * @param[in] data The data to be copied
+ * @param[in] compare The compare function
+ * @return The index of the new member, otherwise @c -1 on errors
*
- * The data given to @a compare function are the pointer to member
- * memory itself, do no change it.
+ * @details This copies the given pointer contents at the array position defined by the
+ * given @a compare function. The pointer is not referenced, instead
+ * its contents are copied to the members array using the previously
+ * defined @c member_size.
+ *
+ * @note The data given to the @p compare function is a pointer to the member
+ * memory itself, do no change it.
*
* @see eina_inarray_insert_sorted()
* @see eina_inarray_insert_at()
Eina_Compare_Cb compare) EINA_ARG_NONNULL(1, 2, 3);
/**
- * @brief Copy the data to array at position found by comparison function
- * @param array array object
- * @param data data to be copied
- * @param compare compare function
- * @return the index of the new member or @c -1 on errors.
+ * @brief Copies the data to the array at a position found by the comparison function.
+ *
+ * @param[in] array The array object
+ * @param[in] data The data to be copied
+ * @param[in] compare The compare function
+ * @return The index of the new member, otherwise @c -1 on errors
*
- * Copies the given pointer contents at the array position defined by
- * given @a compare function. The pointer is not referenced, instead
- * its contents is copied to the members array using the previously
- * defined @c member_size.
+ * @details This copies the given pointer contents at the array position defined by the
+ * given @p compare function. The pointer is not referenced, instead
+ * its contents are copied to the members array using the previously
+ * defined @p member_size.
*
- * The data given to @a compare function are the pointer to member
- * memory itself, do no change it.
+ * @note The data given to the @p compare function is a pointer to the member
+ * memory itself, do no change it.
*
- * This variation will optimize insertion position assuming the array
- * is already sorted by doing binary search.
+ * @note This variation optimizes the insertion position assuming that the array
+ * is already sorted by doing a binary search.
*
* @see eina_inarray_sort()
*
Eina_Compare_Cb compare) EINA_ARG_NONNULL(1, 2, 3);
/**
- * @brief Find data and remove matching member
- * @param array array object
- * @param data data to be found and removed
- * @return the index of the removed member or @c -1 on errors.
+ * @brief Finds data and removes the matching member.
+ *
+ * @param[in] array The array object
+ * @param[in] data The data to be found and removed
+ * @return The index of the removed member, otherwise @c -1 on errors
*
- * Find data in the array and remove it. Data may be an existing
- * member of array (then optimized) or the contents will be matched
- * using memcmp().
+ * @details This finds data in the array and removes it. Data may be an existing
+ * member of the array (then optimized) or the contents are matched
+ * using memcmp().
*
* @see eina_inarray_pop()
* @see eina_inarray_remove_at()
const void *data) EINA_ARG_NONNULL(1, 2);
/**
- * @brief Removes the last member of the array
- * @param array array object
- * @return the data poped out of the array.
+ * @brief Removes the last member of the array.
*
- * Note: The data could be considered valid only until any other operation touch the Inarray.
+ * @param[in] array The array object
+ * @return The data poped out of the array
+ *
+ * @note The data could be considered valid only until any other operation touched the Inarray.
*
* @since 1.2
*/
EAPI void *eina_inarray_pop(Eina_Inarray *array) EINA_ARG_NONNULL(1);
/**
- * @brief Get the member at given position
- * @param array array object
- * @param position member position
- * @return pointer to current member memory.
+ * @brief Gets the member at the given position.
+ *
+ * @param[in] array The array object
+ * @param[in] position The member position
+ * @return A pointer to current the member memory
*
- * Gets the member given its position in the array. It is a pointer to
- * its current memory, then it can be invalidated with functions that
- * changes the array such as eina_inarray_push(),
- * eina_inarray_insert_at() or eina_inarray_remove_at() or variants.
+ * @details This gets the member given that its position in the array is provided. It is a pointer to
+ * its current memory, then it can be invalidated with functions that
+ * change the array such as eina_inarray_push(),
+ * eina_inarray_insert_at(), or eina_inarray_remove_at(), or variants.
*
- * See also eina_inarray_lookup() and eina_inarray_lookup_sorted().
+ * @see eina_inarray_lookup()
+ * @see eina_inarray_lookup_sorted()
*
* @since 1.2
*/
unsigned int position) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
/**
- * @brief Copy the data at given position in the array
- * @param array array object
- * @param position where to insert the member
- * @param data data to be copied at position
- * @return #EINA_TRUE on success, #EINA_FALSE on failure.
+ * @brief Copies the data at the given position in the array.
+ *
+ * @param[in] array The array object
+ * @param[in] position The position to insert the member at
+ * @param[in] data The data to be copied at the position
+ * @return #EINA_TRUE on success, otherwise #EINA_FALSE on failure
*
- * Copies the given pointer contents at the given @a position in the
- * array. The pointer is not referenced, instead its contents is
- * copied to the members array using the previously defined
- * @c member_size.
+ * @details This copies the given pointer contents at the given @p position in the
+ * array. The pointer is not referenced, instead its contents are
+ * copied to the members array using the previously defined
+ * @p member_size.
*
- * All the members from @a position to the end of the array are
- * shifted to the end.
+ * @note All the members from @a position to the end of the array are
+ * shifted to the end.
*
- * If @a position is equal to the end of the array (equals to
- * eina_inarray_count()), then the member is appended.
+ * @note If @a position is equal to the end of the array (equal to
+ * eina_inarray_count()), then the member is appended.
*
- * If @a position is bigger than the array length, it will fail.
+ * @note If @a position is bigger than the array length, it fails.
*
* @since 1.2
*/
const void *data) EINA_ARG_NONNULL(1, 3);
/**
- * @brief Opens a space at given position, returning its pointer.
- * @param array array object
- * @param position where to insert first member (open/allocate space)
- * @param member_count how many times member_size bytes will be allocated.
- * @return pointer to first member memory allocated or @c NULL on errors.
+ * @brief Opens a space at the given position, returning its pointer.
*
- * This is similar to eina_inarray_insert_at(), but useful if the
- * members contents are still unknown or unallocated. It will make
- * room for the required number of items and return the pointer to the
- * first item, similar to malloc(member_count * member_size), with the
- * guarantee all memory is within members array.
+ * @param[in] array The array object
+ * @param[in] position The position to insert first member at (open/allocate space)
+ * @param[in] member_count The number of times @c member_size bytes are allocated
+ * @return A pointer to the first member memory allocated, otherwise @c NULL on errors
*
- * The new member memory is undefined, it's not automatically zeroed.
+ * @note This is similar to eina_inarray_insert_at(), but useful if the
+ * members contents are still unknown or unallocated. It makes
+ * room for the required number of items and returns the pointer to the
+ * first item, similar to malloc(member_count * member_size), with the
+ * guarantee that all the memory is within the members array.
*
- * All the members from @a position to the end of the array are
- * shifted to the end.
+ * @note The new member memory is undefined, it's not automatically zeroed.
*
- * If @a position is equal to the end of the array (equals to
- * eina_inarray_count()), then the member is appended.
+ * @note All the members from @a position to the end of the array are
+ * shifted to the end.
*
- * If @a position is bigger than the array length, it will fail.
+ * @note If @a position is equal to the end of the array (equal to
+ * eina_inarray_count()), then the member is appended.
+ *
+ * @note If @a position is bigger than the array length, it fails.
*
* @since 1.2
*/
unsigned int member_count) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
/**
- * @brief Copy the data over the given position.
- * @param array array object
- * @param position where to replace the member
- * @param data data to be copied at position
- * @return #EINA_TRUE on success, #EINA_FALSE on failure.
+ * @brief Copies the data to the given position.
+ *
+ * @param[in] array The array object
+ * @param[in] position The position to copy the member at
+ * @param[in] data The data to be copied at the position
+ * @return #EINA_TRUE on success, otherwise #EINA_FALSE on failure
*
- * Copies the given pointer contents at the given @a position in the
- * array. The pointer is not referenced, instead its contents is
- * copied to the members array using the previously defined
- * @c member_size.
+ * @details This copies the given pointer contents at the given @p position in the
+ * array. The pointer is not referenced, instead its contents are
+ * copied to the members array using the previously defined
+ * @p member_size.
*
- * If @a position does not exist, it will fail.
+ * @note If @p position does not exist, it fails.
*
* @since 1.2
*/
const void *data) EINA_ARG_NONNULL(1, 3);
/**
- * @brief Remove member at given position
- * @param array array object
- * @param position position to be removed
- * @return #EINA_TRUE on success, #EINA_FALSE on failure.
+ * @brief Removes a member from the given position.
*
- * The member is removed from array and any members after it are moved
- * towards the array head.
+ * @param[in] array The array object
+ * @param[in] position The position from which to remove a member
+ * @return #EINA_TRUE on success, otherwise #EINA_FALSE on failure
*
- * See also eina_inarray_pop() and eina_inarray_remove().
+ * @note The member is removed from an array and members after it are moved
+ * towards the array head.
+ *
+ * @see eina_inarray_pop()
+ * @see eina_inarray_remove()
*
* @since 1.2
*/
unsigned int position) EINA_ARG_NONNULL(1);
/**
- * @brief Reverse members in the array.
- * @param array array object
+ * @brief Reverses members in the array.
*
- * If you do not want to change the array, just walk its elements
- * backwards, then use EINA_INARRAY_REVERSE_FOREACH() macro.
+ * @param[in] array The array object
+ *
+ * @note If you do not want to change the array, just walk through its elements
+ * backwards, then use the EINA_INARRAY_REVERSE_FOREACH() macro.
*
* @see EINA_INARRAY_REVERSE_FOREACH()
*
EAPI void eina_inarray_reverse(Eina_Inarray *array) EINA_ARG_NONNULL(1);
/**
- * @brief Applies quick sort to array
- * @param array array object
- * @param compare compare function
+ * @brief Applies a quick sort to the array.
+ *
+ * @param[in] array The array object
+ * @param[in] compare The compare function
*
- * Applies quick sort to the @a array.
+ * @details This applies a quick sort to the @a array.
*
- * The data given to @a compare function are the pointer to member
- * memory itself, do no change it.
+ * @note The data given to the @a compare function is a pointer to the member
+ * memory itself, do no change it.
*
* @see eina_inarray_insert_sorted()
*
Eina_Compare_Cb compare) EINA_ARG_NONNULL(1, 2);
/**
- * @brief Search member (linear walk)
- * @param array array object
- * @param data member to search using @a compare function.
- * @param compare compare function
- * @return the member index or -1 if not found.
+ * @brief Searches for a member (linear walk).
+ *
+ * @param[in] array The array object
+ * @param[in] data The member to search using the @p compare function
+ * @param[in] compare The compare function
+ * @return The member index, otherwise @c -1 if not found
*
- * Walks array linearly looking for given data as compared by
- * @a compare function.
+ * @details This walks through an array by linearly looking for the given data compared by
+ * the @p compare function.
*
- * The data given to @a compare function are the pointer to member
- * memory itself, do no change it.
+ * @note The data given to the @p compare function is a pointer to the member
+ * memory itself, do no change it.
*
- * See also eina_inarray_lookup_sorted().
+ * @see eina_inarray_lookup_sorted()
*
* @since 1.2
*/
Eina_Compare_Cb compare) EINA_ARG_NONNULL(1, 2, 3);
/**
- * @brief Search member (binary search walk)
- * @param array array object
- * @param data member to search using @a compare function.
- * @param compare compare function
- * @return the member index or @c -1 if not found.
+ * @brief Searches for member (binary search walk).
*
- * Uses binary search for given data as compared by @a compare function.
+ * @param[in] array The array object
+ * @param[in] data The member to search using the @p compare function
+ * @param[in] compare The compare function
+ * @return The member index, otherwise @c -1 if not found
*
- * The data given to @a compare function are the pointer to member
- * memory itself, do no change it.
+ * @note Uses a binary search for the given data as compared by the @p compare function.
+ *
+ * @note The data given to the @p compare function is a pointer to the member
+ * memory itself, do no change it.
*
* @since 1.2
*/
Eina_Compare_Cb compare) EINA_ARG_NONNULL(1, 2, 3);
/**
- * @brief Call function for each array member
- * @param array array object
- * @param function callback function
- * @param user_data user data given to callback @a function
- * @return #EINA_TRUE if it successfully iterate all items of the array.
+ * @brief Calls @p function for each array member.
+ *
+ * @param[in] array The array object
+ * @param[in] function The callback function
+ * @param[in] user_data The user data given to a callback @a function
+ * @return #EINA_TRUE if it successfully iterates all the items of the array
*
- * Call @a function for every given data in @a array.
+ * @details This calls @p function for every given data in @p array.
*
- * Safe way to iterate over an array. @p function 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.
+ * @note This is a safe way to iterate over an array. @p function should return #EINA_TRUE
+ * as long as you want the function to continue iterating, by
+ * returning #EINA_FALSE it stops and returns #EINA_FALSE as the result.
*
- * The data given to @a function are the pointer to member memory
- * itself.
+ * @note The data given to @p function is a pointer to the member memory itself.
*
* @see EINA_INARRAY_FOREACH()
*
const void *user_data) EINA_ARG_NONNULL(1, 2);
/**
- * @brief Remove all members that matched.
- * @param array array object
- * @param match match function
- * @param user_data user data given to callback @a match.
- * @return number of removed entries or -1 on error.
+ * @brief Removes all the members that match.
+ *
+ * @param[in] array The array object
+ * @param[in] match The match function
+ * @param[in] user_data The user data given to callback @p match
+ * @return The number of removed entries, otherwise @c -1 on error
*
- * Remove all entries in the @a array where @a match function
- * returns #EINA_TRUE.
+ * @details This removes all the entries in @p array, where the @p match function
+ * returns #EINA_TRUE.
*
* @since 1.2
*/
const void *user_data) EINA_ARG_NONNULL(1, 2);
/**
- * @brief Resize array to new size
- * @param array array object
- * @param new_size
- * @return #EINA_TRUE if it successfully resized the array
+ * @brief Resizes array to new size
+ *
+ * @param[in] array The array object
+ * @param[in] new_size New size for resize
+ * @return #EINA_TRUE if it resized the array successfully.
*
* @since 1.10
*/
EAPI Eina_Bool eina_inarray_resize(Eina_Inarray *array, unsigned int new_size);
/**
- * @brief number of members in array.
- * @param array array object
- * @return number of members in array.
+ * @brief Counts the number of members in an array.
+ *
+ * @param[in] array The array object
+ * @return The number of members in the array
*
* @since 1.2
*/
EAPI unsigned int eina_inarray_count(const Eina_Inarray *array) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
/**
- * @brief Returned a new iterator associated to an array.
- * @param array array object
- * @return A new iterator.
+ * @brief Returns a new iterator associated to an array.
+ *
+ * @param[in] array The array object
+ * @return A new iterator
*
- * This function returns a newly allocated iterator associated to
- * @p array.
+ * @details This function returns a newly allocated iterator associated to
+ * @p array.
*
- * If the memory can not be allocated, @c NULL is returned.
- * Otherwise, a valid iterator is returned.
+ * @note If the memory cannot be allocated, @c NULL is returned.
+ * Otherwise, a valid iterator is returned.
*
- * @warning if the array structure changes then the iterator becomes
- * invalid! That is, if you add or remove members this
- * iterator behavior is undefined and your program may crash!
+ * @warning If the array structure changes then the iterator becomes
+ * invalid. That is, if you add or remove members this
+ * iterator's behavior is undefined and your program may crash.
*
* @since 1.2
*/
EAPI Eina_Iterator *eina_inarray_iterator_new(const Eina_Inarray *array) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
/**
- * @brief Returned a new reversed iterator associated to an array.
- * @param array array object
- * @return A new iterator.
+ * @brief Returns a new reversed iterator associated to an array.
*
- * This function returns a newly allocated iterator associated to
- * @p array.
+ * @param[in] array The array object
+ * @return A new iterator
*
- * Unlike eina_inarray_iterator_new(), this will walk the array backwards.
+ * @details This function returns a newly allocated iterator associated to
+ * @p array.
*
- * If the memory can not be allocated, @c NULL is returned
- * Otherwise, a valid iterator is returned.
+ * @note Unlike eina_inarray_iterator_new(), this walks through the array backwards.
*
- * @warning if the array 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!
+ * @note If the memory cannot be allocated, @c NULL is returned.
+ * Otherwise, a valid iterator is returned.
+ *
+ * @warning If the array structure changes then the iterator becomes
+ * invalid. That is, if you add or remove nodes this iterator's
+ * behavior is undefined and your program may crash.
*
* @since 1.2
*/
EAPI Eina_Iterator *eina_inarray_iterator_reversed_new(const Eina_Inarray *array) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
/**
- * @brief Returned a new accessor associated to an array.
- * @param array array object
- * @return A new accessor.
+ * @brief Returns a new accessor associated to an array.
+ *
+ * @param[in] array The array object
+ * @return A new accessor
*
- * This function returns a newly allocated accessor associated to
- * @p array.
+ * @details This function returns a newly allocated accessor associated to
+ * @p array.
*
- * If the memory can not be allocated, @c NULL is returned.
- * Otherwise, a valid accessor is returned.
+ * @note If the memory cannot be allocated, @c NULL is returned
+ * Otherwise, a valid accessor is returned.
*
* @since 1.2
*/
/**
* @def EINA_INARRAY_FOREACH
- * @brief walks array linearly from head to tail
- * @param array array object
- * @param itr the iterator pointer
+ * @brief Walks through an array linearly from head to tail.
+ *
+ * @param[in] array The array object
+ * @param[in] itr An iterator pointer
*
- * @a itr must be a pointer with sizeof(itr*) == array->member_size.
+ * @note @p itr must be a pointer with sizeof(itr*) == array->member_size.
*
- * @warning This is fast as it does direct pointer access, but it will
- * not check for @c NULL pointers or invalid array object!
- * See eina_inarray_foreach() to do that.
+ * @note This is fast as it does direct pointer access, but it does
+ * not check for @c NULL pointers or invalid array objects.
+ * Use eina_inarray_foreach() to do that.
*
- * @warning Do not modify array as you walk it! If that is desired,
- * then use eina_inarray_foreach_remove()
+ * @note Do not modify an array as you walk through it. If that is desired,
+ * then use eina_inarray_foreach_remove().
*
* @since 1.2
*/
/**
* @def EINA_INARRAY_REVERSE_FOREACH
- * @brief walks array linearly from tail to head
- * @param array array object
- * @param itr the iterator pointer
+ * @brief Walks through an array linearly from tail to head.
*
- * @a itr must be a pointer with sizeof(itr*) == array->member_size.
+ * @param[in] array The array object
+ * @param[in] itr An iterator pointer
*
- * @warning This is fast as it does direct pointer access, but it will
- * not check for @c NULL pointers or invalid array object!
+ * @note @p itr must be a pointer with sizeof(itr*) == array->member_size.
*
- * @warning Do not modify array as you walk it! If that is desired,
- * then use eina_inarray_foreach_remove()
+ * @note This is fast as it does direct pointer access, but it does
+ * not check for @c NULL pointers or invalid array objects.
+ *
+ * @note Do not modify an array as you walk through it. If that is desired,
+ * then use eina_inarray_foreach_remove().
*
* @since 1.2
*/
* @}
*/
-/**
- * @}
- */
-
-/**
- * @}
- */
-
#endif /*EINA_INARRAY_H_*/
projects / platform / upstream / efl.git / commitdiff