aboutsummaryrefslogtreecommitdiffstats
path: root/src/lib/eina
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/eina')
-rw-r--r--src/lib/eina/eina_array.h491
-rw-r--r--src/lib/eina/eina_benchmark.h436
-rw-r--r--src/lib/eina/eina_binbuf.h276
-rw-r--r--src/lib/eina/eina_convert.h253
-rw-r--r--src/lib/eina/eina_cpu.h100
-rw-r--r--src/lib/eina/eina_fp.h451
-rw-r--r--src/lib/eina/eina_hamster.h32
-rw-r--r--src/lib/eina/eina_hash.h1390
-rw-r--r--src/lib/eina/eina_inarray.h626
-rw-r--r--src/lib/eina/eina_inlist.h897
-rw-r--r--src/lib/eina/eina_iterator.h282
-rw-r--r--src/lib/eina/eina_lalloc.h67
-rw-r--r--src/lib/eina/eina_list.h1655
-rw-r--r--src/lib/eina/eina_log.h869
-rw-r--r--src/lib/eina/eina_main.h144
-rw-r--r--src/lib/eina/eina_matrixsparse.h406
-rw-r--r--src/lib/eina/eina_mmap.h69
-rw-r--r--src/lib/eina/eina_model.h281
-rw-r--r--src/lib/eina/eina_module.h412
-rw-r--r--src/lib/eina/eina_quadtree.h4
-rw-r--r--src/lib/eina/eina_rbtree.h203
-rw-r--r--src/lib/eina/eina_rectangle.h535
-rw-r--r--src/lib/eina/eina_refcount.h44
-rw-r--r--src/lib/eina/eina_safety_checks.h35
-rw-r--r--src/lib/eina/eina_sched.h10
-rw-r--r--src/lib/eina/eina_simple_xml_parser.h472
-rw-r--r--src/lib/eina/eina_str.h467
-rw-r--r--src/lib/eina/eina_strbuf.h746
-rw-r--r--src/lib/eina/eina_stringshare.h356
-rw-r--r--src/lib/eina/eina_tiler.h349
-rw-r--r--src/lib/eina/eina_tmpstr.h197
-rw-r--r--src/lib/eina/eina_types.h155
-rw-r--r--src/lib/eina/eina_unicode.h214
-rw-r--r--src/lib/eina/eina_ustrbuf.h504
-rw-r--r--src/lib/eina/eina_ustringshare.h201
-rw-r--r--src/lib/eina/eina_value.h2454
-rw-r--r--src/lib/eina/eina_xattr.h281
37 files changed, 7316 insertions, 9048 deletions
diff --git a/src/lib/eina/eina_array.h b/src/lib/eina/eina_array.h
index 07234cd70b..da046d786f 100644
--- a/src/lib/eina/eina_array.h
+++ b/src/lib/eina/eina_array.h
@@ -1,7 +1,7 @@
/* EINA - EFL data type library
* Copyright (C) 2008 Cedric Bail
*
- * This library is free software; you can redistribute it and/or
+ * This library is a free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
@@ -29,139 +29,31 @@
#include "eina_accessor.h"
#include "eina_magic.h"
-
-/**
- * @page eina_array_01_example_page Basic array usage
- * @dontinclude eina_array_01.c
- *
- * For this example we add stdlib.h, stdio.h and string.h for some
- * convenience functions. The first thing to do to be able to use an
- * @ref Eina_Array is to include Eina.h:
- * @skip #include
- * @until Eina.h
- *
- * Here we have a callback that prints the element given to it:
- * @until }
- *
- * Now we create our entry point and declare some variables, nothing especial:
- * @until unsigned
- *
- * 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
- * argument given to the eina_array_new() function. This argument sets how fast
- * the array grows.
- * @until array_new
- *
- * If you know before hand how big the array will need to be you should set the
- * step to that. In our case we can set it to the number of strings we have and
- * since we didn't do that in the eina_array_new() we can do it now:
- * @until array_step_set
- *
- * Now let us populate our array with some strings:
- * @until push
- * @note Notice we use strdup, so we will have to free that memory later on.
- *
- * Now lets check the size of the array:
- * @until printf
- *
- * And now we call a function on every member of our array to print it:
- * @until foreach
- *
- * One of the strengths of @ref Eina_Array over @ref Eina_List is that it has
- * very fast random access to elements, so this is very efficient:
- * @until printf
- *
- * And now we free up the memory allocated with the strdup()s:
- * @until free
- *
- * And the array memory itself:
- * @until array_free
- *
- * And finally shutdown eina and exit:
- * @until }
- *
- * The full source code can be found in the examples folder
- * in the @ref eina_array_01_c "eina_array_01.c" file.
- */
-
-/**
- * @page eina_array_01_c Basic array usage example
- *
- * @include eina_array_01.c
- * @example eina_array_01.c
- */
-
-/**
- * @page eina_array_02_example_page Removing array elements
- * @dontinclude eina_array_02.c
- *
- * Just the usual includes:
- * @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
- * complex as you like:
- * @until }
- *
- * This is the same code we used before to populate the list with the slight
- * difference of not using strdup:
- * @until array_push
- *
- * So we have added all our elements to the array, but it turns out that is not
- * the elements we wanted, so let's empty the array and add the correct strings:
- * @until array_push
- *
- * It seems we made a little mistake in one of our strings so we need to replace
- * it, here is how:
- * @until data_set
- *
- * Now that there is a populated array we can remove elements from it easily:
- * @until array_remove
- *
- * And check that the elements were actually removed:
- * @until printf
- *
- * Since this time we didn't use strdup we don't need to free each string:
- * @until }
- *
- * The full source code can be found in the examples folder
- * in the @ref eina_array_02_c "eina_array_02.c" file.
- */
-
/**
- * @page eina_array_02_c Basic array usage example
- *
- * @include eina_array_02.c
- * @example eina_array_02.c
- */
-
-/**
- * @addtogroup Eina_Array_Group Array
+ * @defgroup Eina_Array_Group Array
+ * @ingroup Eina_Containers_Group
*
- * @brief These functions provide array management.
+ * @brief This group discusses the functions to 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
+ * 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 no more eina array functions are used,
+ * other array function. When no more eina array functions are used,
* eina_shutdown() must be called to free all the resources.
*
* 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.
- * 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.
- * An example of that pattern is given in the description of @ref EINA_ARRAY_ITER_NEXT.
+ * 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 Functions do not check if the used array is valid or not. It's up to
+ * 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.
*
@@ -173,157 +65,157 @@
*
* 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
+ * element to a full array it grows and 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 additonal 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.
+ * When the array needs to grow it allocates memory not just for the element
+ * currently being added, since that would mean allocating memory(which is
+ * computationally expensive) often, instead it grows to be able to hold @a step
+ * more elements. Similarly, if you remove elements in such a way that the
+ * array is left holding its capacity, @a step elements shrink.
*
* The following image illustrates how an Eina_Array grows:
*
* @image html eina_array-growth.png
- * @image latex eina_array-growth.eps "" width=\textwidth
- *
- * Eina_Array only stores pointers but it can store data of any type in the form
- * of void pointers.
+ * @image latex eina_array-growth.eps "eina array growth" width=\textwidth
*
- * See here some examples:
- * @li @ref eina_array_01_example_page
- * @li @ref eina_array_02_example_page
- */
-
-/**
- * @addtogroup Eina_Data_Types_Group Data Types
- *
- * @{
- */
-
-/**
- * @addtogroup Eina_Containers_Group Containers
- *
- * @{
- */
-
-/**
- * @defgroup Eina_Array_Group Array
+ * @remarks Eina_Array only stores pointers, but it can store data of any type in the form
+ * of void pointers.
*
* @{
*/
/**
* @typedef Eina_Array
- * Type for a generic vector.
+ * @brief The structure type for a generic vector.
*/
typedef struct _Eina_Array Eina_Array;
/**
* @typedef Eina_Array_Iterator
- * Type for an iterator on arrays, used with #EINA_ARRAY_ITER_NEXT.
+ * @brief The structure type for an iterator on arrays, used with #EINA_ARRAY_ITER_NEXT.
*/
typedef void **Eina_Array_Iterator;
/**
* @struct _Eina_Array
- * Type for an array of data.
+ * @brief The structure type for an array of data.
*/
struct _Eina_Array
{
#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 EINA_ARRAY_VERSION used when compiling 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 vector of a pointer to payload */
+ unsigned int total; /**< Total number of slots in the vector */
+ unsigned int count; /**< Number of active slots in the vector */
+ unsigned int step; /**< To what extent must we grow the vector when it is full */
EINA_MAGIC
};
/**
- * @brief Create a new array.
+ * @brief Creates 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.
+ * @details This function creates a new array. When adding an element, the array
+ * allocates @a step elements. When that buffer is full, adding
+ * another element increases the buffer by @a step elements again.
*
- * 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 by @p step elements again.
+ * @since_tizen 2.3
+ *
+ * @remarks This function returns 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.
+ *
+ * @param[in] step The count of pointers to add when increasing the array size
+ * @return @c NULL on failure, otherwise a non @c NULL value
*
- * This function return a valid array on success, or @c NULL if memory
- * allocation fails.
*/
EAPI Eina_Array *eina_array_new(unsigned int step) EINA_WARN_UNUSED_RESULT EINA_MALLOC EINA_WARN_UNUSED_RESULT;
/**
- * @brief Free an array.
+ * @brief Frees an array.
+ *
+ * @details This function frees @a 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 @a array. To free them,
+ * use #EINA_ARRAY_ITER_NEXT. For performance reasons, there is no check
+ * on @a array.
+ *
+ * @since_tizen 2.3
*
- * @param array The array to free.
+ * @param[in] 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, walk the array with
- * #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.
+ * @brief Sets 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.
+ * @details This function sets the step of @a array to @a step. For performance
+ * reasons, there is no check on @a array. If it is @c NULL or
+ * invalid, the program may crash.
*
- * 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.
+ * @since_tizen 2.3
+ *
+ * @remarks This function can @b only be called on uninitialized arrays.
+ *
+ * @param[in] array The array
+ * @param[in] sizeof_eina_array The value returned by sizeof(Eina_Array)
+ * @param[in] step The count of pointers to add when increasing the array size
*
- * @warning This function can @b only be called on uninitialized arrays.
*/
EAPI void eina_array_step_set(Eina_Array *array,
unsigned int sizeof_eina_array,
unsigned int step) EINA_ARG_NONNULL(1);
/**
- * @brief Clean an array.
+ * @brief Cleans an array.
+ *
+ * @details This function sets the count member of @a 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 on
+ * @a array. If it is @c NULL or invalid, the program may crash.
*
- * @param array The array to clean.
+ * @since_tizen 2.3
+ *
+ * @param[in] 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.
*/
static inline void eina_array_clean(Eina_Array *array) EINA_ARG_NONNULL(1);
/**
- * @brief Flush an array.
+ * @brief Flushes an array.
+ *
+ * @details This function sets the count and total members of @a array to 0,
+ * frees and sets its data member to @c NULL. For performance reasons,
+ * there is no check on @a array. If it is @c NULL or invalid, the
+ * program may crash.
*
- * @param array The array to flush.
+ * @since_tizen 2.3
+ *
+ * @param[in] 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.
+ * @brief Rebuilds 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 otherwise.
+ * @details This function rebuilds @a array by specifying the elements to keep with the
+ * function @a keep. No empty/invalid fields are left in the array. @a gdata is
+ * an additional data to pass to @a keep. For performance reasons, there is no
+ * check on @a array. If it is @c NULL or invalid, the program may crash.
*
- * This function rebuilds @p array be specifying the elements to keep with the
- * function @p keep. No empty/invalid fields are left in the array. @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.
+ * @since_tizen 2.3
+ *
+ * @remarks If it isn't able to remove items due to an allocation failure, it
+ * returns @c EINA_FALSE and the error is set to #EINA_ERROR_OUT_OF_MEMORY.
+ *
+ * @param[in] array The array
+ * @param[in] keep The functions that selects the data to keep
+ * @param[in] gdata The data to pass to the function @a keep
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE
*
- * If it wasn't able to remove items due to an allocation failure, it will
- * return #EINA_FALSE.
*/
EAPI Eina_Bool eina_array_remove(Eina_Array * array,
Eina_Bool (*keep)(void *data, void *gdata),
@@ -332,15 +224,17 @@ EAPI Eina_Bool eina_array_remove(Eina_Array * array,
/**
* @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.
+ * @details 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.
*
- * 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.
+ * @since_tizen 2.3
+ *
+ * @param[in] array The array.
+ * @param[in] data The data to add.
+ * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*/
static inline Eina_Bool eina_array_push(Eina_Array *array,
const void *data) EINA_ARG_NONNULL(1, 2);
@@ -348,55 +242,66 @@ static inline Eina_Bool eina_array_push(Eina_Array *array,
/**
* @brief Remove the last data of an array.
*
- * @param array The array.
- * @return The retrieved data.
+ * @details 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.
+ *
+ * @since_tizen 2.3
*
- * 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.
+ * @param[in] array The array.
+ * @return The retrieved data.
*/
static inline void *eina_array_pop(Eina_Array *array) EINA_ARG_NONNULL(1);
/**
- * @brief Return the data at a given position in an array.
+ * @brief Sets the data at the given position in an array.
*
- * @param array The array.
- * @param idx The potition of the data to retrieve.
- * @return The retrieved data.
+ * @details This function sets the data at the position @a idx in @a
+ * array to @a 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 on @a array or @a idx. If it is
+ * @c NULL or invalid, the program may crash.
+ *
+ * @since_tizen 2.3
*
- * 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.
+ * @param[in] array The array
+ * @param[in] idx The position of the data to set
*/
static inline void *eina_array_data_get(const Eina_Array *array,
unsigned int idx) EINA_ARG_NONNULL(1);
/**
- * @brief Set the data at a given position in an array.
- *
- * @param array The array.
- * @param idx The position of the data to set.
- * @param 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.
-*/
+ * @brief Sets the data at the given position in an array.
+ *
+ * @details This function sets the data at the position @a idx in @a
+ * array to @a 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 on @a array or @a idx. If it is
+ * @c NULL or invalid, the program may crash.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] array The array
+ * @param[in] idx The position of the data to set
+ * @param[in] data The data to set
+ *
+ */
static inline void eina_array_data_set(const Eina_Array *array,
unsigned int idx,
const void *data) EINA_ARG_NONNULL(1);
+
/**
* @brief Return the number of elements in an array.
*
- * @param array The array.
- * @return The number of elements.
+ * @details 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
+ * @c NULL or invalid, the program may crash.
+ *
+ * @since_tizen 2.3
*
- * 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
- * @c NULL or invalid, the program may crash.
+ * @param[in] array The array.
+ * @return The number of elements.
*
* @deprecated use eina_array_count()
*/
@@ -405,74 +310,82 @@ static inline unsigned int eina_array_count_get(const Eina_Array *array) EINA_AR
/**
* @brief Return the number of elements in an array.
*
- * @param array The array.
- * @return The number of elements.
+ * @details 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
+ * @c NULL or invalid, the program may crash.
*
- * 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
- * @c NULL or invalid, the program may crash.
+ * @since_tizen 2.3
+ *
+ * @param[in] array The array.
+ * @return The number of elements.
*/
static inline unsigned int eina_array_count(const Eina_Array *array) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
/**
- * @brief Get a new iterator associated to an array.
+ * @brief Returns a new iterator associated to an array.
+ *
+ * @details This function returns a newly allocated iterator associated to
+ * @a array. If @a array is @c NULL or the count member of @a array is
+ * less than or equal to 0, this function returns @c NULL. If the memory cannot
+ * be allocated, @c NULL is returned and #EINA_ERROR_OUT_OF_MEMORY is
+ * set. Otherwise, a valid iterator is returned.
*
- * @param array The array.
- * @return A new iterator.
+ * @since_tizen 2.3
+ *
+ * @param[in] 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 @c NULL. If the memory can
- * not be allocated, @c NULL is returned. 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 Get a new accessor associated to an array.
+ * @brief Returns a new accessor associated to an array.
+ *
+ * @details This function returns a newly allocated accessor associated to
+ * @a array. If @a array is @c NULL or the count member of @a array is
+ * less than or equal to @c 0, this function returns @c NULL. If the memory cannot
+ * be allocated, @c NULL is returned and #EINA_ERROR_OUT_OF_MEMORY is
+ * set. Otherwise, a valid accessor is returned.
+ *
+ * @since_tizen 2.3
*
- * @param array The array.
- * @return A new accessor.
+ * @param[in] 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 @c NULL. If the memory can
- * not be allocated, @c NULL is returned. 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;
/**
- * @brief Provide a safe way to iterate over an array
+ * @brief Provides a safe way to iterate over an array.
*
- * @param array The array to iterate over.
- * @param cb The callback to call for each item.
- * @param fdata The user data to pass to the callback.
- * @return #EINA_TRUE if it successfully iterate all items of the array.
+ * @details This function provides a safe way to iterate over an array. @a cb should
+ * return @c EINA_TRUE as long as you want the function to continue iterating,
+ * by returning @c EINA_FALSE it stops and returns @c EINA_FALSE as a result.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] array The array to iterate over
+ * @param[in] cb The callback to call for each item
+ * @param[in] fdata The user data to pass to the callback
+ * @return @c EINA_TRUE if it successfully iterates all the items of the array, otherwise @c EINA_FALSE
*
- * 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
- * return #EINA_FALSE.
*/
static inline Eina_Bool eina_array_foreach(Eina_Array *array,
Eina_Each_Cb cb,
void *fdata);
/**
* @def EINA_ARRAY_ITER_NEXT
- * @brief Macro to iterate over an array easily.
+ * @brief Definition of the macro to iterate over an array easily.
*
- * @param array The array to iterate over.
- * @param index The integer number that is increased while iterating.
- * @param item The data
- * @param iterator The iterator
+ * @details This macro allows the iteration over @a array in an easy way. It
+ * iterates from the first element to the last one. @a index is an
+ * integer that increases from 0 to the number of elements. @a item is
+ * the data of each element of @a array, so it is a pointer to a type
+ * chosen by the user. @a iterator is of type #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.
+ * @since_tizen 2.3
*
- * This macro can be used for freeing the data of an array, like in
- * the following example:
+ * @remarks This macro can be used for freeing the data of an array, like in
+ * the following example:
*
* @code
* Eina_Array *array;
@@ -487,6 +400,12 @@ static inline Eina_Bool eina_array_foreach(Eina_Array *array,
* EINA_ARRAY_ITER_NEXT(array, i, item, iterator)
* free(item);
* @endcode
+ *
+ * @param array The array to iterate over
+ * @param index The integer number that is increased while iterating
+ * @param item The data
+ * @param iterator The iterator
+ *
*/
#define EINA_ARRAY_ITER_NEXT(array, index, item, iterator) \
for (index = 0, iterator = (array)->data; \
@@ -499,12 +418,4 @@ static inline Eina_Bool eina_array_foreach(Eina_Array *array,
* @}
*/
-/**
- * @}
- */
-
-/**
- * @}
- */
-
#endif
diff --git a/src/lib/eina/eina_benchmark.h b/src/lib/eina/eina_benchmark.h
index 8c0c5988da..1633aa569c 100644
--- a/src/lib/eina/eina_benchmark.h
+++ b/src/lib/eina/eina_benchmark.h
@@ -1,14 +1,14 @@
/* EINA - EFL data type library
* Copyright (C) 2008 Cedric Bail
*
- * This library is free software; you can redistribute it and/or
+ * This library is a free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
@@ -21,286 +21,15 @@
#include "eina_array.h"
-
-
-/**
- * @page tutorial_benchmark_page Benchmark Tutorial
- *
- * The Benchmark module allows you to write easily benchmarks
- * framework in a project for timing critical part and detect slow
- * parts of code. In addition it automatically creates data files of
- * these benchmark, as well as a gnuplot file which can display the
- * comparison curves of the benchmarks.
- *
- * @section tutorial_benchmark_basic_usage Basic Usage
- *
- * To create a basic benchmark, you have to follow these steps:
- *
- * @li Create a new benchmark
- * @li Write the functions that wraps the functions you want to
- * benchmark.
- * @li Register these wrappers functions.
- * @li Run the benchmark.
- * @li Free the memory.
- *
- * Here is a basic example of benchmark which creates two functions
- * that will be run. These functions just print a message.
- *
- * @code
- * #include <stdlib.h>
- * #include <stdio.h>
- *
- * #include <Eina.h>
- *
- * static
- * void work1(int request)
- * {
- * printf ("work1 in progress... Request: %d\n", request);
- * }
- *
- * static
- * void work2(int request)
- * {
- * printf ("work2 in progress... Request: %d\n", request);
- * }
- *
- * int main()
- * {
- * Eina_Benchmark *test;
- * Eina_Array *ea;
- *
- * if (!eina_init())
- * return EXIT_FAILURE;
- *
- * test = eina_benchmark_new("test", "run");
- * if (!test)
- * goto shutdown_eina;
- *
- * eina_benchmark_register(test, "work-1", EINA_BENCHMARK(work1), 200, 300, 10);
- * eina_benchmark_register(test, "work-2", EINA_BENCHMARK(work2), 100, 150, 5);
- *
- * ea = eina_benchmark_run(test);
- *
- * eina_benchmark_free(test);
- * eina_shutdown();
- *
- * return EXIT_SUCCESS;
- *
- * shutdown_eina:
- * eina_shutdown();
- *
- * return EXIT_FAILURE;
- * }
- * @endcode
- *
- * As "test", "run" are passed to eina_benchmark_new() and as the tests
- * "work-1" and "work-2" are registered, the data files
- * bench_test_run.work-1.data and bench_test_run.work-2.data will be
- * created after the eina_benchmark_run() call. They contain four
- * columns. The file bench_test_run.work-1.data contains for example:
- *
- * @code
- * # specimen experiment time starting time ending time
- * 200 23632 2852446 2876078
- * 210 6924 2883046 2889970
- * 220 6467 2895962 2902429
- * 230 6508 2908271 2914779
- * 240 6278 2920610 2926888
- * 250 6342 2932830 2939172
- * 260 6252 2944954 2951206
- * 270 6463 2956978 2963441
- * 280 6347 2969548 2975895
- * 290 6457 2981702 2988159
- * @endcode
- *
- * The first column (specimen) is the integer passed to the work1()
- * function when the test is run. The second column (experiment time)
- * is the time, in nanosecond, that work1() takes. The third and
- * fourth columnd are self-explicit.
- *
- * You can see that the integer passed work1() starts from 200 and
- * finishes at 290, with a step of 10. These values are computed withe
- * last 3 values passed to eina_benchmark_register(). See the document
- * of that function for the detailed behavior.
- *
- * The gnuplot file will be named bench_test_run.gnuplot. Just run:
- *
- * @code
- * gnuplot bench_test_run.gnuplot
- * @endcode
- *
- * to create the graphic of the comparison curves. The image file is
- * named output_test_run.png.
- *
- * @section tutorial_benchmark_advanced_usage More Advanced Usage
- *
- * In this section, several test will be created and run. The idea is
- * exactly the same than in the previous section, but with some basic
- * automatic way to run all the benchmarks. The following code
- * benchmarks some Eina converts functions, and some Eina containers
- * types:
- *
- * @code
- * #include <stdlib.h>
- * #include <stdio.h>
- * #include <time.h>
- *
- * #include <Eina.h>
- *
- * static void bench_convert(Eina_Benchmark *bench);
- * static void bench_container(Eina_Benchmark *bench);
- *
- * typedef struct _Benchmark_Case Benchmark_Case;
- *
- * struct _Benchmark_Case
- * {
- * const char *bench_case;
- * void (*build)(Eina_Benchmark *bench);
- * };
- *
- * static const Benchmark_Case benchmarks[] = {
- * { "Bench 1", bench_convert },
- * { "Bench 2", bench_container },
- * { NULL, NULL }
- * };
- *
- * static
- * void convert1(int request)
- * {
- * char tmp[128];
- * int i;
- *
- * srand(time(NULL));
- *
- * for (i = 0; i < request; ++i)
- * eina_convert_itoa(rand(), tmp);
- * }
- *
- * static
- * void convert2(int request)
- * {
- * char tmp[128];
- * int i;
- *
- * srand(time(NULL));
- *
- * for (i = 0; i < request; ++i)
- * eina_convert_xtoa(rand(), tmp);
- * }
- *
- * static void
- * bench_convert(Eina_Benchmark *bench)
- * {
- * eina_benchmark_register(bench, "convert-1", EINA_BENCHMARK(convert1), 200, 400, 10);
- * eina_benchmark_register(bench, "convert-2", EINA_BENCHMARK(convert2), 200, 400, 10);
- * }
- *
- * static
- * void array(int request)
- * {
- * Eina_Array *array;
- * Eina_Array_Iterator it;
- * int *data;
- * int i;
- *
- * srand(time(NULL));
- *
- * array = eina_array_new(64);
- *
- * for (i = 0; i < request; ++i)
- * {
- * data = (int *)malloc(sizeof(int));
- * if (!data) continue;
- * *data = rand();
- * eina_array_push(array, data);
- * }
- *
- * EINA_ARRAY_ITER_NEXT(array, i, data, it)
- * free(data);
- *
- * eina_array_free(array);
- * }
- *
- * static
- * void list(int request)
- * {
- * Eina_List *l = NULL;
- * int *data;
- * int i;
- *
- * srand(time(NULL));
- *
- * for (i = 0; i < request; ++i)
- * {
- * data = (int *)malloc(sizeof(int));
- * if (!data) continue;
- * *data = rand();
- * l = eina_list_prepend(l, data);
- * }
- *
- * while (l)
- * {
- * free(eina_list_data_get(l));
- * l = eina_list_remove_list(l, l);
- * }
- * }
- *
- * static void
- * bench_container(Eina_Benchmark *bench)
- * {
- * eina_benchmark_register(bench, "array", EINA_BENCHMARK(array), 200, 300, 10);
- * eina_benchmark_register(bench, "list", EINA_BENCHMARK(list), 200, 300, 10);
- * }
- *
- * int main()
- * {
- * Eina_Benchmark *test;
- * Eina_Array *ea;
- * unsigned int i;
- *
- * if (!eina_init())
- * return EXIT_FAILURE;
- *
- * for (i = 0; benchmarks[i].bench_case != NULL; ++i)
- * {
- * test = eina_benchmark_new(benchmarks[i].bench_case, "Benchmark example");
- * if (!test)
- * continue;
- *
- * benchmarks[i].build(test);
- *
- * ea = eina_benchmark_run(test);
- *
- * eina_benchmark_free(test);
- * }
- *
- * eina_shutdown();
- *
- * return EXIT_SUCCESS;
- * }
- * @endcode
- *
- * gnuplot can be used to see how are performed the convert functions
- * together, as well as how are performed the containers. So it is now
- * easy to see that the hexadecimal convert function is faster than
- * the decimal one, and that arrays are faster than lists.
- *
- * You can improve all that by executing automatically gnuplot in your
- * program, or integrate the Eina benchmark framework in an autotooled
- * project. See that
- * <a href="http://trac.enlightenment.org/e/wiki/AutotoolsIntegration#Benchmark">page</a>
- * for more informations.
- *
- */
-
-
/**
- * @addtogroup Eina_Benchmark_Group Benchmark
+ * @internal
+ * @defgroup Eina_Benchmark_Group Benchmark
+ * @ingroup Eina_Tools_Group
*
- * These functions allow you to add benchmark framework in a project
- * for timing critical part and detect slow parts of code. It is used
- * in Eina to compare the time used by eina, glib, evas and ecore data
- * types.
+ * @brief This group discusses the functions that allow you to add the benchmark framework in a project
+ * for timing critical part and detecting slow parts of a code. It is used
+ * in Eina to compare the time used by eina, glib, evas, and ecore data
+ * types.
*
* To use the benchmark module, Eina must be initialized with
* eina_init() and later shut down with eina_shutdown(). A benchmark
@@ -308,102 +37,102 @@
* eina_benchmark_free().
*
* eina_benchmark_register() adds a test to a benchmark. That test can
- * be run a certain amount of times. Adding more than one test to be
+ * be run a certain number of times. Adding more than one test to be
* executed allows the comparison between several parts of a program,
* or different implementations.
*
* eina_benchmark_run() runs all the tests registered with
- * eina_benchmark_register(). The amount of time of each test is
+ * eina_benchmark_register(). The amount of time for each test is
* written in a gnuplot file.
*
- * For more information, you can look at the @ref tutorial_benchmark_page.
- */
-
-/**
- * @addtogroup Eina_Tools_Group Tools
- *
- * @{
- */
-
-/**
- * @defgroup Eina_Benchmark_Group Benchmark
- *
* @{
*/
/**
* @typedef Eina_Benchmark
- * Type for a benchmark.
+ * @brief The structure type for a benchmark.
*/
typedef struct _Eina_Benchmark Eina_Benchmark;
/**
* @typedef Eina_Benchmark_Specimens
- * Type for a test function to be called when running a benchmark.
+ * @brief The structure type for a test function to be called when running a benchmark.
*/
typedef void (*Eina_Benchmark_Specimens)(int request);
/**
* @def EINA_BENCHMARK
- * @brief cast to an #Eina_Benchmark_Specimens.
+ * @brief Definition to cast to an #Eina_Benchmark_Specimens.
+ *
+ * @details This macro casts @a function to Eina_Benchmark_Specimens.
*
- * @param function The function to cast.
+ * @param function The function to cast
*
- * This macro casts @p function to Eina_Benchmark_Specimens.
*/
#define EINA_BENCHMARK(function) ((Eina_Benchmark_Specimens)function)
-
/**
- * @brief Create a new array.
+ * @brief Creates a new array.
+ *
+ * @details This function creates a new benchmark. @a name and @a run are used
+ * to name the gnuplot file that eina_benchmark_run() creates.
*
- * @param name The name of the benchmark.
- * @param run The name of the run.
- * @return @c NULL on failure, non @c NULL otherwise.
+ * @since_tizen 2.3
*
- * This function creates a new benchmark. @p name and @p run are used
- * to name the gnuplot file that eina_benchmark_run() will create.
+ * @remarks This function returns a valid benchmark on success, or @c NULL if
+ * memory allocation fails. In that case, the error is set
+ * to #EINA_ERROR_OUT_OF_MEMORY.
+ *
+ * @remarks When the new module is not needed anymore, use
+ * eina_benchmark_free() to free the allocated memory.
+ *
+ * @param[in] name The name of the benchmark
+ * @param[in] run The name of the run
+ * @return @c NULL on failure, otherwise a non @c NULL value
*
- * This function return a valid benchmark on success, or @c NULL if
- * memory allocation fails.
- *
- * When the new module is not needed anymore, use
- * eina_benchmark_free() to free the allocated memory.
*/
EAPI Eina_Benchmark *eina_benchmark_new(const char *name,
const char *run);
/**
- * @brief Free a benchmark object.
+ * @brief Frees a benchmark object.
+ *
+ * @details This function removes all the benchmark tests that have been
+ * registered and frees @a bench. If @a bench is @c NULL, this
+ * function returns immediately.
+ *
+ * @since_tizen 2.3
*
- * @param bench The benchmark to free.
+ * @param[in] bench The benchmark to free
*
- * This function removes all the benchmark tests that have been
- * registered and frees @p bench. If @p bench is @c NULL, this
- * function returns immediately.
*/
EAPI void eina_benchmark_free(Eina_Benchmark *bench);
/**
- * @brief Add a test to a benchmark.
- *
- * @param bench The benchmark.
- * @param name The name of the test.
- * @param bench_cb The test function to be called.
- * @param count_start The start data to be passed to @p bench_cb.
- * @param count_end The end data to be passed to @p bench_cb.
- * @param count_step The step data to be passed to @p bench_cb.
- * @return #EINA_FALSE on failure, #EINA_TRUE otherwise.
- *
- * This function adds the test named @p name to @p benchmark. @p
- * bench_cb is the function called when the test is executed. That
- * test can be executed a certain amount of time. @p count_start, @p count_end and
- * @p count_step define a loop with a step increment. The integer that is
- * increasing by @p count_step from @p count_start to @p count_end is passed to @p
- * bench_cb when eina_benchmark_run() is called.
- *
- * If @p bench is @c NULL, this function returns immediately.
- * This function returns #EINA_FALSE on failure, #EINA_TRUE otherwise.
+ * @brief Adds a test to a benchmark.
+ *
+ * @details This function adds the test named @a name to @a benchmark. @a
+ * bench_cb is the function called when the test is executed. That
+ * test can be executed for a certain amount of time. @a count_start, @a count_end, and
+ * @a count_step define a loop with a step increment. The integer that is
+ * increasing by @a count_step from @a count_start to @a count_end is passed to @a
+ * bench_cb when eina_benchmark_run() is called.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks If @a bench is @c NULL, this function returns immediately. If the
+ * allocation of the memory of the test to add fails, the error is set
+ * to #EINA_ERROR_OUT_OF_MEMORY. This function returns @c EINA_FALSE
+ * on failure, otherwise it returns @c EINA_TRUE.
+ *
+ * @param[in] bench The benchmark
+ * @param[in] name The name of the test
+ * @param[in] bench_cb The test function to be called
+ * @param[in] count_start The start data to be passed to @a bench_cb
+ * @param[in] count_end The end data to be passed to @a bench_cb
+ * @param[in] count_step The step data to be passed to @a bench_cb
+ * @return @c EINA_FALSE on failure, otherwise @c EINA_TRUE
+ *
*/
EAPI Eina_Bool eina_benchmark_register(Eina_Benchmark *bench,
const char *name,
@@ -413,29 +142,32 @@ EAPI Eina_Bool eina_benchmark_register(Eina_Benchmark *bench,
int count_step);
/**
- * @brief Run the benchmark tests that have been registered.
- *
- * @param bench The benchmark.
- * @return The list of names of the test files.
+ * @brief Runs the benchmark tests that have been registered.
*
- * This function runs all the tests that as been registered with
- * eina_benchmark_register() and save the result in a gnuplot
- * file. The name of the file has the following format:
+ * @details This function runs all the tests that have been registered with
+ * eina_benchmark_register() and saves the result in a gnuplot
+ * file. The name of the file has the following format:
*
* @code
* bench_[name]_[run]%s.gnuplot
* @endcode
*
- * where [name] and [run] are the values passed to
- * eina_benchmark_new().
+ * where [name] and [run] are the values passed to
+ * eina_benchmark_new().
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Each registered test is executed and timed. The time is written to
+ * the gnuplot file. The number of times each test is executed is
+ * controlled by the parameters passed to eina_benchmark_register().
+ *
+ * @remarks If @a bench is @c NULL, this functions returns @c NULL
+ * immediately. Otherwise, it returns the list of names of each
+ * test.
*
- * Each registered test is executed and timed. The time is written to
- * the gnuplot file. The number of times each test is executed is
- * controlled by the parameters passed to eina_benchmark_register().
+ * @param[in] bench The benchmark
+ * @return The list of names of the test files
*
- * If @p bench is @c NULL, this functions returns @c NULL
- * immediately. Otherwise, it returns the list of the names of each
- * test.
*/
EAPI Eina_Array *eina_benchmark_run(Eina_Benchmark *bench);
@@ -443,8 +175,4 @@ EAPI Eina_Array *eina_benchmark_run(Eina_Benchmark *bench);
* @}
*/
-/**
- * @}
- */
-
#endif /* EINA_BENCHMARK_H_ */
diff --git a/src/lib/eina/eina_binbuf.h b/src/lib/eina/eina_binbuf.h
index 32f3b1ebfe..71216479b1 100644
--- a/src/lib/eina/eina_binbuf.h
+++ b/src/lib/eina/eina_binbuf.h
@@ -7,39 +7,33 @@
#include "eina_types.h"
/**
- * @addtogroup Eina_Binary_Buffer_Group Binary Buffer
+ * @defgroup Eina_Binary_Buffer_Group Binary Buffer
+ * @ingroup Eina_Data_Types_Group
*
- * @brief These functions provide string buffers management.
+ * @brief This group discusses the functions that provide string buffers management.
*
* The Binary Buffer data type is designed to be a mutable string,
- * allowing to append, prepend or insert a string to a buffer.
- */
-
-/**
- * @addtogroup Eina_Data_Types_Group Data Types
- *
- * @{
- */
-
-/**
- * @defgroup Eina_Binary_Buffer_Group Binary Buffer
+ * allowing to append, prepend, or insert a string into a buffer.
*
* @{
*/
/**
* @typedef Eina_Binbuf
- * Type for a string buffer.
+ * @brief The structure type for a string buffer.
*/
typedef struct _Eina_Strbuf Eina_Binbuf;
/**
- * @brief Create a new string buffer.
+ * @brief Creates a new string buffer.
*
- * @return Newly allocated string buffer instance.
+ * @details This function creates a new string buffer. On error, @c NULL is
+ * returned and Eina error is set to #EINA_ERROR_OUT_OF_MEMORY. To
+ * free the resources, use eina_binbuf_free().
+ *
+ * @since_tizen 2.3
*
- * This function creates a new string buffer. On error, @c NULL is
- * returned. To free the resources, use eina_binbuf_free().
+ * @return Newly allocated string buffer instance.
*
* @see eina_binbuf_free()
* @see eina_binbuf_append()
@@ -48,76 +42,67 @@ typedef struct _Eina_Strbuf Eina_Binbuf;
EAPI Eina_Binbuf *eina_binbuf_new(void) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
/**
- * @brief Create a new string buffer using the passed string. The passed
- * string is used directly as the buffer, it's somehow the opposite function of
- * @ref eina_binbuf_string_steal . The passed string must be malloced.
- *
- * @param str the string to manage
- * @param length the length of the string.
- * @return Newly allocated string buffer instance.
+ * @brief Creates a new string buffer using the passed string. The passed
+ * string is used directly as the buffer, it's somehow the opposite function of
+ * @ref eina_binbuf_string_steal . The passed string must be malloced.
*
- * This function creates a new string buffer. On error, @c NULL is
- * returned. To free the resources, use eina_binbuf_free().
+ * @details This function creates a new string buffer. On error, @c NULL is
+ * returned and Eina error is set to #EINA_ERROR_OUT_OF_MEMORY. To
+ * free the resources, use eina_binbuf_free().
*
- * @see eina_binbuf_manage_new()
* @since 1.2.0
- */
-EAPI Eina_Binbuf *eina_binbuf_manage_new_length(unsigned char *str, size_t length) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
-
-/**
- * @brief Create a new string buffer using the passed string. The passed
- * string is used directly as the buffer, it's somehow the opposite function of
- * @ref eina_binbuf_string_steal . The passed string will not be touched.
*
- * @param str the string to start from
- * @param length the length of the string.
- * @return Newly allocated string buffer instance.
+ * @since_tizen 2.3
*
- * This function creates a new string buffer. On error, @c NULL is
- * returned. To free the resources, use eina_binbuf_free(). It will
- * not touch the internal buffer. Any changing operation will
- * create a fresh new memory, copy old data there and starting modifying
- * that one.
+ * @param[in] str The string to manage
+ * @param[in] length The length of the string
+ * @return A newly allocated string buffer instance
*
* @see eina_binbuf_manage_new()
- * @since 1.9.0
*/
-EAPI Eina_Binbuf *eina_binbuf_manage_read_only_new_length(const unsigned char *str, size_t length) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
+EAPI Eina_Binbuf *eina_binbuf_manage_new_length(unsigned char *str, size_t length) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
/**
- * @brief Free a string buffer.
+ * @brief Frees a string buffer.
+ *
+ * @details This function frees the memory of @a buf. @a buf must have been
+ * created by eina_binbuf_new().
*
- * @param buf The string buffer to free.
+ * @since_tizen 2.3
*
- * This function frees the memory of @p buf. @p buf must have been
- * created by eina_binbuf_new().
+ * @param[in] buf The string buffer to free
*/
EAPI void eina_binbuf_free(Eina_Binbuf *buf) EINA_ARG_NONNULL(1);
/**
- * @brief Reset a string buffer.
+ * @brief Resets a string buffer.
+ *
+ * @details This function resets @a buf, the buffer length is set to @c 0 and the
+ * string is set to '\\0'. No memory is freed.
*
- * @param buf The string buffer to reset.
+ * @since_tizen 2.3
+ *
+ * @param[in] buf The string buffer to reset
*
- * This function reset @p buf: the buffer len is set to 0, and the
- * string is set to '\\0'. No memory is free'd.
*/
EAPI void eina_binbuf_reset(Eina_Binbuf *buf) EINA_ARG_NONNULL(1);
/**
- * @brief Append a string of exact length to a buffer, reallocating as necessary.
+ * @brief Appends a string of exact length to a buffer, reallocating as necessary.
+ *
+ * @details This function appends @a str to @a buf. @a str must be at most of size
+ * @a length. It is slightly faster than eina_binbuf_append() as
+ * it does not compute the size of @a str. It is useful when dealing
+ * with strings of known size, such as eina_strngshare. If @a buf
+ * can't append it, @c EINA_FALSE is returned, otherwise @c EINA_TRUE is
+ * returned.
*
- * @param buf The string buffer to append to.
- * @param str The string to append.
- * @param length The exact length to use.
- * @return #EINA_TRUE on success, #EINA_FALSE on failure.
+ * @since_tizen 2.3
*
- * This function appends @p str to @p buf. @p str must be of size at
- * most @p length. It is slightly faster than eina_binbuf_append() as
- * it does not compute the size of @p str. It is useful when dealing
- * with strings of known size, such as eina_strngshare. If @p buf
- * can't append it, #EINA_FALSE is returned, otherwise #EINA_TRUE is
- * returned.
+ * @param[in] buf The string buffer to append to
+ * @param[in] str The string to append
+ * @param[in] length The exact length to use
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure
*
* @see eina_stringshare_length()
* @see eina_binbuf_append()
@@ -126,52 +111,38 @@ EAPI void eina_binbuf_reset(Eina_Binbuf *buf) EINA_ARG_NONNULL(1);
EAPI Eina_Bool eina_binbuf_append_length(Eina_Binbuf *buf, const unsigned char *str, size_t length) EINA_ARG_NONNULL(1, 2);
/**
- * @brief Append an Eina_Binbuf to a buffer, reallocating as necessary.
- *
- * @param buf The string buffer to append to.
- * @param data The string buffer to append.
- * @return #EINA_TRUE on success, #EINA_FALSE on failure.
+ * @brief Appends a character to a string buffer, reallocating as
+ * necessary.
*
- * This function appends @p data to @p buf. @p data must be allocated and
- * different from @c NULL. It is slightly faster than eina_binbuf_append() as
- * it does not compute the size of @p str. If @p buf can't append it,
- * #EINA_FALSE is returned, otherwise #EINA_TRUE is returned.
+ * @details This function inserts @a c to @a buf. If it cannot insert it, @c EINA_FALSE
+ * is returned, otherwise @c EINA_TRUE is returned.
*
- * @see eina_binbuf_append()
- * @see eina_binbuf_append_n()
- * @see eina_binbuf_append_length()
- * @since 1.9.0
- */
-EAPI Eina_Bool eina_binbuf_append_buffer(Eina_Binbuf *buf, const Eina_Binbuf *data) EINA_ARG_NONNULL(1, 2);
-
-/**
- * @brief Append a character to a string buffer, reallocating as
- * necessary.
+ * @since_tizen 2.3
*
- * @param buf The string buffer to append to.
- * @param c The char to append.
- * @return #EINA_TRUE on success, #EINA_FALSE on failure.
+ * @param[in] buf The string buffer to append to
+ * @param[in] c The character to append
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure
*
- * This function inserts @p c to @p buf. If it can not insert it, #EINA_FALSE
- * is returned, otherwise #EINA_TRUE is returned.
*/
EAPI Eina_Bool eina_binbuf_append_char(Eina_Binbuf *buf, unsigned char c) EINA_ARG_NONNULL(1);
/**
- * @brief Insert a string of exact length to a buffer, reallocating as necessary.
+ * @brief Inserts a string of exact length into a buffer, reallocating as necessary.
+ *
+ * @details This function inserts @a str into @a buf. @a str must be at most of size
+ * @a length. It is slightly faster than eina_binbuf_insert() as
+ * it does not compute the size of @a str. It is useful when dealing
+ * with strings of known size, such as eina_strngshare. If @a buf
+ * can't insert it, @c EINA_FALSE is returned, otherwise @c EINA_TRUE is
+ * returned.
*
- * @param buf The string buffer to insert to.
- * @param str The string to insert.
- * @param length The exact length to use.
- * @param pos The position to insert the string.
- * @return #EINA_TRUE on success, #EINA_FALSE on failure.
+ * @since_tizen 2.3
*
- * This function inserts @p str to @p buf. @p str must be of size at
- * most @p length. It is slightly faster than eina_binbuf_insert() as
- * it does not compute the size of @p str. It is useful when dealing
- * with strings of known size, such as eina_strngshare. If @p buf
- * can't insert it, #EINA_FALSE is returned, otherwise #EINA_TRUE is
- * returned.
+ * @param[in] buf The string buffer to insert to
+ * @param[in] str The string to insert
+ * @param[in] length The exact length to use
+ * @param[in] pos The position at which to insert the string
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure
*
* @see eina_stringshare_length()
* @see eina_binbuf_insert()
@@ -180,84 +151,99 @@ EAPI Eina_Bool eina_binbuf_append_char(Eina_Binbuf *buf, unsigned char c) EINA_A
EAPI Eina_Bool eina_binbuf_insert_length(Eina_Binbuf *buf, const unsigned char *str, size_t length, size_t pos) EINA_ARG_NONNULL(1, 2);
/**
- * @brief Insert a character to a string buffer, reallocating as
- * necessary.
+ * @brief Inserts a character into a string buffer, reallocating as
+ * necessary.
*
- * @param buf The string buffer to insert to.
- * @param c The char to insert.
- * @param pos The position to insert the char.
- * @return #EINA_TRUE on success, #EINA_FALSE on failure.
+ * @details This function inserts @a c into @a buf at position @a pos. If @a buf
+ * can't append it, @c EINA_FALSE is returned, otherwise @c EINA_TRUE is
+ * returned.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] buf The string buffer to insert into
+ * @param[in] c The character to insert
+ * @param[in] pos The position at which to insert the character
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure
*
- * This function inserts @p c to @p buf at position @p pos. If @p buf
- * can't append it, #EINA_FALSE is returned, otherwise #EINA_TRUE is
- * returned.
*/
EAPI Eina_Bool eina_binbuf_insert_char(Eina_Binbuf *buf, unsigned char c, size_t pos) EINA_ARG_NONNULL(1);
/**
- * @brief Remove a slice of the given string buffer.
- *
- * @param buf The string buffer to remove a slice.
- * @param start The initial (inclusive) slice position to start
- * removing, in bytes.
- * @param end The final (non-inclusive) slice position to finish
- * removing, in bytes.
- * @return #EINA_TRUE on success, #EINA_FALSE on failure.
- *
- * This function removes a slice of @p buf, starting at @p start
- * (inclusive) and ending at @p end (non-inclusive). Both values are
- * in bytes. It returns #EINA_FALSE on failure, #EINA_TRUE otherwise.
+ * @brief Removes a slice of the given string buffer.
+ *
+ * @details This function removes a slice of @a buf, starting from @a start
+ * (inclusive) and ending at @a end (non-inclusive). Both values are
+ * in bytes. It returns @c EINA_FALSE on failure, otherwise @c EINA_TRUE.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] buf The string buffer to remove a slice of
+ * @param[in] start The initial (inclusive) slice position to start
+ * removing from, in bytes
+ * @param[in] end The final (non-inclusive) slice position to finish
+ * removing at, in bytes
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure
*/
EAPI Eina_Bool eina_binbuf_remove(Eina_Binbuf *buf, size_t start, size_t end) EINA_ARG_NONNULL(1);
/**
- * @brief Retrieve a pointer to the contents of a string buffer
+ * @brief Gets a pointer to the contents of a string buffer.
+ *
+ * @details This function returns the string contained in @a buf. The returned
+ * value must not be modified and is no longer valid if @a buf is
+ * modified. In other words, any eina_binbuf_append() or similar
+ * makes that pointer invalid.
*
- * @param buf The string buffer.
- * @return The current string in the string buffer.
+ * @since_tizen 2.3
*
- * This function returns the string contained in @p buf. The returned
- * value must not be modified and will no longer be valid if @p buf is
- * modified. In other words, any eina_binbuf_append() or similar will
- * make that pointer invalid.
+ * @param[in] buf The string buffer
+ * @return The current string in the string buffer
*
* @see eina_binbuf_string_steal()
*/
EAPI const unsigned char *eina_binbuf_string_get(const Eina_Binbuf *buf) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
/**
- * @brief Steal the contents of a string buffer.
+ * @brief Steals the contents of a string buffer.
*
- * @param buf The string buffer to steal.
- * @return The current string in the string buffer.
+ * @details This function returns the string contained in @a buf. @a buf is
+ * then initialized and does not own the returned string anymore. The
+ * caller must release the memory of the returned string by calling
+ * free().
*
- * This function returns the string contained in @p buf. @p buf is
- * then initialized and does not own the returned string anymore. The
- * caller must release the memory of the returned string by calling
- * free().
+ * @since_tizen 2.3
+ *
+ * @param[in] buf The string buffer to steal from
+ * @return The current string in the string buffer
*
* @see eina_binbuf_string_get()
*/
EAPI unsigned char *eina_binbuf_string_steal(Eina_Binbuf *buf) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
/**
- * @brief Free the contents of a string buffer but not the buffer.
+ * @brief Frees the contents of a string buffer but not the buffer.
+ *
+ * @details This function frees the string contained in @a buf without freeing
+ * @a buf.
+ *
+ * @since_tizen 2.3
*
- * @param buf The string buffer to free the string of.
+ * @param[in] buf The string buffer to free the string of
*
- * This function frees the string contained in @p buf without freeing
- * @p buf.
*/
EAPI void eina_binbuf_string_free(Eina_Binbuf *buf) EINA_ARG_NONNULL(1);
/**
- * @brief Retrieve the length of the string buffer content.
+ * @brief Gets the length of the string buffer's content.
*
- * @param buf The string buffer.
- * @return The current length of the string, in bytes.
+ * @details This function returns the length of @a buf.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] buf The string buffer
+ * @return The current length of the string, in bytes
*
- * This function returns the length of @p buf.
*/
EAPI size_t eina_binbuf_length_get(const Eina_Binbuf *buf) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
@@ -265,8 +251,4 @@ EAPI size_t eina_binbuf_length_get(const Eina_Binbuf *buf) EINA_ARG_NONNULL(1
* @}
*/
-/**
- * @}
- */
-
#endif /* EINA_STRBUF_H */
diff --git a/src/lib/eina/eina_convert.h b/src/lib/eina/eina_convert.h
index be65cc404e..588a7e185c 100644
--- a/src/lib/eina/eina_convert.h
+++ b/src/lib/eina/eina_convert.h
@@ -1,14 +1,14 @@
/* EINA - EFL data type library
* Copyright (C) 2008 Cedric BAIL, Vincent Torri
*
- * This library is free software; you can redistribute it and/or
+ * This library is a free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
@@ -26,22 +26,23 @@
/**
- * @addtogroup Eina_Convert_Group Convert
+ * @defgroup Eina_Convert_Group Convert
+ * @ingroup Eina_Tools_Group
*
- * These functions allow you to convert integer or real numbers to
- * string or conversely.
+ * @brief This group discusses the functions that allow you to convert an
+ * integer or real numbers to a string or conversely.
*
* To use these functions, you have to call eina_init()
- * first, and eina_shutdown() when eina is not used anymore.
+ * first, and then eina_shutdown() when eina is not used anymore.
*
* @section Eina_Convert_From_Integer_To_Sring Conversion from integer to string
*
* To convert an integer to a string in the decimal base,
* eina_convert_itoa() should be used. If the hexadecimal base is
- * wanted, eina_convert_xtoa() should be used. They all need a buffer
+ * wanted, eina_convert_xtoa() should be used. They all need a buffer that is
* sufficiently large to store all the cyphers.
*
- * Here is an example of use:
+ * Here is an example for use:
*
* @code
* #include <stdlib.h>
@@ -76,15 +77,14 @@
* gcc -Wall -o test_eina_convert test_eina.c `pkg-config --cflags --libs eina`
* @endcode
*
- * @note
- * The alphabetical cyphers are in lower case.
+ * @remarks The alphabetical cyphers are in lower case.
*
* @section Eina_Convert_Double Conversion double / string
*
* To convert a double to a string, eina_convert_dtoa() should be
* used. Like with the integer functions, a buffer must be used. The
* resulting string has the following format (which is the result
- * obtained with snprintf() and the @%a modifier):
+ * obtained with snprintf() and the modifier):
*
* @code
* [-]0xh.hhhhhp[+-]e
@@ -92,18 +92,18 @@
*
* To convert a string to a double, eina_convert_atod() should be
* used. The format of the string must be as above. Then, the double
- * has the following mantiss and exponent:
+ * has the following mantissa and exponent:
*
* @code
* mantiss : [-]hhhhhh
* exponent : 2^([+-]e - 4 * n)
* @endcode
*
- * with n being number of cypers after the point in the string
- * format. To obtain the double number from the mantiss and exponent,
+ * with n being the number of cyphers after the point in the string
+ * format. To obtain the double number from the mantissa and exponent,
* use ldexp().
*
- * Here is an example of use:
+ * Here is an example for use:
*
* @code
* #include <stdlib.h>
@@ -144,97 +144,107 @@
* @code
* gcc -Wall -o test_eina_convert test_eina.c `pkg-config --cflags --libs eina` -lm
* @endcode
+ *
+ * @{
*/
/**
- * @addtogroup Eina_Tools_Group Tools
- *
- * @{
+ * @var EINA_ERROR_CONVERT_P_NOT_FOUND
+ * @brief Error identifier corresponding to string not containing 'p'.
*/
+EAPI extern Eina_Error EINA_ERROR_CONVERT_P_NOT_FOUND;
+
/**
- * @defgroup Eina_Convert_Group Convert
- *
- * @{
+ * @var EINA_ERROR_CONVERT_0X_NOT_FOUND
+ * @brief The error identifier corresponding to the string not containing '0x'.
*/
+EAPI extern Eina_Error EINA_ERROR_CONVERT_0X_NOT_FOUND;
-EAPI extern Eina_Error EINA_ERROR_CONVERT_P_NOT_FOUND; /**< Not used, perhaps a placeholder? Defined as 0 in eina_convert.c*/
-EAPI extern Eina_Error EINA_ERROR_CONVERT_0X_NOT_FOUND; /**< Not used, perhaps a placeholder? Defined as 0 in eina_convert.c*/
-EAPI extern Eina_Error EINA_ERROR_CONVERT_OUTRUN_STRING_LENGTH; /**< Not used, perhaps a placeholder? Defined as 0 in eina_convert.c*/
+/**
+ * @var EINA_ERROR_CONVERT_OUTRUN_STRING_LENGTH
+ * @brief The error identifier corresponding to the length of the string being too small.
+ */
+EAPI extern Eina_Error EINA_ERROR_CONVERT_OUTRUN_STRING_LENGTH;
/**
- * @brief Convert an integer number to a string in decimal base.
+ * @brief Converts an integer number to a string in decimal base.
+ *
+ * @details This function converts @a n to a null terminated string. The
+ * converted string is in decimal base. As no check is done, @a s must
+ * be a buffer that is sufficiently large to store the integer.
*
- * @param n The integer to convert.
- * @param s The buffer to store the converted integer.
- * @return The length of the string, including the nul terminated
- * character.
+ * @since_tizen 2.3
*
- * This function converts @p n to a nul terminated string. The
- * converted string is in decimal base. As no check is done, @p s must
- * be a buffer that is sufficiently large to store the integer.
+ * @remarks The returned value is the length of the string, including the null
+ * terminated character.
+ *
+ * @param[in] n The integer to convert
+ * @param[in] s The buffer to store the converted integer
+ * @return The length of the string, including the null terminated
+ * character
*
- * The returned value is the length of the string, including the nul
- * terminated character.
*/
EAPI int eina_convert_itoa(int n, char *s) EINA_ARG_NONNULL(2);
/**
- * @brief Convert an integer number to a string in hexadecimal base.
+ * @brief Converts an integer number to a string in hexadecimal base.
+ *
+ * @details This function converts @a n to a null terminated string. The
+ * converted string is in hexadecimal base and the alphabetical
+ * cyphers are in lower case. As no check is done, @a s must be a
+ * buffer that is sufficiently large to store the integer.
*
- * @param n The integer to convert.
- * @param s The buffer to store the converted integer.
- * @return The length of the string, including the nul terminated
- * character.
+ * @since_tizen 2.3
*
- * This function converts @p n to a nul terminated string. The
- * converted string is in hexadecimal base and the alphabetical
- * cyphers are in lower case. As no check is done, @p s must be a
- * buffer that is sufficiently large to store the integer.
+ * @remarks The returned value is the length of the string, including the null
+ * terminated character.
+ *
+ * @param[in] n The integer to convert
+ * @param[in] s The buffer to store the converted integer
+ * @return The length of the string, including the null terminated
+ * character
*
- * The returned value is the length of the string, including the nul
- * terminated character.
*/
EAPI int eina_convert_xtoa(unsigned int n, char *s) EINA_ARG_NONNULL(2);
/**
- * @brief Convert a double to a string.
+ * @brief Converts a double to a string.
*
- * @param d The double to convert.
- * @param des The destination buffer to store the converted double.
- * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
+ * @details This function converts the double @a d to a string. The string is
+ * stored in the buffer pointed by @a des and must be sufficiently
+ * large to contain the converted double. The returned string is null
+ * terminated and has the following format:
*
- * This function converts the double @p d to a string. The string is
- * stored in the buffer pointed by @p des and must be sufficiently
- * large to contain the converted double. The returned string is nul
- * terminated and has the following format:
+ * @since_tizen 2.3
*
* @code
* [-]0xh.hhhhhp[+-]e
* @endcode
*
- * where the h are the hexadecimal cyphers of the mantiss and e the
+ * where h are the hexadecimal cyphers of the mantissa and e is the
* exponent (a decimal number).
*
- * The returned value is the length of the string, including the nul
- * character.
+ * @remarks The returned value is the length of the string, including the null
+ * terminated character.
+ *
+ * @param[in] d The double to convert
+ * @param[in] des The destination buffer to store the converted double
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE
+ *
*/
EAPI int eina_convert_dtoa(double d, char *des) EINA_ARG_NONNULL(2);
/**
- * @brief Convert a string to a double.
+ * @brief Converts a string to a double.
*
- * @param src The string to convert.
- * @param length The length of the string.
- * @param m The mantisse.
- * @param e The exponent.
- * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
+ * @details This function converts the string @a s of length @a length that
+ * represents a double in hexadecimal base to a double. It is used to
+ * replace the use of snprintf() with the modifier, which is
+ * missing on some platform (like Windows (tm) or OpenBSD).
*
- * This function converts the string @p s of length @p length that
- * represent a double in hexadecimal base to a double. It is used to
- * replace the use of snprintf() with the \%a modifier, which is
- * missing on some platform (like Windows (tm) or OpenBSD).
+ * @since_tizen 2.3
*
* The string must have the following format:
*
@@ -242,20 +252,33 @@ EAPI int eina_convert_dtoa(double d, char *des) EINA_ARG_NONNULL(2);
* [-]0xh.hhhhhp[+-]e
* @endcode
*
- * where the h are the hexadecimal cyphers of the mantiss and e the
- * exponent (a decimal number). If n is the number of cypers after the
- * point, the returned mantiss and exponents are:
+ * where h are the hexadecimal cyphers of the mantissa and e is the
+ * exponent (a decimal number). If n is the number of cyphers after the
+ * point, the returned mantissa and exponent are:
*
* @code
* mantiss : [-]hhhhhh
* exponent : 2^([+-]e - 4 * n)
* @endcode
*
- * The mantiss and exponent are stored in the buffers pointed
- * respectively by @p m and @p e.
+ * The mantissa and exponent are stored in the buffers pointed
+ * by @a m and @a e respectively.
+ *
+ * If the string is invalid, the error is set to:
*
- * If the string is invalid #EINA_FALSE is returned, otherwise #EINA_TRUE is
+ * @li #EINA_ERROR_CONVERT_0X_NOT_FOUND - If no 0x is found,
+ * @li #EINA_ERROR_CONVERT_P_NOT_FOUND - If no p is found,
+ * @li #EINA_ERROR_CONVERT_OUTRUN_STRING_LENGTH If @a length is not correct.
+ *
+ * In those cases, @c EINA_FALSE is returned, otherwise @c EINA_TRUE is
* returned.
+ *
+ * @param[in] src The string to convert
+ * @param[in] length The length of the string
+ * @param[out] m The mantissa
+ * @param[out] e The exponent
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE
+ *
*/
EAPI Eina_Bool eina_convert_atod(const char *src,
int length,
@@ -264,47 +287,45 @@ EAPI Eina_Bool eina_convert_atod(const char *src,
/**
- * @brief Convert a 32.32 fixed point number to a string.
+ * @brief Converts a 32.32 fixed point number to a string.
*
- * @param fp The fixed point number to convert.
- * @param des The destination buffer to store the converted fixed point number.
- * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
- *
- * This function converts the 32.32 fixed point number @p fp to a
- * string. The string is stored in the buffer pointed by @p des and
- * must be sufficiently large to contain the converted fixed point
- * number. The returned string is terminated and has the following
- * format:
+ * @details This function converts the 32.32 fixed point number @a fp to a
+ * string. The string is stored in the buffer pointed by @a des and
+ * must be sufficiently large to contain the converted fixed point
+ * number. The returned string is terminated and has the following
+ * format:
*
* @code
* [-]0xh.hhhhhp[+-]e
* @endcode
*
- * where the h are the hexadecimal cyphers of the mantiss and e the
+ * where h are the hexadecimal cyphers of the mantissa and e is the
* exponent (a decimal number).
*
- * The returned value is the length of the string, including the nul
- * character.
+ * @since_tizen 2.3
+ *
+ * @remarks The returned value is the length of the string, including the null
+ * terminating character.
+ *
+ * @remarks The code is the same as eina_convert_dtoa() except that it
+ * implements the frexp() function for fixed point numbers and does
+ * some optimisations.
+ *
+ * @param[in] fp The fixed point number to convert
+ * @param[in] des The destination buffer to store the converted fixed point number
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE
*
- * @note The code is the same than eina_convert_dtoa() except that it
- * implements the frexp() function for fixed point numbers and does
- * some optimisations.
*/
EAPI int eina_convert_fptoa(Eina_F32p32 fp,
char *des) EINA_ARG_NONNULL(2);
/**
- * @brief Convert a string to a 32.32 fixed point number.
+ * @brief Converts a string to a 32.32 fixed point number.
*
- * @param src The string to convert.
- * @param length The length of the string.
- * @param fp The fixed point number.
- * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
- *
- * This function converts the string @p src of length @p length that
- * represent a double in hexadecimal base to a 32.32 fixed point
- * number stored in @p fp. The function always tries to convert the
- * string with eina_convert_atod().
+ * @details This function converts the string @a src of length @a length that
+ * represents a double in hexadecimal base to a 32.32 fixed point
+ * number stored in @a fp. The function always tries to convert the
+ * string with eina_convert_atod().
*
* The string must have the following format:
*
@@ -312,23 +333,37 @@ EAPI int eina_convert_fptoa(Eina_F32p32 fp,
* [-]0xh.hhhhhp[+-]e
* @endcode
*
- * where the h are the hexadecimal cyphers of the mantiss and e the
- * exponent (a decimal number). If n is the number of cypers after the
- * point, the returned mantiss and exponents are:
+ * where h are the hexadecimal cyphers of the mantissa and e is the
+ * exponent (a decimal number). If n is the number of cyphers after the
+ * point, the returned mantissa and exponent are:
*
* @code
* mantiss : [-]hhhhhh
* exponent : 2^([+-]e - 4 * n)
* @endcode
*
- * The mantiss and exponent are stored in the buffers pointed
- * respectively by @p m and @p e.
+ * The mantissa and exponent are stored in the buffers pointed
+ * by @a m and @a e respectively.
+ *
+ * @remarks If the string is invalid, the error is set to:
*
- * If the string is invalid, #EINA_FALSE is returned,
- * otherwise @p fp is computed and #EINA_TRUE is returned.
+ * @li #EINA_ERROR_CONVERT_0X_NOT_FOUND - If no 0x is found,
+ * @li #EINA_ERROR_CONVERT_P_NOT_FOUND If no p is found,
+ * @li #EINA_ERROR_CONVERT_OUTRUN_STRING_LENGTH If @a length is not correct.
+ *
+ * In those cases, or if @a fp is @c NULL, @c EINA_FALSE is returned,
+ * otherwise @a fp is computed and @c EINA_TRUE is returned.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks The code uses eina_convert_atod() and does the correct bit
+ * shift to compute the fixed point number.
+ *
+ * @param[in] src The string to convert
+ * @param[in] length The length of the string
+ * @param[out] fp The fixed point number
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE
*
- * @note The code uses eina_convert_atod() and do the correct bit
- * shift to compute the fixed point number.
*/
EAPI Eina_Bool eina_convert_atofp(const char *src,
int length,
@@ -338,8 +373,4 @@ EAPI Eina_Bool eina_convert_atofp(const char *src,
* @}
*/
-/**
- * @}
- */
-
#endif /* EINA_CONVERT_H_ */
diff --git a/src/lib/eina/eina_cpu.h b/src/lib/eina/eina_cpu.h
index e871774aa2..19be53047d 100644
--- a/src/lib/eina/eina_cpu.h
+++ b/src/lib/eina/eina_cpu.h
@@ -1,14 +1,14 @@
/* EINA - EFL data type library
* Copyright (C) 2007-2008 Jorge Luis Zapata Muga
*
- * This library is free software; you can redistribute it and/or
+ * This library is a free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. aSee the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
@@ -19,30 +19,8 @@
#ifndef EINA_CPU_H_
#define EINA_CPU_H_
-/**
- * @addtogroup Eina_Cpu_Group Cpu
- *
- * @brief Cpu and architecture related helpers
- */
-
-/**
- * @addtogroup Eina_Tools_Group Tools
- *
- * @{
- */
-
-/**
- * @defgroup Eina_Cpu_Group Cpu
- *
- * @{
- */
-
#include "eina_types.h"
-/**
- * @typedef Eina_Cpu_Features
- * Enumerates different hardware architectures.
- */
typedef enum _Eina_Cpu_Features
{
EINA_CPU_MMX = 0x00000001,
@@ -53,83 +31,9 @@ typedef enum _Eina_Cpu_Features
EINA_CPU_ALTIVEC = 0x00000010,
EINA_CPU_VIS = 0x00000020,
EINA_CPU_NEON = 0x00000040,
- EINA_CPU_SSSE3 = 0x00000080,
- EINA_CPU_SSE41 = 0x00000100,
- EINA_CPU_SSE42 = 0x00000200
} Eina_Cpu_Features;
-/**
- * @brief Global hardware architecture handler
- *
- * @return the current cpu features
- */
-EAPI extern Eina_Cpu_Features eina_cpu_features;
-
-/**
- * @brief Cpu features accessor
- *
- * @return the current cpu features
- */
EAPI Eina_Cpu_Features eina_cpu_features_get(void);
-
-/**
- * @brief Get the current number of precessors
- *
- * @return the number of processors that are online, that
- * is available when the function is called.
- */
EAPI int eina_cpu_count(void);
-/**
- * @brief Get the current virtual page size
- *
- * @return the fixed length that represents the smallest unit of data for memory
- * allocation performed by the operating system on behalf of the program, and
- * for transfers between the main memory and any other auxiliary store.
- */
-EAPI int eina_cpu_page_size(void);
-
-/**
- * @brief Reverses the byte order of a 16-bit (destination) register.
- *
- * @param x The binary word to swap
- * @return a byte order swapped 16-bit integer.
- *
- * On big endian systems, the number is converted to little endian byte order.
- * On little endian systems, the number is converted to big endian byte order.
- */
-static inline unsigned short eina_swap16(unsigned short x);
-
-/**
- * @brief Reverses the byte order of a 32-bit (destination) register.
- *
- * @param x The binary word to swap
- * @return a byte order swapped 32-bit integer.
- *
- * On big endian systems, the number is converted to little endian byte order.
- * On little endian systems, the number is converted to big endian byte order.
- */
-static inline unsigned int eina_swap32(unsigned int x);
-
-/**
- * @brief Reverses the byte order of a 64-bit (destination) register.
- *
- * @param x The binary word to swap
- * @return a byte order swapped 64-bit integer.
- *
- * On big endian systems, the number is converted to little endian byte order.
- * On little endian systems, the number is converted to big endian byte order.
- */
-static inline unsigned long long eina_swap64(unsigned long long x);
-
-#include "eina_inline_cpu.x"
-
-/**
- * @}
- */
-
-/**
- * @}
- */
-
#endif /* EINA_CPU_H_ */
diff --git a/src/lib/eina/eina_fp.h b/src/lib/eina/eina_fp.h
index 7a169a20f5..236bd1018d 100644
--- a/src/lib/eina/eina_fp.h
+++ b/src/lib/eina/eina_fp.h
@@ -2,14 +2,14 @@
* Copyright (C) 2007-2008 Jorge Luis Zapata Muga
* Copyright (C) 2009 Cedric BAIL
*
- * This library is free software; you can redistribute it and/or
+ * This library is a free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
@@ -20,24 +20,6 @@
#ifndef EINA_FP_H_
# define EINA_FP_H_
-/**
- * @addtogroup Eina_Fp_Group Fp
- *
- * @brief Floating point numbers data type management.
- */
-
-/**
- * @addtogroup Eina_Data_Types_Group Data Types
- *
- * @{
- */
-
-/**
- * @defgroup Eina_Fp_Group Fp
- *
- * @{
- */
-
#include "eina_types.h"
#ifdef _MSC_VER
@@ -48,436 +30,77 @@ typedef signed int int32_t;
# include <stdint.h>
#endif
-/**
- * @def EINA_F32P32_PI
- * @brief Yields the 32-bit PI constant
- */
#define EINA_F32P32_PI 0x00000003243f6a89
-/**
- * @typedef Eina_F32p32
- * Type for floating point number where the size of the integer part is 32-bit
- * and the size of the decimal part is 32-bit
- */
typedef int64_t Eina_F32p32;
-
-/**
- * @typedef Eina_F16p16
- * Type for floating point number where the size of the integer part is 16-bit
- * and the size of the decimal part is 16-bit
- */
typedef int32_t Eina_F16p16;
-
-/**
- * @typedef Eina_F8p24
- * Type for floating point number where the size of the integer part is 8-bit
- * and the size of the decimal part is 24bits
- */
typedef int32_t Eina_F8p24;
-/**
- * @brief Create a new Eina_F32p32 floating point number from standard 32-bit
- * integer
- *
- * @param v 32-bit integer value to convert
- * @return The value converted into Eina_F32p32 format
- */
static inline Eina_F32p32 eina_f32p32_int_from(int32_t v);
-
-/**
- * @brief Create a new standard 32-bit integer from Eina_F32p32 floating point
- * number
- *
- * @param v Eina_F32p32 value to convert
- * @return The value converted into 32-bit integer
- */
static inline int32_t eina_f32p32_int_to(Eina_F32p32 v);
-
-/**
- * @brief Create a new Eina_F32p32 floating point number from standard double
- *
- * @param v double value to convert
- * @return The value converted into Eina_F32p32 format
- */
static inline Eina_F32p32 eina_f32p32_double_from(double v);
-
-/**
- * @brief Create a new standard double from Eina_F32p32 floating point
- * number
- *
- * @param v Eina_F32p32 value to convert
- * @return The value converted into double
- */
static inline double eina_f32p32_double_to(Eina_F32p32 v);
-/**
- * @brief Calculates the sum of two Eina_F32p32 floating point numbers
- *
- * @param a The first number
- * @param b The second number
- * @return The sum result of the two numbers @p a + @p b
- */
-static inline Eina_F32p32 eina_f32p32_add(Eina_F32p32 a, Eina_F32p32 b);
-
-/**
- * @brief Calculates the substraction of two Eina_F32p32 floating point numbers
- *
- * @param a The first number
- * @param b The substracted number
- * @return The substaction result of the two numbers @p a - @p b
- */
-static inline Eina_F32p32 eina_f32p32_sub(Eina_F32p32 a, Eina_F32p32 b);
-
-/**
- * @brief Calculates the multiplication of two Eina_F32p32 floating point numbers
- *
- * @param a The first number
- * @param b The second number
- * @return The mutliplication result of the two numbers @p a * @p b
- *
- * To prevent overflow during multiplication we need to reduce the precision of
- * the fraction part Shift both values to only contain 16 bit of the fraction
- * part (rounded). After multiplication we again have a value with a 32-bit
- * fraction part.
- */
-static inline Eina_F32p32 eina_f32p32_mul(Eina_F32p32 a, Eina_F32p32 b);
-
-/**
- * @brief Calculates the scale multiplication of one Eina_F32p32 floating point
- * number with an integer
- *
- * @param a The Eina_F32p32 number
- * @param b The integer value
- * @return The mutliplication result of the two numbers @p a * @p b
- */
-static inline Eina_F32p32 eina_f32p32_scale(Eina_F32p32 a, int b);
-
-/**
- * @brief Calculates the division of two Eina_F32p32 floating point numbers
- *
- * @param a The numerator number
- * @param b The denominator number
- * @return The division result of the two numbers @p a / @p b
- */
-static inline Eina_F32p32 eina_f32p32_div(Eina_F32p32 a, Eina_F32p32 b);
-
-/**
- * @brief Calculates the square root of an Eina_F32p32 floating point number
- *
- * @param a The number to calculate the square root from
- * @return The square root result for the number @p a
- */
+static inline Eina_F32p32 eina_f32p32_add(Eina_F32p32 a,
+ Eina_F32p32 b);
+static inline Eina_F32p32 eina_f32p32_sub(Eina_F32p32 a,
+ Eina_F32p32 b);
+static inline Eina_F32p32 eina_f32p32_mul(Eina_F32p32 a,
+ Eina_F32p32 b);
+static inline Eina_F32p32 eina_f32p32_scale(Eina_F32p32 a,
+ int b);
+static inline Eina_F32p32 eina_f32p32_div(Eina_F32p32 a,
+ Eina_F32p32 b);
static inline Eina_F32p32 eina_f32p32_sqrt(Eina_F32p32 a);
-
-/**
- * @brief Get the absolute value of the integer part of and Eina_F32p32 floating
- * point number
- *
- * @param a The floating point number
- * @return The positive integer part of the number @p a
- */
static inline unsigned int eina_f32p32_fracc_get(Eina_F32p32 v);
-/**
- * @brief Get the absolute value of an Eina_F32p32 floating point number
- *
- * @param a The floating point number
- * @return The absolute value for the number @p a
- * @warning Has known issues on 64-bit architecture, prefer
- * eina_f32p32_fracc_get() instead
- */
+// dont use llabs - issues if not on 64bit
#define eina_fp32p32_llabs(a) ((a < 0) ? -(a) : (a))
-/**
- * @brief Calculates the cosinus of a floating point number
- *
- * @param a The angle in radians to calculate the cosinus from.
- * @return The cosinus value of the angle @p a
- */
EAPI Eina_F32p32 eina_f32p32_cos(Eina_F32p32 a);
-
-/**
- * @brief Calculates the sinus of a floating point number
- *
- * @param a The angle in radians to calculate the sinus from.
- * @return The cosinus value of the angle @p a
- */
EAPI Eina_F32p32 eina_f32p32_sin(Eina_F32p32 a);
-
-/**
- * @def EINA_F16P16_ONE
- *
- * Yields the maximum 16-bit unsigned integer size (= 65536)
- */
-#define EINA_F16P16_ONE (1 << 16)
-
-/**
- * @def EINA_F16P16_HALF
- *
- * Yields the maximum 16-bit signed integer size (= 32768)
- */
-#define EINA_F16P16_HALF (1 << 15)
-
-/**
- * @brief Create a new Eina_F16p316 floating point number from standard 32-bit
- * integer
- *
- * @param v 32-bit integer value to convert
- * @return The value converted into Eina_F16p16 format
- */
static inline Eina_F16p16 eina_f16p16_int_from(int32_t v);
-
-/**
- * @brief Create a new standard 32-bit integer from Eina_F16p16 floating point
- * number
- *
- * @param v Eina_F16p16 value to convert
- * @return The value converted into 32-bit integer
- */
static inline int32_t eina_f16p16_int_to(Eina_F16p16 v);
-
-/**
- * @brief Create a new Eina_F16p16 floating point number from standard double
- *
- * @param v double value to convert
- * @return The value converted into Eina_F16p16 format
- */
-static inline Eina_F16p16 eina_f16p16_double_from(double v);
-
-/**
- * @brief Create a new standard double from Eina_F16p16 floating point
- * number
- *
- * @param v Eina_F16p16 value to convert
- * @return The value converted into double
- */
-static inline double eina_f16p16_double_to(Eina_F16p16 v);
-
-/**
- * @brief Create a new Eina_F16p16 floating point number from standard float
- *
- * @param v float value to convert
- * @return The value converted into Eina_F16p16 format
- */
static inline Eina_F16p16 eina_f16p16_float_from(float v);
-
-/**
- * @brief Create a new standard float from Eina_F16p16 floating point
- * number
- *
- * @param v Eina_F16p16 value to convert
- * @return The value converted into float
- */
static inline float eina_f16p16_float_to(Eina_F16p16 v);
-/**
- * @brief Calculates the sum of two Eina_F16p16 floating point numbers
- *
- * @param a The first number
- * @param b The second number
- * @return The sum result of the two numbers @p a + @p b
- */
-static inline Eina_F16p16 eina_f16p16_add(Eina_F16p16 a, Eina_F16p16 b);
-
-/**
- * @brief Calculates the substraction of two Eina_F16p16 floating point numbers
- *
- * @param a The first number
- * @param b The substracted number
- * @return The substaction result of the two numbers @p a - @p b
- */
-static inline Eina_F16p16 eina_f16p16_sub(Eina_F16p16 a, Eina_F16p16 b);
-
-/**
- * @brief Calculates the multiplication of two Eina_F16p16 floating point numbers
- *
- * @param a The first number
- * @param b The second number
- * @return The mutliplication result of the two numbers @p a * @p b
- */
-static inline Eina_F16p16 eina_f16p16_mul(Eina_F16p16 a, Eina_F16p16 b);
-
-/**
- * @brief Calculates the scale multiplication of one Eina_F16p16 floating point
- * number with an integer
- *
- * @param a The Eina_F16p16 number
- * @param b The integer value
- * @return The mutliplication result of the two numbers @p a * @p b
- */
-static inline Eina_F16p16 eina_f16p16_scale(Eina_F16p16 a, int b);
-
-/**
- * @brief Calculates the division of two Eina_F16p16 floating point numbers
- *
- * @param a The numerator number
- * @param b The denominator number
- * @return The division result of the two numbers @p a / @p b
- */
-static inline Eina_F16p16 eina_f16p16_div(Eina_F16p16 a, Eina_F16p16 b);
-
-/**
- * @brief Calculates the square root of an Eina_F16p16 floating point number
- *
- * @param a The number to calculate the square root from
- * @return The square root result for the number @p a
- */
+static inline Eina_F16p16 eina_f16p16_add(Eina_F16p16 a,
+ Eina_F16p16 b);
+static inline Eina_F16p16 eina_f16p16_sub(Eina_F16p16 a,
+ Eina_F16p16 b);
+static inline Eina_F16p16 eina_f16p16_mul(Eina_F16p16 a,
+ Eina_F16p16 b);
+static inline Eina_F16p16 eina_f16p16_scale(Eina_F16p16 a,
+ int b);
+static inline Eina_F16p16 eina_f16p16_div(Eina_F16p16 a,
+ Eina_F16p16 b);
static inline Eina_F16p16 eina_f16p16_sqrt(Eina_F16p16 a);
-
-/**
- * @brief Get the absolute value of the integer part of and Eina_F16p16 floating
- * point number
- *
- * @param a The floating point number
- * @return The positive integer part of the number @p a
- */
static inline unsigned int eina_f16p16_fracc_get(Eina_F16p16 v);
-
-/**
- * @brief Create a new Eina_F16p316 floating point number from standard 32-bit
- * integer
- *
- * @param v 32-bit integer value to convert
- * @return The value converted into Eina_F8p24 format
- */
static inline Eina_F8p24 eina_f8p24_int_from(int32_t v);
-
-/**
- * @brief Create a new standard 32-bit integer from Eina_F8p24 floating point
- * number
- *
- * @param v Eina_F8p24 value to convert
- * @return The value converted into 32-bit integer
- */
static inline int32_t eina_f8p24_int_to(Eina_F8p24 v);
-
-/**
- * @brief Create a new Eina_F8p24 floating point number from standard float
- *
- * @param v float value to convert
- * @return The value converted into Eina_F8p24 format
- */
static inline Eina_F8p24 eina_f8p24_float_from(float v);
-
-/**
- * @brief Create a new standard float from Eina_F8p24 floating point number
- *
- * @param v Eina_F8p24 value to convert
- * @return The value converted into float
- */
static inline float eina_f8p24_float_to(Eina_F8p24 v);
-/**
- * @brief Calculates the sum of two Eina_F8p24 floating point numbers
- *
- * @param a The first number
- * @param b The second number
- * @return The sum result of the two numbers @p a + @p b
- */
-static inline Eina_F8p24 eina_f8p24_add(Eina_F8p24 a, Eina_F8p24 b);
-
-/**
- * @brief Calculates the substraction of two Eina_F8p24 floating point numbers
- *
- * @param a The first number
- * @param b The substracted number
- * @return The substaction result of the two numbers @p a - @p b
- */
-static inline Eina_F8p24 eina_f8p24_sub(Eina_F8p24 a, Eina_F8p24 b);
-
-/**
- * @brief Calculates the multiplication of two Eina_F8p24 floating point numbers
- *
- * @param a The first number
- * @param b The second number
- * @return The mutliplication result of the two numbers @p a * @p b
- */
-static inline Eina_F8p24 eina_f8p24_mul(Eina_F8p24 a, Eina_F8p24 b);
-
-/**
- * @brief Calculates the scale multiplication of one Eina_F8p24 floating point
- * number with an integer
- *
- * @param a The Eina_F16p16 number
- * @param b The integer value
- * @return The mutliplication result of the two numbers @p a * @p b
- */
-static inline Eina_F8p24 eina_f8p24_scale(Eina_F8p24 a, int b);
-
-/**
- * @brief Calculates the division of two Eina_F8p24 floating point numbers
- *
- * @param a The numerator number
- * @param b The denominator number
- * @return The division result of the two numbers @p a / @p b
- */
-static inline Eina_F8p24 eina_f8p24_div(Eina_F8p24 a, Eina_F8p24 b);
-
-/**
- * @brief Calculates the square root of an Eina_F8p24 floating point number
- *
- * @param a The number to calculate the square root from
- * @return The square root result for the number @p a
- */
+static inline Eina_F8p24 eina_f8p24_add(Eina_F8p24 a,
+ Eina_F8p24 b);
+static inline Eina_F8p24 eina_f8p24_sub(Eina_F8p24 a,
+ Eina_F8p24 b);
+static inline Eina_F8p24 eina_f8p24_mul(Eina_F8p24 a,
+ Eina_F8p24 b);
+static inline Eina_F8p24 eina_f8p24_scale(Eina_F8p24 a,
+ int b);
+static inline Eina_F8p24 eina_f8p24_div(Eina_F8p24 a,
+ Eina_F8p24 b);
static inline Eina_F8p24 eina_f8p24_sqrt(Eina_F8p24 a);
-
-/**
- * @brief Get the absolute value of the integer part of and Eina_F8p24 floating
- * point number
- *
- * @param a The floating point number
- * @return The positive integer part of the number @p a
- */
static inline unsigned int eina_f8p24_fracc_get(Eina_F8p24 v);
-/**
- * @brief Converts an Eina_F16p16 floating point number into Eina_F32p32 format
- *
- * @param a The Eina_F16p16 floating point number
- * @return The converted Eina_F32p32 floating point number
- */
static inline Eina_F32p32 eina_f16p16_to_f32p32(Eina_F16p16 a);
-
-/**
- * @brief Converts an Eina_F8p24 floating point number into Eina_F32p32 format
- *
- * @param a The Eina_F8p24 floating point number
- * @return The converted Eina_F32p32 floating point number
- */
static inline Eina_F32p32 eina_f8p24_to_f32p32(Eina_F8p24 a);
-
-/**
- * @brief Converts an Eina_F32p32 floating point number into Eina_F16p16 format
- *
- * @param a The Eina_F32p32 floating point number
- * @return The converted Eina_F16p16 floating point number
- */
static inline Eina_F16p16 eina_f32p32_to_f16p16(Eina_F32p32 a);
-
-/**
- * @brief Converts an Eina_F8p24 floating point number into Eina_F16p16 format
- *
- * @param a The Eina_F8p24 floating point number
- * @return The converted Eina_F16p16 floating point number
- */
static inline Eina_F16p16 eina_f8p24_to_f16p16(Eina_F8p24 a);
-
-/**
- * @brief Converts an Eina_F32p32 floating point number into Eina_F8p24 format
- *
- * @param a The Eina_F32p32 floating point number
- * @return The converted Eina_F8p16 floating point number
- */
static inline Eina_F8p24 eina_f32p32_to_f8p24(Eina_F32p32 a);
-
-/**
- * @brief Converts an Eina_F16p16 floating point number into Eina_F8p16 format
- *
- * @param a The Eina_F16p16 floating point number
- * @return The converted Eina_F8p16 floating point number
- */
static inline Eina_F8p24 eina_f16p16_to_f8p24(Eina_F16p16 a);
#include "eina_inline_f32p32.x"
@@ -485,12 +108,4 @@ static inline Eina_F8p24 eina_f16p16_to_f8p24(Eina_F16p16 a);
#include "eina_inline_f8p24.x"
#include "eina_inline_fp.x"
-/**
- * @}
- */
-
-/**
- * @}
- */
-
#endif
diff --git a/src/lib/eina/eina_hamster.h b/src/lib/eina/eina_hamster.h
index bea759d57f..3bc58da3dd 100644
--- a/src/lib/eina/eina_hamster.h
+++ b/src/lib/eina/eina_hamster.h
@@ -1,14 +1,14 @@
/* EINA - EFL data type library
* Copyright (C) 2008 Cedric Bail
*
- * This library is free software; you can redistribute it and/or
+ * This library is a free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
@@ -20,30 +20,24 @@
#define EINA_HAMSTER_H_
/**
- * @addtogroup Eina_Hamster_Group Hamster
+ * @internal
+ * @defgroup Eina_Hamster_Group Hamster
+ * @ingroup Eina_Core_Group
*
- * @brief These functions provide hamster calls.
+ * @brief This group discusses the functions that provide hamster calls.
*
* @{
*/
-/**
- * @addtogroup Eina_Core_Group Core
- *
- * @{
- */
/**
- * @defgroup Eina_Hamster_Group Hamster
- */
-
-
-/**
- * @brief Get the hamster count.
+ * @brief Gets the hamster count.
*
- * @return The number of available hamsters.
+ * @since_tizen 2.3
*
- * This function returns how many hamsters you have.
+ * @details This function returns the number of hamsters that are available.
+ *
+ * @return The number of available hamsters
*/
EAPI int eina_hamster_count(void);
@@ -51,8 +45,4 @@ EAPI int eina_hamster_count(void);
* @}
*/
-/**
- * @}
- */
-
#endif /* EINA_HAMSTER_H_ */
diff --git a/src/lib/eina/eina_hash.h b/src/lib/eina/eina_hash.h
index 4681a47164..3e256a5b64 100644
--- a/src/lib/eina/eina_hash.h
+++ b/src/lib/eina/eina_hash.h
@@ -2,14 +2,14 @@
* Copyright (C) 2002-2008 Carsten Haitzler, Gustavo Sverzut Barbieri,
* Vincent Torri, Jorge Luis Zapata Muga, Cedric Bail
*
- * This library is free software; you can redistribute it and/or
+ * This library is a free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
@@ -24,152 +24,21 @@
#include "eina_iterator.h"
/**
- * @page hash_01_example_page Eina_Hash in action
- * @dontinclude eina_hash_01.c
- *
- * We are going to store some tuples into our table, that will map each @a name
- * to a @a number. The cost to access a given number from the name should be
- * very small, even with many entries in our table. This is the initial data:
- * @skip _Phone_Entry
- * @until // _start_entries
- *
- * Before starting to play with the hash, let's write a callback that will be
- * used to free the elements from it. Since we are just storing strduped
- * strings, we just need to free them:
- *
- * @skip static
- * @until }
- *
- * We also need a callback to iterate over the elements of the list later, so
- * we are defining it now:
- *
- * @skip Eina_Bool
- * @until }
- *
- * Now let's create our @ref Eina_Hash using @ref
- * eina_hash_string_superfast_new :
- *
- * @skip eina_init
- * @until phone_book
- *
- * Now we add the keys and data to the hash using @ref eina_hash_add . This
- * means that the key is copied inside the table, together with the pointer to
- * the data (phone numbers).
- *
- * @skip for
- * @until }
- *
- * Some basic manipulations with the hash, like finding a value given a key,
- * deleting an entry, modifying an entry are exemplified in the following lines.
- * Notice that the @ref eina_hash_modify function returns the old value stored
- * in that entry, and it needs to be freed, while the @ref eina_hash_del
- * function already calls our free callback:
- *
- * @skip Look for
- * @until free(
- *
- * The @ref eina_hash_set function can be used to set a key-value entry to the
- * table if it doesn't exist, or to modify an existent entry. It returns the old
- * entry if it was already set, and NULL otherwise. But since it will
- * return NULL on error too, we need to check if an error has occurred:
- *
- * @skip Modify
- * @until printf("\n");
- *
- * There are different ways of iterate over the entries of a hash. Here we show
- * two of them: using @ref eina_hash_foreach and @ref Eina_Iterator .
- *
- * @skip List of phones
- * @until eina_iterator_free(it);
- *
- * It's also possible to change the key for a specific entry, without having to
- * remove the entry from the table and adding it again:
- *
- * @skipline eina_hash_move
- *
- * We can remove all the elements from the table without free the table itself:
- *
- * @skip Empty the phone book
- * @until eina_hash_population
- *
- * Or free the the entire table with its content:
- *
- * @skipline eina_hash_free
- *
- *
- * The full code for this example can be seen here: @ref eina_hash_01_c
- */
-
-/**
- * @page eina_hash_01_c Hash table in action
- *
- * @include eina_hash_01.c
- * @example eina_hash_01.c
- */
-
-/**
- * @page hash_02_example_page Different types of tables
- *
- * This example shows two more types of hash tables that can be created using
- * @ref Eina_Hash . For more types, consult the reference documentation of @ref
- * eina_hash_new.
- * @include eina_hash_02.c
- * @example eina_hash_02.c
- */
-
-/**
- * @example eina_hash_03.c
- * Same example as @ref hash_01_example_page but using a "string small" hash
- * table instead of "string superfast".
- */
-
-/**
- * @example eina_hash_04.c
- * Same example as @ref hash_01_example_page but using a "string djb2" hash
- * table instead of "string superfast".
- */
-
-/**
- * @example eina_hash_05.c
- * Same example as @ref hash_01_example_page but using a "int32" hash
- * table instead of "string superfast".
- */
-
-/**
- * @example eina_hash_06.c
- * Same example as @ref hash_01_example_page but using a "int64" hash
- * table instead of "string superfast".
- */
-
-/**
- * @example eina_hash_07.c
- * Same example as @ref hash_01_example_page but using a "pointer" hash
- * table instead of "string superfast".
- */
-
-/**
- * @example eina_hash_08.c
- * This example shows the the usage of eina_hash_add(), eina_hash_add_by_hash(),
- * eina_hash_direct_add_by_hash(), eina_hash_del(), eina_hash_del_by_key_hash(),
- * eina_hash_del_by_key(), eina_hash_del_by_data(), eina_hash_find_by_hash() and
- * eina_hash_modify_by_hash().
- */
-
-/**
- * @addtogroup Eina_Hash_Group Hash Table
+ * @defgroup Eina_Hash_Group Hash Table
+ * @ingroup Eina_Containers_Group
*
- * @brief Hash table management. Useful for mapping keys to values.
+ * @brief Performs hash table management. It is useful for mapping keys to values.
*
- * The hash table is useful for when one wants to implement a table that maps
+ * The hash table is useful when one wants to implement a table that maps
* keys (usually strings) to data, and have relatively fast access time. The
* performance is proportional to the load factor of the table (number of
* elements / number of buckets). See @ref hashtable_algo for implementation
* details.
*
- * Different implementations exists depending on what kind of key will be used
- * to access the data: strings, integers, pointers, stringshared or your own.
+ * Different implementations exist depending on what kind of key is used
+ * to access the data: strings, integers, pointers, stringshared, or your own key.
*
- * Eina hash tables can copy the keys when using eina_hash_add() or not when
+ * Eina hash tables can copy keys by using eina_hash_add() or not copy by
* using eina_hash_direct_add().
*
* @section hashtable_algo Algorithm
@@ -178,46 +47,44 @@
* bucket is a pointer to a structure that is the head of a <a
* href="http://en.wikipedia.org/wiki/Red-black_tree">red-black tree</a>. The
* array can then be indexed by the [hash_of_element mod N]. The
- * hash_of_element is calculated using the hashing function, passed as
+ * hash_of_element is calculated using the hashing function, passed as a
* parameter to the @ref eina_hash_new function. N is the number of buckets
* (array positions), and is calculated based on the buckets_power_size
- * (argument of @ref eina_hash_new too). The following picture illustrates the
+ * (argument of @ref eina_hash_new too). The following picture ilustrates the
* basic idea:
*
- * @htmlonly
- * <img src="01_hash-table.png" width="500" />
- * @endhtmlonly
+ * @image html 01_hash-table.png
* @image latex 01_hash-table.eps
*
- * Adding an element to the hash table is made of:
- * @li calculating the hash for that key (using the specified hash function);
- * @li calculate the array position [hash mod N];
- * @li add the element to the rbtree on that position.
+ * Adding an element to the hash table consists of:
+ * @li Calculating the hash for that key (using the specified hash function);
+ * @li Calculating the array position [hash mod N];
+ * @li Adding the element to the rbtree at that position.
*
- * The two first steps have constant time, proportional to the hash function
- * being used. Adding the key to the rbtree will be proportional on the number
+ * The first two steps have constant time, proportional to the hash function
+ * being used. Adding the key to the rbtree is proportional to the number
* of keys on that bucket.
*
* The average cost of lookup depends on the number of keys per
- * bucket (load factor) of the table, if the distribution of keys is
+ * bucket (load factor) of the table, if the distribution of the keys is
* sufficiently uniform.
*
* @section hashtable_perf Performance
*
* As said before, the performance depends on the load factor. So trying to keep
- * the load factor as small as possible will improve the hash table performance. But
- * increasing the buckets_power_size will also increase the memory consumption.
+ * the load factor as small as possible improves the hash table performance. But
+ * increasing the buckets_power_size also increases the memory consumption.
* The default hash table creation functions already have a good number of
* buckets, enough for most cases. Particularly for strings, if just a few keys
- * (less than 30) will be added to the hash table, @ref
- * eina_hash_string_small_new should be used, since it will reduce the memory
+ * (less than 30) are added to the hash table, @ref
+ * eina_hash_string_small_new should be used, since it reduces the memory
* consumption for the buckets, and you still won't have many collisions.
* However, @ref eina_hash_string_small_new still uses the same hash calculation
- * function that @ref eina_hash_string_superfast_new, which is more complex than
+ * function that @ref eina_hash_string_superfast_new uses, which is more complex than
* @ref eina_hash_string_djb2_new. The latter has a faster hash computation
- * function, but that will imply on a not so good distribution. But if just a
- * few keys are being added, this is not a problem, it will still have not many
- * collisions and be faster to calculate the hash than in a hash created with
+ * function, but that implies to a not so good distribution. But if just a
+ * few keys are being added, this is not a problem, it still does not have many
+ * collisions and is faster in calculating the hash than when a hash is created with
* @ref eina_hash_string_small_new and @ref eina_hash_string_superfast_new.
*
* A simple comparison between them would be:
@@ -226,64 +93,30 @@
* @li @c string_small - slower hash function but less collisions - 32 buckets
* (lower memory consumption)
* @li @c string_superfast - slower hash function but less collisions - 256 buckets
- * (higher memory consumption) - not randomized, avoid it on public remote interface.
+ * (higher memory consumption)
*
* Basically for a very small number of keys (10 or less), @c djb2 should be
* used, or @c string_small if you have a restriction on memory usage. And for a
- * higher number of keys, @c string_superfast should be preferred if not used on a
- * public remote interface.
+ * higher number of keys, @c string_superfast should always be preferred.
*
* If just stringshared keys are being added, use @ref
- * eina_hash_stringshared_new. If a lot of keys will be added to the hash table
+ * eina_hash_stringshared_new. If a lot of keys are added to the hash table
* (e.g. more than 1000), then it's better to increase the buckets_power_size.
* See @ref eina_hash_new for more details.
*
* When adding a new key to a hash table, use @ref eina_hash_add or @ref
- * eina_hash_direct_add (the latter if this key is already stored elsewhere). If
+ * eina_hash_direct_add (the latter is if this key is already stored elsewhere). If
* the key may be already inside the hash table, instead of checking with
* @ref eina_hash_find and then doing @ref eina_hash_add, one can use just @ref
- * eina_hash_set (this will change the data pointed by this key if it was
+ * eina_hash_set (this changes the data pointed by this key if it is
* already present in the table).
*
- * @section hashtable_tutorial Tutorial
- *
- * These examples show many Eina_Hash functions in action:
- * <ul>
- * <li> @ref hash_01_example_page
- * <li> @ref hash_02_example_page
- * <li> Different types of hash in use:
- * <ul>
- * <li> @ref eina_hash_03.c "string small"
- * <li> @ref eina_hash_04.c "string djb2"
- * <li> @ref eina_hash_05.c "int32"
- * <li> @ref eina_hash_06.c "int64"
- * <li> @ref eina_hash_07.c "pointer"
- * </ul>
- * <li> @ref eina_hash_08.c "Different add and delete functions"
- * </ul>
- */
-
-/**
- * @addtogroup Eina_Data_Types_Group Data Types
- *
- * @{
- */
-
-/**
- * @addtogroup Eina_Containers_Group Containers
- *
- * @{
- */
-
-/**
- * @defgroup Eina_Hash_Group Hash Table
- *
* @{
*/
/**
* @typedef Eina_Hash
- * Type for a generic hash table.
+ * @brief The structure type for a generic hash table.
*/
typedef struct _Eina_Hash Eina_Hash;
@@ -309,10 +142,9 @@ struct _Eina_Hash_Tuple
* Type for a function to determine the length of a hash key.
*/
typedef unsigned int (*Eina_Key_Length)(const void *key);
-
/**
* @def EINA_KEY_LENGTH
- * @param Function The function used to calculate length of hash key.
+ * @param Function The function used to calculate the length of the hash key
*/
#define EINA_KEY_LENGTH(Function) ((Eina_Key_Length)Function)
@@ -323,7 +155,7 @@ typedef unsigned int (*Eina_Key_Length)(const void *key);
typedef int (*Eina_Key_Cmp)(const void *key1, int key1_length, const void *key2, int key2_length);
/**
* @def EINA_KEY_CMP
- * @param Function The function used to compare hash key.
+ * @param Function The function used to compare the hash key
*/
#define EINA_KEY_CMP(Function) ((Eina_Key_Cmp)Function)
@@ -334,7 +166,7 @@ typedef int (*Eina_Key_Cmp)(const void *key1, int key1_length, const vo
typedef int (*Eina_Key_Hash)(const void *key, int key_length);
/**
* @def EINA_KEY_HASH
- * @param Function The function used to hash key.
+ * @param Function The function used to hash the key.
*/
#define EINA_KEY_HASH(Function) ((Eina_Key_Hash)Function)
@@ -346,33 +178,36 @@ typedef Eina_Bool (*Eina_Hash_Foreach)(const Eina_Hash *hash, const void *key
/**
- * @brief Create a new hash table.
- *
- * @param key_length_cb The function called when getting the size of the key.
- * @param key_cmp_cb The function called when comparing the keys.
- * @param key_hash_cb The function called when getting the values.
- * @param data_free_cb The function called on each value when the hash table is
- * freed, or when an item is deleted from it. @c NULL can be passed as
- * callback.
- * @param buckets_power_size The size of the buckets.
- * @return The new hash table.
- *
- * This function creates a new hash table using user-defined callbacks
- * to manage the hash table. On failure, @c NULL is returned.
- * If @p key_cmp_cb or @p key_hash_cb
- * are @c NULL, @c NULL is returned. If @p buckets_power_size is
- * smaller or equal than 2, or if it is greater or equal than 17,
- * @c NULL is returned.
- *
- * The number of buckets created will be 2 ^ @p buckets_power_size. This means
- * that if @p buckets_power_size is 5, there will be created 32 buckets. for a
- * @p buckets_power_size of 8, there will be 256 buckets.
- *
- * Pre-defined functions are available to create a hash table. See
- * eina_hash_string_djb2_new(), eina_hash_string_superfast_new(),
- * eina_hash_string_small_new(), eina_hash_int32_new(),
- * eina_hash_int64_new(), eina_hash_pointer_new() and
- * eina_hash_stringshared_new().
+ * @brief Creates a new hash table.
+ *
+ * @details This function creates a new hash table using user-defined callbacks
+ * to manage the hash table. On failure, @c NULL is returned
+ * and #EINA_ERROR_OUT_OF_MEMORY is set. If @a key_cmp_cb or @a key_hash_cb
+ * are @c NULL, @c NULL is returned. If @a buckets_power_size is
+ * smaller than or equal to 2, or if it is greater than or equal to 17,
+ * @c NULL is returned.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks The number of buckets created are 2 ^ @a buckets_power_size. This means
+ * that if @a buckets_power_size is 5, it creates 32 buckets. For a
+ * @a buckets_power_size of 8, it creates 256 buckets.
+ *
+ * @remarks Pre-defined functions are available to create a hash table. See
+ * eina_hash_string_djb2_new(), eina_hash_string_superfast_new(),
+ * eina_hash_string_small_new(), eina_hash_int32_new(),
+ * eina_hash_int64_new(), eina_hash_pointer_new(), and
+ * eina_hash_stringshared_new().
+ *
+ * @param[in] key_length_cb The function called when getting the size of the key
+ * @param[in] key_cmp_cb The function called when comparing the keys
+ * @param[in] key_hash_cb The function called when getting the values
+ * @param[in] data_free_cb The function called on each value when the hash table is
+ * freed, or when an item is deleted from it \n
+ * @c NULL can be passed as a callback.
+ * @param[in] buckets_power_size The size of the buckets
+ * @return The new hash table
+ *
*/
EAPI Eina_Hash *eina_hash_new(Eina_Key_Length key_length_cb,
Eina_Key_Cmp key_cmp_cb,
@@ -381,124 +216,133 @@ EAPI Eina_Hash *eina_hash_new(Eina_Key_Length key_length_cb,
int buckets_power_size) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(2, 3);
/**
- * @brief Redefine the callback that clean the data of a hash
+ * @brief Redefines the callback that cleans the data of a hash.
*
- * @param hash The given hash table
- * @param data_free_cb The function called on each value when the hash
- * table is freed, or when an item is deleted from it. @c NULL can be passed as
- * callback to remove an existing callback.
+ * @since 1.1
*
- * The argument received by @p data_free_cb will be that data of the item being
- * removed.
+ * @since_tizen 2.3
*
- * @since 1.1
- * @see eina_hash_new.
+ * @remarks The argument received by @a data_free_cb is the data of the item being
+ * removed.
+ *
+ * @param[in] hash The given hash table
+ * @param[in] data_free_cb The function called on each value when the hash
+ * table is freed, or when an item is deleted from it \n
+ * @c NULL can be passed as
+ * callback to remove an existing callback.
+ *
+ * @see eina_hash_new
*/
EAPI void eina_hash_free_cb_set(Eina_Hash *hash, Eina_Free_Cb data_free_cb) EINA_ARG_NONNULL(1);
/**
- * @brief Create a new hash table using the djb2 algorithm.
+ * @brief Creates a new hash table using the djb2 algorithm.
*
- * @param data_free_cb The function called on each value when the hash table
- * is freed, or when an item is deleted from it. @c NULL can be passed as
- * callback.
- * @return The new hash table.
+ * @details This function creates a new hash table using the djb2 algorithm for
+ * table management and strcmp() to compare the keys. Values can then
+ * be looked up with pointers other than the original key pointer that
+ * is used to add values. On failure, this function returns @c NULL.
*
- * This function creates a new hash table using the djb2 algorithm for
- * table management and strcmp() to compare the keys. Values can then
- * be looked up with pointers other than the original key pointer that
- * was used to add values. On failure, this function returns @c NULL.
+ * @since_tizen 2.3
+ *
+ * @param[in] data_free_cb The function called on each value when the hash table
+ * is freed, or when an item is deleted from it \n
+ * @c NULL can be passed as a callback.
+ *
+ * @return The new hash table
*/
EAPI Eina_Hash *eina_hash_string_djb2_new(Eina_Free_Cb data_free_cb);
/**
- * @brief Create a new hash table for use with strings.
+ * @brief Creates a new hash table for use with strings.
*
- * @param data_free_cb The function called on each value when the hash table
- * is freed, or when an item is deleted from it. @c NULL can be passed as
- * callback.
- * @return The new hash table.
+ * @details This function creates a new hash table using the superfast algorithm
+ * for table management and strcmp() to compare the keys. Values can
+ * then be looked up with pointers other than the original key pointer
+ * that is used to add values. On failure, this function returns
+ * @c NULL.
*
- * This function creates a new hash table using the superfast algorithm
- * for table management and strcmp() to compare the keys. Values can
- * then be looked up with pointers other than the original key pointer
- * that was used to add values. On failure, this function returns
- * @c NULL.
+ * @since_tizen 2.3
*
- * NOTE: don't use this kind of hash when their is a possibility to remotely
- * request and push data in it. This hash is subject to denial of service.
+ * @param[in] data_free_cb The function called on each value when the hash table
+ * is freed, or when an item is deleted from it \n
+ * @c NULL can be passed as a callback.
+ * @return The new hash table
*/
EAPI Eina_Hash *eina_hash_string_superfast_new(Eina_Free_Cb data_free_cb);
/**
- * @brief Create a new hash table for use with strings with small bucket size.
- *
- * @param data_free_cb The function called on each value when the hash table
- * is freed, or when an item is deleted from it. @c NULL can be passed as
- * callback.
- * @return The new hash table.
- *
- * This function creates a new hash table using the superfast algorithm
- * for table management and strcmp() to compare the keys, but with a
- * smaller bucket size (compared to eina_hash_string_superfast_new())
- * which will minimize the memory used by the returned hash
- * table. Values can then be looked up with pointers other than the
- * original key pointer that was used to add values. On failure, this
- * function returns @c NULL.
+ * @brief Creates a new hash table for use with strings having a small bucket size.
+ *
+ * @details This function creates a new hash table using the superfast algorithm
+ * for table management and strcmp() to compare the keys, but with a
+ * smaller bucket size (compared to eina_hash_string_superfast_new()),
+ * which minimizes the memory used by the returned hash
+ * table. Values can then be looked up with pointers other than the
+ * original key pointer that is used to add values. On failure, this
+ * function returns @c NULL.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] data_free_cb The function called on each value when the hash table
+ * is freed, or when an item is deleted from it \n
+ * @c NULL can be passed as a callback.
+ * @return The new hash table
*/
EAPI Eina_Hash *eina_hash_string_small_new(Eina_Free_Cb data_free_cb);
/**
- * @brief Create a new hash table for use with 32bit integers.
- *
- * @param data_free_cb The function called on each value when the hash table
- * is freed, or when an item is deleted from it. @c NULL can be passed as
- * callback.
- * @return The new hash table.
- *
- * This function creates a new hash table where keys are 32bit integers.
- * When adding or looking up in the hash table, pointers to 32bit integers
- * must be passed. They can be addresses on the stack if you let the
- * eina_hash copy the key. Values can then
- * be looked up with pointers other than the original key pointer that was
- * used to add values. This method is not suitable to match string keys as
- * it would only match the first character.
- * On failure, this function returns @c NULL.
+ * @brief Creates a new hash table for use with 32 bit integers.
+ *
+ * @details This function creates a new hash table where keys are 32 bit integers.
+ * When adding or looking up in the hash table, pointers to 32 bit integers
+ * must be passed. They can be addresses on the stack if you let
+ * eina_hash copy the key. Values can then
+ * be looked up with pointers other than the original key pointer that is
+ * used to add values. This method is not suitable to match string keys as
+ * it would only match the first character.
+ * On failure, this function returns @c NULL.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] data_free_cb The function called on each value when the hash table
+ * is freed, or when an item is deleted from it \n
+ * @c NULL can be passed as a callback.
+ * @return The new hash table
+ *
*/
EAPI Eina_Hash *eina_hash_int32_new(Eina_Free_Cb data_free_cb);
/**
- * @brief Create a new hash table for use with 64bit integers.
- *
- * @param data_free_cb The function called on each value when the hash table
- * is freed, or when an item is deleted from it. @c NULL can be passed as
- * callback.
- * @return The new hash table.
- *
- * This function creates a new hash table where keys are 64bit integers.
- * When adding or looking up in the hash table, pointers to 64bit integers
- * must be passed. They can be addresses on the stack. Values can then
- * be looked up with pointers other than the original key pointer that was
- * used to add values. This method is not suitable to match string keys as
- * it would only match the first character.
- * On failure, this function returns @c NULL.
+ * @brief Creates a new hash table for use with 64 bit integers.
+ *
+ * @details This function creates a new hash table where keys are 64 bit integers.
+ * When adding or looking up in the hash table, pointers to 64 bit integers
+ * must be passed. They can be addresses on the stack. Values can then
+ * be looked up with pointers other than the original key pointer that is
+ * used to add values. This method is not suitable to match string keys as
+ * it would only match the first character.
+ * On failure, this function returns @c NULL.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] data_free_cb The function called on each value when the hash table
+ * is freed, or when an item is deleted from it \n
+ * @c NULL can be passed as a callback.
+ * @return The new hash table
+ *
*/
EAPI Eina_Hash *eina_hash_int64_new(Eina_Free_Cb data_free_cb);
/**
- * @brief Create a new hash table for use with pointers.
- *
- * @param data_free_cb The function called on each value when the hash table
- * is freed, or when an item is deleted from it. @c NULL can be passed as
- * callback.
- * @return The new hash table.
+ * @brief Creates a new hash table for use with pointers.
*
- * This function creates a new hash table using the int64/int32 algorithm for
- * table management and dereferenced pointers to compare the
- * keys. Values can then be looked up with pointers other than the
- * original key pointer that was used to add values. This method may
- * appear to be able to match string keys, actually it only matches
- * the first character. On failure, this function returns @c NULL.
+ * @details This function creates a new hash table using the int64/int32 algorithm for
+ * table management and dereferenced pointers to compare the
+ * keys. Values can then be looked up with pointers other than the
+ * original key pointer that is used to add values. This method may
+ * appear to be able to match string keys, actually it only matches
+ * the first character. On failure, this function returns @c NULL.
*
* @code
* // For a hash that will have only one pointer to each structure
@@ -508,23 +352,28 @@ EAPI Eina_Hash *eina_hash_int64_new(Eina_Free_Cb data_free_cb);
* if (!eina_hash_find(hash, &data))
* eina_hash_add(hash, &data, data);
* @endcode
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] data_free_cb The function called on each value when the hash table
+ * is freed, or when an item is deleted from it \n
+ * @c NULL can be passed as a callback.
+ * @return The new hash table
+ *
*/
EAPI Eina_Hash *eina_hash_pointer_new(Eina_Free_Cb data_free_cb);
/**
- * @brief Create a new hash table optimized for stringshared values.
+ * @brief Creates a new hash table optimized for stringshared values.
*
- * @param data_free_cb The function called on each value when the hash table
- * is freed, or when an item is deleted from it. @c NULL can be passed as
- * callback.
- * @return The new hash table.
+ * @details This function creates a new hash table optimized for stringshared
+ * values. Values CANNOT be looked up with pointers not
+ * equal to the original key pointer that is used to add a value. On failure,
+ * this function returns @c NULL.
*
- * This function creates a new hash table optimized for stringshared
- * values. Values CAN NOT be looked up with pointers not
- * equal to the original key pointer that was used to add a value. On failure,
- * this function returns @c NULL.
+ * @since_tizen 2.3
*
- * Excerpt of code that will NOT work with this type of hash:
+ * An Excerpt of a code that does NOT work with this type of hash:
*
* @code
* extern Eina_Hash *hash;
@@ -532,173 +381,208 @@ EAPI Eina_Hash *eina_hash_pointer_new(Eina_Free_Cb data_free_cb);
* const char *a = eina_stringshare_add("key");
*
* eina_hash_add(hash, a, value);
- * eina_hash_find(hash, "key");
+ * eina_hash_find(hash, "key")
* @endcode
+ *
+ * @param[in] data_free_cb The function called on each value when the hash table
+ * is freed, or when an item is deleted from it \n
+ * @c NULL can be passed as a callback.
+ * @return The new hash table
+ *
*/
EAPI Eina_Hash *eina_hash_stringshared_new(Eina_Free_Cb data_free_cb);
/**
- * @brief Add an entry to the given hash table.
- *
- * @param hash The given hash table. Cannot be @c NULL.
- * @param key A unique key. Cannot be @c NULL.
- * @param data Data to associate with the string given by @p key. Cannot be @c
- * NULL.
- * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
- *
- * This function adds @p key to @p hash. @p key is
- * expected to be unique within the hash table. Key uniqueness varies
- * depending on the type of @p hash: a stringshared @ref Eina_Hash
- * need to have unique pointers (which implies unique strings).
- * All other string hash types require the strings
- * themselves to be unique. Pointer, int32 and int64 hashes need to have these
- * values as unique. Failure to use sufficient uniqueness will
- * result in unexpected results when inserting data pointers accessed
- * with eina_hash_find(), and removed with eina_hash_del(). Key
- * strings are case sensitive. This function returns #EINA_FALSE if an error
- * occurred, #EINA_TRUE otherwise.
+ * @brief Adds an entry to the given hash table.
+ *
+ * @details This function adds @a key to @a hash. @a key is
+ * expected to be unique within the hash table. The key's uniqueness varies
+ * depending on the type of @a hash: a stringshared @ref Eina_Hash
+ * needs to have unique pointers (which implies unique strings).
+ * All other string hash types require the strings
+ * themselves to be unique. Pointer, int32 and int64 hashes need to have these
+ * values as unique. Failure to use sufficient uniqueness
+ * results in unexpected results when inserting data pointers accessed
+ * by eina_hash_find() and removed by eina_hash_del().
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Key strings are case sensitive. If an error occurs, eina_error_get()
+ * should be used to determine if an allocation error occurred during
+ * this function. This function returns @c EINA_FALSE if an error
+ * occurs, otherwise it returns @c EINA_TRUE.
+ *
+ * @param[in] hash The given hash table \n
+ * It cannot be @c NULL.
+ * @param[in] key A unique key \n
+ * It cannot be @c NULL.
+ * @param[in] data The data to associate with the string given by @a key \n
+ * It cannot be @c NULL.
+ * @return @c EINA_FALSE if an error occurs, otherwise @c EINA_TRUE
+ *
*/
EAPI Eina_Bool eina_hash_add(Eina_Hash *hash,
const void *key,
const void *data) EINA_ARG_NONNULL(1, 2, 3);
/**
- * @brief Add an entry to the given hash table without duplicating the string
- * key.
- *
- * @param hash The given hash table. Cannot be @c NULL.
- * @param key A unique key. Cannot be @c NULL.
- * @param data Data to associate with the string given by @p key. Cannot be @c
- * NULL
- * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
- *
- * This function adds @p key to @p hash. @p key is
- * expected to be unique within the hash table. Key uniqueness varies
- * depending on the type of @p hash: a stringshared @ref Eina_Hash
- * need have unique pointers (which implies unique strings).
- * All other string hash types require the strings
- * themselves to be unique. Pointer, int32 and int64 hashes need to have these
- * values as unique. Failure to use sufficient uniqueness will
- * result in unexpected results when inserting data pointers accessed
- * with eina_hash_find(), and removed with eina_hash_del(). This
- * function does not make a copy of @p key, so it must be a string
- * constant or stored elsewhere ( in the object being added). Key
- * strings are case sensitive. This function returns #EINA_FALSE if an error
- * occurred, #EINA_TRUE otherwise.
+ * @brief Adds an entry to the given hash table without duplicating the string
+ * key.
+ *
+ * @details This function adds @a key to @a hash. @a key is
+ * expected to be unique within the hash table. The key's uniqueness varies
+ * depending on the type of @a hash: a stringshared @ref Eina_Hash
+ * needs to have unique pointers (which implies unique strings).
+ * All other string hash types require the strings
+ * themselves to be unique. Pointer, int32 and int64 hashes need to have these
+ * values as unique. Failure to use sufficient uniqueness
+ * results in unexpected results when inserting data pointers accessed
+ * by eina_hash_find() and removed by eina_hash_del().
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This function does not make a copy of @a key, so it must be a string
+ * constant or should be stored elsewhere (in the object being added). Key
+ * strings are case sensitive. If an error occurs, eina_error_get()
+ * should be used to determine if an allocation error occurred during
+ * this function. This function returns @c EINA_FALSE if an error
+ * occurs, otherwise @c EINA_TRUE.
+ *
+ * @param[in] hash The given hash table \n
+ * It cannot be @c NULL.
+ * @param[in] key A unique key \n
+ * It cannot be @c NULL.
+ * @param[in] data The data to associate with the string given by @a key \n
+ * It cannot be @c NULL.
+ * @return @c EINA_FALSE if an error occurs, ptherwise @c EINA_TRUE
+ *
*/
EAPI Eina_Bool eina_hash_direct_add(Eina_Hash *hash,
const void *key,
const void *data) EINA_ARG_NONNULL(1, 2, 3);
/**
- * @brief Remove the entry identified by a key or a data from the given
- * hash table.
- *
- * @param hash The given hash table.
- * @param key The key.
- * @param data The data pointer to remove if the key is @c NULL.
- * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
- *
- * This function removes the entry identified by @p key or @p data
- * from @p hash. If a free function was given to the
- * callback on creation, it will be called for the data being
- * deleted. If @p hash is @c NULL, the functions returns immediately #EINA_FALSE.
- * If @p key is @c NULL, then @p data is used to find the a
- * match to remove, otherwise @p key is used and @p data is not
- * required and can be @c NULL. This function returns #EINA_FALSE if
- * an error occurred, #EINA_TRUE otherwise.
- *
- * @note if you know you already have the key, use
- * eina_hash_del_by_key() or eina_hash_del_by_key_hash(). If you
- * know you don't have the key, use eina_hash_del_by_data()
- * directly.
+ * @brief Removes the entry identified by a key or data from the given
+ * hash table.
+ *
+ * @details This function removes the entry identified by @a key or @a data
+ * from @a hash. If a free function is given to the
+ * callback on creation, it is called for the data being
+ * deleted. If @a hash is @c NULL, the functions returns @c EINA_FALSE immediately.
+ * If @a key is @c NULL, then @a data is used to find the
+ * match to remove, otherwise @a key is used and @a data is not
+ * required and can be @c NULL. This function returns @c EINA_FALSE if
+ * an error occurs, otherwise it returns EINA_TRUE.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks If you already have the key, use
+ * eina_hash_del_by_key() or eina_hash_del_by_key_hash(). If you
+ * don't have the key, use eina_hash_del_by_data() directly.
+ *
+ * @param[in] hash The given hash table
+ * @param[in] key The key
+ * @param[in] data The data pointer to remove if the key is @c NULL
+ * @return @c EINA_FALSE if an error occurs, otherwise @c EINA_TRUE
+ *
*/
EAPI Eina_Bool eina_hash_del(Eina_Hash *hash,
const void *key,
const void *data) EINA_ARG_NONNULL(1);
/**
- * @brief Retrieve a specific entry in the given hash table.
+ * @brief Finds a specific entry in the given hash table.
*
- * @param hash The given hash table.
- * @param key The key of the entry to find.
- * @return The data pointer for the stored entry on success, @c NULL
- * otherwise.
+ * @details This function retrieves the entry associated to @a key in
+ * @a hash. If @a hash is @c NULL, this function returns
+ * @c NULL immediately. This function returns the data pointer on success,
+ * otherwise it returns @c NULL.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] hash The given hash table
+ * @param[in] key The key of the entry to find
+ * @return The data pointer for the stored entry on success, otherwise @c NULL
*
- * This function retrieves the entry associated to @p key in
- * @p hash. If @p hash is @c NULL, this function returns immediately
- * @c NULL. This function returns the data pointer on success, @c NULL
- * otherwise.
*/
EAPI void *eina_hash_find(const Eina_Hash *hash,
const void *key) EINA_ARG_NONNULL(2);
/**
- * @brief Modify the entry pointer at the specified key and return the old
- * entry.
- * @param hash The given hash table.
- * @param key The key of the entry to modify.
- * @param data The data to replace the old entry.
- * @return The data pointer for the old stored entry on success, or
- * @c NULL otherwise.
- *
- * This function modifies the data of @p key with @p data in @p
- * hash. If no entry is found, nothing is added to @p hash. On success
- * this function returns the old entry, otherwise it returns @c NULL.
+ * @brief Modifies the entry pointer at the specified key and returns the old
+ * entry.
+ *
+ * @details This function modifies the data of @a key with @a data in @a
+ * hash. If no entry is found, nothing is added to @a hash. On success
+ * this function returns the old entry, otherwise it returns @c NULL.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] hash The given hash table
+ * @param[in] key The key of the entry to modify
+ * @param[in] data The data used to replace the old entry
+ * @return The data pointer for the old stored entry on success,
+ * otherwise @c NULL
*/
EAPI void *eina_hash_modify(Eina_Hash *hash,
const void *key,
const void *data) EINA_ARG_NONNULL(1, 2, 3);
/**
- * @brief Modify the entry pointer at the specified key and return the
- * old entry or add the entry if not found.
- *
- * @param hash The given hash table.
- * @param key The key of the entry to modify.
- * @param data The data to replace the old entry
- * @return The data pointer for the old stored entry, or @c NULL
- * otherwise.
- *
- * This function modifies the data of @p key with @p data in @p
- * hash. If no entry is found, @p data is added to @p hash with the
- * key @p key. On success this function returns the old entry,
- * otherwise it returns @c NULL.
+ * @brief Modifies the entry pointer at the specified key and returns the
+ * old entry or adds the entry if not found.
+ *
+ * @details This function modifies the data of @a key with @a data in @a
+ * hash. If no entry is found, @a data is added to @a hash with the
+ * key @a key. On success, this function returns the old entry,
+ * otherwise it returns @c NULL. To check for errors, use
+ * eina_error_get().
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] hash The given hash table
+ * @param[in] key The key of the entry to modify
+ * @param[in] data The data used to replace the old entry
+ * @return The data pointer for the old stored entry on success,
+ * otherwise @c NULL
*/
EAPI void *eina_hash_set(Eina_Hash *hash,
const void *key,
const void *data) EINA_ARG_NONNULL(1, 2);
/**
- * @brief Change the key associated with a data without triggering the
- * free callback.
+ * @brief Changes the key associated with the data without triggering the
+ * free callback.
*
- * @param hash The given hash table.
- * @param old_key The current key associated with the data
- * @param new_key The new key to associate data with
- * @return #EINA_FALSE in any case but success, #EINA_TRUE on success.
+ * @details This function allows for the move of data from one key to another,
+ * but does not call the Eina_Free_Cb associated with the hash table
+ * when destroying the old key.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] hash The given hash table
+ * @param[in] old_key The current key associated with the data
+ * @param[in] new_key The new key to associate the data with
+ * @return @c EINA_FALSE in any case but success, otherwise @c EINA_TRUE on success
*
- * This function allows for the move of data from one key to another,
- * but does not call the Eina_Free_Cb associated with the hash table
- * when destroying the old key.
*/
EAPI Eina_Bool eina_hash_move(Eina_Hash *hash,
const void *old_key,
const void *new_key) EINA_ARG_NONNULL(1, 2, 3);
/**
- * Free the given hash table resources.
+ * @brief Frees the given hash table resources.
*
- * @param hash The hash table to be freed.
+ * @details This function frees up all the memory allocated to storing @a hash,
+ * and calls the free callback if it has been passed to the hash table
+ * at creation time. If no free callback has been passed, any entries
+ * in the table that the program has no more pointers for elsewhere
+ * may now be lost, so this should only be called if the program has
+ * already freed any allocated data in the hash table or has
+ * pointers for data in the table stored elsewhere as well. If @a hash
+ * is @c NULL, the function returns immediately.
*
- * This function frees up all the memory allocated to storing @p hash,
- * and call the free callback if it has been passed to the hash table
- * at creation time. If no free callback has been passed, any entries
- * in the table that the program has no more pointers for elsewhere
- * may now be lost, so this should only be called if the program has
- * already freed any allocated data in the hash table or has the
- * pointers for data in the table stored elsewhere as well. If @p hash
- * is @c NULL, the function returns immediately.
+ * @since_tizen 2.3
*
* Example:
* @code
@@ -707,55 +591,70 @@ EAPI Eina_Bool eina_hash_move(Eina_Hash *hash,
* eina_hash_free(hash);
* hash = NULL;
* @endcode
+ *
+ * @param[in] hash The hash table to be freed
+ *
*/
EAPI void eina_hash_free(Eina_Hash *hash) EINA_ARG_NONNULL(1);
/**
- * Free the given hash table buckets resources.
+ * @brief Frees the given hash table buckets resources.
+ *
+ * @details This function frees up all the memory allocated to storing the
+ * buckets of @a hash, and calls the free callback on all hash table
+ * buckets if it has been passed to the hash table at creation time,
+ * it then frees the buckets. If no free callback has been passed, no
+ * buckets value are freed. If @a hash is @c NULL, the function
+ * returns immediately.
+ *
+ * @since_tizen 2.3
*
- * @param hash The hash table whose buckets have to be freed.
+ * @param[in] hash The hash table whose buckets have to be freed
*
- * This function frees up all the memory allocated to storing the
- * buckets of @p hash, and calls the free callback on all hash table
- * buckets if it has been passed to the hash table at creation time,
- * then frees the buckets. If no free callback has been passed, no
- * buckets value will be freed. If @p hash is @c NULL, the function
- * returns immediately.
*/
EAPI void eina_hash_free_buckets(Eina_Hash *hash) EINA_ARG_NONNULL(1);
/**
* @brief Returns the number of entries in the given hash table.
*
- * @param hash The given hash table.
- * @return The number of entries in the hash table.
+ * @details This function returns the number of entries in @a hash, or @c 0 on
+ * error. If @a hash is @c NULL, @c 0 is returned.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] hash The given hash table
+ * @return The number of entries in the hash table
*
- * This function returns the number of entries in @p hash, or 0 on
- * error. If @p hash is @c NULL, @c 0 is returned.
*/
EAPI int eina_hash_population(const Eina_Hash *hash) EINA_ARG_NONNULL(1);
/**
- * @brief Add an entry to the given hash table.
- *
- * @param hash The given hash table. Cannot be @c NULL.
- * @param key A unique key. Cannot be @c NULL.
- * @param key_length The length of the key.
- * @param key_hash The hash that will always match key.
- * @param data The data to associate with the string given by the key. Cannot be
- * @c NULL.
- * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
- *
- * This function adds @p key to @p hash. @p hash, @p key and @p data
- * cannot be @c NULL, in that case #EINA_FALSE is returned. @p key is
- * expected to be a unique within the hash table. Otherwise,
- * one cannot be sure which inserted data pointer will be accessed
- * with @ref eina_hash_find, and removed with @ref eina_hash_del. Do
- * not forget to count '\\0' for string when setting the value of
- * @p key_length. @p key_hash is expected to always match
- * @p key. Otherwise, one cannot be sure to find it again with @ref
- * eina_hash_find_by_hash. Key strings are case sensitive. This function
- * returns #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
+ * @brief Adds an entry to the given hash table.
+ *
+ * @details This function adds @a key to @a hash. @a hash, @a key, and @a data
+ * cannot be @c NULL, in that case @c EINA_FALSE is returned. @a key is
+ * expected to be unique within the hash table. Otherwise,
+ * one cannot be sure which inserted data pointer is accessed
+ * by @ref eina_hash_find, and removed by @ref eina_hash_del. Do
+ * not forget to count '\\0' for string when setting the value of
+ * @a key_length. @a key_hash is expected to always match
+ * @a key. Otherwise, one cannot be sure to find it again with @ref
+ * eina_hash_find_by_hash. Key strings are case sensitive. If an error
+ * occurs, eina_error_get() should be used to determine if an
+ * allocation error occurred during this function. This function
+ * returns @c EINA_FALSE if an error occurs, otherwise it returns @c EINA_TRUE.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] hash The given hash table \n
+ * It cannot be @c NULL.
+ * @param[in] key A unique key \n
+ * It cannot be @c NULL.
+ * @param[in] key_length The length of the key
+ * @param[in] key_hash The hash that always matches the key
+ * @param[in] data The data to associate with the string given by the key \n
+ * It cannot be @c NULL.
+ * @return @c EINA_FALSE if an error occurs, otherwise @c EINA_TRUE
*
* @see eina_hash_add()
*/
@@ -766,30 +665,36 @@ EAPI Eina_Bool eina_hash_add_by_hash(Eina_Hash *hash,
const void *data) EINA_ARG_NONNULL(1, 2, 5);
/**
- * @brief Add an entry to the given hash table and do not duplicate the string
- * key.
- *
- * @param hash The given hash table. Cannot be @c NULL.
- * @param key A unique key. Cannot be @c NULL.
- * @param key_length Should be the length of @p key (don't forget to count
- * '\\0' for string).
- * @param key_hash The hash that will always match key.
- * @param data Data to associate with the string given by @p key. Cannot be @c
- * NULL.
- * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
- *
- * This function adds @p key to @p hash. @p hash, @p key and @p data
- * can be @c NULL, in that case #EINA_FALSE is returned. @p key is
- * expected to be unique within the hash table. Otherwise,
- * one cannot be sure which inserted data pointer will be accessed
- * with @ref eina_hash_find, and removed with @ref eina_hash_del. This
- * function does not make a copy of @p key so it must be a string
- * constant or stored elsewhere (in the object being added). Do
- * not forget to count '\\0' for string when setting the value of
- * @p key_length. @p key_hash is expected to always match
- * @p key. Otherwise, one cannot be sure to find it again with @ref
- * eina_hash_find_by_hash. Key strings are case sensitive. This function
- * returns #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
+ * @brief Adds an entry to the given hash table and does not duplicate the string
+ * key.
+ *
+ * @details This function adds @a key to @a hash. @a hash, @a key, and @a data
+ * can be @c NULL, in that case @c EINA_FALSE is returned. @a key is
+ * expected to be unique within the hash table. Otherwise,
+ * one cannot be sure which inserted data pointer is going to be accessed
+ * by @ref eina_hash_find, and removed by @ref eina_hash_del. This
+ * function does not make a copy of @a key so it must be a string
+ * constant or should be stored elsewhere (in the object being added). Do
+ * not forget to count '\\0' for string when setting the value of
+ * @a key_length. @a key_hash is expected to always match
+ * @a key. Otherwise, one cannot be sure to find it again with @ref
+ * eina_hash_find_by_hash. Key strings are case sensitive. If an error
+ * occurs, eina_error_get() should be used to determine if an
+ * allocation error occurred during this function. This function
+ * returns @c EINA_FALSE if an error occurs, otherwise it returns @c EINA_TRUE.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] hash The given hash table \n
+ * It cannot be @c NULL.
+ * @param[in] key A unique key \n
+ * It cannot be @c NULL.
+ * @param[in] key_length The length of @a key (don't forget to count
+ * '\\0' for string).
+ * @param[in] key_hash The hash that always matches the key.
+ * @param[in] data The data to associate with the string given by @a key \n
+ * It cannot be @c NULL.
+ * @return @c EINA_FALSE if an error occurs, otherwise @c EINA_TRUE
*
* @see eina_hash_direct_add()
*/
@@ -800,25 +705,29 @@ EAPI Eina_Bool eina_hash_direct_add_by_hash(Eina_Hash *hash,
const void *data) EINA_ARG_NONNULL(1, 2, 5);
/**
- * @brief Remove the entry identified by a key and a key hash from the given
- * hash table.
- *
- * @param hash The given hash table. Cannot be @c NULL.
- * @param key The key. Cannot be @c NULL.
- * @param key_length The length of the key.
- * @param key_hash The hash that always match the key.
- * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
- *
- * This function removes the entry identified by @p key and
- * @p key_hash from @p hash. If a free function was given to the
- * callback on creation, it will be called for the data being
- * deleted. Do not forget to count '\\0' for string when setting the
- * value of @p key_length. If @p hash or @p key are @c NULL, the
- * functions returns immediately #EINA_FALSE. This function
- * returns #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
- *
- * @note if you don't have the key_hash, use eina_hash_del_by_key() instead.
- * @note if you don't have the key, use eina_hash_del_by_data() instead.
+ * @brief Removes the entry identified by a key and a key hash from the given
+ * hash table.
+ *
+ * @details This function removes the entry identified by @a key and
+ * @a key_hash from @a hash. If a free function is given to the
+ * callback on creation, it is called for the data being
+ * deleted. Do not forget to count '\\0' for string when setting the
+ * value of @a key_length. If @a hash or @a key is @c NULL, the
+ * functions return @c EINA_FALSE immediately. This function
+ * returns @c EINA_FALSE if an error occurs, otherwise it returns @c EINA_TRUE.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks If you don't have the key_hash, use eina_hash_del_by_key() instead.
+ * @remarks If you don't have the key, use eina_hash_del_by_data() instead.
+ *
+ * @param[in] hash The given hash table \n
+ * It cannot be @c NULL.
+ * @param[in] key The key \n
+ * It cannot be @c NULL.
+ * @param[in] key_length The length of the key
+ * @param[in] key_hash The hash that always matches the key
+ * @return @c EINA_FALSE if an error occurs, otherwise @c EINA_TRUE
*/
EAPI Eina_Bool eina_hash_del_by_key_hash(Eina_Hash *hash,
const void *key,
@@ -826,81 +735,92 @@ EAPI Eina_Bool eina_hash_del_by_key_hash(Eina_Hash *hash,
int key_hash) EINA_ARG_NONNULL(1, 2);
/**
- * @brief Remove the entry identified by a key from the given hash table.
- *
- * This version will calculate key length and hash by using functions
- * provided to hash creation function.
- *
- * @param hash The given hash table. Cannot be @c NULL.
- * @param key The key. Cannot be @c NULL.
- * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
- *
- * This function removes the entry identified by @p key from @p
- * hash. The key length and hash will be calculated automatically by
- * using functiond provided to has creation function. If a free
- * function was given to the callback on creation, it will be called
- * for the data being deleted. If @p hash or @p key are @c NULL, the
- * functions returns immediately #EINA_FALSE. This function
- * returns #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
- *
- * @note if you already have the key_hash, use eina_hash_del_by_key_hash()
- * instead.
- * @note if you don't have the key, use eina_hash_del_by_data() instead.
+ * @brief Removes the entry identified by a key from the given hash table.
+ *
+ * @details This function removes the entry identified by @a key from @a
+ * hash. The key length and hash is calculated automatically by
+ * using functions provided to the hash creation function. If a free
+ * function is given to the callback on creation, it is called
+ * for the data being deleted. If @a hash or @a key is @c NULL, the
+ * functions return @c EINA_FALSE immediately. This function
+ * returns @c EINA_FALSE if an error occurs, otherwise it returns @c EINA_TRUE.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks If you already have the key_hash, use eina_hash_del_by_key_hash()
+ * instead.
+ * @remarks If you don't have the key, use eina_hash_del_by_data() instead.
+ *
+ * @remarks This version calculates the key length and hash by using functions
+ * provided to the hash creation function.
+ *
+ * @param[in] hash The given hash table \n
+ * It cannot be @c NULL.
+ * @param[in] key The key \n
+ * It cannot be @c NULL.
+ * @return @c EINA_FALSE if an error occurs, otherwise @c EINA_TRUE
+ *
*/
EAPI Eina_Bool eina_hash_del_by_key(Eina_Hash *hash,
const void *key) EINA_ARG_NONNULL(1, 2);
/**
- * @brief Remove the entry identified by a data from the given hash table.
+ * @brief Removes the entry identified by data from the given hash table.
*
- * This version is slow since there is no quick access to nodes based on data.
+ * @details This function removes the entry identified by @a data from @a
+ * hash. If a free function is given to the callback on creation, it
+ * is called for the data being deleted. If @a hash or @a data
+ * is @c NULL, the functions return @c EINA_FALSE immediately. This
+ * function returns @c EINA_FALSE if an error occurs, otherwise it returns @c EINA_TRUE.
*
- * @param hash The given hash table. Cannot be @c NULL.
- * @param data The data value to search and remove. Cannot be @c NULL.
- * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
- * thing goes fine.
+ * @since_tizen 2.3
*
- * This function removes the entry identified by @p data from @p
- * hash. If a free function was given to the callback on creation, it
- * will be called for the data being deleted. If @p hash or @p data
- * are @c NULL, the functions returns immediately #EINA_FALSE. This
- * function returns #EINA_FALSE if an error occurred, #EINA_TRUE
- * otherwise.
+ * @remarks If you already have the key, use eina_hash_del_by_key() or
+ * eina_hash_del_by_key_hash() instead.
*
- * @note if you already have the key, use eina_hash_del_by_key() or
- * eina_hash_del_by_key_hash() instead.
+ * @remarks This version is slow since there is no quick access to nodes based on the data.
+ *
+ * @param[in] hash The given hash table \n
+ * It cannot be @c NULL.
+ * @param[in] data The data value to search and remove \n
+ * It cannot be @c NULL.
+ * @return @c EINA_FALSE if an error occurs, otherwise @c EINA_TRUE on success
*/
EAPI Eina_Bool eina_hash_del_by_data(Eina_Hash *hash,
const void *data) EINA_ARG_NONNULL(1, 2);
/**
- * @brief Remove the entry identified by a key and a key hash or a
- * data from the given hash table.
- *
- * If @p key is @c NULL, then @p data is used to find a match to
- * remove.
- *
- * @param hash The given hash table. Cannot be @c NULL.
- * @param key The key.
- * @param key_length The length of the key.
- * @param key_hash The hash that always match the key.
- * @param data The data pointer to remove if the key is @c NULL.
- * @return #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
- *
- * This function removes the entry identified by @p key and
- * @p key_hash, or @p data, from @p hash. If a free function was given to
- * the callback on creation, it will be called for the data being
- * deleted. If @p hash is @c NULL, the functions returns immediately #EINA_FALSE.
- * If @p key is @c NULL, then @p key_length and @p key_hash
- * are ignored and @p data is used to find a match to remove,
- * otherwise @p key and @p key_hash are used and @p data is not
- * required and can be @c NULL. Do not forget to count '\\0' for
- * string when setting the value of @p key_length. This function
- * returns #EINA_FALSE if an error occurred, #EINA_TRUE otherwise.
- *
- * @note if you know you already have the key, use eina_hash_del_by_key_hash(),
- * if you know you don't have the key, use eina_hash_del_by_data()
- * directly.
+ * @brief Removes the entry identified by a key and a key hash or the
+ * data from the given hash table.
+ *
+ * @details This function removes the entry identified by @a key and
+ * @a key_hash, or @a data, from @a hash. If a free function is given to
+ * the callback on creation, it is called for the data being
+ * deleted. If @a hash is @c NULL, the functions return @c EINA_FALSE immediately.
+ * If @a key is @c NULL, then @a key_length and @a key_hash
+ * are ignored and @a data is used to find a match to remove,
+ * otherwise @a key and @a key_hash are used and @a data is not
+ * required and can be @c NULL. Do not forget to count '\\0' for
+ * string when setting the value of @a key_length. This function
+ * returns @c EINA_FALSE if an error occurs, otherwise it returns @c EINA_TRUE.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks If you already have the key, use eina_hash_del_by_key_hash().
+ * If you don't have the key, use eina_hash_del_by_data()
+ * directly.
+ *
+ * @remarks If @a key is @c NULL, then @a data is used to find a match to
+ * remove.
+ *
+ * @param[in] hash The given hash table \n
+ * It cannot be @c NULL.
+ * @param[in] key The key
+ * @param[in] key_length The length of the key
+ * @param[in] key_hash The hash that always matches the key
+ * @param[in] data The data pointer to remove if the key is @c NULL
+ * @return @c EINA_FALSE if an error occurs, otherwise @c EINA_TRUE
+ *
*/
EAPI Eina_Bool eina_hash_del_by_hash(Eina_Hash *hash,
const void *key,
@@ -909,21 +829,24 @@ EAPI Eina_Bool eina_hash_del_by_hash(Eina_Hash *hash,
const void *data) EINA_ARG_NONNULL(1);
/**
- * @brief Retrieve a specific entry in the given hash table.
- *
- * @param hash The given hash table. Cannot be @c NULL.
- * @param key The key of the entry to find.
- * @param key_length The length of the key.
- * @param key_hash The hash that always match the key
- * @return The data pointer for the stored entry on success, @c NULL
- * otherwise.
- *
- * This function retrieves the entry associated to @p key of length
- * @p key_length in @p hash. @p key_hash is the hash that always match
- * @p key. It is ignored if @p key is @c NULL. Do not forget to count
- * '\\0' for string when setting the value of @p key_length. If
- * @p hash is @c NULL, this function returns immediately @c NULL. This
- * function returns the data pointer on success, @c NULL otherwise.
+ * @brief Retrieves a specific entry in the given hash table.
+ *
+ * @details This function retrieves the entry associated to @a key of length
+ * @a key_length in @a hash. @a key_hash is the hash that always matches
+ * @a key. It is ignored if @a key is @c NULL. Do not forget to count
+ * '\\0' for string when setting the value of @a key_length. If
+ * @a hash is @c NULL, this function returns @c NULL immediately. This
+ * function returns the data pointer on success, otherwise it returns @c NULL.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] hash The given hash table \n
+ * It cannot be @c NULL.
+ * @param[in] key The key of the entry to find
+ * @param[in] key_length The length of the key
+ * @param[in] key_hash The hash that always matches the key
+ * @return The data pointer for the stored entry on success,
+ * otherwise @c NULL
*/
EAPI void *eina_hash_find_by_hash(const Eina_Hash *hash,
const void *key,
@@ -931,19 +854,22 @@ EAPI void *eina_hash_find_by_hash(const Eina_Hash *hash,
int key_hash) EINA_ARG_NONNULL(1, 2);
/**
- * @brief Modify the entry pointer at the specified key and returns
- * the old entry.
- *
- * @param hash The given hash table.
- * @param key The key of the entry to modify.
- * @param key_length Should be the length of @p key (don't forget to count
- * '\\0' for string).
- * @param key_hash The hash that always match the key. Ignored if @p key is
- * @c NULL.
- * @param data The data to replace the old entry, if it exists.
- * @return The data pointer for the old stored entry, or @c NULL if not
- * found. If an existing entry is not found, nothing is added to the
- * hash.
+ * @brief Modifies the entry pointer at the specified key and returns
+ * the old entry.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] hash The given hash table
+ * @param[in] key The key of the entry to modify
+ * @param[in] key_length The length of @a key (don't forget to count
+ * '\\0' for string)
+ * @param[in] key_hash The hash that always matches the key \n
+ * It is ignored if @a key is @c NULL.
+ * @param[in] data The data to replace the old entry, if it exists
+ * @return The data pointer for the old stored entry, otherwise @c NULL if not
+ * found \n
+ * If an existing entry is not found, nothing is added to the
+ * hash.
*/
EAPI void *eina_hash_modify_by_hash(Eina_Hash *hash,
const void *key,
@@ -952,80 +878,90 @@ EAPI void *eina_hash_modify_by_hash(Eina_Hash *hash,
const void *data) EINA_ARG_NONNULL(1, 2, 5);
/**
- * @brief Returned a new iterator associated to hash keys.
+ * @brief Returns a new iterator associated to hash keys.
+ *
+ * @details This function returns a newly allocated iterator associated to @a
+ * hash. If @a hash is not populated, this function still returns a
+ * valid iterator that always returns @c false on a call to
+ * eina_iterator_next(), thus keeping the API sane.
*
- * @param hash The hash.
- * @return A new iterator.
+ * @since_tizen 2.3
*
- * This function returns a newly allocated iterator associated to @p
- * hash. If @p hash is not populated, this function still returns a
- * valid iterator that will always return false on
- * eina_iterator_next(), thus keeping API sane.
+ * @remarks If the memory cannot be allocated, @c NULL is returned
+ * and #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is
+ * returned.
*
- * If the memory can not be allocated, NULL is returned.
- * Otherwise, a valid iterator is returned.
+ * @remarks If the hash structure changes, the iterator becomes
+ * invalid. That is, if you add or remove items this iterator's
+ * behavior is undefined and your program may crash.
+ *
+ * @param[in] hash The hash
+ * @return A new iterator
*
- * @warning if the hash structure changes then the iterator becomes
- * invalid! That is, if you add or remove items this iterator
- * behavior is undefined and your program may crash!
*/
EAPI Eina_Iterator *eina_hash_iterator_key_new(const Eina_Hash *hash) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
/**
- * @brief Returned a new iterator associated to hash data.
+ * @brief Returns a new iterator associated to hash data.
+ *
+ * @details This function returns a newly allocated iterator associated to
+ * @a hash. If @a hash is not populated, this function still returns a
+ * valid iterator that always returns @c false on a call to
+ * eina_iterator_next(), thus keeping the API sane.
*
- * @param hash The hash.
- * @return A new iterator.
+ * @since_tizen 2.3
*
- * This function returns a newly allocated iterator associated to
- * @p hash. If @p hash is not populated, this function still returns a
- * valid iterator that will always return false on
- * eina_iterator_next(), thus keeping API sane.
+ * @remarks If the memory cannot be allocated, @c NULL is returned
+ * and #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is
+ * returned.
*
- * If the memory can not be allocated, @c NULL is returned.
- * Otherwise, a valid iterator is returned.
+ * @remarks If the hash structure changes then the iterator becomes
+ * invalid. That is, if you add or remove items this iterator's behavior
+ * is undefined and your program may crash.
+ *
+ * @param[in] hash The hash
+ * @return A new iterator
*
- * @warning if the hash structure changes then the iterator becomes
- * invalid. That is, if you add or remove items this iterator behavior
- * is undefined and your program may crash.
*/
EAPI Eina_Iterator *eina_hash_iterator_data_new(const Eina_Hash *hash) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
/**
- * @brief Returned a new iterator associated to hash keys and data.
+ * @brief Returns a new iterator associated to hash keys and data.
+ *
+ * @details This function returns a newly allocated iterator associated to @a
+ * hash. If @a hash is not populated, this function still returns a
+ * valid iterator that always returns @c false on a call to
+ * eina_iterator_next(), thus keeping the API sane.
+ *
+ * @since_tizen 2.3
*
- * @param hash The hash.
- * @return A new iterator.
+ * @remarks If the memory cannot be allocated, @c NULL is returned
+ * and #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is
+ * returned.
*
- * This function returns a newly allocated iterator associated to @p
- * hash. If @p hash is not populated, this function still returns a
- * valid iterator that will always return false on
- * eina_iterator_next(), thus keeping API sane.
+ * @remarks The iterator data provides values as Eina_Hash_Tuple that should not
+ * be modified.
*
- * If the memory can not be allocated, @c NULL is returned.
- * Otherwise, a valid iterator is returned.
+ * @remarks If the hash structure changes then the iterator becomes
+ * invalid. That is, if you add or remove items this iterator's
+ * behavior is undefined and your program may crash.
*
- * @note iterator data will provide values as Eina_Hash_Tuple that should not
- * be modified!
+ * @param[in] hash The hash
+ * @return A new iterator
*
- * @warning if the hash structure changes then the iterator becomes
- * invalid! That is, if you add or remove items this iterator
- * behavior is undefined and your program may crash!
*/
EAPI Eina_Iterator *eina_hash_iterator_tuple_new(const Eina_Hash *hash) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
/**
- * @brief Call a function on every member stored in the hash table
+ * @brief Calls a function on every member stored in the hash table.
*
- * @param hash The hash table whose members will be walked
- * @param func The function to call on each parameter
- * @param fdata The data pointer to pass to the function being called
+ * @details This function goes through every entry in the hash table @a hash and calls
+ * the function @a func on each member. The function should @b not modify the
+ * hash table contents if it returns @c 1. @b If the hash table contents are
+ * modified by this function or the function wishes to stop processing it, it must
+ * return @c 0, otherwise it must return @c 1 to keep processing.
*
- * This function goes through every entry in the hash table @p hash and calls
- * the function @p func on each member. The function should @b not modify the
- * hash table contents if it returns @c 1. @b If the hash table contents are
- * modified by this function or the function wishes to stop processing it must
- * return @c 0, otherwise return @c 1 to keep processing.
+ * @since_tizen 2.3
*
* Example:
* @code
@@ -1048,125 +984,107 @@ EAPI Eina_Iterator *eina_hash_iterator_tuple_new(const Eina_Hash *hash) EINA_MAL
* free(hash_fn_data);
* }
* @endcode
+ *
+ * @param[in] hash The hash table whose members are walked
+ * @param[in] func The function to call on each parameter
+ * @param[in] fdata The data pointer to pass to the function being called
*/
EAPI void eina_hash_foreach(const Eina_Hash *hash,
Eina_Hash_Foreach func,
const void *fdata) EINA_ARG_NONNULL(1, 2);
-
-
/**
- * @brief Append data to an #Eina_List inside a hash
- *
- * This function is identical to the sequence of calling
- * eina_hash_find(), eina_list_append(), eina_hash_set(),
- * but with one fewer required hash lookup.
- * @param hash The hash table
- * @param key The key associated with the data
- * @param data The data to append to the list
- * @since 1.10
- */
-EAPI void eina_hash_list_append(Eina_Hash *hash, const void *key, const void *data) EINA_ARG_NONNULL(1, 2, 3);
-/**
- * @brief Append data to an #Eina_List inside a hash
- *
- * This function is identical to the sequence of calling
- * eina_hash_find(), eina_list_append(), eina_hash_set(),
- * but with one fewer required hash lookup.
- * @param hash The hash table
- * @param key The key associated with the data
- * @param data The data to append to the list
- * @since 1.10
- */
-EAPI void eina_hash_list_prepend(Eina_Hash *hash, const void *key, const void *data) EINA_ARG_NONNULL(1, 2, 3);
-/**
- * @brief Append data to an #Eina_List inside a hash
- *
- * This function is identical to the sequence of calling
- * eina_hash_find(), eina_list_append(), eina_hash_set(),
- * but with one fewer required hash lookup.
- * @param hash The hash table
- * @param key The key associated with the data
- * @param data The data to append to the list
- * @since 1.10
- */
-EAPI void eina_hash_list_remove(Eina_Hash *hash, const void *key, const void *data) EINA_ARG_NONNULL(1, 2, 3);
-
-/**
- * @brief
- * Paul Hsieh (http://www.azillionmonkeys.com/qed/hash.html) hash function used by WebCore (http://webkit.org/blog/8/hashtables-part-2/)
- *
- * @param key The key to hash
- * @param len The length of the key
+ * @brief Paul Hsieh (http://www.azillionmonkeys.com/qed/hash.html) hash
+ * function used by WebCore (http://webkit.org/blog/8/hashtables-part-2/)
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] key The key to hash
+ * @param[in] len The length of the key
* @return The hash value
*/
EAPI int eina_hash_superfast(const char *key,
int len) EINA_ARG_NONNULL(1);
-/**
- * @brief
- * Hash function first reported by Dan Bernstein many years ago in comp.lang.c
- *
- * @param key The key to hash
- * @param len The length of the key
+/**
+ * @details The djb2 hash function
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks djb2 hash algorithm was first reported by dan bernstein, and was
+ * the old default hash function for evas.
+ *
+ * @remarks This hash function first reported by dan bernstein many years ago
+ * in comp.lang.c
+ *
+ * @param[in] key The key to hash
+ * @param[in] len The length of the key
* @return The hash value
*/
static inline int eina_hash_djb2(const char *key,
int len) EINA_ARG_NONNULL(1);
-/**
- * @brief
- * Hash function first reported by Dan Bernstein many years ago in comp.lang.c
- *
- * @param key The key to hash
- * @param plen The length of the key
+
+/**
+ * @details The djb2 hash function withoug length
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks djb2 hash algorithm was first reported by dan bernstein, and was
+ * the old default hash function for evas.
+ *
+ * @remarks This hash function first reported by dan bernstein many years ago
+ * in comp.lang.c
+ *
+ * @param[in] key The key to hash
+ * @param[out] plen The length of the key to be returned
* @return The hash value
*/
static inline int eina_hash_djb2_len(const char *key,
int *plen) EINA_ARG_NONNULL(1, 2);
-/**
- * @brief
- * Hash function from http://www.concentric.net/~Ttwang/tech/inthash.htm
- *
- * @param pkey The key to hash
- * @param len The length of the key
+/**
+ * @details The 32 bit integer hash function
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Hash function from
+ * http://www.concentric.net/~Ttwang/tech/inthash.htm
+ *
+ * @param[in] pkey The key to hash
+ * @param[in] len The length of the key
* @return The hash value
*/
static inline int eina_hash_int32(const unsigned int *pkey,
int len) EINA_ARG_NONNULL(1);
-/**
- * @brief
- * Hash function from http://www.concentric.net/~Ttwang/tech/inthash.htm
- *
- * @param pkey The key to hash
- * @param len The length of the key
+
+/**
+ * @details The 64 bit integer hash function
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] pkey The key to hash
+ * @param[in] len The length of the key
* @return The hash value
*/
-static inline int eina_hash_int64(const unsigned long long int *pkey,
+static inline int eina_hash_int64(const unsigned long int *pkey,
int len) EINA_ARG_NONNULL(1);
-/**
- * @brief
- * Hash function from http://sites.google.com/site/murmurhash/
- *
- * @param key The key to hash
- * @param len The length of the key
+/**
+ * @details The murmur3 hash function
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks http://sites.google.com/site/murmurhash/
+ *
+ * @param[in] key The key to hash
+ * @param[in] len The length of the key
* @return The hash value
*/
static inline int eina_hash_murmur3(const char *key,
int len) EINA_ARG_NONNULL(1);
-
#include "eina_inline_hash.x"
/**
* @}
*/
-/**
- * @}
- */
-
-/**
- * @}
- */
-
#endif /*EINA_HASH_H_*/
diff --git a/src/lib/eina/eina_inarray.h b/src/lib/eina/eina_inarray.h
index 34e7380841..a75f354c4a 100644
--- a/src/lib/eina/eina_inarray.h
+++ b/src/lib/eina/eina_inarray.h
@@ -1,14 +1,14 @@
/* EINA - EFL data type library
* Copyright (C) 2012 ProFUSION embedded systems
*
- * This library is free software; you can redistribute it and/or
+ * This library is a free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
@@ -24,138 +24,13 @@
#include "eina_accessor.h"
/**
- * @page eina_inarray_example_01 Eina inline array usage
- * @dontinclude eina_inarray_01.c
- *
- * 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 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 }
- *
- * And then move on to the code we actually care about, starting with variable
- * declarations and eina initialization:
- * @until eina_init
- *
- * Creating an inline array is very simple, we just need to know what type we
- * want to store:
- * @until inarray_new
- * @note The second parameter(the step) is left at zero which means that eina
- * 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 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.
- *
- * So let's add some more elements:
- * @until push
- * @until push
- * @until push
- *
- * 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 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
- * eina_inarray_step_set() function, which is just like the eina_inarray_new()
- * 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 a different type, but because our types have
- * different sizes. Eina inline arrays don't actually know anything about types,
- * 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);
- * @endcode
- *
- * And now to add our integer values to the array:
- * @until push
- * @until push
- * @until push
- *
- * 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
- * eina_inarray_insert_sorted() instead:
- * @until insert_sorted
- *
- * We then print the size of our array, and the array itself, much like last
- * time the values are not surprising, and neither should it be that the memory
- * addresses are contiguous:
- * @until printf
- * @until printf
- *
- * Once done we free our array and shutdown eina:
- * @until }
- *
- * The source for this example: @ref eina_inarray_01_c
- */
-
-/**
- * @page eina_inarray_01_c eina_inarray_01.c
- * @include eina_inarray_01.c
- * @example eina_inarray_01.c
- */
-
-/**
- * @page eina_inarray_example_02 Eina inline array of strings
- * @dontinclude eina_inarray_02.c
- *
- * 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:
- * @skip int
- * @until eina_init
- *
- * We then create the array much like we did on @ref eina_inarray_example_01 :
- * @until inarray_new
- *
- * 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 }
- *
- * The source for this example: @ref eina_inarray_02_c
- */
-
-/**
- * @page eina_inarray_02_c eina_inarray_02.c
- * @include eina_inarray_02.c
- * @example eina_inarray_02.c
- */
-
-/**
* @defgroup Eina_Inline_Array_Group Inline Array
* @ingroup Eina_Containers_Group
* @since 1.2
*
- * @brief Inline array is a container that stores the data itself, not the pointers to the data.
+ * @brief Inline array is a container that stores the data itself, not the pointers to the data,
*
- * This means there is no memory fragmentation, also for small data types(such
+ * 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
@@ -163,29 +38,23 @@
* of the array is a lot more costly than appending, so those operations should
* be minimized.
*
- * Examples:
- * @li @ref eina_inarray_example_01
- * @li @ref eina_inarray_example_02
- *
* @{
*/
/**
* @typedef Eina_Inarray
- * @brief Type for the inlined array.
+ * @brief The structure type for the inlined array type.
*
* @since 1.2
*/
typedef struct _Eina_Inarray Eina_Inarray;
/**
- * @brief Inline array structure.
- *
- * @note Use #Eina_Inarray instead.
+ * @brief Inline array structure, use #Eina_Inarray typedef instead.
*
- * @note Do not modify these fields directly, use eina_inarray_step_set() or
- * eina_inarray_new() instead.
+ * @details Do not modify these fields directly, use eina_inarray_step_set() or
+ * eina_inarray_new() instead.
*
* @since 1.2
*/
@@ -205,21 +74,24 @@ struct _Eina_Inarray
/**
* @brief Creates a new inline array.
*
- * @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
- *
* @details This creates a new array where members are inlined in a sequence. Each
* member has @a member_size bytes.
*
- * @note If the @a step is @c 0, then a safe default is chosen.
+ * @since 1.2
*
- * @note On failure, @c NULL is returned. If @p member_size is zero, then @c NULL is returned.
+ * @since_tizen 2.3
*
- * @see eina_inarray_free()
+ * @remarks If the @a step is @c 0, then a safe default is chosen.
*
- * @since 1.2
+ * @remarks On failure, @c NULL is returned and #EINA_ERROR_OUT_OF_MEMORY is
+ * set. If @a member_size is zero, then @c NULL is returned.
+ *
+ * @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
+ *
+ * @see eina_inarray_free()
*/
EAPI Eina_Inarray *eina_inarray_new(unsigned int member_size,
unsigned int step) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
@@ -227,32 +99,37 @@ EAPI Eina_Inarray *eina_inarray_new(unsigned int member_size,
/**
* @brief Frees an array and its members.
*
+ * @since 1.2
+ *
+ * @since_tizen 2.3
+ *
* @param[in] array The array object
*
* @see eina_inarray_flush()
*
- * @since 1.2
*/
EAPI void eina_inarray_free(Eina_Inarray *array) EINA_ARG_NONNULL(1);
/**
* @brief Initializes an inline array.
*
+ * @details This initializes an array. If the @a step is @c 0, then a safe default is
+ * chosen.
+ *
+ * @since 1.2
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This is useful for arrays inlined into other structures or
+ * allocated to a stack.
+ *
* @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
- *
- * @details This initializes an array. If the @p step is @c 0, then a safe default is
- * chosen.
- *
- * @note This is useful for arrays inlined into other structures or
- * allocated to a stack.
+ * extra amount
*
* @see eina_inarray_flush()
- *
- * @since 1.2
*/
EAPI void eina_inarray_step_set(Eina_Inarray *array,
unsigned int sizeof_eina_inarray,
@@ -262,65 +139,59 @@ EAPI void eina_inarray_step_set(Eina_Inarray *array,
/**
* @brief Removes every member from the array.
*
+ * @since 1.2
+ *
+ * @since_tizen 2.3
*
* @param[in] array The array object
*
- * @since 1.2
*/
EAPI void eina_inarray_flush(Eina_Inarray *array) EINA_ARG_NONNULL(1);
/**
* @brief Copies the data as the last member of the array.
*
- * @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
- *
* @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
- */
-EAPI int eina_inarray_push(Eina_Inarray *array,
- const void *data) EINA_ARG_NONNULL(1, 2);
-
-/**
- * @brief Allocate new item at the end of the array.
+ *
+ * @since_tizen 2.3
*
* @param[in] array The array object
- * @param[in] size The number of new item to allocate
+ * @param[in] data The data to be copied at the end
+ * @return The index of the new member, otherwise @c -1 on errors
*
- * @note The returned pointer is only valid until you use any other eina_inarray
- * function.
+ * @see eina_inarray_insert_at()
*
- * @since 1.8
*/
-EAPI void *eina_inarray_grow(Eina_Inarray *array, unsigned int size);
+EAPI int eina_inarray_push(Eina_Inarray *array,
+ const void *data) EINA_ARG_NONNULL(1, 2);
/**
* @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
- *
* @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.
+ * @since 1.2
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks The data given to the @a compare function is a pointer to the member
+ * memory itself, do no change it.
+ *
+ * @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
*
* @see eina_inarray_insert_sorted()
* @see eina_inarray_insert_at()
* @see eina_inarray_push()
- *
- * @since 1.2
*/
EAPI int eina_inarray_insert(Eina_Inarray *array,
const void *data,
@@ -329,25 +200,27 @@ EAPI int eina_inarray_insert(Eina_Inarray *array,
/**
* @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
- *
* @details This copies the given pointer contents at the array position defined by the
- * given @p compare function. The pointer is not referenced, instead
+ * given @a compare function. The pointer is not referenced, instead
* its contents are copied to the members array using the previously
- * defined @p member_size.
+ * 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.
+ * @since 1.2
*
- * @note This variation optimizes the insertion position assuming that the array
- * is already sorted by doing a binary search.
+ * @since_tizen 2.3
*
- * @see eina_inarray_sort()
+ * @remarks The data given to the @a compare function is a pointer to the member
+ * memory itself, do no change it.
*
- * @since 1.2
+ * @remarks This variation optimizes the insertion position assuming that the array
+ * is already sorted by doing a binary search.
+ *
+ * @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
+ *
+ * @see eina_inarray_sort()
*/
EAPI int eina_inarray_insert_sorted(Eina_Inarray *array,
const void *data,
@@ -356,18 +229,20 @@ EAPI int eina_inarray_insert_sorted(Eina_Inarray *array,
/**
* @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
- *
* @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().
*
+ * @since 1.2
+ *
+ * @since_tizen 2.3
+ *
+ * @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
+ *
* @see eina_inarray_pop()
* @see eina_inarray_remove_at()
- *
- * @since 1.2
*/
EAPI int eina_inarray_remove(Eina_Inarray *array,
const void *data) EINA_ARG_NONNULL(1, 2);
@@ -375,31 +250,36 @@ EAPI int eina_inarray_remove(Eina_Inarray *array,
/**
* @brief Removes the last member of the array.
*
+ * @since 1.2
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks The data could be considered valid only until any other operation touched 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 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
- *
* @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.
*
+ * @since 1.2
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] array The array object
+ * @param[in] position The member position
+ * @return A pointer to current the member memory
+ *
* @see eina_inarray_lookup()
* @see eina_inarray_lookup_sorted()
- *
- * @since 1.2
*/
EAPI void *eina_inarray_nth(const Eina_Inarray *array,
unsigned int position) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
@@ -407,25 +287,28 @@ EAPI void *eina_inarray_nth(const Eina_Inarray *array,
/**
* @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
- *
- * @details This copies the given pointer contents at the given @p position in the
+ * @details This copies the given pointer contents at the given @a 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.
+ * @c member_size.
*
- * @note All the members from @a position to the end of the array are
- * shifted to the end.
+ * All the members from @a position to the end of the array are
+ * shifted to the end.
*
- * @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 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.
+ * If @a position is bigger than the array length, it fails.
*
* @since 1.2
+ *
+ * @since_tizen 2.3
+ *
+ * @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 @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure
+ *
*/
EAPI Eina_Bool eina_inarray_insert_at(Eina_Inarray *array,
unsigned int position,
@@ -434,28 +317,31 @@ EAPI Eina_Bool eina_inarray_insert_at(Eina_Inarray *array,
/**
* @brief Opens a space at the given position, returning its pointer.
*
- * @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
+ * @since 1.2
*
- * @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.
+ * @since_tizen 2.3
*
- * @note The new member memory is undefined, it's not automatically zeroed.
+ * @remarks 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.
*
- * @note All the members from @a position to the end of the array are
- * shifted to the end.
+ * The new member memory is undefined, it's not automatically zeroed.
*
- * @note If @a position is equal to the end of the array (equal to
- * eina_inarray_count()), then the member is appended.
+ * @remarks All the members from @a position to the end of the array are
+ * shifted to the end.
*
- * @note If @a position is bigger than the array length, it fails.
+ * 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 fails.
+ *
+ * @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
*
- * @since 1.2
*/
EAPI void *eina_inarray_alloc_at(Eina_Inarray *array,
unsigned int position,
@@ -464,19 +350,22 @@ EAPI void *eina_inarray_alloc_at(Eina_Inarray *array,
/**
* @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
- *
- * @details This copies the given pointer contents at the given @p position in the
+ * @details This copies the given pointer contents at the given @a 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.
+ * @c member_size.
*
- * @note If @p position does not exist, it fails.
+ * If @a position does not exist, it fails.
*
* @since 1.2
+ *
+ * @since_tizen 2.3
+ *
+ * @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 @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure
+ *
*/
EAPI Eina_Bool eina_inarray_replace_at(Eina_Inarray *array,
unsigned int position,
@@ -485,17 +374,20 @@ EAPI Eina_Bool eina_inarray_replace_at(Eina_Inarray *array,
/**
* @brief Removes a member from the given position.
*
+ * @since 1.2
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks The member is removed from an array and 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
- *
- * @note The member is removed from an array and members after it are moved
- * towards the array head.
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure
*
* @see eina_inarray_pop()
* @see eina_inarray_remove()
*
- * @since 1.2
*/
EAPI Eina_Bool eina_inarray_remove_at(Eina_Inarray *array,
unsigned int position) EINA_ARG_NONNULL(1);
@@ -503,31 +395,35 @@ EAPI Eina_Bool eina_inarray_remove_at(Eina_Inarray *array,
/**
* @brief Reverses members in the array.
*
- * @param[in] array The array object
+ * @since 1.2
*
- * @note If you do not want to change the array, just walk through its elements
- * backwards, then use the EINA_INARRAY_REVERSE_FOREACH() macro.
+ * @since_tizen 2.3
*
- * @see EINA_INARRAY_REVERSE_FOREACH()
+ * @remarks If you do not want to change the array, just walk through its elements
+ * backwards, then use the EINA_INARRAY_REVERSE_FOREACH() macro.
*
- * @since 1.2
+ * @param[in] array The array object
+ *
+ * @see EINA_INARRAY_REVERSE_FOREACH()
*/
EAPI void eina_inarray_reverse(Eina_Inarray *array) EINA_ARG_NONNULL(1);
/**
* @brief Applies a quick sort to the array.
*
- * @param[in] array The array object
- * @param[in] compare The compare function
- *
* @details This applies a quick sort to the @a array.
*
- * @note The data given to the @a compare function is a pointer to the member
- * memory itself, do no change it.
+ * @since 1.2
+ *
+ * @since_tizen 2.3
*
- * @see eina_inarray_insert_sorted()
+ * @remarks The data given to the @a compare function is a pointer to the member
+ * memory itself, do no change it.
*
- * @since 1.2
+ * @param[in] array The array object
+ * @param[in] compare The compare function
+ *
+ * @see eina_inarray_insert_sorted()
*/
EAPI void eina_inarray_sort(Eina_Inarray *array,
Eina_Compare_Cb compare) EINA_ARG_NONNULL(1, 2);
@@ -535,20 +431,26 @@ EAPI void eina_inarray_sort(Eina_Inarray *array,
/**
* @brief Searches for a member (linear walk).
*
+ * @details This walks through an array by linearly looking for the given data compared by
+ * the @a compare function.
+ *
+ * The data given to the @a compare function is a pointer to the member
+ * memory itself, do no change it.
+ *
+ * @since 1.2
+ *
+ * @since_tizen 2.3
+ *
* @param[in] array The array object
- * @param[in] data The member to search using the @p compare function
+ * @param[in] data The member to search using the @a compare function
* @param[in] compare The compare function
* @return The member index, otherwise @c -1 if not found
*
- * @details This walks through an array by linearly looking for the given data 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.
- *
* @see eina_inarray_lookup_sorted()
*
* @since 1.2
+ *
+ * @since_tizen 2.3
*/
EAPI int eina_inarray_search(const Eina_Inarray *array,
const void *data,
@@ -557,41 +459,47 @@ EAPI int eina_inarray_search(const Eina_Inarray *array,
/**
* @brief Searches for member (binary search walk).
*
+ * @since 1.2
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Uses a binary search for the given data as compared by the @a compare function.
+ *
+ * The data given to the @a compare function is a pointer to the member
+ * memory itself, do no change it.
+ *
* @param[in] array The array object
- * @param[in] data The member to search using the @p compare function
+ * @param[in] data The member to search using the @a compare function
* @param[in] compare The compare function
* @return The member index, otherwise @c -1 if not found
*
- * @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
*/
EAPI int eina_inarray_search_sorted(const Eina_Inarray *array,
const void *data,
Eina_Compare_Cb compare) EINA_ARG_NONNULL(1, 2, 3);
/**
- * @brief Calls @p function for each array member.
+ * @brief Calls @a 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
+ * @details This calls @a function for every given data in @a array.
*
- * @details This calls @p function for every given data in @p array.
+ * @since 1.2
*
- * @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.
+ * @since_tizen 2.3
*
- * @note The data given to @p function is a pointer to the member memory itself.
+ * @remarks This is a safe way to iterate over an array. @a function should return @c EINA_TRUE
+ * as long as you want the function to continue iterating, by
+ * returning @c EINA_FALSE it stops and returns @c EINA_FALSE as the result.
*
- * @see EINA_INARRAY_FOREACH()
+ * The data given to @a function is a pointer to the member memory
+ * itself.
*
- * @since 1.2
+ * @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 @c EINA_TRUE if it successfully iterates all the items of the array
+ *
+ * @see EINA_INARRAY_FOREACH()
*/
EAPI Eina_Bool eina_inarray_foreach(const Eina_Inarray *array,
Eina_Each_Cb function,
@@ -600,96 +508,104 @@ EAPI Eina_Bool eina_inarray_foreach(const Eina_Inarray *array,
/**
* @brief Removes all the members that match.
*
+ * @details This removes all the entries in @a array, where the @a match function
+ * returns @c EINA_TRUE.
+ *
+ * @since 1.2
+ *
+ * @since_tizen 2.3
+ *
* @param[in] array The array object
* @param[in] match The match function
- * @param[in] user_data The user data given to callback @p match
+ * @param[in] user_data The user data given to callback @a match
* @return The number of removed entries, otherwise @c -1 on error
*
- * @details This removes all the entries in @p array, where the @p match function
- * returns #EINA_TRUE.
- *
- * @since 1.2
*/
EAPI int eina_inarray_foreach_remove(Eina_Inarray *array,
Eina_Each_Cb match,
const void *user_data) EINA_ARG_NONNULL(1, 2);
/**
- * @brief Resizes array to new size
+ * @brief Counts the number of members in an array.
*
- * @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.2
*
- * @since 1.10
- */
-EAPI Eina_Bool eina_inarray_resize(Eina_Inarray *array, unsigned int new_size);
-
-/**
- * @brief Counts the number of members in an array.
+ * @since_tizen 2.3
*
* @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 Returns a new iterator associated to an array.
*
- * @param[in] array The array object
- * @return A new iterator
- *
* @details This function returns a newly allocated iterator associated to
- * @p array.
+ * @a array.
+ *
+ * If the memory cannot be allocated, @c NULL is returned
+ * and #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is
+ * returned.
+ *
+ * @since 1.2
*
- * @note If the memory cannot be allocated, @c NULL is returned.
- * Otherwise, a valid iterator is returned.
+ * @since_tizen 2.3
*
- * @warning If the array structure changes then the iterator becomes
+ * @remarks 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
+ * @param[in] array The array object
+ * @return A new iterator
+ *
*/
EAPI Eina_Iterator *eina_inarray_iterator_new(const Eina_Inarray *array) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
/**
* @brief Returns a new reversed iterator associated to an array.
*
- * @param[in] array The array object
- * @return A new iterator
- *
* @details This function returns a newly allocated iterator associated to
- * @p array.
+ * @a array.
*
- * @note Unlike eina_inarray_iterator_new(), this walks through the array backwards.
+ * If the memory cannot be allocated, @c NULL is returned
+ * and #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is
+ * returned.
*
- * @note If the memory cannot be allocated, @c NULL is returned.
- * Otherwise, a valid iterator is returned.
+ * @since 1.2
*
- * @warning If the array structure changes then the iterator becomes
+ * @since_tizen 2.3
+ *
+ * @remarks Unlike eina_inarray_iterator_new(), this walks through the array backwards.
+ *
+ *
+ * @remarks 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
+ * @param[in] array The array object
+ * @return A new iterator
+ *
*/
EAPI Eina_Iterator *eina_inarray_iterator_reversed_new(const Eina_Inarray *array) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
/**
* @brief Returns a new accessor associated to an array.
*
- * @param[in] array The array object
- * @return A new accessor
- *
* @details This function returns a newly allocated accessor associated to
- * @p array.
+ * @a array.
*
- * @note If the memory cannot be allocated, @c NULL is returned
- * Otherwise, a valid accessor is returned.
+ * If the memory cannot be allocated, @c NULL is returned
+ * and #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid accessor is
+ * returned.
*
* @since 1.2
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] array The array object
+ * @return A new accessor
+ *
*/
EAPI Eina_Accessor *eina_inarray_accessor_new(const Eina_Inarray *array) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
@@ -697,46 +613,52 @@ EAPI Eina_Accessor *eina_inarray_accessor_new(const Eina_Inarray *array) EINA_MA
* @def EINA_INARRAY_FOREACH
* @brief Walks through an array linearly from head to tail.
*
- * @param[in] array The array object
- * @param[in] itr An iterator pointer
+ * @since 1.2
*
- * @note @p itr must be a pointer with sizeof(itr*) == array->member_size.
+ * @since_tizen 2.3
*
- * @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.
+ * @remarks @a itr must be a pointer with sizeof(itr*) == array->member_size.
*
- * @note Do not modify an array as you walk through it. If that is desired,
- * then use eina_inarray_foreach_remove().
+ * @remarks 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.
+ *
+ * @remarks Do not modify an array as you walk through it. If that is desired,
+ * then use eina_inarray_foreach_remove().
+ *
+ * @param array The array object
+ * @param itr An iterator pointer
*
- * @since 1.2
*/
#define EINA_INARRAY_FOREACH(array, itr) \
for ((itr) = (array)->members; \
- (itr) < (((__typeof__(*itr)*)(array)->members) + (array)->len); \
+ (itr) < (((typeof(*itr)*)(array)->members) + (array)->len); \
(itr)++)
/**
* @def EINA_INARRAY_REVERSE_FOREACH
* @brief Walks through an array linearly from tail to head.
*
- * @param[in] array The array object
- * @param[in] itr An iterator pointer
+ * @since 1.2
*
- * @note @p itr must be a pointer with sizeof(itr*) == array->member_size.
+ * @since_tizen 2.3
*
- * @note This is fast as it does direct pointer access, but it does
- * not check for @c NULL pointers or invalid array objects.
+ * @remarks @a itr must be a pointer with sizeof(itr*) == array->member_size.
*
- * @note Do not modify an array as you walk through it. If that is desired,
- * then use eina_inarray_foreach_remove().
+ * @remarks This is fast as it does direct pointer access, but it does
+ * not check for @c NULL pointers or invalid array objects.
+ *
+ * @remarks Do not modify an array as you walk through it. If that is desired,
+ * then use eina_inarray_foreach_remove().
+ *
+ * @param array The array object
+ * @param itr An iterator pointer
*
- * @since 1.2
*/
#define EINA_INARRAY_REVERSE_FOREACH(array, itr) \
- for ((itr) = ((((__typeof__(*(itr))*)(array)->members) + (array)->len) - 1); \
- (((itr) >= (__typeof__(*(itr))*)(array)->members) \
- && ((array)->members != NULL)); \
+ for ((itr) = ((((typeof(*(itr))*)(array)->members) + (array)->len) - 1); \
+ (((itr) >= (typeof(*(itr))*)(array)->members) \
+ && ((array)->members != NULL)); \
(itr)--)
/**
diff --git a/src/lib/eina/eina_inlist.h b/src/lib/eina/eina_inlist.h
index 6c1b1cc951..3753ae1fc8 100644
--- a/src/lib/eina/eina_inlist.h
+++ b/src/lib/eina/eina_inlist.h
@@ -1,14 +1,14 @@
/* EINA - EFL data type library
* Copyright (C) 2002-2008 Carsten Haitzler, Vincent Torri
*
- * This library is free software; you can redistribute it and/or
+ * This library is a free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
@@ -25,298 +25,32 @@
#include <stddef.h>
/**
- * @page eina_inlist_01_example_page Eina_Inlist basic usage
- * @dontinclude eina_inlist_01.c
- *
- * To see the full source for this example, click here: @ref
- * eina_inlist_01_c
- *
- * As explained before, inline lists mean its nodes pointers are part of same
- * memory block/blob. This is done by using the macro @ref EINA_INLIST inside the
- * data structure that will be used:
- *
- * @skip struct
- * @until };
- *
- * The resulting node representing this struct can be exemplified by the
- * following picture:
- *
- * @image html eina_inlist-node_eg1-my-struct.png
- * @image rtf eina_inlist-node_eg1-my-struct.png
- * @image latex eina_inlist-node_eg1-my-struct.eps
- *
- * Let's define a comparison function that will be used later during the
- * sorting of the list:
- *
- * @skip int
- * @until }
- *
- * The @ref Eina_Inlist can be used exactly the same way as @ref Eina_List when
- * appending, prepending and removing items. But since we already have the node
- * pointers inside the structure, they need to be retrieved with the macro @ref
- * EINA_INLIST_GET :
- *
- * @skip malloc
- * @until append
- *
- * Notice that @ref eina_inlist_append always receives the head of the list as
- * first argument, and its return value should be used as the list pointer
- * (head):
- *
- * @skip malloc
- * @until append
- *
- * After appending 3 items, the list now should look similar to this:
- *
- * @image html eina_inlist-node_eg1-inlist.png
- * @image rtf eina_inlist-node_eg1-inlist.png
- * @image latex eina_inlist-node_eg1-inlist.eps "" width=\textwidth
- *
- * The macro @ref EINA_INLIST_FOREACH can be used to iterate over the list:
- *
- * @skip printf
- * @until cur->a
- *
- * @ref eina_inlist_promote(), @ref eina_inlist_demote(), @ref
- * eina_inlist_append_relative() and similar functions all work in the same way
- * as the @ref Eina_List :
- *
- * @skip eina_inlist_promote
- * @until eina_inlist_demote
- *
- * Now let's use the @c sort_cb function declared above to sort our list:
- *
- * @skipline eina_inlist_sort
- *
- * Removing an element from the inlist is also similar to @ref Eina_List :
- *
- * @skip inlist_remove
- * @until free
- *
- * Another way of walking through the inlist.
- *
- * @skip for
- * @until }
- *
- * Notice that in the previous piece of code, since we only have the pointers to
- * the inlist nodes, we have to use the @ref EINA_INLIST_CONTAINER_GET macro
- * that will return the pointer to the entire structure. Of course, in this case
- * it is the same as the list pointer, since the @ref EINA_INLIST macro was used
- * in the beginning of the structure.
- *
- * Now to finish this example, lets delete this list:
- *
- * @skip while
- * @until }
- */
-
-/**
- * @page eina_inlist_02_example_page Eina_Inlist advanced usage - lists and inlists
- * @dontinclude eina_inlist_02.c
- *
- * This example describes the usage of @ref Eina_Inlist mixed with @ref
- * Eina_List . We create and add elements to an inlist, and the even members
- * are also added to a normal list. Later we remove the elements divisible by 3
- * from this normal list.
- *
- * The struct that is going to be used is the same used in @ref
- * eina_inlist_01_example_page , since we still need the @ref EINA_INLIST macro to
- * declare the inlist node info:
- *
- * @skip struct
- * @until };
- *
- * The resulting node representing this struct can be exemplified by the
- * following picture:
- *
- * @image html eina_inlist-node_eg2-my-struct.png
- * @image rtf eina_inlist-node_eg2-my-struct.png
- * @image latex eina_inlist-node_eg2-my-struct.eps
- *
- * Now we need some pointers and auxiliar variables that will help us iterate on
- * the lists:
- *
- * @skip struct
- * @until l_next;
- *
- * Allocating 100 elements and putting them into an inlist, and the even
- * elements also go to the normal list:
- *
- * @skip for
- * @until }
- *
- * After this point, what we have are two distinct lists that share some
- * elements. The first list (inlist) is defined by the pointers inside the
- * elements data structure, while the second list (normal list) has its own node
- * data structure that is kept outside of the elements.
- *
- * The two lists, sharing some elements, can be represented by the following
- * picture:
- *
- * @htmlonly
- * <img src="eina_inlist-node_eg2-list-inlist.png" style="max-width: 100%;"/>
- * @endhtmlonly
- * @image rtf eina_inlist-node_eg2-list-inlist.png
- * @image latex eina_inlist-node_eg2-list-inlist.eps "" width=\textwidth
- *
- * Accessing both lists is done normally, as if they didn't have any elements in
- * common:
- *
- * @skip printf
- * @until eina_list_count
- *
- * We can remove elements from the normal list, but we just don't free them
- * because they are still stored in the inlist:
- *
- * @skip EINA_LIST_FOREACH_SAFE
- * @until eina_list_count
- *
- * To finish this example, we want to free both lists, we can't just free all
- * elements on the second list (normal list) because they are still being used
- * in the inlist. So we first discard the normal list without freeing its
- * elements, then we free all elements in the inlist (that contains all elements
- * allocated until now):
- *
- * @skip eina_list_free
- * @until }
- *
- * Here is the full source code for this example: @ref eina_inlist_02_c
- */
-
-/**
- * @page eina_inlist_03_example_page Eina_Inlist advanced usage - multi-inlists
- * @dontinclude eina_inlist_03.c
- *
- * This example describes the usage of multiple inlists storing the same data.
- * It means that some data may appear in more than one inlist at the same time.
- * We will demonstrate this by creating an inlist with 100 numbers, and adding
- * the odd numbers to the second inlist, then remove the numbers divisible by 3
- * from the second list.
- *
- * To accomplish this, it is necessary to have two inlist pointers in the struct
- * that is going to be stored. We are using the default inlist member @ref
- * EINA_INLIST, and adding another member @c even that is of type @ref
- * Eina_Inlist too:
- *
- * @skip struct
- * @until };
- *
- * The representation for this struct is:
- *
- * @image html eina_inlist-node_eg3-my-struct.png
- * @image rtf eina_inlist-node_eg3-my-struct.png
- * @image latex eina_inlist-node_eg3-my-struct.eps
- *
- * And we will define some convenience macros that are equivalent to @ref
- * EINA_INLIST_GET and @ref EINA_INLIST_CONTAINER_GET :
- *
- * @skip define
- * @until offsetof
- *
- * We need two pointers, one for each list, and a pointer that will be used as
- * an iterator:
- *
- * @skipline Eina_Inlist
- *
- * Now we allocate and add to the first list every number from 0 to 99. These
- * nodes data also have the @ref Eina_Inlist node info for the second list (@c
- * even). We will use them to add just the even numbers to the second list, the
- * @c list_even. Also notice that we are using our macro @c EVEN_INLIST_GET to
- * get the pointer to the even list node info:
- *
- * @skip for
- * @until }
- *
- * And the resulting lists will be as follow:
- *
- * @htmlonly
- * <img src="eina_inlist-node_eg3-two-inlists.png" style="max-width: 100%;"/>
- * @endhtmlonly
- * @image rtf eina_inlist-node_eg3-two-inlists.png
- * @image latex eina_inlist-node_eg3-two-inlists.eps "" width=\textwidth
- *
- * For the first list, we can use the macro @ref EINA_INLIST_FOREACH to iterate
- * over its elements:
- *
- * @skip FOREACH
- * @until printf
- *
- * But for the second list, we have to do it manually. Of course we could create
- * a similar macro to @ref EINA_INLIST_FOREACH, but since this macro is more
- * complex than the other two and we are using it only once, it's better to just
- * do it manually:
- *
- * @skip for
- * @until }
- *
- * Let's just check that the two lists have the expected number of elements:
- *
- * @skip list count
- * @until list_even count
- *
- * And removing the numbers divisible by 3 only from the second list:
- *
- * @skip itr
- * @until list_even count
- *
- * Now that we don't need the two lists anymore, we can just free all the items.
- * Since all of the allocated data was put into the first list, and both lists
- * are made of pointers to inside the data structures, we can free only the
- * first list (that contains all the elements) and the second list will be gone
- * with it:
- *
- * @skip while
- * @until free
- *
- * To see the full source code for this example, click here: @ref
- * eina_inlist_03_c
- *
- */
-
-/**
- * @page eina_inlist_01_c eina_inlist_01.c Eina_Inlist basic usage source
- * @include eina_inlist_01.c
- */
-
-/**
- * @page eina_inlist_02_c eina_inlist_02.c Eina_Inlist advanced usage - lists and inlists source
- * @include eina_inlist_02.c
- */
-
-/**
- * @page eina_inlist_03_c eina_inlist_03.c Eina_Inlist advanced usage - multi-inlists source
- * @include eina_inlist_03.c
- */
-
-/**
- * @addtogroup Eina_Inline_List_Group Inline List
+ * @defgroup Eina_Inline_List_Group Inline List
+ * @ingroup Eina_Containers_Group
*
* @brief These functions provide inline list management.
*
- * Inline lists mean its nodes pointers are part of same memory as
- * data. This has the benefit of fragmenting memory less and avoiding
+ * Inline lists mean its nodes pointers are part of the same memory as
+ * the data. This has the benefit of fragmenting less memory and avoiding
* @c node->data indirection, but has the drawback of higher cost for some
* common operations like count and sort.
*
* It is possible to have inlist nodes to be part of regular lists, created with
* @ref eina_list_append() or @ref eina_list_prepend(). It's also possible to
- * have a structure with two inlist pointers, thus be part of two different
- * inlists at the same time, but the current convenience macros provided won't
+ * have a structure with two inlist pointers, thus being part of two different
+ * inlists at the same time, but the current convenience macros that are provided won't
* work for both of them. Consult @ref inlist_advanced for more info.
*
* Inline lists have their purposes, but if you don't know what those purposes are, go with
* regular lists instead.
*
* Tip: When using inlists in more than one place (that is, passing them around
- * functions or keeping a pointer to them in a structure) it's more correct
+ * functions or keeping a pointer to them in a structure) it's is better
* to keep a pointer to the first container, and not a pointer to the first
* inlist item (mostly they are the same, but that's not always correct).
- * This lets the compiler to do type checking and let the programmer know
+ * This lets the compiler do type checking and lets the programmer know
* exactly what type this list is.
*
- * A simple example demonstrating the basic usage of an inlist can be found
- * here: @ref eina_inlist_01_example_page
- *
* @section inlist_algo Algorithm
*
* The basic structure can be represented by the following picture:
@@ -325,304 +59,274 @@
* @image rtf eina_inlist-node.png
* @image latex eina_inlist-node.eps
*
- * One data structure will also have the node information, with three pointers:
- * @a prev, @a next and @a last. The @a last pointer is just valid for the first
- * element (the list head), otherwise each insertion in the list would have to
- * be done updating every node with the correct pointer. This means that it's
- * always very important to keep a pointer to the first element of the list,
+ * One data structure also has node information with three pointers:
+ * @a prev, @a next, and @a last. The @a last pointer is just valid for the first
+ * element (the list head), otherwise each insertion in the list has to
+ * be done by updating every node with the correct pointer. This means that it's
+ * very important to keep a pointer to the first element of the list,
* since it is the only one that has the correct information to allow a proper
* O(1) append to the list.
*
* @section inlist_perf Performance
*
* Due to the nature of the inlist, there's no accounting information, and no
- * easy access to the last element from each list node. This means that @ref
+ * easy access to the last element of each list node. This means that @ref
* eina_inlist_count() is order-N, while @ref eina_list_count() is order-1 (constant
* time).
*
* @section inlist_advanced Advanced Usage
*
- * The basic usage considers a struct that will have the user data, and also
- * have an inlist node information (prev, next and last pointers) created with
- * @ref EINA_INLIST during the struct declaration. This allows one to use the
+ * The basic usage considers a struct that has the user data, and also
+ * has the inlist node information (prev, next, and last pointers) created with
+ * @ref EINA_INLIST during struct declaration. This allows one to use the
* convenience macros @ref EINA_INLIST_GET(), @ref EINA_INLIST_CONTAINER_GET(),
- * @ref EINA_INLIST_FOREACH() and so. This happens because the @ref EINA_INLIST
+ * @ref EINA_INLIST_FOREACH(), and so on. This happens because the @ref EINA_INLIST
* macro declares a struct member with the name @a __inlist, and all the other
* macros assume that this struct member has this name.
*
* It may be the case that someone needs to have some inlist nodes added to a
* @ref Eina_List too. If this happens, the inlist nodes can be added to the
- * @ref Eina_List without any problems. This example demonstrates this case:
- * @ref eina_inlist_02_example_page
- *
- * It's also possible to have some data that is part of two different inlists.
- * If this is the case, then it won't be possible to use the convenience macros
- * to both of the lists. It will be necessary to create a new set of macros that
- * will allow access to the second list node info. An example for this usage can
- * be found here:
- * @ref eina_inlist_03_example_page
- *
- * List of examples:
- * @li @ref eina_inlist_01_example_page
- * @li @ref eina_inlist_02_example_page
- * @li @ref eina_inlist_03_example_page
- */
-
-/**
- * @addtogroup Eina_Data_Types_Group Data Types
- *
- * @{
- */
-
-/**
- * @addtogroup Eina_Containers_Group Containers
+ * @ref Eina_List without any problem.
*
- * @{
- */
-
-/**
- * @defgroup Eina_Inline_List_Group Inline List
+ * It's also possible to have data that is part of two different inlists.
+ * If this is the case, then it won't be possible to use convenience macros
+ * for both of the lists. It is necessary to create a new set of macros that
+ * allow access to the second list node info.
*
* @{
*/
/**
* @typedef Eina_Inlist
- * Inlined list type.
+ * @brief The structure type for an inlined list type.
*/
typedef struct _Eina_Inlist Eina_Inlist;
/**
* @typedef Eina_Inlist_Sorted_State
+ * @brief The structure type for the state of a sorted Eina_Inlist.
* @since 1.1.0
- * State of sorted Eina_Inlist
*/
typedef struct _Eina_Inlist_Sorted_State Eina_Inlist_Sorted_State;
/**
* @struct _Eina_Inlist
- * Inlined list type.
+ * @brief The structure type for an Inlined list type.
*/
struct _Eina_Inlist
{
- Eina_Inlist *next; /**< next node */
- Eina_Inlist *prev; /**< previous node */
- Eina_Inlist *last; /**< last node */
+ Eina_Inlist *next; /**< Next node */
+ Eina_Inlist *prev; /**< Previous node */
+ Eina_Inlist *last; /**< Last node */
};
-/** Used for declaring an inlist member in a struct */
+/** Definition used for declaring an inlist member in a struct */
#define EINA_INLIST Eina_Inlist __in_list
-/** Utility macro to get the inlist object of a struct */
+/** Definition of the utility macro to get the inlist object of a struct */
#define EINA_INLIST_GET(Inlist) (& ((Inlist)->__in_list))
-/** Utility macro to get the container object of an inlist */
+/** Definition of the utility macro to get the container object of an inlist */
#define EINA_INLIST_CONTAINER_GET(ptr, \
type) ((type *)((char *)ptr - \
offsetof(type, __in_list)))
/**
- * Add a new node to end of a list.
+ * @brief Adds a new node to the end of a list.
+ *
+ * @details This code is meant to be fast: appends are O(1) and do not
+ * walk through @a in_list.
*
- * @note this code is meant to be fast: appends are O(1) and do not
- * walk @a in_list.
+ * @since_tizen 2.3
*
- * @note @a in_item is considered to be in no list. If it was in another
- * list before, eina_inlist_remove() it before adding. No
- * check of @a new_l prev and next pointers is done, so it's safe
- * to have them uninitialized.
+ * @remarks @a in_item is considered to be in no list. If it has been in another
+ * list before, eina_inlist_remove() it before adding. No
+ * check of @a new_l prev and next pointers is done, so it's safe
+ * to have them uninitialized.
*
- * @param in_list existing list head or @c NULL to create a new list.
- * @param in_item new list node, must not be @c NULL.
+ * @param[in] in_list The existing list head, otherwise @c NULL to create a new list
+ * @param[in] in_item new The list node, must not be @c NULL
*
- * @return the new list head. Use it and not @a in_list anymore.
+ * @return The new list head \n
+ * Use it and not @a in_list anymore.
*/
EAPI Eina_Inlist *eina_inlist_append(Eina_Inlist *in_list,
Eina_Inlist *in_item) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
/**
- * Add a new node to beginning of list.
+ * @brief Adds a new node to the beginning of the list.
*
- * @note this code is meant to be fast: appends are O(1) and do not
- * walk @a in_list.
+ * @details This code is meant to be fast: appends are O(1) and do not
+ * walk through @a in_list.
*
- * @note @a new_l is considered to be in no list. If it was in another
- * list before, eina_inlist_remove() it before adding. No
- * check of @a new_l prev and next pointers is done, so it's safe
- * to have them uninitialized.
+ * @since_tizen 2.3
*
- * @param in_list existing list head or @c NULL to create a new list.
- * @param in_item new list node, must not be @c NULL.
+ * @remarks @a new_l is considered to be in no list. If it has been in another
+ * list before, eina_inlist_remove() it before adding. No
+ * check of @a new_l prev and next pointers is done, so it's safe
+ * to have them uninitialized.
*
- * @return the new list head. Use it and not @a in_list anymore.
+ * @param[in] in_list The existing list head, otherwise @c NULL to create a new list
+ * @param[in] in_item The new list node, must not be @c NULL
+ *
+ * @return The new list head \n
+ * Use it and not @a in_list anymore.
*/
EAPI Eina_Inlist *eina_inlist_prepend(Eina_Inlist *in_list,
Eina_Inlist *in_item) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
/**
- * Add a new node after the given relative item in list.
+ * @brief Adds a new node after the given relative item in the list.
+ *
+ * @details This code is meant to be fast: appends are O(1) and do not
+ * walk through @a in_list.
*
- * @note this code is meant to be fast: appends are O(1) and do not
- * walk @a in_list.
+ * @since_tizen 2.3
*
- * @note @a in_item_l is considered to be in no list. If it was in another
- * list before, eina_inlist_remove() it before adding. No
- * check of @a in_item prev and next pointers is done, so it's safe
- * to have them uninitialized.
+ * @remarks @a in_item_l is considered to be in no list. If it has been in another
+ * list before, eina_inlist_remove() it before adding. No
+ * check of @a in_item prev and next pointers is done, so it's safe
+ * to have them uninitialized.
*
- * @note @a in_relative is considered to be inside @a in_list, no checks are
- * done to confirm that and giving nodes from different lists
- * will lead to problems. Giving NULL @a in_relative is the same as
- * eina_list_append().
+ * @remarks @a in_relative is considered to be inside @a in_list, no checks are
+ * done to confirm that and giving nodes from different lists
+ * leads to problems. Setting @a in_relative to @c NULL is the same as
+ * eina_list_append().
*
- * @param in_list existing list head or @c NULL to create a new list.
- * @param in_item new list node, must not be @c NULL.
- * @param in_relative reference node, @a in_item will be added after it.
+ * @param[in] in_list The existing list head, otherwise @c NULL to create a new list
+ * @param[in] in_item new The list node, must not be @c NULL
+ * @param[in] in_relative The reference node, @a in_item is added after it
*
- * @return the new list head. Use it and not @a list anymore.
+ * @return The new list head \n
+ * Use it and not @a list anymore.
*/
EAPI Eina_Inlist *eina_inlist_append_relative(Eina_Inlist *in_list,
Eina_Inlist *in_item,
Eina_Inlist *in_relative) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
/**
- * Add a new node before the given relative item in list.
+ * @brief Adds a new node before the given relative item in the list.
+ *
+ * @details This code is meant to be fast: appends are O(1) and do not
+ * walk through @a in_list.
*
- * @note this code is meant to be fast: appends are O(1) and do not
- * walk @a in_list.
+ * @since_tizen 2.3
*
- * @note @a in_item is considered to be in no list. If it was in another
- * list before, eina_inlist_remove() it before adding. No
- * check of @a in_item prev and next pointers is done, so it's safe
- * to have them uninitialized.
+ * @remarks @a in_item is considered to be in no list. If it has been in another
+ * list before, eina_inlist_remove() it before adding. No
+ * check of @a in_item prev and next pointers is done, so it's safe
+ * to have them uninitialized.
*
- * @note @a in_relative is considered to be inside @a in_list, no checks are
- * done to confirm that and giving nodes from different lists
- * will lead to problems. Giving NULL @a in_relative is the same as
- * eina_list_prepend().
+ * @remarks @a in_relative is considered to be inside @a in_list, no checks are
+ * done to confirm that and giving nodes from different lists
+ * leads to problems. Setting @a in_relative to @c NULL is the same as
+ * eina_list_prepend().
*
- * @param in_list existing list head or @c NULL to create a new list.
- * @param in_item new list node, must not be @c NULL.
- * @param in_relative reference node, @a in_item will be added before it.
+ * @param[in] in_list The existing list head, otherwise @c NULL to create a new list
+ * @param[in] in_item new The list node, must not be @c NULL
+ * @param[in] in_relative The reference node, @a in_item is added before it
*
- * @return the new list head. Use it and not @a in_list anymore.
+ * @return The new list head \n
+ * Use it and not @a in_list anymore.
*/
EAPI Eina_Inlist *eina_inlist_prepend_relative(Eina_Inlist *in_list,
Eina_Inlist *in_item,
Eina_Inlist *in_relative) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
/**
- * Remove node from list.
+ * @brief Removes a node from the list.
*
- * @note this code is meant to be fast: appends are O(1) and do not
- * walk @a list.
+ * @details This code is meant to be fast: appends are O(1) and do not
+ * walk through @a list.
*
- * @note @a in_item is considered to be inside @a in_list, no checks are
- * done to confirm that and giving nodes from different lists
- * will lead to problems, especially if @a in_item is the head since
- * it will be different from @a list and the wrong new head will
- * be returned.
+ * @since_tizen 2.3
*
- * @param in_list existing list head, must not be @c NULL.
- * @param in_item existing list node, must not be @c NULL.
+ * @remarks @a in_item is considered to be inside @a in_list, no checks are
+ * done to confirm that and giving nodes from different lists
+ * lead to problems, especially if @a in_item is the head since
+ * it is different from @a list and the wrong new head is
+ * returned.
*
- * @return the new list head. Use it and not @a list anymore.
+ * @param[in] in_list The existing list head, must not be @c NULL
+ * @param[in] in_item The existing list node, must not be @c NULL
+ *
+ * @return The new list head \n
+ * Use it and not @a list anymore.
*/
EAPI Eina_Inlist *eina_inlist_remove(Eina_Inlist *in_list,
Eina_Inlist *in_item) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT;
/**
- * Find given node in list, returns itself if found, NULL if not.
+ * @brief Finds a given node in the list, returns itself if found, @c NULL if not.
+ *
+ * @details This is an expensive call and has O(n) cost, possibly
+ * walking the whole list.
*
- * @warning this is an expensive call and has O(n) cost, possibly
- * walking the whole list.
+ * @since_tizen 2.3
*
- * @param in_list existing list to search @a in_item in, must not be @c NULL.
- * @param in_item what to search for, must not be @c NULL.
+ * @param[in] in_list The existing list to search @a in_item in, must not be @c NULL
+ * @param[in] in_item The item to search for, must not be @c NULL
*
- * @return @a in_item if found, @c NULL if not.
+ * @return @a in_item if found, @c NULL if not
*/
EAPI Eina_Inlist *eina_inlist_find(Eina_Inlist *in_list,
Eina_Inlist *in_item) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
/**
- * Move existing node to beginning of list.
+ * @brief Moves an existing node to the beginning of the list.
*
- * @note this code is meant to be fast: appends are O(1) and do not
- * walk @a list.
+ * @details This code is meant to be fast: appends are O(1) and do not
+ * walk through @a list.
*
- * @note @a item is considered to be inside @a list. No checks are
- * done to confirm this, and giving nodes from different lists
- * will lead to problems.
+ * @since_tizen 2.3
*
- * @param list existing list head or @c NULL to create a new list.
- * @param item list node to move to beginning (head), must not be @c NULL.
+ * @remarks @a item is considered to be inside @a list. No checks are
+ * done to confirm this, and giving nodes from different lists
+ * leads to problems.
*
- * @return the new list head. Use it and not @a list anymore.
+ * @param[in] list The existing list head, otherwise @c NULL to create a new list
+ * @param[in] item The list node to move to the beginning (head), must not be @c NULL
+ *
+ * @return The new list head \n
+ * Use it and not @a list anymore.
*/
EAPI Eina_Inlist *eina_inlist_promote(Eina_Inlist *list,
Eina_Inlist *item) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT;
/**
- * Move existing node to end of list.
+ * @brief Moves an existing node to the end of the list.
+ *
+ * @details This code is meant to be fast: appends are O(1) and do not
+ * walk through @a list.
*
- * @note this code is meant to be fast: appends are O(1) and do not
- * walk @a list.
+ * @since_tizen 2.3
*
- * @note @a item is considered to be inside @a list. No checks are
- * done to confirm this, and giving nodes from different lists
- * will lead to problems.
+ * @remarks @a item is considered to be inside @a list. No checks are
+ * done to confirm this, and giving nodes from different lists
+ * leads to problems.
*
- * @param list existing list head or @c NULL to create a new list.
- * @param item list node to move to end (tail), must not be @c NULL.
+ * @param[in] list The existing list head, otherwise @c NULL to create a new list
+ * @param[in] item The list node to move to the end (tail), must not be @c NULL
*
- * @return the new list head. Use it and not @a list anymore.
+ * @return The new list head \n
+ * Use it and not @a list anymore.
*/
EAPI Eina_Inlist *eina_inlist_demote(Eina_Inlist *list,
Eina_Inlist *item) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT;
/**
- * @brief Get the first list node in the list.
- *
- * @param list The list to get the first list node from.
- * @return The first list node in the list.
- *
- * This function returns the first list node in the list @p list. If
- * @p list is @c NULL, @c NULL is returned.
- *
- * This is a O(N) operation (it takes time proportional
- * to the length of the list).
- *
- * @since 1.8
- */
-static inline Eina_Inlist *eina_inlist_first(const Eina_Inlist *list) EINA_PURE EINA_WARN_UNUSED_RESULT;
-
-/**
- * @brief Get the last list node in the list.
- *
- * @param list The list to get the last list node from.
- * @return The last list node in the list.
- *
- * This function returns the last list node in the list @p list. If
- * @p list is @c NULL, @c NULL is returned.
+ * @brief Gets the count of the number of items in a list.
*
- * This is a O(N) operation (it takes time proportional
- * to the length of the list).
+ * @details This function returns the number of members that @a list contains. If the
+ * @a list is @c NULL, @c 0 is returned.
*
- * @since 1.8
- */
-static inline Eina_Inlist *eina_inlist_last(const Eina_Inlist *list) EINA_PURE EINA_WARN_UNUSED_RESULT;
-
-/**
- * @brief Get the count of the number of items in a list.
+ * @since_tizen 2.3
*
- * @param list The list whose count to return.
- * @return The number of members in the list.
+ * @remarks This is an order-N operation and so the time depends
+ * on the number of elements in the list, so it might become
+ * slow for big lists.
*
- * This function returns how many members @p list contains. If the
- * list is @c NULL, @c 0 is returned.
+ * @param[in] list The list whose count to return
+ * @return The number of members in the list
*
- * @warning This is an order-N operation and so the time will depend
- * on the number of elements on the list, so, it might become
- * slow for big lists!
*/
EAPI unsigned int eina_inlist_count(const Eina_Inlist *list) EINA_WARN_UNUSED_RESULT;
@@ -630,152 +334,178 @@ EAPI unsigned int eina_inlist_count(const Eina_Inlist *list) EINA_WARN_UNUSED_
/**
* @brief Returns a new iterator associated to @a list.
*
- * @param in_list The list.
- * @return A new iterator.
+ * @details This function returns a newly allocated iterator associated to @a
+ * in_list. If @a in_list is @c NULL or the count member of @a in_list is less than
+ * or equal to @c 0, this function still returns a valid iterator that
+ * always returns @c false on a call to eina_iterator_next(), thus keeping the API
+ * sane.
*
- * This function returns a newly allocated iterator associated to @p
- * in_list. If @p in_list is @c NULL or the count member of @p in_list is less
- * or equal than 0, this function still returns a valid iterator that
- * will always return false on eina_iterator_next(), thus keeping API
- * sane.
+ * @since_tizen 2.3
*
- * If the memory can not be allocated, @c NULL is returned.
- * Otherwise, a valid iterator is returned.
+ * @remarks If the memory cannot be allocated, @c NULL is returned
+ * and #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator
+ * is returned.
+ *
+ * @remarks If the list structure changes then the iterator becomes
+ * invalid, and if you add or remove nodes the iterator's
+ * behavior is undefined, and your program may crash.
+ *
+ * @param[in] in_list The list
+ * @return A new iterator
*
- * @warning if the list structure changes then the iterator becomes
- * invalid, and if you add or remove nodes iterator
- * behavior is undefined, and your program may crash!
*/
EAPI Eina_Iterator *eina_inlist_iterator_new(const Eina_Inlist *in_list) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
/**
- * @brief Returns a new accessor associated to a list.
+ * @brief Returns a new accessor associated to the list.
+ *
+ * @details This function returns a newly allocated accessor associated to
+ * @a in_list. If @a in_list is @c NULL or the count member of @a in_list is
+ * less than or equal to @c 0, this function returns @c NULL. If the memory cannot
+ * be allocated, @c NULL is returned and #EINA_ERROR_OUT_OF_MEMORY is
+ * set. Otherwise, a valid accessor is returned.
*
- * @param in_list The list.
- * @return A new accessor.
+ * @since_tizen 2.3
+ *
+ * @param[in] in_list The list
+ * @return A new accessor
*
- * This function returns a newly allocated accessor associated to
- * @p in_list. If @p in_list is @c NULL or the count member of @p in_list is
- * less or equal than @c 0, this function returns @c NULL. If the memory can
- * not be allocated, @c NULL is returned and Otherwise, a valid accessor is
- * returned.
*/
EAPI Eina_Accessor *eina_inlist_accessor_new(const Eina_Inlist *in_list) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
/**
- * @brief Insert a new node into a sorted list.
+ * @brief Inserts a new node into a sorted list.
+ *
+ * @details This function inserts items into a linked list assuming it is
+ * sorted and the result is sorted. If @a list is @c NULLL, @a item
+ * is returned. On success, a new list pointer that should be
+ * used in place of the one given to this function is
+ * returned. Otherwise, the old pointer is returned.
*
- * @param list The given linked list, @b must be sorted.
- * @param item list node to insert, must not be @c NULL.
- * @param func The function called for the sort.
- * @return A list pointer.
* @since 1.1.0
*
- * This function inserts item into a linked list assuming it was
- * sorted and the result will be sorted. If @p list is @c NULLL, item
- * is returned. On success, a new list pointer that should be
- * used in place of the one given to this function is
- * returned. Otherwise, the old pointer is returned.
- *
- * @note O(log2(n)) comparisons (calls to @p func) average/worst case
- * performance. As said in eina_list_search_sorted_near_list(),
- * lists do not have O(1) access time, so walking to the correct node
- * can be costly, consider worst case to be almost O(n) pointer
- * dereference (list walk).
+ * @since_tizen 2.3
+ *
+ * @remarks Average/worst case performance is O(log2(n)) comparisons (calls to @a func).
+ * As said in eina_list_search_sorted_near_list(),
+ * lists do not have O(1) access time, so walking to the correct node
+ * can be costly, consider worst case to be almost O(n) pointer
+ * dereference (list walk).
+ *
+ * @param[in] list The given linked list, @b must be sorted
+ * @param[in] item The list node to insert, must not be @c NULL
+ * @param[in] func The function called for the sort
+ * @return A list pointer
+ *
+ * @see eina_error_get()
*/
EAPI Eina_Inlist *eina_inlist_sorted_insert(Eina_Inlist *list, Eina_Inlist *item, Eina_Compare_Cb func) EINA_ARG_NONNULL(2, 3) EINA_WARN_UNUSED_RESULT;
/**
- * @brief Create state with valid data in it.
+ * @brief Creates a state with the valid data in it.
*
- * @return A valid Eina_Inlist_Sorted_State.
* @since 1.1.0
*
- * See eina_inlist_sorted_state_insert() for more information.
+ * @since_tizen 2.3
+ *
+ * @return A valid Eina_Inlist_Sorted_State
+ *
+ * @see eina_inlist_sorted_state_insert()
*/
EAPI Eina_Inlist_Sorted_State *eina_inlist_sorted_state_new(void);
/**
- * @brief Force an Eina_Inlist_Sorted_State to match the content of a list.
+ * @brief Forces an Eina_Inlist_Sorted_State to match the content of a list.
+ *
+ * @details This function is useful if you didn't use eina_inlist_sorted_state_insert() at any point,
+ * but still think you have a sorted list.
+ * It only works correctly on a sorted list.
*
- * @param state The state to update
- * @param list The list to match
- * @return The number of item in the actually in the list
* @since 1.1.0
*
- * See eina_inlist_sorted_state_insert() for more information. This function is
- * usefull if you didn't use eina_inlist_sorted_state_insert() at some point, but
- * still think you have a sorted list. It will only correctly work on a sorted list.
+ * @since_tizen 2.3
+ *
+ * @param[in] state The state to update
+ * @param[in] list The list to match
+ * @return The number of items that are actually in the list
+ *
+ * @see eina_inlist_sorted_state_insert()
*/
EAPI int eina_inlist_sorted_state_init(Eina_Inlist_Sorted_State *state, Eina_Inlist *list);
/**
- * @brief Free an Eina_Inlist_Sorted_State.
+ * @brief Frees an Eina_Inlist_Sorted_State.
*
- * @param state The state to destroy
* @since 1.1.0
*
- * See eina_inlist_sorted_state_insert() for more information.
+ * @since_tizen 2.3
+ *
+ * @param[in] state The state to destroy
+ *
+ * @see eina_inlist_sorted_state_insert()
*/
EAPI void eina_inlist_sorted_state_free(Eina_Inlist_Sorted_State *state);
/**
- * @brief Insert a new node into a sorted list.
+ * @brief Inserts a new node into a sorted list.
+ *
+ * @details This function inserts an item into a linked list assuming @a state matches
+ * the exact content order of the list. It uses @a state to do a fast
+ * first step dichotomic search before starting to walk through the inlist itself.
+ * This makes this code much faster than eina_inlist_sorted_insert() as it
+ * doesn't need to walk through the list at all. The result is of course a sorted
+ * list with an updated state.. If @a list is @c NULLL, @a item
+ * is returned. On success, a new list pointer that should be
+ * used in place of the one given to this function is
+ * returned. Otherwise, the old pointer is returned.
*
- * @param list The given linked list, @b must be sorted.
- * @param item list node to insert, must not be @c NULL.
- * @param func The function called for the sort.
- * @param state The current array for initial dichotomic search
- * @return A list pointer.
* @since 1.1.0
*
- * This function inserts item into a linked list assuming @p state match
- * the exact content order of the list. It use @p state to do a fast
- * first step dichotomic search before starting to walk the inlist itself.
- * This make this code much faster than eina_inlist_sorted_insert() as it
- * doesn't need to walk the list at all. The result is of course a sorted
- * list with an updated state.. If @p list is @c NULLL, item
- * is returned. On success, a new list pointer that should be
- * used in place of the one given to this function is
- * returned. Otherwise, the old pointer is returned.
- *
- * @note O(log2(n)) comparisons (calls to @p func) average/worst case
- * performance. As said in eina_list_search_sorted_near_list(),
- * lists do not have O(1) access time, so walking to the correct node
- * can be costly, but this version try to minimize that by making it a
- * O(log2(n)) for number small number. After n == 256, it start to add a
- * linear cost again. Consider worst case to be almost O(n) pointer
- * dereference (list walk).
+ * @since_tizen 2.3
+ *
+ * @remarks Average/worst case performance is O(log2(n)) comparisons (calls to @a func)
+ * As said in eina_list_search_sorted_near_list(),
+ * lists do not have O(1) access time, so walking to the correct node
+ * can be costly, but this version tries to minimize that by making it
+ * O(log2(n)) for a small number. After n == 256, it starts to add
+ * linear cost again. Consider worst case to be almost O(n) pointer
+ * dereference (list walk).
+ *
+ * @param[in] list The given linked list, @b must be sorted
+ * @param[in] item The list node to insert, must not be @c NULL
+ * @param[in] func The function called for the sort
+ * @param[in] state The current array for an initial dichotomic search
+ * @return A list pointer
+ *
+ *
+ * @see eina_error_get()
*/
EAPI Eina_Inlist *eina_inlist_sorted_state_insert(Eina_Inlist *list,
Eina_Inlist *item,
Eina_Compare_Cb func,
Eina_Inlist_Sorted_State *state);
/**
- * @brief Sort a list according to the ordering func will return.
+ * @brief Sorts a list according to the ordering that @a func returns.
*
- * @param head The list handle to sort.
- * @param func A function pointer that can handle comparing the list data
- * nodes.
- * @return the new head of list.
+ * @details This function sorts all the elements of @a head. @a func is used to
+ * compare two elements of @a head. If @a head or @a func is @c NULL,
+ * this function returns @c NULL.
*
- * This function sorts all the elements of @p head. @p func is used to
- * compare two elements of @p head. If @p head or @p func are @c NULL,
- * this function returns @c NULL.
+ * @since_tizen 2.3
*
- * @note @b in-place: this will change the given list, so you should
- * now point to the new list head that is returned by this function.
+ * @remarks @b in-place: This changes the given list, so you should
+ * now point to the new list head that is returned by this function.
*
- * @note Worst case is O(n * log2(n)) comparisons (calls to func()).
- * That means that for 1,000,000 list elements, sort will do 20,000,000
- * comparisons.
+ * @remarks Worst case is O(n * log2(n)) comparisons (calls to func()).
+ * That means, for 1,000,000 list elements, sort does 20,000,000
+ * comparisons.
*
* Example:
* @code
* typedef struct _Sort_Ex Sort_Ex;
* struct _Sort_Ex
* {
- * EINA_INLIST;
+ * INLIST;
* const char *text;
* };
*
@@ -794,21 +524,33 @@ EAPI Eina_Inlist *eina_inlist_sorted_state_insert(Eina_Inlist *list,
*
* list = eina_inlist_sort(list, sort_cb);
* @endcode
+ *
+ * @param[in] head The list handle to sort
+ * @param[in] func A function pointer that can handle comparing the list data nodes
+ *
+ * @return The new head of the list
+ *
*/
EAPI Eina_Inlist *eina_inlist_sort(Eina_Inlist *head, Eina_Compare_Cb func);
-/* This two macros are helpers for the _FOREACH ones, don't use them */
+/* These two macros are helpers for the _FOREACH ones, don't use them */
/**
* @def _EINA_INLIST_OFFSET
- * @param ref The reference to be used.
+ *
+ * @since_tizen 2.3
+ *
+ * @param ref The reference to be used
*/
#define _EINA_INLIST_OFFSET(ref) ((char *)&(ref)->__in_list - (char *)(ref))
#if !defined(__cplusplus)
/**
* @def _EINA_INLIST_CONTAINER
- * @param ref The reference to be used.
- * @param ptr The pointer to be used.
+ *
+ * @since_tizen 2.3
+ *
+ * @param ref The reference to be used
+ * @param ptr The pointer to be used
*/
#define _EINA_INLIST_CONTAINER(ref, ptr) (void *)((char *)(ptr) - \
_EINA_INLIST_OFFSET(ref))
@@ -817,15 +559,18 @@ EAPI Eina_Inlist *eina_inlist_sort(Eina_Inlist *head, Eina_Compare_Cb func);
* In C++ we can't assign a "type*" pointer to void* so we rely on GCC's typeof
* operator.
*/
-# define _EINA_INLIST_CONTAINER(ref, ptr) (__typeof__(ref))((char *)(ptr) - \
- _EINA_INLIST_OFFSET(ref))
+#define _EINA_INLIST_CONTAINER(ref, ptr) (typeof(ref))((char *)(ptr) - \
+ _EINA_INLIST_OFFSET(ref))
#endif
/**
* @def EINA_INLIST_FOREACH
- * @param list The list to iterate on.
- * @param it The pointer to the list item, i.e. a pointer to each item
- * that is part of the list.
+ *
+ * @since_tizen 2.3
+ *
+ * @param list The list to iterate on
+ * @param it A pointer to the list item, i.e. a pointer to each item
+ * that is a part of the list.
*/
#define EINA_INLIST_FOREACH(list, it) \
for (it = NULL, it = (list ? _EINA_INLIST_CONTAINER(it, list) : NULL); it; \
@@ -833,69 +578,37 @@ EAPI Eina_Inlist *eina_inlist_sort(Eina_Inlist *head, Eina_Compare_Cb func);
/**
* @def EINA_INLIST_FOREACH_SAFE
- * @param list The list to iterate on.
- * @param list2 Auxiliar Eina_Inlist variable so we can save the pointer to the
- * next element, allowing us to free/remove the current one. Note that this
- * macro is only safe if the next element is not removed. Only the current one
- * is allowed to be removed.
- * @param it The pointer to the list item, i.e. a pointer to each item
- * that is part of the list.
+ *
+ * @since_tizen 2.3
+ *
+ * @param list The list to iterate on
+ * @param list2 The auxiliar Eina_Inlist variable so we can save the pointer to the
+ * next element, allowing us to free/remove the current one \n
+ * Note that this macro is safe only if the next element is not removed \n
+ * Only the current one is allowed to be removed.
+ *
+ * @param it A pointer to the list item, i.e. a pointer to each item
+ * that is a part of the list
*/
#define EINA_INLIST_FOREACH_SAFE(list, list2, it) \
- for (it = NULL, it = (list ? _EINA_INLIST_CONTAINER(it, list) : NULL), list2 = it ? EINA_INLIST_GET(it)->next : NULL; \
+ for (it = NULL, it = (list ? _EINA_INLIST_CONTAINER(it, list) : NULL), list2 = it ? ((EINA_INLIST_GET(it) ? EINA_INLIST_GET(it)->next : NULL)) : NULL; \
it; \
it = NULL, it = list2 ? _EINA_INLIST_CONTAINER(it, list2) : NULL, list2 = list2 ? list2->next : NULL)
/**
* @def EINA_INLIST_REVERSE_FOREACH
- * @param list The list to traversed in reverse order.
- * @param it The pointer to the list item, i.e. a pointer to each item
- * that is part of the list.
+ *
+ * @since_tizen 2.3
+ *
+ * @param list The list to traverse in the reverse order
+ * @param it A pointer to the list item, i.e. a pointer to each item
+ * that is a part of the list
*/
#define EINA_INLIST_REVERSE_FOREACH(list, it) \
for (it = NULL, it = (list ? _EINA_INLIST_CONTAINER(it, list->last) : NULL); \
it; it = (EINA_INLIST_GET(it)->prev ? _EINA_INLIST_CONTAINER(it, EINA_INLIST_GET(it)->prev) : NULL))
/**
- * @def EINA_INLIST_REVERSE_FOREACH_FROM
- * @param list The last list to traversed in reverse order.
- * @param it The pointer to the list item, i.e. a pointer to each item
- * that is part of the list.
- * @see EINA_INLIST_REVERSE_FOREACH()
- * @since 1.8
- *
- * EINA_INLIST_REVERSE_FOREACH() starts from last list of the given list.
- * This starts from given list, not the last one.
- */
-#define EINA_INLIST_REVERSE_FOREACH_FROM(list, it) \
- for (it = NULL, it = (list ? _EINA_INLIST_CONTAINER(it, list) : NULL); \
- it; it = (EINA_INLIST_GET(it)->prev ? _EINA_INLIST_CONTAINER(it, EINA_INLIST_GET(it)->prev) : NULL))
-
-/**
- * @def EINA_INLIST_FREE
- * @param list The list to free.
- * @param it The pointer to the list item, i.e. a pointer to each item
- * that is part of the list.
- *
- * NOTE: it is the duty of the body loop to properly remove the item from the
- * inlist and free it. This function will turn into a infinite loop if you
- * don't remove all items from the list.
- * @since 1.8
- */
-#define EINA_INLIST_FREE(list, it) \
- for (it = (__typeof__(it)) list; list; it = (__typeof__(it)) list)
-
-#include "eina_inline_inlist.x"
-
-/**
- * @}
- */
-
-/**
- * @}
- */
-
-/**
* @}
*/
diff --git a/src/lib/eina/eina_iterator.h b/src/lib/eina/eina_iterator.h
index 291b98d66f..0ed573d9d3 100644
--- a/src/lib/eina/eina_iterator.h
+++ b/src/lib/eina/eina_iterator.h
@@ -1,14 +1,14 @@
/* EINA - EFL data type library
* Copyright (C) 2008 Cedric Bail
*
- * This library is free software; you can redistribute it and/or
+ * This library is a free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
@@ -25,147 +25,80 @@
#include "eina_magic.h"
/**
- * @page eina_iterator_example_page Eina_Iterator usage
- * @dontinclude eina_iterator_01.c
- *
- * As always when using eina we need to include it:
- * @skip #include
- * @until Eina.h
- *
- * Here we a declare an unimpressive @ref Eina_Each_Cb "function" that prints
- * some data:
- * @until }
- * @note Returning EINA_TRUE is important so we don't stop iterating over the
- * container.
- *
- * And here a more interesting function, it uses an iterator to print the
- * contents of a container. What's interesting about it is that it doesn't care
- * the type of container, it works for anything that can provide an iterator:
- * @until }
- *
- * And on to our main function were we declare some variables and initialize
- * eina, nothing too special:
- * @until eina_init
- *
- * Next we populate both an array and a list with our strings, for more details
- * see @ref eina_list_01_example_page and @ref eina_array_01_example_page :
- * @until }
- *
- * And now we create an array and because the first element of the container
- * doesn't interest us we skip it:
- * @until iterator_next
- *
- * Having our iterator now pointing to interesting data we go ahead and print:
- * @until print_eina_container
- *
- * As always once data with a structure we free it, but just because we can we
- * do it by asking the iterator for it's container, and then of course free the
- * iterator itself:
- * @until eina_iterator_free
- *
- * But so far you're not impressed in @ref eina_array_01_example_page an array is
- * also printed, so now we go to the cool stuff and use an iterator to do same
- * stuff to a list:
- * @until eina_iterator_free
- * @note The only significant diference to the block above is in the
- * function used to create the iterator.
- *
- * And now we free the list and shut eina down:
- * @until }
- */
-
-/**
- * @page eina_iterator_01_c Eina_Iterator usage
- * @page eina_iterator_01_c Eina_Iterator usage
- *
- * @include eina_iterator_01.c
- * @example eina_iterator_01.c
- */
-
-/**
- * @addtogroup Eina_Iterator_Group Iterator Functions
+ * @defgroup Eina_Iterator_Group Iterator Functions
+ * @ingroup Eina_Content_Access_Group Content
*
- * @brief These functions manage iterators on containers.
+ * @brief This group of functions manages iterators on containers.
*
* These functions allow to access elements of a container in a
* generic way, without knowing which container is used (a bit like
- * iterators in the C++ STL). Iterators only allows sequential access
- * (that is, from an element to the next one). For random access, see
+ * iterators in the C++ STL). Iterators only allow sequential access
+ * (that is, from one element to the next one). For random access, see
* @ref Eina_Accessor_Group.
*
* Getting an iterator to access elements of a given container is done through
* the functions of that particular container. There is no function to create
* a generic iterator as iterators absolutely depend on the container. This
- * means you won't find iterator creation function here, those can be found on
+ * means you won't find a iterator creation function here, those can be found on
* the documentation of the container type you're using. Though created with
* container specific functions iterators are always deleted with the same
* function: eina_iterator_free().
*
- * To get the data and iterate, use eina_iterator_next(). To call a function on
+ * To get data and iterate it, use eina_iterator_next(). To call a function on
* all the elements of a container, use eina_iterator_foreach().
- *
- * Here an @ref eina_iterator_example_page "example"
- */
-
-/**
- * @addtogroup Eina_Content_Access_Group Content Access
- *
- * @{
- */
-
-/**
- * @defgroup Eina_Iterator_Group Iterator Functions
*
* @{
*/
/**
* @typedef Eina_Iterator
- * Abstract type for iterators.
+ * @brief The structure type containing the abstract type for iterators.
*/
typedef struct _Eina_Iterator Eina_Iterator;
/**
* @typedef Eina_Iterator_Next_Callback
- * Type for a callback that returns the next element in a container.
+ * @brief The boolean type for a callback that returns the next element in a container.
*/
typedef Eina_Bool (*Eina_Iterator_Next_Callback)(Eina_Iterator *it, void **data);
/**
* @typedef Eina_Iterator_Get_Container_Callback
- * Type for a callback that returns the container.
+ * @brief Called to return the container.
*/
typedef void *(*Eina_Iterator_Get_Container_Callback)(Eina_Iterator *it);
/**
* @typedef Eina_Iterator_Free_Callback
- * Type for a callback that frees the container.
+ * @brief Called to free the container.
*/
typedef void (*Eina_Iterator_Free_Callback)(Eina_Iterator *it);
/**
* @typedef Eina_Iterator_Lock_Callback
- * Type for a callback that lock the container.
+ * @brief Called to lock the container.
*/
typedef Eina_Bool (*Eina_Iterator_Lock_Callback)(Eina_Iterator *it);
/**
* @struct _Eina_Iterator
- * structure of an iterator
+ * @brief The structure type of an iterator.
*
- * If creating an iterator remember to set the type using @ref EINA_MAGIC_SET.
+ * @internal
+ * @remarks When creating an iterator remember to set the type using #EINA_MAGIC_SET.
+ * @endinternal
*/
struct _Eina_Iterator
{
#define EINA_ITERATOR_VERSION 1
- int version; /**< Version of the Iterator API. */
+ int version; /**< Version of the Iterator API */
- Eina_Iterator_Next_Callback next EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT; /**< Callback called when a next element is requested. */
- Eina_Iterator_Get_Container_Callback get_container EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; /**< Callback called when the container is requested. */
- Eina_Iterator_Free_Callback free EINA_ARG_NONNULL(1); /**< Callback called when the container is freed. */
+ Eina_Iterator_Next_Callback next EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT; /**< Callback called when the next element is requested */
+ Eina_Iterator_Get_Container_Callback get_container EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; /**< Callback called when the container is requested */
+ Eina_Iterator_Free_Callback free EINA_ARG_NONNULL(1); /**< Callback called when the container is freed */
- Eina_Iterator_Lock_Callback lock EINA_WARN_UNUSED_RESULT; /**< Callback called when the container is locked. */
- Eina_Iterator_Lock_Callback unlock EINA_WARN_UNUSED_RESULT; /**< Callback called when the container is unlocked. */
+ Eina_Iterator_Lock_Callback lock EINA_WARN_UNUSED_RESULT; /**< Callback called when the container is locked */
+ Eina_Iterator_Lock_Callback unlock EINA_WARN_UNUSED_RESULT; /**< Callback called when the container is unlocked */
#define EINA_MAGIC_ITERATOR 0x98761233
EINA_MAGIC
@@ -173,79 +106,91 @@ struct _Eina_Iterator
/**
* @def FUNC_ITERATOR_NEXT(Function)
- * Helper macro to cast @p Function to a Eina_Iterator_Next_Callback.
+ * @brief Definition of a helper macro to cast @a Function to a Eina_Iterator_Next_Callback.
*/
#define FUNC_ITERATOR_NEXT(Function) ((Eina_Iterator_Next_Callback)Function)
/**
* @def FUNC_ITERATOR_GET_CONTAINER(Function)
- * Helper macro to cast @p Function to a Eina_Iterator_Get_Container_Callback.
+ * @brief Definition of a helper macro to cast @a Function to a Eina_Iterator_Get_Container_Callback.
*/
#define FUNC_ITERATOR_GET_CONTAINER(Function) ((Eina_Iterator_Get_Container_Callback)Function)
/**
* @def FUNC_ITERATOR_FREE(Function)
- * Helper macro to cast @p Function to a Eina_Iterator_Free_Callback.
+ * @brief Definition of a helper macro to cast @a Function to a Eina_Iterator_Free_Callback.
*/
#define FUNC_ITERATOR_FREE(Function) ((Eina_Iterator_Free_Callback)Function)
/**
* @def FUNC_ITERATOR_LOCK(Function)
- * Helper macro to cast @p Function to a Eina_Iterator_Lock_Callback.
+ * @brief Definition of a helper macro to cast @a Function to a Eina_Iterator_Lock_Callback.
*/
#define FUNC_ITERATOR_LOCK(Function) ((Eina_Iterator_Lock_Callback)Function)
/**
- * @brief Free an iterator.
+ * @brief Frees an iterator.
+ *
+ * @details This function frees @a iterator if it is not @c NULL.
+ *
+ * @since_tizen 2.3
*
- * @param iterator The iterator to free.
+ * @param[in] iterator The iterator to free
*
- * This function frees @p iterator if it is not @c NULL;
*/
EAPI void eina_iterator_free(Eina_Iterator *iterator);
/**
- * @brief Return the container of an iterator.
+ * @brief Gets the container of an iterator.
*
- * @param iterator The iterator.
- * @return The container which created the iterator.
+ * @details This function returns the container that created @a iterator. If
+ * @a iterator is @c NULL, this function returns @c NULL.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] iterator The iterator
+ * @return The container that created the iterator
*
- * This function returns the container which created @p iterator. If
- * @p iterator is @c NULL, this function returns @c NULL.
*/
EAPI void *eina_iterator_container_get(Eina_Iterator *iterator) EINA_ARG_NONNULL(1) EINA_PURE;
/**
- * @brief Return the value of the current element and go to the next one.
+ * @brief Returns the value of the current element and goes to the next one.
+ *
+ * @details This function returns the value of the current element pointed by
+ * @a iterator in @a data and then goes to the next element. If @a
+ * iterator is @c NULL or if a problem occurs, @c EINA_FALSE is
+ * returned, otherwise @c EINA_TRUE is returned.
*
- * @param iterator The iterator.
- * @param data The data of the element.
- * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
+ * @since_tizen 2.3
+ *
+ * @param[in] iterator The iterator
+ * @param[in] data The data of the element
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE
*
- * This function returns the value of the current element pointed by
- * @p iterator in @p data, then goes to the next element. If @p
- * iterator is @c NULL or if a problem occurred, #EINA_FALSE is
- * returned, otherwise #EINA_TRUE is returned.
*/
EAPI Eina_Bool eina_iterator_next(Eina_Iterator *iterator,
void **data) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
/**
- * @brief Iterate over the container and execute a callback on each element.
- *
- * @param iterator The iterator.
- * @param callback The callback called on each iteration.
- * @param fdata The data passed to the callback.
- *
- * This function iterates over the elements pointed by @p iterator,
- * beginning from the current element. For Each element, the callback
- * @p cb is called with the data @p fdata. If @p iterator is @c NULL,
- * the function returns immediately. Also, if @p cb returns #EINA_FALSE,
- * the iteration stops at that point, if @p cb returns #EINA_TRUE
- * the iteration continues.
+ * @brief Iterates over the container and executes a callback on each element.
+ *
+ * @details This function iterates over the elements pointed by @a iterator,
+ * beginning from the current element. For each element, the callback
+ * @a cb is called with the data @a fdata. If @a iterator is @c NULL,
+ * the function returns immediately. Also, if @a cb returns @c EINA_FALSE,
+ * the iteration stops at that point. If @a cb returns @c EINA_TRUE
+ * the iteration continues.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] iterator The iterator
+ * @param[in] callback The callback called on each iteration
+ * @param[in] fdata The data passed to the callback
+ *
*/
EAPI void eina_iterator_foreach(Eina_Iterator *iterator,
Eina_Each_Cb callback,
@@ -253,52 +198,55 @@ EAPI void eina_iterator_foreach(Eina_Iterator *iterator,
/**
- * @brief Lock the container of the iterator.
+ * @brief Locks the container of the iterator.
+ *
+ * @since_tizen 2.3
*
- * @param iterator The iterator.
- * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
+ * @remarks If the container of the @a iterator permits it, it is locked. When a
+ * container is locked by calling eina_iterator_foreach() on it, it returns
+ * immediately. If @a iterator is @c NULL or if a problem occurs, @c EINA_FALSE
+ * is returned, otherwise @c EINA_TRUE is returned. If the container isn't
+ * lockable, it returns @c EINA_TRUE.
*
- * If the container of the @p iterator permits it, it will be locked. When a
- * container is locked calling eina_iterator_foreach() on it will return
- * immediately. If @p iterator is @c NULL or if a problem occurred, #EINA_FALSE
- * is returned, otherwise #EINA_TRUE is returned. If the container isn't
- * lockable, it will return #EINA_TRUE.
+ * @remarks None of the existing eina data structures are lockable.
+ *
+ * @param[in] iterator The iterator
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE
*
- * @warning None of the existing eina data structures are lockable.
*/
EAPI Eina_Bool eina_iterator_lock(Eina_Iterator *iterator) EINA_ARG_NONNULL(1);
/**
- * @brief Unlock the container of the iterator.
+ * @brief Unlocks the container of the iterator.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks If the container of the @a iterator permits it and is previously
+ * locked, it is unlocked. If @a iterator is @c NULL or if a
+ * problem occurs, @c EINA_FALSE is returned, otherwise @c EINA_TRUE
+ * is returned. If the container is not lockable, it
+ * returns @c EINA_TRUE.
*
- * @param iterator The iterator.
- * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
+ * @remarks None of the existing eina data structures are lockable.
*
- * If the container of the @p iterator permits it and was previously
- * locked, it will be unlocked. If @p iterator is @c NULL or if a
- * problem occurred, #EINA_FALSE is returned, otherwise #EINA_TRUE
- * is returned. If the container is not lockable, it will
- * return #EINA_TRUE.
+ * @param[in] iterator The iterator
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE
*
- * @warning None of the existing eina data structures are lockable.
*/
EAPI Eina_Bool eina_iterator_unlock(Eina_Iterator *iterator) EINA_ARG_NONNULL(1);
/**
* @def EINA_ITERATOR_FOREACH
- * @brief Macro to iterate over all elements easily.
+ * @brief Definition of the macro to iterate over all the elements easily.
*
- * @param itr The iterator to use.
- * @param data Where to store * data, must be a pointer support getting
- * its address since * eina_iterator_next() requires a pointer
- * to pointer!
+ * @since_tizen 2.3
*
- * This macro is a convenient way to use iterators, very similar to
- * EINA_LIST_FOREACH().
+ * @details This macro is a convenient way to use iterators, very similar to
+ * EINA_LIST_FOREACH().
*
- * This macro can be used for freeing the data of a list, like in the
- * following example. It has the same goal as the one documented in
- * EINA_LIST_FOREACH(), but using iterators:
+ * @remarks This macro can be used for freeing the data of a list, like in the
+ * following example. It has the same goal as the one documented in
+ * EINA_LIST_FOREACH(), but using iterators:
*
* @code
* Eina_List *list;
@@ -315,19 +263,25 @@ EAPI Eina_Bool eina_iterator_unlock(Eina_Iterator *iterator) EINA_ARG_NONNULL(1)
* eina_list_free(list);
* @endcode
*
- * @note this example is not optimal algorithm to release a list since
- * it will walk the list twice, but it serves as an example. For
- * optimized version use EINA_LIST_FREE()
+ * @remarks This example is not an optimal algorithm to release a list as
+ * it walks through the list twice, but it serves as an example. For an
+ * optimized version use EINA_LIST_FREE().
+ *
+ * @remarks The order in which the elements are traversed depends on the
+ * underlying container and @b shouldn't be relied upon.
+ *
+ * @remarks Unless explicitly stated in the function's returning iterators,
+ * do not modify the iterated object while you walk through it. In this
+ * example using lists, do not remove the list nodes or the program might
+ * crash. This is not a limitation of the iterators themselves,
+ * but a limitation in the iterators implementations to keep them as simple
+ * and fast as possible.
*
- * @warning The order in which the elements will be traversed depends on the
- * underlying container and @b shouldn't be relied upon.
+ * @param itr The iterator to use
+ * @param data A pointer to store the data \n
+ * It must be a pointer to support getting
+ * its address since eina_iterator_next() requires a pointer.
*
- * @warning unless explicitly stated in functions returning iterators,
- * do not modify the iterated object while you walk it, in this
- * example using lists, do not remove list nodes or you might
- * crash! This is not a limitiation of iterators themselves,
- * rather in the iterators implementations to keep them as simple
- * and fast as possible.
*/
#define EINA_ITERATOR_FOREACH(itr, \
data) while (eina_iterator_next((itr), \
@@ -337,8 +291,4 @@ EAPI Eina_Bool eina_iterator_unlock(Eina_Iterator *iterator) EINA_ARG_NONNULL(1)
* @}
*/
-/**
- * @}
- */
-
#endif
diff --git a/src/lib/eina/eina_lalloc.h b/src/lib/eina/eina_lalloc.h
index 573562e601..f015d83dc6 100644
--- a/src/lib/eina/eina_lalloc.h
+++ b/src/lib/eina/eina_lalloc.h
@@ -1,14 +1,14 @@
/* EINA - EFL data type library
* Copyright (C) 2007-2008 Jorge Luis Zapata Muga
*
- * This library is free software; you can redistribute it and/or
+ * This library is a free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
@@ -22,38 +22,38 @@
#include "eina_types.h"
/**
- * @addtogroup Eina_Tools_Group Tools
- *
- * @{
- */
-
-/**
* @defgroup Eina_Lalloc_Group Lazy allocator
+ * @ingroup Eina_Tools_Group
+ *
+ * @brief This group provides lazy allocator functions.
*
* @{
*/
-/**
+/**
* @typedef Eina_Lalloc_Alloc
* Type definition for the callback used to allocate new items in a lazy allocator.
- *
*/
typedef Eina_Bool (*Eina_Lalloc_Alloc)(void *user_data, int num);
+
/**
* @def EINA_LALLOC_ALLOC
- * @param function The function to allocate.
+ *
+ * @since_tizen 2.3
+ *
+ * @param function The function to allocate
*/
#define EINA_LALLOC_ALLOC(function) ((Eina_Lalloc_Alloc)function)
-/**
+/**
* @typedef Eina_Lalloc_Free
- * Type definition for the callback used to allocate new items in a lazy allocator.
- *
+ *
+ * @brief Type definition for the callback used to allocate new items in a lazy allocator.
*/
typedef void (*Eina_Lalloc_Free)(void *user_data);
/**
* @def EINA_LALLOC_FREE
- * @param function The function to free.
+ * @param function The function to free
*/
#define EINA_LALLOC_FREE(function) ((Eina_Lalloc_Free)function)
@@ -67,11 +67,12 @@ typedef struct _Eina_Lalloc Eina_Lalloc;
/**
* @brief Create a new lazy allocator.
*
- * @param data The data for which memory will be allocated.
- * @param alloc_cb The callback to allocate memory for @p data items.
- * @param free_cb The callback to free memory for @p data items.
- * @param num_init The number of @p data items to initally allocate space for.
- *
+ * @since_tizen 2.3
+ *
+ * @param[in] data The data for which memory will be allocated.
+ * @param[in] alloc_cb The callback to allocate memory for @p data items.
+ * @param[in] free_cb The callback to free memory for @p data items.
+ * @param[in] num_init The number of @p data items to initally allocate space for.
* @return A new lazy allocator.
*
*/
@@ -79,34 +80,36 @@ EAPI Eina_Lalloc *eina_lalloc_new(void *data,
Eina_Lalloc_Alloc alloc_cb,
Eina_Lalloc_Free free_cb,
int num_init) EINA_ARG_NONNULL(2, 3);
-
+
/**
* @brief Free the resources for a lazy allocator.
*
- * @param a The lazy allocator to free.
+ * @since_tizen 2.3
*
+ * @param[in] a The lazy allocator to free.
*/
EAPI void eina_lalloc_free(Eina_Lalloc *a) EINA_ARG_NONNULL(1);
/**
* @brief Add several elements to a lazy allocator.
*
- * @param a The lazy allocater to add items to.
- * @param num The number of elements to add.
- *
- * @return EINA_TRUE on success, else EINA_FALSE.
+ * @since_tizen 2.3
*
+ * @param[in] a The lazy allocater to add items to.
+ * @param[in] num The number of elements to add.
+ * @return EINA_TRUE on success, else EINA_FALSE.
*/
EAPI Eina_Bool eina_lalloc_elements_add(Eina_Lalloc *a,
int num) EINA_ARG_NONNULL(1);
-
+
/**
* @brief Allocate one more of whatever the lazy allocator is allocating.
*
- * @param a The lazy allocator to add an item to.
- *
- * @return EINA_TRUE on success, else EINA_FALSE.
+ * @since_tizen 2.3
*
+ * @param[in] a The lazy allocator to add an item to.
+ *
+ * @return EINA_TRUE on success, else EINA_FALSE.
*/
EAPI Eina_Bool eina_lalloc_element_add(Eina_Lalloc *a) EINA_ARG_NONNULL(1);
@@ -114,8 +117,4 @@ EAPI Eina_Bool eina_lalloc_element_add(Eina_Lalloc *a) EINA_ARG_NONNULL(1);
* @}
*/
-/**
- * @}
- */
-
#endif /* EINA_LALLOC_H_ */
diff --git a/src/lib/eina/eina_list.h b/src/lib/eina/eina_list.h
index 91de6ea08c..bad591ed21 100644
--- a/src/lib/eina/eina_list.h
+++ b/src/lib/eina/eina_list.h
@@ -1,14 +1,14 @@
/* EINA - EFL data type library
* Copyright (C) 2002-2008 Carsten Haitzler, Vincent Torri, Jorge Luis Zapata Muga
*
- * This library is free software; you can redistribute it and/or
+ * This library is a free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
@@ -29,297 +29,69 @@
#include "eina_magic.h"
/**
- * @page eina_list_01_example_page Adding elements to Eina_List
- * @dontinclude eina_list_01.c
- *
- * Creating an @ref Eina_List and adding elements to it is very easy and can be
- * understood from an example:
- * First thing is always to include Eina.h, for this example we also
- * include stdio.h so we can use printf.
- * @skip #include
- * @until Eina.h
- *
- * Just some boilerplate code, declaring some variable and initializing eina.
- * @until eina_init
- * Here we add a sequence of elements to our list. By using append we add
- * elements to the end of the list, so the list will look like this:@n
- * @htmlonly
- * <img src="eina_list_example_01_a.png" style="max-width: 100%;" />
- * <a href="eina_list_example_01_a.png">Full-size</a>
- * @endhtmlonly
- * @image rtf eina_list_example_01_a.png
- * @image latex eina_list_example_01_a.eps "" width=\textwidth
- * @until roslin
- * There are a couple of interesting things happening here, first is that we are
- * passing a NULL pointer to the first @ref eina_list_append() call, when this
- * is done a list is created. The other @b very important detail to notice is
- * that the return value is attributed to the @a list variable, this needs to
- * be done every time we use a a function that alters the contents of the list.
- *
- * Now that we have a list with some elements in it we can look at its contents.
- * @until printf
- *
- * There are many ways of accessing elements in the list, including by its
- * index:
- * @until nth
- * @note It should be noted that the index starts at 0.
- *
- * @ref eina_list_append() is not the only way to add elements to a a list. A
- * common requirement is to add an element in a specific position this can be
- * accomplished using @ref eina_list_append_relative() and
- * @ref eina_list_append_relative_list():
- * @until zarek
- * First @a "cain" is added after the second element(remember that indexes are
- * 0 based) and then we add @a "zarek" after @a "cain".
- *
- * @ref Eina_List also has prepend analogs to append functions we have used so
- * far:
- * @until lampkin
- * With this additions our list now looks like this:@n
- * @htmlonly
- * <img src="eina_list_example_01_b.png" style="max-width: 100%;" />
- * <a href="eina_list_example_01_b.png">Full-size</a>
- * @endhtmlonly
- * @image rtf eina_list_example_01_b.png
- * @image latex eina_list_example_01_b.eps "" width=\textwidth
- *
- * Once done using the list it needs to be freed, and since we are done with
- * eina that also need to be shutdown:
- * @until }
- *
- * The full source code can be found on the examples folder
- * on the @ref eina_list_01_c "eina_list_01.c" file.
- */
-
-/**
- * @page eina_list_01_c Adding elements to Eina_List example
- *
- * @include eina_list_01.c
- * @example eina_list_01.c
- */
-
-/**
- * @page eina_list_02_example_page Sorting Eina_List elements
- * @dontinclude eina_list_02.c
- *
- * If you don't know how to create lists see
- * @ref eina_list_01_example_page.
- *
- * @skip #include
- * @until boomer
- * This is the code we have already seen to create a list. Now if we need to
- * search the list we can do it like this:
- * @until return
- *
- * However if searching the list multiple times it probably is better to sort
- * the list since the sorted_search functions are much faster:
- * @until return
- *
- * Once the list is sorted it's not a good idea to use append/prepend functions
- * since that would add the element in the wrong place, instead elements should
- * be added with @ref eina_list_sorted_insert():
- * @until sorted_insert
- *
- * A noteworthy use case is adding an element to a list only if it doesn't exist
- * already, this can accomplished by searching for the element that is closest
- * to what is being added, and if that doesn't match add:
- * @until append
- * @note @ref eina_list_search_sorted_near_list() will tell you not only the
- * nearest node to what was searched for but how it compares to your term, this
- * way it is easy to know if you have to add before or after that node.
- *
- * It is sometimes useful to get a portion of the list as another list, here we
- * take every element that comes after "boomer" and split it into "other_list":
- * @until split_list
- *
- * It is also possible to add entire lists of elements using
- * @ref eina_list_sorted_merge():
- * @until sorted_merge
- *
- * And as always release memory and shutdown eina before ending:
- * @until }
- *
- * The full source code can be found on the examples folder
- * on the @ref eina_list_02_c "eina_list_02.c" file.
- */
-
-/**
- * @page eina_list_02_c Sorting Eina_List elements example
+ * @defgroup Eina_List_Group List
+ * @ingroup Eina_Containers_Group
*
- * @include eina_list_02.c
- * @example eina_list_02.c
- */
-
-/**
- * @page eina_list_03_example_page Reordering Eina_List elements
- * @dontinclude eina_list_03.c
- *
- * If you don't know how to create lists see
- * @ref eina_list_01_example_page.
- *
- * We start out with code that should be familiar by now:
- * @skip #include
- * @until gemenon
- *
- * You can move elements around in a list using @ref eina_list_move() or using
- * @ref eina_list_promote_list() and @ref eina_list_demote_list() which move a
- * list node to the head and end of the list respectevely:
- * @until demote
- *
- * Removing elements from a list can be done with ease:
- * @until sagitarius
- *
- * To replace an element in the list it is not necessary to remove it and then
- * add with the new value, it is possible to just change the value of a node:
- * @until aquarius
- *
- * We will now take a peek to see if the list still has the right number of
- * elements:
- * @until printf
- *
- * Now that the list is in alphabetical order let's create a copy of it in
- * reverse order and print every element to see if worked as expected:
- * @until iterator_free
- * @note Always remember to free your iterators when done using them.
- *
- * And as always release memory and shutdown eina before ending:
- * @until }
- *
- * The full source code can be found on the examples folder
- * on the @ref eina_list_03_c "eina_list_03.c" file.
- */
-
-/**
- * @page eina_list_03_c Reordering Eina_List elements example
+ * @brief This group discusses the functions that provide double linked list management.
*
- * @include eina_list_03.c
- * @example eina_list_03.c
- */
-
-/**
- * @page eina_list_04_example_page Eina_List and memory allocation
- * @dontinclude eina_list_04.c
- *
- * If you don't know how to create lists see
- * @ref eina_list_01_example_page. In this example we also use
- * @ref Eina_Stringshare_Group, however it should be possible to understand the code
- * regardless of previous knowledge about it.
- *
- * Here we have the usual list creation code with a twist, now we are using as
- * data for the list memory that has to be freed later on.
- * @skip #include
- * @until Sharon
- *
- * This time we are going to iterate over our list in a different way:
- * @until printf
- *
- * And now we are going to iterate over the list backwards:
- * @until printf
- *
- * And now we need to free up the memory allocated during creation of the list:
- * @until stringshare_del
- * @note We don't need to use eina_list_free() since @ref EINA_LIST_FREE takes
- * care of that.
- *
- * And shut everything down:
- * @until }
- *
- * The full source code can be found on the examples folder
- * on the @ref eina_list_04_c "eina_list_04.c" file.
- */
-
-/**
- * @page eina_list_04_c Eina_List and memory allocation example
+ * @remarks Eina_List is a doubly linked list. It can store data of any type in the
+ * form of void pointers. It has convenience functions to do all the common
+ * operations, which means it should rarely, if ever, be necessary to directly
+ * access the struct's fields. Nevertheless it can be useful to understand the
+ * inner workings of the data structure being used.
*
- * @include eina_list_04.c
- * @example eina_list_04.c
- */
-
-/**
- * @addtogroup Eina_List_Group List
- *
- * @brief These functions provide double linked list management.
- *
- * Eina_List is a doubly linked list. It can store data of any type in the
- * form of void pointers. It has convenience functions to do all the common
- * operations which means it should rarely if ever be necessary to directly
- * access the struct's fields. Nevertheless it can be useful to understand the
- * inner workings of the data structure being used.
- *
- * @ref Eina_List nodes keep references to the previous node, the next node, its
- * data and to an accounting structure.
+ * @remarks @ref Eina_List nodes keep references to the previous node, the next node, its
+ * data, and to an accounting structure.
*
+ * @image html eina_list.png
* @htmlonly
- * <img src="eina_list.png" style="max-width: 100%;" />
* <a href="eina_list.png">Full-size</a>
* @endhtmlonly
* @image rtf eina_list.png
* @image latex eina_list.eps width=5cm
*
- * @ref Eina_List_Accounting is used to improve the performance of some
- * functions. It is private and <b>should not</b> be modified. It contains a
- * reference to the end of the list and the number of elements in the list.
- *
- * @note Every function that modifies the contents of the list returns a pointer
- * to the head of the list and it is essential that this be pointer be used in
- * any future references to the list.
- *
- * Most functions have two versions that have the same effect but operate on
- * different arguments, the @a plain functions operate over data(eg.:
- * @ref eina_list_append_relative, @ref eina_list_remove,
- * @ref eina_list_data_find), the @a list versions of these functions operate
- * on @ref Eina_List nodes.
- *
- * @warning You must @b always use the pointer to the first element of the list
- * as the list!
- * @warning You must @b never use a pointer to an element in the middle of the
- * list as the list!
- *
- * Here are some examples of @ref Eina_List usage:
- * @li @ref eina_list_01_example_page
- * @li @ref eina_list_02_example_page
- * @li @ref eina_list_03_example_page
- * @li @ref eina_list_04_example_page
- */
-
-/**
- * @addtogroup Eina_Data_Types_Group Data Types
+ * @remarks @ref Eina_List_Accounting is used to improve the performance of some
+ * functions. It is private and <b>should not</b> be modified. It contains a
+ * reference to the end of the list and the number of elements in the list.
*
- * @{
- */
-
-/**
- * @addtogroup Eina_Containers_Group Containers
+ * @remarks Every function that modifies the contents of the list returns a pointer
+ * to the head of the list and it is essential that this pointer be used in
+ * any future references to the list.
*
- * @{
- */
-
-/**
- * @defgroup Eina_List_Group List
+ * @remarks Most functions have two versions that have the same effect but operate on
+ * different arguments, the @a plain functions operate over data(eg.:
+ * @ref eina_list_append_relative, @ref eina_list_remove,
+ * @ref eina_list_data_find), the @a list versions of these functions operate
+ * on @ref Eina_List nodes.
+ *
+ * @remarks You must @b always use the pointer to the first element of the list,
+ * as the list.
+ * @remarks You must @b never use a pointer to an element in the middle of the
+ * list, as the list.
*
* @{
*/
/**
* @typedef Eina_List
- * Type for a generic double linked list.
+ * @brief The structure type for a generic double linked list.
*/
typedef struct _Eina_List Eina_List;
/**
* @typedef Eina_List_Accounting
- * Cache used to store the last element of a list and the number of
- * elements, for fast access.
+ * @brief The structure type of the cache used to store the last element of a list and the number of
+ * elements, for fast access.
*/
typedef struct _Eina_List_Accounting Eina_List_Accounting;
/**
* @struct _Eina_List
- * Type for a generic double linked list.
+ * @brief The structure type for a generic double linked list.
*/
struct _Eina_List
{
- void *data; /**< Pointer to list element payload */
+ void *data; /**< Pointer to the list element payload */
Eina_List *next; /**< Next member in the list */
Eina_List *prev; /**< Previous member in the list */
Eina_List_Accounting *accounting; /**< Private list accounting info - don't touch */
@@ -329,41 +101,49 @@ struct _Eina_List
/**
* @struct _Eina_List_Accounting
- * Cache used to store the last element of a list and the number of
- * elements, for fast access. It is for private used and must not be
- * touched.
+ * @brief The structure type for the cache used to store the last element of a list and the number of
+ * elements, for fast access. It is for private use and must not be
+ * touched.
*/
struct _Eina_List_Accounting
{
Eina_List *last; /**< Pointer to the last element of the list - don't touch */
- unsigned int count; /**< Number of elements of the list - don't touch */
+ unsigned int count; /**< Number of elements in the list - don't touch */
EINA_MAGIC
};
/**
- * @brief Append the given data to the given linked list.
+ * @brief Appends the given data to the given linked list.
*
- * @param list The given list.
- * @param data The data to append.
- * @return A list pointer.
+ * @details This function appends @a data to @a list. If @a list is @c NULL, a
+ * new list is returned. On success, a new list pointer that should be
+ * used in place of the one given to this function is
+ * returned. Otherwise, the old pointer is returned.
*
- * This function appends @p data to @p list. If @p list is @c NULL, a
- * new list is returned. On success, a new list pointer that should be
- * used in place of the one given to this function is
- * returned. Otherwise, the old pointer is returned.
+ * @since_tizen 2.3
*
- * The following example code demonstrates how to ensure that the
- * given data has been successfully appended.
+ * @remarks The following example code demonstrates how to ensure that the
+ * given data has been successfully appended.
*
* @code
* Eina_List *list = NULL;
* extern void *my_data;
*
* list = eina_list_append(list, my_data);
+ * if (eina_error_get())
+ * {
+ * fprintf(stderr, "ERROR: Memory is low. List allocation failed.\n");
+ * exit(-1);
+ * }
* @endcode
*
- * @warning @p list must be a pointer to the first element of the list(or NULL).
+ * @remarks @a list must be a pointer to the first element of the list(or NULL).
+ *
+ * @param[in] list The given list
+ * @param[in] data The data to append
+ * @return A list pointer
+ *
*/
EAPI Eina_List *eina_list_append(Eina_List *list, const void *data) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
@@ -371,17 +151,15 @@ EAPI Eina_List *eina_list_append(Eina_List *list, const void *data) E
/**
* @brief Prepends the given data to the given linked list.
*
- * @param list The given list.
- * @param data The data to prepend.
- * @return A list pointer.
+ * @details This function prepends @a data to @a list. If @a list is @c NULL, a
+ * new list is returned. On success, a new list pointer that should be
+ * used in place of the one given to this function is
+ * returned. Otherwise, the old pointer is returned.
*
- * This function prepends @p data to @p list. If @p list is @c NULL, a
- * new list is returned. On success, a new list pointer that should be
- * used in place of the one given to this function is
- * returned. Otherwise, the old pointer is returned.
+ * @since_tizen 2.3
*
- * The following example code demonstrates how to ensure that the
- * given data has been successfully prepended.
+ * @remarks The following example code demonstrates how to ensure that the
+ * given data has been successfully prepended.
*
* Example:
* @code
@@ -389,31 +167,38 @@ EAPI Eina_List *eina_list_append(Eina_List *list, const void *data) E
* extern void *my_data;
*
* list = eina_list_prepend(list, my_data);
+ * if (eina_error_get())
+ * {
+ * fprintf(stderr, "ERROR: Memory is low. List allocation failed.\n");
+ * exit(-1);
+ * }
* @endcode
*
- * @warning @p list must be a pointer to the first element of the list.
+ * @remarks @a list must be a pointer to the first element of the list.
+ *
+ * @param[in] list The given list
+ * @param[in] data The data to prepend.
+ * @return A list pointer
+ *
*/
EAPI Eina_List *eina_list_prepend(Eina_List *list, const void *data) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
/**
- * @brief Insert the given data into the given linked list after the specified data.
+ * @brief Inserts the given data into the given linked list after the specified data.
*
- * @param list The given linked list.
- * @param data The data to insert.
- * @param relative The data to insert after.
- * @return A list pointer.
+ * @details This function inserts @a data to @a list after @a relative. If
+ * @a relative is not in the list, @a data is appended to the end of
+ * the list. If @a list is @c NULL, a new list is returned. If there
+ * are multiple instances of @a relative in the list, @a data is
+ * inserted after the first instance.On success, a new list pointer
+ * that should be used in place of the one given to this function is
+ * returned. Otherwise, the old pointer is returned.
*
- * This function inserts @p data to @p list after @p relative. If
- * @p relative is not in the list, @p data is appended to the end of
- * the list. If @p list is @c NULL, a new list is returned. If there
- * are multiple instances of @p relative in the list, @p data is
- * inserted after the first instance.On success, a new list pointer
- * that should be used in place of the one given to this function is
- * returned. Otherwise, the old pointer is returned.
+ * @since_tizen 2.3
*
- * The following example code demonstrates how to ensure that the
- * given data has been successfully inserted.
+ * @remarks The following example code demonstrates how to ensure that the
+ * given data has been successfully inserted.
*
* @code
* Eina_List *list = NULL;
@@ -421,54 +206,70 @@ EAPI Eina_List *eina_list_prepend(Eina_List *list, const void *data)
* extern void *relative_member;
*
* list = eina_list_append(list, relative_member);
+ * if (eina_error_get())
+ * {
+ * fprintf(stderr, "ERROR: Memory is low. List allocation failed.\n");
+ * exit(-1);
+ * }
* list = eina_list_append_relative(list, my_data, relative_member);
+ * if (eina_error_get())
+ * {
+ * fprintf(stderr, "ERROR: Memory is low. List allocation failed.\n");
+ * exit(-1);
+ * }
* @endcode
*
- * @warning @p list must be a pointer to the first element of the list.
+ * @remarks @a list must be a pointer to the first element of the list.
+ *
+ * @param[in] list The given linked list
+ * @param[in] data The data to insert
+ * @param[in] relative The data to insert after
+ * @return A list pointer
+ *
*/
EAPI Eina_List *eina_list_append_relative(Eina_List *list, const void *data, const void *relative) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
/**
- * @brief Append a list node to a linked list after the specified member
- *
- * @param list The given linked list.
- * @param data The data to insert.
- * @param relative The list node to insert after.
- * @return A list pointer.
- *
- * This function inserts @p data to @p list after the list node
- * @p relative. If @p list or @p relative are @c NULL, @p data is just
- * appended to @p list using eina_list_append(). If @p list is
- * @c NULL, a new list is returned. If there are multiple instances
- * of @p relative in the list, @p data is inserted after the first
- * instance. On success, a new list pointer that should be used in
- * place of the one given to this function is returned. Otherwise, the
- * old pointer is returned.
- *
- * @warning @p list must be a pointer to the first element of the list.
+ * @brief Appends a list node to a linked list after the specified member.
+ *
+ * @details This function inserts @a data to @a list after the list node
+ * @a relative. If @a list or @a relative is @c NULL, @a data is just
+ * appended to @a list using eina_list_append(). If @a list is
+ * @c NULL, a new list is returned. If there are multiple instances
+ * of @a relative in the list, @a data is inserted after the first
+ * instance. On success, a new list pointer that should be used in
+ * place of the one given to this function is returned. Otherwise, the
+ * old pointer is returned.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks @a list must be a pointer to the first element of the list.
+ *
+ * @param[in] list The given linked list
+ * @param[in] data The data to insert
+ * @param[in] relative The list node to insert after
+ * @return A list pointer
+ *
*/
EAPI Eina_List *eina_list_append_relative_list(Eina_List *list, const void *data, Eina_List *relative) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
/**
- * @brief Prepend a data pointer to a linked list before the specified member
+ * @brief Prepends a data pointer to a linked list before the specified member.
*
- * @param list The given linked list.
- * @param data The data to insert.
- * @param relative The data to insert before.
- * @return A list pointer.
+ * @details This function inserts @a data to @a list before @a relative. If
+ * @a relative is not in the list, @a data is prepended to the list
+ * with eina_list_prepend(). If @a list is @c NULL, a new list is
+ * returned. If there are multiple instances of @a relative in the
+ * list, @a data is inserted before the first instance. On success, a
+ * new list pointer that should be used in place of the one given to
+ * this function is returned. Otherwise, the old pointer is returned.
*
- * This function inserts @p data to @p list before @p relative. If
- * @p relative is not in the list, @p data is prepended to the list
- * with eina_list_prepend(). If @p list is @c NULL, a new list is
- * returned. If there are multiple instances of @p relative in the
- * list, @p data is inserted before the first instance. On success, a
- * new list pointer that should be used in place of the one given to
- * this function is returned. Otherwise, the old pointer is returned.
+ * @since_tizen 2.3
*
- * The following code example demonstrates how to ensure that the
- * given data has been successfully inserted.
+ * @remarks The following code example demonstrates how to ensure that the
+ * given data has been successfully inserted.
*
* @code
* Eina_List *list = NULL;
@@ -476,97 +277,121 @@ EAPI Eina_List *eina_list_append_relative_list(Eina_List *list, const
* extern void *relative_member;
*
* list = eina_list_append(list, relative_member);
+ * if (eina_error_get_error())
+ * {
+ * fprintf(stderr, "ERROR: Memory is low. List allocation failed.\n");
+ * exit(-1);
+ * }
* list = eina_list_prepend_relative(list, my_data, relative_member);
+ * if (eina_error_get())
+ * {
+ * fprintf(stderr, "ERROR: Memory is low. List allocation failed.\n");
+ * exit(-1);
+ * }
* @endcode
*
- * @warning @p list must be a pointer to the first element of the list.
+ * @remarks @a list must be a pointer to the first element of the list.
+ *
+ * @param[in] list The given linked list
+ * @param[in] data The data to insert
+ * @param[in] relative The data to insert before
+ * @return A list pointer
+ *
*/
EAPI Eina_List *eina_list_prepend_relative(Eina_List *list, const void *data, const void *relative) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
/**
- * @brief Prepend a list node to a linked list before the specified member
- *
- * @param list The given linked list.
- * @param data The data to insert.
- * @param relative The list node to insert before.
- * @return A list pointer.
- *
- * This function inserts @p data to @p list before the list node
- * @p relative. If @p list or @p relative are @c NULL, @p data is just
- * prepended to @p list using eina_list_prepend(). If @p list is
- * @c NULL, a new list is returned. If there are multiple instances
- * of @p relative in the list, @p data is inserted before the first
- * instance. On success, a new list pointer that should be used in
- * place of the one given to this function is returned. Otherwise, the
- * old pointer is returned.
- *
- * @warning @p list must be a pointer to the first element of the list.
+ * @brief Prepends a list node to a linked list before the specified member.
+ *
+ * @details This function inserts @a data to @a list before the list node
+ * @a relative. If @a list or @a relative is @c NULL, @a data is just
+ * prepended to @a list using eina_list_prepend(). If @a list is
+ * @c NULL, a new list is returned. If there are multiple instances
+ * of @a relative in the list, @a data is inserted before the first
+ * instance. On success, a new list pointer that should be used in
+ * place of the one given to this function is returned. Otherwise, the
+ * old pointer is returned.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks @a list must be a pointer to the first element of the list.
+ *
+ * @param[in] list The given linked list
+ * @param[in] data The data to insert
+ * @param[in] relative The list node to insert before
+ * @return A list pointer
+ *
*/
EAPI Eina_List *eina_list_prepend_relative_list(Eina_List *list, const void *data, Eina_List *relative) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
/**
- * @brief Insert a new node into a sorted list.
- *
- * @param list The given linked list, @b must be sorted.
- * @param func The function called for the sort.
- * @param data The data to insert sorted.
- * @return A list pointer.
- *
- * This function inserts values into a linked list assuming it was
- * sorted and the result will be sorted. If @p list is @c NULLL, a new
- * list is returned. On success, a new list pointer that should be
- * used in place of the one given to this function is
- * returned. Otherwise, the old pointer is returned.
- *
- * @note O(log2(n)) comparisons (calls to @p func) average/worst case
- * performance as it uses eina_list_search_sorted_near_list() and thus
- * is bounded to that. As said in eina_list_search_sorted_near_list(),
- * lists do not have O(1) access time, so walking to the correct node
- * can be costly, consider worst case to be almost O(n) pointer
- * dereference (list walk).
- *
- * @warning @p list must be a pointer to the first element of the list.
+ * @brief Inserts a new node into a sorted list.
+ *
+ * @details This function inserts values into a linked list assuming it is
+ * sorted and the result is sorted. If @a list is @c NULLL, a new
+ * list is returned. On success, a new list pointer that should be
+ * used in place of the one given to this function is
+ * returned. Otherwise, the old pointer is returned.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Average/worst case performance is O(log2(n)) comparisons (calls to @a func)
+ * as it uses eina_list_search_sorted_near_list() and thus
+ * is bounded to that. As said in eina_list_search_sorted_near_list(),
+ * lists do not have O(1) access time, so walking to the correct node
+ * can be costly, consider worst case to be almost O(n) pointer
+ * dereference (list walk).
+ *
+ * @remarks @a list must be a pointer to the first element of the list.
+ *
+ * @param[in] list The given linked list, @b must be sorted
+ * @param[in] func The function called for the sort
+ * @param[in] data The data to insert in the sorted list
+ * @return A list pointer
+ *
+ * @see eina_error_get()
*/
EAPI Eina_List *eina_list_sorted_insert(Eina_List *list, Eina_Compare_Cb func, const void *data) EINA_ARG_NONNULL(2, 3) EINA_WARN_UNUSED_RESULT;
/**
- * @brief Remove the first instance of the specified data from the given list.
+ * @brief Removes the first instance of the specified data from the given list.
+ *
+ * @details This function removes the first instance of @a data from
+ * @a list. If the specified data is not in the given list (this
+ * includes the case where @a data is @c NULL), nothing is done and the
+ * specified @a list is returned. If @a list is @c NULL, @c NULL is returned,
+ * otherwise a new list pointer that should be used in place of the one
+ * passed to this function is returned.
+ *
+ * @since_tizen 2.3
*
- * @param list The given list.
- * @param data The specified data.
- * @return A list pointer.
+ * @remarks @a list must be a pointer to the first element of the list.
*
- * This function removes the first instance of @p data from
- * @p list. If the specified data is not in the given list (this
- * includes the case where @p data is @c NULL), nothing is done and the
- * specified @p list returned. If @p list is @c NULL, @c NULL is returned,
- * otherwise a new list pointer that should be used in place of the one
- * passed to this function.
+ * @param[in] list The given list
+ * @param[in] data The specified data
+ * @return A list pointer
*
- * @warning @p list must be a pointer to the first element of the list.
*/
EAPI Eina_List *eina_list_remove(Eina_List *list, const void *data) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
/**
- * @brief Remove the specified list node.
+ * @brief Removes the specified list node.
*
- * @param list The given linked list.
- * @param remove_list The list node which is to be removed.
- * @return A list pointer.
+ * @details This function removes the list node @a remove_list from @a list and
+ * frees the list node structure @a remove_list. If @a list is
+ * @c NULL, this function returns @c NULL. If @a remove_list is
+ * @c NULL, it returns @a list, otherwise, a new list pointer that
+ * should be used in place of the one passed to this function is returned.
*
- * This function removes the list node @p remove_list from @p list and
- * frees the list node structure @p remove_list. If @p list is
- * @c NULL, this function returns @c NULL. If @p remove_list is
- * @c NULL, it returns @p list, otherwise, a new list pointer that
- * should be used in place of the one passed to this function.
+ * @since_tizen 2.3
*
- * The following code gives an example (notice we use EINA_LIST_FOREACH
- * instead of EINA_LIST_FOREACH_SAFE because we stop the loop after
- * removing the current node).
+ * @remarks The following code gives an example (notice we use EINA_LIST_FOREACH
+ * instead of EINA_LIST_FOREACH_SAFE because we stop the loop after
+ * removing the current node).
*
* @code
* extern Eina_List *list;
@@ -576,30 +401,33 @@ EAPI Eina_List *eina_list_remove(Eina_List *list, const void *data) E
*
* EINA_LIST_FOREACH(list, l, data)
* {
- * if (data == my_data)
- * {
- * list = eina_list_remove_list(list, l);
- * break;
- * }
+ * if (data == my_data)
+ * {
+ * list = eina_list_remove_list(list, l);
+ * break;
+ * }
* }
* @endcode
*
- * @warning @p list must be a pointer to the first element of the list.
+ * @remarks @a list must be a pointer to the first element of the list.
+ *
+ * @param[in] list The given linked list
+ * @param[in] remove_list The list node to be removed
+ * @return A list pointer
+ *
*/
EAPI Eina_List *eina_list_remove_list(Eina_List *list, Eina_List *remove_list) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
/**
- * @brief Move the specified data to the head of the list.
+ * @brief Moves the specified data to the head of the list.
*
- * @param list The list handle to move the data.
- * @param move_list The list node to move.
- * @return A new list handle to replace the old one
+ * @details This function moves @a move_list to the front of @a list. If the list is
+ * @c NULL, @c NULL is returned. If @a move_list is @c NULL,
+ * @a list is returned. Otherwise, a new list pointer that should be
+ * used in place of the one passed to this function is returned.
*
- * This function move @p move_list to the front of @p list. If list is
- * @c NULL, @c NULL is returned. If @p move_list is @c NULL,
- * @p list is returned. Otherwise, a new list pointer that should be
- * used in place of the one passed to this function.
+ * @since_tizen 2.3
*
* Example:
* @code
@@ -610,30 +438,33 @@ EAPI Eina_List *eina_list_remove_list(Eina_List *list, Eina_List *rem
*
* EINA_LIST_FOREACH(list, l, data)
* {
- * if (data == my_data)
- * {
- * list = eina_list_promote_list(list, l);
- * break;
- * }
+ * if (data == my_data)
+ * {
+ * list = eina_list_promote_list(list, l);
+ * break;
+ * }
* }
* @endcode
*
- * @warning @p list must be a pointer to the first element of the list.
+ * @remarks @a list must be a pointer to the first element of the list.
+ *
+ * @param[in] list The list handle to move the data
+ * @param[in] move_list The list node to move
+ * @return A new list handle to replace the old one
+ *
*/
EAPI Eina_List *eina_list_promote_list(Eina_List *list, Eina_List *move_list) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
/**
- * @brief Move the specified data to the tail of the list.
+ * @brief Moves the specified data to the tail of the list.
*
- * @param list The list handle to move the data.
- * @param move_list The list node to move.
- * @return A new list handle to replace the old one
+ * @details This function moves @a move_list to the back of @a list. If the list is
+ * @c NULL, @c NULL is returned. If @a move_list is @c NULL,
+ * @a list is returned. Otherwise, a new list pointer that should be
+ * used in place of the one passed to this function is returned.
*
- * This function move @p move_list to the back of @p list. If list is
- * @c NULL, @c NULL is returned. If @p move_list is @c NULL,
- * @p list is returned. Otherwise, a new list pointer that should be
- * used in place of the one passed to this function.
+ * @since_tizen 2.3
*
* Example:
* @code
@@ -644,29 +475,32 @@ EAPI Eina_List *eina_list_promote_list(Eina_List *list, Eina_List *mo
*
* EINA_LIST_FOREACH(list, l, data)
* {
- * if (data == my_data)
- * {
- * list = eina_list_demote_list(list, l);
- * break;
- * }
+ * if (data == my_data)
+ * {
+ * list = eina_list_demote_list(list, l);
+ * break;
+ * }
* }
* @endcode
*
- * @warning @p list must be a pointer to the first element of the list.
+ * @remarks @a list must be a pointer to the first element of the list.
+ *
+ * @param[in] list The list handle to move the data
+ * @param[in] move_list The list node to move
+ * @return A new list handle to replace the old one
+ *
*/
EAPI Eina_List *eina_list_demote_list(Eina_List *list, Eina_List *move_list);
/**
- * @brief Find a member of a list and return the member.
+ * @brief Finds a member of a list and returns the member.
*
- * @param list The list to search for a data.
- * @param data The data pointer to find in the list.
- * @return The found member data pointer if found, @c NULL otherwise.
+ * @details This function searches in @a list from beginning to end for the
+ * first member whose data pointer is @a data. If it is found, @a data
+ * is returned, otherwise @c NULL is returned.
*
- * This function searches in @p list from beginning to end for the
- * first member whose data pointer is @p data. If it is found, @p data
- * will be returned, otherwise @c NULL will be returned.
+ * @since_tizen 2.3
*
* Example:
* @code
@@ -679,126 +513,151 @@ EAPI Eina_List *eina_list_demote_list(Eina_List *list, Eina_List *mov
* }
* @endcode
*
- * @warning @p list must be a pointer to the first element of the list.
+ * @remarks @a list must be a pointer to the first element of the list.
+ *
+ * @param[in] list The list to search for data
+ * @param[in] data The data pointer to find in the list
+ * @return The found member data pointer, otherwise @c NULL
+ *
*/
EAPI void *eina_list_data_find(const Eina_List *list, const void *data) EINA_PURE EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
/**
- * @brief Find a member of a list and return the list node containing that member.
+ * @brief Finds a member of a list and returns the list node containing that member.
+ *
+ * @details This function searches in @a list from beginning to end for the
+ * first member whose data pointer is @a data. If it is found, the
+ * list node containing the specified member is returned, otherwise
+ * @c NULL is returned.
+ *
+ * @since_tizen 2.3
*
- * @param list The list to search for data.
- * @param data The data pointer to find in the list.
- * @return The found members list node on success, @c NULL otherwise.
+ * @remarks @a list must be a pointer to the first element of the list.
*
- * This function searches in @p list from beginning to end for the
- * first member whose data pointer is @p data. If it is found, the
- * list node containing the specified member is returned, otherwise
- * @c NULL is returned.
+ * @param[in] list The list to search for data
+ * @param[in] data The data pointer to find in the list
+ * @return The found members list node on success, otherwise @c NULL
*
- * @warning @p list must be a pointer to the first element of the list.
*/
EAPI Eina_List *eina_list_data_find_list(const Eina_List *list, const void *data) EINA_PURE EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
/**
- * @brief Move a data pointer from one list to another
+ * @brief Moves a data pointer from one list to another.
*
- * @param to The list to move the data to
- * @param from The list to move from
- * @param data The data to move
- * @return #EINA_TRUE on success, else #EINA_FALSE
+ * @details This function is a shortcut for doing the following:
+ * to = eina_list_append(to, data);
+ * from = eina_list_remove(from, data);
*
- * This function is a shortcut for doing the following:
- * to = eina_list_append(to, data);
- * from = eina_list_remove(from, data);
+ * @since_tizen 2.3
+ *
+ * @remarks @a list must be a pointer to the first element of the list.
+ *
+ * @param[out] to The list to move the data to
+ * @param[out] from The list to move from
+ * @param[in] data The data to move
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE
*
- * @warning @p list must be a pointer to the first element of the list.
*/
EAPI Eina_Bool eina_list_move(Eina_List **to, Eina_List **from, void *data);
/**
- * @brief Move a list node from one list to another
+ * @brief Moves a list node from one list to another.
+ *
+ * @details This function is a shortcut for doing the following:
+ * to = eina_list_append(to, data->data);
+ * from = eina_list_remove_list(from, data);
*
- * @param to The list to move the data to
- * @param from The list to move from
- * @param data The list node containing the data to move
- * @return #EINA_TRUE on success, else #EINA_FALSE
+ * @since_tizen 2.3
*
- * This function is a shortcut for doing the following:
- * to = eina_list_append(to, data->data);
- * from = eina_list_remove_list(from, data);
+ * @remarks @a list must be a pointer to the first element of the list.
+ *
+ * @param[out] to The list to move the data to
+ * @param[out] from The list to move from
+ * @param[in] data The list node containing the data to move
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE
*
- * @warning @p list must be a pointer to the first element of the list.
*/
EAPI Eina_Bool eina_list_move_list(Eina_List **to, Eina_List **from, Eina_List *data);
/**
- * @brief Free an entire list and all the nodes, ignoring the data contained.
-
- * @param list The list to free
+ * @brief Frees an entire list and all the nodes, ignoring the data contained.
+ *
+ * @details This function frees all the nodes of @a list. It does not free the
+ * data of the nodes. To free them, use #EINA_LIST_FREE.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] list The list to free
* @return A @c NULL pointer
*
- * This function frees all the nodes of @p list. It does not free the
- * data of the nodes. To free them, use #EINA_LIST_FREE.
*/
EAPI Eina_List *eina_list_free(Eina_List *list);
/**
- * @brief Get the nth member's data pointer in a list.
+ * @brief Gets the nth member's data pointer in a list.
+ *
+ * @details This function returns the data pointer of element number @a n, in
+ * the @a list. The first element in the array is element number 0. If
+ * the element number @a n does not exist, @c NULL is
+ * returned. Otherwise, the data of the found element is returned.
*
- * @param list The list to get the specified member number from.
- * @param n The number of the element (0 being the first).
- * @return The data pointer stored in the specified element.
+ * @since_tizen 2.3
*
- * This function returns the data pointer of element number @p n, in
- * the @p list. The first element in the array is element number 0. If
- * the element number @p n does not exist, @c NULL is
- * returned. Otherwise, the data of the found element is returned.
+ * @remarks Worst case is O(n).
*
- * @note Worst case is O(n).
+ * @remarks @a list must be a pointer to the first element of the list.
+ *
+ * @param[in] list The list to get the specified member number from
+ * @param[in] n The number of the element (0 being the first)
+ * @return The data pointer stored in the specified element
*
- * @warning @p list must be a pointer to the first element of the list.
*/
EAPI void *eina_list_nth(const Eina_List *list, unsigned int n) EINA_PURE EINA_WARN_UNUSED_RESULT;
/**
- * @brief Get the nth member's list node in a list.
+ * @brief Gets the nth member's list node in a list.
+ *
+ * @details This function returns the list node of element number @a n, in
+ * @a list. The first element in the array is element number 0. If the
+ * element number @a n does not exist or @a list is @c NULL, or @a n is
+ * greater than the count of the elements in @a list minus 1, @c NULL is
+ * returned. Otherwise the list node stored in the numbered element is
+ * returned.
+ *
+ * @since_tizen 2.3
*
- * @param list The list to get the specfied member number from.
- * @param n The number of the element (0 being the first).
- * @return The list node stored in the numbered element.
+ * @remarks Worst case is O(n).
*
- * This function returns the list node of element number @p n, in
- * @p list. The first element in the array is element number 0. If the
- * element number @p n does not exist or @p list is @c NULL or @p n is
- * greater than the count of elements in @p list minus 1, @c NULL is
- * returned. Otherwise the list node stored in the numbered element is
- * returned.
+ * @remarks @a list must be a pointer to the first element of the list.
*
- * @note Worst case is O(n).
+ * @param[in] list The list to get the specfied member number from
+ * @param[in] n The number of the element (0 being the first)
+ * @return The list node stored in the numbered element
*
- * @warning @p list must be a pointer to the first element of the list.
*/
EAPI Eina_List *eina_list_nth_list(const Eina_List *list, unsigned int n) EINA_PURE EINA_WARN_UNUSED_RESULT;
/**
- * @brief Reverse all the elements in the list.
+ * @brief Reverses all the elements in the list.
*
- * @param list The list to reverse.
- * @return The list head after it has been reversed.
+ * @details This function reverses the order of all the elements in @a list, so the
+ * last member is now first, and so on. If @a list is @c NULL, this
+ * function returns @c NULL.
*
- * This function reverses the order of all elements in @p list, so the
- * last member is now first, and so on. If @p list is @c NULL, this
- * functon returns @c NULL.
+ * @since_tizen 2.3
*
- * @note @b in-place: this will change the given list, so you should
- * now point to the new list head that is returned by this function.
+ * @remarks @b in-place: This changes the given list, so you should
+ * now point to the new list head that is returned by this function.
*
- * @warning @p list must be a pointer to the first element of the list.
+ * @remarks @a list must be a pointer to the first element of the list.
+ *
+ * @param[in] list The list to reverse
+ * @return The list head after it has been reversed
*
* @see eina_list_reverse_clone()
* @see eina_list_iterator_reversed_new()
@@ -807,19 +666,21 @@ EAPI Eina_List *eina_list_reverse(Eina_List *list) EINA_WARN_UNUSED_R
/**
- * @brief Clone (copy) all the elements in the list in reverse order.
+ * @brief Clones (copies) all the elements in the list in the reverse order.
+ *
+ * @details This function reverses the order of all the elements in @a list, so the
+ * last member is now first, and so on. If @a list is @c NULL, this
+ * function returns @c NULL. This returns a copy of the given list.
*
- * @param list The list to reverse.
- * @return The new list that has been reversed.
+ * @since_tizen 2.3
*
- * This function reverses the order of all elements in @p list, so the
- * last member is now first, and so on. If @p list is @c NULL, this
- * functon returns @c NULL. This returns a copy of the given list.
+ * @remarks @b copy: This copies the list and you should then use
+ * eina_list_free() when it is not required anymore.
*
- * @note @b copy: this will copy the list and you should then
- * eina_list_free() when it is not required anymore.
+ * @remarks @a list must be a pointer to the first element of the list.
*
- * @warning @p list must be a pointer to the first element of the list.
+ * @param[in] list The list to reverse
+ * @return The new list that has been reversed
*
* @see eina_list_reverse()
* @see eina_list_clone()
@@ -828,19 +689,21 @@ EAPI Eina_List *eina_list_reverse_clone(const Eina_List *list) EINA_W
/**
- * @brief Clone (copy) all the elements in the list in exactly same order.
+ * @brief Clones (copies) all the elements in the list in the exactly same order.
+ *
+ * @details This function clones in an order which is same as the order of all the elements in @a list.
+ * If @a list is @c NULL, this functon returns @c NULL. This returns a copy of
+ * the given list.
*
- * @param list The list to clone.
- * @return The new list that has been cloned.
+ * @since_tizen 2.3
*
- * This function clone in order of all elements in @p list. If @p list
- * is @c NULL, this functon returns @c NULL. This returns a copy of
- * the given list.
+ * @remarks @b copy: This copies the list and you should then use
+ * eina_list_free() when it is not required anymore.
*
- * @note @b copy: this will copy the list and you should then
- * eina_list_free() when it is not required anymore.
+ * @remarks @a list must be a pointer to the first element of the list.
*
- * @warning @p list must be a pointer to the first element of the list.
+ * @param[in] list The list to clone
+ * @return The new list that has been cloned
*
* @see eina_list_reverse_clone()
*/
@@ -848,24 +711,21 @@ EAPI Eina_List *eina_list_clone(const Eina_List *list) EINA_WARN_UNUS
/**
- * @brief Sort a list according to the ordering func will return.
+ * @brief Sorts a list according to the ordering that @a func returns.
*
- * @param list The list handle to sort.
- * @param limit The maximum number of list elements to sort.
- * @param func A function pointer that can handle comparing the list data
- * nodes.
- * @return the new head of list.
+ * @details This function sorts @a list.
+ * If @a limit is @c 0 or greater than the number of
+ * elements in @a list, all the elements are sorted. @a func is used to
+ * compare two elements of @a list. If @a func is @c NULL, this function returns
+ * @a list.
*
- * This function sorts @p list. If @p limit is 0 or greater than the number of
- * elements in @p list, all the elements are sorted. @p func is used to
- * compare two elements of @p list. If @p func is @c NULL, this function returns
- * @p list.
+ * @since_tizen 2.3
*
- * @note @b in-place: this will change the given list, so you should
- * now point to the new list head that is returned by this function.
+ * @remarks @b in-place: This changes the given list, so you should
+ * now point to the new list head that is returned by this function.
*
- * @note Worst case is O(n * log2(n)) comparisons (calls to func()).
- * That means that for 1,000,000 list sort will do 20,000,000 comparisons.
+ * @remarks Worst case is O(n * log2(n)) comparisons (calls to func()).
+ * That means, for 1,000,000 list sort we do 20,000,000 comparisons.
*
* Example:
* @code
@@ -885,67 +745,51 @@ EAPI Eina_List *eina_list_clone(const Eina_List *list) EINA_WARN_UNUS
* list = eina_list_sort(list, eina_list_count(list), sort_cb);
* @endcode
*
- * @warning @p list must be a pointer to the first element of the list.
- */
-EAPI Eina_List *eina_list_sort(Eina_List *list, unsigned int limit, Eina_Compare_Cb func) EINA_ARG_NONNULL(3) EINA_WARN_UNUSED_RESULT;
-
-
-/**
- * @brief Shuffle list.
- *
- * @param list The list handle to shuffle.
- * @param func A function pointer that can return an int between 2 inclusives values
- * @return the new head of list.
- *
- * This function shuffles @p list.
- * @p func is used to generate random list indexes within the range of
- * unshuffled list items. If @p func is @c NULL, rand is used.
- *
- * @note @b in-place: this will change the given list, so you should
- * now point to the new list head that is returned by this function.
+ * @remarks @a list must be a pointer to the first element of the list.
*
- * @since 1.8
+ * @param[in] list The list handle to sort
+ * @param[in] limit The maximum number of list elements to sort
+ * @param[in] func A function pointer that can handle comparing the list data
+ * nodes
+ * @return The new head of the list
*
- * @warning @p list must be a pointer to the first element of the list.
*/
-EAPI Eina_List *eina_list_shuffle(Eina_List *list, Eina_Random_Cb func) EINA_WARN_UNUSED_RESULT;
+EAPI Eina_List *eina_list_sort(Eina_List *list, unsigned int limit, Eina_Compare_Cb func) EINA_ARG_NONNULL(3) EINA_WARN_UNUSED_RESULT;
/**
- * @brief Merge two list.
+ * @brief Merges two lists.
+ *
+ * @details This function puts @a right at the end of @a left and returns the head.
+ * Both @a left and @a right do not exist anymore after the merge.
*
- * @param left Head list to merge.
- * @param right Tail list to merge.
- * @return A new merged list.
+ * @since_tizen 2.3
*
- * This function puts right at the end of left and returns the head.
+ * @remarks Merge cost is O(n), @b n being the size of the smallest
+ * list. This is due to the need to fix accounting of that segment,
+ * making count and last access O(1).
*
- * Both left and right do not exist anymore after the merge.
+ * @remarks @a list must be a pointer to the first element of the list.
*
- * @note merge cost is O(n), being @b n the size of the smallest
- * list. This is due the need to fix accounting of that segment,
- * making count and last access O(1).
+ * @param[in] left The head list to merge
+ * @param[in] right The tail list to merge
+ * @return A new merged list
*
- * @warning @p list must be a pointer to the first element of the list.
*/
EAPI Eina_List *eina_list_merge(Eina_List *left, Eina_List *right) EINA_WARN_UNUSED_RESULT;
/**
- * @brief Merge two sorted list according to the ordering func will return.
+ * @brief Merges two sorted lists according to the ordering that @a func returns.
*
- * @param left First list to merge.
- * @param right Second list to merge.
- * @param func A function pointer that can handle comparing the list data
- * nodes.
- * @return A new sorted list.
+ * @details This function compares the head of @a left and @a right, and chooses the
+ * smallest one to be the head of the returned list. It continues this process
+ * for all the entries of both the lists.
*
- * This function compares the head of @p left and @p right, and choose the
- * smallest one to be head of the returned list. It will continue this process
- * for all entry of both list.
+ * Both the left and the right lists are not vaild anymore after the merge and should
+ * not be used. If @a func is @c NULL, it returns @c NULL.
*
- * Both left and right lists are not vailid anymore after the merge and should
- * not be used. If @p func is @c NULL, it will return @c NULL.
+ * @since_tizen 2.3
*
* Example:
* @code
@@ -966,61 +810,63 @@ EAPI Eina_List *eina_list_merge(Eina_List *left, Eina_List *right) EI
* list = eina_list_sorted_merge(sorted1, sorted2, sort_cb);
* @endcode
*
- * @warning @p list must be a pointer to the first element of the list.
+ * @remarks @a list must be a pointer to the first element of the list.
+ *
+ * @param[in] left The first list to merge
+ * @param[in] right The second list to merge
+ * @param[in] func A function pointer that can handle comparing the list data
+ * nodes
+ * @return A new sorted list
+ *
*/
EAPI Eina_List *eina_list_sorted_merge(Eina_List *left, Eina_List *right, Eina_Compare_Cb func) EINA_ARG_NONNULL(3) EINA_WARN_UNUSED_RESULT;
/**
- * @brief Split a list into 2 lists.
+ * @brief Splits a list into 2 lists.
*
- * @param list List to split.
- * @param relative The list will be split after @p relative.
- * @param right The head of the new right list.
- * @return The new left list
+ * @details This function splits @a list into two lists ( left and right ) after the node @a relative. @a relative
+ * becomes the last node of the left list. If @a list or @a right is @c NULL, @a list is returned.
+ * If @a relative is @c NULL, @a right is set to @a list and @c NULL is returned.
+ * If @a relative is the last node of @a list, @a list is returned and @a right is set to @c NULL.
+ *
+ * List does not exist anymore after the split.
*
- * This function splits @p list into two lists ( left and right ) after the node @p relative. @p Relative
- * will become the last node of the left list. If @p list or @p right are @c NULL list is returns.
- * If @p relative is NULL right is set to @p list and @c NULL is returns.
- * If @p relative is the last node of @p list list is returns and @p right is set to @c NULL.
+ * @since_tizen 2.3
*
- * list does not exist anymore after the split.
+ * @remarks @a list must be a pointer to the first element of the list.
+ *
+ * @param[in] list The list to split
+ * @param[in] relative The list is split after @a relative
+ * @param[out] right The head of the new right list
+ * @return The new left list
*
- * @warning @p list must be a pointer to the first element of the list.
*/
EAPI Eina_List *eina_list_split_list(Eina_List *list, Eina_List *relative, Eina_List **right) EINA_WARN_UNUSED_RESULT;
/**
- * @brief Returns node nearest to data is in the sorted list.
- *
- * @param list The list to search for data, @b must be sorted.
- * @param func A function pointer that can handle comparing the list data nodes.
- * @param data reference value to search.
- * @param result_cmp if provided returns the result of
- * func(node->data, data) node being the last (returned) node. If node
- * was found (exact match), then it is 0. If returned node is smaller
- * than requested data, it is less than 0 and if it's bigger it's
- * greater than 0. It is the last value returned by func().
- * @return the nearest node, @c NULL if not found.
- *
- * This function searches for a node containing @p data as its data in @p list,
- * if such a node exists it will be returned and @p result_cmp will be @p 0. If
- * the data of no node in @p list is equal to @p data, the node with the nearest
- * value to that will be returned and @p result_cmp will be the return value of
- * @p func with @p data and the returned node's data as arguments.
- *
- * This function is useful for inserting an element in the list only in case it
- * isn't already present in the list, the naive way of doing this would be:
+ * @brief Returns the node nearest to data in the sorted list.
+ *
+ * @details This function searches for a node containing @a data as its data in @a list,
+ * if such a node exists it is returned and @a result_cmp is @c 0. If
+ * the data of no node in @a list is equal to @a data, the node with the nearest
+ * value to that is returned and @a result_cmp is the return value of
+ * @a func with @a data and the returned node's data as arguments.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks This function is useful for inserting an element in the list only in case it
+ * isn't already present in the list, the naive way of doing this would be:
* @code
* void *ptr = eina_list_data_find(list, "my data");
* if (!ptr)
* eina_list_sorted_insert(list, "my data");
* @endcode
- *
- * However this has the downside of walking through the list twice, once to
- * check if the data is already present and another to insert the element in the
- * corret position. This can be done more eficiently:
+ *
+ * @remarks However, this has the downside of walking through the list twice, once to
+ * check if the data is already present and another to insert the element in the
+ * correct position. This can be done more efficiently by:
* @code
* int cmp_result;
* l = eina_list_search_sorted_near_list(list, cmp_func, "my data",
@@ -1030,21 +876,32 @@ EAPI Eina_List *eina_list_split_list(Eina_List *list, Eina_List *rela
* else if (cmp_result < 0)
* list = eina_list_append_relative_list(list, "my data", l);
* @endcode
- *
- * If @a cmp_result is 0 the element is already in the list and we need not
- * insert it, if @a cmp_result is greater than zero @a "my @a data" needs to
- * come after @a l(the nearest node present), if less than zero before.
- *
- * @note O(log2(n)) average/worst case performance, for 1,000,000
- * elements it will do a maximum of 20 comparisons. This is much
- * faster than the 1,000,000 comparisons made naively walking the list
- * from head to tail, so depending on the number of searches and
- * insertions, it may be worth to eina_list_sort() the list and do the
- * searches later. As lists do not have O(1) access time, walking to
- * the correct node can be costly, consider worst case to be almost
- * O(n) pointer dereference (list walk).
- *
- * @warning @p list must be a pointer to the first element of the list.
+ *
+ * If @a cmp_result is 0 the element is already in the list and we need not
+ * insert it, if @a cmp_result is greater than zero @a "my @a data" needs to
+ * come after @a l(the nearest node present), if less than zero it needs to come before.
+ *
+ * @remarks Average/worst case performance is O(log2(n)), for 1,000,000
+ * elements it does a maximum of 20 comparisons. This is much
+ * faster than the 1,000,000 comparisons made naively by walking the list
+ * from head to tail, so depending on the number of searches and
+ * insertions, it may be better to eina_list_sort() the list and do the
+ * searches later. As lists do not have O(1) access time, walking to
+ * the correct node can be costly, consider worst case to be almost
+ * O(n) pointer dereference (list walk).
+ *
+ * @remarks @a list must be a pointer to the first element of the list.
+ *
+ * @param[in] list The list to search for data, @b must be sorted
+ * @param[in] func A function pointer that can handle comparing the list data nodes
+ * @param[in] data The reference value to search
+ * @param[in] result_cmp If provided it returns the result of
+ * the func(node->data, data) node being the last (returned) node. If node
+ * is found (exact match), then it is @c 0. If the returned node is smaller
+ * than the requested data, it is less than @c 0 and if it's bigger it's
+ * greater than @c 0. It is the last value returned by func().
+ * @return The nearest node, otherwise @c NULL if not found
+ *
*
* @see eina_list_search_sorted_list()
* @see eina_list_sort()
@@ -1054,31 +911,33 @@ EAPI Eina_List *eina_list_search_sorted_near_list(const Eina_List *li
/**
- * @brief Returns node if data is in the sorted list.
+ * @brief Returns the node if data is in the sorted list.
+ *
+ * @since_tizen 2.3
*
- * @param list The list to search for data, @b must be sorted.
- * @param func A function pointer that can handle comparing the list data nodes.
- * @param data reference value to search.
- * @return the node if func(node->data, data) == 0, @c NULL if not found.
+ * @remarks This can be used to check if some value is inside the list and get
+ * the container node in this case. It should be used when the list is
+ * known to be sorted as it does a binary search for results.
*
- * This can be used to check if some value is inside the list and get
- * the container node in this case. It should be used when list is
- * known to be sorted as it will do binary search for results.
+ * Example: Imagine a user gives a string, you check if it's in the list
+ * before duplicating its contents.
*
- * Example: imagine user gives a string, you check if it's in the list
- * before duplicating its contents.
+ * @remarks Average/worst case performance is O(log2(n)), for 1,000,000
+ * elements it does a maximum of 20 comparisons. This is much
+ * faster than the 1,000,000 comparisons made by
+ * eina_list_search_unsorted_list(), so depending on the number of
+ * searches and insertions, it may be better to eina_list_sort() the
+ * list and do the searches later. As said in
+ * eina_list_search_sorted_near_list(), lists do not have O(1) access
+ * time, so walking to the correct node can be costly, consider worst
+ * case to be almost O(n) pointer dereference (list walk).
*
- * @note O(log2(n)) average/worst case performance, for 1,000,000
- * elements it will do a maximum of 20 comparisons. This is much
- * faster than the 1,000,000 comparisons made by
- * eina_list_search_unsorted_list(), so depending on the number of
- * searches and insertions, it may be worth to eina_list_sort() the
- * list and do the searches later. As said in
- * eina_list_search_sorted_near_list(), lists do not have O(1) access
- * time, so walking to the correct node can be costly, consider worst
- * case to be almost O(n) pointer dereference (list walk).
+ * @remarks @a list must be a pointer to the first element of the list.
*
- * @warning @p list must be a pointer to the first element of the list.
+ * @param[in] list The list to search for data, @b must be sorted
+ * @param[in] func A function pointer that can handle comparing the list data nodes
+ * @param[in] data The reference value to search
+ * @return The node if func(node->data, data) == 0, otherwise @c NULL if not found
*
* @see eina_list_search_sorted()
* @see eina_list_sort()
@@ -1090,32 +949,34 @@ EAPI Eina_List *eina_list_search_sorted_list(const Eina_List *list, E
/**
- * @brief Returns node data if it is in the sorted list.
+ * @brief Returns the node data if it is in the sorted list.
*
- * @param list The list to search for data, @b must be sorted.
- * @param func A function pointer that can handle comparing the list data nodes.
- * @param data reference value to search.
- * @return the node value (@c node->data) if func(node->data, data) == 0,
- * NULL if not found.
+ * @since_tizen 2.3
*
- * This can be used to check if some value is inside the list and get
- * the existing instance in this case. It should be used when list is
- * known to be sorted as it will do binary search for results.
+ * @remarks This can be used to check if some value is inside the list and get
+ * the existing instance in this case. It should be used when a list is
+ * known to be sorted as it does a binary search for results.
*
- * Example: imagine user gives a string, you check if it's in the list
- * before duplicating its contents.
+ * Example: Imagine a user gives a string, you check if it's in the list
+ * before duplicating its contents.
*
- * @note O(log2(n)) average/worst case performance, for 1,000,000
- * elements it will do a maximum of 20 comparisons. This is much
- * faster than the 1,000,000 comparisons made by
- * eina_list_search_unsorted(), so depending on the number of
- * searches and insertions, it may be worth to eina_list_sort() the
- * list and do the searches later. As said in
- * eina_list_search_sorted_near_list(), lists do not have O(1) access
- * time, so walking to the correct node can be costly, consider worst
- * case to be almost O(n) pointer dereference (list walk).
+ * @remarks Average/worst case performance is O(log2(n)), for 1,000,000
+ * elements it does a maximum of 20 comparisons. This is much
+ * faster than the 1,000,000 comparisons made by
+ * eina_list_search_unsorted(), so depending on the number of
+ * searches and insertions, it may be better to eina_list_sort() the
+ * list and do the searches later. As said in
+ * eina_list_search_sorted_near_list(), lists do not have O(1) access
+ * time, so walking to the correct node can be costly, consider worst
+ * case to be almost O(n) pointer dereference (list walk).
*
- * @warning @p list must be a pointer to the first element of the list.
+ * @remarks @a list must be a pointer to the first element of the list.
+ *
+ * @param[in] list The list to search for data, @b must be sorted
+ * @param[in] func A function pointer that can handle comparing the list data nodes.
+ * @param[in] data The reference value to search
+ * @return The node value (@c node->data) if func(node->data, data) == 0,
+ * otherwise @c NULL if not found
*
* @see eina_list_search_sorted_list()
* @see eina_list_sort()
@@ -1126,24 +987,26 @@ EAPI void *eina_list_search_sorted(const Eina_List *list, Eina_C
/**
- * @brief Returns node if data is in the unsorted list.
+ * @brief Returns the node if data is in the unsorted list.
+ *
+ * @since_tizen 2.3
*
- * @param list The list to search for data, may be unsorted.
- * @param func A function pointer that can handle comparing the list data nodes.
- * @param data reference value to search.
- * @return the node if func(node->data, data) == 0, @c NULL if not found.
+ * @remarks This can be used to check if some value is inside the list and get
+ * the container node in this case.
*
- * This can be used to check if some value is inside the list and get
- * the container node in this case.
+ * Example: Imagine a user gives a string, you check if it's in the list
+ * before duplicating its contents.
*
- * Example: imagine user gives a string, you check if it's in the list
- * before duplicating its contents.
+ * @remarks This is expensive and may walk the whole list, it's order-N,
+ * that is for 1,000,000 elements list it may walk and compare
+ * 1,000,000 nodes.
*
- * @note this is expensive and may walk the whole list, it's order-N,
- * that is for 1,000,000 elements list it may walk and compare
- * 1,000,000 nodes.
+ * @remarks @a list must be a pointer to the first element of the list.
*
- * @warning @p list must be a pointer to the first element of the list.
+ * @param[in] list The list to search for data, may be unsorted
+ * @param[in] func A function pointer that can handle comparing the list data nodes
+ * @param[in] data The reference value to search
+ * @return The node if func(node->data, data) == 0, otherwise @c NULL if not found
*
* @see eina_list_search_sorted_list()
* @see eina_list_search_unsorted()
@@ -1152,25 +1015,27 @@ EAPI Eina_List *eina_list_search_unsorted_list(const Eina_List *list,
/**
- * @brief Returns node data if it is in the unsorted list.
+ * @brief Returns the node data if it is in the unsorted list.
*
- * @param list The list to search for data, may be unsorted.
- * @param func A function pointer that can handle comparing the list data nodes.
- * @param data reference value to search.
- * @return the node value (@c node->data) if func(node->data, data) == 0,
- * @c NULL if not found.
+ * @since_tizen 2.3
*
- * This can be used to check if some value is inside the list and get
- * the existing instance in this case.
+ * @remarks This can be used to check if some value is inside the list and get
+ * the existing instance in this case.
*
- * Example: imagine user gives a string, you check if it's in the list
- * before duplicating its contents.
+ * Example: Imagine a user gives a string, you check if it's in the list
+ * before duplicating its contents.
*
- * @note this is expensive and may walk the whole list, it's order-N,
- * that is for 1,000,000 elements list it may walk and compare
- * 1,000,000 nodes.
+ * @remarks This is expensive and may walk the whole list, it's order-N,
+ * that is for 1,000,000 elements list it may walk and compare
+ * 1,000,000 nodes.
*
- * @warning @p list must be a pointer to the first element of the list.
+ * @remarks @a list must be a pointer to the first element of the list.
+ *
+ * @param[in] list The list to search for data, may be unsorted
+ * @param[in] func A function pointer that can handle comparing the list data nodes
+ * @param[in] data The reference value to search.
+ * @return The node value (@c node->data) if func(node->data, data) == 0,
+ * otherwise @c NULL if not found
*
* @see eina_list_search_sorted()
* @see eina_list_search_unsorted_list()
@@ -1178,191 +1043,211 @@ EAPI Eina_List *eina_list_search_unsorted_list(const Eina_List *list,
EAPI void *eina_list_search_unsorted(const Eina_List *list, Eina_Compare_Cb func, const void *data);
/**
- * @brief Get the last list node in the list.
+ * @brief Gets the last list node in the list.
+ *
+ * @details This function returns the last list node in the list @a list. If
+ * @a list is @c NULL or empty, @c NULL is returned.
+ *
+ * @since_tizen 2.3
*
- * @param list The list to get the last list node from.
- * @return The last list node in the list.
+ * @remarks This is an order-1 operation (it takes the same short time
+ * regardless of the length of the list).
*
- * This function returns the last list node in the list @p list. If
- * @p list is @c NULL or empty, @c NULL is returned.
+ * @remarks @a list must be a pointer to the first element of the list.
*
- * This is a order-1 operation (it takes the same short time
- * regardless of the length of the list).
+ * @param[in] list The list to get the last list node from
+ * @return The last list node in the list
*
- * @warning @p list must be a pointer to the first element of the list.
*/
static inline Eina_List *eina_list_last(const Eina_List *list) EINA_PURE EINA_WARN_UNUSED_RESULT;
/**
- * @brief Get the next list node after the specified list node.
+ * @brief Gets the next list node after the specified list node.
*
- * @param list The list node to get the next list node from
- * @return The next list node on success, @c NULL otherwise.
+ * @details This function returns the next list node after the current one in
+ * @a list. It is equivalent to list->next. If @a list is @c NULL or
+ * if no next list node exists, it returns @c NULL.
*
- * This function returns the next list node after the current one in
- * @p list. It is equivalent to list->next. If @p list is @c NULL or
- * if no next list node exists, it returns @c NULL.
+ * @since_tizen 2.3
+ *
+ * @remarks @a list must be a pointer to the first element of the list.
+ *
+ * @param[in] list The list node to get the next list node from
+ * @return The next list node on success, otherwise @c NULL
*
- * @warning @p list must be a pointer to the first element of the list.
*/
static inline Eina_List *eina_list_next(const Eina_List *list) EINA_PURE EINA_WARN_UNUSED_RESULT;
/**
- * @brief Get the previous list node before the specified list node.
+ * @brief Gets the previous list node before the specified list node.
+ *
+ * @details This function returns the previous list node before the current one
+ * in @a list. It is equivalent to list->prev. If @a list is @c NULL or
+ * if no previous list node exists, it returns @c NULL.
*
- * @param list The list node to get the previous list node from.
- * @return The previous list node o success, @c NULL otherwise.
- * if no previous list node exists
+ * @since_tizen 2.3
*
- * This function returns the previous list node before the current one
- * in @p list. It is equivalent to list->prev. If @p list is @c NULL or
- * if no previous list node exists, it returns @c NULL.
+ * @remarks @a list must be a pointer to the first element of the list.
+ *
+ * @param[in] list The list node to get the previous list node from
+ * @return The previous list node on success, otherwise @c NULL
+ * if no previous list node exists
*
- * @warning @p list must be a pointer to the first element of the list.
*/
static inline Eina_List *eina_list_prev(const Eina_List *list) EINA_PURE EINA_WARN_UNUSED_RESULT;
/**
- * @brief Get the list node data member.
+ * @brief Gets the list node data member.
+ *
+ * @details This function returns the data member of the specified list node
+ * @a list. It is equivalent to list->data. If @p list is @c NULL, this
+ * function returns @c NULL.
+ *
+ * @since_tizen 2.3
*
- * @param list The list node to get the data member of.
- * @return The data member from the list node.
+ * @remarks @a list must be a pointer to the first element of the list.
*
- * This function returns the data member of the specified list node @p
- * list. It is equivalent to list->data. If @p list is @c NULL, this
- * function returns @c NULL.
+ * @param[in] list The list node to get the data member of
+ * @return The data member from the list node
*
- * @warning @p list must be a pointer to the first element of the list.
*/
static inline void *eina_list_data_get(const Eina_List *list) EINA_PURE EINA_WARN_UNUSED_RESULT;
/**
- * @brief Set the list node data member.
+ * @brief Sets the list node data member.
*
- * @param list The list node to get the data member of.
- * @param data The data member to the list node.
- * @return The previous data value.
+ * @details This function sets the data member @a data of the specified list node
+ * @a list. It returns the previous data of the node. If @a list is
+ * @c NULL, this function returns @c NULL.
*
- * This function set the data member @p data of the specified list node
- * @p list. It returns the previous data of the node. If @p list is
- * @c NULL, this function returns @c NULL.
+ * @since_tizen 2.3
+ *
+ * @remarks @a list must be a pointer to the first element of the list.
+ *
+ * @param[in] list The list node to get the data member of
+ * @param[in] data The data member for the list node
+ * @return The previous data value
*
- * @warning @p list must be a pointer to the first element of the list.
*/
static inline void *eina_list_data_set(Eina_List *list, const void *data);
/**
- * @brief Get the count of the number of items in a list.
+ * @brief Gets the count of the number of items in a list.
+ *
+ * @details This function returns the number of members that @a list contains. If the
+ * @a list is @c NULL, @c 0 is returned.
*
- * @param list The list whose count to return.
- * @return The number of members in the list.
+ * @since_tizen 2.3
*
- * This function returns how many members @p list contains. If the
- * list is @c NULL, @c 0 is returned.
+ * @remarks This is an order-1 operation and takes the same time regardless
+ * of the length of the list.
*
- * NB: This is an order-1 operation and takes the same time regardless
- * of the length of the list.
+ * @remarks @a list must be a pointer to the first element of the list.
+ *
+ * @param[in] list The list whose count to return
+ * @return The number of members in the list
*
- * @warning @p list must be a pointer to the first element of the list.
*/
static inline unsigned int eina_list_count(const Eina_List *list) EINA_PURE;
+
/**
- * @brief Returns the last list node's data
+ * @brief Returns a new iterator associated to a list.
*
- * @param list The list
- * @return The node's data, or @c NULL on being passed a @c NULL pointer
+ * @details This function returns a newly allocated iterator associated to @a
+ * list. If @a list is @c NULL or the count member of @a list is less than
+ * or equal to @c 0, this function still returns a valid iterator that
+ * always returns @c false on eina_iterator_next(), thus keeping the API
+ * sane.
*
- * This macro is a shortcut for typing eina_list_data_get(eina_list_last())
- * @since 1.8
- */
-static inline void *eina_list_last_data_get(const Eina_List *list);
-
-/**
- * @brief Returned a new iterator associated to a list.
+ * @since_tizen 2.3
*
- * @param list The list.
- * @return A new iterator.
+ * @remarks If the memory cannot be allocated, @c NULL is returned
+ * and #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator
+ * is returned.
*
- * This function returns a newly allocated iterator associated to @p
- * list. If @p list is @c NULL or the count member of @p list is less
- * or equal than 0, this function still returns a valid iterator that
- * will always return false on eina_iterator_next(), thus keeping API
- * sane.
+ * @remarks @a list must be a pointer to the first element of the list.
*
- * If the memory can not be allocated, NULL is returned.
- * Otherwise, a valid iterator is returned.
+ * @remarks If the list 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.
*
- * @warning @p list must be a pointer to the first element of the list.
+ * @param[in] list The list
+ * @return A new iterator
*
- * @warning if the list 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!
*/
EAPI Eina_Iterator *eina_list_iterator_new(const Eina_List *list) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
/**
- * @brief Returned a new reversed iterator associated to a list.
+ * @brief Returns a new reversed iterator associated to a list.
+ *
+ * @details This function returns a newly allocated iterator associated to
+ * @a list. If @a list is @c NULL or the count member of @a list is less than
+ * or equal to 0, this function still returns a valid iterator that
+ * always returns @c false on eina_iterator_next(), thus keeping the API
+ * sane.
*
- * @param list The list.
- * @return A new iterator.
+ * @since_tizen 2.3
*
- * This function returns a newly allocated iterator associated to @p
- * list. If @p list is @c NULL or the count member of @p list is less
- * or equal than 0, this function still returns a valid iterator that
- * will always return false on eina_iterator_next(), thus keeping API
- * sane.
+ * @remarks Unlike eina_list_iterator_new(), this walks the list backwards.
*
- * Unlike eina_list_iterator_new(), this will walk the list backwards.
+ * @remarks If the memory cannot be allocated, @c NULL is returned
+ * and #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator
+ * is returned.
*
- * If the memory can not be allocated, NULL is returned.
- * Otherwise, a valid iterator is returned.
+ * @remarks @a list must be a pointer to the first element of the list.
*
- * @warning @p list must be a pointer to the first element of the list.
+ * @remarks If the list 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.
+ *
+ * @param[in] list The list
+ * @return A new iterator
*
- * @warning if the list 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!
*/
EAPI Eina_Iterator *eina_list_iterator_reversed_new(const Eina_List *list) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
/**
- * @brief Returned a new accessor associated to a list.
+ * @brief Returns a new accessor associated to a list.
+ *
+ * @details This function returns a newly allocated accessor associated to
+ * @a list. If @a list is @c NULL or the count member of @a list is
+ * less than or equal to 0, this function returns @c NULL.
+ *
+ * @since_tizen 2.3
*
- * @param list The list.
- * @return A new accessor.
+ * @remarks If the memory cannot be allocated,
+ * @c NULL is returned and #EINA_ERROR_OUT_OF_MEMORY is
+ * set. Otherwise, a valid accessor is returned.
*
- * This function returns a newly allocated accessor associated to
- * @p list. If @p list is @c NULL or the count member of @p list 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.
+ * @remarks @a list must be a pointer to the first element of the list.
+ *
+ * @param[in] list The list
+ * @return A new accessor
*
- * @warning @p list must be a pointer to the first element of the list.
*/
EAPI Eina_Accessor *eina_list_accessor_new(const Eina_List *list) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
/**
* @def EINA_LIST_FOREACH
- * @brief Macro to iterate over a list.
+ * @brief Definition of the macro to iterate over a list.
+ *
+ * @details This macro iterates over @a list from the first element to
+ * the last. @a data is the data related to the current element.
+ * @a l is an #Eina_List used as the list iterator.
*
- * @param list The list to iterate over.
- * @param l A list that is used as an iterator and points to the current node.
- * @param data Current item's data.
+ * @since_tizen 2.3
*
- * This macro iterates over @p list from the first element to
- * the last. @p data is the data related to the current element.
- * @p l is an #Eina_List used as the list iterator.
+ * @remarks The following diagram ilustrates this macro iterating over a list of four
+ * elements("one", "two", "three" and "four"):
*
- * The following diagram illustrates this macro iterating over a list of four
- * elements("one", "two", "three" and "four"):
+ * @image html eina-list-foreach.png
* @htmlonly
- * <img src="eina-list-foreach.png" style="max-width: 100%;" />
* <a href="eina-list-foreach.png">Full-size</a>
* @endhtmlonly
- * @image latex eina-list-foreach.eps "" width=\textwidth
+ * @image latex eina-list-foreach.eps "eina list foreach" width=\textwidth
*
* It can be used to free list data, as in the following example:
*
@@ -1380,19 +1265,24 @@ EAPI Eina_Accessor *eina_list_accessor_new(const Eina_List *list) EINA_MA
* eina_list_free(list);
* @endcode
*
- * @note This is not the optimal way to release memory allocated to
- * a list, since it iterates over the list twice.
- * For an optimized algorithm, use EINA_LIST_FREE().
+ * @remarks This is not the optimal way to release memory allocated to
+ * a list, since it iterates over the list twice.
+ * For an optimized algorithm, use EINA_LIST_FREE().
*
- * @warning @p list must be a pointer to the first element of the list.
+ * @remarks @a list must be a pointer to the first element of the list.
*
- * @warning Be careful when deleting list nodes.
+ * @remarks Be careful when deleting list nodes.
* If you remove the current node and continue iterating,
- * the code will fail because the macro will not be able
+ * the code fails because the macro is not able
* to get the next node. Notice that it's OK to remove any
* node if you stop the loop after that.
* For destructive operations such as this, consider
* using EINA_LIST_FOREACH_SAFE().
+ *
+ * @param list The list to iterate over
+ * @param l A list that is used as an iterator and points to the current node
+ * @param data The current item's data
+ *
*/
#define EINA_LIST_FOREACH(list, l, data) \
for (l = list, \
@@ -1403,24 +1293,23 @@ EAPI Eina_Accessor *eina_list_accessor_new(const Eina_List *list) EINA_MA
/**
* @def EINA_LIST_REVERSE_FOREACH
- * @brief Macro to iterate over a list in the reverse order.
+ * @brief Definition of the macro to iterate over a list in the reverse order.
+ *
+ * @details This macro works like EINA_LIST_FOREACH, but iterates from the
+ * last element of a list to the first.
+ * @a data is the data related to the current element, while @a l
+ * is an #Eina_List that is used as the list iterator.
*
- * @param list The list to iterate over.
- * @param l A list that is used as an iterator and points to the current node.
- * @param data Current item's data.
+ * @since_tizen 2.3
*
- * This macro works like EINA_LIST_FOREACH, but iterates from the
- * last element of a list to the first.
- * @p data is the data related to the current element, while @p l
- * is an #Eina_List that is used as the list iterator.
+ * @remarks The following diagram ilustrates this macro iterating over a list of four
+ * elements("one", "two", "three" and "four"):
*
- * The following diagram illustrates this macro iterating over a list of four
- * elements("one", "two", "three" and "four"):
+ * @image html eina-list-reverse-foreach.png
* @htmlonly
- * <img src="eina-list-reverse-foreach.png" style="max-width: 100%;" />
* <a href="eina-list-reverse-foreach.png">Full-size</a>
* @endhtmlonly
- * @image latex eina-list-reverse-foreach.eps "" width=\textwidth
+ * @image latex eina-list-reverse-foreach.eps "eina list reverse foreach" width=\textwidth
*
* It can be used to free list data, as in the following example:
*
@@ -1438,19 +1327,24 @@ EAPI Eina_Accessor *eina_list_accessor_new(const Eina_List *list) EINA_MA
* eina_list_free(list);
* @endcode
*
- * @note This is not the optimal way to release memory allocated to
- * a list, since it iterates over the list twice.
- * For an optimized algorithm, use EINA_LIST_FREE().
+ * @remarks This is not the optimal way to release memory allocated to
+ * a list, since it iterates over the list twice.
+ * For an optimized algorithm, use EINA_LIST_FREE().
*
- * @warning @p list must be a pointer to the first element of the list.
+ * @remarks @a list must be a pointer to the first element of the list.
*
- * @warning Be careful when deleting list nodes.
+ * @remarks Be careful when deleting list nodes.
* If you remove the current node and continue iterating,
- * the code will fail because the macro will not be able
+ * the code fails because the macro is not able
* to get the next node. Notice that it's OK to remove any
* node if you stop the loop after that.
* For destructive operations such as this, consider
* using EINA_LIST_REVERSE_FOREACH_SAFE().
+ *
+ * @param list The list to iterate over
+ * @param l A list that is used as an iterator and points to the current node
+ * @param data The current item's data
+ *
*/
#define EINA_LIST_REVERSE_FOREACH(list, l, data) \
for (l = eina_list_last(list), \
@@ -1461,27 +1355,25 @@ EAPI Eina_Accessor *eina_list_accessor_new(const Eina_List *list) EINA_MA
/**
* @def EINA_LIST_FOREACH_SAFE
- * @brief Macro to iterate over a list with support for node deletion.
+ * @brief Definition of the macro to iterate over a list with support for node deletion.
+ *
+ * @details This macro iterates over @a list from the first element to
+ * the last. @a data is the data related to the current element.
+ * @a l is an #Eina_List used as the list iterator.
*
- * @param list The list to iterate over.
- * @param l A list that is used as an iterator and points to the current node.
- * @param l_next A list that is used as an iterator and points to the next node.
- * @param data Current item's data.
+ * @since_tizen 2.3
*
- * This macro iterates over @p list from the first element to
- * the last. @p data is the data related to the current element.
- * @p l is an #Eina_List used as the list iterator.
+ * @remarks Since this macro stores a pointer to the next list node in @a l_next,
+ * deleting the current node and continuing looping is safe.
*
- * Since this macro stores a pointer to the next list node in @p l_next,
- * deleting the current node and continuing looping is safe.
+ * @remarks The following diagram ilustrates this macro iterating over a list of four
+ * elements("one", "two", "three" and "four"):
*
- * The following diagram illustrates this macro iterating over a list of four
- * elements("one", "two", "three" and "four"):
+ * @image html eina-list-foreach-safe.png
* @htmlonly
- * <img src="eina-list-foreach-safe.png" style="max-width: 100%;" />
* <a href="eina-list-foreach-safe.png">Full-size</a>
* @endhtmlonly
- * @image latex eina-list-foreach-safe.eps "" width=\textwidth
+ * @image latex eina-list-foreach-safe.eps "eina list foreach safe" width=\textwidth
*
* This macro can be used to free list nodes, as in the following example:
*
@@ -1496,14 +1388,19 @@ EAPI Eina_Accessor *eina_list_accessor_new(const Eina_List *list) EINA_MA
* // EINA_LIST_FOREACH_SAFE will be used to free elements that match "key".
*
* EINA_LIST_FOREACH_SAFE(list, l, l_next, data)
- * if (strcmp(data, "key") == 0)
- * {
- * free(data);
- * list = eina_list_remove_list(list, l);
- * }
+ * if (strcmp(data, "key") == 0) {
+ * free(data);
+ * list = eina_list_remove_list(list, l);
+ * }
* @endcode
*
- * @warning @p list must be a pointer to the first element of the list.
+ * @remarks @a list must be a pointer to the first element of the list.
+ *
+ * @param list The list to iterate over
+ * @param l A list that is used as an iterator and points to the current node
+ * @param l_next A list that is used as an iterator and points to the next node
+ * @param data The current item's data
+ *
*/
#define EINA_LIST_FOREACH_SAFE(list, l, l_next, data) \
for (l = list, \
@@ -1516,29 +1413,27 @@ EAPI Eina_Accessor *eina_list_accessor_new(const Eina_List *list) EINA_MA
/**
* @def EINA_LIST_REVERSE_FOREACH_SAFE
- * @brief Macro to iterate over a list in the reverse order with support
+ * @brief Definition of the macro to iterate over a list in the reverse order with support
* for deletion.
*
- * @param list The list to iterate over.
- * @param l A list that is used as an iterator and points to the current node.
- * @param l_prev A list that is used as an iterator and points to the previous node.
- * @param data Current item's data.
+ * @details This macro works like EINA_LIST_FOREACH_SAFE, but iterates from the
+ * last element of a list to the first.
+ * @a data is the data related to the current element, while @a l
+ * is an #Eina_List that is used as the list iterator.
*
- * This macro works like EINA_LIST_FOREACH_SAFE, but iterates from the
- * last element of a list to the first.
- * @p data is the data related to the current element, while @p l
- * is an #Eina_List that is used as the list iterator.
+ * @since_tizen 2.3
*
- * Since this macro stores a pointer to the previous list node in @p l_prev,
- * deleting the current node and continuing looping is safe.
+ * @remarks Since this macro stores a pointer to the previous list node in @a l_prev,
+ * deleting the current node and continuing looping is safe.
*
- * The following diagram illustrates this macro iterating over a list of four
- * elements("one", "two", "three" and "four"):
+ * @remarks The following diagram ilustrates this macro iterating over a list of four
+ * elements("one", "two", "three" and "four"):
+ *
+ * @image html eina-list-reverse-foreach-safe.png
* @htmlonly
- * <img src="eina-list-reverse-foreach-safe.png" style="max-width: 100%;" />
* <a href="eina-list-reverse-foreach-safe.png">Full-size</a>
* @endhtmlonly
- * @image latex eina-list-reverse-foreach-safe.eps "" width=\textwidth
+ * @image latex eina-list-reverse-foreach-safe.eps "eina list reverse foreach safe" width=\textwidth
*
* This macro can be used to free list nodes, as in the following example:
*
@@ -1553,14 +1448,19 @@ EAPI Eina_Accessor *eina_list_accessor_new(const Eina_List *list) EINA_MA
* // EINA_LIST_REVERSE_FOREACH_SAFE will be used to free elements that match "key".
*
* EINA_LIST_REVERSE_FOREACH_SAFE(list, l, l_prev, data)
- * if (strcmp(data, "key") == 0)
- * {
- * free(data);
- * list = eina_list_remove_list(list, l);
- * }
+ * if (strcmp(data, "key") == 0) {
+ * free(data);
+ * list = eina_list_remove_list(list, l);
+ * }
* @endcode
*
- * @warning @p list must be a pointer to the first element of the list.
+ * @remarks @a list must be a pointer to the first element of the list.
+ *
+ * @param list The list to iterate over
+ * @param l A list that is used as an iterator and points to the current node
+ * @param l_prev A list that is used as an iterator and points to the previous node
+ * @param data The current item's data
+ *
*/
#define EINA_LIST_REVERSE_FOREACH_SAFE(list, l, l_prev, data) \
for (l = eina_list_last(list), \
@@ -1573,21 +1473,21 @@ EAPI Eina_Accessor *eina_list_accessor_new(const Eina_List *list) EINA_MA
/**
* @def EINA_LIST_FREE
- * @brief Macro to remove each list node while having access to each node's data.
+ * @brief Definition of the macro to remove each list node while having access to each node's data.
+ *
+ * @details This macro calls #eina_list_remove_list for each list node and stores
+ * the data contained in the current node in @a data.
*
- * @param list The list that will be cleared.
- * @param data Current node's data.
+ * @since_tizen 2.3
*
- * This macro will call #eina_list_remove_list for each list node, and store
- * the data contained in the current node in @p data.
+ * @remarks The following diagram ilustrates this macro iterating over a list of four
+ * elements("one", "two", "three" and "four"):
*
- * The following diagram illustrates this macro iterating over a list of four
- * elements("one", "two", "three" and "four"):
+ * @image html eina-list-free.png
* @htmlonly
- * <img src="eina-list-free.png" style="max-width: 100%;" />
* <a href="eina-list-free.png">Full-size</a>
* @endhtmlonly
- * @image latex eina-list-free.eps "" width=\textwidth
+ * @image latex eina-list-free.eps "eina list free" width=\textwidth
*
* If you do not need to release node data, it is easier to call #eina_list_free().
*
@@ -1602,7 +1502,10 @@ EAPI Eina_Accessor *eina_list_accessor_new(const Eina_List *list) EINA_MA
* free(data);
* @endcode
*
- * @warning @p list must be a pointer to the first element of the list.
+ * @remarks @a list must be a pointer to the first element of the list.
+ *
+ * @param list The list that is cleared
+ * @param data The current node's data
*
* @see eina_list_free()
*/
@@ -1618,12 +1521,4 @@ EAPI Eina_Accessor *eina_list_accessor_new(const Eina_List *list) EINA_MA
* @}
*/
-/**
- * @}
- */
-
-/**
- * @}
- */
-
#endif /* EINA_LIST_H_ */
diff --git a/src/lib/eina/eina_log.h b/src/lib/eina/eina_log.h
index 84e7f23655..ee609a0efd 100644
--- a/src/lib/eina/eina_log.h
+++ b/src/lib/eina/eina_log.h
@@ -1,14 +1,14 @@
/* EINA - EFL data type library
* Copyright (C) 2007-2008 Jorge Luis Zapata Muga, Cedric Bail
*
- * This library is free software; you can redistribute it and/or
+ * This library is a free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
@@ -39,189 +39,51 @@
#define EINA_COLOR_RESET "\033[0m"
#define EINA_COLOR_HIGH "\033[1m"
-
-/**
- * @page tutorial_log_page Log Tutorial
- *
- * @section tutorial_log_introduction Introduction
- *
- * The Eina Log module provides logging facilities for libraries and
- * applications. It provides colored logging, basic logging levels (error,
- * warning, debug, info, critical) and loggers - called logging domains -
- * which will be covered on next sections.
- *
- * @section tutorial_log_basic_usage Basic Usage
- *
- * Log messages can be displayed using the following macros:
- *
- * @li EINA_LOG_ERR(),
- * @li EINA_LOG_INFO(),
- * @li EINA_LOG_WARN(),
- * @li EINA_LOG_DBG().
- *
- * Here is an example:
- *
- * @include eina_log_02.c
- *
- * If you compiled Eina without debug mode, execution will yield only one log
- * message, which is "argument is negative".
- *
- * Here we introduce the concept of logging domains (or loggers), which might
- * already be familiar to readers. It is basically a way to separate a set of
- * log messages into a context (e.g. a module) and provide a way of controlling
- * this set as a whole.
- *
- * For example, suppose you have 3 different modules on your application and you
- * want to get logging only from one of them (e.g. create some sort of filter).
- * For achieving that, all you need to do is create a logging domain for each
- * module so that all logging inside a module can be considered as a whole.
- *
- * Logging domains are specified by a name, color applied to the name and the
- * level. The first two (name and color) are set through code, that is, inside
- * your application/module/library.
- *
- * The level is used for controlling which messages should appear. It
- * specifies the lowest level that should be displayed (e.g. a message
- * with level 11 being logged on a domain with level set to 10 would be
- * displayed, while a message with level 9 wouldn't).
- *
- * The domain level is set during runtime (in contrast with the name and
- * color) through the environment variable EINA_LOG_LEVELS. This variable
- * expects a list in the form domain_name1:level1,domain_name2:level2,... . For
- * example:
- *
- * @verbatim EINA_LOG_LEVELS=mymodule1:5,mymodule2:2,mymodule3:0 ./myapp@endverbatim
- *
- * This line would set mymodule1 level to 5, mymodule2 level to 2 and mymodule3
- * level to 0.
- *
- * There's also a global logger to which EINA_LOG_(ERR, DBG, INFO, CRIT, WARN)
- * macros do log on. It is a logger that is created internally by Eina Log with
- * an empty name and can be used for general logging (where logging domains do
- * not apply).
- *
- * Since this global logger doesn't have a name, you can't set its level through
- * EINA_LOG_LEVELS variable. Here we introduce a second environment variable
- * that is a bit more special: EINA_LOG_LEVEL.
- *
- * This variable specifies the level of the global logging domain and the level
- * of domains that haven't been set through EINA_LOG_LEVELS. Here's an example:
- *
- * @verbatim EINA_LOG_LEVEL=3 EINA_LOG_LEVELS=module1:10,module3:2 ./myapp@endverbatim
- *
- * Supposing you have modules named "module1", "module2" and "module3", this
- * line would result in module1 with level 10, module2 with level 3 and module3
- * with level 2. Note that module2's level wasn't specified, so it's level is
- * set to the global level. This way we can easily apply filters to multiple
- * domains with only one parameter (EINA_LOG_LEVEL=num).
- *
- * The global level (EINA_LOG_LEVEL) can also be set through code, using
- * eina_log_level_set() function.
- *
- * While developing your libraries or applications, you may notice that
- * EINA_LOG_DOM_(ERR, DBG, INFO, CRIT, WARN) macros also print out
- * messages from eina itself. Here we introduce another environment variable
- * that is a bit more special: EINA_LOG_LEVELS_GLOB.
- *
- * This variable allows you to disable the logging of any/all code in eina itself.
- * This is useful when developing your libraries or applications so that you can
- * see your own domain's messages easier without having to sift through a lot of
- * internal eina debug messages. Here's an example:
- *
- * @verbatim EINA_LOG_LEVEL=3 EINA_LOG_LEVELS_GLOB=eina_*:0 ./myapp@endverbatim
- *
- * This will disable eina_log output from all internal eina code thus allowing
- * you to see your own domain messages easier.
- *
- * @section tutorial_log_advanced_display Advanced usage of print callbacks
- *
- * The log module allows the user to change the way
- * eina_log_print() displays the messages. It suffices to pass to
- * eina_log_print_cb_set() the function used to display the
- * message. That function must be of type #Eina_Log_Print_Cb. As a
- * custom data can be passed to that callback, powerful display
- * messages can be displayed.
- *
- * It is suggested to not use __FILE__, __FUNCTION__ or __LINE__ when
- * writing that callback, but when defining macros (like
- * EINA_LOG_ERR() and other macros).
- *
- * Here is an example of custom callback, whose behavior can be
- * changed at runtime:
- *
- * @include eina_log_03.c
- * @example eina_log_02.c
- * @example eina_log_03.c
- */
-
/**
- * @addtogroup Eina_Log_Group Log
- *
* @brief Full-featured logging system.
*
* Eina provides eina_log_print(), a standard function to manage all
- * logging messages. This function may be called directly or using the
- * helper macros such as EINA_LOG_DBG(), EINA_LOG_ERR() or those that
- * take a specific domain as argument EINA_LOG_DOM_DBG(),
- * EINA_LOG_DOM_ERR(). Internally, eina_log_print() will call the
+ * logging messages. This function may be called directly or by using the
+ * helper macros such as EINA_LOG_DBG(), EINA_LOG_ERR(), or those that
+ * take a specific domain as an argument such as EINA_LOG_DOM_DBG(),
+ * EINA_LOG_DOM_ERR(). Internally, eina_log_print() calls the
* function defined with eina_log_print_cb_set(), that defaults to
* eina_log_print_cb_stderr(), but may be changed to do whatever you
* need, such as networking or syslog logging.
*
* The logging system is thread safe once initialized with
* eina_log_threads_enable(). The thread that calls this function
- * first is considered "main thread" and other threads will have their
- * thread id (pthread_self()) printed in the log message so it is easy
+ * first is considered "main thread" and other threads have their
+ * thread ID (pthread_self()) printed in the log message so it is easy
* to detect from where it is coming.
*
- * Log domains is the Eina way to differentiate messages. There might
+ * Log domains is the Eina way to differentiate between messages. There might
* be different domains to represent different modules, different
- * feature-set, different categories and so on. Filtering can be
+ * feature-sets, different categories, and so on. Filtering can be
* applied to domain names by means of @c EINA_LOG_LEVELS environment
* variable or eina_log_domain_level_set().
*
* The different logging levels serve to customize the amount of
- * debugging one want to take and may be used to automatically call
+ * debugging one might want to take and may be used to automatically call
* abort() once some given level message is printed. This is
- * controlled by environment variable @c EINA_LOG_ABORT and the level
- * to be considered critical with @c EINA_LOG_ABORT_LEVEL. These can
- * be changed with eina_log_abort_on_critical_set() and
+ * controlled by an environment variable @c EINA_LOG_ABORT and the level
+ * to be considered critical, which is @c EINA_LOG_ABORT_LEVEL. These can
+ * be changed by eina_log_abort_on_critical_set() and
* eina_log_abort_on_critical_level_set().
*
* The default maximum level to print is defined by environment
* variable @c EINA_LOG_LEVEL, but may be set per-domain with @c
- * EINA_LOG_LEVELS. It will default to #EINA_LOG_ERR. This can be
- * changed with eina_log_level_set().
+ * EINA_LOG_LEVELS. It defaults to #EINA_LOG_ERR. This can be
+ * changed by eina_log_level_set().
*
* To use the log system Eina must be initialized with eina_init() and
- * later shut down with eina_shutdown(). Here is a straightforward
- * example:
- *
- * @include eina_log_01.c
- *
- * Compile this code with the following command:
- *
- * @verbatim gcc -Wall -o eina_log_01 eina_log_01.c `pkg-config --cflags --libs eina`@endverbatim
- *
- * Now execute the program with:
- *
- * @verbatim EINA_LOG_LEVEL=2 ./eina_log_01@endverbatim
- *
- * You should see a message displayed in the terminal.
- *
- * For more information, you can look at the @ref tutorial_log_page.
- *
- * @example eina_log_01.c
- */
-
-/**
- * @addtogroup Eina_Tools_Group Tools
- *
- * @{
+ * later shut down with eina_shutdown().
*/
/**
+ * @internal
* @defgroup Eina_Log_Group Log
+ * @ingroup Eina_Tools_Group
*
* @{
*/
@@ -236,15 +98,15 @@ EAPI extern int EINA_LOG_DOMAIN_GLOBAL;
/**
* @def EINA_LOG_DOMAIN_DEFAULT
- * This macro defines the domain to use with the macros EINA_LOG_DOM_DBG(),
- * EINA_LOG_DOM_INFO(), EINA_LOG_DOM_WARN(), EINA_LOG_DOM_ERR() and
- * EINA_LOG_DOM_CRIT().
+ * @brief Definition of the macro that defines the domain to use with the macros EINA_LOG_DOM_DBG(),
+ * EINA_LOG_DOM_INFO(), EINA_LOG_DOM_WARN(), EINA_LOG_DOM_ERR(), and
+ * EINA_LOG_DOM_CRIT().
*
- * If not defined prior to the inclusion of this header, then it
- * defaults to #EINA_LOG_DOMAIN_GLOBAL.
+ * @remarks If not defined prior to the inclusion of this header, then it
+ * defaults to #EINA_LOG_DOMAIN_GLOBAL.
*
- * @note One may like to redefine this in its code to avoid typing too
- * much. In this case the recommended way is:
+ * @remarks One may like to redefine this in its code to avoid typing too
+ * much. In this case, the recommended way is:
*
* @code
* #include <Eina.h>
@@ -261,10 +123,10 @@ EAPI extern int EINA_LOG_DOMAIN_GLOBAL;
* }
* @endcode
*
- * @warning If one defines the domain prior to inclusion of this
+ * @remarks If one defines the domain prior to inclusion of this
* header, the defined log domain symbol must be defined
* prior as well, otherwise the inlined functions defined by
- * Eina will fail to find the symbol, causing build failure.
+ * Eina fail to find the symbol, causing a build failure.
*
* @code
* #define EINA_LOG_DOMAIN_DEFAULT _log_dom
@@ -287,17 +149,17 @@ EAPI extern int EINA_LOG_DOMAIN_GLOBAL;
/**
* @def EINA_LOG(DOM, LEVEL, fmt, ...)
- * Logs a message on the specified domain, level and format.
- *
- * @note if @c EINA_LOG_LEVEL_MAXIMUM is defined, then messages larger
- * than this value will be ignored regardless of current domain
- * level, the eina_log_print() is not even called! Most
- * compilers will just detect the two integers make the branch
- * impossible and remove the branch and function call all
- * together. Take this as optimization tip and possible remove
- * debug messages from binaries to be deployed, saving on hot
- * paths. Never define @c EINA_LOG_LEVEL_MAXIMUM on public
- * header files.
+ * @brief Definition that logs a message on the specified domain, level, and format.
+ *
+ * @remarks If @c EINA_LOG_LEVEL_MAXIMUM is defined, then messages larger
+ * than this value are ignored regardless of the current domain
+ * level, eina_log_print() is not even called. Most
+ * compilers just detect the two integers that make the branch
+ * impossible and remove the branch and function call all
+ * together. Take this as an optimization tip and possibly remove
+ * debug messages from binaries to be deployed, saving on hot
+ * paths. Never define @c EINA_LOG_LEVEL_MAXIMUM on public
+ * header files.
*/
#ifdef EINA_ENABLE_LOG
# ifdef EINA_LOG_LEVEL_MAXIMUM
@@ -324,43 +186,43 @@ EAPI extern int EINA_LOG_DOMAIN_GLOBAL;
/**
* @def EINA_LOG_DOM_CRIT(DOM, fmt, ...)
- * Logs a message with level CRITICAL on the specified domain and format.
+ * @brief Definition that logs a message with level as CRITICAL on the specified domain and format.
*/
#define EINA_LOG_DOM_CRIT(DOM, fmt, ...) \
EINA_LOG(DOM, EINA_LOG_LEVEL_CRITICAL, fmt, ## __VA_ARGS__)
/**
* @def EINA_LOG_DOM_ERR(DOM, fmt, ...)
- * Logs a message with level ERROR on the specified domain and format.
+ * @brief Definition that logs a message with level as ERROR on the specified domain and format.
*/
#define EINA_LOG_DOM_ERR(DOM, fmt, ...) \
EINA_LOG(DOM, EINA_LOG_LEVEL_ERR, fmt, ## __VA_ARGS__)
/**
* @def EINA_LOG_DOM_INFO(DOM, fmt, ...)
- * Logs a message with level INFO on the specified domain and format.
+ * @brief Definition that logs a message with level as INFO on the specified domain and format.
*/
#define EINA_LOG_DOM_INFO(DOM, fmt, ...) \
EINA_LOG(DOM, EINA_LOG_LEVEL_INFO, fmt, ## __VA_ARGS__)
/**
* @def EINA_LOG_DOM_DBG(DOM, fmt, ...)
- * Logs a message with level DEBUG on the specified domain and format.
+ * @brief Definition that logs a message with level as DEBUG on the specified domain and format.
*/
#define EINA_LOG_DOM_DBG(DOM, fmt, ...) \
EINA_LOG(DOM, EINA_LOG_LEVEL_DBG, fmt, ## __VA_ARGS__)
/**
* @def EINA_LOG_DOM_WARN(DOM, fmt, ...)
- * Logs a message with level WARN on the specified domain and format.
+ * @brief Definition that logs a message with level as WARN on the specified domain and format.
*/
#define EINA_LOG_DOM_WARN(DOM, fmt, ...) \
EINA_LOG(DOM, EINA_LOG_LEVEL_WARN, fmt, ## __VA_ARGS__)
/**
* @def EINA_LOG_CRIT(fmt, ...)
- * Logs a message with level CRITICAL on the default domain with the specified
- * format.
+ * @brief Definition that logs a message with level as CRITICAL on the default domain with the specified
+ * format.
*/
#define EINA_LOG_CRIT(fmt, ...) \
EINA_LOG(EINA_LOG_DOMAIN_DEFAULT, \
@@ -370,87 +232,79 @@ EAPI extern int EINA_LOG_DOMAIN_GLOBAL;
/**
* @def EINA_LOG_ERR(fmt, ...)
- * Logs a message with level ERROR on the default domain with the specified
- * format.
+ * @brief Definition that logs a message with level as ERROR on the default domain with the specified
+ * format.
*/
#define EINA_LOG_ERR(fmt, ...) \
EINA_LOG(EINA_LOG_DOMAIN_DEFAULT, EINA_LOG_LEVEL_ERR, fmt, ## __VA_ARGS__)
/**
* @def EINA_LOG_INFO(fmt, ...)
- * Logs a message with level INFO on the default domain with the specified
- * format.
+ * @brief Definition that logs a message with level as INFO on the default domain with the specified
+ * format.
*/
#define EINA_LOG_INFO(fmt, ...) \
EINA_LOG(EINA_LOG_DOMAIN_DEFAULT, EINA_LOG_LEVEL_INFO, fmt, ## __VA_ARGS__)
/**
* @def EINA_LOG_WARN(fmt, ...)
- * Logs a message with level WARN on the default domain with the specified
- * format.
+ * @brief Definition that logs a message with level as WARN on the default domain with the specified
+ * format.
*/
#define EINA_LOG_WARN(fmt, ...) \
EINA_LOG(EINA_LOG_DOMAIN_DEFAULT, EINA_LOG_LEVEL_WARN, fmt, ## __VA_ARGS__)
/**
* @def EINA_LOG_DBG(fmt, ...)
- * Logs a message with level DEBUG on the default domain with the specified
- * format.
+ * @brief Definition that logs a message with level as DEBUG on the default domain with the specified
+ * format.
*/
#define EINA_LOG_DBG(fmt, ...) \
EINA_LOG(EINA_LOG_DOMAIN_DEFAULT, EINA_LOG_LEVEL_DBG, fmt, ## __VA_ARGS__)
/**
* @typedef Eina_Log_Domain
- * The domain used for logging.
+ * @brief The structure type containing the domain used for logging.
*/
typedef struct _Eina_Log_Domain Eina_Log_Domain;
/**
* @struct _Eina_Log_Domain
- * The domain used for logging.
+ * @brief The structure type containing the domain used for logging.
*/
struct _Eina_Log_Domain
{
- int level; /**< Max level to log */
+ int level; /**< Maximum level to log */
const char *domain_str; /**< Formatted string with color to print */
const char *name; /**< Domain name */
size_t namelen; /**< strlen(name) */
/* Private */
Eina_Bool deleted : 1; /**< Flags deletion of domain, a free slot */
-
- /* Add new members here. */
- const char *color; /**< Color to use when printing in this domain */
};
/**
- * Enable logging module to handle threads.
+ * @brief Enables logging module to handle threads.
*
- * There is no disable option on purpose, if it is enabled, there is
- * no way back until you call the last eina_shutdown().
+ * @remarks There is no disable option on purpose, if it is enabled, there is
+ * no way back until you call the last eina_shutdown().
*
- * There is no function to retrieve if threads are enabled as one is
- * not supposed to know this from outside.
+ * @remarks There is no function to retrieve if threads are enabled as one is
+ * not supposed to know this from outside.
*
- * After this call is executed at least once, if Eina was compiled
- * with threads support then logging will lock around debug messages
- * and threads that are not the main thread will have its identifier
- * printed.
+ * @remarks After this call is executed at least once, if Eina is compiled
+ * with threads support then logging locks around debug messages
+ * and threads that are not the main thread is going to have its identifier
+ * printed.
*
- * The main thread is considered the thread where the first
- * eina_init() was called.
+ * The main thread is considered the thread where the first
+ * eina_init() was called.
*/
EAPI void eina_log_threads_enable(void);
-
-/**
- * @typedef Eina_Log_Level
- * List of available logging levels.
- */
/**
* @enum _Eina_Log_Level
- * List of available logging levels.
+ * @brief Enumeration for the list of available logging levels.
*/
typedef enum _Eina_Log_Level
{
@@ -465,165 +319,162 @@ typedef enum _Eina_Log_Level
/**
* @typedef Eina_Log_Print_Cb
- * Type for print callbacks.
+ * Called to print callbacks.
*/
typedef void (*Eina_Log_Print_Cb)(const Eina_Log_Domain *d,
Eina_Log_Level level,
const char *file, const char *fnc, int line,
const char *fmt, void *data, va_list args);
-/**
- * @typedef Eina_Log_State
- * List of available log states.
- */
-/**
- * @enum _Eina_Log_State
- * List of available log states.
- */
-typedef enum _Eina_Log_State
-{
- EINA_LOG_STATE_START,
- EINA_LOG_STATE_STOP
-} Eina_Log_State;
-
/*
* Customization
*/
/**
- * Sets logging method to use.
+ * @brief Sets the logging function to use.
*
- * @param cb The callback to call when printing a log.
- * @param data The data to pass to the callback.
+ * @since_tizen 2.3
*
- * By default, eina_log_print_cb_stderr() is used.
+ * @remarks By default, eina_log_print_cb_stderr() is used.
+ * @remarks It is safe to call from any thread.
+ * @remarks The given function @a cb is called protected by mutex.
+ * This means you're safe from other calls but you should never
+ * call eina_log_print(), directly or indirectly.
*
- * @note MT: safe to call from any thread.
+ * @param[in] cb The callback to call when printing a log
+ * @param[in] data The data to pass to the callback
*
- * @note MT: given function @a cb will be called protected by mutex.
- * This means you're safe from other calls but you should never
- * call eina_log_print(), directly or indirectly.
*/
EAPI void eina_log_print_cb_set(Eina_Log_Print_Cb cb, void *data) EINA_ARG_NONNULL(1);
/**
- * @brief Set the default log level.
+ * @brief Sets the default log level.
*
- * @param level The log level.
+ * @details This function sets the log level @a level. It is used in
+ * eina_log_print().
*
- * This function sets the log level @p level. It is used in
- * eina_log_print().
+ * @since_tizen 2.3
*
- * @note this is initially set to envvar EINA_LOG_LEVEL by eina_init().
+ * @remarks This is initially set to envvar EINA_LOG_LEVEL by eina_init().
+ *
+ * @param[in] level The log level
*
* @see eina_log_level_get()
*/
EAPI void eina_log_level_set(int level);
/**
- * @brief Get the default log level.
+ * @brief Gets the default log level.
+ *
+ * @since_tizen 2.3
*
- * @return the log level that limits eina_log_print().
+ * @return The log level that limits eina_log_print()
*
* @see eina_log_level_set()
*/
EAPI int eina_log_level_get(void) EINA_WARN_UNUSED_RESULT;
-/**
- * @brief Determine if a given @p level should be logged.
- *
- * @return #EINA_TRUE if the @p level should be logged, else #EINA_FALSE.
- *
- * @see eina_log_level_set()
- */
static inline Eina_Bool eina_log_level_check(int level);
/**
- * @brief Checks if current thread is the main thread.
+ * @brief Checks whether the current thread is the main thread.
+ *
+ * @since_tizen 2.3
*
- * If there is no thread support (compiled with --disable-pthreads) or
- * threads were not enabled, then #EINA_TRUE is returned. The only case where
- * #EINA_FALSE is returned is when threads were successfully enabled but the
- * current thread is not the one that called eina_log_threads_init() (the
- * manin thread).
- *
- * @return #EINA_TRUE if the current thread is the one that called
- * eina_log_threads_init(), otherwise #EINA_FALSE.
+ * @return @c EINA_TRUE if threads are enabled and the current thread
+ * is the one that called eina_log_threads_init() \n
+ * If there is no thread support (compiled with --disable-pthreads) or
+ * they are not enabled, then @c EINA_TRUE is also
+ * returned \n
+ * The only case where @c EINA_FALSE is returned is
+ * when threads are successfully enabled but the current
+ * thread is not the main (one that called
+ * eina_log_threads_init()).
*/
EAPI Eina_Bool eina_log_main_thread_check(void) EINA_CONST EINA_WARN_UNUSED_RESULT;
/**
- * @brief Enable or disable colored text in the logs.
+ * @brief Sets whether color logging should be disabled.
*
- * @param disabled If #EINA_TRUE, color logging should be disabled.
+ * @since_tizen 2.3
*
- * @note this is initially set to envvar EINA_LOG_COLOR_DISABLE by eina_init().
+ * @remarks This is initially set to envvar EINA_LOG_COLOR_DISABLE by eina_init().
+ *
+ * @param[in] disabled If @c EINA_TRUE color logging should be disabled
*
* @see eina_log_color_disable_get()
*/
EAPI void eina_log_color_disable_set(Eina_Bool disabled);
/**
- * @brief Determine if color logging is enabled or disabled.
+ * @brief Gets whether color logging should be disabled.
+ *
+ * @since_tizen 2.3
*
- * @return If #EINA_TRUE, color logging is disabled.
+ * @return @c EINA_TRUE if color logging should be disabled
*
* @see eina_log_color_disable_set()
*/
EAPI Eina_Bool eina_log_color_disable_get(void) EINA_WARN_UNUSED_RESULT;
/**
- * @brief Set if originating file name logging should be disabled.
+ * @brief Sets whether originating file name logging should be disabled.
*
- * @param disabled if #EINA_TRUE, file name logging should be disabled.
+ * @since_tizen 2.3
*
- * @note this is initially set to envvar EINA_LOG_FILE_DISABLE by eina_init().
+ * @remarks This is initially set to envvar EINA_LOG_FILE_DISABLE by eina_init().
+ *
+ * @param[in] disabled If @c EINA_TRUE file name logging should be disabled
*
* @see eina_log_file_disable_get()
*/
EAPI void eina_log_file_disable_set(Eina_Bool disabled);
/**
- * @brief Get if originating file name logging should be disabled.
+ * @brief Gets whether originating file name logging should be disabled.
+ *
+ * @since_tizen 2.3
*
- * @return if #EINA_TRUE, file name logging should be disabled.
+ * @return @c EINA_TRUE if file name logging should be disabled
*
* @see eina_log_file_disable_set()
*/
EAPI Eina_Bool eina_log_file_disable_get(void) EINA_WARN_UNUSED_RESULT;
/**
- * @brief Set if originating function name logging should be disabled.
+ * @brief Sets whether originating function name logging should be disabled.
*
- * @param disabled if #EINA_TRUE, function name logging should be disabled.
+ * @since_tizen 2.3
*
- * @note this is initially set to envvar EINA_LOG_FUNCTION_DISABLE by
- * eina_init().
+ * @remarks This is initially set to envvar EINA_LOG_FUNCTION_DISABLE by
+ * eina_init().
+ *
+ * @param[in] disabled If @c EINA_TRUE function name logging should be disabled
*
* @see eina_log_function_disable_get()
*/
EAPI void eina_log_function_disable_set(Eina_Bool disabled);
/**
- * @brief Get if originating function name logging should be disabled.
+ * @brief Gets whether originating function name logging should be disabled.
*
- * @return if #EINA_TRUE, function name logging should be disabled.
+ * @return @c EINA_TRUE if function name logging should be disabled
*
* @see eina_log_function_disable_set()
*/
EAPI Eina_Bool eina_log_function_disable_get(void) EINA_WARN_UNUSED_RESULT;
/**
- * @brief Set if critical messages should abort the program.
+ * @brief Sets whether critical messages should abort the program.
*
- * @param abort_on_critical if #EINA_TRUE, messages with level equal
- * or smaller than eina_log_abort_on_critical_level_get() will
- * abort the program.
+ * @remarks This is initially set to envvar EINA_LOG_ABORT by
+ * eina_init().
*
- * @note this is initially set to envvar EINA_LOG_ABORT by
- * eina_init().
+ * @param[in] abort_on_critical If @c EINA_TRUE, messages with level equal to
+ * or smaller than eina_log_abort_on_critical_level_get()
+ * abort the program.
*
* @see eina_log_abort_on_critical_get()
* @see eina_log_abort_on_critical_level_set()
@@ -631,11 +482,13 @@ EAPI Eina_Bool eina_log_function_disable_get(void) EINA_WARN_UNUSED_RES
EAPI void eina_log_abort_on_critical_set(Eina_Bool abort_on_critical);
/**
- * @brief Get if critical messages should abort the program.
+ * @brief Gets whether critical messages should abort the program.
+ *
+ * @since_tizen 2.3
*
- * @return if #EINA_TRUE, any messages with level equal or smaller
- * than eina_log_abort_on_critical_level_get() will abort the
- * program.
+ * @return @c EINA_TRUE if messages with level equal to or smaller
+ * than eina_log_abort_on_critical_level_get() abort the
+ * program
*
* @see eina_log_abort_on_critical_set()
* @see eina_log_abort_on_critical_level_set()
@@ -643,14 +496,15 @@ EAPI void eina_log_abort_on_critical_set(Eina_Bool abort_on_critic
EAPI Eina_Bool eina_log_abort_on_critical_get(void) EINA_WARN_UNUSED_RESULT;
/**
- * @brief Set level that triggers abort if abort-on-critical is set.
+ * @brief Sets the level that triggers abort if abort-on-critical is set.
*
- * @param critical_level levels equal or smaller than the given value
- * will trigger program abortion if
- * eina_log_abort_on_critical_get() returns #EINA_TRUE.
+ * @since_tizen 2.3
*
- * @note this is initially set to envvar EINA_LOG_ABORT_LEVEL by
- * eina_init().
+ * @remarks This is initially set to envvar EINA_LOG_ABORT_LEVEL by
+ * eina_init().
+ *
+ * @param[in] critical_level If @c EINA_TRUE, levels equal to or smaller than
+ * eina_log_abort_on_critical_get() triggers program abortion
*
* @see eina_log_abort_on_critical_level_get()
* @see eina_log_abort_on_critical_get()
@@ -658,11 +512,12 @@ EAPI Eina_Bool eina_log_abort_on_critical_get(void) EINA_WARN_UNUSED_RE
EAPI void eina_log_abort_on_critical_level_set(int critical_level);
/**
- * @brief Get level that triggers abort if abort-on-critical is set.
+ * @brief Gets the level that triggers abort if abort-on-critical is set.
+ *
+ * @since_tizen 2.3
*
- * @return critical level equal or smaller than value will trigger
- * program abortion if eina_log_abort_on_critical_get()
- * returns #EINA_TRUE.
+ * @return @c EINA_TRUE if the critical level equal to or smaller than
+ * eina_log_abort_on_critical_get() triggers program abortion
*
* @see eina_log_abort_on_critical_level_set()
* @see eina_log_abort_on_critical_get()
@@ -671,32 +526,39 @@ EAPI int eina_log_abort_on_critical_level_get(void) EINA_WARN_UNU
/**
- * Set the domain level given its name.
+ * @brief Sets the domain level given that its name is provided.
*
- * This call has the same effect as setting
- * EINA_LOG_LEVELS=&lt;@p domain_name&gt;:&lt;@p level&gt;
+ * @since_tizen 2.3
*
- * @param domain_name domain name to change the level. It may be of a
- * still not registered domain. If the domain is not registered
- * yet, it will be saved as a pending set and applied upon
- * registration.
- * @param level level to use to limit eina_log_print() for given domain.
+ * @remarks This call has the same effect as setting
+ * EINA_LOG_LEVELS=&lt;@a domain_name&gt;:&lt;@a level&gt;
+ *
+ * @param[in] domain_name The domain name to change the level \n
+ * It may be of a still not registered domain \n
+ * If the domain is not registered
+ * yet, it is saved as a pending set and applied upon
+ * registration.
+ * @param[in] level The level to use to limit eina_log_print() for the given domain
*/
EAPI void eina_log_domain_level_set(const char *domain_name, int level) EINA_ARG_NONNULL(1);
/**
- * Get the domain level given its name.
+ * @brief Gets the domain level given that its name is provided.
+ *
+ * @since_tizen 2.3
*
- * @param domain_name domain name to retrieve the level. It may be of
- * a still not registered domain. If the domain is not
- * registered yet, but there is a pending value, either from
- * eina_log_domain_level_set(),EINA_LOG_LEVELS environment
- * variable or from EINA_LOG_LEVELS_GLOB, these are
- * returned. If nothing else was found, then the global/default
- * level (eina_log_level_get()) is returned.
+ * @param[in] domain_name The domain name to retrieve the level \n
+ * It may be of a still not registered domain \n
+ * If the domain is not registered yet, but there is a pending value either from
+ * eina_log_domain_level_set(), EINA_LOG_LEVELS environment
+ * variable, or EINA_LOG_LEVELS_GLOB, these are
+ * returned \n
+ * If nothing else is found, then the global/default
+ * level (eina_log_level_get()) is returned.
*
- * @return level to use to limit eina_log_print() for given
- * domain. On error (@p domain_name == NULL),
+ * @return The level to use to limit eina_log_print() for the given
+ * domain \n
+ * On error (@a domain_name == NULL),
* EINA_LOG_LEVEL_UNKNOWN is returned.
*
* @see eina_log_domain_level_set()
@@ -705,29 +567,19 @@ EAPI void eina_log_domain_level_set(const char *domain_name, int l
EAPI int eina_log_domain_level_get(const char *domain_name) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
/**
- * Get the domain level given its identifier.
+ * @brief Gets the domain level given that its identifier is provided.
*
- * @param domain identifier, so it must be previously registered with
- * eina_log_domain_register(). It's a much faster version of
- * eina_log_domain_level_get(), but relies on domain being
- * present.
+ * @since_tizen 2.3
*
- * @return #EINA_TRUE if level should be printed, #EINA_FALSE if not.
- * (domain's level is greater or equal @a level).
- */
-EAPI int eina_log_domain_registered_level_get(int domain) EINA_WARN_UNUSED_RESULT;
-
-/**
- * Set the domain level given its identifier.
+ * @param[in] domain The domain identifier, so it must be previously registered with
+ * eina_log_domain_register() \n
+ * It's a much faster version of eina_log_domain_level_get(),
+ * but relies on the domain being present.
*
- * @param domain identifier, so it must be previously registered with
- * eina_log_domain_register(). It's a much faster version of
- * eina_log_domain_level_get(), but relies on domain being
- * present.
- * @param level level to use to limit eina_log_print() for given domain.
- * @since 1.10
+ * @return @c EINA_TRUE if the level should be printed, otherwise @c EINA_FALSE if not
+ * (domain's level is greater than or equal to @a level)
*/
-EAPI void eina_log_domain_registered_level_set(int domain, int level);
+EAPI int eina_log_domain_registered_level_get(int domain) EINA_WARN_UNUSED_RESULT;
static inline Eina_Bool eina_log_domain_level_check(int domain, int level);
@@ -736,23 +588,30 @@ static inline Eina_Bool eina_log_domain_level_check(int domain, int level);
*/
/**
- * @param name Domain name
- * @param color Color of the domain name
+ * @brief Logs domains
+ *
+ * @since_tizen 2.3
*
- * @return Domain index that will be used as the DOMAIN parameter on log
- * macros. A negative return value means an log occurred.
+ * @remarks It is safe to call from any thread.
*
- * @note MT: safe to call from any thread.
+ * @param[in] name The domain name
+ * @param[in] color The color of the domain name
+ *
+ * @return The domain index that is used as the DOMAIN parameter on log
+ * macros \n
+ * A negative return value means a log occurred.
*/
EAPI int eina_log_domain_register(const char *name, const char *color) EINA_ARG_NONNULL(1);
/**
- * Forget about a logging domain registered by eina_log_domain_register()
+ * @brief Forgets about a logging domain registered by eina_log_domain_register().
+ *
+ * @since_tizen 2.3
*
- * @param domain domain identifier as reported by eina_log_domain_register(),
- * must be >= 0.
+ * @remarks It is safe to call from any thread.
*
- * @note MT: safe to call from any thread.
+ * @param[in] domain The domain identifier as reported by eina_log_domain_register(),
+ * must be >= 0
*/
EAPI void eina_log_domain_unregister(int domain);
@@ -761,27 +620,29 @@ EAPI void eina_log_domain_unregister(int domain);
*/
/**
- * Print out log message using given domain and level.
+ * @brief Prints out log messages using the given domain and level.
*
- * @note Usually you'll not use this function directly but the helper
- * macros EINA_LOG(), EINA_LOG_DOM_CRIT(), EINA_LOG_CRIT() and
- * so on. See eina_log.h
+ * @details This function may be called from different threads if
+ * eina_log_threads_enable() is called before.
*
- * @param domain logging domain to use or @c EINA_LOG_DOMAIN_GLOBAL if
- * you registered none. It is recommended that modules and
- * applications have their own logging domain.
- * @param level message level, those with level greater than user
- * specified value (eina_log_level_set() or environment
- * variables EINA_LOG_LEVEL, EINA_LOG_LEVELS) will be ignored.
- * @param file filename that originated the call, must @b not be @c NULL.
- * @param function function that originated the call, must @b not be @c NULL.
- * @param line originating line in @a file.
- * @param fmt printf-like format to use. Should not provide trailing
- * '\n' as it is automatically included.
- * @param ... variadic args.
+ * @since_tizen 2.3
*
- * @note MT: this function may be called from different threads if
- * eina_log_threads_enable() was called before.
+ * @remarks Usually you do not use this function directly but the helper
+ * macros EINA_LOG(), EINA_LOG_DOM_CRIT(), EINA_LOG_CRIT(), and
+ * so on. See eina_log.h
+ *
+ * @param[in] domain The logging domain to use, otherwise @c EINA_LOG_DOMAIN_GLOBAL if
+ * you registered none \n
+ * It is recommended that modules and
+ * applications have their own logging domain.
+ * @param[in] level The message level, those with levels greater than the user
+ * specified value (eina_log_level_set() or environment
+ * variables like EINA_LOG_LEVEL, EINA_LOG_LEVELS) are ignored
+ * @param[in] file The filename that originated the call, must @b not be @c NULL
+ * @param[in] function The function that originated the call, must @b not be @c NULL
+ * @param[in] line The originating line in @a file
+ * @param[in] fmt The printf-like format to use, should not provide trailing
+ * '\n' as it is automatically included
*/
EAPI void eina_log_print(int domain,
Eina_Log_Level level,
@@ -792,27 +653,30 @@ EAPI void eina_log_print(int domain,
...) EINA_ARG_NONNULL(3, 4, 6) EINA_PRINTF(6, 7) EINA_NOINSTRUMENT;
/**
- * Print out log message using given domain and level.
+ * @brief Prints out log messages using the given domain and level.
+ *
+ * @details This function may be called from different threads if
+ * eina_log_threads_enable() is called before.
*
- * @note Usually you'll not use this function directly but the helper
- * macros EINA_LOG(), EINA_LOG_DOM_CRIT(), EINA_LOG_CRIT() and
- * so on. See eina_log.h
+ * @since_tizen 2.3
*
- * @param domain logging domain to use or @c EINA_LOG_DOMAIN_GLOBAL if
- * you registered none. It is recommended that modules and
- * applications have their own logging domain.
- * @param level message level, those with level greater than user
- * specified value (eina_log_level_set() or environment
- * variables EINA_LOG_LEVEL, EINA_LOG_LEVELS) will be ignored.
- * @param file filename that originated the call, must @b not be @c NULL.
- * @param fnc function that originated the call, must @b not be @c NULL.
- * @param line originating line in @a file.
- * @param fmt printf-like format to use. Should not provide trailing
- * '\n' as it is automatically included.
- * @param args the arguments needed by the format.
+ * @remarks Usually you do not use this function directly, but the helper
+ * macros like EINA_LOG(), EINA_LOG_DOM_CRIT(), EINA_LOG_CRIT(), and
+ * so on. See eina_log.h
*
- * @note MT: this function may be called from different threads if
- * eina_log_threads_enable() was called before.
+ * @param[in] domain The logging domain to use, otherwise @c EINA_LOG_DOMAIN_GLOBAL if
+ * you registered none \n
+ * It is recommended that modules and
+ * applications have their own logging domain.
+ * @param[in] level The message level, those with levels greater than the user
+ * specified value (eina_log_level_set() or environment
+ * variables like EINA_LOG_LEVEL, EINA_LOG_LEVELS) are ignored
+ * @param[in] file The filename that originated the call, must @b not be @c NULL
+ * @param[in] fnc The function that originated the call, must @b not be @c NULL
+ * @param[in] line The originating line in @a file.
+ * @param[in] fmt The printf-like format to use, should not provide trailing
+ * '\n' as it is automatically included
+ * @param[in] args The arguments needed by the format.
*
* @see eina_log_print()
*/
@@ -829,30 +693,33 @@ EAPI void eina_log_vprint(int domain,
*/
/**
- * @brief Alternative logging method, this will output to standard output stream.
+ * @brief Alternative logging function, this outputs to the standard output stream.
+ *
+ * @details This function colorizes the output based on the domain provided color and
+ * the message logging level. To disable color, set the environment variable
+ * EINA_LOG_COLOR_DISABLE=1. Similarly, to disable file and line
+ * information, set EINA_LOG_FILE_DISABLE=1 or
+ * EINA_LOG_FUNCTION_DISABLE=1 to avoid function name in the output. It is
+ * not acceptable to have both EINA_LOG_FILE_DISABLE and
+ * EINA_LOG_FUNCTION_DISABLE at the same time, in this case just
+ * EINA_LOG_FUNCTION_DISABLE is considered and file information
+ * is printed anyways.
+ *
+ * @since_tizen 2.3
*
- * @param d The domain.
- * @param level The level.
- * @param file The file which is logged.
- * @param fnc The function which is logged.
- * @param line The line which is logged.
- * @param fmt The ouptut format to use.
- * @param data Not used.
- * @param args The arguments needed by the format.
+ * @remarks If threads are enabled, this function is called within locks.
+ * @remarks Threads different from the main thread have a thread ID
+ * appended to the domain name.
*
- * This method will colorize output based on domain provided color and
- * message logging level. To disable color, set environment variable
- * EINA_LOG_COLOR_DISABLE=1. Similarly, to disable file and line
- * information, set EINA_LOG_FILE_DISABLE=1 or
- * EINA_LOG_FUNCTION_DISABLE=1 to avoid function name in output. It is
- * not acceptable to have both EINA_LOG_FILE_DISABLE and
- * EINA_LOG_FUNCTION_DISABLE at the same time, in this case just
- * EINA_LOG_FUNCTION_DISABLE will be considered and file information
- * will be printed anyways.
+ * @param[in] d The domain
+ * @param[in] level The level
+ * @param[in] file The file that is logged
+ * @param[in] fnc The function that is logged
+ * @param[in] line The line that is logged
+ * @param[in] fmt The ouptut format to use
+ * @param[in] data Not used
+ * @param[in] args The arguments needed by the format
*
- * @note MT: if threads are enabled, this function is called within locks.
- * @note MT: Threads different from main thread will have thread id
- * appended to domain name.
*/
EAPI void eina_log_print_cb_stdout(const Eina_Log_Domain *d,
Eina_Log_Level level,
@@ -864,38 +731,41 @@ EAPI void eina_log_print_cb_stdout(const Eina_Log_Domain *d,
va_list args);
/**
- * @brief Default logging method, this will output to standard error stream.
+ * @brief Default logging function, this outputs to the standard error stream.
*
- * @param d The domain.
- * @param level The level.
- * @param file The file which is logged.
- * @param fnc The function which is logged.
- * @param line The line which is logged.
- * @param fmt The ouptut format to use.
- * @param data Not used.
- * @param args The arguments needed by the format.
+ * @details This function colorizes the output based on the domain provided color and
+ * the message logging level.
*
- * This method will colorize output based on domain provided color and
- * message logging level.
+ * To disable color, set the environment variable
+ * EINA_LOG_COLOR_DISABLE=1. To enable color, even if directing to a
+ * file or when using a non-supported color terminal, use
+ * EINA_LOG_COLOR_DISABLE=0. If EINA_LOG_COLOR_DISABLE is unset (or
+ * -1), then Eina disables color if terminal ($TERM) is
+ * unsupported or redirecting to a file.
*
- * To disable color, set environment variable
- * EINA_LOG_COLOR_DISABLE=1. To enable color, even if directing to a
- * file or when using a non-supported color terminal, use
- * EINA_LOG_COLOR_DISABLE=0. If EINA_LOG_COLOR_DISABLE is unset (or
- * -1), then Eina will disable color if terminal ($TERM) is
- * unsupported or if redirecting to a file.
-
- . Similarly, to disable file and line
- * information, set EINA_LOG_FILE_DISABLE=1 or
- * EINA_LOG_FUNCTION_DISABLE=1 to avoid function name in output. It is
- * not acceptable to have both EINA_LOG_FILE_DISABLE and
- * EINA_LOG_FUNCTION_DISABLE at the same time, in this case just
- * EINA_LOG_FUNCTION_DISABLE will be considered and file information
- * will be printed anyways.
+ * Similarly, to disable file and line
+ * information, set EINA_LOG_FILE_DISABLE=1 or
+ * EINA_LOG_FUNCTION_DISABLE=1 to avoid function name in the output. It is
+ * not acceptable to have both EINA_LOG_FILE_DISABLE and
+ * EINA_LOG_FUNCTION_DISABLE at the same time, in this case just
+ * EINA_LOG_FUNCTION_DISABLE is considered and file information
+ * is printed anyways.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks If threads are enabled, this function is called within locks.
+ * @remarks Threads different from the main thread have a thread ID
+ * appended to the domain name.
+ *
+ * @param[in] d The domain
+ * @param[in] level The level
+ * @param[in] file The file that is logged
+ * @param[in] fnc The function that is logged
+ * @param[in] line The line that is logged
+ * @param[in] fmt The ouptut format to use
+ * @param[in] data Not used
+ * @param[in] args The arguments needed by the format
*
- * @note MT: if threads are enabled, this function is called within locks.
- * @note MT: Threads different from main thread will have thread id
- * appended to domain name.
*/
EAPI void eina_log_print_cb_stderr(const Eina_Log_Domain *d,
Eina_Log_Level level,
@@ -907,22 +777,25 @@ EAPI void eina_log_print_cb_stderr(const Eina_Log_Domain *d,
va_list args);
/**
- * Alternative logging method, this will output to given file stream.
+ * @brief Alternative logging function, this outputs to the given file stream.
*
- * @param d The domain.
- * @param level Not used.
- * @param file The file which is logged.
- * @param fnc The function which is logged.
- * @param line The line which is logged.
- * @param fmt The ouptut format to use.
- * @param data The file which will store the output (as a FILE *).
- * @param args The arguments needed by the format.
+ * @details This function never gives color as the output.
*
- * This method will never output color.
+ * @since_tizen 2.3
+ *
+ * @remarks If threads are enabled, this function is called within locks.
+ * @remarks Threads different from the main thread have a thread ID
+ * appended to the domain name.
+ *
+ * @param[in] d The domain
+ * @param[in] level Not used
+ * @param[in] file The file that is logged
+ * @param[in] fnc The function that is logged
+ * @param[in] line The line that is logged
+ * @param[in] fmt The ouptut format to use
+ * @param[in] data The file that stores the output (as a FILE *)
+ * @param[in] args The arguments needed by the format
*
- * @note MT: if threads are enabled, this function is called within locks.
- * @note MT: Threads different from main thread will have thread id
- * appended to domain name.
*/
EAPI void eina_log_print_cb_file(const Eina_Log_Domain *d,
Eina_Log_Level level,
@@ -933,79 +806,77 @@ EAPI void eina_log_print_cb_file(const Eina_Log_Domain *d,
void *data,
va_list args);
-
+/*--- TIZEN_ONLY : begin ---*/
/**
- * Alternative logging method, this will output to systemd journal.
- *
- * @param d The domain.
- * @param level Not used.
- * @param file The file which is logged.
- * @param fnc The function which is logged.
- * @param line The line which is logged.
- * @param fmt The ouptut format to use.
- * @param data The file which will store the output (as a FILE *).
- * @param args The arguments needed by the format.
+ * @brief Alternative logging function, this outputs to the system log.
*
- * This method will never output color.
+ * @details This function never gives color as the output.
*
- * @note if systemd journal is not there it will display error on stderr.
- * @note if the process has been started by systemd this will be the default logging method.
+ * @param[in] d The domain
+ * @param[in] level Not used
+ * @param[in] file The file that is logged
+ * @param[in] fnc The function that is logged
+ * @param[in] line The line that is logged
+ * @param[in] fmt The ouptut format to use
+ * @param[in] data Not Used
+ * @param[in] args The arguments needed by the format
*
- * @since 1.8
*/
-EAPI void eina_log_print_cb_journald(const Eina_Log_Domain *d,
- Eina_Log_Level level,
- const char *file,
- const char *fnc,
- int line,
- const char *fmt,
- void *data,
- va_list args);
+EAPI void eina_log_print_cb_syslog(const Eina_Log_Domain *d,
+ Eina_Log_Level level,
+ const char *file,
+ const char *fnc,
+ int line,
+ const char *fmt,
+ void *data,
+ va_list args);
+#ifdef HAVE_DLOG
/**
- * Configure console color of given file.
+ * @brief Alternative logging function, this outputs to the dlog.
*
- * @param fp file to configure console color (usually stderr or stdout).
- * @param color a VT color code such as EINA_COLOR_RED or EINA_COLOR_RESET.
+ * @since_tizen 2.3
*
- * @note if color is disabled, nothing is done. See
- * eina_log_color_disable_get()
- * @note on windows, both @a fp and @a color is converted automatically.
+ * @param[in] d The domain
+ * @param[in] level Not used
+ * @param[in] file The file that is logged
+ * @param[in] fnc The function that is logged
+ * @param[in] line The line that is logged
+ * @param[in] fmt The ouptut format to use
+ * @param[in] data Not Used
+ * @param[in] args The arguments needed by the format
*
- * @since 1.7
*/
-EAPI void eina_log_console_color_set(FILE *fp,
- const char *color) EINA_ARG_NONNULL(1, 2);
+EAPI void eina_log_print_cb_dlog(const Eina_Log_Domain *d,
+ Eina_Log_Level level,
+ const char *file,
+ const char *fnc,
+ int line,
+ const char *fmt,
+ void *data,
+ va_list args);
+#endif
-/** String that indicates the log system is initializing */
-extern EAPI const char *_eina_log_state_init;
-/** String that indicates the log system is shutting down */
-extern EAPI const char *_eina_log_state_shutdown;
-/** @def EINA_LOG_STATE_INIT
- *String that indicates the log system is initializing
- */
-#define EINA_LOG_STATE_INIT _eina_log_state_init
-/** @def EINA_LOG_STATE_SHUTDOWN
- *String that indicates the log system is shutting down
- */
-#define EINA_LOG_STATE_SHUTDOWN _eina_log_state_shutdown
+/*--- TIZEN_ONLY : end ---*/
/**
- * @brief Start or stop the timing of a phase.
+ * @brief Configures the console color of the given file.
+ *
+ * @since 1.7
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks If color is disabled, nothing is done.
+ * @remarks In windows, both @a fp and @a color are converted automatically.
*
- * @param domain The domain.
- * @param state State indicating if we are starting or stopping a phase.
- * @param phase The name of the phase to be used in the log.
+ * @param[in] fp The file to configure the console color of(usually stderr or stdout)
+ * @param[in] color A VT color code such as EINA_COLOR_RED or EINA_COLOR_RESET
*
- * @note One domain can be in only one phase at a time.
- * @note If you change the name of the phase, it is assumed that
- * the previous phase has stopped.
- * @note The phase name should be available for all the life of the timing.
- * @since 1.8
+ *
+ * @see eina_log_color_disable_get()
*/
-EAPI void eina_log_timing(int domain,
- Eina_Log_State state,
- const char *phase) EINA_ARG_NONNULL(1, 3);
+EAPI void eina_log_console_color_set(FILE *fp,
+ const char *color) EINA_ARG_NONNULL(1, 2);
#include "eina_inline_log.x"
@@ -1013,8 +884,4 @@ EAPI void eina_log_timing(int domain,
* @}
*/
-/**
- * @}
- */
-
#endif /* EINA_LOG_H_ */
diff --git a/src/lib/eina/eina_main.h b/src/lib/eina/eina_main.h
index d7a7f0b01f..f0efe7ed5a 100644
--- a/src/lib/eina/eina_main.h
+++ b/src/lib/eina/eina_main.h
@@ -1,14 +1,14 @@
/* EINA - EFL data type library
* Copyright (C) 2008 Cedric Bail
*
- * This library is free software; you can redistribute it and/or
+ * This library is a free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
@@ -19,44 +19,34 @@
#ifndef EINA_MAIN_H_
#define EINA_MAIN_H_
-#include <Efl_Config.h>
-
#include "eina_types.h"
/**
- * @addtogroup Eina_Main_Group Main
- *
- * @brief These functions provide general initialisation and shut down
- * functions.
- */
-
-/**
- * @addtogroup Eina_Core_Group Core
- *
- * @{
- */
-
-/**
+ * @internal
* @defgroup Eina_Main_Group Main
+ * @ingroup Eina_Core_Group
+ *
+ * @brief This group discusses the functions that provide general initialisation and shut down
+ * functions.
*
* @{
*/
/**
* @def EINA_VERSION_MAJOR
- * @brief Major version of Eina
+ * @brief Definition of the major version of Eina.
*/
-#define EINA_VERSION_MAJOR EFL_VERSION_MAJOR
+#define EINA_VERSION_MAJOR 1
/**
* @def EINA_VERSION_MINOR
- * @brief Minor version of Eina
+ * @brief Definition of the minor version of Eina.
*/
-#define EINA_VERSION_MINOR EFL_VERSION_MINOR
+#define EINA_VERSION_MINOR 8
/**
* @typedef Eina_Version
- * The version of Eina.
+ * @brief The structure type containing the version of Eina.
*/
typedef struct _Eina_Version
{
@@ -69,90 +59,104 @@ typedef struct _Eina_Version
EAPI extern Eina_Version *eina_version;
/**
- * @brief Initialize the Eina library.
+ * @brief Initializes the Eina library.
+ *
+ * @details This function sets up all the eina modules. It returns @c 0 on
+ * failure (that is, when one of the module fails to initialize),
+ * otherwise it returns the number of times it has already been
+ * called.
*
- * @return 1 or greater on success, 0 on error.
+ * @since_tizen 2.3
*
- * This function sets up all the eina modules. It returns 0 on
- * failure (that is, when one of the module fails to initialize),
- * otherwise it returns the number of times it has already been
- * called.
+ * @remarks When Eina is not used anymore, call eina_shutdown() to shut down
+ * the Eina library.
+ *
+ * @return @c 1 or greater on success, otherwise @c 0 on error
*
- * When Eina is not used anymore, call eina_shutdown() to shut down
- * the Eina library.
*/
EAPI int eina_init(void);
/**
- * @brief Shut down the Eina library.
+ * @brief Shuts down the Eina library.
+ *
+ * @details This function shuts down the Eina library. It returns @c 0 when it has
+ * been called the same number of times as eina_init(). In that case,
+ * it shuts down all the Eina modules.
+ *
+ * Once this function succeeds (that is, @c 0 is returned), you must
+ * not call any of the Eina functions anymore. You must call
+ * eina_init() again to use the Eina functions again.
*
- * @return 0 when all the modules are completely shut down, 1 or
- * greater otherwise.
+ * @since_tizen 2.3
*
- * This function shuts down the Eina library. It returns 0 when it has
- * been called the same number of times than eina_init(). In that case
- * it shut down all the Eina modules.
+ * @return @c 0 when all the modules are completely shut down, otherwise @c 1 or greater
*
- * Once this function succeeds (that is, @c 0 is returned), you must
- * not call any of the Eina function anymore. You must call
- * eina_init() again to use the Eina functions again.
*/
EAPI int eina_shutdown(void);
/**
- * @brief Initialize the mutexes of the Eina library.
+ * @brief Initializes the mutexes of the Eina library.
*
- * @return 1 or greater on success, 0 on error.
+ * @details This function sets up all the mutexes in all the eina modules. It returns @c 0 on
+ * failure (that is, when one of the module fails to initialize),
+ * otherwise it returns the number of times it has already been
+ * called.
*
- * This function sets up all the mutexes in all eina modules. It returns 0 on
- * failure (that is, when one of the module fails to initialize),
- * otherwise it returns the number of times it has already been
- * called.
+ * @since_tizen 2.3
*
- * When the mutexes are not used anymore, call eina_threads_shutdown() to shut down
- * the mutexes.
+ * @remarks When the mutexes are not used anymore, call eina_threads_shutdown() to shut down
+ * the mutexes.
+ *
+ * @remarks This function should never be called outside the main loop.
+ *
+ * @return @c 1 or greater on success, otherwise @c 0 on error
*
- * This function should never be called outside of the main loop.
*/
EAPI int eina_threads_init(void);
/**
- * @brief Shut down mutexes in the Eina library.
+ * @brief Shuts down mutexes in the Eina library.
+ *
+ * @details This function shuts down the mutexes in the Eina library. It returns @c 0 when it has
+ * been called the same number of times as eina_threads_init(). In that case
+ * it shuts down all the mutexes.
+ *
+ * Once this function succeeds (that is, @c 0 is returned), you must
+ * not call any of the Eina functions in a thread anymore. You must call
+ * eina_threads_init() again to use the Eina functions in a thread again.
*
- * @return 0 when all mutexes are completely shut down, 1 or
- * greater otherwise.
+ * @since_tizen 2.3
*
- * This function shuts down the mutexes in the Eina library. It returns 0 when it has
- * been called the same number of times than eina_threads_init(). In that case
- * it shut down all the mutexes.
+ * @remarks This function should never be called outside the main loop.
*
- * Once this function succeeds (that is, @c 0 is returned), you must
- * not call any of the Eina function in a thread anymore. You must call
- * eina_threads_init() again to use the Eina functions in a thread again.
+ * @return @c 0 when all the mutexes are completely shut down, otherwise @c 1 or greater
*
- * This function should never be called outside of the main loop.
*/
EAPI int eina_threads_shutdown(void);
/**
- * @brief Check if you are calling this function from the same thread Eina was initialized or not
- *
- * @return #EINA_TRUE is the calling function is the same thread, #EINA_FALSE otherwise.
+ * @brief Check whether you are calling this function from the same thread in which Eina is initialized.
*
* @since 1.1.0
*
- * Most EFL function are not thread safe and all the call need to happen in
- * the main loop. With this call you could know if you can call an EFL
- * function or not.
+ * @since_tizen 2.3
+ *
+ * @remarks Most EFL functions are not thread safe and all the calls need to happen in
+ * the main loop. With this call you could know if you can call an EFL
+ * function.
+ *
+ * @return @c EINA_TRUE if the calling function is in the same thread, otherwise @c EINA_FALSE
+ *
*/
EAPI Eina_Bool eina_main_loop_is(void);
/**
- * @brief You should never use that function excpet if you really really know what your are doing.
- * @since 1.1.0
+ * @brief You should never use this function unless you really know what you are doing.
*
- * If you are reading this documentation, that certainly means you don't know what is the purpose of
- * this call and you should just not use it.
+ * @since_tizen 2.3
+ *
+ * @remarks If you are reading this documentation, that certainly means you don't know the purpose of
+ * this call, so you should not use it.
*/
EAPI void eina_main_loop_define(void);
@@ -160,8 +164,4 @@ EAPI void eina_main_loop_define(void);
* @}
*/
-/**
- * @}
- */
-
#endif /* EINA_MAIN_H_ */
diff --git a/src/lib/eina/eina_matrixsparse.h b/src/lib/eina/eina_matrixsparse.h
index 5523c0fb31..fc29481846 100644
--- a/src/lib/eina/eina_matrixsparse.h
+++ b/src/lib/eina/eina_matrixsparse.h
@@ -1,14 +1,14 @@
/* EINA - EFL data type library
* Copyright (C) 2009 Gustavo Sverzut Barbieri
*
- * This library is free software; you can redistribute it and/or
+ * This library is a free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
@@ -28,66 +28,54 @@
#include "eina_accessor.h"
/**
- * @addtogroup Eina_Matrixsparse_Group Sparse Matrix
- *
- * @brief These functions provide matrix sparse management.
- *
- * For more information, you can look at the @ref tutorial_matrixsparse_page.
- */
-
-/**
- * @addtogroup Eina_Data_Types_Group Data Types
- *
- * @{
- */
-
-/**
- * @addtogroup Eina_Containers_Group Containers
- *
- * @{
- */
-
-/**
* @defgroup Eina_Matrixsparse_Group Sparse Matrix
+ * @ingroup Eina_Containers_Group
+ *
+ * @brief This group discusses the functions to provide matrix sparse management.
*
* @{
*/
/**
* @typedef Eina_Matrixsparse
- * Type for a generic sparse matrix.
+ * @brief The structure type for a generic sparse matrix.
*/
typedef struct _Eina_Matrixsparse Eina_Matrixsparse;
/**
* @typedef Eina_Matrixsparse_Row
- * Type for a generic sparse matrix row, opaque for users.
+ * @brief The structure type for a generic sparse matrix row, opaque for users.
*/
typedef struct _Eina_Matrixsparse_Row Eina_Matrixsparse_Row;
/**
* @typedef Eina_Matrixsparse_Cell
- * Type for a generic sparse matrix cell, opaque for users.
+ * @brief The structure type for a generic sparse matrix cell, opaque for users.
*/
typedef struct _Eina_Matrixsparse_Cell Eina_Matrixsparse_Cell;
-/* constructors and destructors */
+/* Constructors and destructors */
/**
- * @brief Create a new Sparse Matrix.
- *
- * @param rows number of rows in matrix. Operations with rows greater than this
- * value will fail.
- * @param cols number of columns in matrix. Operations with columns greater
- * than this value will fail.
- * @param free_func used to delete cell data contents, used by
- * eina_matrixsparse_free(), eina_matrixsparse_size_set(),
- * eina_matrixsparse_row_idx_clear(),
- * eina_matrixsparse_column_idx_clear(),
- * eina_matrixsparse_cell_idx_clear() and possible others.
- * @param user_data given to @a free_func as first parameter.
- *
- * @return Newly allocated matrix or @c NULL if allocation failed.
+ * @brief Creates a new Sparse Matrix.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] rows The number of rows in the matrix \n
+ * Operations with rows greater than this
+ * value fail.
+ * @param[in] cols The number of columns in the matrix \n
+ * Operations with columns greater
+ * than this value fail.
+ * @param[in] free_func The function used to delete cell data contents, used by
+ * eina_matrixsparse_free(), eina_matrixsparse_size_set(),
+ * eina_matrixsparse_row_idx_clear(),
+ * eina_matrixsparse_column_idx_clear(),
+ * eina_matrixsparse_cell_idx_clear(), and other possible functions.
+ * @param[in] user_data The data given to @a free_func as the first parameter
+ *
+ * @return The newly allocated matrix, otherwise @c NULL if allocation fails and eina_error
+ * is set
*/
EAPI Eina_Matrixsparse *eina_matrixsparse_new(unsigned long rows,
unsigned long cols,
@@ -96,61 +84,71 @@ EAPI Eina_Matrixsparse *eina_matrixsparse_new(unsigned long rows,
const void *user_data);
/**
- * @brief Free resources allocated to Sparse Matrix.
+ * @brief Frees resources allocated to the Sparse Matrix.
+ *
+ * @since_tizen 2.3
*
- * @param m The Sparse Matrix instance to free, must @b not be @c NULL.
+ * @param[in] m The Sparse Matrix instance to free, must @b not be @c NULL
*/
EAPI void eina_matrixsparse_free(Eina_Matrixsparse *m);
-/* size manipulation */
+/* Size manipulation */
/**
- * @brief Get the current size of Sparse Matrix.
+ * @brief Gets the current size of the Sparse Matrix.
+ *
+ * @since_tizen 2.3
*
- * The given parameters are guaranteed to be set if they're not @c NULL,
- * even if this function fails (ie: @a m is not a valid matrix instance).
+ * @remarks The given parameters are guaranteed to be set if they're not @c NULL,
+ * even if this function fails (ie: @a m is not a valid matrix instance).
*
- * @param m the sparse matrix to operate on.
- * @param rows returns the number of rows, may be @c NULL. If @a m is invalid,
- * returned value is zero, otherwise it's a positive integer.
- * @param cols returns the number of columns, may be @c NULL. If @a m is
- * invalid, returned value is zero, otherwise it's a positive integer.
+ * @param[in] m The sparse matrix to operate on
+ * @param[out] rows The number of rows, may be @c NULL \n
+ * If @a m is invalid the returned value is zero, otherwise it's a positive integer.
+ * @param[out] cols The number of columns, may be @c NULL \n
+ * If @a m is invalid the returned value is zero, otherwise it's a positive integer.
*/
EAPI void eina_matrixsparse_size_get(const Eina_Matrixsparse *m,
unsigned long *rows,
unsigned long *cols);
/**
- * @brief Resize the Sparse Matrix.
+ * @brief Resizes the Sparse Matrix.
*
- * This will resize the sparse matrix, possibly freeing cells on rows
- * and columns that will cease to exist.
+ * @details This resizes the sparse matrix, possibly freeing cells of rows
+ * and columns that cease to exist.
*
- * @param m the sparse matrix to operate on.
- * @param rows the new number of rows, must be greater than zero.
- * @param cols the new number of columns, must be greater than zero.
- * @return #EINA_TRUE on success, #EINA_FALSE on failure.
+ * @since_tizen 2.3
+ *
+ * @remarks The cells, rows, or columns are not reference counted and thus
+ * after this call any reference might be invalid if the instance is
+ * freed.
+ *
+ * @param[in] m The sparse matrix to operate on
+ * @param[in] rows The new number of rows, must be greater than zero
+ * @param[in] cols The new number of columns, must be greater than zero
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure
*
- * @warning cells, rows or columns are not reference counted and thus
- * after this call any reference might be invalid if instance were
- * freed.
*/
EAPI Eina_Bool eina_matrixsparse_size_set(Eina_Matrixsparse *m,
unsigned long rows,
unsigned long cols);
-/* data getting */
+/* Obtaining data */
/**
- * Get the cell reference inside Sparse Matrix.
+ * @brief Gets the cell reference inside the Sparse Matrix.
+ *
+ * @since_tizen 2.3
*
- * @param m the sparse matrix to operate on.
- * @param row the new number of row to clear.
- * @param col the new number of column to clear.
- * @param cell pointer to return cell reference, if any exists.
+ * @param[in] m The sparse matrix to operate on
+ * @param[in] row The new row number to clear
+ * @param[in] col The new column number to clear
+ * @param[out] cell A pointer to return the cell reference, if it exists
*
- * @return @c 1 on success, @c 0 on failure. It is considered success if did not
- * exist but index is inside matrix size, in this case @c *cell == NULL
+ * @return @c 1 on success, otherwise @c 0 on failure \n
+ * It is considered successful if it does not
+ * exist but its index is inside the matrix size, in this case @c *cell == NULL
*
* @see eina_matrixsparse_cell_data_get()
* @see eina_matrixsparse_data_idx_get()
@@ -158,11 +156,11 @@ EAPI Eina_Bool eina_matrixsparse_size_set(Eina_Matrixsparse *m,
EAPI Eina_Bool eina_matrixsparse_cell_idx_get(const Eina_Matrixsparse *m, unsigned long row, unsigned long col, Eina_Matrixsparse_Cell **cell);
/**
- * Get data associated with given cell reference.
+ * @brief Gets the data associated to the given cell reference.
*
- * @param cell given cell reference, must @b not be @c NULL.
+ * @param[in] cell The given cell reference, must @b not be @c NULL
*
- * @return data associated with given cell.
+ * @return The data associated to the given cell
*
* @see eina_matrixsparse_cell_idx_get()
* @see eina_matrixsparse_data_idx_get()
@@ -170,13 +168,15 @@ EAPI Eina_Bool eina_matrixsparse_cell_idx_get(const Eina_Matrixsparse *m, unsign
EAPI void *eina_matrixsparse_cell_data_get(const Eina_Matrixsparse_Cell *cell);
/**
- * Get data associated with given cell given its indexes.
+ * @brief Gets the data associated to the given cell given that its indexes are provided.
*
- * @param m the sparse matrix to operate on.
- * @param row the new number of row to clear.
- * @param col the new number of column to clear.
+ * @since_tizen 2.3
*
- * @return Data associated with given cell or @c NULL if nothing is associated.
+ * @param[in] m The sparse matrix to operate on
+ * @param[in] row The new row number to clear
+ * @param[in] col The new column number to clear
+ *
+ * @return The data associated to the given cell, otherwise @c NULL if nothing is associated
*
* @see eina_matrixsparse_cell_idx_get()
* @see eina_matrixsparse_cell_data_get()
@@ -184,26 +184,30 @@ EAPI void *eina_matrixsparse_cell_data_get(const Eina_Matrixsparse_Cell *cel
EAPI void *eina_matrixsparse_data_idx_get(const Eina_Matrixsparse *m, unsigned long row, unsigned long col);
/**
- * Get position (indexes) of the given cell.
+ * @brief Gets the position (indexes) of the given cell.
+ *
+ * @since_tizen 2.3
*
- * @param cell the cell reference, must @b not be @c NULL.
- * @param row where to store cell row number, may be @c NULL.
- * @param col where to store cell column number, may be @c NULL.
+ * @param[in] cell The cell reference, must @b not be @c NULL
+ * @param[out] row The location to store the cell row number, may be @c NULL
+ * @param[out] col The location to store the column number, may be @c NULL
*
- * @return #EINA_TRUE on success, #EINA_FALSE otherwise (@c cell is @c NULL).
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE (@c cell is @c NULL)
*/
EAPI Eina_Bool eina_matrixsparse_cell_position_get(const Eina_Matrixsparse_Cell *cell, unsigned long *row, unsigned long *col);
-/* data setting */
+/* Setting data */
/**
- * Change cell reference value without freeing the possibly existing old value.
+ * @brief Changes the cell reference value without freeing a possible existing old value.
+ *
+ * @since_tizen 2.3
*
- * @param cell the cell reference, must @b not be @c NULL.
- * @param data new data to set.
- * @param p_old returns the old value intact (not freed).
+ * @param[in] cell The cell reference, must @b not be @c NULL
+ * @param[in] data The new data to set
+ * @param[out] p_old The old value that is intact (not freed)
*
- * @return #EINA_TRUE on success, #EINA_FALSE otherwise (@a cell is @c NULL).
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE (@a cell is @c NULL)
*
* @see eina_matrixsparse_cell_data_set()
* @see eina_matrixsparse_data_idx_replace()
@@ -211,15 +215,17 @@ EAPI Eina_Bool eina_matrixsparse_cell_position_get(const Eina_Matrixsparse_Cell
EAPI Eina_Bool eina_matrixsparse_cell_data_replace(Eina_Matrixsparse_Cell *cell, const void *data, void **p_old);
/**
- * Change cell value freeing the possibly existing old value.
+ * @brief Changes the cell value by freeing a possible existing old value.
*
- * In contrast to eina_matrixsparse_cell_data_replace(), this function will
- * call @c free_func() on existing value.
+ * @since_tizen 2.3
*
- * @param cell the cell reference, must @b not be @c NULL.
- * @param data new data to set.
+ * @remarks In contrast to eina_matrixsparse_cell_data_replace(), this function
+ * calls @c free_func() on the existing value.
*
- * @return #EINA_TRUE on success, #EINA_FALSE otherwise (@a cell is @c NULL).
+ * @param[in] cell The cell reference, must @b not be @c NULL
+ * @param[in] data The new data to set
+ *
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE (@a cell is @c NULL).
*
* @see eina_matrixsparse_cell_data_replace()
* @see eina_matrixsparse_data_idx_set()
@@ -227,16 +233,18 @@ EAPI Eina_Bool eina_matrixsparse_cell_data_replace(Eina_Matrixsparse_Cell *cell,
EAPI Eina_Bool eina_matrixsparse_cell_data_set(Eina_Matrixsparse_Cell *cell, const void *data);
/**
- * Change cell value without freeing the possibly existing old value, using
- * indexes.
+ * @brief Changes the cell value without freeing a possible existing old value, using
+ * indexes.
+ *
+ * @since_tizen 2.3
*
- * @param m the sparse matrix, must @b not be @c NULL.
- * @param row the row number to set the value.
- * @param col the column number to set the value.
- * @param data new data to set.
- * @param p_old returns the old value intact (not freed).
+ * @param[in] m The sparse matrix, must @b not be @c NULL
+ * @param[in] row The row number to set the value of
+ * @param[in] col The column number to set the value of
+ * @param[in] data The new data to set
+ * @param[out] p_old The old value that is intact (not freed)
*
- * @return #EINA_TRUE on success, #EINA_FALSE otherwise (@a m is @c NULL, indexes are not valid).
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE (@a m is @c NULL, indexes are not valid)
*
* @see eina_matrixsparse_cell_data_replace()
* @see eina_matrixsparse_data_idx_set()
@@ -244,146 +252,166 @@ EAPI Eina_Bool eina_matrixsparse_cell_data_set(Eina_Matrixsparse_Cell *cell, con
EAPI Eina_Bool eina_matrixsparse_data_idx_replace(Eina_Matrixsparse *m, unsigned long row, unsigned long col, const void *data, void **p_old);
/**
- * Change cell value freeing the possibly existing old value, using
- * indexes.
+ * @brief Changes the cell value by freeing a possible existing old value, using
+ * indexes.
+ *
+ * @since_tizen 2.3
*
- * In contrast to eina_matrixsparse_data_idx_replace(), this function will
- * call @c free_func() on existing value.
+ * @remarks In contrast to eina_matrixsparse_data_idx_replace(), this function
+ * calls @c free_func() on the existing value.
*
- * @param m the sparse matrix, must @b not be @c NULL.
- * @param row the row number to set the value.
- * @param col the column number to set the value.
- * @param data new data to set.
+ * @param[in] m The sparse matrix, must @b not be @c NULL
+ * @param[in] row The row number to set the value of
+ * @param[in] col The column number to set the value of
+ * @param[in] data The new data to set
*
- * @return #EINA_TRUE on success, #EINA_FALSE otherwise (@a m is @c NULL, indexes are not valid).
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE (@a m is @c NULL, indexes are not valid)
*
* @see eina_matrixsparse_cell_data_replace()
*/
EAPI Eina_Bool eina_matrixsparse_data_idx_set(Eina_Matrixsparse *m, unsigned long row, unsigned long col, const void *data);
-/* data deleting */
+/* Deleting data */
/**
- * Clear (erase all cells) of row given its index.
+ * @brief Clears (erases) all the cells of the row given that its index is provided.
*
- * Existing cells will be cleared with @c free_func() given to
- * eina_matrixsparse_new().
+ * @since_tizen 2.3
*
- * @param m the sparse matrix to operate on.
- * @param row the new number of row to clear.
+ * @remarks Existing cells are cleared with @c free_func() given to
+ * eina_matrixsparse_new().
*
- * @return #EINA_TRUE on success, #EINA_FALSE on failure. It is considered success if row
- * had no cells filled. Failure is asking for clear row outside
- * matrix size.
+ * @remarks The cells, rows, or columns are not reference counted and thus
+ * after this call any reference might be invalid if an instance is
+ * freed.
+ *
+ * @param[in] m The sparse matrix to operate on
+ * @param[in] row The new row number to clear
+ *
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure \n
+ * It is considered successful if the row has no filled cells \n
+ * Failure is asking for a clear row outside the matrix size.
*
- * @warning cells, rows or columns are not reference counted and thus
- * after this call any reference might be invalid if instance were
- * freed.
*/
EAPI Eina_Bool eina_matrixsparse_row_idx_clear(Eina_Matrixsparse *m, unsigned long row);
/**
- * Clear (erase all cells) of column given its index.
+ * @brief Clears (erases) all the cells of the column given that its index is provided.
+ *
+ * @since_tizen 2.3
*
- * Existing cells will be cleared with @c free_func() given to
- * eina_matrixsparse_new().
+ * @remarks Existing cells are cleared with @c free_func() given to
+ * eina_matrixsparse_new().
*
- * @param m the sparse matrix to operate on.
- * @param col the new number of column to clear.
+ * @remarks The cells, rows, or columns are not reference counted and thus
+ * after this call any reference might be invalid if an instance is
+ * freed.
*
- * @return #EINA_TRUE on success, #EINA_FALSE on failure. It is considered success if column
- * had no cells filled. Failure is asking for clear column outside
- * matrix size.
+ * @param[in] m The sparse matrix to operate on
+ * @param[in] col The new column number to clear
+ *
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure \n
+ * It is considered successful if the column has no filled cells \n
+ * Failure is asking for a clear column outside the matrix size.
*
- * @warning cells, rows or columns are not reference counted and thus
- * after this call any reference might be invalid if instance were
- * freed.
*/
EAPI Eina_Bool eina_matrixsparse_column_idx_clear(Eina_Matrixsparse *m, unsigned long col);
/**
- * Clear (erase) cell given its indexes.
+ * @brief Clears (erases) a cell given that its indexes are provided.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Existing cells are cleared with @c free_func() given to
+ * eina_matrixsparse_new().
*
- * Existing cell will be cleared with @c free_func() given to
- * eina_matrixsparse_new().
+ * @remarks The cells, rows, or columns are not reference counted and thus
+ * after this call any reference might be invalid if an instance is
+ * freed.
*
- * @param m the sparse matrix to operate on.
- * @param row the new number of row to clear.
- * @param col the new number of column to clear.
+ * @remarks This call might delete a container column and row if this cell is the
+ * last remainder.
*
- * @return #EINA_TRUE on success, #EINA_FALSE on failure. It is considered success if did not
- * exist but index is inside matrix size.
+ * @param[in] m The sparse matrix to operate on
+ * @param[in] row The new row number to clear
+ * @param[in] col The new column number to clear
*
- * @warning cells, rows or columns are not reference counted and thus
- * after this call any reference might be invalid if instance were
- * freed.
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure \n
+ * It is considered successful if it does not exist but its index is inside the matrix size.
*
- * @note This call might delete container column and row if this cell was the
- * last remainder.
*/
EAPI Eina_Bool eina_matrixsparse_cell_idx_clear(Eina_Matrixsparse *m, unsigned long row, unsigned long col);
/**
- * Clear (erase) cell given its reference.
+ * @brief Clears (erases) a cell given that its referenceis provided.
*
- * @param cell the cell reference, must @b not be @c NULL.
+ * @since_tizen 2.3
*
- * @return #EINA_TRUE on success, #EINA_FALSE on failure.
+ * @remarks The cells, rows, or columns are not reference counted and thus
+ * after this call any reference might be invalid if an instance is
+ * freed.
*
- * @warning cells, rows or columns are not reference counted and thus
- * after this call any reference might be invalid if instance were
- * freed.
+ * @remarks This call might delete a container column and row if this cell is the
+ * last remainder.
+ *
+ * @param[in] cell The cell reference, must @b not be @c NULL
+ *
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure
*
- * @note This call might delete container column and row if this cell was the
- * last remainder.
*/
EAPI Eina_Bool eina_matrixsparse_cell_clear(Eina_Matrixsparse_Cell *cell);
-/* iterators */
+/* Iterators */
/**
- * Creates a new iterator over existing matrix cells.
+ * @brief Creates a new iterator over existing matrix cells.
+ *
+ * @since_tizen 2.3
*
- * This is a cheap walk, it will just report existing cells and holes
- * in the sparse matrix will be ignored. That means the reported
- * indexes will not be sequential.
+ * @remarks This is a cheap walk, it just reports existing cells and holes
+ * in the sparse matrix are ignored. That means the reported
+ * indexes are not sequential.
*
- * The iterator data will be the cell reference, one may query current
- * position with eina_matrixsparse_cell_position_get() and cell value
- * with eina_matrixsparse_cell_data_get().
+ * @remarks The iterator data is the cell reference, one may query the current
+ * position with eina_matrixsparse_cell_position_get() and cell value
+ * with eina_matrixsparse_cell_data_get().
*
- * @param m The Sparse Matrix reference, must @b not be @c NULL.
- * @return A new iterator.
+ * @remarks If the matrix structure changes then the iterator becomes
+ * invalid. That is, if you add or remove cells this iterator's
+ * behavior is undefined and your program may crash.
+ *
+ * @param[in] m The Sparse Matrix reference, must @b not be @c NULL
+ * @return A new iterator
*
- * @warning if the matrix structure changes then the iterator becomes
- * invalid! That is, if you add or remove cells this iterator
- * behavior is undefined and your program may crash!
*/
EAPI Eina_Iterator *eina_matrixsparse_iterator_new(const Eina_Matrixsparse *m);
/**
- * Creates a new iterator over all matrix cells.
+ * @brief Creates a new iterator over all the matrix cells.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Unlike eina_matrixsparse_iterator_new(), this one reports all
+ * the matrix cells, even those that are still empty (holes). These are
+ * reported as dummy cells that contain no data.
*
- * Unlike eina_matrixsparse_iterator_new() this one will report all
- * matrix cells, even those that are still empty (holes). These will
- * be reported as dummy cells that contains no data.
+ * @remarks Be aware that iterating a big matrix (1000x1000) calls your
+ * function that number of times (1000000 times in that case) even if
+ * your matrix have no elements at all.
*
- * Be aware that iterating a big matrix (1000x1000) will call your
- * function that number of times (1000000 times in that case) even if
- * your matrix have no elements at all!
+ * @remarks The iterator data is the cell reference, one may query the current
+ * position with eina_matrixsparse_cell_position_get() and cell value
+ * with eina_matrixsparse_cell_data_get(). If the cell is empty then the
+ * reference is a dummy/placeholder, thus setting a value with
+ * eina_matrixsparse_cell_data_set() leaves the pointer unreferenced.
*
- * The iterator data will be the cell reference, one may query current
- * position with eina_matrixsparse_cell_position_get() and cell value
- * with eina_matrixsparse_cell_data_get(). If cell is empty then the
- * reference will be a dummy/placeholder, thus setting value with
- * eina_matrixsparse_cell_data_set() will leave pointer unreferenced.
+ * @remarks If the matrix structure changes then the iterator becomes
+ * invalid. That is, if you add or remove cells this iterator's
+ * behavior is undefined and your program may crash.
*
- * @param m The Sparse Matrix reference, must @b not be @c NULL.
- * @return A new iterator.
+ * @param[in] m The Sparse Matrix reference, must @b not be @c NULL
+ * @return A new iterator
*
- * @warning if the matrix structure changes then the iterator becomes
- * invalid! That is, if you add or remove cells this iterator
- * behavior is undefined and your program may crash!
*/
EAPI Eina_Iterator *eina_matrixsparse_iterator_complete_new(const Eina_Matrixsparse *m);
@@ -391,12 +419,4 @@ EAPI Eina_Iterator *eina_matrixsparse_iterator_complete_new(const Eina_Matrixspa
* @}
*/
-/**
- * @}
- */
-
-/**
- * @}
- */
-
#endif /* EINA_MATRIXSPARSE_H_ */
diff --git a/src/lib/eina/eina_mmap.h b/src/lib/eina/eina_mmap.h
index 1d1d58c976..16f3044ffe 100644
--- a/src/lib/eina/eina_mmap.h
+++ b/src/lib/eina/eina_mmap.h
@@ -2,10 +2,11 @@
#define EINA_MMAP_H_
/**
- * @addtogroup Eina_Mmap_Group Mmap Group
- * @ingroup Eina
+ * @internal
+ * @defgroup Eina_Mmap_Group Mmap Group
+ * @ingroup Eina_Core_Group
*
- * @brief These functions provide helpers for safe mmap handling
+ * @brief This group discusses the functions that provide helpers for safe mmap handling.
*
* @{
*
@@ -13,44 +14,50 @@
*/
/**
- * @brief Enable or disable safe mmaped IO handling
- *
- * @param enabled The enabled state (to enable, pass #EINA_TRUE)
- * @return #EINA_TRUE on success, #EINA_FALSE on failure.
- *
- * This enables (if possible on your platform) a signal handler for
- * SIGBUS, that replaces the "bad page" with a page of 0's (from /dev/zero)
- * if a SIGBUS occurs. This allows for safe mmap() of files that may truncate
- * or from files on devices with IO errors. Normally these cases will result
- * in a SIGBUS being delivered (and termination of your process), but
- * when "mmap safety" is enabled, this will not occur. Instead a page of
- * bytes of the value 0 will replace the "bad page", allowing the process
- * to continue and allow its own parsing error detection to safely abort
- * the operation without the process falling apart.
- *
- * If you disable mmap safety, the SIGBUS handler will be restored to its
- * default handler. Note that eina_file_map_all() and eina_file_map_new()
- * will automatically enable mmap safety as they provide an mmaped file IO
- * layer, and rely on mmap to not fail for any part of the file.
- *
- * If you set up your own SIGBUS handler, then this will effectively disable
- * the safe mmap handling and make you liable to crashes on IO to or from
- * such "damaged files" that would take down your process.
+ * @brief Enables or disables safe mmaped IO handling.
+ *
+ * @details This enables (if possible on your platform) a signal handler for
+ * SIGBUS, that replaces the "bad page" with a page of 0's (from /dev/zero)
+ * if a SIGBUS occurs. This allows for safe mmap() of files that may truncate
+ * or from files on devices with IO errors. Normally these cases result
+ * in a SIGBUS being delivered (and termination of your process), but
+ * when "mmap safety" is enabled, this does not occur. Instead a page of
+ * bytes of the value 0 replaces the "bad page", allowing the process
+ * to continue and allow its own parsing error detection to safely abort
+ * the operation without the process falling apart.
*
* @since 1.1.0
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks If you disable mmap safety, the SIGBUS handler is restored to its
+ * default handler. Note that eina_file_map_all() and eina_file_map_new()
+ * automatically enable mmap safety as they provide an mmaped file IO
+ * layer, and rely on mmap to not fail for any part of the file.
+ *
+ * @remarks If you set up your own SIGBUS handler, then this effectively disables
+ * the safe mmap handling and makes you liable to crashes on IO to or from
+ * such "damaged files" that would take down your process.
+ *
+ * @param[in] enabled The enabled state (to enable, pass @c EINA_TRUE)
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure
+ *
*/
EAPI Eina_Bool
eina_mmap_safety_enabled_set(Eina_Bool enabled);
/**
- * @brief Get the enabled state of mmap safety.
- *
- * @return The safety state (#EINA_TRUE if enabled)
+ * @brief Gets the enabled state of mmap safety.
*
- * This returns the mmap safety state set by eina_mmap_safety_enabled_set().
- * See eina_mmap_safety_enabled_set() for more information.
+ * @details This returns the mmap safety state set by eina_mmap_safety_enabled_set().
*
* @since 1.1.0
+ *
+ * @since_tizen 2.3
+ *
+ * @return The safety state (@c EINA_TRUE if enabled)
+ *
+ * @see eina_mmap_safety_enabled_set()
*/
EAPI Eina_Bool
eina_mmap_safety_enabled_get(void);
diff --git a/src/lib/eina/eina_model.h b/src/lib/eina/eina_model.h
index b6229c1ce5..8e323390c5 100644
--- a/src/lib/eina/eina_model.h
+++ b/src/lib/eina/eina_model.h
@@ -46,228 +46,9 @@
*/
/**
- * @page eina_model_02_example_page Creating a simple model
- * @dontinclude eina_model_02.c
- *
- * This example shows the creation of a model with five properties, named:
- * 'a', 'b', 'c', 'd' and 'e' with values 0, 1, 2, 3 and 4
- * respectively. In addition to the 5 properties our model also add 5 children,
- * and to each child we give a property named 'x' with a value of 1, 2, 3, 4 and
- * 5.
- *
- * In other words this piece of code shows how to use eina_model to store a list
- * of elements, given that the list itself has some properties.
- *
- * Now let's walk through the code and examine the interesting bits.
- *
- * This is some pretty standard initialization code.
- * @until eina_init
- *
- * We now create our eina_model, the important detail here is the type of the
- * model being created, for this example we use the generic type provided by
- * eina:
- * @until model_new
- *
- * Once our model has been created we can add callbacks to be notified of events
- * that happen to our model, for this example we are just going to add a
- * callback for the "delete" event. To get a list of events a given eina model
- * can emit see @ref eina_model_event_names_list_get().
- * @until callback_add
- *
- * Once we have a model, we need to populate it with information. There are two
- * types of information we can store on an eina model: properties and eina
- * models. We are going to start by looking at properties.
- *
- * Properties are, simply put, named values. They have a char* identifier and an
- * Eina_Value value. This means you can store in a property almost any type of
- * data. For this example we are going to add some very simple numeric
- * properties which will have single letter identifiers.
- * @until }
- * @until }
- *
- * Despite being able to store almost any value properties the least flexible
- * information unit we can put in an eina model. We can add eina models to our
- * eina model, this allows us to represt complex information hierarchies. This
- * example adds 5 models(with no children of their own) to our parent model @c
- * m.
- * @until }
- * The code here should be pretty easy to understand, we create a model, much
- * like we did before, and we then add a property to our model, again a task we
- * have already done.
- *
- * The important issue to note here is that we could have given each of our @c c
- * child models as complex an structure as we needed, they could each be a list
- * or a tree on their own right.
- *
- * Now that we have a populated model we print a string representation of
- * it(without forgetting to free the string):
- * @until free
- *
- * And since we are done using our model we release our reference to it(and
- * since no else holds references to it, it will be freed):
- * @until }
- *
- * Note that we don't need to iterate over the children of @c m unrefing it,
- * this is because we don't hold references to it, we freed our references right
- * after we added them to their parent model, so when the parent model dies(and
- * releases the references to it's children) they will be freed.
- *
- * The only thing we are going to look at is the callback we registered for
- * whenever a model is deleted, since our models don't do anything fancy we are
- * just going to print the memory address of the model being freed.
- * @until }
- *
- * Note that this means the memory address is still valid, our callback is
- * called just before the memory is freed so we could still access its
- * information here.
- *
- * The full code can be seen in @ref eina_model_02_c
- */
-
-/**
- * @page eina_model_02_c eina_model_02.c
- * @include eina_model_02.c
- * @example eina_model_02.c
- */
-
-/**
- * @page eina_model_03_example_page Using Eina_Model and inheritance
- * @dontinclude eina_model_03.c
- *
- * This example will use two custom defined eina model types: @c PERSON_TYPE to
- * represent a person and @c ADDRESS_BOOK_TYPE to represent the an address book.
- * Both our types inherit from EINA_MODEL_TYPE_STRUCT, and, therefore,
- * store it's data on a struct. Our address book will be very simple it will
- * only contain one property, the name of the file where we store our address
- * book. The person type will contain two fields a name and en email. Let's look
- * at the code.
- *
- * We'll start with declaring the variables and functions we'll need to define
- * our custom type. This will all be explained when the variables get used.
- * @until address_book_init
- *
- * We then jump into our @c main function, declare a couple of variables and
- * initialize eina:
- * @until eina_init
- *
- * After eina is initialized we'll @c address_book_init() which will initialize
- * both our @c PERSON_TYPE and our @c ADDRESS_BOOK_TYPE. Details of this will be
- * shown latter on:
- * @until address_book_init
- *
- * Now that everything is correctly initialized we can create the model that
- * will represent our address book's
- * @until eina_model_new
- *
- * Before we can load data into our model we need to tell it where to load from,
- * we do this by setting it's filename property:
- * @until value_flush
- *
- * We then load data into our model and display it as a string:
- * @until free
- *
- * While @c eina_model_to_string allows you to see the contents of the model,
- * it's display format is not user friendly, it's best used for debugging. So
- * let's now print our model in a user friendly way.
- *
- * First we see how many people are in our address book and print that:
- * @until printf
- *
- * And now we iterate over every child of our address book model, which
- * represents a person:
- * @until person
- *
- * But again simply calling @c eina_model_to_string would result in not very
- * user friendly output, so we'll need to get the properties of the person(name
- * and email) and print them with some formatting:
- * @until printf
- *
- * We then free the resources we allocated to print this person:
- * @until }
- *
- * And that's it for our main function, now just freeing our resources:
- * @until }
- *
- * This however obviously doesn't conclude our example we need to examine how
- * the the loading of data works to really understand what is happening in the
- * @c main function.
- *
- * Let's start with the constructors(and the variables they use). Both our
- * constructors do two very important tasks:
- * @li Calls our parent's constructor, and
- * @li Sets the description of the struct on our model
- *
- * For these constructors that's all we need to do since most of our
- * functionality is provided by @c EINA_MODEL_TYPE_STRUCT.
- * @until }
- * @until }
- *
- * And now we have our load function, it opens the file from which we'll
- * read the address book:
- * @until EINA_SAFETY_ON_NULL_RETURN_VAL
- *
- * Once the file has been opened we read from it line by line and for each
- * non-blank line we get a name and an email:
- * @until email
- * @until email
- *
- * Once we have the name and email we create our person model, set it's
- * properties and make our person a child of the address book:
- * @until }
- *
- * And now that we're done reading the file we close it:
- * @until }
- *
- * This next function is perphaps the most interesting one of our example, it's
- * the one that creates the definition of our derived types.
- *
- * First thing we'll do is the description of the members of our person type.
- * @until person_members[1].type
- * Now the description of the struct itself(which uses the members):
- * @until }
- * And finally we define the person type itself:
- * @until person_type.constructor
- *
- * With the person now described we'll do the same process for our address book
- * type:
- * @until address_book_type.load
- *
- * So far everything we created has been in the scope of our function to make
- * this available outside(such as in the @c main function where we use @c
- * ADDRESS_BOOK_TYPE and on @c _address_book_load function where we use @c
- * PERSON_TYPE) we need to assign our descriptions and type to global variables:
- * @until }
- *
- * This concludes this example. A good exercise for the reader is to extend this
- * example to have the model save the addres book, for example once it's
- * unloaded, this can be done by overriding the .unload property of @c
- * ADDRESS_BOOK_TYPE.
- *
- * For the full code see: @ref eina_model_03_c
- */
-
-/**
- * @page eina_model_03_c eina_model_03.c
- * @include eina_model_03.c
- * @example eina_model_03.c
- */
-
-/**
- * @addtogroup Eina_Data_Types_Group Data Types
- *
- * @since 1.2
- *
- * @{
- */
-
-/**
- * @addtogroup Eina_Containers_Group Containers
- *
- * @{
- */
-
-/**
+ * @internal
* @defgroup Eina_Model_Group Data Model API
+ * @ingroup Eina_Containers_Group
*
* Abstracts data access to hierarchical data in an efficient way,
* extensible to different backing stores such as database or remote
@@ -288,21 +69,19 @@
* fixed set of names and they have fixed type, as defined by
* the #Eina_Value_Struct_Desc description used internally.
*
- * Examples:
- * @li @ref eina_model_01_c inheritance example, uses #EINA_MODEL_TYPE_GENERIC
- * @li @ref eina_model_02_example_page contains an easy to follow
- * example that demonstrates several of the important features of
- * eina_model, uses #EINA_MODEL_TYPE_GENERIC.
- * @li @ref eina_model_03_example_page walk-through example on how to
- * inherit types, a suggestion of eina_model_load() usage and
- * uses #EINA_MODEL_TYPE_STRUCT.
- * @li @ref eina_model_04_c Advanced inheritance, interfaces and interface
- * function overloading example.
- *
* @{
*/
+/**
+ * @var EINA_ERROR_MODEL_FAILED
+ * Defined when model-specific errors happens.
+ */
EAPI extern Eina_Error EINA_ERROR_MODEL_FAILED;
+
+/**
+ * @var EINA_ERROR_MODEL_METHOD_MISSING
+ * Defined when model-specific errors happens.
+ */
EAPI extern Eina_Error EINA_ERROR_MODEL_METHOD_MISSING;
/**
@@ -508,8 +287,9 @@ EAPI void eina_model_xunref(Eina_Model *model,
/**
+ * @internal
* @defgroup Eina_Model_Event_Group Data Model Events
- * Events and their usage with models.
+ * @brief Events and their usage with models.
*
* Events are specified by each type and interface level
* using #Eina_Model_Event_Description. One can know all events supported
@@ -748,8 +528,9 @@ EAPI Eina_Bool eina_model_unload(Eina_Model *model) EINA_ARG_NONNULL(1);
/**
+ * @internal
* @defgroup Eina_Model_Properties_Group Data Model Properties
- * Properties and their usage with models.
+ * @brief Properties and their usage with models.
*
* Properties are attributes of model. They have a name and contain a
* data value (@ref Eina_Value_Group).
@@ -835,8 +616,9 @@ EAPI void eina_model_properties_names_list_free(Eina_List *list);
*/
/**
+ * @internal
* @defgroup Eina_Model_Children_Group Data Model Children
- * Children and their usage with models.
+ * @brief Children and their usage with models.
*
* Children are other model instances that are kept sequentially in
* the model. They are accessed by their integer index within the
@@ -1005,8 +787,9 @@ EAPI Eina_Bool eina_model_child_sort(Eina_Model *model,
*/
/**
+ * @internal
* @defgroup Eina_Model_Iterators_Group Data Model Iterators
- * Iterators and their usage with models.
+ * @brief Iterators and their usage with models.
*
* One of the most common tasks of models is to iterate over their
* children, either forwards or backwards, filtering by some criteria
@@ -1273,10 +1056,11 @@ EAPI Eina_Iterator *eina_model_child_slice_filtered_iterator_get(Eina_Model *mod
EAPI char *eina_model_to_string(const Eina_Model *model) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT EINA_MALLOC;
/**
+ * @internal
* @defgroup Eina_Model_Type_Group Data Model Type management
*
- * Functions and structures related to implementing new types or
- * extending existing ones.
+ * @brief Functions and structures related to implementing new types or
+ * extending existing ones.
*
* All eina_model_type functions takes an Eina_Model_Type or
* Eina_Model_Interface as parameter and may be used to validate or
@@ -1288,14 +1072,6 @@ EAPI char *eina_model_to_string(const Eina_Model *model) EINA_ARG_NONNULL(1) EIN
* compare() method of the given type (or its parent) instead of the
* most specific type of provided Eina_Model.
*
- * Examples:
- * @li @ref eina_model_02_example_page contains an easy to follow
- * example that demonstrates several of the important features of
- * eina_model, uses #EINA_MODEL_TYPE_GENERIC.
- * @li @ref eina_model_03_example_page walk-through example on how to
- * inherit types, a suggestion of eina_model_load() usage and uses
- * #EINA_MODEL_TYPE_STRUCT.
- *
* @{
*/
@@ -2218,7 +1994,7 @@ EAPI Eina_Bool eina_model_interface_constructor(const Eina_Model_Interface *ifac
* @param model The model instance.
* @return #EINA_TRUE on success, #EINA_FALSE on failure.
*
- * @warning If @a model doesn't implement @a iface does nothing and
+ * @warning If @a model doesn't implement @a iface does nothing and
* returns #EINA_FALSE.
*
* @see eina_model_del()
@@ -2819,9 +2595,10 @@ EAPI void eina_model_interface_children_sort(const Eina_Model_Interface *iface,
*/
/**
+ * @internal
* @defgroup Eina_Model_Utils_Group Data Model Utilities
*
- * Miscellaneous utilities to help usage or debug of @ref Eina_Model_Group.
+ * @brief Miscellaneous utilities to help usage or debug of @ref Eina_Model_Group.
*
* @{
*/
@@ -3135,12 +2912,4 @@ EAPI extern const char *EINA_MODEL_INTERFACE_NAME_CHILDREN;
/**
* @}
*/
-
-/**
- * @}
- */
-
-/**
- * @}
- */
#endif
diff --git a/src/lib/eina/eina_module.h b/src/lib/eina/eina_module.h
index 834dfa8d83..6d50284ecc 100644
--- a/src/lib/eina/eina_module.h
+++ b/src/lib/eina/eina_module.h
@@ -1,14 +1,14 @@
/* EINA - EFL data type library
* Copyright (C) 2007-2008 Jorge Luis Zapata Muga
*
- * This library is free software; you can redistribute it and/or
+ * This library is a free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
@@ -24,318 +24,336 @@
#include "eina_error.h"
/**
- * @addtogroup Eina_Module_Group Module
- *
- * @brief These functions provide module management.
- */
-
-/**
- * @addtogroup Eina_Tools_Group Tools
- *
- * @{
- */
-
-/**
* @defgroup Eina_Module_Group Module
+ * @ingroup Eina_Tools_Group
+ *
+ * @brief This group of functions provide module management.
*
* Eina module provides some helpers over POSIX dlopen(). It is not
- * meant to replace, abstract or make a "portable" version of the
+ * meant to replace, abstract, or make a "portable" version of the
* POSIX, but enhance its usage by defining some good practices.
*
* Modules are created with eina_module_new() and later loaded with
* eina_module_load(). Loads are reference counted and there must be
* the same number of eina_module_unload() in order to have it to call
- * dlclose(). This makes simple to have different users for the same
+ * dlclose(). This makes it simple to have different users for the same
* module.
*
- * The loaded shared objects may have two visible functions that will
- * be called and might provide initialization and shutdown
+ * The loaded shared objects may have two visible functions that are
+ * called and might provide initialization and shutdown
* procedures. The symbols are @c __eina_module_init and
- * @c __eina_module_shutdown and will be defined by the macros
+ * @c __eina_module_shutdown and are defined by the macros
* EINA_MODULE_INIT() and EINA_MODULE_SHUTDOWN().
*
* There are some helpers to automatically create modules based on
* directory listing. See eina_module_arch_list_get(),
- * eina_module_list_get() and eina_module_find().
+ * eina_module_list_get(), and eina_module_find().
*
* @{
*/
/**
* @typedef Eina_Module
- * Dynamic module loader handle.
+ * @brief The structure type for the dynamic module loader handle.
*/
typedef struct _Eina_Module Eina_Module;
/**
* @typedef Eina_Module_Cb
- * Dynamic module loader callback.
+ * @brief The dynamic module loader callback.
*/
typedef Eina_Bool (*Eina_Module_Cb)(Eina_Module *m, void *data);
/**
* @typedef Eina_Module_Init
- * If a function with such signature is exported by module as
- * __eina_module_init, it will be called on the first load after
- * dlopen() and if #EINA_FALSE is returned, load will fail, #EINA_TRUE
- * means the module was successfully initialized.
+ * @brief If a function with such a signature is exported by the module as
+ * __eina_module_init, it is called on the first load after
+ * dlopen() and if @c EINA_FALSE is returned, the load fails, @c EINA_TRUE
+ * means the module is successfully initialized.
* @see Eina_Module_Shutdown
*/
typedef Eina_Bool (*Eina_Module_Init)(void);
/**
* @typedef Eina_Module_Shutdown
- * If a function with such signature is exported by module as
- * __eina_module_shutdown, it will be called before calling dlclose()
+ * @brief If a function with such a signature is exported by the module as
+ * __eina_module_shutdown, it is called before calling dlclose()
* @see Eina_Module_Init
*/
typedef void (*Eina_Module_Shutdown)(void);
/**
* @def EINA_MODULE_INIT
- * declares the given function as the module initializer (__eina_module_init).
- * It must be of signature #Eina_Module_Init
+ * @brief Definition that declares the given function as the module initializer (__eina_module_init).
+ * It must be of signature #Eina_Module_Init
*/
#define EINA_MODULE_INIT(f) EAPI Eina_Module_Init __eina_module_init = &f
/**
* @def EINA_MODULE_SHUTDOWN
- * declares the given function as the module shutdownializer
- * (__eina_module_shutdown). It must be of signature #Eina_Module_Shutdown
+ * @brief Defintion that declares the given function as the module shutdown initializer (__eina_module_shutdown).
+ * It must be of signature #Eina_Module_Shutdown
*/
#define EINA_MODULE_SHUTDOWN(f) EAPI Eina_Module_Shutdown __eina_module_shutdown = &f
+/**
+ * @var EINA_ERROR_WRONG_MODULE
+ * @brief The error identifier corresponding to a wrong module.
+ */
extern EAPI Eina_Error EINA_ERROR_WRONG_MODULE;
+
+/**
+ * @var EINA_ERROR_MODULE_INIT_FAILED
+ * @brief The error identifier corresponding to a failure during the initialisation of a module.
+ */
extern EAPI Eina_Error EINA_ERROR_MODULE_INIT_FAILED;
/**
- * @brief Return a new module.
+ * @brief Returns a new module.
*
- * @param file The name of the file module to load.
- * @return A new module. If @p file is @c NULL, or if it does not exist,
- * the function returns @c NULL, otherwise, it allocates an Eina_Module,
- * stores a duplicate string of @p file, sets its reference to @c 0 and
- * its handle to @c NULL.
+ * @since_tizen 2.3
*
- * When the new module is not needed anymore, use eina_module_free()
- * to free the allocated memory.
+ * @remarks When the new module is not needed anymore, use eina_module_free()
+ * to free the allocated memory.
+ *
+ * @param[in] file The name of the file module to load
+ * @return A new module \n
+ * If @a file is @c NULL, the function returns @c NULL,
+ * otherwise it allocates an Eina_Module, stores
+ * a duplicate string of @a file, sets its reference to @c 0 and
+ * its handle to @c NULL.
*
* @see eina_module_load
*/
-EAPI Eina_Module *
- eina_module_new(const char *file) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+EAPI Eina_Module *eina_module_new(const char *file) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
/**
- * @brief Delete a module.
+ * @brief Deletes a module.
*
- * @param module The module to delete.
- * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
+ * @details This function calls eina_module_unload() if @a module has been previously
+ * loaded and frees the allocated memory. On success this function
+ * returns @c EINA_TRUE, otherwise it returns @c EINA_FALSE. If @a module is @c NULL, the
+ * function returns immediately.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] module The module to delete
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE
*
- * This function calls eina_module_unload() if @p module has been previously
- * loaded and frees the allocated memory. On success this function
- * returns #EINA_TRUE and #EINA_FALSE otherwise. If @p module is @c NULL, the
- * function returns immediately.
- */
-EAPI Eina_Bool
- eina_module_free(Eina_Module *module) EINA_ARG_NONNULL(1);
-
-/**
- * @brief Load a module.
- *
- * @param module The module to load.
- * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
- *
- * This function load the shared file object passed in
- * eina_module_new(). If it is a internal Eina module (like the
- * mempools), it also initialize it. If the shared file object can not
- * be loaded, #EINA_FALSE is returned. If it is an internal Eina module and the
- * module can not be initialized, #EINA_FALSE is returned. If the module has
- * already been loaded, it's reference counter is increased by one and
- * #EINA_TRUE is returned. If @p module is @c NULL, the function returns
- * immediately #EINA_FALSE.
- *
- * When the symbols of the shared file objects are not needed
- * anymore, call eina_module_unload() to unload the module.
*/
-EAPI Eina_Bool
- eina_module_load(Eina_Module *module) EINA_ARG_NONNULL(1);
+EAPI Eina_Bool eina_module_free(Eina_Module *module) EINA_ARG_NONNULL(1);
/**
- * @brief Unload a module.
- *
- * @param module The module to load.
- * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
- *
- * This function unload the module @p module that has been previously
- * loaded by eina_module_load(). If the reference counter of @p module is
- * strictly greater than @c 1, #EINA_FALSE is returned. Otherwise, the
- * shared object file is closed and if it is a internal Eina module, it
- * is shutted down just before. In that case, #EINA_TRUE is
- * returned. In all case, the reference counter is decreased. If @p module
- * is @c NULL, the function returns immediately #EINA_FALSE.
+ * @brief Loads a module.
+ *
+ * @details This function loads the shared file object passed in
+ * eina_module_new(). If it is an internal Eina module (like the
+ * mempools), it also initializes it. If the shared file object cannot
+ * be loaded, the error #EINA_ERROR_WRONG_MODULE is set and
+ * and @c EINA_FALSE is returned. If it is an internal Eina module and the
+ * module cannot be initialized, the error #EINA_ERROR_MODULE_INIT_FAILED
+ * is set and @c EINA_FALSE is returned. If the module has already been loaded,
+ * its reference counter is increased by one and @c EINA_TRUE is returned.
+ * If @a module is @c NULL, the function returns @c EINA_FALSE immediately.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks When the symbols of the shared file objects are not needed
+ * anymore, call eina_module_unload() to unload the module.
+ *
+ * @param[in] module The module to load
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE
+ *
*/
-EAPI Eina_Bool
- eina_module_unload(Eina_Module *module) EINA_ARG_NONNULL(1);
+EAPI Eina_Bool eina_module_load(Eina_Module *module) EINA_ARG_NONNULL(1);
/**
- * @brief Retrieve the data associated to a symbol.
+ * @brief Unloads a module.
*
- * @param module The module.
- * @param symbol The symbol.
- * @return The data associated to the symbol, or @c NULL on failure.
+ * @details This function unloads the module @a module that has been previously
+ * loaded by eina_module_load(). If the reference counter of @a module is
+ * strictly greater than @c 1, @c EINA_FALSE is returned. Otherwise, the
+ * shared object file is closed and if it is an internal Eina module, it
+ * is shut down just before. In that case, @c EINA_TRUE is
+ * returned. In all cases, the reference counter is decreased. If @a module
+ * is @c NULL, the function returns @c EINA_FALSE immediately.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] module The module to unload
+ * @return @c EINA_TRUE on success, otherwise EINA_FALSE
*
- * This function returns the data associated to @p symbol of @p module. @p
- * module must have been loaded before with eina_module_load(). If @p module
- * is @c NULL, or if it has not been correctly loaded before, the
- * function returns immediately @c NULL.
*/
-EAPI void *
- eina_module_symbol_get(const Eina_Module *module, const char *symbol) EINA_PURE EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT;
+EAPI Eina_Bool eina_module_unload(Eina_Module *module) EINA_ARG_NONNULL(1);
/**
- * @brief Return the file name associated to the module.
+ * @brief Gets the data associated to a symbol.
+ *
+ * @details This function returns the data associated to @a symbol of @a module. @a
+ * module must have been loaded earlier with eina_module_load(). If @a module
+ * is @c NULL, or if it has not been correctly loaded before, the
+ * function returns @c NULL immediately.
*
- * @param module The module.
- * @return The file name.
+ * @since_tizen 2.3
+ *
+ * @param[in] module The module
+ * @param[in] symbol The symbol
+ * @return The data associated to the symbol, otherwise @c NULL on failure
*
- * This function returns the file name passed in eina_module_new(). If
- * @p module is @c NULL, the function returns immediately @c NULL. The
- * returned value must no be freed.
*/
-EAPI const char *
- eina_module_file_get(const Eina_Module *module) EINA_PURE EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+EAPI void *eina_module_symbol_get(const Eina_Module *module, const char *symbol) EINA_PURE EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT;
/**
- * @brief Define if on module load we should expose all symbol
+ * @brief Gets the file name associated to the module.
+ *
+ * @details This function returns the file name passed in eina_module_new(). If
+ * @a module is @c NULL, the function returns @c NULL immediately. The
+ * returned value must no be freed.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] module The module
+ * @return The file name
*
- * @param module The module to turn off/on symbol to be exposed
- * @since 1.11
*/
-EAPI void eina_module_symbol_global_set(Eina_Module *module, Eina_Bool global) EINA_ARG_NONNULL(1);
+EAPI const char *eina_module_file_get(const Eina_Module *module) EINA_PURE EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
+
/**
- * @brief Return the path built from the location of a library and a
- * given sub directory.
- *
- * @param symbol The symbol to search for.
- * @param sub_dir The subdirectory to append.
- * @return The built path on success, @c NULL otherwise.
- *
- * This function returns the path built by concatenating the path of
- * the library containing the symbol @p symbol and @p sub_dir. @p sub_dir
- * can be @c NULL. The returned path must be freed when not used
- * anymore. If the symbol is not found, or dl_addr() is not supported,
- * or allocation fails, this function returns @c NULL.
+ * @brief Gets the path built from the location of a library and a
+ * given sub directory.
+ *
+ * @details This function returns the path built by concatenating the path of
+ * the library containing the symbol @a symbol and @a sub_dir. @a sub_dir
+ * can be @c NULL. The returned path must be freed when not used
+ * anymore. If the symbol is not found, or dl_addr() is not supported,
+ * or allocation fails, this function returns @c NULL.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] symbol The symbol to search for
+ * @param[in] sub_dir The subdirectory to append
+ * @return The built path on success, otherwise @c NULL
+ *
*/
-EAPI char *
- eina_module_symbol_path_get(const void *symbol, const char *sub_dir) EINA_PURE EINA_MALLOC EINA_ARG_NONNULL(1, 2);
+EAPI char *eina_module_symbol_path_get(const void *symbol, const char *sub_dir) EINA_PURE EINA_MALLOC EINA_ARG_NONNULL(1, 2);
/**
- * @brief Return the path built from the value of an environment variable and a
- * given sub directory.
- *
- * @param env The environment variable to expand.
- * @param sub_dir The subdirectory to append.
- * @return The built path on success, @c NULL otherwise.
- *
- * This function returns the path built by concatenating the value of
- * the environment variable named @p env and @p sub_dir. @p sub_dir
- * can be @c NULL. The returned path must be freed when not used
- * anymore. If the symbol is not found, or @p env does not exist, or
- * allocation fails, this function returns @c NULL.
+ * @brief Gets the path built from the value of an environment variable and a
+ * given sub directory.
+ *
+ * @details This function returns the path built by concatenating the value of
+ * the environment variable named @a env and @a sub_dir. @a sub_dir
+ * can be @c NULL. The returned path must be freed when not used
+ * anymore. If the symbol is not found, or @a env does not exist, or
+ * allocation fails, this function returns @c NULL.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] env The environment variable to expand
+ * @param[in] sub_dir The subdirectory to append
+ * @return The built path on success, otherwise @c NULL
+ *
*/
-EAPI char *
- eina_module_environment_path_get(const char *env, const char *sub_dir) EINA_PURE EINA_MALLOC EINA_ARG_NONNULL(1, 2);
+EAPI char *eina_module_environment_path_get(const char *env, const char *sub_dir) EINA_PURE EINA_MALLOC EINA_ARG_NONNULL(1, 2);
/**
- * @brief Get an array of modules found on the directory path matching an arch type.
+ * @brief Gets an array of modules found on the directory path matching an arch type.
+ *
+ * @details This function adds to @a array the module names found in @a path
+ * which match the CPU architecture @a arch. If @a path or @a arch is
+ * @c NULL, the function returns @a array immediately. @a array can be
+ * @c NULL. In that case, it is created with 4 elements.
*
- * @param array The array that stores the list of the modules.
- * @param path The directory's path to search for modules.
- * @param arch The architecture string.
- * @return The array of modules found in @p path matching @p arch.
+ * @since_tizen 2.3
+ *
+ * @param[in] array The array that stores the list of the modules
+ * @param[in] path The directory path to search for modules
+ * @param[in] arch The architecture string
+ * @return The array of modules found in @a path matching @a arch
*
- * This function adds to @p array the module names found in @p path
- * which match the cpu architecture @p arch. If @p path or @p arch is
- * @c NULL, the function returns immediately @p array. @p array can be
- * @c NULL. In that case, it is created with 4 elements.
*/
-EAPI Eina_Array *
- eina_module_arch_list_get(Eina_Array *array, const char *path, const char *arch);
+EAPI Eina_Array *eina_module_arch_list_get(Eina_Array *array, const char *path, const char *arch);
/**
- * @brief Get a list of modules found on the directory path.
- *
- * @param array The array that stores the list of the modules.
- * @param path The directory's path to search for modules.
- * @param recursive Iterate recursively on the path.
- * @param cb Callback function to call on each module.
- * @param data Data passed to the callback function.
- * @return The array of modules found in @p path.
- *
- * This function adds to @p array the list of modules found in
- * @p path. If @p recursive is #EINA_TRUE, then recursive search is
- * done. The callback @p cb is called on each module found, and @p data
- * is passed to @p cb. If @p path is @c NULL, the function returns
- * immediately @p array. If the returned value of @p cb is @c 0, the
- * module will not be added to the list, otherwise it will be added.
- * @p array can be @c NULL. In that case, it is created with 4
- * elements. @p cb can be @c NULL.
+ * @brief Gets a list of modules found on the directory path.
+ *
+ * @details This function adds to @a array the list of modules found in
+ * @a path. If @a recursive is @c EINA_TRUE, then recursive search is
+ * done. The callback @a cb is called on each module found, and @a data
+ * is passed to @a cb. If @a path is @c NULL, the function returns
+ * @a array immediately. If the returned value of @a cb is @c 0, the
+ * module is not added to the list, otherwise it is added.
+ * @a array can be @c NULL. In that case, it is created with 4
+ * elements. @a cb can be @c NULL.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] array The array that stores the list of the modules
+ * @param[in] path The directory path to search for modules
+ * @param[in] recursive The boolean value to iterate recursively on the path
+ * @param[in] cb The callback function to call on each module
+ * @param[in] data The data passed to the callback function
+ * @return The array of modules found in @a path
+ *
*/
-EAPI Eina_Array *
- eina_module_list_get(Eina_Array *array, const char *path, Eina_Bool recursive, Eina_Module_Cb cb, void *data) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
+EAPI Eina_Array *eina_module_list_get(Eina_Array *array, const char *path, Eina_Bool recursive, Eina_Module_Cb cb, void *data) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
/**
- * @brief Load every module on the list of modules.
+ * @brief Loads every module on the list of modules.
*
- * @param array The array of modules to load.
+ * @details This function calls eina_module_load() on each element found in
+ * @a array. If @a array is @c NULL, this function does nothing.
*
- * This function calls eina_module_load() on each element found in
- * @p array. If @p array is @c NULL, this function does nothing.
- */
-EAPI void
- eina_module_list_load(Eina_Array *array) EINA_ARG_NONNULL(1);
-
-/**
- * @brief Unload every module on the list of modules.
+ * @since_tizen 2.3
*
- * @param array The array of modules to unload.
+ * @param[in] array The array of modules to load
*
- * This function calls eina_module_unload() on each element found in
- * @p array. If @p array is @c NULL, this function does nothing.
*/
-EAPI void
- eina_module_list_unload(Eina_Array *array) EINA_ARG_NONNULL(1);
+EAPI void eina_module_list_load(Eina_Array *array) EINA_ARG_NONNULL(1);
/**
- * @p Free every module on the list of modules.
+ * @brief Unloads every module on the list of modules.
+ *
+ * @details This function calls eina_module_unload() on each element found in
+ * @a array. If @a array is @c NULL, this function does nothing.
+ *
+ * @since_tizen 2.3
*
- * @param array The array of modules to free.
+ * @param[in] array The array of modules to unload
*
- * This function calls eina_module_free() on each element found in
- * @p array. If @p array is @c NULL, this function does nothing.
*/
-EAPI void
- eina_module_list_free(Eina_Array *array) EINA_ARG_NONNULL(1);
+EAPI void eina_module_list_unload(Eina_Array *array) EINA_ARG_NONNULL(1);
/**
- * @brief Find an module in array.
+ * @brief Frees every module on the list of modules.
*
- * @param array The array to find the module.
- * @param module The name of module to be searched.
- * @return The module to find on success, @c NULL otherwise.
+ * @details This function calls eina_module_free() on each element found in
+ * @a array. If @a array is @c NULL, this function does nothing.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] array The array of modules to free
*
- * This function finds an @p module in @p array.
- * If the element is found the function returns the module, else
- * @c NULL is returned.
*/
-EAPI Eina_Module *
- eina_module_find(const Eina_Array *array, const char *module) EINA_ARG_NONNULL(1, 2);
+EAPI void eina_module_list_free(Eina_Array *array) EINA_ARG_NONNULL(1);
/**
- * @}
+ * @brief Finds a module in an array.
+ *
+ * @details This function finds a @a module in @a array.
+ * If the element is found the function returns the module, otherwise
+ * @c NULL is returned.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] array The array to find the module in
+ * @param[in] module The name of the module to be searched
+ * @return The module to find on success, otherwise @c NULL
+ *
*/
+EAPI Eina_Module *eina_module_find(const Eina_Array *array, const char *module) EINA_ARG_NONNULL(1, 2);
/**
* @}
diff --git a/src/lib/eina/eina_quadtree.h b/src/lib/eina/eina_quadtree.h
index 2638d8ba59..28817404bc 100644
--- a/src/lib/eina/eina_quadtree.h
+++ b/src/lib/eina/eina_quadtree.h
@@ -1,14 +1,14 @@
/* EINA - EFL data type library
* Copyright (C) 2010 Cedric BAIL
*
- * This library is free software; you can redistribute it and/or
+ * This library is a free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
diff --git a/src/lib/eina/eina_rbtree.h b/src/lib/eina/eina_rbtree.h
index 6a4d764299..e37d1f06b5 100644
--- a/src/lib/eina/eina_rbtree.h
+++ b/src/lib/eina/eina_rbtree.h
@@ -1,14 +1,14 @@
/* EINA - EFL data type library
* Copyright (C) 2008 Cedric Bail
*
- * This library is free software; you can redistribute it and/or
+ * This library is a free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
@@ -26,38 +26,23 @@
#include "eina_iterator.h"
/**
- * @addtogroup Eina_Rbtree_Group Red-Black tree
+ * @defgroup Eina_Rbtree_Group Red-Black tree
+ * @ingroup Eina_Containers_Group
*
- * @brief These functions provide Red-Black trees management.
+ * @brief This group discusses the functions that provide Red-Black trees management.
*
* For a brief description look at http://en.wikipedia.org/wiki/Red-black_tree .
* This code is largely inspired from a tutorial written by Julienne Walker at :
* http://eternallyconfuzzled.com/tuts/datastructures/jsw_tut_rbtree.aspx . The
- * main difference is that this set of function never allocate any data, making
+ * main difference is that this set of functions never allocate any data, making
* them particularly useful for memory management.
- */
-
-/**
- * @addtogroup Eina_Data_Types_Group Data Types
- *
- * @{
- */
-
-/**
- * @addtogroup Eina_Containers_Group Containers
- *
- * @{
- */
-
-/**
- * @defgroup Eina_Rbtree_Group Red-Black tree
*
* @{
*/
/**
* @typedef Eina_Rbtree_Color
- * node color.
+ * @brief Enumeration of the node color.
*/
typedef enum {
EINA_RBTREE_RED,
@@ -66,7 +51,7 @@ typedef enum {
/**
* @typedef Eina_Rbtree_Direction
- * walk direction.
+ * @brief Enumeration of the walk direction.
*/
typedef enum {
EINA_RBTREE_LEFT = 0,
@@ -75,19 +60,19 @@ typedef enum {
/**
* @typedef Eina_Rbtree
- * Type for a Red-Black tree node. It should be inlined into user's type.
+ * @brief The structure type for a Red-Black tree node. It should be inlined into the user type.
*/
typedef struct _Eina_Rbtree Eina_Rbtree;
struct _Eina_Rbtree
{
Eina_Rbtree *son[2];
- unsigned int color : 1;
+ Eina_Rbtree_Color color : 1;
};
/**
* @def EINA_RBTREE
- * recommended way to declare the inlined Eina_Rbtree in your type.
+ * @brief Definition of the recommended way to declare the inlined Eina_Rbtree for your type.
*
* @code
* struct my_type {
@@ -103,87 +88,101 @@ struct _Eina_Rbtree
/**
* @def EINA_RBTREE_GET
- * access the inlined node if it was created with #EINA_RBTREE.
+ *
+ * @since_tizen 2.3
+ *
+ * @brief Definition to access the inlined node if it is created with #EINA_RBTREE.
*/
#define EINA_RBTREE_GET(Rbtree) (&((Rbtree)->__rbtree))
/**
* @def EINA_RBTREE_CONTAINER_GET
- * find back the container of an red black tree.
+ *
+ * @since_tizen 2.3
+ *
+ * @brief Definition to find back the container of a red black tree.
*/
#define EINA_RBTREE_CONTAINER_GET(Ptr, Type) ((Type *)((char *)Ptr - offsetof(Type, __rbtree)))
/**
* @typedef Eina_Rbtree_Cmp_Node_Cb
- * Function used compare two nodes and see which direction to navigate.
+ * @brief Compares two nodes and decides which direction to navigate.
*/
typedef Eina_Rbtree_Direction (*Eina_Rbtree_Cmp_Node_Cb)(const Eina_Rbtree *left, const Eina_Rbtree *right, void *data);
/**
* @def EINA_RBTREE_CMP_NODE_CB
- * Cast using #Eina_Rbtree_Cmp_Node_Cb
+ * @brief Definition of the cast using #Eina_Rbtree_Cmp_Node_Cb.
*/
#define EINA_RBTREE_CMP_NODE_CB(Function) ((Eina_Rbtree_Cmp_Node_Cb)Function)
/**
* @typedef Eina_Rbtree_Cmp_Key_Cb
- * Function used compare node with a given key of specified length.
+ * @brief Compares a node with the given key of the specified length.
*/
typedef int (*Eina_Rbtree_Cmp_Key_Cb)(const Eina_Rbtree *node, const void *key, int length, void *data);
/**
* @def EINA_RBTREE_CMP_KEY_CB
- * Cast using #Eina_Rbtree_Cmp_Key_Cb
+ * @brief Definition of the cast using #Eina_Rbtree_Cmp_Key_Cb.
*/
#define EINA_RBTREE_CMP_KEY_CB(Function) ((Eina_Rbtree_Cmp_Key_Cb)Function)
/**
* @typedef Eina_Rbtree_Free_Cb
- * Function used free a node.
+ * @brief Called to free a node.
*/
typedef void (*Eina_Rbtree_Free_Cb)(Eina_Rbtree *node, void *data);
/**
* @def EINA_RBTREE_FREE_CB
- * Cast using #Eina_Rbtree_Free_Cb
+ * @brief Definition of the cast using #Eina_Rbtree_Free_Cb.
*/
#define EINA_RBTREE_FREE_CB(Function) ((Eina_Rbtree_Free_Cb)Function)
/**
- * @brief Insert a new node inside an existing red black tree.
+ * @brief Inserts a new node inside an existing red black tree.
*
- * @param root The root of an exisiting valid red black tree.
- * @param node The new node to insert.
- * @param cmp The callback that is able to compare two nodes.
- * @param data Private data to help the compare function.
- * @return The new root of the red black tree.
+ * @details This function inserts a new node into a valid red black tree. @c NULL is
+ * an empty valid red black tree. The resulting new tree is a valid red
+ * black tree. This function doesn't allocate any data.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] root The root of an existing valid red black tree
+ * @param[in] node The new node to insert
+ * @param[in] cmp The callback that is able to compare two nodes
+ * @param[in] data The private data to help the compare function
+ * @return The new root of the red black tree
*
- * This function insert a new node in a valid red black tree. @c NULL is
- * an empty valid red black tree. The resulting new tree is a valid red
- * black tree. This function doesn't allocate any data.
*/
EAPI Eina_Rbtree *eina_rbtree_inline_insert(Eina_Rbtree *root, Eina_Rbtree *node, Eina_Rbtree_Cmp_Node_Cb cmp, const void *data) EINA_ARG_NONNULL(2, 3) EINA_WARN_UNUSED_RESULT;
/**
- * @brief Remove a node from an existing red black tree.
+ * @brief Removes a node from an existing red black tree.
+ *
+ * @details This function removes a new node from a valid red black tree that should
+ * contain the node that you are removing. This function returns @c NULL
+ * when the red black tree becomes empty. This function doesn't free any data.
*
- * @param root The root of a valid red black tree.
- * @param node The node to remove from the tree.
- * @param cmp The callback that is able to compare two nodes.
- * @param data Private data to help the compare function.
- * @return The new root of the red black tree.
+ * @since_tizen 2.3
+ *
+ * @param[in] root The root of a valid red black tree
+ * @param[in] node The node to remove from the tree
+ * @param[in] cmp The callback that is able to compare two nodes
+ * @param[in] data The private data to help the compare function
+ * @return The new root of the red black tree
*
- * This function remove a new node in a valid red black tree that should
- * contain the node that you are removing. This function will return @c NULL
- * when the red black tree got empty. This function doesn't free any data.
*/
EAPI Eina_Rbtree *eina_rbtree_inline_remove(Eina_Rbtree *root, Eina_Rbtree *node, Eina_Rbtree_Cmp_Node_Cb cmp, const void *data) EINA_ARG_NONNULL(2, 3) EINA_WARN_UNUSED_RESULT;
/**
- * @brief Delete all nodes from a valid red black tree.
+ * @brief Deletes all the nodes from a valid red black tree.
+ *
+ * @since_tizen 2.3
*
- * @param root The root of a valid red black tree.
- * @param func The callback that will free each node.
- * @param data Private data to help the compare function.
+ * @param[in] root The root of a valid red black tree
+ * @param[in] func The callback that frees each node
+ * @param[in] data The private data to help the compare function
*
*/
EAPI void eina_rbtree_delete(Eina_Rbtree *root, Eina_Rbtree_Free_Cb func, void *data) EINA_ARG_NONNULL(2);
@@ -192,62 +191,74 @@ static inline Eina_Rbtree *eina_rbtree_inline_lookup(const Eina_Rbtree *root, co
/**
- * @brief Returned a new prefix iterator associated to a rbtree.
+ * @brief Returns a new prefix iterator associated to an rbtree.
*
- * @param root The root of rbtree.
- * @return A new iterator.
+ * @details This function returns a newly allocated iterator associated to
+ * @a root. It iterates the tree using prefix walk. If @a root is
+ * @c NULL, this function still returns a valid iterator that always
+ * returns @c false on eina_iterator_next(), thus keeping the API sane.
*
- * This function returns a newly allocated iterator associated to @p
- * root. It will iterate the tree using prefix walk. If @p root is @c
- * NULL, this function still returns a valid iterator that will always
- * return false on eina_iterator_next(), thus keeping API sane.
+ * @since_tizen 2.3
*
- * If the memory can not be allocated, @c NULL is returned.
- * Otherwise, a valid iterator is returned.
+ * @remarks If the memory cannot be allocated, @c NULL is returned
+ * and #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is
+ * returned.
+ *
+ * @remarks If the rbtree 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.
+ *
+ * @param[in] root The root of the rbtree
+ * @return A new iterator
*
- * @warning if the rbtree 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!
*/
EAPI Eina_Iterator *eina_rbtree_iterator_prefix(const Eina_Rbtree *root) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
/**
- * @brief Returned a new prefix iterator associated to a rbtree.
+ * @brief Returns a new prefix iterator associated to an rbtree.
+ *
+ * @details This function returns a newly allocated iterator associated to
+ * @a root. It iterates the tree using infix walk. If @a root is
+ * @c NULL, this function still returns a valid iterator that always
+ * returns @c false on eina_iterator_next(), thus keeping the API sane.
*
- * @param root The root of rbtree.
- * @return A new iterator.
+ * @since_tizen 2.3
*
- * This function returns a newly allocated iterator associated to @p
- * root. It will iterate the tree using infix walk. If @p root is @c
- * NULL, this function still returns a valid iterator that will always
- * return false on eina_iterator_next(), thus keeping API sane.
+ * @remarks If the memory cannot be allocated, @c NULL is returned
+ * and #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is
+ * returned.
*
- * If the memory can not be allocated, @c NULL is returned.
- * Otherwise, a valid iterator is returned.
+ * @remarks If the rbtree 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.
+ *
+ * @param[in] root The root of the rbtree
+ * @return A new iterator
*
- * @warning if the rbtree 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!
*/
EAPI Eina_Iterator *eina_rbtree_iterator_infix(const Eina_Rbtree *root) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
/**
- * @brief Returned a new prefix iterator associated to a rbtree.
+ * @brief Returns a new prefix iterator associated to an rbtree.
+ *
+ * @details This function returns a newly allocated iterator associated to
+ * @a root. It iterates the tree using postfix walk. If @a root is
+ * @c NULL, this function still returns a valid iterator that always
+ * returns @c false on eina_iterator_next(), thus keeping the API sane.
*
- * @param root The root of rbtree.
- * @return A new iterator.
+ * @since_tizen 2.3
*
- * This function returns a newly allocated iterator associated to @p
- * root. It will iterate the tree using postfix walk. If @p root is @c
- * NULL, this function still returns a valid iterator that will always
- * return false on eina_iterator_next(), thus keeping API sane.
+ * @remarks If the memory cannot be allocated, @c NULL is returned
+ * and #EINA_ERROR_OUT_OF_MEMORY is set. Otherwise, a valid iterator is
+ * returned.
*
- * If the memory can not be allocated, @c NULL is returned.
- * Otherwise, a valid iterator is returned.
+ * @remarks If the rbtree 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.
+ *
+ * @param[in] root The root of the rbtree
+ * @return A new iterator
*
- * @warning if the rbtree 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!
*/
EAPI Eina_Iterator *eina_rbtree_iterator_postfix(const Eina_Rbtree *root) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
@@ -257,12 +268,4 @@ EAPI Eina_Iterator *eina_rbtree_iterator_postfix(const Eina_Rbtree *root)
* @}
*/
-/**
- * @}
- */
-
-/**
- * @}
- */
-
#endif
diff --git a/src/lib/eina/eina_rectangle.h b/src/lib/eina/eina_rectangle.h
index 55d370ff25..e7675128df 100644
--- a/src/lib/eina/eina_rectangle.h
+++ b/src/lib/eina/eina_rectangle.h
@@ -1,14 +1,14 @@
/* EINA - EFL data type library
* Copyright (C) 2007-2008 Jorge Luis Zapata Muga
*
- * This library is free software; you can redistribute it and/or
+ * This library is a free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
@@ -22,490 +22,417 @@
#include "eina_types.h"
/**
- * @addtogroup Eina_Rectangle_Group Rectangle
- *
- * @brief These functions provide rectangle management.
- */
-
-/**
- * @addtogroup Eina_Tools_Group Tools
- *
- * @{
- */
-
-/**
* @defgroup Eina_Rectangle_Group Rectangle
+ * @ingroup Eina_Tools_Group
+ *
+ * @brief This group discusses the functions that provide rectangle management.
*
* @{
*/
-#define EINA_RECTANGLE_INIT { 0, 0, 0, 0}
-#define EINA_RECTANGLE_FORMAT "dx%d - %dx%d"
-#define EINA_RECTANGLE_ARGS(r) (r)->x, (r)->y, (r)->w, (r)->h
-
/**
* @typedef Eina_Rectangle
- * Simple rectangle structure.
+ * @brief The structure type for the simple rectangle structure.
*/
typedef struct _Eina_Rectangle
{
- int x; /**< top-left x co-ordinate of rectangle */
- int y; /**< top-left y co-ordinate of rectangle */
- int w; /**< width of rectangle */
- int h; /**< height of rectangle */
+ int x; /**< The top-left x co-ordinate of the rectangle */
+ int y; /**< The top-left y co-ordinate of the rectangle */
+ int w; /**< The width of the rectangle */
+ int h; /**< The height of the rectangle */
} Eina_Rectangle;
/**
* @typedef Eina_Rectangle_Pool
- * Type for an opaque pool of rectangle.
+ * @brief The structure type for an opaque rectangle pool.
*/
typedef struct _Eina_Rectangle_Pool Eina_Rectangle_Pool;
/**
- * @typedef Eina_Rectangle_Pool_Type
- * Type for an Eina Pool based on packing algorithm.
- * @since 1.11
+ * @typedef Eina_Rectangle_Packing
+ * @brief Enumeration of the type for an Eina Pool based on the packing algorithm.
+ * @since 1.10
*/
typedef enum {
Eina_Packing_Descending, /**< Current */
- Eina_Packing_Ascending, /**< sorting in assending order */
- Eina_Packing_Bottom_Left, /**< sorting in bottemleft fasion */
- Eina_Packing_Bottom_Left_Skyline, /**< bottemleft skyline */
- Eina_Packing_Bottom_Left_Skyline_Improved /**< optimized bottemleft skyline */
+ Eina_Packing_Ascending, /**< Sorting in ascending order */
+ Eina_Packing_Bottom_Left, /**< Sorting in bottom left fashion */
+ Eina_Packing_Bottom_Left_Skyline, /**< Bottom left skyline */
+ Eina_Packing_Bottom_Left_Skyline_improved /**< Optimized bottom left skyline */
} Eina_Rectangle_Packing;
/**
* @brief Check if the given spans intersect.
*
- * @param c1 The column of the first span.
- * @param l1 The length of the first span.
- * @param c2 The column of the second span.
- * @param l2 The length of the second span.
- * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
+ * @details This function returns #EINA_TRUE if the given spans intersect,
+ * #EINA_FALSE otherwise.
*
- * This function returns #EINA_TRUE if the given spans intersect, #EINA_FALSE
- * otherwise.
+ * @since_tizen 2.3
+ *
+ * @param[in] c1 The column of the first span.
+ * @param[in] l1 The length of the first span.
+ * @param[in] c2 The column of the second span.
+ * @param[in] l2 The length of the second span.
+ * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*/
static inline int eina_spans_intersect(int c1, int l1, int c2, int l2) EINA_WARN_UNUSED_RESULT;
/**
* @brief Check if the given rectangle is empty.
*
- * @param r The rectangle to check.
- * @return #EINA_TRUE if the rectangle is empty, #EINA_FALSE otherwise.
+ * @details This function returns #EINA_TRUE if @p r is empty, #EINA_FALSE
+ * otherwise. No check is done on @p r, so it must be a valid
+ * rectangle.
+ *
+ * @since_tizen 2.3
*
- * This function returns #EINA_TRUE if @p r is empty, #EINA_FALSE
- * otherwise. No check is done on @p r, so it must be a valid
- * rectangle.
+ * @param[in] r The rectangle to check.
+ * @return #EINA_TRUE if the rectangle is empty, #EINA_FALSE otherwise.
*/
static inline Eina_Bool eina_rectangle_is_empty(const Eina_Rectangle *r) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
/**
* @brief Set the coordinates and size of the given rectangle.
*
- * @param r The rectangle.
- * @param x The top-left x coordinate of the rectangle.
- * @param y The top-left y coordinate of the rectangle.
- * @param w The width of the rectangle.
- * @param h The height of the rectangle.
+ * @details This function sets its top-left x coordinate to @p x, its top-left
+ * y coordinate to @p y, its width to @p w and its height to @p h. No
+ * check is done on @p r, so it must be a valid rectangle.
+ *
+ * @since_tizen 2.3
*
- * This function sets its top-left x coordinate to @p x, its top-left
- * y coordinate to @p y, its width to @p w and its height to @p h. No
- * check is done on @p r, so it must be a valid rectangle.
+ * @param[in] r The rectangle.
+ * @param[in] x The top-left x coordinate of the rectangle.
+ * @param[in] y The top-left y coordinate of the rectangle.
+ * @param[in] w The width of the rectangle.
+ * @param[in] h The height of the rectangle.
*/
static inline void eina_rectangle_coords_from(Eina_Rectangle *r, int x, int y, int w, int h) EINA_ARG_NONNULL(1);
/**
* @brief Check if the given rectangles intersect.
*
- * @param r1 The first rectangle.
- * @param r2 The second rectangle.
- * @return #EINA_TRUE if the rectangles intersect, #EINA_FALSE otherwise.
+ * @details This function returns #EINA_TRUE if @p r1 and @p r2 intersect, #EINA_FALSE
+ * otherwise. No check is done on @p r1 and @p r2, so they must be valid
+ * rectangles.
*
- * This function returns #EINA_TRUE if @p r1 and @p r2 intersect, #EINA_FALSE
- * otherwise. No check is done on @p r1 and @p r2, so they must be valid
- * rectangles.
+ * @since_tizen 2.3
+ *
+ * @param[in] r1 The first rectangle.
+ * @param[in] r2 The second rectangle.
+ * @return #EINA_TRUE if the rectangles intersect, #EINA_FALSE otherwise.
*/
static inline Eina_Bool eina_rectangles_intersect(const Eina_Rectangle *r1, const Eina_Rectangle *r2) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT;
/**
* @brief Check if the given x-coordinate is in the rectangle .
*
- * @param r The rectangle.
- * @param x The x coordinate.
- * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
+ * @details This function returns #EINA_TRUE if @p x is in @p r with respect to
+ * the horizontal direction, #EINA_FALSE otherwise. No check is done
+ * on @p r, so it must be a valid rectangle.
*
- * This function returns #EINA_TRUE if @p x is in @p r with respect to
- * the horizontal direction, #EINA_FALSE otherwise. No check is done
- * on @p r, so it must be a valid rectangle.
+ * @since_tizen 2.3
+ *
+ * @param[in] r The rectangle.
+ * @param[in] x The x coordinate.
+ * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*/
static inline Eina_Bool eina_rectangle_xcoord_inside(const Eina_Rectangle *r, int x) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
/**
* @brief Check if the given y-coordinate is in the rectangle .
*
- * @param r The rectangle.
- * @param y The y coordinate.
- * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
+ * @details This function returns #EINA_TRUE if @p y is in @p r with respect to
+ * the vertical direction, #EINA_FALSE otherwise. No check is done
+ * on @p r, so it must be a valid rectangle.
*
- * This function returns #EINA_TRUE if @p y is in @p r with respect to
- * the vertical direction, #EINA_FALSE otherwise. No check is done
- * on @p r, so it must be a valid rectangle.
+ * @since_tizen 2.3
+ *
+ * @param[in] r The rectangle.
+ * @param[in] y The y coordinate.
+ * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*/
static inline Eina_Bool eina_rectangle_ycoord_inside(const Eina_Rectangle *r, int y) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
/**
* @brief Check if the given point is in the rectangle .
*
- * @param r The rectangle.
- * @param x The x coordinate of the point.
- * @param y The y coordinate of the point.
- * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
+ * @details This function returns #EINA_TRUE if the point of coordinate (@p x,
+ * @p y) is in @p r, #EINA_FALSE otherwise. No check is done on @p r,
+ * so it must be a valid rectangle.
+ *
+ * @since_tizen 2.3
*
- * This function returns #EINA_TRUE if the point of coordinate (@p x,
- * @p y) is in @p r, #EINA_FALSE otherwise. No check is done on @p r,
- * so it must be a valid rectangle.
+ * @param[in] r The rectangle.
+ * @param[in] x The x coordinate of the point.
+ * @param[in] y The y coordinate of the point.
+ * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
*/
static inline Eina_Bool eina_rectangle_coords_inside(const Eina_Rectangle *r, int x, int y) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
/**
* @brief Get the union of two rectangles.
*
- * @param dst The first rectangle.
- * @param src The second rectangle.
+ * @details This function get the union of the rectangles @p dst and @p src. The
+ * result is stored in @p dst. No check is done on @p dst or @p src,
+ * so they must be valid rectangles.
+ *
+ * @since_tizen 2.3
*
- * This function get the union of the rectangles @p dst and @p src. The
- * result is stored in @p dst. No check is done on @p dst or @p src,
- * so they must be valid rectangles.
+ * @param[in] dst The first rectangle.
+ * @param[in] src The second rectangle.
*/
static inline void eina_rectangle_union(Eina_Rectangle *dst, const Eina_Rectangle *src) EINA_ARG_NONNULL(1, 2);
/**
* @brief Get the intersection of two rectangles.
*
- * @param dst The first rectangle.
- * @param src The second rectangle.
+ * @details This function get the intersection of the rectangles @p dst and
+ * @p src. The result is stored in @p dst. No check is done on @p dst
+ * or @p src, so they must be valid rectangles.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] dst The first rectangle.
+ * @param[in] src The second rectangle.
* @return #EINA_TRUE if the rectangles intersect, #EINA_FALSE
* otherwise.
- *
- * This function get the intersection of the rectangles @p dst and
- * @p src. The result is stored in @p dst. No check is done on @p dst
- * or @p src, so they must be valid rectangles.
*/
static inline Eina_Bool eina_rectangle_intersection(Eina_Rectangle *dst, const Eina_Rectangle *src) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT;
/**
- * @brief FIXME I am useless and used by no one
+ * @brief Rescale a rectangle inner position.
+ *
+ * @details This function rescales a rectangle by using @p out and @p in.
*
- * @param in The inner rectangle.
- * @param out The outer rectangle.
- * @param res The resulting rectangle.
+ * @since_tizen 2.3
*
+ * @param[in] out The outter rectangle.
+ * @param[in] in The inner rectangle.
+ * @param[in] res The rectangle to be rescaled
*/
static inline void eina_rectangle_rescale_in(const Eina_Rectangle *out, const Eina_Rectangle *in, Eina_Rectangle *res) EINA_ARG_NONNULL(1, 2, 3);
/**
- * @brief FIXME I am useless and used by no one
+ * @brief Rescale a rectangle outter position.
*
- * @param in The inner rectangle.
- * @param out The outer rectangle.
- * @param res The resulting rectangle.
+ * @details This function rescales a rectangle by using @p out and @p in.
*
+ * @since_tizen 2.3
+ *
+ * @param[in] out The outter rectangle.
+ * @param[in] in The inner rectangle.
+ * @param[in] res The rectangle to be rescaled
*/
static inline void eina_rectangle_rescale_out(const Eina_Rectangle *out, const Eina_Rectangle *in, Eina_Rectangle *res) EINA_ARG_NONNULL(1, 2, 3);
-/**
- *
- * @brief Tells whether a rectangle is valid or not.
- *
- * @param r The rectangle
- * @return #EINA_TRUE if the rectangle is valid, #EINA_FALSE otherwise.
- *
- * This function checks if both width and height attributes of the rectangle are
- * positive integers. If so, the rectangle is considered valid, else the
- * rectangle is invalid.
- */
-static inline Eina_Bool eina_rectangle_is_valid(const Eina_Rectangle *r) EINA_ARG_NONNULL(1);
/**
+ * @brief Adds a rectangle in a new pool.
*
- * @brief Gives the rectangle maximum x coordinate.
- *
- * @param thiz The rectangle
- * @return the maximum x coordinate
- *
- * This function calculates the maximum x coordinate of the rectangle by summing
- * the @p width with the current @p x coodinate of the rectangle.
- */
-static inline int eina_rectangle_max_x(Eina_Rectangle *thiz) EINA_ARG_NONNULL(1);
-
-/**
+ * @details This function adds the rectangle of size (@a width, @a height) to a
+ * new pool. If the pool cannot be created, @c NULL is
+ * returned. Otherwise the newly allocated pool is returned.
*
- * @brief Gives the rectangle maximum y coordinate.
+ * @since_tizen 2.3
*
- * @param thiz The rectangle
- * @return the maximum y coordinate
+ * @param[in] w The width of the rectangle
+ * @param[in] h The height of the rectangle
+ * @return A newly allocated pool on success, otherwise @c NULL
*
- * This function calculates the maximum y coordinate of the rectangle by summing
- * the @p height with the current @p y coodinate of the rectangle.
*/
-static inline int eina_rectangle_max_y(Eina_Rectangle *thiz) EINA_ARG_NONNULL(1);
+EAPI Eina_Rectangle_Pool *eina_rectangle_pool_new(int w, int h) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
/**
+ * @brief Gets the pool of the given rectangle.
*
- * @brief Slices a rectangle vertically into two subrectangles starting from left edge
+ * @details This function returns the pool in which @a rect is present. If @a rect is
+ * @c NULL, @c NULL is returned.
*
- * @param thiz The rectangle to slice
- * @param slice The sliced part of the rectangle
- * @param remainder The left over part of the original rectangle after slice
- * @param amount The x inner coordinate of the rectangle where to perform the
- * slicing.
- * @return #EINA_TRUE if the cut succeeds, #EINA_FALSE otherwise
+ * @since_tizen 2.3
*
- * Use this function if we must cut a rectangle vertically. The @p amount
- * parameter defines the x inner coordinate where to do the cut, starting from
- * the left edge of the rectangle. If the @p amount value is greater than the
- * rectangle width, there will be not cut possible and #EINA_FALSE will be
- * returned.
- */
-static inline Eina_Bool eina_rectangle_x_cut(Eina_Rectangle *thiz, Eina_Rectangle *slice, Eina_Rectangle *remainder, int amount) EINA_ARG_NONNULL(1);
-
-/**
+ * @param[in] rect The rectangle
+ * @return The pool of the given rectangle
*
- * @brief Slices a rectangle horizontally into two subrectangles starting from bottom edge
- *
- * @param thiz The rectangle to slice
- * @param slice The sliced part of the rectangle
- * @param remainder The left over part of the original rectangle after slice
- * @param amount The y inner coordinate of the rectangle where to perform the
- * slicing.
- * @return #EINA_TRUE if the cut succeeds, #EINA_FALSE otherwise
- *
- * Use this function if we must cut a rectangle horizontally. The @p amount
- * parameter defines the y inner coordinate where to do the cut, starting from
- * the bottom edge of the rectangle. If the @p amount value is greater than the
- * rectangle width, there will be not cut possible and #EINA_FALSE will be
- * returned.
*/
-static inline Eina_Bool eina_rectangle_y_cut(Eina_Rectangle *thiz, Eina_Rectangle *slice, Eina_Rectangle *remainder, int amount) EINA_ARG_NONNULL(1);
+EAPI Eina_Rectangle_Pool *eina_rectangle_pool_get(Eina_Rectangle *rect) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
/**
+ * @brief Gets the width and height of the given pool.
+ *
+ * @details This function returns the width and height of @a pool and stores
+ * them in @a w and @a h respectively if they are not @c NULL. If
+ * @a pool is @c NULL, @c EINA_FALSE is returned. Otherwise @c EINA_TRUE is
+ * returned.
*
- * @brief Slices a rectangle vertically starting from right edge
+ * @since_tizen 2.3
*
- * @param thiz The rectangle to slice
- * @param slice The sliced part of the rectangle
- * @param remainder The left over part of the original rectangle after slice
- * @param amount The amount to cut off the rectangle starting from the right
- * edge
- * @return #EINA_TRUE if the cut succeeds, #EINA_FALSE otherwise
+ * @param[in] pool The pool
+ * @param[out] w The returned width
+ * @param[out] h The returned height
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE
*
- * Use this function if we must cut a rectangle vertically. The @p amount
- * parameter defines the inner x coordinate where to do the cut, starting from
- * the right edge of the rectangle. If the @p amount value is greater than the
- * rectangle width, there will be not cut possible and #EINA_FALSE will be
- * returned.
*/
-static inline Eina_Bool eina_rectangle_width_cut(Eina_Rectangle *thiz, Eina_Rectangle *slice, Eina_Rectangle *remainder, int amount) EINA_ARG_NONNULL(1);
+EAPI Eina_Bool eina_rectangle_pool_geometry_get(Eina_Rectangle_Pool *pool, int *w, int *h) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
/**
+ * @brief Gets the data from the given pool.
+ *
+ * @details This function gets the data from @a pool set by
+ * eina_rectangle_pool_data_set(). If @a pool is @c NULL, this
+ * function returns @c NULL.
*
- * @brief Slices a rectangle horizontally starting from top edge
+ * @since_tizen 2.3
*
- * @param thiz The rectangle to slice
- * @param slice The sliced part of the rectangle
- * @param remainder The left over part of the original rectangle after slice
- * @param amount The amount to cut off the rectangle starting from the top edge
- * @return #EINA_TRUE if the cut succeeds, #EINA_FALSE otherwise
+ * @param[in] pool The pool
+ * @return The returned data
*
- * Use this function if we must cut a rectangle horizontally. The @p amount
- * parameter defines the inner y coordinate where to do the cut, starting from
- * the top edge of the rectangle. If the @p amount value is greater than the
- * rectangle width, there will be not cut possible and #EINA_FALSE will be
- * returned.
*/
-static inline Eina_Bool eina_rectangle_height_cut(Eina_Rectangle *thiz, Eina_Rectangle *slice, Eina_Rectangle *remainder, int amount) EINA_ARG_NONNULL(1);
+EAPI void *eina_rectangle_pool_data_get(Eina_Rectangle_Pool *pool) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
/**
- * @brief Subtract two rectangles.
+ * @brief Sets the data to the given pool.
*
- * @param thiz The minuend rectangle
- * @param other The subtrahend rectangle
+ * @details This function sets @a data to @a pool. If @a pool is @c NULL, this
+ * function does nothing.
*
- * This function subtract two rectangles. The difference is stored on @p out
- * There will be at most four differences, use eina_rectangle_is_valid to
- * confirm the number of differences.
- */
-static inline Eina_Bool eina_rectangle_subtract(Eina_Rectangle *thiz, Eina_Rectangle *other, Eina_Rectangle out[4]) EINA_ARG_NONNULL(1);
-
-/**
- * @brief Add a rectangle in a new pool.
+ * @since_tizen 2.3
*
- * @param w The width of the rectangle.
- * @param h The height of the rectangle.
- * @return A newly allocated pool on success, @c NULL otherwise.
+ * @param[in] pool The pool
+ * @param[in] data The data to set
*
- * This function adds the rectangle of size (@p width, @p height) to a
- * new pool. If the pool can not be created, @c NULL is
- * returned. Otherwise the newly allocated pool is returned.
*/
-EAPI Eina_Rectangle_Pool *eina_rectangle_pool_new(int w, int h) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
+EAPI void eina_rectangle_pool_data_set(Eina_Rectangle_Pool *pool, const void *data) EINA_ARG_NONNULL(1);
/**
- * @brief Return the pool of the given rectangle.
+ * @brief Frees the given pool.
*
- * @param rect The rectangle.
- * @return The pool of the given rectangle.
+ * @details This function frees the allocated data of @a pool. If @a pool is
+ * @c NULL, this function returns immediately.
*
- * This function returns the pool in which @p rect is. If @p rect is
- * @c NULL, @c NULL is returned.
- */
-EAPI Eina_Rectangle_Pool *eina_rectangle_pool_get(Eina_Rectangle *rect) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
-
-/**
- * @brief Return the width and height of the given pool.
+ * @since_tizen 2.3
*
- * @param pool The pool.
- * @param w The returned width.
- * @param h The returned height.
- * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
+ * @param[in] pool The pool to free
*
- * This function returns the width and height of @p pool and store
- * them in respectively @p w and @p h if they are not @c NULL. If
- * @p pool is @c NULL, #EINA_FALSE is returned. Otherwise #EINA_TRUE is
- * returned.
*/
-EAPI Eina_Bool eina_rectangle_pool_geometry_get(Eina_Rectangle_Pool *pool, int *w, int *h) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
+EAPI void eina_rectangle_pool_free(Eina_Rectangle_Pool *pool) EINA_ARG_NONNULL(1);
/**
- * @brief Get the data from the given pool.
+ * @brief Returns the number of rectangles in the given pool.
*
- * @param pool The pool.
- * @return The returned data.
+ * @details This function returns the number of rectangles in @a pool.
*
- * This function gets the data from @p pool set by
- * eina_rectangle_pool_data_set(). If @p pool is @c NULL, this
- * function returns @c NULL.
- */
-EAPI void *eina_rectangle_pool_data_get(Eina_Rectangle_Pool *pool) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
-
-/**
- * @brief Set the data to the given pool.
+ * @since_tizen 2.3
*
- * @param pool The pool.
- * @param data The data to set.
+ * @param[in] pool The pool
+ * @return The number of rectangles in the pool
*
- * This function sets @p data to @p pool. If @p pool is @c NULL, this
- * function does nothing.
*/
-EAPI void eina_rectangle_pool_data_set(Eina_Rectangle_Pool *pool, const void *data) EINA_ARG_NONNULL(1);
+EAPI int eina_rectangle_pool_count(Eina_Rectangle_Pool *pool) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
/**
- * @brief Free the given pool.
+ * @brief Requests for a rectangle of the given size in the given pool.
*
- * @param pool The pool to free.
+ * @details This function retrieves from @a pool the rectangle of width @a w and
+ * height @a h. If @a pool is @c NULL, or @a w or @a h are non-positive,
+ * the function returns @c NULL. If @a w or @a h are greater than the
+ * pool size, the function returns @c NULL. On success, the function
+ * returns the rectangle that matches the size (@a w, @a h).
+ * Otherwise it returns @c NULL.
*
- * This function frees the allocated data of @p pool. If @p pool is
- * @c NULL, this function returned immediately.
- */
-EAPI void eina_rectangle_pool_free(Eina_Rectangle_Pool *pool) EINA_ARG_NONNULL(1);
-
-/**
- * @brief Return the number of rectangles in the given pool.
+ * @since_tizen 2.3
*
- * @param pool The pool.
- * @return The number of rectangles in the pool.
+ * @param[in] pool The pool
+ * @param[in] w The width of the rectangle to request for
+ * @param[in] h The height of the rectangle to request for
+ * @return The requested rectangle on success, otherwise @c NULL
*
- * This function returns the number of rectangles in @p pool.
- */
-EAPI int eina_rectangle_pool_count(Eina_Rectangle_Pool *pool) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
-
-/**
- * @brief Request a rectangle of given size in the given pool.
- *
- * @param pool The pool.
- * @param w The width of the rectangle to request.
- * @param h The height of the rectangle to request.
- * @return The requested rectangle on success, @c NULL otherwise.
- *
- * This function retrieve from @p pool the rectangle of width @p w and
- * height @p h. If @p pool is @c NULL, or @p w or @p h are non-positive,
- * the function returns @c NULL. If @p w or @p h are greater than the
- * pool size, the function returns @c NULL. On success, the function
- * returns the rectangle which matches the size (@p w, @p h).
- * Otherwise it returns @c NULL.
*/
EAPI Eina_Rectangle *eina_rectangle_pool_request(Eina_Rectangle_Pool *pool, int w, int h) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
/**
- * @brief Remove the given rectangle from the pool.
+ * @brief Removes the given rectangle from the pool.
+ *
+ * @details This function removes @a rect from the pool. If @a rect is
+ * @c NULL, the function returns immediately. Otherwise it removes
+ * @a rect from the pool.
+ *
+ * @since_tizen 2.3
*
- * @param rect The rectangle to remove from the pool.
+ * @param[in] rect The rectangle to remove from the pool
*
- * This function removes @p rect from the pool. If @p rect is
- * @c NULL, the function returns immediately. Otherwise it removes @p
- * rect from the pool.
*/
EAPI void eina_rectangle_pool_release(Eina_Rectangle *rect) EINA_ARG_NONNULL(1);
/**
* @def EINA_RECTANGLE_SET
- * @brief Macro to set the values of a #Eina_Rectangle.
+ * @brief Provides a macro to set the values of a #Eina_Rectangle.
*
- * @param Rectangle The rectangle to set the values.
- * @param X The X coordinate of the top left corner of the rectangle.
- * @param Y The Y coordinate of the top left corner of the rectangle.
- * @param W The width of the rectangle.
- * @param H The height of the rectangle.
+ * @details This macro sets the values of @a Rectangle. (@a X, @a Y) are the
+ * coordinates of the top left corner of @a Rectangle, @a W is its
+ * width and @a H is its height.
+ *
+ * @since_tizen 2.3
+ *
+ * @param Rectangle The rectangle to set the values of
+ * @param X The X coordinate of the top left corner of the rectangle
+ * @param Y The Y coordinate of the top left corner of the rectangle
+ * @param W The width of the rectangle
+ * @param H The height of the rectangle
*
- * This macro set the values of @p Rectangle. (@p X, @p Y) is the
- * coordinates of the top left corner of @p Rectangle, @p W is its
- * width and @p H is its height.
*/
#define EINA_RECTANGLE_SET(Rectangle, X, Y, W, H) \
- { \
- (Rectangle)->x = X; \
- (Rectangle)->y = Y; \
- (Rectangle)->w = W; \
- (Rectangle)->h = H; \
- }
+ (Rectangle)->x = X; \
+ (Rectangle)->y = Y; \
+ (Rectangle)->w = W; \
+ (Rectangle)->h = H;
/**
- * @brief Create a new rectangle.
- *
- * @param x The X coordinate of the top left corner of the rectangle.
- * @param y The Y coordinate of the top left corner of the rectangle.
- * @param w The width of the rectangle.
- * @param h The height of the rectangle.
- * @return The new rectangle on success, @ NULL otherwise.
- *
- * This function creates a rectangle which top left corner has the
- * coordinates (@p x, @p y), with height @p w and height @p h and adds
- * it to the rectangles pool. No check is done on @p w and @p h. This
- * function returns a new rectangle on success, @c NULL otherwhise.
+ * @brief Creates a new rectangle.
+ *
+ * @details This function creates a rectangle whose top left corner has the
+ * coordinates (@a x, @a y), with width @a w and height @a h and adds
+ * it to the rectangle's pool. No check is done on @a w and @a h. This
+ * function returns a new rectangle on success, otherwise it returns @c NULL.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] x The X coordinate of the top left corner of the rectangle
+ * @param[in] y The Y coordinate of the top left corner of the rectangle
+ * @param[in] w The width of the rectangle
+ * @param[in] h The height of the rectangle
+ * @return The new rectangle on success, otherwise @c NULL
+ *
*/
EAPI Eina_Rectangle *eina_rectangle_new(int x, int y, int w, int h) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
/**
- * @brief Free the given rectangle.
+ * @brief Frees the given rectangle.
*
- * @param rect The rectangle to free.
+ * @details This function removes @a rect from the rectangles pool.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] rect The rectangle to free
*
- * This function removes @p rect from the rectangles pool.
*/
EAPI void eina_rectangle_free(Eina_Rectangle *rect) EINA_ARG_NONNULL(1);
/**
- * @brief Sets the type of given rectangle pool.
+ * @brief Sets the type of the given rectangle pool.
+ *
+ * @details This function sets @a type of @a pool.
*
- * @param pool The rectangle pool for which type is to be set.
+ * @since 1.10
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] pool The rectangle pool type to set
+ * @param[in] type The packing type to set
*
- * This function sets @p type of @p pool.
* @see Eina_Rectangle_Packing
- * @since 1.11
*/
-EAPI void eina_rectangle_pool_packing_set(Eina_Rectangle_Pool *pool,Eina_Rectangle_Packing type) EINA_ARG_NONNULL(1);
+EAPI void eina_rectangle_pool_packing_set(Eina_Rectangle_Pool *pool, Eina_Rectangle_Packing type) EINA_ARG_NONNULL(1);
#include "eina_inline_rectangle.x"
@@ -513,8 +440,4 @@ EAPI void eina_rectangle_pool_packing_set(Eina_Rectangle_Pool *pool,E
* @}
*/
-/**
- * @}
- */
-
#endif /*_EINA_RECTANGLE_H_*/
diff --git a/src/lib/eina/eina_refcount.h b/src/lib/eina/eina_refcount.h
index 6650b01680..775ed2327b 100644
--- a/src/lib/eina/eina_refcount.h
+++ b/src/lib/eina/eina_refcount.h
@@ -1,14 +1,14 @@
/* EINA - EFL data type library
* Copyright (C) 20011 Cedric Bail
*
- * This library is free software; you can redistribute it and/or
+ * This library is a free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
@@ -20,57 +20,45 @@
#define EINA_REFCOUNT_H_
/**
- * @addtogroup Eina_Refcount References counting
+ * @internal
+ * @defgroup Eina_Refcount References counting
+ * @ingroup Eina_Data_Types_Group
*
- * @brief Small macro that simplify references counting.
+ * @brief This group discusses the functions of the small macro that simplifies references counting.
*
* References counting is not a difficult task, but you must
- * handle it correctly every where, and that the issue. This
- * set of macro do provide helper that will force to use the
- * correct code in most case and reduce the bug likeliness.
- * Of course this without affecting speed !
- */
-
-/**
- * @addtogroup Eina_Data_Types_Group Data Types
- *
- * @{
- */
-
-/**
- * @defgroup Eina_Refcount References counting
+ * handle it correctly every where, and that is the issue. This
+ * set of macros do provide a helper that forces to use the
+ * correct code in most cases and reduces the likeliness of a bug.
+ * Of course, this is achieved without affecting the speed.
*
* @{
*/
/**
* @typedef Eina_Refcount
- * Inlined references counting type.
+ * @brief The integer type containing inlined references counting type.
*/
typedef int Eina_Refcount;
-/** Used for declaring a reference counting member in a struct */
+/** The definition used for declaring a reference counting member in a struct */
#define EINA_REFCOUNT Eina_Refcount __refcount
-/** Used just after allocating a object */
+/** The definition used just after allocating an object */
#define EINA_REFCOUNT_INIT(Variable) (Variable)->__refcount = 1
-/** Used when using referring to an object one more time */
+/** The definition used when referring to an object one more time */
#define EINA_REFCOUNT_REF(Variable) (Variable)->__refcount++
-/** Used when removing a reference to an object. The code just after will automatically be called when necessary */
+/** The definition used when removing a reference to an object. The code just after this is automatically called when necessary */
#define EINA_REFCOUNT_UNREF(Variable) \
if (--((Variable)->__refcount) == 0)
-/** Get refcounting value */
+/** The definition to get the reference counting value */
#define EINA_REFCOUNT_GET(Variable) (Variable)->__refcount
/**
* @}
*/
-/**
- * @}
- */
-
#endif /* EINA_REFCOUNT_H_ */
diff --git a/src/lib/eina/eina_safety_checks.h b/src/lib/eina/eina_safety_checks.h
index d9c22d9ea0..356007c983 100644
--- a/src/lib/eina/eina_safety_checks.h
+++ b/src/lib/eina/eina_safety_checks.h
@@ -20,13 +20,9 @@
#define EINA_SAFETY_CHECKS_H_
/**
- * @addtogroup Eina_Tools_Group Tools
- *
- * @{
- */
-
-/**
+ * @internal
* @defgroup Eina_Safety_Checks_Group Safety Checks
+ * @ingroup Eina_Tools_Group
*
* @warning @c eina_safety_checks.h should only be included by source
* files, after all other includes and before the source file
@@ -50,6 +46,7 @@
* // all these files will emit warning from EINA_ARG_NONNULL()
* #include <Evas.h> // third party headers
* #include <Ecore.h>
+ * #include <eina_error.h> // eina own header
*
* #include <eina_safety_checks.h>
* // all these files below will NOT emit warning from EINA_ARG_NONNULL(),
@@ -59,10 +56,6 @@
* #include "my_functions2.h"
*
* @endcode
- */
-
-/**
- * @addtogroup Eina_Safety_Checks_Group Safety Checks
*
* Safety checks are a set of macros to check for parameters or values
* that should never happen, it is similar in concept to assert(), but
@@ -76,8 +69,9 @@
* options to @c configure script.
*
* Whenever these macros capture an error, EINA_LOG_ERR() will be
- * called.
- *
+ * called and @c eina_error set to @c EINA_ERROR_SAFETY_FAILED and can
+ * be checked with eina_error_get() after call.
+ *
* @see EINA_SAFETY_ON_NULL_RETURN(), EINA_SAFETY_ON_NULL_RETURN_VAL()
* and other macros.
*
@@ -87,6 +81,10 @@
#include "eina_config.h"
#include "eina_error.h"
+/**
+ * @var EINA_ERROR_SAFETY_FAILED
+ * Error identifier corresponding to safety check failure.
+ */
EAPI extern Eina_Error EINA_ERROR_SAFETY_FAILED;
#ifdef EINA_SAFETY_CHECKS
@@ -98,6 +96,7 @@ EAPI extern Eina_Error EINA_ERROR_SAFETY_FAILED;
{ \
if (EINA_UNLIKELY((exp) == NULL)) \
{ \
+ eina_error_set(EINA_ERROR_SAFETY_FAILED); \
EINA_LOG_ERR("%s", "safety check failed: " # exp " == NULL"); \
return; \
} \
@@ -109,6 +108,7 @@ EAPI extern Eina_Error EINA_ERROR_SAFETY_FAILED;
{ \
if (EINA_UNLIKELY((exp) == NULL)) \
{ \
+ eina_error_set(EINA_ERROR_SAFETY_FAILED); \
EINA_LOG_ERR("%s", "safety check failed: " # exp " == NULL"); \
return (val); \
} \
@@ -120,6 +120,7 @@ EAPI extern Eina_Error EINA_ERROR_SAFETY_FAILED;
{ \
if (EINA_UNLIKELY((exp) == NULL)) \
{ \
+ eina_error_set(EINA_ERROR_SAFETY_FAILED); \
EINA_LOG_ERR("%s", "safety check failed: " # exp " == NULL"); \
goto label; \
} \
@@ -131,6 +132,7 @@ EAPI extern Eina_Error EINA_ERROR_SAFETY_FAILED;
{ \
if (EINA_UNLIKELY(exp)) \
{ \
+ eina_error_set(EINA_ERROR_SAFETY_FAILED); \
EINA_LOG_ERR("%s", "safety check failed: " # exp " is true"); \
return; \
} \
@@ -142,6 +144,7 @@ EAPI extern Eina_Error EINA_ERROR_SAFETY_FAILED;
{ \
if (EINA_UNLIKELY(exp)) \
{ \
+ eina_error_set(EINA_ERROR_SAFETY_FAILED); \
EINA_LOG_ERR("%s", "safety check failed: " # exp " is true"); \
return val; \
} \
@@ -153,6 +156,7 @@ EAPI extern Eina_Error EINA_ERROR_SAFETY_FAILED;
{ \
if (EINA_UNLIKELY(exp)) \
{ \
+ eina_error_set(EINA_ERROR_SAFETY_FAILED); \
EINA_LOG_ERR("%s", "safety check failed: " # exp " is true"); \
goto label; \
} \
@@ -164,6 +168,7 @@ EAPI extern Eina_Error EINA_ERROR_SAFETY_FAILED;
{ \
if (EINA_UNLIKELY(!(exp))) \
{ \
+ eina_error_set(EINA_ERROR_SAFETY_FAILED); \
EINA_LOG_ERR("%s", "safety check failed: " # exp " is false"); \
return; \
} \
@@ -175,6 +180,7 @@ EAPI extern Eina_Error EINA_ERROR_SAFETY_FAILED;
{ \
if (EINA_UNLIKELY(!(exp))) \
{ \
+ eina_error_set(EINA_ERROR_SAFETY_FAILED); \
EINA_LOG_ERR("%s", "safety check failed: " # exp " is false"); \
return val; \
} \
@@ -186,6 +192,7 @@ EAPI extern Eina_Error EINA_ERROR_SAFETY_FAILED;
{ \
if (EINA_UNLIKELY(!(exp))) \
{ \
+ eina_error_set(EINA_ERROR_SAFETY_FAILED); \
EINA_LOG_ERR("%s", "safety check failed: " # exp " is false"); \
goto label; \
} \
@@ -276,7 +283,3 @@ EAPI extern Eina_Error EINA_ERROR_SAFETY_FAILED;
/**
* @}
*/
-
-/**
- * @}
- */
diff --git a/src/lib/eina/eina_sched.h b/src/lib/eina/eina_sched.h
index 13f35a4476..6832cef8cd 100644
--- a/src/lib/eina/eina_sched.h
+++ b/src/lib/eina/eina_sched.h
@@ -1,14 +1,14 @@
/* EINA - EFL data type library
* Copyright (C) 2010 ProFUSION embedded systems
*
- * This library is free software; you can redistribute it and/or
+ * This library is a free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
@@ -17,8 +17,9 @@
*/
/**
+ * @internal
* @defgroup Schedule Schedule
- * @ingroup Eina_Tools_Group
+ * @ingroup Eina_Core_Group
*
* @{
*
@@ -43,6 +44,9 @@
* set the nice level on the current thread. In Linux, it does work and it's the
* only one that is implemented as of now. In this case, the nice level is
* incremented on this thread by @c NICENESS.
+ *
+ * @since_tizen 2.3
+ *
*/
EAPI void eina_sched_prio_drop(void);
diff --git a/src/lib/eina/eina_simple_xml_parser.h b/src/lib/eina/eina_simple_xml_parser.h
index 8f83c1e01a..bd3730b38c 100644
--- a/src/lib/eina/eina_simple_xml_parser.h
+++ b/src/lib/eina/eina_simple_xml_parser.h
@@ -2,14 +2,14 @@
* Copyright (C) 2011 Gustavo Sverzut Barbieri
* Cedric Bail
*
- * This library is free software; you can redistribute it and/or
+ * This library is a free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
@@ -27,115 +27,29 @@
#include "eina_inlist.h"
/**
- * @page eina_simple_xml_parser_example_01_page
- * @dontinclude eina_simple_xml_parser_01.c
- *
- * We are going to parse an XML sample file and print the data to stdout.
- *
- * Like all examples we start by including Eina:
- * @skipline #include
- *
- * We declare 2 booleans to keep track of tags:
- * @skipline tag_login
- * @skipline tag_message
- *
- * Here we declare some variables and initialize eina:
- * @until eina_init
- *
- * We fill buffer with the XML data from chat.xml:
- * @until fread
- *
- * We will use an Eina_Array to store the data:
- * @skipline array
- *
- * Here we call eina_simple_xml_parse(). We pass the buffer with data, its size,
- * we ask to strip leading and trailing whitespace, we give the callback
- * function and the array to store the formatted data:
- * @until _xml_tag_cb
- *
- * This will loop over the array and print the data using _print callback:
- * @skipline foreach
- *
- * This is the main XML parser callback, it will check for known tags and get
- * the corresponding values:
- * @skip static
- * @until str
- *
- * We first check for opening tag:
- * @skipline type
- *
- * If we know the tag should have attributes, then we find them using
- * eina_simple_xml_tag_attributes_find() and give them to another parsing
- * function using eina_simple_xml_attributes_parse():
- * @until _xml_attr_cb
- *
- * We check for other known tags:
- * @until tag_message
- *
- * We then check data for corresponding tag:
- * @until EINA_FALSE
- *
- * We are doing the formatting in same time and put all the \<post\> children
- * in str.
- * @until EINA_FALSE
- *
- * Finally, we store our string in the array:
- * @skipline push
- *
- * This is the callback to parse the attributes, we check for key name and keep
- * the value:
- * @skip static
- * @until snprintf
- *
- * This is the function that simply print items of the array:
- * @until EINA_TRUE
- *
- * You can see the full source code
- * @ref eina_simple_xml_parser_example_01 "here".
- */
-
-/**
- * @page eina_simple_xml_parser_example_01
- * @include eina_simple_xml_parser_01.c
- * @example eina_simple_xml_parser_01.c
- */
-
-/**
* @defgroup Eina_Simple_XML_Group Simple_XML
+ * @ingroup Eina_Tools_Group
*
- * Simplistic relaxed SAX-like XML parser.
+ * @brief This is a simplistic relaxed SAX-like XML parser.
*
- * This parser is far from being compliant with XML standard, but will
- * do for most XMLs out there. If you know that your format is simple
- * and will not vary in future with strange corner cases, then you can
+ * This parser is far from being compliant with XML standards, but
+ * works for most XMLs out there. If you know that your format is simple
+ * and won't vary in the future with strange corner cases, then you can
* use it safely.
*
- * The parser is SAX like, that is, it will tokenize contents and call
- * you back so you can take some action. No contents are allocated
+ * The parser is SAX like, that is, it tokenizes content and calls
+ * you back so that you can take some action. No content is allocated
* during this parser work and it's not recursive, so you can use it
- * with a very large document without worries.
+ * with a very large document without any issues.
*
- * It will not validate the document anyhow, neither it will create a
+ * It does not validate the document anyhow, neither does it create a
* tree hierarchy. That's up to you.
*
* Accordingly to XML, open tags may contain attributes. This parser
- * will not tokenize this. If you want you can use
+ * does not tokenize this. If you want you can use
* eina_simple_xml_tag_attributes_find() and then
* eina_simple_xml_attributes_parse().
*
- * For more information, see
- * @ref eina_simple_xml_parser_example_01_page "this example".
- */
-
-/**
- * @addtogroup Eina_Tools_Group Tools
- *
- * @{
- */
-
-/**
- * @defgroup Eina_Simple_XML_Group Simple_XML
- *
* @{
*/
@@ -160,6 +74,10 @@ struct _Eina_Simple_XML_Attribute
const char *value;
};
+/**
+ * @typedef _Eina_Simple_XML_Node_Type
+ * @brief Enumeration for a simple XML node type.
+ */
typedef enum _Eina_Simple_XML_Node_Type
{
EINA_SIMPLE_XML_NODE_ROOT = 0,
@@ -195,23 +113,24 @@ struct _Eina_Simple_XML_Node_Data
size_t length;
char data[];
};
+
/**
* @typedef _Eina_Simple_XML_Type
- * a simple XML type.
+ * @brief Enumeration for a simple XML type.
*/
typedef enum _Eina_Simple_XML_Type
{
- EINA_SIMPLE_XML_OPEN = 0, /*!< \<tag attribute="value"\> */
- EINA_SIMPLE_XML_OPEN_EMPTY, /*!< \<tag attribute="value" /\> */
- EINA_SIMPLE_XML_CLOSE, /*!< \</tag\> */
- EINA_SIMPLE_XML_DATA, /*!< tag text data */
- EINA_SIMPLE_XML_CDATA, /*!< \<![CDATA[something]]\> */
- EINA_SIMPLE_XML_ERROR, /*!< error contents */
- EINA_SIMPLE_XML_PROCESSING, /*!< \<?xml ... ?\> \<?php .. ?\> */
- EINA_SIMPLE_XML_DOCTYPE, /*!< \<!DOCTYPE html */
- EINA_SIMPLE_XML_COMMENT, /*!< \<!-- something --\> */
- EINA_SIMPLE_XML_IGNORED, /*!< whatever is ignored by parser, like whitespace */
- EINA_SIMPLE_XML_DOCTYPE_CHILD /*!< \<!DOCTYPE_CHILD @since 1.8 */
+ EINA_SIMPLE_XML_OPEN = 0, /**< \<tag attribute="value"\> */
+ EINA_SIMPLE_XML_OPEN_EMPTY, /**< \<tag attribute="value" /\> */
+ EINA_SIMPLE_XML_CLOSE, /**< \</tag\> */
+ EINA_SIMPLE_XML_DATA, /**< tag text data */
+ EINA_SIMPLE_XML_CDATA, /**< \<![CDATA[something]]\> */
+ EINA_SIMPLE_XML_ERROR, /**< Error contents */
+ EINA_SIMPLE_XML_PROCESSING, /**< \<?xml ... ?\> \<?php .. ?\> */
+ EINA_SIMPLE_XML_DOCTYPE, /**< \<!DOCTYPE html */
+ EINA_SIMPLE_XML_COMMENT, /**< \<!-- something --\> */
+ EINA_SIMPLE_XML_IGNORED, /**< Whatever is ignored by the parser, like whitespace */
+ EINA_SIMPLE_XML_DOCTYPE_CHILD /**< \<!DOCTYPE_CHILD @since 1.8 */
} Eina_Simple_XML_Type;
typedef Eina_Bool (*Eina_Simple_XML_Cb)(void *data, Eina_Simple_XML_Type type, const char *content, unsigned offset, unsigned length);
@@ -219,25 +138,28 @@ typedef Eina_Bool (*Eina_Simple_XML_Attribute_Cb)(void *data, const char *key, c
/**
- * Parse a section of XML string text
- *
- * @param buf the input string. May not contain \0 terminator.
- * @param buflen the input string size.
- * @param strip whenever this parser should strip leading and trailing
- * whitespace. These whitespace will still be issued, but as type
- * #EINA_SIMPLE_XML_IGNORED.
- * @param func what to call back while parse to do some action. The
- * first parameter is the given user @a data, the second is the
- * token type, the third is the pointer to content start (it's
- * not a NULL terminated string!), the forth is where this
- * content is located inside @a buf (does not include tag
- * start, for instance "<!DOCTYPE value>" the offset points at
- * "value"), the fifth is the size of the content. Whenever this
- * function return #EINA_FALSE the parser will abort. @param
- * data what to give as context to @a func.
- *
- * @return #EINA_TRUE on success or #EINA_FALSE if it was aborted by user or
- * parsing error.
+ * @brief Parses a section of the XML string text.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] buf The input string \n
+ * May not contain the \0 terminator.
+ * @param[in] buflen The input string size
+ * @param[in] strip The boolean value that indicates when this parser should do strip leading and whitespace trailing \n
+ * This whitespace is still issued, but as type
+ * #EINA_SIMPLE_XML_IGNORED.
+ * @param[in] func The function to call back while parse does some action \n
+ * The first parameter is the given user @a data, the second is the
+ * token type, the third is the pointer to the content's start (it's
+ * not a NULL terminated string), the fourth is where this
+ * content is located, that is @a buf (does not include tag
+ * start, for instance "<!DOCTYPE value>" the offset points at
+ * "value"), the fifth is the size of the content \n
+ * Whenever this function returns @c EINA_FALSE the parser aborts.
+ * @param[in] data The data to give as context to @a func
+ *
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE if it is aborted by the user or a
+ * parsing error occurs
*/
EAPI Eina_Bool eina_simple_xml_parse(const char *buf, unsigned buflen,
Eina_Bool strip,
@@ -245,253 +167,305 @@ EAPI Eina_Bool eina_simple_xml_parse(const char *buf, unsigned buflen,
/**
- * Given the contents of a tag, find where the attributes start.
+ * @brief Finds where the attributes start from given the contents of a tag are provided.
+ *
+ * @since_tizen 2.3
*
- * @param buf the input string. May not contain \0 terminator.
- * @param buflen the input string size.
- * @return pointer to the start of attributes, it can be used
- * to feed eina_simple_xml_attributes_parse(). @c NULL is returned
- * if no attributes were found.
+ * @remarks The tag contents are returned by eina_simple_xml_parse() when
+ * type is #EINA_SIMPLE_XML_OPEN or #EINA_SIMPLE_XML_OPEN_EMPTY.
*
- * The tag contents is returned by eina_simple_xml_parse() when
- * type is #EINA_SIMPLE_XML_OPEN or #EINA_SIMPLE_XML_OPEN_EMPTY.
+ * @param[in] buf The input string \n
+ * May not contain \0 terminator.
+ * @param[in] buflen The input string size
+ * @return A pointer to the start of the attributes, it can be used
+ * to feed eina_simple_xml_attributes_parse() \n
+ * @c NULL is returned if no attributes are found.
*
*/
EAPI const char * eina_simple_xml_tag_attributes_find(const char *buf, unsigned buflen);
/**
- * Given a buffer with xml attributes, parse them to key=value pairs.
- *
- * @param buf the input string. May not contain \0 terminator.
- * @param buflen the input string size.
- * @param func what to call back while parse to do some action. The
- * first parameter is the given user @a data, the second is the
- * key (null-terminated) and the last is the value (null
- * terminated). These strings should not be modified and
- * reference is just valid until the function return.
- * @param data data to pass to the callback function.
- *
- * @return #EINA_TRUE on success or #EINA_FALSE if it was aborted by user or
- * parsing error.
+ * @brief Parses a buffer with XML attributes to key=value pairs.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] buf The input string \n
+ * May not contain \0 terminator.
+ * @param[in] buflen The input string size
+ * @param[in] func The function to call back while parse does some action \n
+ * The first parameter is the given user @a data, the second is the
+ * key (null-terminated) and the last is the value (null
+ * terminated) \n
+ * These strings should not be modified and the
+ * reference is just valid till the function returns
+ * @param[in] data The data to pass to the callback function
+ *
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE if it is aborted by the user or a
+ * parsing error occurs
*/
EAPI Eina_Bool eina_simple_xml_attributes_parse(const char *buf, unsigned buflen,
Eina_Simple_XML_Attribute_Cb func, const void *data);
/**
- * Create (and append) new attribute to tag.
+ * @brief Creates (and appends) a new attribute to the tag.
*
- * @param parent if provided, will be set in the resulting structure
- * as well as the attribute will be appended to attributes list.
- * @param key Null-terminated string. Must not be @c NULL.
- * @param value Null-terminated string. If @c NULL, the empty string will be used.
+ * @since_tizen 2.3
*
- * @return Newly allocated memory or @c NULL on error. This memory should be
- * released with eina_simple_xml_attribute_free() or indirectly
+ * @param[in] parent If provided, this is set in the resulting structure
+ * and the attribute is appended to the attributes list
+ * @param[in] key The null-terminated string \n
+ * Must not be @c NULL.
+ * @param[in] value The null-terminated string \n
+ * If @c NULL, the empty string is used.
+ *
+ * @return The newly allocated memory, otherwise @c NULL on error \n
+ * This memory should be released directly with eina_simple_xml_attribute_free() or indirectly
* with eina_simple_xml_node_tag_free().
*/
EAPI Eina_Simple_XML_Attribute * eina_simple_xml_attribute_new(Eina_Simple_XML_Node_Tag *parent, const char *key, const char *value);
/**
- * Remove attribute from parent and delete it.
+ * @brief Removes an attribute from the parent and deletes it.
+ *
+ * @since_tizen 2.3
*
- * @param attr attribute to release memory.
+ * @param[in] attr The attribute to release memory of
*/
EAPI void eina_simple_xml_attribute_free(Eina_Simple_XML_Attribute *attr);
/**
- * Create new tag. If parent is provided, it is automatically appended.
+ * @brief Creates a new tag. If @a parent is provided, it is automatically appended.
+ *
+ * @since_tizen 2.3
*
- * @param parent if provided, will be set in the resulting structure
- * as well as the tag will be appended to children list.
- * @param name Null-terminated string. Must not be @c NULL.
+ * @param[in] parent If provided, this is set in the resulting structure
+ * and the tag is appended to the children list
+ * @param[in] name The null-terminated string \n
+ * Must not be @c NULL.
*
- * @return Newly allocated memory or @c NULL on error. This memory should be
- * released with eina_simple_xml_node_tag_free() or indirectly
- * with eina_simple_xml_node_tag_free() of the parent.
+ * @return The newly allocated memory, otherwise @c NULL on error \n
+ * This memory of the parent should be released directly with eina_simple_xml_node_tag_free() or indirectly
+ * with eina_simple_xml_node_tag_free().
*/
EAPI Eina_Simple_XML_Node_Tag * eina_simple_xml_node_tag_new(Eina_Simple_XML_Node_Tag *parent, const char *name);
/**
- * Remove tag from parent and delete it.
+ * @brief Removes a tag from the parent and deletes it.
+ *
+ * @since_tizen 2.3
*
- * @param tag to release memory.
+ * @param[in] tag The tag to release memory of
*/
EAPI void eina_simple_xml_node_tag_free(Eina_Simple_XML_Node_Tag *tag);
/**
- * Create new data. If parent is provided, it is automatically appended.
+ * @brief Creates new data. If @a parent is provided, it is automatically appended.
*
- * @param parent if provided, will be set in the resulting structure
- * as well as the data will be appended to children list.
- * @param contents String to be used. Must not be @c NULL.
- * @param length size in bytes of @a contents.
+ * @since_tizen 2.3
*
- * @return Newly allocated memory or NULL on error. This memory should be
- * released with eina_simple_xml_node_data_free() or indirectly
- * with eina_simple_xml_node_tag_free() of the parent.
+ * @param[in] parent If provided, this is set in the resulting structure
+ * and the data is appended to the children list
+ * @param[in] contents The string to be used \n
+ * Must not be @c NULL.
+ * @param[in] length size in bytes of @a contents
+ *
+ * @return The newly allocated memory, otherwise @c NULL on error \n
+ * This memory of the parent should be released directly with eina_simple_xml_node_data_free() or indirectly
+ * with eina_simple_xml_node_tag_free().
*/
EAPI Eina_Simple_XML_Node_Data * eina_simple_xml_node_data_new(Eina_Simple_XML_Node_Tag *parent, const char *contents, size_t length);
/**
- * Remove data from parent and delete it.
+ * @brief Removes data from the parent and deletes it.
+ *
+ * @since_tizen 2.3
*
- * @param node to release memory.
+ * @param[in] node The data to release memory of
*/
EAPI void eina_simple_xml_node_data_free(Eina_Simple_XML_Node_Data *node);
/**
- * Create new cdata. If parent is provided, it is automatically appended.
+ * @brief Creates new cdata. If @a parent is provided, it is automatically appended.
*
- * @param parent if provided, will be set in the resulting structure
- * as well as the cdata will be appended to children list.
- * @param contents String to be used. Must not be @c NULL.
- * @param length size in bytes of @a content.
+ * @since_tizen 2.3
*
- * @return Newly allocated memory or @c NULL on error. This memory should be
- * released with eina_simple_xml_node_cdata_free() or indirectly
- * with eina_simple_xml_node_tag_free() of the parent.
+ * @param[in] parent If provided, this is set in the resulting structure
+ * and the cdata is appended to the children list
+ * @param[in] contents The string to be used \n
+ * Must not be @c NULL.
+ * @param[in] length size in bytes of @a contents
+ *
+ * @return The newly allocated memory, otherwise @c NULL on error \n
+ * This memory of the parent should be released directly with eina_simple_xml_node_cdata_free() or indirectly
+ * with eina_simple_xml_node_tag_free().
*/
EAPI Eina_Simple_XML_Node_CData * eina_simple_xml_node_cdata_new(Eina_Simple_XML_Node_Tag *parent, const char *contents, size_t length);
/**
- * Remove cdata from parent and delete it.
+ * @brief Removes cdata from the parent and deletes it.
*
- * @param node to release memory.
+ * @since_tizen 2.3
+ *
+ * @param[in] node The cdata to release memory of
*/
EAPI void eina_simple_xml_node_cdata_free(Eina_Simple_XML_Node_Data *node);
/**
- * Create new doctype child. If parent is provided, it is automatically appended.
+ * @brief Creates a new doctype child. If @a parent is provided, it is automatically appended.
*
- * @param parent if provided, will be set in the resulting structure
- * as well as the doctype child will be appended to children list.
- * @param contents String to be used. Must not be @c NULL.
- * @param length size in bytes of @a content.
+ * @since 1.8
*
- * @return Newly allocated memory or @c NULL on error. This memory should be
- * released with eina_simple_xml_node_doctype_child_free() or indirectly
- * with eina_simple_xml_node_tag_free() of the parent.
+ * @since_tizen 2.3
+ *
+ * @param[in] parent If provided, this is set in the resulting structure
+ * and the doctype child is appended to the children list
+ * @param[in] contents The string to be used \n
+ * Must not be @c NULL.
+ * @param[in] length size in bytes of @a contents
+ *
+ * @return The newly allocated memory, otherwise @c NULL on error \n
+ * This memory of the parent should be released directly with eina_simple_xml_node_doctype_child_free() or indirectly
+ * with eina_simple_xml_node_tag_free().
*
- * @since 1.8
*/
EAPI Eina_Simple_XML_Node_Doctype_Child * eina_simple_xml_node_doctype_child_new(Eina_Simple_XML_Node_Tag *parent, const char *contents, size_t length);
/**
- * Remove doctype child from parent and delete it.
- *
- * @param node to release memory.
+ * @brief Removes the doctype child from the parent and deletes it.
*
* @since 1.8
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] node The doctype child to release memory of
+ *
*/
EAPI void eina_simple_xml_node_doctype_child_free(Eina_Simple_XML_Node_Data *node);
/**
- * Create new processing. If parent is provided, it is automatically appended.
+ * @brief Creates new processing. If @a parent is provided, it is automatically appended.
+ *
+ * @since_tizen 2.3
*
- * @param parent if provided, will be set in the resulting structure
- * as well as the processing will be appended to children list.
- * @param contents String to be used. Must not be @c NULL.
- * @param length size in bytes of @a contents.
+ * @param[in] parent If provided, this is set in the resulting structure
+ * and the processing is appended to the children list
+ * @param[in] contents The string to be used \n
+ * Must not be @c NULL.
+ * @param[in] length size in bytes of @a contents
*
- * @return Newly allocated memory or @c NULL on error. This memory should be
- * released with eina_simple_xml_node_processing_free() or indirectly
- * with eina_simple_xml_node_tag_free() of the parent.
+ * @return The newly allocated memory, otherwise @c NULL on error \n
+ * This memory of the parent should be released directly with eina_simple_xml_node_processing_free() or indirectly
+ * with eina_simple_xml_node_tag_free().
*/
EAPI Eina_Simple_XML_Node_Processing * eina_simple_xml_node_processing_new(Eina_Simple_XML_Node_Tag *parent, const char *contents, size_t length);
/**
- * Remove processing from parent and delete it.
+ * @brief Removes processing from the parent and deletes it.
*
- * @param node processing to release memory.
+ * @since_tizen 2.3
+ *
+ * @param[in] node The processing to release memory of
*/
EAPI void eina_simple_xml_node_processing_free(Eina_Simple_XML_Node_Data *node);
/**
- * Create new doctype. If parent is provided, it is automatically appended.
+ * @brief Creates a new doctype. If @a parent is provided, it is automatically appended.
+ *
+ * @since_tizen 2.3
*
- * @param parent if provided, will be set in the resulting structure
- * as well as the doctype will be appended to children list.
- * @param contents String to be used. Must not be @c NULL.
- * @param length size in bytes of @a contents.
+ * @param[in] parent If provided, this is set in the resulting structure
+ * and the doctype is appended to the children list
+ * @param[in] contents The string to be used \n
+ * Must not be @c NULL.
+ * @param[in] length size in bytes of @a contents
*
- * @return Newly allocated memory or @c NULL on error. This memory should be
- * released with eina_simple_xml_node_doctype_free() or indirectly
- * with eina_simple_xml_node_tag_free() of the parent.
+ * @return The newly allocated memory, otherwise @c NULL on error \n
+ * This memory of the parent should be released directly with eina_simple_xml_node_doctype_free() or indirectly
+ * with eina_simple_xml_node_tag_free().
*/
EAPI Eina_Simple_XML_Node_Doctype * eina_simple_xml_node_doctype_new(Eina_Simple_XML_Node_Tag *parent, const char *contents, size_t length);
/**
- * Remove doctype from parent and delete it.
+ * @brief Removes the doctype from the parent and deletes it.
+ *
+ * @since_tizen 2.3
*
- * @param node doctype to release memory.
+ * @param[in] node The doctype to release memory of
*/
EAPI void eina_simple_xml_node_doctype_free(Eina_Simple_XML_Node_Data *node);
/**
- * Create new comment. If parent is provided, it is automatically appended.
+ * @brief Creates a new comment. If @a parent is provided, it is automatically appended.
*
- * @param parent if provided, will be set in the resulting structure
- * as well as the comment will be appended to children list.
- * @param contents String to be used. Must not be @c NULL.
- * @param length size in bytes of @a contents.
+ * @since_tizen 2.3
*
- * @return Newly allocated memory or @c NULL on error. This memory should be
- * released with eina_simple_xml_node_comment_free() or indirectly
- * with eina_simple_xml_node_tag_free() of the parent.
+ * @param[in] parent If provided, this is set in the resulting structure
+ * and the comment is appended to the children list
+ * @param[in] contents The string to be used \n
+ * Must not be @c NULL.
+ * @param[in] length size in bytes of @a contents
+ *
+ * @return The newly allocated memory, otherwise @c NULL on error \n
+ * This memory of the parent should be released directly with eina_simple_xml_node_comment_free() or indirectly
+ * with eina_simple_xml_node_tag_free().
*/
EAPI Eina_Simple_XML_Node_Comment * eina_simple_xml_node_comment_new(Eina_Simple_XML_Node_Tag *parent, const char *contents, size_t length);
/**
- * Remove comment from parent and delete it.
+ * @brief Removes a comment from the parent and deletes it.
*
- * @param node comment to release memory.
+ * @since_tizen 2.3
+ *
+ * @param[in] node The comment to release memory of
*/
EAPI void eina_simple_xml_node_comment_free(Eina_Simple_XML_Node_Data *node);
/**
- * Load a XML node tree based on the given string.
+ * @brief Loads an XML node tree based on the given string.
+ *
+ * @since_tizen 2.3
*
- * @param buf the input string. May not contain \0 terminator.
- * @param buflen the input string size.
- * @param strip whenever this parser should strip leading and trailing
- * whitespace.
+ * @param[in] buf The input string \n
+ * May not contain \0 terminator.
+ * @param[in] buflen The input string size
+ * @param[in] strip The boolean value that indicates when this parser should do
+ * strip leading and whitespace trailing
*
- * @return Document root with children tags, or @c NULL on errors.
- * Document with errors may return partial tree instead of @c NULL,
- * we'll do our best to avoid returning nothing.
+ * @return The document root with children tags, otherwise @c NULL on errors \n
+ * The document with errors may return a partial tree instead of @c NULL,
+ * we are going to do our best to avoid returning nothing.
*/
EAPI Eina_Simple_XML_Node_Root * eina_simple_xml_node_load(const char *buf, unsigned buflen, Eina_Bool strip);
/**
- * Free node tree build with eina_simple_xml_node_load()
+ * @brief Frees the node tree built with eina_simple_xml_node_load().
+ *
+ * @since_tizen 2.3
*
- * @param root memory returned by eina_simple_xml_node_load()
+ * @param[in] root The memory returned by eina_simple_xml_node_load()
*/
EAPI void eina_simple_xml_node_root_free(Eina_Simple_XML_Node_Root *root);
/**
- * Converts the node tree under the given element to a XML string.
+ * @brief Converts the node tree under the given element to an XML string.
*
- * @param node the base node to convert.
- * @param indent Indentation string, or @c NULL to disable it.
+ * @since_tizen 2.3
*
- * @return @c NULL on errors or a newly allocated string on success.
+ * @param[in] node The base node to convert
+ * @param[in] indent The indentation string, otherwise @c NULL to disable it
+ *
+ * @return @c NULL on errors, otherwise a newly allocated string on success
*/
EAPI char * eina_simple_xml_node_dump(Eina_Simple_XML_Node *node, const char *indent);
-
-/**
- * @}
- */
-
/**
* @}
*/
diff --git a/src/lib/eina/eina_str.h b/src/lib/eina/eina_str.h
index dae592bac6..4a2439e3ce 100644
--- a/src/lib/eina/eina_str.h
+++ b/src/lib/eina/eina_str.h
@@ -7,211 +7,172 @@
#include "eina_types.h"
/**
- * @page tutorial_eina_string Eina String example
- * @dontinclude eina_str_01.c
- *
- * Whenever using eina we need to include it:
- * @skipline #include
- * @line #include
- *
- * In our main function we declare(and initialize) some variables and initialize
- * eina:
- * @until eina_init
- *
- * It's frequently necessary to split a string into its constituent parts,
- * eina_str_split() make's it easy to do so:
- * @until printf
- *
- * Another common need is to make a string uppercase or lowercase, so let's
- * create a string and make it uppercase and then make it lowercase again:
- * @until printf
- * @until printf
- *
- * Next we use eina to check if our @p names string starts or ends with some
- * values:
- * @until Has
- *
- * When strings will be used in a terminal(or a number of other places) it
- * necessary to escape certain characters that appear in them:
- * @until printf
- *
- * Much as we previously split a string we will now join two strings:
- * @until printf
- *
- * With strlcpy() we can copy what portion of the @p prologue fits in @p str and
- * be sure that it's still NULL terminated:
- * @until printf
- *
- * Since we are done with @p prologue and @p str we should free them:
- * @until free(str
- *
- * Finally we see strlcat in action:
- * @until printf("
- *
- * And then shut eina down and exit:
- * @until }
- * @example eina_str_01.c
- */
-/**
- * @addtogroup Eina_String_Group String
+ * @defgroup Eina_String_Group String
+ * @ingroup Eina_Tools_Group
*
- * @brief Provide useful functions for C string manipulation.
+ * @brief The group discusses useful functions for C string manipulation.
*
- * This group of functions allow you to more easily manipulate strings, they
- * provide functionality not available through string.h.
+ * This group of functions allows you to manipulate strings more easily, they
+ * provide functionality that is not available through string.h.
*
- * @warning Since these functions modify the strings they can't be used with
+ * Since these functions modify the strings they can't be used with
* shared strings(eina_stringshare).
*
- * See an example @ref tutorial_eina_string "here".
- */
-
-/**
- * @addtogroup Eina_Tools_Group Tools
- *
- * For more information refer to the @ref tutorial_eina_string "string example".
- *
- * @{
- */
-
-/**
- * @defgroup Eina_String_Group String
- *
* @{
*/
/* strlcpy implementation for libc's lacking it */
/**
- * @brief Copy a c-string to another.
- *
- * @param dst The destination string.
- * @param src The source string.
- * @param siz The size of the destination string.
- * @return The length of the source string.
- *
- * This function copies up to @p siz - 1 characters from the
- * NULL-terminated string @p src to @p dst, NULL-terminating the result
- * (unless @p siz is equal to 0). The returned value is the length of
- * @p src. If the returned value is greater than @p siz, truncation
- * occurred.
- *
- * @note The main difference between eina_strlcpy and strncpy is that this
- * ensures @p dst is NULL-terminated even if no @c NULL byte is found in the first
- * @p siz bytes of src.
+ * @brief Copies one c-string to another.
+ *
+ * @details This function copies up to @a siz - 1 characters from the
+ * NULL-terminated string @a src to @a dst, NULL-terminating the result
+ * (unless @a siz is equal to 0). The returned value is the length of
+ * @a src. If the returned value is greater than @a siz, truncation
+ * occurs.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks The main difference between eina_strlcpy and strncpy is that this
+ * ensures that @a dst is NULL-terminated even if no @c NULL byte is found in the first
+ * @a siz bytes of @a src.
+ *
+ * @param[in] dst The destination string
+ * @param[in] src The source string
+ * @param[in] siz The size of the destination string
+ * @return The length of the source string
+ *
*/
EAPI size_t eina_strlcpy(char *dst, const char *src, size_t siz) EINA_ARG_NONNULL(1, 2);
/**
- * @brief Append a c-string.
+ * @brief Appends a c-string.
+ *
+ * @details This function appends @a src to @a dst of size @a siz (unlike
+ * strncat, @a siz is the full size of @a dst, no space is left). At
+ * most @a siz - 1 characters are copied. Always NULL-terminates
+ * (unless @a siz <= strlen(dst)). This function returns strlen(src) +
+ * MIN(siz, strlen(initial dst)). If the returned value is greater than or
+ * equal to @a siz, truncation occurs.
*
- * @param dst The destination string.
- * @param src The source string.
- * @param siz The size of the destination string.
+ * @since_tizen 2.3
+ *
+ * @param[in] dst The destination string
+ * @param[in] src The source string
+ * @param[in] siz The size of the destination string
* @return The length of the source string plus MIN(siz, strlen(initial dst))
*
- * This function appends @p src to @p dst of size @p siz (unlike
- * strncat, @p siz is the full size of @p dst, not space left). At
- * most @p siz - 1 characters will be copied. Always NULL-terminates
- * (unless @p siz <= strlen(dst)). This function returns strlen(src) +
- * MIN(siz, strlen(initial dst)). If the returned value is greater or
- * equal than @p siz, truncation occurred.
*/
EAPI size_t eina_strlcat(char *dst, const char *src, size_t siz) EINA_ARG_NONNULL(1, 2);
/**
- * @brief Check if the given string has the given prefix.
+ * @brief Check whether the given string has the given prefix.
+ *
+ * @details This function returns @c EINA_TRUE if @a str has the prefix
+ * @a prefix, otherwise it returns @c EINA_FALSE. If the length of @a prefix is
+ * greater than @a str, @c EINA_FALSE is returned.
*
- * @param str The string to work with.
- * @param prefix The prefix to check for.
- * @return #EINA_TRUE if the string has the given prefix, #EINA_FALSE otherwise.
+ * @since_tizen 2.3
+ *
+ * @param[in] str The string to work with
+ * @param[in] prefix The prefix to check for
+ * @return @c EINA_TRUE if the string has the given prefix, otherwise @c EINA_FALSE
*
- * This function returns #EINA_TRUE if @p str has the prefix
- * @p prefix, #EINA_FALSE otherwise. If the length of @p prefix is
- * greater than @p str, #EINA_FALSE is returned.
*/
EAPI Eina_Bool eina_str_has_prefix(const char *str, const char *prefix) EINA_PURE EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT;
/**
- * @brief Check if the given string has the given suffix.
+ * @brief Check whether the given string has the given suffix.
+ *
+ * @details This function returns @c EINA_TRUE if @a str has the suffix
+ * @a suffix, otherwise it returns @c EINA_FALSE. If the length of @a suffix is
+ * greater than @a str, @c EINA_FALSE is returned.
*
- * @param str The string to work with.
- * @param suffix The suffix to check for.
- * @return #EINA_TRUE if the string has the given suffix, #EINA_FALSE otherwise.
+ * @since_tizen 2.3
+ *
+ * @param[in] str The string to work with
+ * @param[in] suffix The suffix to check for
+ * @return @c EINA_TRUE if the string has the given suffix, otherwise @c EINA_FALSE
*
- * This function returns #EINA_TRUE if @p str has the suffix
- * @p suffix, #EINA_FALSE otherwise. If the length of @p suffix is
- * greater than @p str, #EINA_FALSE is returned.
*/
EAPI Eina_Bool eina_str_has_suffix(const char *str, const char *suffix) EINA_PURE EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT;
/**
- * @brief Check if the given string has the given extension.
+ * @brief Check whether the given string has the given extension.
+ *
+ * @details This function does the same as eina_str_has_suffix(), except it's case
+ * insensitive.
*
- * @param str The string to work with.
- * @param ext The extension to check for.
- * @return #EINA_TRUE if the string has the given extension, #EINA_FALSE otherwise.
+ * @since_tizen 2.3
+ *
+ * @param[in] str The string to work with
+ * @param[in] ext The extension to check for
+ * @return @c EINA_TRUE if the string has the given extension, otherwise @c EINA_FALSE
*
- * This function does the same as eina_str_has_suffix(), except it's case
- * insensitive.
*/
EAPI Eina_Bool eina_str_has_extension(const char *str, const char *ext) EINA_PURE EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT;
/**
- * @brief Split a string using a delimiter.
- *
- * @param string The string to split.
- * @param delimiter The string which specifies the places at which to split the string.
- * @param max_tokens The maximum number of strings to split string into, or a number less
- * than 1 to split as many times as possible. This parameter
- * IGNORES the added @c NULL terminator.
- * @return A newly-allocated NULL-terminated array of strings or @c NULL if it
- * fails to allocate the array.
- *
- * This function splits @p string into a maximum of @p max_tokens pieces,
- * using the given delimiter @p delimiter. @p delimiter is not included in any
- * of the resulting strings, unless @p max_tokens is reached. If
- * @p max_tokens is less than @c 1, the string is splitted as many times as possible. If
- * @p max_tokens is reached, the last string in the returned string
- * array contains the remainder of string. The returned value is a
- * newly allocated NULL-terminated array of strings or @c NULL if it fails to
- * allocate the array. To free it, free the first element of the array and the
- * array itself.
- *
- * @note If you need the number of elements in the returned array see
- * eina_str_split_full().
+ * @brief Splits a string using a delimiter.
+ *
+ * @details This function splits @a string into a maximum of @a max_tokens pieces,
+ * using the given delimiter @a delimiter. @a delimiter is not included in any
+ * of the resulting strings, unless @a max_tokens is reached. If
+ * @a max_tokens is less than @c 1, the string is splitted as many times as possible. If
+ * @a max_tokens is reached, the last string in the returned string
+ * array contains the remainder of the string. The returned value is a
+ * newly allocated NULL-terminated array of strings or @c NULL if it fails to
+ * allocate the array. To free it, free the first element of the array and the
+ * array itself.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks If you need the number of elements in the returned array see
+ * eina_str_split_full().
+ *
+ * @param[in] string The string to split
+ * @param[in] delimiter The string that specifies the places at which to split the string
+ * @param[in] max_tokens The maximum number of strings to split the string into, or a number less
+ * than @c 1 to split as many times as possible \n
+ * This parameter IGNORES the added @c NULL terminator.
+ * @return A newly-allocated NULL-terminated array of strings, otherwise @c NULL if it
+ * fails to allocate the array
+ *
*/
EAPI char **eina_str_split(const char *string, const char *delimiter, int max_tokens) EINA_ARG_NONNULL(1, 2) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
/**
- * @brief Split a string using a delimiter and returns number of elements.
- *
- * @param string The string to split.
- * @param delimiter The string which specifies the places at which to split the string.
- * @param max_tokens The maximum number of strings to split string into, or a number less
- * than 1 to split as many times as possible. This parameter
- * IGNORES the added @c NULL terminator.
- * @param elements Where to return the number of elements in returned
- * array. This array is guaranteed to be no greater than @p max_tokens, and
- * it will NOT count the @c NULL terminator element.
- * @return A newly-allocated NULL-terminated array of strings or @c NULL if it
- * fails to allocate the array.
- *
- * This function splits @p string into a maximum of @p max_tokens pieces,
- * using the given delimiter @p delimiter. @p delimiter is not included in any
- * of the resulting strings, unless @p max_tokens is reached. If
- * @p max_tokens is less than @c 1, the string is splitted as many times as possible. If
- * @p max_tokens is reached, the last string in the returned string
- * array contains the remainder of string. The returned value is a
- * newly allocated NULL-terminated array of strings or @c NULL if it fails to
- * allocate the array. To free it, free the first element of the array and the
- * array itself.
- *
- * @note The actual size of the returned array, when @p elements returns greater than zero,
- * will always be @p elements + 1. This is due to the @c NULL terminator element that
- * is added to the array for safety. If it returns @c 6, the number of split strings returned
- * will be 6, but the size of the array (including the @c NULL element) will actually be 7.
+ * @brief Splits a string using a delimiter and returns the number of elements.
+ *
+ * @details This function splits @a string into a maximum of @a max_tokens pieces,
+ * using the given delimiter @a delimiter. @a delimiter is not included in any
+ * of the resulting strings, unless @a max_tokens is reached. If
+ * @a max_tokens is less than @c 1, the string is splitted as many times as possible. If
+ * @a max_tokens is reached, the last string in the returned string
+ * array contains the remainder of the string. The returned value is a
+ * newly allocated NULL-terminated array of strings or @c NULL if it fails to
+ * allocate the array. To free it, free the first element of the array and the
+ * array itself.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks The actual size of the returned array, when @a elements returns greater than zero,
+ * is always @a elements + 1. This is due to the @c NULL terminator element that
+ * is added to the array for safety. If it returns @c 6, the number of split strings returned
+ * is 6, but the size of the array (including the @c NULL element) is actually 7.
+ *
+ * @param string The string to split
+ * @param[in] delimiter The string that specifies the places at which to split the string
+ * @param[in] max_tokens The maximum number of strings to split the string into, or a number less
+ * than @c 1 to split as many times as possible \n
+ * This parameter IGNORES the added @c NULL terminator.
+ * @param[out] elements The number of elements in the returned array \n
+ * This array is guaranteed to be no greater than @a max_tokens, and
+ * it does NOT count the @c NULL terminator element.
+ * @return A newly-allocated NULL-terminated array of strings, otherwise @c NULL if it
+ * fails to allocate the array
*
* @see eina_str_split()
*/
@@ -219,27 +180,29 @@ EAPI char **eina_str_split_full(const char *string, const char *delimit
/**
- * @brief Join two strings of known length.
- *
- * @param dst The buffer to store the result.
- * @param size Size (in byte) of the buffer.
- * @param sep The separator character to use.
- * @param a First string to use, before @p sep.
- * @param a_len length of @p a.
- * @param b Second string to use, after @p sep.
- * @param b_len length of @p b.
- * @return The number of characters printed.
- *
- * This function joins the strings @p a and @p b (in that order) and
- * separate them with @p sep. The result is stored in the buffer
- * @p dst and at most @p size - 1 characters will be written and the
- * string is NULL-terminated. @p a_len is the length of @p a (not
- * including '\\0') and @p b_len is the length of @p b (not including
- * '\\0'). This function returns the number of characters printed (not
- * including the trailing '\\0' used to end output to strings). Just
- * like snprintf(), it will not write more than @p size bytes, thus a
- * returned value of @p size or more means that the output was
- * truncated.
+ * @brief Joins two strings of known length.
+ *
+ * @details This function joins the strings @a a and @a b (in that order) and
+ * separates them with @a sep. The result is stored in the buffer
+ * @a dst and at most @a size - 1 characters are written and the
+ * string is NULL-terminated. @a a_len is the length of @a a (not
+ * including '\\0') and @a b_len is the length of @a b (not including
+ * '\\0'). This function returns the number of characters printed (not
+ * including the trailing '\\0' used to end output to the strings). Just
+ * like snprintf(), it does not write more than @a size bytes, thus a
+ * returned value of @a size or more means that the output is
+ * truncated.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] dst The buffer to store the result
+ * @param[in] size The size (in byte) of the buffer
+ * @param[in] sep The separator character to use
+ * @param[in] a The first string to use, before @a sep
+ * @param[in] a_len The length of @a a
+ * @param[in] b The second string to use, after @a sep
+ * @param[in] b_len The length of @a b
+ * @return The number of characters printed
*
* @see eina_str_join()
* @see eina_str_join_static()
@@ -248,101 +211,125 @@ EAPI size_t eina_str_join_len(char *dst, size_t size, char sep, const c
/**
- * @brief Use Iconv to convert a text string from one encoding to another.
+ * @brief Uses Iconv to convert a text string from one encoding to another.
+ *
+ * @details This function converts @a text, encoded in @a enc_from. On success,
+ * the converted text is returned and is encoded in @a enc_to. On
+ * failure, @c NULL is returned. Iconv is used to convert @a text. If
+ * Iconv is not available, @c NULL is returned. When not used anymore,
+ * the returned value must be freed.
*
- * @param enc_from Encoding to convert from.
- * @param enc_to Encoding to convert to.
- * @param text The text to convert.
- * @return The converted text.
+ * @since_tizen 2.3
*
- * This function converts @p text, encoded in @p enc_from. On success,
- * the converted text is returned and is encoded in @p enc_to. On
- * failure, @c NULL is returned. Iconv is used to convert @p text. If
- * Iconv is not available, @c NULL is returned. When not used anymore,
- * the returned value must be freed.
+ * @param[in] enc_from The encoding to convert from
+ * @param[in] enc_to The encoding to convert to
+ * @param[in] text The text to convert
+ * @return The converted text
*
- * @warning This function is guaranteed to break when '\0' characters are in @p text.
- * DO NOT USE THIS FUNCTION IF YOUR TEXT CONTAINS NON-TERMINATING '\0' CHARACTERS.
*/
EAPI char *eina_str_convert(const char *enc_from, const char *enc_to, const char *text) EINA_WARN_UNUSED_RESULT EINA_MALLOC EINA_ARG_NONNULL(1, 2, 3);
-/**
- * @brief Use Iconv to convert a text string from one encoding to another.
- *
- * @param enc_from Encoding to convert from.
- * @param enc_to Encoding to convert to.
- * @param text The text to convert.
- * @param len The size in bytes of the text to convert.
- * @param retlen The size in bytes of the converted text.
- * @return The converted text.
- *
- * This function converts @p text, encoded in @p enc_from. On success,
- * the converted text is returned and is encoded in @p enc_to. On
- * failure, @c NULL is returned. Iconv is used to convert @p text. If
- * Iconv is not available, @c NULL is returned. When not used anymore,
- * the returned value must be freed.
- *
- * @since 1.8
- */
-EAPI char *eina_str_convert_len(const char *enc_from, const char *enc_to, const char *text, size_t len, size_t *retlen) EINA_WARN_UNUSED_RESULT EINA_MALLOC EINA_ARG_NONNULL(1, 2, 3);
-
/**
- * @brief Escape slashes, spaces and apostrophes in strings.
+ * @brief Escapes back slashes, spaces, and apostrophes in strings.
+ *
+ * @since_tizen 2.3
+ *
+ * @remarks Escaping is done by adding a back slash \ before any occurrence of back slashes \,
+ * spaces " ", or apostrophes "'". This function returns a newly allocated
+ * escaped string on success or @c NULL on failure. When not used anymore, the
+ * returned value must be freed.
*
- * @param str The string to escape.
- * @return The escaped string.
+ * @param[in] str The string to escape
+ * @return The escaped string
*
- * Escaping is done by adding a slash "\" before any occurrence of slashes "\",
- * spaces " " or apostrophes "'". This function returns a newly allocated
- * escaped string on success, @c NULL on failure. When not used anymore, the
- * returned value must be freed.
*/
EAPI char *eina_str_escape(const char *str) EINA_WARN_UNUSED_RESULT EINA_MALLOC EINA_ARG_NONNULL(1);
/**
- * @brief Lowercase all the characters in range [A-Z] in the given string.
+ * @brief Lowercases all the characters in the range [A-Z] in the given string.
+ *
+ * @details This function modifies the original string, changing all characters
+ * in [A-Z] to lowercase. If @a str is @c NULL or is an empty string,
+ * this function does nothing.
+ *
+ * @since_tizen 2.3
*
- * @param str The string to lowercase.
+ * @param[out] str The string to lowercase
*
- * This function modifies the original string, changing all characters
- * in [A-Z] to lowercase. If @p str is @c NULL or is an empty string,
- * this function does nothing.
*/
EAPI void eina_str_tolower(char **str);
/**
- * @brief Uppercase all the characters in range [a-z] in the given string.
+ * @brief Uppercases all the characters in the range [a-z] in the given string.
*
- * @param str The string to uppercase.
+ * @details This function modifies the original string, changing all characters
+ * in [a-z] to uppercase. If @a str is @c NULL or is an empty string,
+ * this function does nothing.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[out] str The string to uppercase
*
- * This function modifies the original string, changing all characters
- * in [a-z] to uppercase. If @p str is @c NULL or is an empty string,
- * this function does nothing.
*/
EAPI void eina_str_toupper(char **str);
+/**
+ * @brief Join two strings of known length.
+ *
+ * @details This function is similar to eina_str_join_len(), but will compute
+ * the length of @p a and @p b using strlen().
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] dst The buffer to store the result.
+ * @param[in] size Size (in byte) of the buffer.
+ * @param[in] sep The separator character to use.
+ * @param[in] a First string to use, before @p sep.
+ * @param[in] b Second string to use, after @p sep.
+ * @return The number of characters printed.
+ *
+ * @see eina_str_join_len()
+ * @see eina_str_join_static()
+ */
static inline size_t eina_str_join(char *dst, size_t size, char sep, const char *a, const char *b) EINA_ARG_NONNULL(1, 4, 5);
/**
* @def eina_str_join_static(dst, sep, a, b)
- * @brief Join two static strings and store the result in a static buffer.
+ * @brief Joins two static strings and stores the result in a static buffer.
*
- * @param dst The buffer to store the result.
- * @param sep The separator character to use.
- * @param a First string to use, before @p sep.
- * @param b Second string to use, after @p sep.
- * @return The number of characters printed.
+ * @details This function is similar to eina_str_join_len(), but assumes
+ * that string sizes are known using sizeof(X).
+ *
+ * @since_tizen 2.3
*
- * This function is similar to eina_str_join_len(), but will assume
- * string sizes are know using sizeof(X).
+ * @param dst The buffer to store the result
+ * @param sep The separator character to use
+ * @param a The first string to use, before @a sep
+ * @param b The second string to use, after @a sep
+ * @return The number of characters printed
*
* @see eina_str_join()
* @see eina_str_join_static()
*/
#define eina_str_join_static(dst, sep, a, b) eina_str_join_len(dst, sizeof(dst), sep, a, (sizeof(a) > 0) ? sizeof(a) - 1 : 0, b, (sizeof(b) > 0) ? sizeof(b) - 1 : 0)
+/**
+ * @brief Count up to a given amount of bytes of the given string.
+ *
+ * @details This function returns the size of @p str, up to @p maxlen
+ * characters. It avoid needless iterations after that size. @p str
+ * must be a valid pointer and MUST not be @c NULL, otherwise this
+ * function will crash. This function returns the string size, or
+ * (size_t)-1 if the size is greater than @a maxlen.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] str The string pointer.
+ * @param[in] maxlen The maximum length to allow.
+ * @return the string size or (size_t)-1 if greater than @a maxlen.
+ */
static inline size_t eina_strlen_bounded(const char *str, size_t maxlen) EINA_PURE EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
#include "eina_inline_str.x"
@@ -351,8 +338,4 @@ static inline size_t eina_strlen_bounded(const char *str, size_t maxlen) EINA_PU
* @}
*/
-/**
- * @}
- */
-
#endif /* EINA_STR_H */
diff --git a/src/lib/eina/eina_strbuf.h b/src/lib/eina/eina_strbuf.h
index 1a628b9fef..7ce38705b4 100644
--- a/src/lib/eina/eina_strbuf.h
+++ b/src/lib/eina/eina_strbuf.h
@@ -6,71 +6,34 @@
#include "eina_types.h"
-
-/**
- * @page tutorial_strbuf Eina_Strbuf example
- * @dontinclude eina_strbuf_01.c
- *
- * First thing always is including Eina:
- * @skipline #include
- * @until #include
- *
- * Next we initialize eina and create a string buffer to play with:
- * @until strbuf_new
- *
- * Here you can see two different ways of creating a buffer with the same
- * contents. We could create them in simpler ways, but this gives us an
- * opportunity to demonstrate several functions in action:
- * @until strbuf_reset
- * @until strbuf_reset
- *
- * Next we use the printf family of functions to create a formated string,
- * add, remove and replace some content:
- * @until strbuf_string_get
- * @until strbuf_string_get
- * @until strbuf_string_get
- *
- * Once done we free our string buffer, shut down Eina and end the application:
- * @until }
- *
- * @example eina_strbuf_01.c
- */
/**
- * @addtogroup Eina_String_Buffer_Group String Buffer
- *
- * @brief These functions provide string buffers management.
- *
- * The String Buffer data type is designed to be a mutable string,
- * allowing to append, prepend or insert a string to a buffer.
+ * @defgroup Eina_String_Buffer_Group String Buffer
+ * @ingroup Eina_Data_Types_Group
*
- * For more information see @ref tutorial_strbuf "this example".
- */
-
-/**
- * @addtogroup Eina_Data_Types_Group Data Types
+ * @brief This group discusses the functions that provide string buffers management.
*
- * @{
- */
-
-/**
- * @defgroup Eina_String_Buffer_Group String Buffer
+ * @remarks The String Buffer data type is designed to be a mutable string,
+ * allowing to append, prepend, or insert a string into a buffer.
*
* @{
*/
/**
* @typedef Eina_Strbuf
- * Type for a string buffer.
+ * @brief The structure type for a string buffer.
*/
typedef struct _Eina_Strbuf Eina_Strbuf;
/**
- * @brief Create a new string buffer.
+ * @brief Creates a new string buffer.
+ *
+ * @details This function creates a new string buffer. On error, @c NULL is
+ * returned and Eina error is set to #EINA_ERROR_OUT_OF_MEMORY. To
+ * free the resources, use eina_strbuf_free().
*
- * @return Newly allocated string buffer instance.
+ * @since_tizen 2.3
*
- * This function creates a new string buffer. On error, @c NULL is
- * returned. To free the resources, use eina_strbuf_free().
+ * @return A newly allocated string buffer instance
*
* @see eina_strbuf_free()
* @see eina_strbuf_append()
@@ -79,89 +42,86 @@ typedef struct _Eina_Strbuf Eina_Strbuf;
EAPI Eina_Strbuf *eina_strbuf_new(void) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
/**
- * @brief Create a new string buffer using the passed string. The passed
- * string is used directly as the buffer, it's somehow the opposite function of
- * @ref eina_strbuf_string_steal . The passed string must be malloced.
+ * @brief Creates a new string buffer using the passed string. The passed
+ * string is used directly as the buffer, it's somehow the opposite function of
+ * @ref eina_strbuf_string_steal. The passed string must be malloced.
*
- * @param str the string to manage
- * @return Newly allocated string buffer instance.
+ * @details This function creates a new string buffer. On error, @c NULL is
+ * returned and Eina error is set to #EINA_ERROR_OUT_OF_MEMORY. To
+ * free the resources, use eina_strbuf_free().
*
- * This function creates a new string buffer. On error, @c NULL is
- * returned. To free the resources, use eina_strbuf_free().
+ * @since 1.1.0
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] str The string to manage
+ * @return A newly allocated string buffer instance
*
* @see eina_strbuf_free()
* @see eina_strbuf_append()
* @see eina_strbuf_string_get()
- * @since 1.1.0
*/
EAPI Eina_Strbuf *eina_strbuf_manage_new(char *str) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
/**
- * @brief Create a new string buffer using the passed string. The passed
- * string is used directly as the buffer, it's somehow the opposite function of
- * @ref eina_strbuf_string_steal . The passed string must be malloced.
+ * @brief Creates a new string buffer using the passed string. The passed
+ * string is used directly as the buffer, it's somehow the opposite function of
+ * @ref eina_strbuf_string_steal. The passed string must be malloced.
*
- * @param str the string to manage
- * @param length the length of the string.
- * @return Newly allocated string buffer instance.
+ * @details This function creates a new string buffer. On error, @c NULL is
+ * returned and Eina error is set to #EINA_ERROR_OUT_OF_MEMORY. To
+ * free the resources, use eina_strbuf_free().
*
- * This function creates a new string buffer. On error, @c NULL is
- * returned. To free the resources, use eina_strbuf_free().
- *
- * @see eina_strbuf_manage_new()
* @since 1.2.0
- */
-EAPI Eina_Strbuf *eina_strbuf_manage_new_length(char *str, size_t length) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
-
-/**
- * @brief Create a new string buffer using the passed string. The passed
- * string is used directly as the buffer, it's somehow the opposite function of
- * @ref eina_strbuf_string_steal . The passed string must be malloced.
*
- * @param str the string to manage
- * @param length the length of the string.
- * @return Newly allocated string buffer instance.
+ * @since_tizen 2.3
*
- * This function creates a new string buffer. On error, @c NULL is
- * returned. To free the resources, use eina_strbuf_free().
+ * @param[in] str The string to manage
+ * @param[in] length The length of the string
+ * @return A newly allocated string buffer instance
*
* @see eina_strbuf_manage_new()
- * @since 1.9.0
*/
-EAPI Eina_Strbuf *eina_strbuf_manage_read_only_new_length(const char *str, size_t length) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
+EAPI Eina_Strbuf *eina_strbuf_manage_new_length(char *str, size_t length) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
/**
- * @brief Free a string buffer.
+ * @brief Frees a string buffer.
*
- * @param buf The string buffer to free.
+ * @details This function frees the memory of @a buf. @a buf must have been
+ * created by eina_strbuf_new().
*
- * This function frees the memory of @p buf. @p buf must have been
- * created by eina_strbuf_new().
+ * @since_tizen 2.3
+ *
+ * @param[in] buf The string buffer to free
*/
EAPI void eina_strbuf_free(Eina_Strbuf *buf) EINA_ARG_NONNULL(1);
/**
- * @brief Reset a string buffer.
+ * @brief Resets a string buffer.
+ *
+ * @details This function resets @a buf: the buffer length is set to 0, and the
+ * string is set to '\\0'. No memory is freed.
*
- * @param buf The string buffer to reset.
+ * @since_tizen 2.3
*
- * This function reset @p buf: the buffer len is set to 0, and the
- * string is set to '\\0'. No memory is free'd.
+ * @param[in] buf The string buffer to reset
*/
EAPI void eina_strbuf_reset(Eina_Strbuf *buf) EINA_ARG_NONNULL(1);
/**
- * @brief Append a string to a buffer, reallocating as necessary.
+ * @brief Appends a string to a buffer, reallocating as necessary.
+ *
+ * @details This function appends @a str to @a buf. It computes the length of
+ * @a str, so is slightly slower than eina_strbuf_append_length(). If
+ * the length is known beforehand, consider using that variant. If
+ * @a buf can't append it, @c EINA_FALSE is returned, otherwise @c EINA_TRUE is
+ * returned.
*
- * @param buf The string buffer to append to.
- * @param str The string to append.
- * @return #EINA_TRUE on success, #EINA_FALSE on failure.
+ * @since_tizen 2.3
*
- * This function appends @p str to @p buf. It computes the length of
- * @p str, so is slightly slower than eina_strbuf_append_length(). If
- * the length is known beforehand, consider using that variant. If
- * @p buf can't append it, #EINA_FALSE is returned, otherwise #EINA_TRUE is
- * returned.
+ * @param[in] buf The string buffer to append to
+ * @param[in] str The string to append
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure
*
* @see eina_strbuf_append()
* @see eina_strbuf_append_length()
@@ -169,35 +129,40 @@ EAPI void eina_strbuf_reset(Eina_Strbuf *buf) EINA_ARG_NONNULL(1);
EAPI Eina_Bool eina_strbuf_append(Eina_Strbuf *buf, const char *str) EINA_ARG_NONNULL(1, 2);
/**
- * @brief Append an escaped string to a buffer, reallocating as necessary.
+ * @brief Appends an escaped string to a buffer, reallocating as necessary.
*
- * @param buf The string buffer to append to.
- * @param str The string to append.
- * @return #EINA_TRUE on success, #EINA_FALSE on failure.
+ * @details This function escapes and then appends the string @a str to @a buf. If @a str
+ * cannot be appended, @c EINA_FALSE is returned, otherwise, @c EINA_TRUE is
+ * returned.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] buf The string buffer to append to
+ * @param[in] str The string to append
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure
*
- * This function escapes and then appends the string @p str to @p buf. If @p str
- * can not be appended, #EINA_FALSE is returned, otherwise, #EINA_TRUE is
- * returned.
*/
EAPI Eina_Bool eina_strbuf_append_escaped(Eina_Strbuf *buf, const char *str) EINA_ARG_NONNULL(1, 2);
/**
- * @brief Append a string to a buffer, reallocating as necessary,
- * limited by the given length.
+ * @brief Appends a string to a buffer, reallocating as necessary,
+ * limited by the given length.
*
- * @param buf The string buffer to append to.
- * @param str The string to append.
- * @param maxlen The maximum number of characters to append.
- * @return #EINA_TRUE on success, #EINA_FALSE on failure.
+ * @details This function appends at most @a maxlen characters of @a str to
+ * @a buf. It can't append more than the length of @a str. It
+ * computes the length of @a str, so it is slightly slower than
+ * eina_strbuf_append_length(). If the length is known beforehand,
+ * consider using that variant (@a maxlen should then be checked so
+ * that it is greater than the size of @a str). If @a str cannot be
+ * appended, @c EINA_FALSE is returned, otherwise @c EINA_TRUE is
+ * returned.
*
- * This function appends at most @p maxlen characters of @p str to
- * @p buf. It can't append more than the length of @p str. It
- * computes the length of @p str, so it is slightly slower than
- * eina_strbuf_append_length(). If the length is known beforehand,
- * consider using that variant (@p maxlen should then be checked so
- * that it is greater than the size of @p str). If @p str can not be
- * appended, #EINA_FALSE is returned, otherwise, #EINA_TRUE is
- * returned.
+ * @since_tizen 2.3
+ *
+ * @param[in] buf The string buffer to append to
+ * @param[in] str The string to append
+ * @param[in] maxlen The maximum number of characters to append
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure
*
* @see eina_strbuf_append()
* @see eina_strbuf_append_length()
@@ -205,19 +170,22 @@ EAPI Eina_Bool eina_strbuf_append_escaped(Eina_Strbuf *buf, const char *str) EIN
EAPI Eina_Bool eina_strbuf_append_n(Eina_Strbuf *buf, const char *str, size_t maxlen) EINA_ARG_NONNULL(1, 2);
/**
- * @brief Append a string of exact length to a buffer, reallocating as necessary.
+ * @brief Appends a string of exact length to a buffer, reallocating as necessary.
+ *
+ * @details This function appends @a str to @a buf. @a str must be at most of size
+ * @a length. It is slightly faster than eina_strbuf_append() as
+ * it does not compute the size of @a str. It is useful when dealing
+ * with strings of known size, such as eina_stringshare. If @a buf
+ * can't append it, @c EINA_FALSE is returned, otherwise @c EINA_TRUE is
+ * returned.
*
- * @param buf The string buffer to append to.
- * @param str The string to append.
- * @param length The exact length to use.
- * @return #EINA_TRUE on success, #EINA_FALSE on failure.
+ * @since_tizen 2.3
+ *
+ * @param[in] buf The string buffer to append to
+ * @param[in] str The string to append
+ * @param[in] length The exact length to use
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure
*
- * This function appends @p str to @p buf. @p str must be of size at
- * most @p length. It is slightly faster than eina_strbuf_append() as
- * it does not compute the size of @p str. It is useful when dealing
- * with strings of known size, such as eina_stringshare. If @p buf
- * can't append it, #EINA_FALSE is returned, otherwise #EINA_TRUE is
- * returned.
*
* @see eina_stringshare_length()
* @see eina_strbuf_append()
@@ -226,130 +194,128 @@ EAPI Eina_Bool eina_strbuf_append_n(Eina_Strbuf *buf, const char *str, size_t ma
EAPI Eina_Bool eina_strbuf_append_length(Eina_Strbuf *buf, const char *str, size_t length) EINA_ARG_NONNULL(1, 2);
/**
- * @brief Append an Eina_Strbuf to a buffer, reallocating as necessary.
- *
- * @param buf The string buffer to append to.
- * @param data The string buffer to append.
- * @return #EINA_TRUE on success, #EINA_FALSE on failure.
+ * @brief Appends a character to a string buffer, reallocating as
+ * necessary.
*
- * This function appends @p data to @p buf. @p data must be allocated and
- * different from @NULL. It is slightly faster than eina_strbuf_append() as
- * it does not compute the size of @p str. If @p buf can't append it,
- * #EINA_FALSE is returned, otherwise #EINA_TRUE is returned.
+ * @details This function inserts @a c to @a buf. If it cannot insert it, @c EINA_FALSE
+ * is returned, otherwise @c EINA_TRUE is returned.
*
- * @see eina_strbuf_append()
- * @see eina_strbuf_append_n()
- * @see eina_strbuf_append_length()
- * @since 1.9.0
- */
-EAPI Eina_Bool eina_strbuf_append_buffer(Eina_Strbuf *buf, const Eina_Strbuf *data) EINA_ARG_NONNULL(1, 2);
-
-/**
- * @brief Append a character to a string buffer, reallocating as
- * necessary.
+ * @since_tizen 2.3
*
- * @param buf The string buffer to append to.
- * @param c The char to append.
- * @return #EINA_TRUE on success, #EINA_FALSE on failure.
+ * @param[in] buf The string buffer to append to
+ * @param[in] c The character to append
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure
*
- * This function inserts @p c to @p buf. If it can not insert it, #EINA_FALSE
- * is returned, otherwise #EINA_TRUE is returned.
*/
EAPI Eina_Bool eina_strbuf_append_char(Eina_Strbuf *buf, char c) EINA_ARG_NONNULL(1);
/**
- * @brief Append a string to a buffer, reallocating as necessary.
+ * @brief Appends a string to a buffer, reallocating as necessary.
+ *
+ * @details This function appends the string defined by the format @a fmt to @a buf. @a
+ * fmt must be of a valid format from the printf family of functions. If it can't
+ * insert it, @c EINA_FALSE is returned, otherwise @c EINA_TRUE is returned.
*
- * @param buf The string buffer to append to.
- * @param fmt The string to append.
- * @return #EINA_TRUE on success, #EINA_FALSE on failure.
+ * @since_tizen 2.3
*
- * This function appends the string defined by the format @p fmt to @p buf. @p
- * fmt must be of a valid format for printf family of functions. If it can't
- * insert it, #EINA_FALSE is returned, otherwise #EINA_TRUE is returned.
+ * @param[in] buf The string buffer to append to
+ * @param[in] fmt The string to append
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure
*
* @see eina_strbuf_append()
*/
EAPI Eina_Bool eina_strbuf_append_printf(Eina_Strbuf *buf, const char *fmt, ...) EINA_ARG_NONNULL(1, 2) EINA_PRINTF(2, 3);
/**
- * @brief Append a string to a buffer, reallocating as necessary.
+ * @brief Appends a string to a buffer, reallocating as necessary.
+ *
+ * @since_tizen 2.3
*
- * @param buf The string buffer to append to.
- * @param fmt The string to append.
- * @param args The variable arguments.
- * @return #EINA_TRUE on success, #EINA_FALSE on failure.
+ * @param[in] buf The string buffer to append to
+ * @param[in] fmt The string to append
+ * @param[in] args The variable arguments
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure
*
* @see eina_strbuf_append_printf()
*/
EAPI Eina_Bool eina_strbuf_append_vprintf(Eina_Strbuf *buf, const char *fmt, va_list args) EINA_ARG_NONNULL(1, 2);
/**
- * @brief Insert a string to a buffer, reallocating as necessary.
+ * @brief Inserts a string into a buffer, reallocating as necessary.
*
- * @param buf The string buffer to insert.
- * @param str The string to insert.
- * @param pos The position to insert the string.
- * @return #EINA_TRUE on success, #EINA_FALSE on failure.
+ * @details This function inserts @a str into @a buf at position @a pos. It
+ * computes the length of @a str, so is slightly slower than
+ * eina_strbuf_insert_length(). If the length is known beforehand,
+ * consider using that variant. If @a buf can't insert it, @c EINA_FALSE
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] buf The string buffer to insert into
+ * @param[in] str The string to insert
+ * @param[in] pos The position at which to insert the string
+ * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE on failure
*
- * This function inserts @p str to @p buf at position @p pos. It