parent
7c3aa4194d
commit
4aa79a0fb9
|
@ -277,4 +277,8 @@ EAPI Eina_Bool eina_accessor_unlock(Eina_Accessor *accessor) EINA_ARG_NONNULL(1)
|
|||
* @}
|
||||
*/
|
||||
|
||||
/**
|
||||
* @}
|
||||
*/
|
||||
|
||||
#endif
|
||||
|
|
|
@ -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 <stdlib.h>
|
||||
* #include <stdio.h>
|
||||
* #include <string.h>
|
||||
*
|
||||
* #include <eina_array.h>
|
||||
*
|
||||
* 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,
|
|||
* @}
|
||||
*/
|
||||
|
||||
/**
|
||||
* @}
|
||||
*/
|
||||
|
||||
|
||||
/**
|
||||
* @}
|
||||
*/
|
||||
|
|
|
@ -174,7 +174,3 @@ eina_accessor_unlock(Eina_Accessor *accessor)
|
|||
return accessor->unlock(accessor);
|
||||
return EINA_TRUE;
|
||||
}
|
||||
|
||||
/**
|
||||
* @}
|
||||
*/
|
||||
|
|
|
@ -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 <stdlib.h>
|
||||
* #include <stdio.h>
|
||||
* #include <string.h>
|
||||
*
|
||||
* #include <eina_array.h>
|
||||
*
|
||||
* 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;
|
||||
}
|
||||
|
||||
/**
|
||||
* @}
|
||||
*/
|
||||
|
|
Loading…
Reference in New Issue