kimcinoo
/
efl
forked from enlightenment/efl
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

docs: Fix typos and some wrong expressions in Eina API reference doxygen. 

Summary: I had fixed some typos and some wrong expressions, such as capital letters, singular, and orders of groups in Eina API reference doxygen.

Test Plan: Doxygen Revision

Reviewers: stefan, cedric, raster, Jaehyun_Cho, jpeg

Reviewed By: jpeg

Subscribers: conr2d

Differential Revision: https://phab.enlightenment.org/D4674
This commit is contained in:
Myoungwoon Roy, Kim 2017-02-20 15:18:21 +09:00 committed by Jean-Philippe Andre
parent 2ea9e7010c
commit ec71f6607a
55 changed files with 1441 additions and 1536 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
src/lib/eina/Eina.h
View File

@ -197,9 +197,9 @@
* should return properly populated @ref _Eina_Iterator and @ref _Eina_Accessor. * should return properly populated @ref _Eina_Iterator and @ref _Eina_Accessor.
* *
* @defgroup Eina_Tools_Group Tools * @defgroup Eina_Tools_Group Tools
* @ingroup Eina
* @brief Eina tools aims to help application development, providing ways to * @brief Eina tools aims to help application development, providing ways to
* make it safer, log errors, manage memory more efficiently and more. * make it safer, log errors, manage memory more efficiently and more.
* @ingroup Eina
*/ */
#ifdef _WIN32 #ifdef _WIN32

51
src/lib/eina/eina_accessor.h
View File

@ -138,7 +138,7 @@ typedef Eina_Bool (*Eina_Accessor_Lock_Callback)(Eina_Accessor *it);
/** /**
* @typedef Eina_Accessor_Clone_Callback * @typedef Eina_Accessor_Clone_Callback
* @brief Type for a callback to return a clone for the accessor * @brief Type for a callback to return a clone for the accessor.
* @since 1.10 * @since 1.10
*/ */
typedef Eina_Accessor* (*Eina_Accessor_Clone_Callback)(Eina_Accessor *it); typedef Eina_Accessor* (*Eina_Accessor_Clone_Callback)(Eina_Accessor *it);
@ -169,31 +169,31 @@ struct _Eina_Accessor
/** /**
* @def FUNC_ACCESSOR_GET_AT(Function) * @def FUNC_ACCESSOR_GET_AT(Function)
* @brief Helper macro to cast @a Function to a Eina_Accessor_Get_At_Callback. * @brief Definition for helper macro to cast @a Function to a Eina_Accessor_Get_At_Callback.
*/ */
#define FUNC_ACCESSOR_GET_AT(Function) ((Eina_Accessor_Get_At_Callback)Function) #define FUNC_ACCESSOR_GET_AT(Function) ((Eina_Accessor_Get_At_Callback)Function)
/** /**
* @def FUNC_ACCESSOR_GET_CONTAINER(Function) * @def FUNC_ACCESSOR_GET_CONTAINER(Function)
* @brief Helper macro to cast @a Function to a Eina_Accessor_Get_Container_Callback. * @brief Definition for helper macro to cast @a Function to a Eina_Accessor_Get_Container_Callback.
*/ */
#define FUNC_ACCESSOR_GET_CONTAINER(Function) ((Eina_Accessor_Get_Container_Callback)Function) #define FUNC_ACCESSOR_GET_CONTAINER(Function) ((Eina_Accessor_Get_Container_Callback)Function)
/** /**
* @def FUNC_ACCESSOR_FREE(Function) * @def FUNC_ACCESSOR_FREE(Function)
* @brief Helper macro to cast @a Function to a Eina_Accessor_Free_Callback. * @brief Definition for helper macro to cast @a Function to a Eina_Accessor_Free_Callback.
*/ */
#define FUNC_ACCESSOR_FREE(Function) ((Eina_Accessor_Free_Callback)Function) #define FUNC_ACCESSOR_FREE(Function) ((Eina_Accessor_Free_Callback)Function)
/** /**
* @def FUNC_ACCESSOR_LOCK(Function) * @def FUNC_ACCESSOR_LOCK(Function)
* @brief Helper macro to cast @a Function to a Eina_Iterator_Lock_Callback. * @brief Definition for helper macro to cast @a Function to a Eina_Iterator_Lock_Callback.
*/ */
#define FUNC_ACCESSOR_LOCK(Function) ((Eina_Accessor_Lock_Callback)Function) #define FUNC_ACCESSOR_LOCK(Function) ((Eina_Accessor_Lock_Callback)Function)
/** /**
* @def FUNC_ACCESSOR_CLONE(Function) * @def FUNC_ACCESSOR_CLONE(Function)
* @brief Helper macro to cast @p Function to a Eina_Iterator_Clone_Callback. * @brief Definition for helper macro to cast @p Function to a Eina_Iterator_Clone_Callback.
* @since 1.10 * @since 1.10
*/ */
#define FUNC_ACCESSOR_CLONE(Function) ((Eina_Accessor_Clone_Callback)Function) #define FUNC_ACCESSOR_CLONE(Function) ((Eina_Accessor_Clone_Callback)Function)
@ -201,26 +201,23 @@ struct _Eina_Accessor
/** /**
* @brief Frees an accessor. * @brief Frees an accessor.
* * @details This function frees @a accessor if it is not @c NULL.
* @param[in] accessor The accessor to free * @param[in] accessor The accessor to free
* *
* @details This function frees @a accessor if it is not @c NULL.
*/ */
EAPI void eina_accessor_free(Eina_Accessor *accessor); EAPI void eina_accessor_free(Eina_Accessor *accessor);
/** /**
* @brief Gets the data of an accessor at the given position. * @brief Gets the data of an accessor at the given position.
* * @details This function retrieves the data of the element pointed by
* @p accessor at the position @p position, and stores it in
* @p data. If @p accessor is @c NULL or if an error occurs, @c EINA_FALSE
* is returned, otherwise @c EINA_TRUE is returned.
* @param[in] accessor The accessor * @param[in] accessor The accessor
* @param[in] position The position of the element * @param[in] position The position of the element
* @param[in] data The pointer that stores the data to retrieve * @param[in] data The pointer that stores the data to retrieve
* @return #EINA_TRUE on success, otherwise #EINA_FALSE * @return #EINA_TRUE on success, otherwise #EINA_FALSE
* *
* @details This function retrieves the data of the element pointed by
* @p accessor at the position @p position, and stores it in
* @p data. If @p accessor is @c NULL or if an error occurs, #EINA_FALSE
* is returned, otherwise #EINA_TRUE is returned.
*
*/ */
EAPI Eina_Bool eina_accessor_data_get(Eina_Accessor *accessor, EAPI Eina_Bool eina_accessor_data_get(Eina_Accessor *accessor,
unsigned int position, unsigned int position,
@ -228,17 +225,22 @@ EAPI Eina_Bool eina_accessor_data_get(Eina_Accessor *accessor,
/** /**
* @brief Gets the container of an accessor. * @brief Gets the container of an accessor.
* * @details This function returns the container that created @p accessor. If
* @p accessor is @c NULL, this function returns @c NULL.
* @param[in] accessor The accessor * @param[in] accessor The accessor
* @return The container that created the accessor * @return The container that created the accessor
* *
* @details This function returns the container that created @p accessor. If
* @p accessor is @c NULL, this function returns @c NULL.
*/ */
EAPI void *eina_accessor_container_get(Eina_Accessor *accessor) EINA_ARG_NONNULL(1) EINA_PURE; EAPI void *eina_accessor_container_get(Eina_Accessor *accessor) EINA_ARG_NONNULL(1) EINA_PURE;
/** /**
* @brief Iterates over the container and executes a callback on the chosen elements. * @brief Iterates over the container and executes a callback on the chosen elements.
* @details This function iterates over the elements pointed by @p accessor,
* starting from the element at position @p start and ending at the
* element at position @p end. For each element, the callback
* @p cb is called with the data @p fdata. If @p accessor is @c NULL
* or if @p start is greater than or equal to @p end, the function returns
* immediately.
* *
* @param[in] accessor The accessor * @param[in] accessor The accessor
* @param[in] cb The callback called on the chosen elements * @param[in] cb The callback called on the chosen elements
@ -246,12 +248,6 @@ EAPI void *eina_accessor_container_get(Eina_Accessor *accessor) EINA_ARG_NONNULL
* @param[in] end The position of the last element * @param[in] end The position of the last element
* @param[in] fdata The data passed to the callback * @param[in] fdata The data passed to the callback
* *
* @details This function iterates over the elements pointed by @p accessor,
* starting from the element at position @p start and ending at the
* element at position @p end. For each element, the callback
* @p cb is called with the data @p fdata. If @p accessor is @c NULL
* or if @p start is greater than or equal to @p end, the function returns
* immediately.
*/ */
EAPI void eina_accessor_over(Eina_Accessor *accessor, EAPI void eina_accessor_over(Eina_Accessor *accessor,
Eina_Each_Cb cb, Eina_Each_Cb cb,
@ -285,7 +281,7 @@ EAPI Eina_Bool eina_accessor_lock(Eina_Accessor *accessor) EINA_ARG_NONNULL(1);
EAPI Eina_Accessor* eina_accessor_clone(Eina_Accessor *accessor) EINA_ARG_NONNULL(1); EAPI Eina_Accessor* eina_accessor_clone(Eina_Accessor *accessor) EINA_ARG_NONNULL(1);
/** /**
* @brief Unlock the container of the accessor. * @brief Unlocks the container of the accessor.
* *
* @param[in] accessor The accessor * @param[in] accessor The accessor
* @return #EINA_TRUE on success, otherwise #EINA_FALSE * @return #EINA_TRUE on success, otherwise #EINA_FALSE
@ -301,7 +297,9 @@ EAPI Eina_Bool eina_accessor_unlock(Eina_Accessor *accessor) EINA_ARG_NONNULL(1)
/** /**
* @def EINA_ACCESSOR_FOREACH * @def EINA_ACCESSOR_FOREACH
* @brief Helper macro to iterate over all the elements easily. * @brief Definition for helper macro to iterate over all the elements easily.
* @details This macro allows a convenient way to loop over all elements in an
* accessor, very similar to EINA_LIST_FOREACH().
* *
* @param accessor The accessor to use * @param accessor The accessor to use
* @param counter A counter used by eina_accessor_data_get() when * @param counter A counter used by eina_accessor_data_get() when
@ -310,9 +308,6 @@ EAPI Eina_Bool eina_accessor_unlock(Eina_Accessor *accessor) EINA_ARG_NONNULL(1)
* It must be a pointer to support getting * It must be a pointer to support getting
* its address since eina_accessor_data_get() requires a pointer. * its address since eina_accessor_data_get() requires a pointer.
* *
* @details This macro allows a convenient way to loop over all elements in an
* accessor, very similar to EINA_LIST_FOREACH().
*
* This macro can be used for freeing the data of a list, like in the * 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 * following example. It has the same goal as the one documented in
* EINA_LIST_FOREACH(), but using accessors: * EINA_LIST_FOREACH(), but using accessors:

2
src/lib/eina/eina_alloca.h
View File

@ -44,7 +44,7 @@ extern "C"
# endif # endif
/** /**
* Allocates memory in the stack frame of the caller, so it's automatically * Allocates memory in the stack frame of the caller, so it's automatically
* freed when the caller returns. See alloca(3) for detials. * freed when the caller returns. See alloca(3) for details.
*/ */
void *alloca(size_t size); void *alloca(size_t size);
# endif # endif

38
src/lib/eina/eina_array.h
View File

@ -177,7 +177,7 @@
* array it @b may shrink. * array it @b may shrink.
* *
* Allocating memory is expensive, so when the array needs to grow it allocates * 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 * enough memory to hold @p step additional elements, not just the element
* currently being added. Similarly if you remove elements, it won't free space * currently being added. Similarly if you remove elements, it won't free space
* until you have removed @p step elements. * until you have removed @p step elements.
* *
@ -242,7 +242,7 @@ struct _Eina_Array
/** /**
* @brief Create a new array. * @brief Creates a new array.
* *
* @param step The count of pointers to add when increasing the array size. * @param step The count of pointers to add when increasing the array size.
* @return @c NULL on failure, non @c NULL otherwise. * @return @c NULL on failure, non @c NULL otherwise.
@ -257,7 +257,7 @@ struct _Eina_Array
EAPI Eina_Array *eina_array_new(unsigned int step) EINA_WARN_UNUSED_RESULT EINA_MALLOC EINA_WARN_UNUSED_RESULT; 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.
* *
* @param array The array to free. * @param array The array to free.
* *
@ -269,7 +269,7 @@ EAPI Eina_Array *eina_array_new(unsigned int step) EINA_WARN_UNUSED_RESULT EINA_
EAPI void eina_array_free(Eina_Array *array); EAPI void eina_array_free(Eina_Array *array);
/** /**
* @brief Set the step of an array. * @brief Sets the step of an array.
* *
* @param array The array. * @param array The array.
* @param sizeof_eina_array Should be the value returned by sizeof(Eina_Array). * @param sizeof_eina_array Should be the value returned by sizeof(Eina_Array).
@ -285,7 +285,7 @@ EAPI void eina_array_step_set(Eina_Array *array,
unsigned int sizeof_eina_array, unsigned int sizeof_eina_array,
unsigned int step) EINA_ARG_NONNULL(1); unsigned int step) EINA_ARG_NONNULL(1);
/** /**
* @brief Clean an array. * @brief Cleans an array.
* *
* @param array The array to clean. * @param array The array to clean.
* *
@ -297,7 +297,7 @@ EAPI void eina_array_step_set(Eina_Array *array,
static inline void eina_array_clean(Eina_Array *array) EINA_ARG_NONNULL(1); static inline void eina_array_clean(Eina_Array *array) EINA_ARG_NONNULL(1);
/** /**
* @brief Flush an array. * @brief Flushes an array.
* *
* @param array The array to flush. * @param array The array to flush.
* *
@ -309,7 +309,7 @@ static inline void eina_array_clean(Eina_Array *array) EINA_ARG_NONNULL(1);
EAPI void eina_array_flush(Eina_Array *array) EINA_ARG_NONNULL(1); 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 array The array.
* @param keep The functions which selects the data to keep. * @param keep The functions which selects the data to keep.
@ -329,7 +329,7 @@ EAPI Eina_Bool eina_array_remove(Eina_Array * array,
void *gdata) EINA_ARG_NONNULL(1, 2); void *gdata) EINA_ARG_NONNULL(1, 2);
/** /**
* @brief Append a data to an array. * @brief Appends a data to an array.
* *
* @param array The array. * @param array The array.
* @param data The data to add. * @param data The data to add.
@ -345,7 +345,7 @@ static inline Eina_Bool eina_array_push(Eina_Array *array,
const void *data) EINA_ARG_NONNULL(1, 2); const void *data) EINA_ARG_NONNULL(1, 2);
/** /**
* @brief Remove the last data of an array. * @brief Removes the last data of an array.
* *
* @param array The array. * @param array The array.
* @return The retrieved data. * @return The retrieved data.
@ -359,10 +359,10 @@ static inline Eina_Bool eina_array_push(Eina_Array *array,
static inline void *eina_array_pop(Eina_Array *array) EINA_ARG_NONNULL(1); 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 Returns the data at a given position in an array.
* *
* @param array The array. * @param array The array.
* @param idx The potition of the data to retrieve. * @param idx The position of the data to retrieve.
* @return The retrieved data. * @return The retrieved data.
* *
* This function returns the data at the position @p idx in @p * This function returns the data at the position @p idx in @p
@ -372,7 +372,7 @@ static inline void *eina_array_pop(Eina_Array *array) EINA_ARG_NONNULL(1);
static inline void *eina_array_data_get(const Eina_Array *array, static inline void *eina_array_data_get(const Eina_Array *array,
unsigned int idx) EINA_ARG_NONNULL(1); unsigned int idx) EINA_ARG_NONNULL(1);
/** /**
* @brief Set the data at a given position in an array. * @brief Sets the data at a given position in an array.
* *
* @param array The array. * @param array The array.
* @param idx The position of the data to set. * @param idx The position of the data to set.
@ -388,7 +388,8 @@ static inline void eina_array_data_set(const Eina_Array *array,
unsigned int idx, unsigned int idx,
const void *data) EINA_ARG_NONNULL(1); const void *data) EINA_ARG_NONNULL(1);
/** /**
* @brief Return the number of elements in an array. * @deprecated use eina_array_count()
* @brief Returns the number of elements in an array.
* *
* @param array The array. * @param array The array.
* @return The number of elements. * @return The number of elements.
@ -397,12 +398,11 @@ static inline void eina_array_data_set(const Eina_Array *array,
* performance reasons, there is no check of @p array. If it is * performance reasons, there is no check of @p array. If it is
* @c NULL or invalid, the program may crash. * @c NULL or invalid, the program may crash.
* *
* @deprecated use eina_array_count()
*/ */
static inline unsigned int eina_array_count_get(const Eina_Array *array) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; static inline unsigned int eina_array_count_get(const Eina_Array *array) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
/** /**
* @brief Return the number of elements in an array. * @brief Returns the number of elements in an array.
* *
* @param array The array. * @param array The array.
* @return The number of elements. * @return The number of elements.
@ -414,7 +414,7 @@ static inline unsigned int eina_array_count_get(const Eina_Array *array) EINA_AR
static inline unsigned int eina_array_count(const Eina_Array *array) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; 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 Gets a new iterator associated to an array.
* *
* @param array The array. * @param array The array.
* @return A new iterator. * @return A new iterator.
@ -427,7 +427,7 @@ static inline unsigned int eina_array_count(const Eina_Array *array) EINA_ARG_NO
EAPI Eina_Iterator *eina_array_iterator_new(const Eina_Array *array) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; 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 Gets a new accessor associated to an array.
* *
* @param array The array. * @param array The array.
* @return A new accessor. * @return A new accessor.
@ -440,7 +440,7 @@ EAPI Eina_Iterator *eina_array_iterator_new(const Eina_Array *array) EINA
*/ */
EAPI Eina_Accessor *eina_array_accessor_new(const Eina_Array *array) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; 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 array The array to iterate over.
* @param cb The callback to call for each item. * @param cb The callback to call for each item.
@ -457,7 +457,7 @@ static inline Eina_Bool eina_array_foreach(Eina_Array *array,
void *fdata); void *fdata);
/** /**
* @def EINA_ARRAY_ITER_NEXT * @def EINA_ARRAY_ITER_NEXT
* @brief Macro to iterate over an array easily. * @brief Definition for the macro to iterate over an array easily.
* *
* @param array The array to iterate over. * @param array The array to iterate over.
* @param index The integer number that is increased while iterating. * @param index The integer number that is increased while iterating.

16
src/lib/eina/eina_benchmark.h
View File

@ -116,7 +116,7 @@
* The first column (specimen) is the integer passed to the work1() * The first column (specimen) is the integer passed to the work1()
* function when the test is run. The second column (experiment time) * function when the test is run. The second column (experiment time)
* is the time, in nanosecond, that work1() takes. The third and * is the time, in nanosecond, that work1() takes. The third and
* fourth columnd are self-explicit. * fourth column are self-explicit.
* *
* You can see that the integer passed work1() starts from 200 and * 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 * finishes at 290, with a step of 10. These values are computed withe
@ -129,7 +129,7 @@
* gnuplot bench_test_run.gnuplot * gnuplot bench_test_run.gnuplot
* @endcode * @endcode
* *
* to create the graphic of the comparison curves. The image file is * To create the graphic of the comparison curves. The image file is
* named output_test_run.png. * named output_test_run.png.
* *
* @section tutorial_benchmark_advanced_usage More Advanced Usage * @section tutorial_benchmark_advanced_usage More Advanced Usage
@ -345,7 +345,7 @@ typedef void (*Eina_Benchmark_Specimens)(int request);
/** /**
* @def EINA_BENCHMARK * @def EINA_BENCHMARK
* @brief cast to an #Eina_Benchmark_Specimens. * @brief Definition for the cast to an #Eina_Benchmark_Specimens.
* *
* @param function The function to cast. * @param function The function to cast.
* *
@ -355,7 +355,7 @@ typedef void (*Eina_Benchmark_Specimens)(int request);
/** /**
* @brief Create a new array. * @brief Creates a new array.
* *
* @param name The name of the benchmark. * @param name The name of the benchmark.
* @param run The name of the run. * @param run The name of the run.
@ -374,7 +374,7 @@ EAPI Eina_Benchmark *eina_benchmark_new(const char *name,
const char *run); const char *run);
/** /**
* @brief Free a benchmark object. * @brief Frees a benchmark object.
* *
* @param bench The benchmark to free. * @param bench The benchmark to free.
* *
@ -385,7 +385,7 @@ EAPI Eina_Benchmark *eina_benchmark_new(const char *name,
EAPI void eina_benchmark_free(Eina_Benchmark *bench); EAPI void eina_benchmark_free(Eina_Benchmark *bench);
/** /**
* @brief Add a test to a benchmark. * @brief Adds a test to a benchmark.
* *
* @param bench The benchmark. * @param bench The benchmark.
* @param name The name of the test. * @param name The name of the test.
@ -413,7 +413,7 @@ EAPI Eina_Bool eina_benchmark_register(Eina_Benchmark *bench,
int count_step); int count_step);
/** /**
* @brief Run the benchmark tests that have been registered. * @brief Runs the benchmark tests that have been registered.
* *
* @param bench The benchmark. * @param bench The benchmark.
* @return The list of names of the test files. * @return The list of names of the test files.
@ -426,7 +426,7 @@ EAPI Eina_Bool eina_benchmark_register(Eina_Benchmark *bench,
* bench_[name]_[run]%s.gnuplot * bench_[name]_[run]%s.gnuplot
* @endcode * @endcode
* *
* where [name] and [run] are the values passed to * Where [name] and [run] are the values passed to
* eina_benchmark_new(). * eina_benchmark_new().
* *
* Each registered test is executed and timed. The time is written to * Each registered test is executed and timed. The time is written to

10
src/lib/eina/eina_bezier.h
View File

@ -48,7 +48,7 @@ struct _Eina_Bezier
}; };
/** /**
* @brief Set the values of the points of the given floating * @brief Sets the values of the points of the given floating
* point cubic bezier curve. * point cubic bezier curve.
* *
* @param b The floating point bezier. * @param b The floating point bezier.
@ -67,7 +67,7 @@ struct _Eina_Bezier
EAPI void eina_bezier_values_set(Eina_Bezier *b, double start_x, double start_y, double ctrl_start_x, double ctrl_start_y, double ctrl_end_x, double ctrl_end_y, double end_x, double end_y) EINA_ARG_NONNULL(1); EAPI void eina_bezier_values_set(Eina_Bezier *b, double start_x, double start_y, double ctrl_start_x, double ctrl_start_y, double ctrl_end_x, double ctrl_end_y, double end_x, double end_y) EINA_ARG_NONNULL(1);
/** /**
* @brief Get the values of the points of the given floating * @brief Gets the values of the points of the given floating
* point cubic bezier curve. * point cubic bezier curve.
* *
* @param b The floating point bezier. * @param b The floating point bezier.
@ -133,7 +133,7 @@ EAPI void eina_bezier_point_at(const Eina_Bezier *b, double t, double *px, doubl
EAPI double eina_bezier_angle_at(const Eina_Bezier *b, double t) EINA_ARG_NONNULL(1); EAPI double eina_bezier_angle_at(const Eina_Bezier *b, double t) EINA_ARG_NONNULL(1);
/** /**
* @brief split the bezier at given length. * @brief Splits the bezier at given length.
* *
* @param b The floating point bezier. * @param b The floating point bezier.
* @param len The given length. * @param len The given length.
@ -144,7 +144,7 @@ EAPI double eina_bezier_angle_at(const Eina_Bezier *b, double t) EINA_ARG_NONNUL
EAPI void eina_bezier_split_at_length(const Eina_Bezier *b, double len, Eina_Bezier *left, Eina_Bezier *right) EINA_ARG_NONNULL(1); EAPI void eina_bezier_split_at_length(const Eina_Bezier *b, double len, Eina_Bezier *left, Eina_Bezier *right) EINA_ARG_NONNULL(1);
/** /**
* @brief get the bound of the the bezier. * @brief Gets the bound of the the bezier.
* *
* @param b The floating point bezier. * @param b The floating point bezier.
* @param x x coordinate of bounding box. * @param x x coordinate of bounding box.
@ -158,7 +158,7 @@ EAPI void eina_bezier_split_at_length(const Eina_Bezier *b, double len, Eina_Bez
EAPI void eina_bezier_bounds_get(const Eina_Bezier *b, double *x, double *y, double *w, double *h) EINA_ARG_NONNULL(1); EAPI void eina_bezier_bounds_get(const Eina_Bezier *b, double *x, double *y, double *w, double *h) EINA_ARG_NONNULL(1);
/** /**
* @brief find the bezier at given interval. * @brief Finds the bezier at given interval.
* *
* @param b The floating point bezier. * @param b The floating point bezier.
* @param t0 The start interval. * @param t0 The start interval.

60
src/lib/eina/eina_binbuf.h
View File

@ -34,7 +34,7 @@
typedef struct _Eina_Strbuf Eina_Binbuf; typedef struct _Eina_Strbuf Eina_Binbuf;
/** /**
* @brief Create a new string buffer. * @brief Creates a new string buffer.
* *
* @return Newly allocated string buffer instance. * @return Newly allocated string buffer instance.
* *
@ -48,12 +48,12 @@ typedef struct _Eina_Strbuf Eina_Binbuf;
EAPI Eina_Binbuf *eina_binbuf_new(void) EINA_MALLOC EINA_WARN_UNUSED_RESULT; 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 * @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 * 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. * @ref eina_binbuf_string_steal . The passed string must be malloced.
* *
* @param str the string to manage * @param str The string to manage.
* @param length the length of the string. * @param length The length of the string.
* @return Newly allocated string buffer instance. * @return Newly allocated string buffer instance.
* *
* This function creates a new string buffer. On error, @c NULL is * This function creates a new string buffer. On error, @c NULL is
@ -65,13 +65,13 @@ EAPI Eina_Binbuf *eina_binbuf_new(void) 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 EINA_DEPRECATED; EAPI Eina_Binbuf *eina_binbuf_manage_new_length(unsigned char *str, size_t length) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_DEPRECATED;
/** /**
* @brief Create a new string buffer using the passed string. The passed * @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 * string is used directly as the buffer, it's somehow the opposite function of
* @ref eina_binbuf_string_steal . * @ref eina_binbuf_string_steal .
* *
* @param str the string to start from * @param str The string to start from.
* @param length the length of the string. * @param length The length of the string.
* @param ro the passed string will not be touched if set to EINA_TRUE. * @param ro The passed string will not be touched if set to EINA_TRUE.
* @return Newly allocated string buffer instance. * @return Newly allocated string buffer instance.
* *
* This function creates a new string buffer. On error, @c NULL is * This function creates a new string buffer. On error, @c NULL is
@ -90,12 +90,12 @@ EAPI Eina_Binbuf *eina_binbuf_manage_new_length(unsigned char *str, size_t lengt
EAPI Eina_Binbuf *eina_binbuf_manage_new(const unsigned char *str, size_t length, Eina_Bool ro) EINA_MALLOC EINA_WARN_UNUSED_RESULT; EAPI Eina_Binbuf *eina_binbuf_manage_new(const unsigned char *str, size_t length, Eina_Bool ro) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
/** /**
* @brief Create a new string buffer using the passed string. The passed * @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 * 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. * @ref eina_binbuf_string_steal . The passed string will not be touched.
* *
* @param str the string to start from * @param str The string to start from.
* @param length the length of the string. * @param length The length of the string.
* @return Newly allocated string buffer instance. * @return Newly allocated string buffer instance.
* *
* This function creates a new string buffer. On error, @c NULL is * This function creates a new string buffer. On error, @c NULL is
@ -110,7 +110,7 @@ EAPI Eina_Binbuf *eina_binbuf_manage_new(const unsigned char *str, size_t length
EAPI Eina_Binbuf *eina_binbuf_manage_read_only_new_length(const unsigned char *str, size_t length) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_DEPRECATED; EAPI Eina_Binbuf *eina_binbuf_manage_read_only_new_length(const unsigned char *str, size_t length) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_DEPRECATED;
/** /**
* @brief Free a string buffer. * @brief Frees a string buffer.
* *
* @param buf The string buffer to free. * @param buf The string buffer to free.
* *
@ -120,7 +120,7 @@ EAPI Eina_Binbuf *eina_binbuf_manage_read_only_new_length(const unsigned char *s
EAPI void eina_binbuf_free(Eina_Binbuf *buf) EINA_ARG_NONNULL(1); EAPI void eina_binbuf_free(Eina_Binbuf *buf) EINA_ARG_NONNULL(1);
/** /**
* @brief Reset a string buffer. * @brief Resets a string buffer.
* *
* @param buf The string buffer to reset. * @param buf The string buffer to reset.
* *
@ -130,7 +130,7 @@ EAPI void eina_binbuf_free(Eina_Binbuf *buf) EINA_ARG_NONNULL(1);
EAPI void eina_binbuf_reset(Eina_Binbuf *buf) EINA_ARG_NONNULL(1); EAPI void eina_binbuf_reset(Eina_Binbuf *buf) EINA_ARG_NONNULL(1);
/** /**
* @brief Expand a buffer, making room for at least @a minimum_unused_space. * @brief Expands a buffer, making room for at least @a minimum_unused_space.
* *
* One of the properties of the buffer is that it may overallocate * One of the properties of the buffer is that it may overallocate
* space, thus it may have more than eina_binbuf_length_get() bytes * space, thus it may have more than eina_binbuf_length_get() bytes
@ -161,7 +161,7 @@ EAPI void eina_binbuf_reset(Eina_Binbuf *buf) EINA_ARG_NONNULL(1);
EAPI Eina_Rw_Slice eina_binbuf_expand(Eina_Binbuf *buf, size_t minimum_unused_space) EINA_ARG_NONNULL(1); EAPI Eina_Rw_Slice eina_binbuf_expand(Eina_Binbuf *buf, size_t minimum_unused_space) EINA_ARG_NONNULL(1);
/** /**
* @brief Mark more bytes as used. * @brief Marks more bytes as used.
* *
* This function should be used after eina_binbuf_expand(), marking * This function should be used after eina_binbuf_expand(), marking
* the extra bytes returned there as used, then they will be * the extra bytes returned there as used, then they will be
@ -182,7 +182,7 @@ EAPI Eina_Rw_Slice eina_binbuf_expand(Eina_Binbuf *buf, size_t minimum_unused_sp
EAPI Eina_Bool eina_binbuf_use(Eina_Binbuf *buf, size_t extra_bytes) EINA_ARG_NONNULL(1); EAPI Eina_Bool eina_binbuf_use(Eina_Binbuf *buf, size_t extra_bytes) 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.
* *
* @param buf The string buffer to append to. * @param buf The string buffer to append to.
* @param str The string to append. * @param str The string to append.
@ -203,7 +203,7 @@ EAPI Eina_Bool eina_binbuf_use(Eina_Binbuf *buf, size_t extra_bytes) EINA_ARG_NO
EAPI Eina_Bool eina_binbuf_append_length(Eina_Binbuf *buf, const unsigned char *str, size_t length) EINA_ARG_NONNULL(1, 2); EAPI Eina_Bool eina_binbuf_append_length(Eina_Binbuf *buf, const unsigned char *str, size_t length) EINA_ARG_NONNULL(1, 2);
/** /**
* @brief Append a slice to a buffer, reallocating as necessary. * @brief Appends a slice to a buffer, reallocating as necessary.
* *
* @param buf The string buffer to append to. * @param buf The string buffer to append to.
* @param slice The slice to append. * @param slice The slice to append.
@ -217,7 +217,7 @@ EAPI Eina_Bool eina_binbuf_append_length(Eina_Binbuf *buf, const unsigned char *
EAPI Eina_Bool eina_binbuf_append_slice(Eina_Binbuf *buf, const Eina_Slice slice) EINA_ARG_NONNULL(1); EAPI Eina_Bool eina_binbuf_append_slice(Eina_Binbuf *buf, const Eina_Slice slice) EINA_ARG_NONNULL(1);
/** /**
* @brief Append an Eina_Binbuf to a buffer, reallocating as necessary. * @brief Appends an Eina_Binbuf to a buffer, reallocating as necessary.
* *
* @param buf The string buffer to append to. * @param buf The string buffer to append to.
* @param data The string buffer to append. * @param data The string buffer to append.
@ -236,7 +236,7 @@ EAPI Eina_Bool eina_binbuf_append_slice(Eina_Binbuf *buf, const Eina_Slice slice
EAPI Eina_Bool eina_binbuf_append_buffer(Eina_Binbuf *buf, const Eina_Binbuf *data) EINA_ARG_NONNULL(1, 2); 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 * @brief Appends a character to a string buffer, reallocating as
* necessary. * necessary.
* *
* @param buf The string buffer to append to. * @param buf The string buffer to append to.
@ -249,7 +249,7 @@ EAPI Eina_Bool eina_binbuf_append_buffer(Eina_Binbuf *buf, const Eina_Binbuf *da
EAPI Eina_Bool eina_binbuf_append_char(Eina_Binbuf *buf, unsigned char c) EINA_ARG_NONNULL(1); 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 to a buffer, reallocating as necessary.
* *
* @param buf The string buffer to insert to. * @param buf The string buffer to insert to.
* @param str The string to insert. * @param str The string to insert.
@ -271,7 +271,7 @@ 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); 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 slice to a buffer, reallocating as necessary. * @brief Inserts a slice to a buffer, reallocating as necessary.
* *
* @param buf The string buffer to insert to. * @param buf The string buffer to insert to.
* @param slice The slice to insert. * @param slice The slice to insert.
@ -287,7 +287,7 @@ EAPI Eina_Bool eina_binbuf_insert_length(Eina_Binbuf *buf, const unsigned char *
EAPI Eina_Bool eina_binbuf_insert_slice(Eina_Binbuf *buf, const Eina_Slice slice, size_t pos) EINA_ARG_NONNULL(1); EAPI Eina_Bool eina_binbuf_insert_slice(Eina_Binbuf *buf, const Eina_Slice slice, size_t pos) EINA_ARG_NONNULL(1);
/** /**
* @brief Insert a character to a string buffer, reallocating as * @brief Inserts a character to a string buffer, reallocating as
* necessary. * necessary.
* *
* @param buf The string buffer to insert to. * @param buf The string buffer to insert to.
@ -302,7 +302,7 @@ EAPI Eina_Bool eina_binbuf_insert_slice(Eina_Binbuf *buf, const Eina_Slice slice
EAPI Eina_Bool eina_binbuf_insert_char(Eina_Binbuf *buf, unsigned char c, size_t pos) EINA_ARG_NONNULL(1); 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. * @brief Removes a slice of the given string buffer.
* *
* @param buf The string buffer to remove a slice. * @param buf The string buffer to remove a slice.
* @param start The initial (inclusive) slice position to start * @param start The initial (inclusive) slice position to start
@ -319,7 +319,7 @@ EAPI Eina_Bool eina_binbuf_insert_char(Eina_Binbuf *buf, unsigned char c, size_t
EAPI Eina_Bool eina_binbuf_remove(Eina_Binbuf *buf, size_t start, size_t end) EINA_ARG_NONNULL(1); 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 Retrieves a pointer to the contents of a string buffer.
* *
* @param buf The string buffer. * @param buf The string buffer.
* @return The current string in the string buffer. * @return The current string in the string buffer.
@ -334,7 +334,7 @@ EAPI Eina_Bool eina_binbuf_remove(Eina_Binbuf *buf, size_t start, size_t end) EI
EAPI const unsigned char *eina_binbuf_string_get(const Eina_Binbuf *buf) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; 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. * @param buf The string buffer to steal.
* @return The current string in the string buffer. * @return The current string in the string buffer.
@ -349,7 +349,7 @@ EAPI const unsigned char *eina_binbuf_string_get(const Eina_Binbuf *buf) EINA_AR
EAPI unsigned char *eina_binbuf_string_steal(Eina_Binbuf *buf) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); 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.
* *
* @param buf The string buffer to free the string of. * @param buf The string buffer to free the string of.
* *
@ -359,7 +359,7 @@ EAPI unsigned char *eina_binbuf_string_steal(Eina_Binbuf *buf) EINA_MALLOC EINA_
EAPI void eina_binbuf_string_free(Eina_Binbuf *buf) EINA_ARG_NONNULL(1); EAPI void eina_binbuf_string_free(Eina_Binbuf *buf) EINA_ARG_NONNULL(1);
/** /**
* @brief Retrieve the length of the string buffer content. * @brief Retrieves the length of the string buffer content.
* *
* @param buf The string buffer. * @param buf The string buffer.
* @return The current length of the string, in bytes. * @return The current length of the string, in bytes.
@ -369,7 +369,7 @@ EAPI void eina_binbuf_string_free(Eina_Binbuf *buf) EINA_ARG_NONNULL(1);
EAPI size_t eina_binbuf_length_get(const Eina_Binbuf *buf) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; EAPI size_t eina_binbuf_length_get(const Eina_Binbuf *buf) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
/** /**
* @brief Get a read-only slice representing the current binbuf contents. * @brief Gets a read-only slice representing the current binbuf contents.
* *
* @param buf the src buffer. * @param buf the src buffer.
* @return a read-only slice for the current contents. It may become * @return a read-only slice for the current contents. It may become
@ -380,7 +380,7 @@ EAPI size_t eina_binbuf_length_get(const Eina_Binbuf *buf) EINA_ARG_NONNULL(1
EAPI Eina_Slice eina_binbuf_slice_get(const Eina_Binbuf *buf) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); EAPI Eina_Slice eina_binbuf_slice_get(const Eina_Binbuf *buf) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
/** /**
* @brief Get a read-write slice representing the current binbuf contents. * @brief Gets a read-write slice representing the current binbuf contents.
* *
* @param buf the src buffer. * @param buf the src buffer.
* @return a read-write slice for the current contents. It may become * @return a read-write slice for the current contents. It may become
@ -393,7 +393,7 @@ EAPI Eina_Slice eina_binbuf_slice_get(const Eina_Binbuf *buf) EINA_WARN_UNUSED_R
*/ */
EAPI Eina_Rw_Slice eina_binbuf_rw_slice_get(const Eina_Binbuf *buf) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); EAPI Eina_Rw_Slice eina_binbuf_rw_slice_get(const Eina_Binbuf *buf) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
/** /**
* @brief Get the content of the buffer and free the buffer * @brief Gets the content of the buffer and free the buffer.
* *
* @param buf the buffer to get the content from and which will be freed * @param buf the buffer to get the content from and which will be freed
* *

14
src/lib/eina/eina_binshare.h
View File

@ -129,14 +129,12 @@ EAPI void eina_binshare_del(const void *obj);
/** /**
* @brief Notes that the given object @b must be shared. * @brief Notes that the given object @b must be shared.
* * @details This function is a cheap way to know the length of a shared
* object.
* @param[in] obj The shared object to know the length \n * @param[in] obj The shared object to know the length \n
* It is safe to give @c NULL, in which case @c -1 is returned * It is safe to give @c NULL, in which case @c -1 is returned
* @return The length of the shared object * @return The length of the shared object
* *
* @details This function is a cheap way to know the length of a shared
* object.
*
* @warning If the given pointer is not shared, bad things happen, mostly a * @warning If the given pointer is not shared, bad things happen, mostly a
* segmentation fault. If in doubt, try strlen(). * segmentation fault. If in doubt, try strlen().
*/ */
@ -152,16 +150,14 @@ EAPI void eina_binshare_dump(void);
/** /**
* @brief Retrieves an instance of a blob for use in a program. * @brief Retrieves an instance of a blob for use in a program.
*
* @param ptr The binary blob to retrieve an instance of
* @return A pointer to an instance of the string on success,
* otherwise @c NULL on failure
*
* @details This macro retrieves an instance of @p obj. If @p obj is * @details This macro retrieves an instance of @p obj. If @p obj is
* @c NULL, then @c NULL is returned. If @p obj is already stored, it * @c NULL, then @c NULL is returned. If @p obj is already stored, it
* is just returned and its reference counter is increased. Otherwise * is just returned and its reference counter is increased. Otherwise
* it is added to the blobs to be searched and a duplicated blob * it is added to the blobs to be searched and a duplicated blob
* of @p obj is returned. * of @p obj is returned.
* @param ptr The binary blob to retrieve an instance of
* @return A pointer to an instance of the string on success,
* otherwise @c NULL on failure
* *
* @note This macro essentially calls eina_binshare_add_length with ptr and sizeof(*ptr) * @note This macro essentially calls eina_binshare_add_length with ptr and sizeof(*ptr)
* as the parameters. It's useful for pointers to structures. * as the parameters. It's useful for pointers to structures.

13
src/lib/eina/eina_clist.h
View File

@ -169,14 +169,13 @@ static inline void eina_clist_add_tail(Eina_Clist *list, Eina_Clist *elem);
/** /**
* @brief Inits an (unlinked) element. * @brief Inits an (unlinked) element.
* @details This function is called on elements that have not been added to the list
* so that eina_clist_element_init() works correctly.
* *
* @param[in] elem An element * @param[in] elem An element
* @pre The element is not in any list. * @pre The element is not in any list.
* @post The element is marked as not being in any list. * @post The element is marked as not being in any list.
* *
* @details This function is called on elements that have not been added to the list
* so that eina_clist_element_init() works correctly.
*
* @note It is not necessary to call this before adding an element to this list. * @note It is not necessary to call this before adding an element to this list.
* *
* @since 1.1.0 * @since 1.1.0
@ -324,7 +323,7 @@ static inline void eina_clist_move_head(Eina_Clist *dst, Eina_Clist *src);
* @brief Iterates through the list, with safety against removal. * @brief Iterates through the list, with safety against removal.
* *
* @param cursor The pointer to be used during the interaction * @param cursor The pointer to be used during the interaction
* @param cursor2 The auxiliar pointer to be used during the interaction * @param cursor2 The auxiliary pointer to be used during the interaction
* @param list The list to be interacted with * @param list The list to be interacted with
*/ */
#define EINA_CLIST_FOR_EACH_SAFE(cursor, cursor2, list) \ #define EINA_CLIST_FOR_EACH_SAFE(cursor, cursor2, list) \
@ -351,7 +350,7 @@ static inline void eina_clist_move_head(Eina_Clist *dst, Eina_Clist *src);
* @brief Iterates through the list using a list entry, with safety against removal. * @brief Iterates through the list using a list entry, with safety against removal.
* *
* @param cursor The pointer to be used during the interaction * @param cursor The pointer to be used during the interaction
* @param cursor2 The auxiliar pointer to be used during the interaction * @param cursor2 The auxiliary pointer to be used during the interaction
* @param list The list to be interacted with * @param list The list to be interacted with
* @param type The type of the list * @param type The type of the list
* @param field The field of the element * @param field The field of the element
@ -378,7 +377,7 @@ static inline void eina_clist_move_head(Eina_Clist *dst, Eina_Clist *src);
* @brief Iterates through the list in the reverse order, with safety against removal. * @brief Iterates through the list in the reverse order, with safety against removal.
* *
* @param cursor The pointer to be used during the interaction * @param cursor The pointer to be used during the interaction
* @param cursor2 The auxiliar pointer to be used during the interaction * @param cursor2 The auxiliary pointer to be used during the interaction
* @param list The list to be interacted with * @param list The list to be interacted with
*/ */
#define EINA_CLIST_FOR_EACH_SAFE_REV(cursor, cursor2, list) \ #define EINA_CLIST_FOR_EACH_SAFE_REV(cursor, cursor2, list) \
@ -406,7 +405,7 @@ static inline void eina_clist_move_head(Eina_Clist *dst, Eina_Clist *src);
* removal. * removal.
* *
* @param cursor The pointer to be used during the interaction * @param cursor The pointer to be used during the interaction
* @param cursor2 The auxiliar pointer to be used during the interaction * @param cursor2 The auxiliary pointer to be used during the interaction
* @param list The list to be interacted with * @param list The list to be interacted with
* @param type The type of the list * @param type The type of the list
* @param field The field of the element * @param field The field of the element

56
src/lib/eina/eina_convert.h
View File

@ -92,15 +92,15 @@
* *
* To convert a string to a double, eina_convert_atod() should be * 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 * used. The format of the string must be as above. Then, the double
* has the following mantiss and exponent: * has the following mantissas and exponent:
* *
* @code * @code
* mantiss : [-]hhhhhh * mantiss : [-]hhhhhh
* exponent : 2^([+-]e - 4 * n) * exponent : 2^([+-]e - 4 * n)
* @endcode * @endcode
* *
* with n being number of cypers after the point in the string * with n being number of cyphers after the point in the string
* format. To obtain the double number from the mantiss and exponent, * format. To obtain the double number from the mantissas and exponent,
* use ldexp(). * use ldexp().
* *
* Here is an example of use: * Here is an example of use:
@ -163,31 +163,31 @@ EAPI extern Eina_Error EINA_ERROR_CONVERT_0X_NOT_FOUND; /**< Not used, perhaps a
EAPI extern Eina_Error EINA_ERROR_CONVERT_OUTRUN_STRING_LENGTH; /**< 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*/
/** /**
* @brief Convert an integer number to a string in decimal base. * @brief Converts an integer number to a string in decimal base.
* *
* @param n The integer to convert. * @param n The integer to convert.
* @param s The buffer to store the converted integer. * @param s The buffer to store the converted integer.
* @return The length of the string, including the nul terminated * @return The length of the string, including the null terminated
* character. * character.
* *
* This function converts @p n to a nul terminated string. The * This function converts @p n to a null terminated string. The
* converted string is in decimal base. As no check is done, @p s must * 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. * be a buffer that is sufficiently large to store the integer.
* *
* The returned value is the length of the string, including the nul * The returned value is the length of the string, including the null
* terminated character. * terminated character.
*/ */
EAPI int eina_convert_itoa(int n, char *s) EINA_ARG_NONNULL(2); 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.
* *
* @param n The integer to convert. * @param n The integer to convert.
* @param s The buffer to store the converted integer. * @param s The buffer to store the converted integer.
* @return The length of the string, including the nul terminated * @return The length of the string, including the null terminated
* character. * character.
* *
* This function converts @p n to a nul terminated string. The * This function converts @p n to a null terminated string. The
* converted string is in hexadecimal base and the alphabetical * converted string is in hexadecimal base and the alphabetical
* cyphers are in lower case. As no check is done, @p s must be a * cyphers are in lower case. As no check is done, @p s must be a
* buffer that is sufficiently large to store the integer. * buffer that is sufficiently large to store the integer.
@ -199,7 +199,7 @@ 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 d The double to convert.
* @param des The destination buffer to store the converted double. * @param des The destination buffer to store the converted double.
@ -207,27 +207,27 @@ EAPI int eina_convert_xtoa(unsigned int n, char *s) EINA_ARG_NONNULL(2);
* *
* This function converts the double @p d to a string. The string is * 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 * stored in the buffer pointed by @p des and must be sufficiently
* large to contain the converted double. The returned string is nul * large to contain the converted double. The returned string is null
* terminated and has the following format: * terminated and has the following format:
* *
* @code * @code
* [-]0xh.hhhhhp[+-]e * [-]0xh.hhhhhp[+-]e
* @endcode * @endcode
* *
* where the h are the hexadecimal cyphers of the mantiss and e the * where the h are the hexadecimal cyphers of the mantissas and e the
* exponent (a decimal number). * exponent (a decimal number).
* *
* The returned value is the length of the string, including the nul * The returned value is the length of the string, including the null
* character. * character.
*/ */
EAPI int eina_convert_dtoa(double d, char *des) EINA_ARG_NONNULL(2); 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 src The string to convert.
* @param length The length of the string. * @param length The length of the string.
* @param m The mantisse. * @param m The mantissa.
* @param e The exponent. * @param e The exponent.
* @return #EINA_TRUE on success, #EINA_FALSE otherwise. * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
* *
@ -242,16 +242,16 @@ EAPI int eina_convert_dtoa(double d, char *des) EINA_ARG_NONNULL(2);
* [-]0xh.hhhhhp[+-]e * [-]0xh.hhhhhp[+-]e
* @endcode * @endcode
* *
* where the h are the hexadecimal cyphers of the mantiss and e the * where the h are the hexadecimal cyphers of the mantissas and e the
* exponent (a decimal number). If n is the number of cypers after the * exponent (a decimal number). If n is the number of cyphers after the
* point, the returned mantiss and exponents are: * point, the returned mantissas and exponents are:
* *
* @code * @code
* mantiss : [-]hhhhhh * mantiss : [-]hhhhhh
* exponent : 2^([+-]e - 4 * n) * exponent : 2^([+-]e - 4 * n)
* @endcode * @endcode
* *
* The mantiss and exponent are stored in the buffers pointed * The mantissas and exponent are stored in the buffers pointed
* respectively by @p m and @p e. * respectively by @p m and @p e.
* *
* If the string is invalid #EINA_FALSE is returned, otherwise #EINA_TRUE is * If the string is invalid #EINA_FALSE is returned, otherwise #EINA_TRUE is
@ -264,7 +264,7 @@ 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 fp The fixed point number to convert.
* @param des The destination buffer to store the converted fixed point number. * @param des The destination buffer to store the converted fixed point number.
@ -280,10 +280,10 @@ EAPI Eina_Bool eina_convert_atod(const char *src,
* [-]0xh.hhhhhp[+-]e * [-]0xh.hhhhhp[+-]e
* @endcode * @endcode
* *
* where the h are the hexadecimal cyphers of the mantiss and e the * where the h are the hexadecimal cyphers of the mantissas and e the
* exponent (a decimal number). * exponent (a decimal number).
* *
* The returned value is the length of the string, including the nul * The returned value is the length of the string, including the null
* character. * character.
* *
* @note The code is the same than eina_convert_dtoa() except that it * @note The code is the same than eina_convert_dtoa() except that it
@ -294,7 +294,7 @@ EAPI int eina_convert_fptoa(Eina_F32p32 fp,
char *des) EINA_ARG_NONNULL(2); 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 src The string to convert.
* @param length The length of the string. * @param length The length of the string.
@ -312,16 +312,16 @@ EAPI int eina_convert_fptoa(Eina_F32p32 fp,
* [-]0xh.hhhhhp[+-]e * [-]0xh.hhhhhp[+-]e
* @endcode * @endcode
* *
* where the h are the hexadecimal cyphers of the mantiss and e the * where the h are the hexadecimal cyphers of the mantissas and e the
* exponent (a decimal number). If n is the number of cypers after the * exponent (a decimal number). If n is the number of cyphers after the
* point, the returned mantiss and exponents are: * point, the returned mantissas and exponents are:
* *
* @code * @code
* mantiss : [-]hhhhhh * mantiss : [-]hhhhhh
* exponent : 2^([+-]e - 4 * n) * exponent : 2^([+-]e - 4 * n)
* @endcode * @endcode
* *
* The mantiss and exponent are stored in the buffers pointed * The mantissas and exponent are stored in the buffers pointed
* respectively by @p m and @p e. * respectively by @p m and @p e.
* *
* If the string is invalid, #EINA_FALSE is returned, * If the string is invalid, #EINA_FALSE is returned,

31
src/lib/eina/eina_counter.h
View File

@ -114,14 +114,13 @@ typedef struct _Eina_Counter Eina_Counter;
/** /**
* @brief Returns a counter. * @brief Returns a counter.
*
* @param[in] name The name of the counter
* @return A newly allocated counter
*
* @details This function returns a new counter. It is characterized by @p * @details This function returns a new counter. It is characterized by @p
* name. If @p name is @c NULL, the function returns @c NULL * name. If @p name is @c NULL, the function returns @c NULL
* immediately. If memory allocation fails, @c NULL is returned. * immediately. If memory allocation fails, @c NULL is returned.
* *
* @param[in] name The name of the counter
* @return A newly allocated counter
*
* @note Whe the new counter is not needed anymore, use eina_counter_free() to * @note Whe the new counter is not needed anymore, use eina_counter_free() to
* free the allocated memory. * free the allocated memory.
*/ */
@ -129,25 +128,23 @@ EAPI Eina_Counter *eina_counter_new(const char *name) EINA_WARN_UNUSED_RESULT EI
/** /**
* @brief Deletes a counter. * @brief Deletes a counter.
*
* @param[in] counter The counter to delete
*
* @details This function removes the clock of @p counter from the used clocks * @details This function removes the clock of @p counter from the used clocks
* (see eina_counter_start()) and frees the memory allocated for * (see eina_counter_start()) and frees the memory allocated for
* @p counter. If @p counter is @c NULL, the function returns * @p counter. If @p counter is @c NULL, the function returns
* immediately. * immediately.
* @param[in] counter The counter to delete
*
*/ */
EAPI void eina_counter_free(Eina_Counter *counter) EINA_ARG_NONNULL(1); EAPI void eina_counter_free(Eina_Counter *counter) EINA_ARG_NONNULL(1);
/** /**
* @brief Starts the time count. * @brief Starts the time count.
*
* @param[in] counter The counter
*
* @details This function specifies that the part of the code beginning just * @details This function specifies that the part of the code beginning just
* after its call is being timed, using @p counter. If * after its call is being timed, using @p counter. If
* @p counter is @c NULL, this function returns immediately. * @p counter is @c NULL, this function returns immediately.
* *
* @param[in] counter The counter
*
* @note This function adds the clock associated to @p counter in a list. If * @note This function adds the clock associated to @p counter in a list. If
* the memory needed by that clock can not be allocated, the function * the memory needed by that clock can not be allocated, the function
* returns and nothing is done. * returns and nothing is done.
@ -159,30 +156,28 @@ EAPI void eina_counter_start(Eina_Counter *counter) EINA_ARG_NONNULL(1)
/** /**
* @brief Stops the time count. * @brief Stops the time count.
*
* @param[in] counter The counter
* @param[in] specimen The number of the test
*
* @details This function stops the timing that has been started with * @details This function stops the timing that has been started with
* eina_counter_start(). @p counter must be the same as the one used * eina_counter_start(). @p counter must be the same as the one used
* with eina_counter_start(). @p specimen is the number of the * with eina_counter_start(). @p specimen is the number of the
* test. If @p counter or its associated clock is @c NULL, or if the * test. If @p counter or its associated clock is @c NULL, or if the
* time can't be retrieved the function exits. * time can't be retrieved the function exits.
* @param[in] counter The counter
* @param[in] specimen The number of the test
*
*/ */
EAPI void eina_counter_stop(Eina_Counter *counter, EAPI void eina_counter_stop(Eina_Counter *counter,
int specimen) EINA_ARG_NONNULL(1); int specimen) EINA_ARG_NONNULL(1);
/** /**
* @brief Dumps the result of all the clocks of a counter to a stream. * @brief Dumps the result of all the clocks of a counter to a stream.
*
* @param[in] counter The counter
* @return A string with a summary of the test
*
* @details This function returns an malloc'd string containing the dump of * @details This function returns an malloc'd string containing the dump of
* all the valid clocks of @p counter. * all the valid clocks of @p counter.
* If @p counter is @c NULL, the functions exits * If @p counter is @c NULL, the functions exits
* immediately. Otherwise, the output is formatted like this: * immediately. Otherwise, the output is formatted like this:
* *
* @param[in] counter The counter
* @return A string with a summary of the test
*
* @verbatim * @verbatim
* \# specimen experiment time starting time ending time * \# specimen experiment time starting time ending time
* 1 208 120000 120208 * 1 208 120000 120208

22
src/lib/eina/eina_cow.h
View File

@ -52,33 +52,33 @@ typedef struct _Eina_Cow Eina_Cow;
typedef void Eina_Cow_Data; typedef void Eina_Cow_Data;
/** /**
* @brief Instantiate a new Eina_Cow pool. * @brief Instantiates a new Eina_Cow pool.
* *
* @param name The name of this pool, used for debug. * @param name The name of this pool, used for debug.
* @param struct_size The size of the object from this pool. * @param struct_size The size of the object from this pool.
* @param step How many objects to allocate when the pool gets empty. * @param step How many objects to allocate when the pool gets empty.
* @param default_value The default value returned by this pool. * @param default_value The default value returned by this pool.
* @param gc Is it possible to run garbage collection on this pool. * @param gc Is it possible to run garbage collection on this pool.
* @return a valid new Eina_Cow or @c NULL on error. * @return A valid new Eina_Cow, or @c NULL on error.
*/ */
EAPI Eina_Cow *eina_cow_add(const char *name, unsigned int struct_size, unsigned int step, const void *default_value, Eina_Bool gc) EINA_WARN_UNUSED_RESULT; EAPI Eina_Cow *eina_cow_add(const char *name, unsigned int struct_size, unsigned int step, const void *default_value, Eina_Bool gc) EINA_WARN_UNUSED_RESULT;
/** /**
* @brief Destroy an Eina_Cow pool and all the allocated memory * @brief Destroys an Eina_Cow pool and all the allocated memory.
* *
* @param cow The pool to destroy * @param cow The pool to destroy
*/ */
EAPI void eina_cow_del(Eina_Cow *cow); EAPI void eina_cow_del(Eina_Cow *cow);
/** /**
* @brief Return an initialized pointer from the pool. * @brief Returns an initialized pointer from the pool.
* @param cow The pool to take things from. * @param cow The pool to take things from.
* @return A pointer to the new pool instance * @return A pointer to the new pool instance
*/ */
EAPI const Eina_Cow_Data *eina_cow_alloc(Eina_Cow *cow) EINA_WARN_UNUSED_RESULT; EAPI const Eina_Cow_Data *eina_cow_alloc(Eina_Cow *cow) EINA_WARN_UNUSED_RESULT;
/** /**
* @brief Free a pointer from the pool. * @brief Frees a pointer from the pool.
* @param cow The pool to gave back memory to. * @param cow The pool to gave back memory to.
* @param data The data to give back. * @param data The data to give back.
* *
@ -88,7 +88,7 @@ EAPI const Eina_Cow_Data *eina_cow_alloc(Eina_Cow *cow) EINA_WARN_UNUSED_RESULT;
EAPI void eina_cow_free(Eina_Cow *cow, const Eina_Cow_Data **data); EAPI void eina_cow_free(Eina_Cow *cow, const Eina_Cow_Data **data);
/** /**
* @brief Get a writable pointer from a const pointer. * @brief Gets a writeable pointer from a const pointer.
* @param cow The pool the pointer come from. * @param cow The pool the pointer come from.
* @param src The pointer you want to write to. * @param src The pointer you want to write to.
* *
@ -97,7 +97,7 @@ EAPI void eina_cow_free(Eina_Cow *cow, const Eina_Cow_Data **data);
EAPI void *eina_cow_write(Eina_Cow *cow, EAPI void *eina_cow_write(Eina_Cow *cow,
const Eina_Cow_Data * const *src) EINA_WARN_UNUSED_RESULT; const Eina_Cow_Data * const *src) EINA_WARN_UNUSED_RESULT;
/** /**
* @brief Set back a pointer into read only. * @brief Sets back a pointer into read only.
* @param cow The pool the pointer come from. * @param cow The pool the pointer come from.
* @param dst The read only version of the pointer. * @param dst The read only version of the pointer.
* @param data The pointer to which data was written to. * @param data The pointer to which data was written to.
@ -110,7 +110,7 @@ EAPI void eina_cow_done(Eina_Cow *cow,
const void *data, const void *data,
Eina_Bool needed_gc); Eina_Bool needed_gc);
/** /**
* @brief Make the destination contain the same thing as the source pointer. * @brief Makes the destination contain the same thing as the source pointer.
* @param cow The pool the pointers come from. * @param cow The pool the pointers come from.
* @param dst The destination to update. * @param dst The destination to update.
* @param src The source of information to copy. * @param src The source of information to copy.
@ -120,7 +120,7 @@ EAPI void eina_cow_memcpy(Eina_Cow *cow,
const Eina_Cow_Data *src); const Eina_Cow_Data *src);
/** /**
* @brief Try to find entries that have the same content and update them. * @brief Tries to find entries that have the same content and update them.
* @param cow The cow to try to compact. * @param cow The cow to try to compact.
* @return EINA_TRUE if something was compacted, EINA_FALSE if nothing was. * @return EINA_TRUE if something was compacted, EINA_FALSE if nothing was.
* *
@ -132,7 +132,7 @@ EAPI Eina_Bool eina_cow_gc(Eina_Cow *cow);
/** /**
* @def EINA_COW_WRITE_BEGIN * @def EINA_COW_WRITE_BEGIN
* @brief This macro setup a writable pointer from a const one. * @brief Definition for the macro to setup a writeable pointer from a const one.
* @param Cow The Eina_Cow where the const pointer come from. * @param Cow The Eina_Cow where the const pointer come from.
* @param Read The const pointer to get a writable handler from. * @param Read The const pointer to get a writable handler from.
* @param Write_Type The type of the pointer you want to write to. * @param Write_Type The type of the pointer you want to write to.
@ -151,7 +151,7 @@ EAPI Eina_Bool eina_cow_gc(Eina_Cow *cow);
/** /**
* @def EINA_COW_WRITE_END * @def EINA_COW_WRITE_END
* @brief This macro close the writable pointer. * @brief Definition for the macro to close the writeable pointer.
* @param Cow The Eina_Cow where the const pointer come from. * @param Cow The Eina_Cow where the const pointer come from.
* @param Read The const pointer to get a writable handler from. * @param Read The const pointer to get a writable handler from.
* @param Write The name of the variable where to put the writeable pointer to. * @param Write The name of the variable where to put the writeable pointer to.

18
src/lib/eina/eina_cpu.h
View File

@ -59,31 +59,31 @@ typedef enum _Eina_Cpu_Features
} Eina_Cpu_Features; } Eina_Cpu_Features;
/** /**
* @brief Global hardware architecture handler * @brief Global hardware architecture handler.
* *
* @return the current cpu features * @return the current cpu features
*/ */
EAPI extern Eina_Cpu_Features eina_cpu_features; EAPI extern Eina_Cpu_Features eina_cpu_features;
/** /**
* @brief Cpu features accessor * @brief Cpu features accessor.
* *
* @return the current cpu features * @return the current cpu features
*/ */
EAPI Eina_Cpu_Features eina_cpu_features_get(void); EAPI Eina_Cpu_Features eina_cpu_features_get(void);
/** /**
* @brief Get the current number of processors * @brief Gets the current number of processors.
* *
* @return the number of processors that are online, that * @return The number of processors that are online, that
* is available when the function is called. * is available when the function is called.
*/ */
EAPI int eina_cpu_count(void); EAPI int eina_cpu_count(void);
/** /**
* @brief Get the current virtual page size * @brief Gets the current virtual page size.
* *
* @return the fixed length that represents the smallest unit of data for memory * @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 * allocation performed by the operating system on behalf of the program, and
* for transfers between the main memory and any other auxiliary store. * for transfers between the main memory and any other auxiliary store.
*/ */
@ -93,7 +93,7 @@ EAPI int eina_cpu_page_size(void);
* @brief Reverses the byte order of a 16-bit (destination) register. * @brief Reverses the byte order of a 16-bit (destination) register.
* *
* @param x The binary word to swap * @param x The binary word to swap
* @return a byte order swapped 16-bit integer. * @return A byte order swapped 16-bit integer.
* *
* On big endian systems, the number is converted to little endian byte order. * 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. * On little endian systems, the number is converted to big endian byte order.
@ -104,7 +104,7 @@ static inline unsigned short eina_swap16(unsigned short x);
* @brief Reverses the byte order of a 32-bit (destination) register. * @brief Reverses the byte order of a 32-bit (destination) register.
* *
* @param x The binary word to swap * @param x The binary word to swap
* @return a byte order swapped 32-bit integer. * @return A byte order swapped 32-bit integer.
* *
* On big endian systems, the number is converted to little endian byte order. * 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. * On little endian systems, the number is converted to big endian byte order.
@ -115,7 +115,7 @@ static inline unsigned int eina_swap32(unsigned int x);
* @brief Reverses the byte order of a 64-bit (destination) register. * @brief Reverses the byte order of a 64-bit (destination) register.
* *
* @param x The binary word to swap * @param x The binary word to swap
* @return a byte order swapped 64-bit integer. * @return A byte order swapped 64-bit integer.
* *
* On big endian systems, the number is converted to little endian byte order. * 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. * On little endian systems, the number is converted to big endian byte order.

2
src/lib/eina/eina_crc.h
View File

@ -12,7 +12,7 @@
#include "eina_magic.h" #include "eina_magic.h"
/** /**
* @brief Generate a crc checksum for the given data using crc-32 algorithm. * @brief Generates a crc checksum for the given data using crc-32 algorithm.
* *
* @param key The data for which crc checksum has to be generated. * @param key The data for which crc checksum has to be generated.
* @param len The length of the data. * @param len The length of the data.

49
src/lib/eina/eina_error.h
View File

@ -107,16 +107,15 @@ EAPI extern Eina_Error EINA_ERROR_OUT_OF_MEMORY EINA_DEPRECATED; /* use ENOMEM *
/** /**
* @brief Registers a new error type. * @brief Registers a new error type.
*
* @param[in] msg The description of the error \n
* It is duplicated using eina_stringshare_add().
* @return The unique number identifier for this error
*
* @details This function stores the error message described by * @details This function stores the error message described by
* @p msg in a list. The returned value is a unique identifier greater than or equal * @p msg in a list. The returned value is a unique identifier greater than or equal
* to @c 1. The description can be retrieved later by passing * to @c 1. The description can be retrieved later by passing
* the returned value to eina_error_msg_get(). * the returned value to eina_error_msg_get().
* *
* @param[in] msg The description of the error \n
* It is duplicated using eina_stringshare_add().
* @return The unique number identifier for this error
*
* @note There is no need to register messages that exist in libC's @c * @note There is no need to register messages that exist in libC's @c
* errno.h, such as @c ENOMEM or @c EBADF. * errno.h, such as @c ENOMEM or @c EBADF.
* *
@ -126,17 +125,16 @@ EAPI Eina_Error eina_error_msg_register(const char *msg) EINA_ARG_NONNULL(1) EI
/** /**
* @brief Registers a new error type, statically allocated message. * @brief Registers a new error type, statically allocated message.
* @details This function stores the error message described by
* @p msg in a list. The returned value is a unique identifier greater than or equal
* to @c 1. The description can be retrieved later by passing
* the returned value to eina_error_msg_get().
* *
* @param[in] msg The description of the error \n * @param[in] msg The description of the error \n
* This string is not duplicated and thus * This string is not duplicated and thus
* the given pointer should live during the usage of eina_error. * the given pointer should live during the usage of eina_error.
* @return The unique number identifier for this error * @return The unique number identifier for this error
* *
* @details This function stores the error message described by
* @p msg in a list. The returned value is a unique identifier greater than or equal
* to @c 1. The description can be retrieved later by passing
* the returned value to eina_error_msg_get().
*
* @note There is no need to register messages that exist in libC's @c * @note There is no need to register messages that exist in libC's @c
* errno.h, such as @c ENOMEM or @c EBADF. * errno.h, such as @c ENOMEM or @c EBADF.
* *
@ -146,6 +144,10 @@ EAPI Eina_Error eina_error_msg_static_register(const char *msg) EINA_ARG_NONNUL
/** /**
* @brief Changes the message of an already registered message. * @brief Changes the message of an already registered message.
* @details This function modifies the message associated with @p error and changes
* it to @p msg. If the error is previously registered by @ref eina_error_msg_static_register
* then the string is not duplicated, otherwise the previous message
* is unrefed and @p msg is copied.
* *
* @param[in] error The Eina_Error to change the message of * @param[in] error The Eina_Error to change the message of
* @param[in] msg The description of the error \n * @param[in] msg The description of the error \n
@ -153,11 +155,6 @@ EAPI Eina_Error eina_error_msg_static_register(const char *msg) EINA_ARG_NONNUL
* otherwise it must remain intact for the duration. * otherwise it must remain intact for the duration.
* @return #EINA_TRUE if successful, otherwise #EINA_FALSE on error * @return #EINA_TRUE if successful, otherwise #EINA_FALSE on error
* *
* @details This function modifies the message associated with @p error and changes
* it to @p msg. If the error is previously registered by @ref eina_error_msg_static_register
* then the string is not duplicated, otherwise the previous message
* is unrefed and @p msg is copied.
*
* @note It is not possible to modify messages that exist in libC's @c * @note It is not possible to modify messages that exist in libC's @c
* errno.h, such as @c ENOMEM or @c EBADF. * errno.h, such as @c ENOMEM or @c EBADF.
* *
@ -169,24 +166,22 @@ EAPI Eina_Bool eina_error_msg_modify(Eina_Error error,
/** /**
* @brief Returns the last set error. * @brief Returns the last set error.
*
* @return The last error or 0 (#EINA_ERROR_NO_ERROR).
*
* @details This function returns the last error set by eina_error_set(). The * @details This function returns the last error set by eina_error_set(). The
* description of the message is returned by eina_error_msg_get(). * description of the message is returned by eina_error_msg_get().
* *
* @return The last error or 0 (#EINA_ERROR_NO_ERROR).
*
* @note This function is thread safe @since 1.10, but slower to use. * @note This function is thread safe @since 1.10, but slower to use.
*/ */
EAPI Eina_Error eina_error_get(void); EAPI Eina_Error eina_error_get(void);
/** /**
* @brief Sets the last error. * @brief Sets the last error.
*
* @param[in] err The error identifier
*
* @details This function sets the last error identifier. The last error can be * @details This function sets the last error identifier. The last error can be
* retrieved by eina_error_get(). * retrieved by eina_error_get().
* *
* @param[in] err The error identifier
*
* @note This is also used to clear previous errors, in which case @p err should * @note This is also used to clear previous errors, in which case @p err should
* be @c 0 (#EINA_ERROR_NO_ERROR). * be @c 0 (#EINA_ERROR_NO_ERROR).
* *
@ -196,25 +191,23 @@ EAPI void eina_error_set(Eina_Error err);
/** /**
* @brief Returns the description of the given error number. * @brief Returns the description of the given error number.
*
* @param[in] error The error number
* @return The description of the error
*
* @details This function returns the description of an error that has been * @details This function returns the description of an error that has been
* registered by eina_error_msg_register(). If an incorrect error is * registered by eina_error_msg_register(). If an incorrect error is
* given, then @c NULL is returned. * given, then @c NULL is returned.
* @param[in] error The error number
* @return The description of the error
*
*/ */
EAPI const char *eina_error_msg_get(Eina_Error error) EINA_PURE; EAPI const char *eina_error_msg_get(Eina_Error error) EINA_PURE;
/** /**
* @brief Finds the #Eina_Error corresponding to a message string. * @brief Finds the #Eina_Error corresponding to a message string.
* @details This function attempts to match @p msg with its corresponding #Eina_Error value.
* If no such value is found, @c 0 is returned.
* *
* @param[in] msg The error message string to match (NOT @c NULL) * @param[in] msg The error message string to match (NOT @c NULL)
* @return The #Eina_Error matching @p msg, otherwise @c 0 on failure * @return The #Eina_Error matching @p msg, otherwise @c 0 on failure
* *
* @details This function attempts to match @p msg with its corresponding #Eina_Error value.
* If no such value is found, @c 0 is returned.
*
* @note this function only works for explicitly registered errors * @note this function only works for explicitly registered errors
* such as the messages given to eina_error_msg_register(), * such as the messages given to eina_error_msg_register(),
* eina_error_msg_static_register() or modified with * eina_error_msg_static_register() or modified with

8
src/lib/eina/eina_evlog.h
View File

@ -56,7 +56,7 @@ struct _Eina_Evlog_Buf
}; };
/** /**
* @brief Log an event in our event log for profiling data * @brief Logs an event in our event log for profiling data.
* *
* Log some interesting event inside of EFL, eg a wakeup (and why etc.). * Log some interesting event inside of EFL, eg a wakeup (and why etc.).
* The @p event string must alwasy be provided and be of the form: * The @p event string must alwasy be provided and be of the form:
@ -117,7 +117,7 @@ EAPI void
eina_evlog(const char *event, void *obj, double srctime, const char *detail); eina_evlog(const char *event, void *obj, double srctime, const char *detail);
/** /**
* @brief Steal an event log buffer from the evlog core * @brief Steals an event log buffer from the evlog core.
* *
* Only one buffer can be stolen at any time. If you steal a new buffer, the * Only one buffer can be stolen at any time. If you steal a new buffer, the
* old stolen buffer is "released" back to the evlog core. * old stolen buffer is "released" back to the evlog core.
@ -130,7 +130,7 @@ EAPI Eina_Evlog_Buf *
eina_evlog_steal(void); eina_evlog_steal(void);
/** /**
* @brief Begin logging - until now eina_evlog is a NOOP * @brief Begins logging - until now eina_evlog is a NOOP.
* *
* @since 1.15 * @since 1.15
*/ */
@ -138,7 +138,7 @@ EAPI void
eina_evlog_start(void); eina_evlog_start(void);
/** /**
* @brief Stop logging * @brief Stops logging.
* *
* You must not be using any evlog buffers stolen by eina_evlog_steal() by * You must not be using any evlog buffers stolen by eina_evlog_steal() by
* the time you call this function. * the time you call this function.

156
src/lib/eina/eina_file.h
View File

@ -71,7 +71,7 @@
* @brief This group discusses the functions to handle files and directories. * @brief This group discusses the functions to handle files and directories.
* *
* @details These functions make it easier to do a number of file and directory operations * @details These functions make it easier to do a number of file and directory operations
* such as getting the list of files in a directory, spliting paths, and finding * such as getting the list of files in a directory, splitting paths, and finding
* out file size and type. * out file size and type.
* *
* @warning All functions in this group are @b blocking, which means they may * @warning All functions in this group are @b blocking, which means they may
@ -159,7 +159,7 @@ typedef enum {
* it never happens */ * it never happens */
/** /**
* @def EINA_PATH_MAX * @def EINA_PATH_MAX
* @brief The constant defined as the highest value for PATH_MAX. * @brief Definition for the constant defined as the highest value for PATH_MAX.
*/ */
#define EINA_PATH_MAX 8192 #define EINA_PATH_MAX 8192
@ -239,23 +239,15 @@ struct _Eina_File_Line
/** /**
* @def EINA_FILE_DIR_LIST_CB * @def EINA_FILE_DIR_LIST_CB
* @brief The macro to cast to an #Eina_File_Dir_List_Cb. * @brief The macro to cast to an #Eina_File_Dir_List_Cb.
* * @details This macro casts @p function to #Eina_File_Dir_List_Cb.
* @param function The function to cast * @param function The function to cast
* *
* @details This macro casts @p function to #Eina_File_Dir_List_Cb.
*/ */
#define EINA_FILE_DIR_LIST_CB(function) ((Eina_File_Dir_List_Cb)function) #define EINA_FILE_DIR_LIST_CB(function) ((Eina_File_Dir_List_Cb)function)
/** /**
* @brief Lists all the files on the directory by calling the function for every file found. * @brief Lists all the files on the directory by calling the function for every file found.
*
* @param[in] dir The directory name
* @param[in] recursive Iterate recursively in the directory
* @param[in] cb The callback to be called
* @param[in] data The data to pass to the callback
* @return #EINA_TRUE on success, otherwise #EINA_FALSE
*
* @details This function calls @p cb for each file that is in @p dir. To have @p cb * @details This function calls @p cb for each file that is in @p dir. To have @p cb
* called on the files that are in subdirectories of @p dir, @p recursive should * called on the files that are in subdirectories of @p dir, @p recursive should
* be #EINA_TRUE. In other words, if @p recursive is #EINA_FALSE, only direct children * be #EINA_TRUE. In other words, if @p recursive is #EINA_FALSE, only direct children
@ -265,6 +257,12 @@ struct _Eina_File_Line
* If @p cb or @p dir is @c NULL or if @p dir is a string of size 0, * If @p cb or @p dir is @c NULL or if @p dir is a string of size 0,
* or if @p dir cannot be opened, this function returns #EINA_FALSE * or if @p dir cannot be opened, this function returns #EINA_FALSE
* immediately. Otherwise, it returns #EINA_TRUE. * immediately. Otherwise, it returns #EINA_TRUE.
*
* @param[in] dir The directory name
* @param[in] recursive Iterate recursively in the directory
* @param[in] cb The callback to be called
* @param[in] data The data to pass to the callback
* @return #EINA_TRUE on success, otherwise #EINA_FALSE
*/ */
EAPI Eina_Bool eina_file_dir_list(const char *dir, EAPI Eina_Bool eina_file_dir_list(const char *dir,
Eina_Bool recursive, Eina_Bool recursive,
@ -273,28 +271,27 @@ EAPI Eina_Bool eina_file_dir_list(const char *dir,
/** /**
* @brief Splits a path according to the delimiter of the filesystem. * @brief Splits a path according to the delimiter of the filesystem.
*
* @param[in] path The path to split
* @return An array of the parts of the path to split
*
* @details This function splits @p path according to the delimiter of the used * @details This function splits @p path according to the delimiter of the used
* filesystem. If @p path is @c NULL or if the array cannot be * filesystem. If @p path is @c NULL or if the array cannot be
* created, @c NULL is returned, otherwise an array with each part of @p path * created, @c NULL is returned, otherwise an array with each part of @p path
* is returned. * is returned.
*
* @param[in] path The path to split
* @return An array of the parts of the path to split
*
*/ */
EAPI Eina_Array *eina_file_split(char *path) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; EAPI Eina_Array *eina_file_split(char *path) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
/** /**
* @brief Gets an iterator to list the content of a directory. * @brief Gets an iterator to list the content of a directory.
* @details This returns an iterator for shared strings, the name of each file in @p dir is
* only fetched when advancing the iterator, which means there is very little
* cost associated with creating the list and stopping halfway through it.
* *
* @param [in] dir The name of the directory to list * @param [in] dir The name of the directory to list
* @return An #Eina_Iterator that walks over the files and directories * @return An #Eina_Iterator that walks over the files and directories
* in @p dir. On failure, it returns @c NULL. * in @p dir. On failure, it returns @c NULL.
* *
* @details This returns an iterator for shared strings, the name of each file in @p dir is
* only fetched when advancing the iterator, which means there is very little
* cost associated with creating the list and stopping halfway through it.
*
* @note The iterator hands the user a stringshared value with the full * @note The iterator hands the user a stringshared value with the full
* path. The user must free the string using eina_stringshare_del() on it. * path. The user must free the string using eina_stringshare_del() on it.
* *
@ -308,16 +305,15 @@ EAPI Eina_Iterator *eina_file_ls(const char *dir) EINA_WARN_UNUSED_RESULT EINA_A
/** /**
* @brief Gets an iterator to list the content of a directory, with direct * @brief Gets an iterator to list the content of a directory, with direct
* information. * information.
* @details This returns an iterator for #Eina_File_Direct_Info, the name of each file in @p
* dir is only fetched when advancing the iterator, which means there is
* cost associated with creating the list and stopping halfway through it.
* *
* @param [in] dir The name of the directory to list * @param [in] dir The name of the directory to list
* *
* @return An #Eina_Iterator that walks over the files and * @return An #Eina_Iterator that walks over the files and
* directories in @p dir. On failure, it returns @c NULL. * directories in @p dir. On failure, it returns @c NULL.
* *
* @details This returns an iterator for #Eina_File_Direct_Info, the name of each file in @p
* dir is only fetched when advancing the iterator, which means there is
* cost associated with creating the list and stopping halfway through it.
*
* @warning The #Eina_File_Direct_Info returned by the iterator <b>must not</b> * @warning The #Eina_File_Direct_Info returned by the iterator <b>must not</b>
* be modified in any way. * be modified in any way.
* @warning When the iterator is advanced or deleted the #Eina_File_Direct_Info * @warning When the iterator is advanced or deleted the #Eina_File_Direct_Info
@ -336,14 +332,13 @@ EAPI Eina_Iterator *eina_file_stat_ls(const char *dir) EINA_WARN_UNUSED_RESULT E
/** /**
* @brief Uses information provided by #Eina_Iterator of eina_file_stat_ls() or eina_file_direct_ls() * @brief Uses information provided by #Eina_Iterator of eina_file_stat_ls() or eina_file_direct_ls()
* to call stat in the most efficient way on your system. * to call stat in the most efficient way on your system.
* @details This function calls fstatat or stat depending on what your system supports. This makes it efficient and simple
* to use on your side without complex detection already done inside Eina on what the system can do.
* *
* @param[in] container The container returned by #Eina_Iterator using eina_iterator_container_get() * @param[in] container The container returned by #Eina_Iterator using eina_iterator_container_get()
* @param[in] info The content of the current #Eina_File_Direct_Info provided by #Eina_Iterator * @param[in] info The content of the current #Eina_File_Direct_Info provided by #Eina_Iterator
* @param[in] buf The location put the result of the stat * @param[in] buf The location put the result of the stat
* @return @c 0 is returnedon success, otherwise @c -1 is returned on error and errno is set appropriately * @return @c 0 is returned on success, otherwise @c -1 is returned on error and errno is set appropriately
*
* @details This function calls fstatat or stat depending on what your system supports. This makes it efficient and simple
* to use on your side without complex detection already done inside Eina on what the system can do.
* *
* @see eina_file_direct_ls() * @see eina_file_direct_ls()
* @see eina_file_stat_ls() * @see eina_file_stat_ls()
@ -355,19 +350,18 @@ EAPI int eina_file_statat(void *container, Eina_File_Direct_Info *info, Eina_Sta
/** /**
* @brief Generates and creates a uniquely named temporary file from a template name. * @brief Generates and creates a uniquely named temporary file from a template name.
* The generated file is opened with the open(2) @c O_EXCL flag. * The generated file is opened with the open(2) @c O_EXCL flag.
* @details This function calls mkstemp(), generates a unique temporary filename
* from template, creates and opens the file, and returns an open file
* descriptor for the file.
* *
* @param[in] templatename This is a string. It must contain the six characters 'XXXXXX' * @param[in] templatename This is a string. It must contain the six characters 'XXXXXX'
* at the end or directly followed by an extension as in * at the end or directly followed by an extension as in
* 'prefixXXXXXX.ext'. * 'prefixXXXXXX.ext'.
* @param[out] path The path to the created temporary file, or @c NULL in case of failure. * @param[out] path The path to the created temporary file, or @c NULL in case of failure.
* It must be released by eina_tmpstr_del(). * It must be released by eina_tmpstr_del().
* @return On success @c file descriptor of the temporary file is returned, * @return On success @c file descriptor of the temporary file is returned,
* On error @c -1 is returned, in which case @c errno is set appropriately. * On error @c -1 is returned, in which case @c errno is set appropriately.
* *
* @details This function calls mkstemp(), generates a unique temporary filename
* from template, creates and opens the file, and returns an open file
* descriptor for the file.
*
* @note If a filename extension was specified in @p templatename, then the new @p path * @note If a filename extension was specified in @p templatename, then the new @p path
* will also contain this extension (since 1.10). * will also contain this extension (since 1.10).
* *
@ -376,7 +370,7 @@ EAPI int eina_file_statat(void *container, Eina_File_Direct_Info *info, Eina_Sta
* the system temporary directory (@see eina_environment_tmp_get()). If the * the system temporary directory (@see eina_environment_tmp_get()). If the
* @p templatename contains a directory separator ('/', or '\\' on Windows) * @p templatename contains a directory separator ('/', or '\\' on Windows)
* then the file will be created inside this directory, which must exist and * then the file will be created inside this directory, which must exist and
* be writable. Use ./filename.XXXXXX to create files in the current * be writeable. Use ./filename.XXXXXX to create files in the current
* working directory. (since 1.17) * working directory. (since 1.17)
* *
* @see eina_file_mkdtemp() * @see eina_file_mkdtemp()
@ -386,23 +380,22 @@ EAPI int eina_file_mkstemp(const char *templatename, Eina_Tmpstr **path) EINA_AR
/** /**
* @brief Generates and creates a uniquely named temporary directory from a template name. * @brief Generates and creates a uniquely named temporary directory from a template name.
* @details This function calls mkdtemp(). The directory is then created with
* permissions 0700.
* *
* @param[in] templatename This is a string. The last six characters of @p templatename * @param[in] templatename This is a string. The last six characters of @p templatename
* must be XXXXXX. * must be XXXXXX.
* @param[out] path The path to the created temporary directory, or @c NULL in case of failure. * @param[out] path The path to the created temporary directory, or @c NULL in case of failure.
* It must be released by eina_tmpstr_del(). * It must be released by eina_tmpstr_del().
* @return On success @c EINA_TRUE is returned, On error @c EINA_FALSE is returned, * @return On success @c EINA_TRUE is returned, On error @c EINA_FALSE is returned,
* in which case @c errno is set appropriately. * in which case @c errno is set appropriately.
* *
* @details This function calls mkdtemp(). The directory is then created with
* permissions 0700.
*
* @note If the @p templatename is a simple directory name (no relative or absolute * @note If the @p templatename is a simple directory name (no relative or absolute
* path to another directory), then a temporary directory will be created inside * path to another directory), then a temporary directory will be created inside
* the system temporary directory (@see eina_environment_tmp_get()). If the * the system temporary directory (@see eina_environment_tmp_get()). If the
* @p templatename contains a directory separator ('/', or '\\' on Windows) * @p templatename contains a directory separator ('/', or '\\' on Windows)
* then the temporary directory will be created inside that other directory, * then the temporary directory will be created inside that other directory,
* which must exist and be writable. (since 1.17) * which must exist and be writeable. (since 1.17)
* *
* @see eina_file_mkstemp() * @see eina_file_mkstemp()
* @since 1.8 * @since 1.8
@ -412,16 +405,15 @@ EAPI Eina_Bool eina_file_mkdtemp(const char *templatename, Eina_Tmpstr **path) E
/** /**
* @brief Gets an iterator to list the content of a directory, with direct * @brief Gets an iterator to list the content of a directory, with direct
* information. * information.
* @details This returns an iterator for #Eina_File_Direct_Info, the name of each file in
* @p dir is only fetched when advancing the iterator, which means there is
* cost associated with creating the list and stopping halfway through it.
* *
* @param [in] dir The name of the directory to list * @param [in] dir The name of the directory to list
* *
* @return An Eina_Iterator that walks over the files and * @return An Eina_Iterator that walks over the files and
* directories in @p dir. On failure, it returns @c NULL. * directories in @p dir. On failure, it returns @c NULL.
* *
* @details This returns an iterator for #Eina_File_Direct_Info, the name of each file in
* @p dir is only fetched when advancing the iterator, which means there is
* cost associated with creating the list and stopping halfway through it.
*
* @warning If readdir_r doesn't contain file type information, file type is * @warning If readdir_r doesn't contain file type information, file type is
* EINA_FILE_UNKNOWN. * EINA_FILE_UNKNOWN.
* @warning The #Eina_File_Direct_Info returned by the iterator <b>must not</b> * @warning The #Eina_File_Direct_Info returned by the iterator <b>must not</b>
@ -441,15 +433,14 @@ EAPI Eina_Iterator *eina_file_direct_ls(const char *dir) EINA_WARN_UNUSED_RESULT
/** /**
* @brief Sanitizes the file path. * @brief Sanitizes the file path.
* @details This function takes care of adding the current working directory if its a
* relative path and also removes all '..' and '//' references in the original
* path.
* *
* @param[in] path The path to sanitize * @param[in] path The path to sanitize
* *
* @return An allocated string with the sanitized path * @return An allocated string with the sanitized path
* *
* @details This function takes care of adding the current working directory if its a
* relative path and also removes all '..' and '//' references in the original
* path.
*
* @since 1.1 * @since 1.1
*/ */
EAPI char *eina_file_path_sanitize(const char *path); EAPI char *eina_file_path_sanitize(const char *path);
@ -475,7 +466,9 @@ typedef enum {
} Eina_File_Copy_Flags; } Eina_File_Copy_Flags;
/** /**
* @brief Copy one file to another using the fastest possible way and report progress. * @brief Copies one file to another using the fastest possible way and report progress.
* @details This function tries to splice if it is available. It is blocked
* until the whole file is copied or it fails.
* *
* @param[in] src The source file. * @param[in] src The source file.
* @param[in] dst The destination file. * @param[in] dst The destination file.
@ -485,31 +478,27 @@ typedef enum {
* @return #EINA_TRUE on success, #EINA_FALSE otherwise (and @p dst * @return #EINA_TRUE on success, #EINA_FALSE otherwise (and @p dst
* will be deleted) * will be deleted)
* *
* @details This function tries to splice if it is available. It is blocked
* until the whole file is copied or it fails.
*
* @note During the progress it may call back @p cb with the progress summary. * @note During the progress it may call back @p cb with the progress summary.
*/ */
EAPI Eina_Bool eina_file_copy(const char *src, const char *dst, Eina_File_Copy_Flags flags, Eina_File_Copy_Progress cb, const void *cb_data) EINA_ARG_NONNULL(1, 2); EAPI Eina_Bool eina_file_copy(const char *src, const char *dst, Eina_File_Copy_Flags flags, Eina_File_Copy_Progress cb, const void *cb_data) EINA_ARG_NONNULL(1, 2);
/** /**
* @brief Gets a read-only handler to a file. * @brief Gets a read-only handler to a file.
* @details This opens a file in the read-only mode. @p name should be an absolute path. An
* #Eina_File handle can be shared among multiple instances if @p shared
* is #EINA_TRUE, otherwise.
* *
* @param[in] name The filename to open * @param[in] name The filename to open
* @param[in] shared Requested a shm * @param[in] shared Requested a shm
* @return An #Eina_File handle to the file * @return An #Eina_File handle to the file
* *
* @details This opens a file in the read-only mode. @p name should be an absolute path. An
* #Eina_File handle can be shared among multiple instances if @p shared
* is #EINA_TRUE, otherwise.
*
* @since 1.1 * @since 1.1
*/ */
EAPI Eina_File *eina_file_open(const char *name, Eina_Bool shared) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC; EAPI Eina_File *eina_file_open(const char *name, Eina_Bool shared) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_MALLOC;
/** /**
* @brief Create a virtual file from a memory pointer. * @brief Creates a virtual file from a memory pointer.
* *
* @param[in] virtual_name A virtual name for Eina_File, if @c NULL, a generated one will be given * @param[in] virtual_name A virtual name for Eina_File, if @c NULL, a generated one will be given
* @param[in] data The memory pointer to take data from * @param[in] data The memory pointer to take data from
@ -523,7 +512,7 @@ EAPI Eina_File *
eina_file_virtualize(const char *virtual_name, const void *data, unsigned long long length, Eina_Bool copy) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); eina_file_virtualize(const char *virtual_name, const void *data, unsigned long long length, Eina_Bool copy) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
/** /**
* @brief Tells if a file is a real file or only exist in memory * @brief Tells if a file is a real file or only exist in memory.
* *
* @param file The file to test * @param file The file to test
* @return #EINA_TRUE if the file is a virtual file * @return #EINA_TRUE if the file is a virtual file
@ -534,14 +523,13 @@ EAPI Eina_Bool
eina_file_virtual(Eina_File *file) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); eina_file_virtual(Eina_File *file) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
/** /**
* @brief Refreshes file information * @brief Refreshes file information.
* @details All current map continue to exist. You need to manually delete
* and recreate them to have the new correct mapping.
* *
* @param file The file to refresh * @param file The file to refresh
* @return #EINA_TRUE if the file has changed * @return #EINA_TRUE if the file has changed
* *
* @details All current map continue to exist. You need to manually delete
* and recreate them to have the new correct mapping.
*
* @since 1.8 * @since 1.8
*/ */
EAPI Eina_Bool eina_file_refresh(Eina_File *file); EAPI Eina_Bool eina_file_refresh(Eina_File *file);
@ -560,11 +548,10 @@ EAPI Eina_File * eina_file_dup(const Eina_File *file);
/** /**
* @brief Unrefs the file handler. * @brief Unrefs the file handler.
* @details This decrements the file's reference count and if it reaches zero it closes the file.
* *
* @param[in] file The file handler to unref * @param[in] file The file handler to unref
* *
* @details This decrements the file's reference count and if it reaches zero it closes the file.
*
* @since 1.1 * @since 1.1
*/ */
EAPI void eina_file_close(Eina_File *file); EAPI void eina_file_close(Eina_File *file);
@ -666,7 +653,10 @@ EAPI void *eina_file_map_new(Eina_File *file, Eina_File_Populate rule,
EAPI void eina_file_map_free(Eina_File *file, void *map); EAPI void eina_file_map_free(Eina_File *file, void *map);
/** /**
* @brief Ask the OS to populate or otherwise pages of memory in file mapping * @brief Asks the OS to populate or otherwise pages of memory in file mapping.
* @details This advises the operating system as to what to do with the memory mapped
* to the given @p file. This affects a specific range of memory and may not
* be honoured if the system chooses to ignore the request.
* *
* @param[in] file The file handle from which the map comes * @param[in] file The file handle from which the map comes
* @param[in] rule The rule to apply to the mapped memory * @param[in] rule The rule to apply to the mapped memory
@ -674,10 +664,6 @@ EAPI void eina_file_map_free(Eina_File *file, void *map);
* @param[in] offset The offset in bytes from the start of the map address * @param[in] offset The offset in bytes from the start of the map address
* @param [in]length The length in bytes of the memory region to populate * @param [in]length The length in bytes of the memory region to populate
* *
* @details This advises the operating system as to what to do with the memory mapped
* to the given @p file. This affects a specific range of memory and may not
* be honored if the system chooses to ignore the request.
*
* @since 1.8 * @since 1.8
*/ */
EAPI void EAPI void
@ -686,20 +672,19 @@ eina_file_map_populate(Eina_File *file, Eina_File_Populate rule, const void *map
/** /**
* @brief Maps line by line in the memory efficiently using an #Eina_Iterator. * @brief Maps line by line in the memory efficiently using an #Eina_Iterator.
*
* @param[in] file The file to run over
* @return An Eina_Iterator that produces #Eina_File_Line
*
* @details This function returns an iterator that acts like fgets without * @details This function returns an iterator that acts like fgets without
* useless memcpy. Be aware that once eina_iterator_next has been called, * useless memcpy. Be aware that once eina_iterator_next has been called,
* nothing can guarantee that the memory is still going to be mapped. * nothing can guarantee that the memory is still going to be mapped.
* *
* @param[in] file The file to run over
* @return An Eina_Iterator that produces #Eina_File_Line
*
* @since 1.3 * @since 1.3
*/ */
EAPI Eina_Iterator *eina_file_map_lines(Eina_File *file); EAPI Eina_Iterator *eina_file_map_lines(Eina_File *file);
/** /**
* @brief Tells whether there has been an IO error during the life of a mmaped file, * @brief Tells whether there has been an IO error during the life of a mmaped file.
* *
* @param[in] file The file handler to the mmaped file * @param[in] file The file handler to the mmaped file
* @param[in] map The memory map to check if an error occurred on it * @param[in] map The memory map to check if an error occurred on it
@ -710,7 +695,9 @@ EAPI Eina_Iterator *eina_file_map_lines(Eina_File *file);
EAPI Eina_Bool eina_file_map_faulted(Eina_File *file, void *map); EAPI Eina_Bool eina_file_map_faulted(Eina_File *file, void *map);
/** /**
* @brief Join two paths of known length. * @brief Joins two paths of known length.
* @details This function is similar to eina_str_join_len(), but the separator
* is '\' on Windows and '/' otherwise.
* *
* @param dst The buffer to store the result. * @param dst The buffer to store the result.
* @param size Size (in byte) of the buffer. * @param size Size (in byte) of the buffer.
@ -720,9 +707,6 @@ EAPI Eina_Bool eina_file_map_faulted(Eina_File *file, void *map);
* @param b_len length of @p b. * @param b_len length of @p b.
* @return The number of characters printed. * @return The number of characters printed.
* *
* This function is similar to eina_str_join_len(), but the separator
* is '\' on Windows and '/' otherwise.
*
* @see eina_str_join_len() * @see eina_str_join_len()
* @see eina_file_path_join() * @see eina_file_path_join()
* *
@ -736,7 +720,10 @@ static inline size_t eina_file_path_join_len(char *dst,
size_t b_len); size_t b_len);
/** /**
* @brief Join two paths of known length. * @brief Joins two paths of known length.
* @details This function is similar to eina_file_path_join_len(), but will compute
* the length of @p a and @p b using strlen(). The path separator is
* '\' on Windows and '/' otherwise.
* *
* @param dst The buffer to store the result. * @param dst The buffer to store the result.
* @param size Size (in byte) of the buffer. * @param size Size (in byte) of the buffer.
@ -744,10 +731,6 @@ static inline size_t eina_file_path_join_len(char *dst,
* @param b Second string to use. * @param b Second string to use.
* @return The number of characters printed. * @return The number of characters printed.
* *
* This function is similar to eina_file_path_join_len(), but will compute
* the length of @p a and @p b using strlen(). The path separator is
* '\' on Windows and '/' otherwise.
*
* @see eina_file_path_join_len() * @see eina_file_path_join_len()
* *
* @since 1.16 * @since 1.16
@ -759,14 +742,13 @@ static inline size_t eina_file_path_join(char *dst,
/** /**
* @brief Unlink file * @brief Unlinks file.
* @details This function is a wrapper around the unlink() system call. It removes a link to
* a file.
* *
* @param pathname File name to unlink. * @param pathname File name to unlink.
* @return #EINA_TRUE if the unlink was successfull, #EINA_FALSE otherwise.. * @return #EINA_TRUE if the unlink was successfull, #EINA_FALSE otherwise..
* *
* This function is a wrapper around the unlink() system call. It removes a link to
* a file.
*
* @since 1.19 * @since 1.19
*/ */
EAPI Eina_Bool eina_file_unlink(const char *pathname); EAPI Eina_Bool eina_file_unlink(const char *pathname);

72
src/lib/eina/eina_fp.h
View File

@ -76,7 +76,7 @@ typedef int32_t Eina_F16p16;
typedef int32_t Eina_F8p24; typedef int32_t Eina_F8p24;
/** /**
* @brief Create a new Eina_F32p32 floating point number from standard 32-bit * @brief Creates a new Eina_F32p32 floating point number from standard 32-bit
* integer * integer
* *
* @param v 32-bit integer value to convert * @param v 32-bit integer value to convert
@ -85,7 +85,7 @@ typedef int32_t Eina_F8p24;
static inline Eina_F32p32 eina_f32p32_int_from(int32_t v); static inline Eina_F32p32 eina_f32p32_int_from(int32_t v);
/** /**
* @brief Create a new standard 32-bit integer from Eina_F32p32 floating point * @brief Creates a new standard 32-bit integer from Eina_F32p32 floating point
* number * number
* *
* @param v Eina_F32p32 value to convert * @param v Eina_F32p32 value to convert
@ -94,15 +94,15 @@ static inline Eina_F32p32 eina_f32p32_int_from(int32_t v);
static inline int32_t eina_f32p32_int_to(Eina_F32p32 v); static inline int32_t eina_f32p32_int_to(Eina_F32p32 v);
/** /**
* @brief Create a new Eina_F32p32 floating point number from standard double * @brief Creates a new Eina_F32p32 floating point number from standard double
* *
* @param v double value to convert * @param v Double value to convert
* @return The value converted into Eina_F32p32 format * @return The value converted into Eina_F32p32 format
*/ */
static inline Eina_F32p32 eina_f32p32_double_from(double v); static inline Eina_F32p32 eina_f32p32_double_from(double v);
/** /**
* @brief Create a new standard double from Eina_F32p32 floating point * @brief Creates a new standard double from Eina_F32p32 floating point
* number * number
* *
* @param v Eina_F32p32 value to convert * @param v Eina_F32p32 value to convert
@ -120,11 +120,11 @@ static inline double eina_f32p32_double_to(Eina_F32p32 v);
static inline Eina_F32p32 eina_f32p32_add(Eina_F32p32 a, Eina_F32p32 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 * @brief Calculates the subtraction of two Eina_F32p32 floating point numbers
* *
* @param a The first number * @param a The first number
* @param b The substracted number * @param b The subtracted number
* @return The substaction result of the two numbers @p a - @p b * @return The subtraction result of the two numbers @p a - @p b
*/ */
static inline Eina_F32p32 eina_f32p32_sub(Eina_F32p32 a, Eina_F32p32 b); static inline Eina_F32p32 eina_f32p32_sub(Eina_F32p32 a, Eina_F32p32 b);
@ -133,7 +133,7 @@ static inline Eina_F32p32 eina_f32p32_sub(Eina_F32p32 a, Eina_F32p32 b);
* *
* @param a The first number * @param a The first number
* @param b The second number * @param b The second number
* @return The mutliplication result of the two numbers @p a * @p b * @return The multiplication result of the two numbers @p a * @p b
* *
* To prevent overflow during multiplication we need to reduce the precision of * 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 * the fraction part Shift both values to only contain 16 bit of the fraction
@ -148,7 +148,7 @@ static inline Eina_F32p32 eina_f32p32_mul(Eina_F32p32 a, Eina_F32p32 b);
* *
* @param a The Eina_F32p32 number * @param a The Eina_F32p32 number
* @param b The integer value * @param b The integer value
* @return The mutliplication result of the two numbers @p a * @p b * @return The multiplication result of the two numbers @p a * @p b
*/ */
static inline Eina_F32p32 eina_f32p32_scale(Eina_F32p32 a, int b); static inline Eina_F32p32 eina_f32p32_scale(Eina_F32p32 a, int b);
@ -170,7 +170,7 @@ static inline Eina_F32p32 eina_f32p32_div(Eina_F32p32 a, Eina_F32p32 b);
static inline Eina_F32p32 eina_f32p32_sqrt(Eina_F32p32 a); static inline Eina_F32p32 eina_f32p32_sqrt(Eina_F32p32 a);
/** /**
* @brief Get the absolute value of the integer part of and Eina_F32p32 floating * @brief Gets the absolute value of the integer part of and Eina_F32p32 floating
* point number * point number
* *
* @param v The floating point number * @param v The floating point number
@ -179,7 +179,7 @@ static inline Eina_F32p32 eina_f32p32_sqrt(Eina_F32p32 a);
static inline unsigned int eina_f32p32_fracc_get(Eina_F32p32 v); static inline unsigned int eina_f32p32_fracc_get(Eina_F32p32 v);
/** /**
* @brief Get the absolute value of an Eina_F32p32 floating point number * @brief Gets the absolute value of an Eina_F32p32 floating point number
* *
* @param a The floating point number * @param a The floating point number
* @return The absolute value for the number @p a * @return The absolute value for the number @p a
@ -220,7 +220,7 @@ EAPI Eina_F32p32 eina_f32p32_sin(Eina_F32p32 a);
#define EINA_F16P16_HALF (1 << 15) #define EINA_F16P16_HALF (1 << 15)
/** /**
* @brief Create a new Eina_F16p316 floating point number from standard 32-bit * @brief Creates a new Eina_F16p316 floating point number from standard 32-bit
* integer * integer
* *
* @param v 32-bit integer value to convert * @param v 32-bit integer value to convert
@ -229,7 +229,7 @@ EAPI Eina_F32p32 eina_f32p32_sin(Eina_F32p32 a);
static inline Eina_F16p16 eina_f16p16_int_from(int32_t v); static inline Eina_F16p16 eina_f16p16_int_from(int32_t v);
/** /**
* @brief Create a new standard 32-bit integer from Eina_F16p16 floating point * @brief Creates a new standard 32-bit integer from Eina_F16p16 floating point
* number * number
* *
* @param v Eina_F16p16 value to convert * @param v Eina_F16p16 value to convert
@ -238,15 +238,15 @@ static inline Eina_F16p16 eina_f16p16_int_from(int32_t v);
static inline int32_t eina_f16p16_int_to(Eina_F16p16 v); static inline int32_t eina_f16p16_int_to(Eina_F16p16 v);
/** /**
* @brief Create a new Eina_F16p16 floating point number from standard double * @brief Creates a new Eina_F16p16 floating point number from standard double
* *
* @param v double value to convert * @param v Double value to convert
* @return The value converted into Eina_F16p16 format * @return The value converted into Eina_F16p16 format
*/ */
static inline Eina_F16p16 eina_f16p16_double_from(double v); static inline Eina_F16p16 eina_f16p16_double_from(double v);
/** /**
* @brief Create a new standard double from Eina_F16p16 floating point * @brief Creates a new standard double from Eina_F16p16 floating point
* number * number
* *
* @param v Eina_F16p16 value to convert * @param v Eina_F16p16 value to convert
@ -255,15 +255,15 @@ static inline Eina_F16p16 eina_f16p16_double_from(double v);
static inline double eina_f16p16_double_to(Eina_F16p16 v); static inline double eina_f16p16_double_to(Eina_F16p16 v);
/** /**
* @brief Create a new Eina_F16p16 floating point number from standard float * @brief Creates a new Eina_F16p16 floating point number from standard float
* *
* @param v float value to convert * @param v Float value to convert
* @return The value converted into Eina_F16p16 format * @return The value converted into Eina_F16p16 format
*/ */
static inline Eina_F16p16 eina_f16p16_float_from(float v); static inline Eina_F16p16 eina_f16p16_float_from(float v);
/** /**
* @brief Create a new standard float from Eina_F16p16 floating point * @brief Creates a new standard float from Eina_F16p16 floating point
* number * number
* *
* @param v Eina_F16p16 value to convert * @param v Eina_F16p16 value to convert
@ -281,11 +281,11 @@ static inline float eina_f16p16_float_to(Eina_F16p16 v);
static inline Eina_F16p16 eina_f16p16_add(Eina_F16p16 a, Eina_F16p16 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 * @brief Calculates the subtraction of two Eina_F16p16 floating point numbers
* *
* @param a The first number * @param a The first number
* @param b The substracted number * @param b The subtracted number
* @return The substaction result of the two numbers @p a - @p b * @return The subtraction result of the two numbers @p a - @p b
*/ */
static inline Eina_F16p16 eina_f16p16_sub(Eina_F16p16 a, Eina_F16p16 b); static inline Eina_F16p16 eina_f16p16_sub(Eina_F16p16 a, Eina_F16p16 b);
@ -294,7 +294,7 @@ static inline Eina_F16p16 eina_f16p16_sub(Eina_F16p16 a, Eina_F16p16 b);
* *
* @param a The first number * @param a The first number
* @param b The second number * @param b The second number
* @return The mutliplication result of the two numbers @p a * @p b * @return The multiplication result of the two numbers @p a * @p b
*/ */
static inline Eina_F16p16 eina_f16p16_mul(Eina_F16p16 a, Eina_F16p16 b); static inline Eina_F16p16 eina_f16p16_mul(Eina_F16p16 a, Eina_F16p16 b);
@ -304,7 +304,7 @@ static inline Eina_F16p16 eina_f16p16_mul(Eina_F16p16 a, Eina_F16p16 b);
* *
* @param a The Eina_F16p16 number * @param a The Eina_F16p16 number
* @param b The integer value * @param b The integer value
* @return The mutliplication result of the two numbers @p a * @p b * @return The multiplication result of the two numbers @p a * @p b
*/ */
static inline Eina_F16p16 eina_f16p16_scale(Eina_F16p16 a, int b); static inline Eina_F16p16 eina_f16p16_scale(Eina_F16p16 a, int b);
@ -326,7 +326,7 @@ static inline Eina_F16p16 eina_f16p16_div(Eina_F16p16 a, Eina_F16p16 b);
static inline Eina_F16p16 eina_f16p16_sqrt(Eina_F16p16 a); static inline Eina_F16p16 eina_f16p16_sqrt(Eina_F16p16 a);
/** /**
* @brief Get the absolute value of the integer part of and Eina_F16p16 floating * @brief Gets the absolute value of the integer part of and Eina_F16p16 floating
* point number * point number
* *
* @param v The floating point number * @param v The floating point number
@ -336,7 +336,7 @@ static inline unsigned int eina_f16p16_fracc_get(Eina_F16p16 v);
/** /**
* @brief Create a new Eina_F16p316 floating point number from standard 32-bit * @brief Creates a new Eina_F16p316 floating point number from standard 32-bit
* integer * integer
* *
* @param v 32-bit integer value to convert * @param v 32-bit integer value to convert
@ -345,7 +345,7 @@ static inline unsigned int eina_f16p16_fracc_get(Eina_F16p16 v);
static inline Eina_F8p24 eina_f8p24_int_from(int32_t v); static inline Eina_F8p24 eina_f8p24_int_from(int32_t v);
/** /**
* @brief Create a new standard 32-bit integer from Eina_F8p24 floating point * @brief Creates a new standard 32-bit integer from Eina_F8p24 floating point
* number * number
* *
* @param v Eina_F8p24 value to convert * @param v Eina_F8p24 value to convert
@ -354,9 +354,9 @@ static inline Eina_F8p24 eina_f8p24_int_from(int32_t v);
static inline int32_t eina_f8p24_int_to(Eina_F8p24 v); static inline int32_t eina_f8p24_int_to(Eina_F8p24 v);
/** /**
* @brief Create a new Eina_F8p24 floating point number from standard float * @brief Creates a new Eina_F8p24 floating point number from standard float
* *
* @param v float value to convert * @param v Float value to convert
* @return The value converted into Eina_F8p24 format * @return The value converted into Eina_F8p24 format
*/ */
static inline Eina_F8p24 eina_f8p24_float_from(float v); static inline Eina_F8p24 eina_f8p24_float_from(float v);
@ -379,11 +379,11 @@ static inline float eina_f8p24_float_to(Eina_F8p24 v);
static inline Eina_F8p24 eina_f8p24_add(Eina_F8p24 a, Eina_F8p24 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 * @brief Calculates the subtraction of two Eina_F8p24 floating point numbers
* *
* @param a The first number * @param a The first number
* @param b The substracted number * @param b The subtracted number
* @return The substaction result of the two numbers @p a - @p b * @return The subtraction result of the two numbers @p a - @p b
*/ */
static inline Eina_F8p24 eina_f8p24_sub(Eina_F8p24 a, Eina_F8p24 b); static inline Eina_F8p24 eina_f8p24_sub(Eina_F8p24 a, Eina_F8p24 b);
@ -392,7 +392,7 @@ static inline Eina_F8p24 eina_f8p24_sub(Eina_F8p24 a, Eina_F8p24 b);
* *
* @param a The first number * @param a The first number
* @param b The second number * @param b The second number
* @return The mutliplication result of the two numbers @p a * @p b * @return The multiplication result of the two numbers @p a * @p b
*/ */
static inline Eina_F8p24 eina_f8p24_mul(Eina_F8p24 a, Eina_F8p24 b); static inline Eina_F8p24 eina_f8p24_mul(Eina_F8p24 a, Eina_F8p24 b);
@ -402,7 +402,7 @@ static inline Eina_F8p24 eina_f8p24_mul(Eina_F8p24 a, Eina_F8p24 b);
* *
* @param a The Eina_F16p16 number * @param a The Eina_F16p16 number
* @param b The integer value * @param b The integer value
* @return The mutliplication result of the two numbers @p a * @p b * @return The multiplication result of the two numbers @p a * @p b
*/ */
static inline Eina_F8p24 eina_f8p24_scale(Eina_F8p24 a, int b); static inline Eina_F8p24 eina_f8p24_scale(Eina_F8p24 a, int b);
@ -424,7 +424,7 @@ static inline Eina_F8p24 eina_f8p24_div(Eina_F8p24 a, Eina_F8p24 b);
static inline Eina_F8p24 eina_f8p24_sqrt(Eina_F8p24 a); static inline Eina_F8p24 eina_f8p24_sqrt(Eina_F8p24 a);
/** /**
* @brief Get the absolute value of the integer part of and Eina_F8p24 floating * @brief Gets the absolute value of the integer part of and Eina_F8p24 floating
* point number * point number
* *
* @param v The floating point number * @param v The floating point number

2
src/lib/eina/eina_hamster.h
View File

@ -39,7 +39,7 @@
/** /**
* @brief Get the hamster count. * @brief Gets the hamster count.
* *
* @return The number of available hamsters. * @return The number of available hamsters.
* *

84
src/lib/eina/eina_hash.h
View File

@ -77,7 +77,7 @@
* @until printf("\n"); * @until printf("\n");
* *
* There are different ways of iterate over the entries of a hash. Here we show * 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 . * two of them: using @ref eina_hash_foreach and @ref Eina_Iterator.
* *
* @skip List of phones * @skip List of phones
* @until eina_iterator_free(it); * @until eina_iterator_free(it);
@ -346,7 +346,7 @@ typedef Eina_Bool (*Eina_Hash_Foreach)(const Eina_Hash *hash, const void *key
/** /**
* @brief Create a new hash table. * @brief Creates a new hash table.
* *
* @param key_length_cb The function called when getting the size of the key. * @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_cmp_cb The function called when comparing the keys.
@ -381,7 +381,7 @@ 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); 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 clean the data of a hash.
* *
* @param hash The given hash table * @param hash The given hash table
* @param data_free_cb The function called on each value when the hash * @param data_free_cb The function called on each value when the hash
@ -397,7 +397,7 @@ EAPI Eina_Hash *eina_hash_new(Eina_Key_Length key_length_cb,
EAPI void eina_hash_free_cb_set(Eina_Hash *hash, Eina_Free_Cb data_free_cb) EINA_ARG_NONNULL(1); 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 * @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 * is freed, or when an item is deleted from it. @c NULL can be passed as
@ -412,7 +412,7 @@ EAPI void eina_hash_free_cb_set(Eina_Hash *hash, Eina_Free_Cb data_free_cb) EINA
EAPI Eina_Hash *eina_hash_string_djb2_new(Eina_Free_Cb data_free_cb); 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 * @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 * is freed, or when an item is deleted from it. @c NULL can be passed as
@ -431,7 +431,7 @@ EAPI Eina_Hash *eina_hash_string_djb2_new(Eina_Free_Cb data_free_cb);
EAPI Eina_Hash *eina_hash_string_superfast_new(Eina_Free_Cb data_free_cb); 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. * @brief Creates 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 * @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 * is freed, or when an item is deleted from it. @c NULL can be passed as
@ -449,7 +449,7 @@ EAPI Eina_Hash *eina_hash_string_superfast_new(Eina_Free_Cb data_free_cb);
EAPI Eina_Hash *eina_hash_string_small_new(Eina_Free_Cb data_free_cb); 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. * @brief Creates a new hash table for use with 32bit integers.
* *
* @param data_free_cb The function called on each value when the 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 * is freed, or when an item is deleted from it. @c NULL can be passed as
@ -468,7 +468,7 @@ EAPI Eina_Hash *eina_hash_string_small_new(Eina_Free_Cb data_free_cb);
EAPI Eina_Hash *eina_hash_int32_new(Eina_Free_Cb data_free_cb); EAPI Eina_Hash *eina_hash_int32_new(Eina_Free_Cb data_free_cb);
/** /**
* @brief Create a new hash table for use with 64bit integers. * @brief Creates a new hash table for use with 64bit integers.
* *
* @param data_free_cb The function called on each value when the 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 * is freed, or when an item is deleted from it. @c NULL can be passed as
@ -486,7 +486,7 @@ EAPI Eina_Hash *eina_hash_int32_new(Eina_Free_Cb data_free_cb);
EAPI Eina_Hash *eina_hash_int64_new(Eina_Free_Cb data_free_cb); EAPI Eina_Hash *eina_hash_int64_new(Eina_Free_Cb data_free_cb);
/** /**
* @brief Create a new hash table for use with pointers. * @brief Creates a new hash table for use with pointers.
* *
* @param data_free_cb The function called on each value when the 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 * is freed, or when an item is deleted from it. @c NULL can be passed as
@ -512,7 +512,7 @@ EAPI Eina_Hash *eina_hash_int64_new(Eina_Free_Cb data_free_cb);
EAPI Eina_Hash *eina_hash_pointer_new(Eina_Free_Cb data_free_cb); 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 * @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 * is freed, or when an item is deleted from it. @c NULL can be passed as
@ -538,7 +538,7 @@ EAPI Eina_Hash *eina_hash_pointer_new(Eina_Free_Cb data_free_cb);
EAPI Eina_Hash *eina_hash_stringshared_new(Eina_Free_Cb data_free_cb); EAPI Eina_Hash *eina_hash_stringshared_new(Eina_Free_Cb data_free_cb);
/** /**
* @brief Add an entry to the given hash table. * @brief Adds an entry to the given hash table.
* *
* @param hash The given hash table. Cannot be @c NULL. * @param hash The given hash table. Cannot be @c NULL.
* @param key A unique key. Cannot be @c NULL. * @param key A unique key. Cannot be @c NULL.
@ -563,7 +563,7 @@ EAPI Eina_Bool eina_hash_add(Eina_Hash *hash,
const void *data) EINA_ARG_NONNULL(1, 2, 3); const void *data) EINA_ARG_NONNULL(1, 2, 3);
/** /**
* @brief Add an entry to the given hash table without duplicating the string * @brief Adds an entry to the given hash table without duplicating the string.
* key. * key.
* *
* @param hash The given hash table. Cannot be @c NULL. * @param hash The given hash table. Cannot be @c NULL.
@ -591,7 +591,7 @@ EAPI Eina_Bool eina_hash_direct_add(Eina_Hash *hash,
const void *data) EINA_ARG_NONNULL(1, 2, 3); const void *data) EINA_ARG_NONNULL(1, 2, 3);
/** /**
* @brief Remove the entry identified by a key or a data from the given * @brief Removes the entry identified by a key or a data from the given
* hash table. * hash table.
* *
* @param hash The given hash table. * @param hash The given hash table.
@ -618,7 +618,7 @@ EAPI Eina_Bool eina_hash_del(Eina_Hash *hash,
const void *data) EINA_ARG_NONNULL(1); const void *data) EINA_ARG_NONNULL(1);
/** /**
* @brief Retrieve a specific entry in the given hash table. * @brief Retrieves a specific entry in the given hash table.
* *
* @param hash The given hash table. * @param hash The given hash table.
* @param key The key of the entry to find. * @param key The key of the entry to find.
@ -634,7 +634,7 @@ EAPI void *eina_hash_find(const Eina_Hash *hash,
const void *key) EINA_ARG_NONNULL(2); const void *key) EINA_ARG_NONNULL(2);
/** /**
* @brief Modify the entry pointer at the specified key and return the old * @brief Modifies the entry pointer at the specified key and return the old
* entry. * entry.
* @param hash The given hash table. * @param hash The given hash table.
* @param key The key of the entry to modify. * @param key The key of the entry to modify.
@ -651,7 +651,7 @@ EAPI void *eina_hash_modify(Eina_Hash *hash,
const void *data) EINA_ARG_NONNULL(1, 2, 3); const void *data) EINA_ARG_NONNULL(1, 2, 3);
/** /**
* @brief Modify the entry pointer at the specified key and return the * @brief Modifies the entry pointer at the specified key and return the
* old entry or add the entry if not found. * old entry or add the entry if not found.
* *
* @param hash The given hash table. * @param hash The given hash table.
@ -670,7 +670,7 @@ EAPI void *eina_hash_set(Eina_Hash *hash,
const void *data) EINA_ARG_NONNULL(1, 2); const void *data) EINA_ARG_NONNULL(1, 2);
/** /**
* @brief Change the key associated with a data without triggering the * @brief Changes the key associated with a data without triggering the
* free callback. * free callback.
* *
* @param hash The given hash table. * @param hash The given hash table.
@ -687,7 +687,7 @@ EAPI Eina_Bool eina_hash_move(Eina_Hash *hash,
const void *new_key) EINA_ARG_NONNULL(1, 2, 3); 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. * @param hash The hash table to be freed.
* *
@ -711,7 +711,7 @@ EAPI Eina_Bool eina_hash_move(Eina_Hash *hash,
EAPI void eina_hash_free(Eina_Hash *hash) EINA_ARG_NONNULL(1); 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.
* *
* @param hash The hash table whose buckets have to be freed. * @param hash The hash table whose buckets have to be freed.
* *
@ -736,7 +736,7 @@ EAPI void eina_hash_free_buckets(Eina_Hash *hash) EINA_ARG_NONNULL(1);
EAPI int eina_hash_population(const Eina_Hash *hash) EINA_ARG_NONNULL(1); EAPI int eina_hash_population(const Eina_Hash *hash) EINA_ARG_NONNULL(1);
/** /**
* @brief Add an entry to the given hash table. * @brief Adds an entry to the given hash table.
* *
* @param hash The given hash table. Cannot be @c NULL. * @param hash The given hash table. Cannot be @c NULL.
* @param key A unique key. Cannot be @c NULL. * @param key A unique key. Cannot be @c NULL.
@ -766,7 +766,7 @@ EAPI Eina_Bool eina_hash_add_by_hash(Eina_Hash *hash,
const void *data) EINA_ARG_NONNULL(1, 2, 5); const void *data) EINA_ARG_NONNULL(1, 2, 5);
/** /**
* @brief Add an entry to the given hash table and do not duplicate the string * @brief Adds an entry to the given hash table and do not duplicate the string
* key. * key.
* *
* @param hash The given hash table. Cannot be @c NULL. * @param hash The given hash table. Cannot be @c NULL.
@ -800,7 +800,7 @@ EAPI Eina_Bool eina_hash_direct_add_by_hash(Eina_Hash *hash,
const void *data) EINA_ARG_NONNULL(1, 2, 5); const void *data) EINA_ARG_NONNULL(1, 2, 5);
/** /**
* @brief Remove the entry identified by a key and a key hash from the given * @brief Removes the entry identified by a key and a key hash from the given
* hash table. * hash table.
* *
* @param hash The given hash table. Cannot be @c NULL. * @param hash The given hash table. Cannot be @c NULL.
@ -817,8 +817,8 @@ EAPI Eina_Bool eina_hash_direct_add_by_hash(Eina_Hash *hash,
* functions returns immediately #EINA_FALSE. This function * functions returns immediately #EINA_FALSE. This function
* returns #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. * 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_hash, use eina_hash_del_by_key() instead.
* @note if you don't have the key, use eina_hash_del_by_data() instead. * @note If you don't have the key, use eina_hash_del_by_data() instead.
*/ */
EAPI Eina_Bool eina_hash_del_by_key_hash(Eina_Hash *hash, EAPI Eina_Bool eina_hash_del_by_key_hash(Eina_Hash *hash,
const void *key, const void *key,
@ -826,7 +826,7 @@ EAPI Eina_Bool eina_hash_del_by_key_hash(Eina_Hash *hash,
int key_hash) EINA_ARG_NONNULL(1, 2); int key_hash) EINA_ARG_NONNULL(1, 2);
/** /**
* @brief Remove the entry identified by a key from the given hash table. * @brief Removes the entry identified by a key from the given hash table.
* *
* This version will calculate key length and hash by using functions * This version will calculate key length and hash by using functions
* provided to hash creation function. * provided to hash creation function.
@ -837,21 +837,21 @@ EAPI Eina_Bool eina_hash_del_by_key_hash(Eina_Hash *hash,
* *
* This function removes the entry identified by @p key from @p * This function removes the entry identified by @p key from @p
* hash. The key length and hash will be calculated automatically by * hash. The key length and hash will be calculated automatically by
* using functiond provided to has creation function. If a free * using function provided to has creation function. If a free
* function was given to the callback on creation, it will be called * 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 * for the data being deleted. If @p hash or @p key are @c NULL, the
* functions returns immediately #EINA_FALSE. This function * functions returns immediately #EINA_FALSE. This function
* returns #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. * 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() * @note If you already have the key_hash, use eina_hash_del_by_key_hash()
* instead. * instead.
* @note if you don't have the key, use eina_hash_del_by_data() instead. * @note If you don't have the key, use eina_hash_del_by_data() instead.
*/ */
EAPI Eina_Bool eina_hash_del_by_key(Eina_Hash *hash, EAPI Eina_Bool eina_hash_del_by_key(Eina_Hash *hash,
const void *key) EINA_ARG_NONNULL(1, 2); 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 a data from the given hash table.
* *
* This version is slow since there is no quick access to nodes based on data. * This version is slow since there is no quick access to nodes based on data.
* *
@ -867,14 +867,14 @@ EAPI Eina_Bool eina_hash_del_by_key(Eina_Hash *hash,
* function returns #EINA_FALSE if an error occurred, #EINA_TRUE * function returns #EINA_FALSE if an error occurred, #EINA_TRUE
* otherwise. * otherwise.
* *
* @note if you already have the key, use eina_hash_del_by_key() or * @note If you already have the key, use eina_hash_del_by_key() or
* eina_hash_del_by_key_hash() instead. * eina_hash_del_by_key_hash() instead.
*/ */
EAPI Eina_Bool eina_hash_del_by_data(Eina_Hash *hash, EAPI Eina_Bool eina_hash_del_by_data(Eina_Hash *hash,
const void *data) EINA_ARG_NONNULL(1, 2); const void *data) EINA_ARG_NONNULL(1, 2);
/** /**
* @brief Remove the entry identified by a key and a key hash or a * @brief Removes the entry identified by a key and a key hash or a
* data from the given hash table. * data from the given hash table.
* *
* If @p key is @c NULL, then @p data is used to find a match to * If @p key is @c NULL, then @p data is used to find a match to
@ -898,8 +898,8 @@ EAPI Eina_Bool eina_hash_del_by_data(Eina_Hash *hash,
* string when setting the value of @p key_length. This function * string when setting the value of @p key_length. This function
* returns #EINA_FALSE if an error occurred, #EINA_TRUE otherwise. * 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(), * @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() * If you know you don't have the key, use eina_hash_del_by_data()
* directly. * directly.
*/ */
EAPI Eina_Bool eina_hash_del_by_hash(Eina_Hash *hash, EAPI Eina_Bool eina_hash_del_by_hash(Eina_Hash *hash,
@ -909,7 +909,7 @@ EAPI Eina_Bool eina_hash_del_by_hash(Eina_Hash *hash,
const void *data) EINA_ARG_NONNULL(1); const void *data) EINA_ARG_NONNULL(1);
/** /**
* @brief Retrieve a specific entry in the given hash table. * @brief Retrieves a specific entry in the given hash table.
* *
* @param hash The given hash table. Cannot be @c NULL. * @param hash The given hash table. Cannot be @c NULL.
* @param key The key of the entry to find. * @param key The key of the entry to find.
@ -931,7 +931,7 @@ EAPI void *eina_hash_find_by_hash(const Eina_Hash *hash,
int key_hash) EINA_ARG_NONNULL(1, 2); int key_hash) EINA_ARG_NONNULL(1, 2);
/** /**
* @brief Modify the entry pointer at the specified key and returns * @brief Modifies the entry pointer at the specified key and returns
* the old entry. * the old entry.
* *
* @param hash The given hash table. * @param hash The given hash table.
@ -952,7 +952,7 @@ EAPI void *eina_hash_modify_by_hash(Eina_Hash *hash,
const void *data) EINA_ARG_NONNULL(1, 2, 5); 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.
* *
* @param hash The hash. * @param hash The hash.
* @return A new iterator. * @return A new iterator.
@ -972,7 +972,7 @@ EAPI void *eina_hash_modify_by_hash(Eina_Hash *hash,
EAPI Eina_Iterator *eina_hash_iterator_key_new(const Eina_Hash *hash) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; 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.
* *
* @param hash The hash. * @param hash The hash.
* @return A new iterator. * @return A new iterator.
@ -1005,7 +1005,7 @@ EAPI Eina_Iterator *eina_hash_iterator_data_new(const Eina_Hash *hash) EINA_MALL
* If the memory can not be allocated, @c NULL is returned. * If the memory can not be allocated, @c NULL is returned.
* Otherwise, a valid iterator is returned. * Otherwise, a valid iterator is returned.
* *
* @note iterator data will provide values as Eina_Hash_Tuple that should not * @note Iterator data will provide values as Eina_Hash_Tuple that should not
* be modified! * be modified!
* *
* @warning if the hash structure changes then the iterator becomes * @warning if the hash structure changes then the iterator becomes
@ -1015,7 +1015,7 @@ EAPI Eina_Iterator *eina_hash_iterator_data_new(const Eina_Hash *hash) EINA_MALL
EAPI Eina_Iterator *eina_hash_iterator_tuple_new(const Eina_Hash *hash) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; 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 hash The hash table whose members will be walked
* @param func The function to call on each parameter * @param func The function to call on each parameter
@ -1055,7 +1055,7 @@ EAPI void eina_hash_foreach(const Eina_Hash *hash,
/** /**
* @brief Append data to an #Eina_List inside a hash * @brief Appends data to an #Eina_List inside a hash.
* *
* This function is identical to the sequence of calling * This function is identical to the sequence of calling
* eina_hash_find(), eina_list_append(), eina_hash_set(), * eina_hash_find(), eina_list_append(), eina_hash_set(),
@ -1067,7 +1067,7 @@ EAPI void eina_hash_foreach(const Eina_Hash *hash,
*/ */
EAPI void eina_hash_list_append(Eina_Hash *hash, const void *key, const void *data) EINA_ARG_NONNULL(1, 2, 3); EAPI void eina_hash_list_append(Eina_Hash *hash, const void *key, const void *data) EINA_ARG_NONNULL(1, 2, 3);
/** /**
* @brief Prepend data to an #Eina_List inside a hash * @brief Prepends data to an #Eina_List inside a hash.
* *
* This function is identical to the sequence of calling * This function is identical to the sequence of calling
* eina_hash_find(), eina_list_prepend(), eina_hash_set(), * eina_hash_find(), eina_list_prepend(), eina_hash_set(),
@ -1079,7 +1079,7 @@ EAPI void eina_hash_list_append(Eina_Hash *hash, const void *key, const void *da
*/ */
EAPI void eina_hash_list_prepend(Eina_Hash *hash, const void *key, const void *data) EINA_ARG_NONNULL(1, 2, 3); EAPI void eina_hash_list_prepend(Eina_Hash *hash, const void *key, const void *data) EINA_ARG_NONNULL(1, 2, 3);
/** /**
* @brief Remove data from an #Eina_List inside a hash * @brief Removes data from an #Eina_List inside a hash.
* *
* This function is identical to the sequence of calling * This function is identical to the sequence of calling
* eina_hash_find(), eina_list_remove(), eina_hash_set(), * eina_hash_find(), eina_list_remove(), eina_hash_set(),

105
src/lib/eina/eina_inarray.h
View File

@ -166,7 +166,7 @@
* *
* We then add element using eina_inarray_insert and print. Then remove that * We then add element using eina_inarray_insert and print. Then remove that
* element and add again using eina_inarray_insert_sorted and prints. This * element and add again using eina_inarray_insert_sorted and prints. This
* shows the 2 different positions the elment gets added. Then searches an * shows the 2 different positions the element gets added. Then searches an
* element in the unsorted array using eina_inarray_search, then sorts the * element in the unsorted array using eina_inarray_search, then sorts the
* array and then searches the same element using eina_inarray_search_sorted. * array and then searches the same element using eina_inarray_search_sorted.
* @until } * @until }
@ -236,15 +236,14 @@ struct _Eina_Inarray
/** /**
* @brief Creates a new inline array. * @brief Creates a new inline array.
* @details This creates a new array where members are inlined in a sequence. Each
* member has @a member_size bytes.
* *
* @param[in] member_size The size of each member in the 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 * @param[in] step The step size by which to resize the array, do this using the following
* extra amount * extra amount
* @return The new inline array table, otherwise @c NULL on failure * @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. * @note If the @a step is @c 0, then a safe default is chosen.
* *
* @note On failure, @c NULL is returned. If @p member_size is zero, then @c NULL is returned. * @note On failure, @c NULL is returned. If @p member_size is zero, then @c NULL is returned.
@ -269,6 +268,8 @@ EAPI void eina_inarray_free(Eina_Inarray *array) EINA_ARG_NONNULL(1);
/** /**
* @brief Initializes an inline array. * @brief Initializes an inline array.
* @details This initializes an array. If the @p step is @c 0, then a safe default is
* chosen.
* *
* @param[in] array The array object to initialize * @param[in] array The array object to initialize
* @param[in] sizeof_eina_inarray The size of array object * @param[in] sizeof_eina_inarray The size of array object
@ -276,9 +277,6 @@ EAPI void eina_inarray_free(Eina_Inarray *array) EINA_ARG_NONNULL(1);
* @param[in] step The step size by which to resize the array, do this using the following * @param[in] step The step size by which to resize the array, do this using the following
* extra amount * 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 * @note This is useful for arrays inlined into other structures or
* allocated to a stack. * allocated to a stack.
* *
@ -294,7 +292,6 @@ EAPI void eina_inarray_step_set(Eina_Inarray *array,
/** /**
* @brief Removes every member from the array. * @brief Removes every member from the array.
* *
*
* @param[in] array The array object * @param[in] array The array object
* *
* @since 1.2 * @since 1.2
@ -303,15 +300,14 @@ EAPI void eina_inarray_flush(Eina_Inarray *array) EINA_ARG_NONNULL(1);
/** /**
* @brief Copies the data as the last member of the array. * @brief Copies the data as the last member of the array.
* @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.
* *
* @param[in] array The array object * @param[in] array The array object
* @param[in] data The data to be copied at the end * @param[in] data The data to be copied at the end
* @return The index of the new member, otherwise @c -1 on errors * @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() * @see eina_inarray_insert_at()
* *
* @since 1.2 * @since 1.2
@ -320,7 +316,7 @@ EAPI int eina_inarray_push(Eina_Inarray *array,
const void *data) EINA_ARG_NONNULL(1, 2); const void *data) EINA_ARG_NONNULL(1, 2);
/** /**
* @brief Allocate new item at the end of the array. * @brief Allocates new item at the end of the array.
* *
* @param[in] array The array object * @param[in] array The array object
* @param[in] size The number of new item to allocate * @param[in] size The number of new item to allocate
@ -334,17 +330,16 @@ EAPI void *eina_inarray_grow(Eina_Inarray *array, unsigned int size);
/** /**
* @brief Copies the data to the array at a position found by the comparison function. * @brief Copies the data to the array at a position found by the comparison function.
* @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.
* *
* @param[in] array The array object * @param[in] array The array object
* @param[in] data The data to be copied * @param[in] data The data to be copied
* @param[in] compare The compare function * @param[in] compare The compare function
* @return The index of the new member, otherwise @c -1 on errors * @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 * @note The data given to the @p compare function is a pointer to the member
* memory itself, do no change it. * memory itself, do no change it.
* *
@ -360,17 +355,16 @@ EAPI int eina_inarray_insert(Eina_Inarray *array,
/** /**
* @brief Copies the data to the array at a position found by the comparison function. * @brief Copies the data to the array at a position found by the comparison function.
* @details This copies the given pointer contents at the array position defined by the
* given @p compare function. The pointer is not referenced, instead
* its contents are copied to the members array using the previously
* defined @p member_size.
* *
* @param[in] array The array object * @param[in] array The array object
* @param[in] data The data to be copied * @param[in] data The data to be copied
* @param[in] compare The compare function * @param[in] compare The compare function
* @return The index of the new member, otherwise @c -1 on errors * @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
* its contents are copied to the members array using the previously
* defined @p member_size.
*
* @note The data given to the @p compare function is a pointer to the member * @note The data given to the @p compare function is a pointer to the member
* memory itself, do no change it. * memory itself, do no change it.
* *
@ -387,15 +381,14 @@ EAPI int eina_inarray_insert_sorted(Eina_Inarray *array,
/** /**
* @brief Finds data and removes the matching member. * @brief Finds data and removes the matching member.
* @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().
* *
* @param[in] array The array object * @param[in] array The array object
* @param[in] data The data to be found and removed * @param[in] data The data to be found and removed
* @return The index of the removed member, otherwise @c -1 on errors * @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().
*
* @see eina_inarray_pop() * @see eina_inarray_pop()
* @see eina_inarray_remove_at() * @see eina_inarray_remove_at()
* *
@ -418,16 +411,15 @@ EAPI void *eina_inarray_pop(Eina_Inarray *array) EINA_ARG_NONNULL(1);
/** /**
* @brief Gets the member at the given position. * @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 * @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 * its current memory, then it can be invalidated with functions that
* change the array such as eina_inarray_push(), * change the array such as eina_inarray_push(),
* eina_inarray_insert_at(), or eina_inarray_remove_at(), or variants. * eina_inarray_insert_at(), or eina_inarray_remove_at(), or variants.
* *
* @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()
* @see eina_inarray_lookup_sorted() * @see eina_inarray_lookup_sorted()
* *
@ -438,17 +430,16 @@ EAPI void *eina_inarray_nth(const Eina_Inarray *array,
/** /**
* @brief Copies the data at the given position in the array. * @brief Copies the data at the given position in the array.
* @details This copies the given pointer contents at the given @p position in the
* array. The pointer is not referenced, instead its contents are
* copied to the members array using the previously defined
* @p member_size.
* *
* @param[in] array The array object * @param[in] array The array object
* @param[in] position The position to insert the member at * @param[in] position The position to insert the member at
* @param[in] data The data to be copied at the position * @param[in] data The data to be copied at the position
* @return #EINA_TRUE on success, otherwise #EINA_FALSE on failure * @return #EINA_TRUE on success, otherwise #EINA_FALSE on failure
* *
* @details This copies the given pointer contents at the given @p position in the
* array. The pointer is not referenced, instead its contents are
* copied to the members array using the previously defined
* @p member_size.
*
* @note All the members from @a position to the end of the array are * @note All the members from @a position to the end of the array are
* shifted to the end. * shifted to the end.
* *
@ -495,17 +486,16 @@ EAPI void *eina_inarray_alloc_at(Eina_Inarray *array,
/** /**
* @brief Copies the data to the given position. * @brief Copies the data to the given position.
* @details This copies the given pointer contents at the given @p position in the
* array. The pointer is not referenced, instead its contents are
* copied to the members array using the previously defined
* @p member_size.
* *
* @param[in] array The array object * @param[in] array The array object
* @param[in] position The position to copy the member at * @param[in] position The position to copy the member at
* @param[in] data The data to be copied at the position * @param[in] data The data to be copied at the position
* @return #EINA_TRUE on success, otherwise #EINA_FALSE on failure * @return #EINA_TRUE on success, otherwise #EINA_FALSE on failure
* *
* @details This copies the given pointer contents at the given @p position in the
* array. The pointer is not referenced, instead its contents are
* copied to the members array using the previously defined
* @p member_size.
*
* @note If @p position does not exist, it fails. * @note If @p position does not exist, it fails.
* *
* @since 1.2 * @since 1.2
@ -548,12 +538,11 @@ EAPI void eina_inarray_reverse(Eina_Inarray *array) EINA_ARG_NONNULL(1);
/** /**
* @brief Applies a quick sort to the array. * @brief Applies a quick sort to the array.
* @details This applies a quick sort to the @a array.
* *
* @param[in] array The array object * @param[in] array The array object
* @param[in] compare The compare function * @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 * @note The data given to the @a compare function is a pointer to the member
* memory itself, do no change it. * memory itself, do no change it.
* *
@ -566,15 +555,14 @@ EAPI void eina_inarray_sort(Eina_Inarray *array,
/** /**
* @brief Searches for a member (linear walk). * @brief Searches for a member (linear walk).
* @details This walks through an array by linearly looking for the given data compared by
* the @p compare function.
* *
* @param[in] array The array object * @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 @p compare function
* @param[in] compare The compare function * @param[in] compare The compare function
* @return The member index, otherwise @c -1 if not found * @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 * @note The data given to the @p compare function is a pointer to the member
* memory itself, do no change it. * memory itself, do no change it.
* *
@ -607,14 +595,13 @@ EAPI int eina_inarray_search_sorted(const Eina_Inarray *array,
/** /**
* @brief Calls @p function for each array member. * @brief Calls @p function for each array member.
* @details This calls @p function for every given data in @p array.
* *
* @param[in] array The array object * @param[in] array The array object
* @param[in] function The callback function * @param[in] function The callback function
* @param[in] user_data The user data given to a callback @a 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 * @return #EINA_TRUE if it successfully iterates all the items of the array
* *
* @details This calls @p function for every given data in @p array.
*
* @note This is a safe way to iterate over an array. @p function should return #EINA_TRUE * @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 * as long as you want the function to continue iterating, by
* returning #EINA_FALSE it stops and returns #EINA_FALSE as the result. * returning #EINA_FALSE it stops and returns #EINA_FALSE as the result.
@ -631,15 +618,14 @@ EAPI Eina_Bool eina_inarray_foreach(const Eina_Inarray *array,
/** /**
* @brief Removes all the members that match. * @brief Removes all the members that match.
* @details This removes all the entries in @p array, where the @p match function
* returns #EINA_TRUE.
* *
* @param[in] array The array object * @param[in] array The array object
* @param[in] match The match function * @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 @p match
* @return The number of removed entries, otherwise @c -1 on error * @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 * @since 1.2
*/ */
EAPI int eina_inarray_foreach_remove(Eina_Inarray *array, EAPI int eina_inarray_foreach_remove(Eina_Inarray *array,
@ -669,13 +655,12 @@ EAPI unsigned int eina_inarray_count(const Eina_Inarray *array) EINA_ARG_NONNULL
/** /**
* @brief Returns 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
* @p array.
* *
* @param[in] array The array object * @param[in] array The array object
* @return A new iterator * @return A new iterator
* *
* @details This function returns a newly allocated iterator associated to
* @p array.
*
* @note If the memory cannot be allocated, @c NULL is returned. * @note If the memory cannot be allocated, @c NULL is returned.
* Otherwise, a valid iterator is returned. * Otherwise, a valid iterator is returned.
* *
@ -689,13 +674,12 @@ EAPI Eina_Iterator *eina_inarray_iterator_new(const Eina_Inarray *array) EINA_MA
/** /**
* @brief Returns a new reversed iterator associated to an array. * @brief Returns a new reversed iterator associated to an array.
* @details This function returns a newly allocated iterator associated to
* @p array.
* *
* @param[in] array The array object * @param[in] array The array object
* @return A new iterator * @return A new iterator
* *
* @details This function returns a newly allocated iterator associated to
* @p array.
*
* @note Unlike eina_inarray_iterator_new(), this walks through the array backwards. * @note Unlike eina_inarray_iterator_new(), this walks through the array backwards.
* *
* @note If the memory cannot be allocated, @c NULL is returned. * @note If the memory cannot be allocated, @c NULL is returned.
@ -711,13 +695,12 @@ EAPI Eina_Iterator *eina_inarray_iterator_reversed_new(const Eina_Inarray *array
/** /**
* @brief Returns 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
* @p array.
* *
* @param[in] array The array object * @param[in] array The array object
* @return A new accessor * @return A new accessor
* *
* @details This function returns a newly allocated accessor associated to
* @p array.
*
* @note If the memory cannot be allocated, @c NULL is returned * @note If the memory cannot be allocated, @c NULL is returned
* Otherwise, a valid accessor is returned. * Otherwise, a valid accessor is returned.
* *

102
src/lib/eina/eina_inlist.h
View File

@ -420,9 +420,9 @@ struct _Eina_Inlist
/** /**
* Add a new node to end of a list. * @brief Adds a new node to end of a list.
* *
* @note this code is meant to be fast: appends are O(1) and do not * @note This code is meant to be fast: appends are O(1) and do not
* walk @a in_list. * walk @a in_list.
* *
* @note @a in_item is considered to be in no list. If it was in another * @note @a in_item is considered to be in no list. If it was in another
@ -430,18 +430,18 @@ struct _Eina_Inlist
* check of @a new_l prev and next pointers is done, so it's safe * check of @a new_l prev and next pointers is done, so it's safe
* to have them uninitialized. * to have them uninitialized.
* *
* @param in_list existing list head or @c NULL to create a new list. * @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_item New 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. Use it and not @a in_list anymore.
*/ */
EAPI Eina_Inlist *eina_inlist_append(Eina_Inlist *in_list, EAPI Eina_Inlist *eina_inlist_append(Eina_Inlist *in_list,
Eina_Inlist *in_item) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; 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 beginning of list.
* *
* @note this code is meant to be fast: appends are O(1) and do not * @note This code is meant to be fast: appends are O(1) and do not
* walk @a in_list. * walk @a in_list.
* *
* @note @a new_l is considered to be in no list. If it was in another * @note @a new_l is considered to be in no list. If it was in another
@ -449,18 +449,18 @@ EAPI Eina_Inlist *eina_inlist_append(Eina_Inlist *in_list,
* check of @a new_l prev and next pointers is done, so it's safe * check of @a new_l prev and next pointers is done, so it's safe
* to have them uninitialized. * to have them uninitialized.
* *
* @param in_list existing list head or @c NULL to create a new list. * @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_item New 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. Use it and not @a in_list anymore.
*/ */
EAPI Eina_Inlist *eina_inlist_prepend(Eina_Inlist *in_list, EAPI Eina_Inlist *eina_inlist_prepend(Eina_Inlist *in_list,
Eina_Inlist *in_item) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; 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 list.
* *
* @note this code is meant to be fast: appends are O(1) and do not * @note This code is meant to be fast: appends are O(1) and do not
* walk @a in_list. * walk @a in_list.
* *
* @note @a in_item_l is considered to be in no list. If it was in another * @note @a in_item_l is considered to be in no list. If it was in another
@ -473,20 +473,20 @@ EAPI Eina_Inlist *eina_inlist_prepend(Eina_Inlist *in_list,
* will lead to problems. Giving NULL @a in_relative is the same as * will lead to problems. Giving NULL @a in_relative is the same as
* eina_list_append(). * eina_list_append().
* *
* @param in_list existing list head or @c NULL to create a new list. * @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_item New list node, must not be @c NULL.
* @param in_relative reference node, @a in_item will be added after it. * @param in_relative Reference node, @a in_item will be added after it.
* *
* @return the new list head. Use it and not @a list anymore. * @return The new list head. Use it and not @a list anymore.
*/ */
EAPI Eina_Inlist *eina_inlist_append_relative(Eina_Inlist *in_list, EAPI Eina_Inlist *eina_inlist_append_relative(Eina_Inlist *in_list,
Eina_Inlist *in_item, Eina_Inlist *in_item,
Eina_Inlist *in_relative) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; 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 list.
* *
* @note this code is meant to be fast: appends are O(1) and do not * @note This code is meant to be fast: appends are O(1) and do not
* walk @a in_list. * walk @a in_list.
* *
* @note @a in_item is considered to be in no list. If it was in another * @note @a in_item is considered to be in no list. If it was in another
@ -499,20 +499,20 @@ EAPI Eina_Inlist *eina_inlist_append_relative(Eina_Inlist *in_list,
* will lead to problems. Giving NULL @a in_relative is the same as * will lead to problems. Giving NULL @a in_relative is the same as
* eina_list_prepend(). * eina_list_prepend().
* *
* @param in_list existing list head or @c NULL to create a new list. * @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_item New list node, must not be @c NULL.
* @param in_relative reference node, @a in_item will be added before it. * @param in_relative Reference node, @a in_item will be added before it.
* *
* @return the new list head. Use it and not @a in_list anymore. * @return The new list head. Use it and not @a in_list anymore.
*/ */
EAPI Eina_Inlist *eina_inlist_prepend_relative(Eina_Inlist *in_list, EAPI Eina_Inlist *eina_inlist_prepend_relative(Eina_Inlist *in_list,
Eina_Inlist *in_item, Eina_Inlist *in_item,
Eina_Inlist *in_relative) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; Eina_Inlist *in_relative) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
/** /**
* Remove node from list. * @brief Removes node from list.
* *
* @note this code is meant to be fast: appends are O(1) and do not * @note This code is meant to be fast: appends are O(1) and do not
* walk @a list. * walk @a list.
* *
* @note @a in_item is considered to be inside @a in_list, no checks are * @note @a in_item is considered to be inside @a in_list, no checks are
@ -521,22 +521,22 @@ EAPI Eina_Inlist *eina_inlist_prepend_relative(Eina_Inlist *in_list,
* it will be different from @a list and the wrong new head will * it will be different from @a list and the wrong new head will
* be returned. * be returned.
* *
* @param in_list existing list head, must not be @c NULL. * @param in_list Existing list head, must not be @c NULL.
* @param in_item existing list node, must not be @c NULL. * @param in_item Existing list node, must not be @c NULL.
* *
* @return the new list head. Use it and not @a list anymore. * @return The new list head. Use it and not @a list anymore.
*/ */
EAPI Eina_Inlist *eina_inlist_remove(Eina_Inlist *in_list, EAPI Eina_Inlist *eina_inlist_remove(Eina_Inlist *in_list,
Eina_Inlist *in_item) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT; 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 given node in list, returns itself if found, NULL if not.
* *
* @warning this is an expensive call and has O(n) cost, possibly * @warning This is an expensive call and has O(n) cost, possibly
* walking the whole list. * walking the whole list.
* *
* @param in_list existing list to search @a in_item in, must not be @c NULL. * @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_item What 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.
*/ */
@ -544,43 +544,43 @@ EAPI Eina_Inlist *eina_inlist_find(Eina_Inlist *in_list,
Eina_Inlist *in_item) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; Eina_Inlist *in_item) EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT;
/** /**
* Move existing node to beginning of list. * @brief Moves existing node to beginning of list.
* *
* @note this code is meant to be fast: appends are O(1) and do not * @note This code is meant to be fast: appends are O(1) and do not
* walk @a list. * walk @a list.
* *
* @note @a item is considered to be inside @a list. No checks are * @note @a item is considered to be inside @a list. No checks are
* done to confirm this, and giving nodes from different lists * done to confirm this, and giving nodes from different lists
* will lead to problems. * will lead to problems.
* *
* @param list existing list head or @c NULL to create a new list. * @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. * @param item List node to move to beginning (head), must not be @c NULL.
* *
* @return the new list head. Use it and not @a list anymore. * @return The new list head. Use it and not @a list anymore.
*/ */
EAPI Eina_Inlist *eina_inlist_promote(Eina_Inlist *list, EAPI Eina_Inlist *eina_inlist_promote(Eina_Inlist *list,
Eina_Inlist *item) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT; Eina_Inlist *item) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT;
/** /**
* Move existing node to end of list. * @brief Moves existing node to end of list.
* *
* @note this code is meant to be fast: appends are O(1) and do not * @note This code is meant to be fast: appends are O(1) and do not
* walk @a list. * walk @a list.
* *
* @note @a item is considered to be inside @a list. No checks are * @note @a item is considered to be inside @a list. No checks are
* done to confirm this, and giving nodes from different lists * done to confirm this, and giving nodes from different lists
* will lead to problems. * will lead to problems.
* *
* @param list existing list head or @c NULL to create a new list. * @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 item List node to move to end (tail), must not be @c NULL.
* *
* @return the new list head. Use it and not @a list anymore. * @return The new list head. Use it and not @a list anymore.
*/ */
EAPI Eina_Inlist *eina_inlist_demote(Eina_Inlist *list, EAPI Eina_Inlist *eina_inlist_demote(Eina_Inlist *list,
Eina_Inlist *item) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT; Eina_Inlist *item) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT;
/** /**
* @brief Get the first list node in the list. * @brief Gets the first list node in the list.
* *
* @param list The list to get the first list node from. * @param list The list to get the first list node from.
* @return The first list node in the list. * @return The first list node in the list.
@ -596,7 +596,7 @@ EAPI Eina_Inlist *eina_inlist_demote(Eina_Inlist *list,
static inline Eina_Inlist *eina_inlist_first(const Eina_Inlist *list) EINA_PURE EINA_WARN_UNUSED_RESULT; 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. * @brief Gets the last list node in the list.
* *
* @param list The list to get the last list node from. * @param list The list to get the last list node from.
* @return The last list node in the list. * @return The last list node in the list.
@ -612,7 +612,7 @@ static inline Eina_Inlist *eina_inlist_first(const Eina_Inlist *list) EINA_PURE
static inline Eina_Inlist *eina_inlist_last(const Eina_Inlist *list) EINA_PURE EINA_WARN_UNUSED_RESULT; 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. * @brief Gets the count of the number of items in a list.
* *
* @param list The list whose count to return. * @param list The list whose count to return.
* @return The number of members in the list. * @return The number of members in the list.
@ -663,10 +663,10 @@ EAPI Eina_Iterator *eina_inlist_iterator_new(const Eina_Inlist *in_list) EINA_MA
EAPI Eina_Accessor *eina_inlist_accessor_new(const Eina_Inlist *in_list) EINA_MALLOC EINA_WARN_UNUSED_RESULT; 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.
* *
* @param list The given linked list, @b must be sorted. * @param list The given linked list, @b must be sorted.
* @param item list node to insert, must not be @c NULL. * @param item List node to insert, must not be @c NULL.
* @param func The function called for the sort. * @param func The function called for the sort.
* @return A list pointer. * @return A list pointer.
* @since 1.1.0 * @since 1.1.0
@ -686,7 +686,7 @@ EAPI Eina_Accessor *eina_inlist_accessor_new(const Eina_Inlist *in_list) EINA_MA
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; 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 state with valid data in it.
* *
* @return A valid Eina_Inlist_Sorted_State. * @return A valid Eina_Inlist_Sorted_State.
* @since 1.1.0 * @since 1.1.0
@ -696,7 +696,7 @@ EAPI Eina_Inlist *eina_inlist_sorted_insert(Eina_Inlist *list, Eina_Inlist *item
EAPI Eina_Inlist_Sorted_State *eina_inlist_sorted_state_new(void); 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.
* *
* @param state The state to update * @param state The state to update
* @param list The list to match * @param list The list to match
@ -710,7 +710,7 @@ EAPI Eina_Inlist_Sorted_State *eina_inlist_sorted_state_new(void);
EAPI int eina_inlist_sorted_state_init(Eina_Inlist_Sorted_State *state, Eina_Inlist *list); 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 * @param state The state to destroy
* @since 1.1.0 * @since 1.1.0
@ -720,7 +720,7 @@ EAPI int eina_inlist_sorted_state_init(Eina_Inlist_Sorted_State *state, Eina_Inl
EAPI void eina_inlist_sorted_state_free(Eina_Inlist_Sorted_State *state); 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.
* *
* @param list The given linked list, @b must be sorted. * @param list The given linked list, @b must be sorted.
* @param item list node to insert, must not be @c NULL. * @param item list node to insert, must not be @c NULL.
@ -752,7 +752,7 @@ EAPI Eina_Inlist *eina_inlist_sorted_state_insert(Eina_Inlist *list,
Eina_Compare_Cb func, Eina_Compare_Cb func,
Eina_Inlist_Sorted_State *state); Eina_Inlist_Sorted_State *state);
/** /**
* @brief Sort a list according to the ordering func will return. * @brief Sorts a list according to the ordering func will return.
* *
* @param head The list handle to sort. * @param head The list handle to sort.
* @param func A function pointer that can handle comparing the list data * @param func A function pointer that can handle comparing the list data

18
src/lib/eina/eina_iterator.h
View File

@ -67,7 +67,7 @@
* also printed, so now we go to the cool stuff and use an iterator to do same * also printed, so now we go to the cool stuff and use an iterator to do same
* stuff to a list: * stuff to a list:
* @until eina_iterator_free * @until eina_iterator_free
* @note The only significant diference to the block above is in the * @note The only significant difference to the block above is in the
* function used to create the iterator. * function used to create the iterator.
* *
* And now we free the list and shut eina down: * And now we free the list and shut eina down:
@ -197,7 +197,7 @@ struct _Eina_Iterator
/** /**
* @brief Free an iterator. * @brief Frees an iterator.
* *
* @param iterator The iterator to free. * @param iterator The iterator to free.
* *
@ -207,7 +207,7 @@ EAPI void eina_iterator_free(Eina_Iterator *iterator);
/** /**
* @brief Return the container of an iterator. * @brief Returns the container of an iterator.
* *
* @param iterator The iterator. * @param iterator The iterator.
* @return The container which created the iterator. * @return The container which created the iterator.
@ -218,7 +218,7 @@ EAPI void eina_iterator_free(Eina_Iterator *iterator);
EAPI void *eina_iterator_container_get(Eina_Iterator *iterator) EINA_ARG_NONNULL(1) EINA_PURE; 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 go to the next one.
* *
* @param iterator The iterator. * @param iterator The iterator.
* @param data The data of the element. * @param data The data of the element.
@ -234,7 +234,7 @@ EAPI Eina_Bool eina_iterator_next(Eina_Iterator *iterator,
/** /**
* @brief Iterate over the container and execute a callback on each element. * @brief Iterates over the container and execute a callback on each element.
* *
* @param iterator The iterator. * @param iterator The iterator.
* @param callback The callback called on each iteration. * @param callback The callback called on each iteration.
@ -253,7 +253,7 @@ EAPI void eina_iterator_foreach(Eina_Iterator *iterator,
/** /**
* @brief Lock the container of the iterator. * @brief Locks the container of the iterator.
* *
* @param iterator The iterator. * @param iterator The iterator.
* @return #EINA_TRUE on success, #EINA_FALSE otherwise. * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
@ -269,7 +269,7 @@ EAPI void eina_iterator_foreach(Eina_Iterator *iterator,
EAPI Eina_Bool eina_iterator_lock(Eina_Iterator *iterator) EINA_ARG_NONNULL(1); 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.
* *
* @param iterator The iterator. * @param iterator The iterator.
* @return #EINA_TRUE on success, #EINA_FALSE otherwise. * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
@ -317,7 +317,7 @@ EAPI Eina_Iterator* eina_iterator_filter_new(Eina_Iterator *original, Eina_Each_
/** /**
* @def EINA_ITERATOR_FOREACH * @def EINA_ITERATOR_FOREACH
* @brief Macro to iterate over all elements easily. * @brief Definition for the macro to iterate over all elements easily.
* *
* @param itr The iterator to use. * @param itr The iterator to use.
* @param data Where to store * data, must be a pointer support getting * @param data Where to store * data, must be a pointer support getting
@ -346,7 +346,7 @@ EAPI Eina_Iterator* eina_iterator_filter_new(Eina_Iterator *original, Eina_Each_
* eina_list_free(list); * eina_list_free(list);
* @endcode * @endcode
* *
* @note this example is not optimal algorithm to release a list since * @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 * it will walk the list twice, but it serves as an example. For
* optimized version use EINA_LIST_FREE() * optimized version use EINA_LIST_FREE()
* *

14
src/lib/eina/eina_lalloc.h
View File

@ -65,12 +65,12 @@ typedef void (*Eina_Lalloc_Free)(void *user_data);
typedef struct _Eina_Lalloc Eina_Lalloc; typedef struct _Eina_Lalloc Eina_Lalloc;
/** /**
* @brief Create a new lazy allocator. * @brief Creates a new lazy allocator.
* *
* @param data The data for which memory will be allocated. * @param data The data for which memory will be allocated.
* @param alloc_cb The callback to allocate memory for @p data items. * @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 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. * @param num_init The number of @p data items to initially allocate space for.
* *
* @return A new lazy allocator. * @return A new lazy allocator.
* *
@ -81,7 +81,7 @@ EAPI Eina_Lalloc *eina_lalloc_new(void *data,
int num_init) EINA_ARG_NONNULL(2, 3); int num_init) EINA_ARG_NONNULL(2, 3);
/** /**
* @brief Free the resources for a lazy allocator. * @brief Frees the resources for a lazy allocator.
* *
* @param a The lazy allocator to free. * @param a The lazy allocator to free.
* *
@ -89,23 +89,23 @@ EAPI Eina_Lalloc *eina_lalloc_new(void *data,
EAPI void eina_lalloc_free(Eina_Lalloc *a) EINA_ARG_NONNULL(1); EAPI void eina_lalloc_free(Eina_Lalloc *a) EINA_ARG_NONNULL(1);
/** /**
* @brief Add several elements to a lazy allocator. * @brief Adds several elements to a lazy allocator.
* *
* @param a The lazy allocater to add items to. * @param a The lazy allocater to add items to.
* @param num The number of elements to add. * @param num The number of elements to add.
* *
* @return EINA_TRUE on success, else EINA_FALSE. * @return #EINA_TRUE on success, else #EINA_FALSE.
* *
*/ */
EAPI Eina_Bool eina_lalloc_elements_add(Eina_Lalloc *a, EAPI Eina_Bool eina_lalloc_elements_add(Eina_Lalloc *a,
int num) EINA_ARG_NONNULL(1); int num) EINA_ARG_NONNULL(1);
/** /**
* @brief Allocate one more of whatever the lazy allocator is allocating. * @brief Allocates one more of whatever the lazy allocator is allocating.
* *
* @param a The lazy allocator to add an item to. * @param a The lazy allocator to add an item to.
* *
* @return EINA_TRUE on success, else EINA_FALSE. * @return #EINA_TRUE on success, else #EINA_FALSE.
* *
*/ */
EAPI Eina_Bool eina_lalloc_element_add(Eina_Lalloc *a) EINA_ARG_NONNULL(1); EAPI Eina_Bool eina_lalloc_element_add(Eina_Lalloc *a) EINA_ARG_NONNULL(1);

112
src/lib/eina/eina_list.h
View File

@ -342,7 +342,7 @@ struct _Eina_List_Accounting
/** /**
* @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 list The given list.
* @param data The data to append. * @param data The data to append.
@ -397,7 +397,7 @@ EAPI Eina_List *eina_list_prepend(Eina_List *list, const void *data)
/** /**
* @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 list The given linked list.
* @param data The data to insert. * @param data The data to insert.
@ -430,7 +430,7 @@ EAPI Eina_List *eina_list_append_relative(Eina_List *list, const void
/** /**
* @brief Append a list node to a linked list after the specified member * @brief Appends a list node to a linked list after the specified member.
* *
* @param list The given linked list. * @param list The given linked list.
* @param data The data to insert. * @param data The data to insert.
@ -452,7 +452,7 @@ EAPI Eina_List *eina_list_append_relative_list(Eina_List *list, const
/** /**
* @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 list The given linked list.
* @param data The data to insert. * @param data The data to insert.
@ -485,7 +485,7 @@ EAPI Eina_List *eina_list_prepend_relative(Eina_List *list, const voi
/** /**
* @brief Prepend a list node to a linked list before the specified member * @brief Prepends a list node to a linked list before the specified member.
* *
* @param list The given linked list. * @param list The given linked list.
* @param data The data to insert. * @param data The data to insert.
@ -507,7 +507,7 @@ EAPI Eina_List *eina_list_prepend_relative_list(Eina_List *list, cons
/** /**
* @brief Insert a new node into a sorted list. * @brief Inserts a new node into a sorted list.
* *
* @param list The given linked list, @b must be sorted. * @param list The given linked list, @b must be sorted.
* @param func The function called for the sort. * @param func The function called for the sort.
@ -533,7 +533,7 @@ EAPI Eina_List *eina_list_sorted_insert(Eina_List *list, Eina_Compare
/** /**
* @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.
* *
* @param list The given list. * @param list The given list.
* @param data The specified data. * @param data The specified data.
@ -552,7 +552,7 @@ EAPI Eina_List *eina_list_remove(Eina_List *list, const void *data) E
/** /**
* @brief Remove the specified list node. * @brief Removes the specified list node.
* *
* @param list The given linked list. * @param list The given linked list.
* @param remove_list The list node which is to be removed. * @param remove_list The list node which is to be removed.
@ -590,7 +590,7 @@ EAPI Eina_List *eina_list_remove_list(Eina_List *list, Eina_List *rem
/** /**
* @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 list The list handle to move the data.
* @param move_list The list node to move. * @param move_list The list node to move.
@ -624,7 +624,7 @@ EAPI Eina_List *eina_list_promote_list(Eina_List *list, Eina_List *mo
/** /**
* @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 list The list handle to move the data.
* @param move_list The list node to move. * @param move_list The list node to move.
@ -658,7 +658,7 @@ EAPI Eina_List *eina_list_demote_list(Eina_List *list, Eina_List *mov
/** /**
* @brief Find a member of a list and return the member. * @brief Finds a member of a list and return the member.
* *
* @param list The list to search for a data. * @param list The list to search for a data.
* @param data The data pointer to find in the list. * @param data The data pointer to find in the list.
@ -684,7 +684,7 @@ EAPI Eina_List *eina_list_demote_list(Eina_List *list, Eina_List *mov
EAPI void *eina_list_data_find(const Eina_List *list, const void *data) EINA_PURE EINA_ARG_NONNULL(2) EINA_WARN_UNUSED_RESULT; 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 return the list node containing that member.
* *
* @param list The list to search for data. * @param list The list to search for data.
* @param data The data pointer to find in the list. * @param data The data pointer to find in the list.
@ -701,7 +701,7 @@ EAPI Eina_List *eina_list_data_find_list(const Eina_List *list, const
/** /**
* @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 to The list to move the data to
* @param from The list to move from * @param from The list to move from
@ -717,7 +717,7 @@ EAPI Eina_List *eina_list_data_find_list(const Eina_List *list, const
EAPI Eina_Bool eina_list_move(Eina_List **to, Eina_List **from, void *data); 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.
* *
* @param to The list to move the data to * @param to The list to move the data to
* @param from The list to move from * @param from The list to move from
@ -734,7 +734,7 @@ EAPI Eina_Bool eina_list_move_list(Eina_List **to, Eina_List **from,
/** /**
* @brief Free an entire list and all the nodes, ignoring the data contained. * @brief Frees an entire list and all the nodes, ignoring the data contained.
* @param list The list to free * @param list The list to free
* @return A @c NULL pointer * @return A @c NULL pointer
@ -746,7 +746,7 @@ 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.
* *
* @param list The list to get the specified member number from. * @param list The list to get the specified member number from.
* @param n The number of the element (0 being the first). * @param n The number of the element (0 being the first).
@ -765,9 +765,9 @@ EAPI void *eina_list_nth(const Eina_List *list, unsigned int n)
/** /**
* @brief Get the nth member's list node in a list. * @brief Gets the nth member's list node in a list.
* *
* @param list The list to get the specfied member number from. * @param list The list to get the specified member number from.
* @param n The number of the element (0 being the first). * @param n The number of the element (0 being the first).
* @return The list node stored in the numbered element. * @return The list node stored in the numbered element.
* *
@ -786,14 +786,14 @@ EAPI Eina_List *eina_list_nth_list(const Eina_List *list, unsigned in
/** /**
* @brief Reverse all the elements in the list. * @brief Reverses all the elements in the list.
* *
* @param list The list to reverse. * @param list The list to reverse.
* @return The list head after it has been reversed. * @return The list head after it has been reversed.
* *
* This function reverses the order of all elements in @p list, so the * 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 * last member is now first, and so on. If @p list is @c NULL, this
* functon returns @c NULL. * function returns @c NULL.
* *
* @note @b in-place: this will change the given list, so you should * @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. * now point to the new list head that is returned by this function.
@ -807,14 +807,14 @@ 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 reverse order.
* *
* @param list The list to reverse. * @param list The list to reverse.
* @return The new list that has been reversed. * @return The new list that has been reversed.
* *
* This function reverses the order of all elements in @p list, so the * 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 * 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. * function returns @c NULL. This returns a copy of the given list.
* *
* @note @b copy: this will copy the list and you should then * @note @b copy: this will copy the list and you should then
* eina_list_free() when it is not required anymore. * eina_list_free() when it is not required anymore.
@ -828,7 +828,7 @@ 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 exactly same order.
* *
* @param list The list to clone. * @param list The list to clone.
* @return The new list that has been cloned. * @return The new list that has been cloned.
@ -848,13 +848,13 @@ 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 func will return.
* *
* @param list The list handle to sort. * @param list The list handle to sort.
* @param limit The maximum number of list elements to sort. * @param limit The maximum number of list elements to sort.
* @param func A function pointer that can handle comparing the list data * @param func A function pointer that can handle comparing the list data
* nodes. * nodes.
* @return the new head of list. * @return The new head of list.
* *
* This function sorts @p list. If @p limit is 0 or greater than the number of * 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 * elements in @p list, all the elements are sorted. @p func is used to
@ -891,17 +891,17 @@ EAPI Eina_List *eina_list_sort(Eina_List *list, unsigned int limit, E
/** /**
* @brief Shuffle list. * @brief Shuffles list.
* *
* @param list The list handle to shuffle. * @param list The list handle to shuffle.
* @param func A function pointer that can return an int between 2 inclusive values * @param func A function pointer that can return an int between 2 inclusive values
* @return the new head of list. * @return The new head of list.
* *
* This function shuffles @p list. * This function shuffles @p list.
* @p func is used to generate random list indexes within the range of * @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. * 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 * @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. * now point to the new list head that is returned by this function.
* *
* @since 1.8 * @since 1.8
@ -912,7 +912,7 @@ EAPI Eina_List *eina_list_shuffle(Eina_List *list, Eina_Random_Cb fun
/** /**
* @brief Merge two list. * @brief Merges two list.
* *
* @param left Head list to merge. * @param left Head list to merge.
* @param right Tail list to merge. * @param right Tail list to merge.
@ -922,7 +922,7 @@ EAPI Eina_List *eina_list_shuffle(Eina_List *list, Eina_Random_Cb fun
* *
* Both left and right do not exist anymore after the merge. * Both left and right do not exist anymore after the merge.
* *
* @note merge cost is O(n), being @b n the size of the smallest * @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, * list. This is due the need to fix accounting of that segment,
* making count and last access O(1). * making count and last access O(1).
* *
@ -932,7 +932,7 @@ EAPI Eina_List *eina_list_merge(Eina_List *left, Eina_List *right) EI
/** /**
* @brief Merge two sorted list according to the ordering func will return. * @brief Merges two sorted list according to the ordering func will return.
* *
* @param left First list to merge. * @param left First list to merge.
* @param right Second list to merge. * @param right Second list to merge.
@ -972,7 +972,7 @@ EAPI Eina_List *eina_list_sorted_merge(Eina_List *left, Eina_List *ri
/** /**
* @brief Split a list into 2 lists. * @brief Splits a list into 2 lists.
* *
* @param list List to split. * @param list List to split.
* @param relative The list will be split after @p relative. * @param relative The list will be split after @p relative.
@ -997,12 +997,12 @@ EAPI Eina_List *eina_list_split_list(Eina_List *list, Eina_List *rela
* @param list The list to search for data, @b must be sorted. * @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 func A function pointer that can handle comparing the list data nodes.
* @param data reference value to search. * @param data reference value to search.
* @param result_cmp if provided returns the result of * @param result_cmp If provided returns the result of
* func(node->data, data) node being the last (returned) node. If node * 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 * 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 * 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(). * greater than 0. It is the last value returned by func().
* @return the nearest node, @c NULL if not found. * @return The nearest node, @c NULL if not found.
* *
* This function searches for a node containing @p data as its data in @p list, * 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 * if such a node exists it will be returned and @p result_cmp will be @p 0. If
@ -1059,7 +1059,7 @@ EAPI Eina_List *eina_list_search_sorted_near_list(const Eina_List *li
* @param list The list to search for data, @b must be sorted. * @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 func A function pointer that can handle comparing the list data nodes.
* @param data reference value to search. * @param data reference value to search.
* @return the node if func(node->data, data) == 0, @c NULL if not found. * @return The node if func(node->data, data) == 0, @c NULL if not found.
* *
* This can be used to check if some value is inside the list and get * 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 * the container node in this case. It should be used when list is
@ -1095,8 +1095,8 @@ EAPI Eina_List *eina_list_search_sorted_list(const Eina_List *list, E
* @param list The list to search for data, @b must be sorted. * @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 func A function pointer that can handle comparing the list data nodes.
* @param data reference value to search. * @param data reference value to search.
* @return the node value (@c node->data) if func(node->data, data) == 0, * @return The node value (@c node->data) if func(node->data, data) == 0,
* NULL if not found. * @c NULL if not found.
* *
* This can be used to check if some value is inside the list and get * 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 * the existing instance in this case. It should be used when list is
@ -1131,7 +1131,7 @@ EAPI void *eina_list_search_sorted(const Eina_List *list, Eina_C
* @param list The list to search for data, may be unsorted. * @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 func A function pointer that can handle comparing the list data nodes.
* @param data reference value to search. * @param data reference value to search.
* @return the node if func(node->data, data) == 0, @c NULL if not found. * @return The node if func(node->data, data) == 0, @c NULL if not found.
* *
* This can be used to check if some value is inside the list and get * This can be used to check if some value is inside the list and get
* the container node in this case. * the container node in this case.
@ -1157,7 +1157,7 @@ EAPI Eina_List *eina_list_search_unsorted_list(const Eina_List *list,
* @param list The list to search for data, may be unsorted. * @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 func A function pointer that can handle comparing the list data nodes.
* @param data reference value to search. * @param data reference value to search.
* @return the node value (@c node->data) if func(node->data, data) == 0, * @return The node value (@c node->data) if func(node->data, data) == 0,
* @c NULL if not found. * @c NULL if not found.
* *
* This can be used to check if some value is inside the list and get * This can be used to check if some value is inside the list and get
@ -1178,7 +1178,7 @@ 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); 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.
* *
* @param list The list to get the last list node from. * @param list The list to get the last list node from.
* @return The last list node in the list. * @return The last list node in the list.
@ -1194,7 +1194,7 @@ EAPI void *eina_list_search_unsorted(const Eina_List *list, Eina
static inline Eina_List *eina_list_last(const Eina_List *list) EINA_PURE EINA_WARN_UNUSED_RESULT; 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 * @param list The list node to get the next list node from
* @return The next list node on success, @c NULL otherwise. * @return The next list node on success, @c NULL otherwise.
@ -1208,10 +1208,10 @@ static inline Eina_List *eina_list_last(const Eina_List *list) EINA_PURE EINA_
static inline Eina_List *eina_list_next(const Eina_List *list) EINA_PURE EINA_WARN_UNUSED_RESULT; 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.
* *
* @param list The list node to get the previous list node from. * @param list The list node to get the previous list node from.
* @return The previous list node o success, @c NULL otherwise. * @return The previous list node on success, @c NULL otherwise.
* if no previous list node exists * if no previous list node exists
* *
* This function returns the previous list node before the current one * This function returns the previous list node before the current one
@ -1223,7 +1223,7 @@ static inline Eina_List *eina_list_next(const Eina_List *list) EINA_PURE EINA_
static inline Eina_List *eina_list_prev(const Eina_List *list) EINA_PURE EINA_WARN_UNUSED_RESULT; 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.
* *
* @param list The list node to get the data member of. * @param list The list node to get the data member of.
* @return The data member from the list node. * @return The data member from the list node.
@ -1237,7 +1237,7 @@ static inline Eina_List *eina_list_prev(const Eina_List *list) EINA_PURE EINA_
static inline void *eina_list_data_get(const Eina_List *list) EINA_PURE EINA_WARN_UNUSED_RESULT; 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 list The list node to get the data member of.
* @param data The data member to the list node. * @param data The data member to the list node.
@ -1252,7 +1252,7 @@ static inline void *eina_list_data_get(const Eina_List *list) EINA_PURE E
static inline void *eina_list_data_set(Eina_List *list, const void *data); 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.
* *
* @param list The list whose count to return. * @param list The list whose count to return.
* @return The number of members in the list. * @return The number of members in the list.
@ -1268,7 +1268,7 @@ static inline void *eina_list_data_set(Eina_List *list, const void *data)
static inline unsigned int eina_list_count(const Eina_List *list) EINA_PURE; static inline unsigned int eina_list_count(const Eina_List *list) EINA_PURE;
/** /**
* @brief Returns the last list node's data * @brief Returns the last list node's data.
* *
* @param list The list * @param list The list
* @return The node's data, or @c NULL on being passed a @c NULL pointer * @return The node's data, or @c NULL on being passed a @c NULL pointer
@ -1279,7 +1279,7 @@ static inline unsigned int eina_list_count(const Eina_List *list) EINA_PURE;
static inline void *eina_list_last_data_get(const Eina_List *list); static inline void *eina_list_last_data_get(const Eina_List *list);
/** /**
* @brief Returned a new iterator associated to a list. * @brief Returns a new iterator associated to a list.
* *
* @param list The list. * @param list The list.
* @return A new iterator. * @return A new iterator.
@ -1303,7 +1303,7 @@ EAPI Eina_Iterator *eina_list_iterator_new(const Eina_List *list) EINA_MA
/** /**
* @brief Returned a new reversed iterator associated to a list. * @brief Returns a new reversed iterator associated to a list.
* *
* @param list The list. * @param list The list.
* @return A new iterator. * @return A new iterator.
@ -1329,7 +1329,7 @@ EAPI Eina_Iterator *eina_list_iterator_reversed_new(const Eina_List *list
/** /**
* @brief Returned a new accessor associated to a list. * @brief Returns a new accessor associated to a list.
* *
* @param list The list. * @param list The list.
* @return A new accessor. * @return A new accessor.
@ -1345,7 +1345,7 @@ EAPI Eina_Iterator *eina_list_iterator_reversed_new(const Eina_List *list
EAPI Eina_Accessor *eina_list_accessor_new(const Eina_List *list) EINA_MALLOC EINA_WARN_UNUSED_RESULT; EAPI Eina_Accessor *eina_list_accessor_new(const Eina_List *list) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
/** /**
* @brief Find the member of the list and return the index. * @brief Finds the member of the list and return the index.
* *
* @param list The list. * @param list The list.
* @param data The data member. * @param data The data member.
@ -1363,7 +1363,7 @@ EAPI int eina_list_data_idx(const Eina_List *list, void *data)
/** /**
* @def EINA_LIST_FOREACH * @def EINA_LIST_FOREACH
* @brief Macro to iterate over a list. * @brief Definition for the macro to iterate over a list.
* *
* @param list The list to iterate over. * @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 A list that is used as an iterator and points to the current node.
@ -1424,7 +1424,7 @@ EAPI int eina_list_data_idx(const Eina_List *list, void *data)
/** /**
* @def EINA_LIST_REVERSE_FOREACH * @def EINA_LIST_REVERSE_FOREACH
* @brief Macro to iterate over a list in the reverse order. * @brief Definition for the macro to iterate over a list in the reverse order.
* *
* @param list The list to iterate over. * @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 A list that is used as an iterator and points to the current node.
@ -1484,7 +1484,7 @@ EAPI int eina_list_data_idx(const Eina_List *list, void *data)
/** /**
* @def EINA_LIST_FOREACH_SAFE * @def EINA_LIST_FOREACH_SAFE
* @brief Macro to iterate over a list with support for node deletion. * @brief Definition for the macro to iterate over a list with support for node deletion.
* *
* @param list The list to iterate over. * @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 A list that is used as an iterator and points to the current node.
@ -1543,7 +1543,7 @@ EAPI int eina_list_data_idx(const Eina_List *list, void *data)
/** /**
* @def EINA_LIST_REVERSE_FOREACH_SAFE * @def EINA_LIST_REVERSE_FOREACH_SAFE
* @brief Macro to iterate over a list in the reverse order with support * @brief Definition for the macro to iterate over a list in the reverse order with support
* for deletion. * for deletion.
* *
* @param list The list to iterate over. * @param list The list to iterate over.
@ -1604,7 +1604,7 @@ EAPI int eina_list_data_idx(const Eina_List *list, void *data)
/** /**
* @def EINA_LIST_FREE * @def EINA_LIST_FREE
* @brief Macro to remove each list node while having access to each node's data. * @brief Definition for the macro to remove each list node while having access to each node's data.
* *
* @param list The list that will be cleared. * @param list The list that will be cleared.
* @param data Current node's data. * @param data Current node's data.

224
src/lib/eina/eina_lock.h
View File

@ -37,7 +37,7 @@
* <a href="https://computing.llnl.gov/tutorials/pthreads/">here</a> * <a href="https://computing.llnl.gov/tutorials/pthreads/">here</a>
* *
* The Eina lock functions are grouped into several categories to handle different * The Eina lock functions are grouped into several categories to handle different
* thread locking and sychronization methods: * thread locking and synchronization methods:
* @li eina_lock_* - Functions that implement locking. * @li eina_lock_* - Functions that implement locking.
* @li eina_condition_* - Functions that implement condition variables. * @li eina_condition_* - Functions that implement condition variables.
* @li eina_rwlock_* - Functions that implement read/write locks. * @li eina_rwlock_* - Functions that implement read/write locks.
@ -45,7 +45,7 @@
* @li eina_semaphore_* - Functions that implement semaphores. * @li eina_semaphore_* - Functions that implement semaphores.
* @li eina_barrier_* - Functions that implement barriers. * @li eina_barrier_* - Functions that implement barriers.
* @li eina_spinlock_* - Functions that implement spinlocks if they are available * @li eina_spinlock_* - Functions that implement spinlocks if they are available
* on the platform. If they are not available, these functuions degrade to plain locks. * on the platform. If they are not available, these functions degrade to plain locks.
* *
* *
* *
@ -93,7 +93,7 @@ typedef enum
} Eina_Lock_Result; } Eina_Lock_Result;
/** /**
* @brief A callback type for deallocation of thread level sotrage data. * @brief A callback type for deallocation of thread level storage data.
*/ */
typedef void (*Eina_TLS_Delete_Cb)(void *ptr); typedef void (*Eina_TLS_Delete_Cb)(void *ptr);
@ -136,19 +136,22 @@ static inline Eina_Bool eina_lock_new(Eina_Lock *mutex);
static inline Eina_Bool eina_lock_recursive_new(Eina_Lock *mutex); static inline Eina_Bool eina_lock_recursive_new(Eina_Lock *mutex);
/** /**
* @brief Deallocates an #Eina_Lock * @brief Deallocates an #Eina_Lock.
*
* @param[in] mutex The #Eina_Lock structure to be deallocated
*
* @details This function deallocates an #Eina_Lock allocated by eina_lock_new() * @details This function deallocates an #Eina_Lock allocated by eina_lock_new()
* and does any platform dependent cleanup that is required. * and does any platform dependent cleanup that is required.
* *
* @param[in] mutex The #Eina_Lock structure to be deallocated
*
* @see eina_lock_new() * @see eina_lock_new()
*/ */
static inline void eina_lock_free(Eina_Lock *mutex); static inline void eina_lock_free(Eina_Lock *mutex);
/** /**
* @brief Attempts to take a lock. * @brief Attempts to take a lock.
* @details This function attempts to gain a lock on the indicated #Eina_Lock. If the
* underlying #Eina_Lock is locked already, this call can be blocked until
* the lock is released. This is appropriate in many cases, but consider using
* eina_lock_take_try() if you don't need to block.
* *
* @param[in] mutex The #Eina_Lock to take * @param[in] mutex The #Eina_Lock to take
* *
@ -156,11 +159,6 @@ static inline void eina_lock_free(Eina_Lock *mutex);
* a deadlock condition exists, it returns #EINA_LOCK_DEADLOCK. If some other * a deadlock condition exists, it returns #EINA_LOCK_DEADLOCK. If some other
* condition causes the take to fail, #EINA_LOCK_FAIL is returned. * condition causes the take to fail, #EINA_LOCK_FAIL is returned.
* *
* @details This function attempts to gain a lock on the indicated #Eina_Lock. If the
* underlying #Eina_Lock is locked already, this call can be blocked until
* the lock is released. This is appropriate in many cases, but consider using
* eina_lock_take_try() if you don't need to block.
*
* @see eina_lock_take_try() * @see eina_lock_take_try()
* @see eina_lock_release() * @see eina_lock_release()
*/ */
@ -168,6 +166,8 @@ static inline Eina_Lock_Result eina_lock_take(Eina_Lock *mutex);
/** /**
* @brief Attempts to take a lock if possible. * @brief Attempts to take a lock if possible.
* @details This function attempts to gain a lock on the indicated #Eina_Lock.
Identical eina_lock_take(), but returns immediately if the lock is already taken.
* *
* @param[in] mutex The #Eina_Lock to take * @param[in] mutex The #Eina_Lock to take
* *
@ -175,9 +175,6 @@ static inline Eina_Lock_Result eina_lock_take(Eina_Lock *mutex);
* a deadlock condition exists, it returns #EINA_LOCK_DEADLOCK. If some other * a deadlock condition exists, it returns #EINA_LOCK_DEADLOCK. If some other
* condition causes the take to fail, #EINA_LOCK_FAIL is returned. * condition causes the take to fail, #EINA_LOCK_FAIL is returned.
* *
* @details This function attempts to gain a lock on the indicated #Eina_Lock.
Identical eina_lock_take(), but returns immediately if the lock is already taken.
*
* @see eina_lock_take() * @see eina_lock_take()
* @see eina_lock_release() * @see eina_lock_release()
*/ */
@ -185,30 +182,28 @@ static inline Eina_Lock_Result eina_lock_take_try(Eina_Lock *mutex);
/** /**
* @brief Releases a lock. * @brief Releases a lock.
*
* @param[in] mutex The #Eina_Lock to release
*
* @return Returns #EINA_LOCK_SUCCEED on success. If it fails, #EINA_LOCK_FAIL is
* returned.
*
* @details This function releases the lock on the indicated #Eina_Lock. If successful, * @details This function releases the lock on the indicated #Eina_Lock. If successful,
* and @c EINA_HAVE_DEBUG_THREADS is defined, @p mutex is updated and information * and @c EINA_HAVE_DEBUG_THREADS is defined, @p mutex is updated and information
* about the locking process is removed (e.g. thread number and backtrace for POSIX). * about the locking process is removed (e.g. thread number and backtrace for POSIX).
* *
* @param[in] mutex The #Eina_Lock to release
*
* @return Returns #EINA_LOCK_SUCCEED on success, If it fails, #EINA_LOCK_FAIL is
* returned.
*
* @see eina_lock_take() * @see eina_lock_take()
* @see eina_lock_take_try() * @see eina_lock_take_try()
*/ */
static inline Eina_Lock_Result eina_lock_release(Eina_Lock *mutex); static inline Eina_Lock_Result eina_lock_release(Eina_Lock *mutex);
/** /**
* @brief Print debug information about a lock. * @brief Prints debug information about a lock.
*
* @param[in] mutex The #Eina_Lock to print debug info for.
*
* @details This function prints debug information for @p mutex. The information is * @details This function prints debug information for @p mutex. The information is
* platform dependant. On POSIX systems it prints the address of @p mutex, * platform dependant. On POSIX systems it prints the address of @p mutex,
* lock state, thread number and a backtrace. * lock state, thread number and a backtrace.
* *
* @param[in] mutex The #Eina_Lock to print debug info for.
*
* @note If @c EINA_HAVE_DEBUG_THREADS is not defined, this function does nothing. * @note If @c EINA_HAVE_DEBUG_THREADS is not defined, this function does nothing.
* *
* @since 1.19 * @since 1.19
@ -217,15 +212,14 @@ EAPI void eina_lock_debug(const Eina_Lock *mutex);
/** /**
* @brief Initializes a new condition variable. * @brief Initializes a new condition variable.
* @details This function initializes an #Eina_Condition structure and associates it with
* an existing lock.
* *
* @param[in] cond The condition variable to create * @param[in] cond The condition variable to create
* @param[in] mutex The #Eina_Lock structure that controls access to this condition variable * @param[in] mutex The #Eina_Lock structure that controls access to this condition variable
* *
* @return #EINA_TRUE on success, #EINA_FALSE otherwise. * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
* *
* @details This function initializes an #Eina_Condition structure and associates it with
* an existing lock.
*
* Condition variables are used to coordinate actions between threads. See * Condition variables are used to coordinate actions between threads. See
* <a href="https://computing.llnl.gov/tutorials/pthreads/#ConVarOverview"> Condition Varable Overview </a> * <a href="https://computing.llnl.gov/tutorials/pthreads/#ConVarOverview"> Condition Varable Overview </a>
* for an introduction to condition variables and their use. * for an introduction to condition variables and their use.
@ -235,33 +229,33 @@ EAPI void eina_lock_debug(const Eina_Lock *mutex);
static inline Eina_Bool eina_condition_new(Eina_Condition *cond, Eina_Lock *mutex); static inline Eina_Bool eina_condition_new(Eina_Condition *cond, Eina_Lock *mutex);
/** /**
* @brief Deallocates a condition variable * @brief Deallocates a condition variable.
*
* @param[in] cond The condition variable to be deallocated.
*
* @details This function deallocates a condition variable and does any platform dependent * @details This function deallocates a condition variable and does any platform dependent
* cleanup that is required. * cleanup that is required.
* *
* @param[in] cond The condition variable to be deallocated.
*
* @see eina_condition_new() * @see eina_condition_new()
*/ */
static inline void eina_condition_free(Eina_Condition *cond); static inline void eina_condition_free(Eina_Condition *cond);
/** /**
* @brief Causes a thread to wait until signaled by the condition. * @brief Causes a thread to wait until signaled by the condition.
* @details This function makes a thread block until a signal is sent to it via @p cond.
* *
* @param[in] cond The #Eina_Condition upon which the thread waits. * @param[in] cond The #Eina_Condition upon which the thread waits.
* *
* @return #EINA_TRUE on success, #EINA_FALSE otherwise. * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
* *
* @details This function makes a thread block until a signal is sent to it via @p cond.
*
* @see eina_condition_timedwait() * @see eina_condition_timedwait()
*/ */
static inline Eina_Bool eina_condition_wait(Eina_Condition *cond); static inline Eina_Bool eina_condition_wait(Eina_Condition *cond);
/** /**
* @brief Causes a thread to wait until signaled by the condition or a * @brief Causes a thread to wait until signalled by the condition or a
* timeout is reached. * timeout is reached.
* @details This function makes a thread block until either a signal is sent to it via
* @p cond or @p t seconds have passed.
* *
* @param[in] cond The #Eina_Condition upon which the thread waits. * @param[in] cond The #Eina_Condition upon which the thread waits.
* @param[in] t The maximum amount of time to wait, in seconds. * @param[in] t The maximum amount of time to wait, in seconds.
@ -269,39 +263,34 @@ static inline Eina_Bool eina_condition_wait(Eina_Condition *cond);
* @return #EINA_TRUE on success, #EINA_FALSE otherwise. If the operation * @return #EINA_TRUE on success, #EINA_FALSE otherwise. If the operation
* timed out, eina error will be set to #ETIMEDOUT. * timed out, eina error will be set to #ETIMEDOUT.
* *
* @details This function makes a thread block until either a signal is sent to it via
* @p cond or @p t seconds have passed.
*
* @see eina_condition_wait() * @see eina_condition_wait()
*/ */
static inline Eina_Bool eina_condition_timedwait(Eina_Condition *cond, double t); static inline Eina_Bool eina_condition_timedwait(Eina_Condition *cond, double t);
/** /**
* @brief Signal all threads waiting for a condition. * @brief Signals all threads waiting for a condition.
* @details This function sends a signal to all the threads waiting on the condition @p cond.
* If you know for sure that there is only one thread waiting, use eina_condition_signal()
* instead to gain a little optimization.
* *
* @param[in] cond The #Eina_Condition that signals all its waiting threads. * @param[in] cond The #Eina_Condition that signals all its waiting threads.
* *
* @return #EINA_TRUE on success, #EINA_FALSE otherwise. * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
* *
* @details This function sends a signal to all the threads waiting on the condition @p cond.
* If you know for sure that there is only one thread waiting, use eina_condition_signal()
* instead to gain a little optimization.
*
* @see eina_condition_signal() * @see eina_condition_signal()
*/ */
static inline Eina_Bool eina_condition_broadcast(Eina_Condition *cond); static inline Eina_Bool eina_condition_broadcast(Eina_Condition *cond);
/** /**
* @brief Signal a thread waiting for a condition. * @brief Signals a thread waiting for a condition.
* @details This function sends a signal to a thread waiting on the condition @p cond.
* If you do not know for sure that there is only one thread waiting, use
* eina_condition_broadcast() instead.
* *
* @param[in] cond The #Eina_Condition that signals its waiting thread. * @param[in] cond The #Eina_Condition that signals its waiting thread.
* *
* @return #EINA_TRUE on success, #EINA_FALSE otherwise. * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
* *
* @details This function sends a signal to a thread waiting on the condition @p cond.
* If you do not know for sure that there is only one thread waiting, use
* eina_condition_broadcast() instead.
*
* @note If there is more than one thread waiting on this condition, one of them is * @note If there is more than one thread waiting on this condition, one of them is
* signalled, but which one is undefined. * signalled, but which one is undefined.
* *
@ -311,43 +300,40 @@ static inline Eina_Bool eina_condition_signal(Eina_Condition *cond);
/** /**
* @brief Initializes a new #Eina_RWLock * @brief Initializes a new #Eina_RWLock.
* @details This function initializes an #Eina_RWLock with appropriate values.
* These values are platform dependent as is the structure of the #Eina_RWLock
* itself.
* *
* @param[in] mutex The #Eina_RWLock to be initialized. * @param[in] mutex The #Eina_RWLock to be initialized.
* *
* @return #EINA_TRUE on success, #EINA_FALSE otherwise. * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
* *
* @details This function initializes an #Eina_RWLock with appropriate values.
* These values are platform dependent as is the structure of the #Eina_RWLock
* itself.
*
* @see eina_rwlock_free() * @see eina_rwlock_free()
*/ */
static inline Eina_Bool eina_rwlock_new(Eina_RWLock *mutex); static inline Eina_Bool eina_rwlock_new(Eina_RWLock *mutex);
/** /**
* @brief Deallocates an #Eina_RWLock * @brief Deallocates an #Eina_RWLock.
*
* @param[in] mutex The #Eina_RWLock structure to be deallocated.
*
* @details This function deallocates an #Eina_RWLock and does any platform dependent * @details This function deallocates an #Eina_RWLock and does any platform dependent
* cleanup that is required. * cleanup that is required.
* *
* @param[in] mutex The #Eina_RWLock structure to be deallocated.
*
* @see eina_rwlock_new() * @see eina_rwlock_new()
*/ */
static inline void eina_rwlock_free(Eina_RWLock *mutex); static inline void eina_rwlock_free(Eina_RWLock *mutex);
/** /**
* @brief Attempts to take a read lock. * @brief Attempts to take a read lock.
* @details This function attempts to gain a read lock on the indicated #Eina_RWLock. If
* the #Eina_RWLock is write locked, this call can be blocked until
* the lock is released.
* *
* @param[in] mutex The #Eina_RWLock to take. * @param[in] mutex The #Eina_RWLock to take.
* *
* @return Returns #EINA_LOCK_SUCCEED on success, #EINA_LOCK_FAIL on failure. * @return Returns #EINA_LOCK_SUCCEED on success, #EINA_LOCK_FAIL on failure.
* *
* @details This function attempts to gain a read lock on the indicated #Eina_RWLock. If
* the #Eina_RWLock is write locked, this call can be blocked until
* the lock is released.
*
* @note This function never return #EINA_LOCK_DEADLOCK. * @note This function never return #EINA_LOCK_DEADLOCK.
* *
* @see eina_rwlock_release() * @see eina_rwlock_release()
@ -356,15 +342,14 @@ static inline Eina_Lock_Result eina_rwlock_take_read(Eina_RWLock *mutex);
/** /**
* @brief Attempts to take a write lock. * @brief Attempts to take a write lock.
* @details This function attempts to gain a write lock on the indicated #Eina_RWLock. If
* the #Eina_RWLock is locked for reading or writing, this call can be
* blocked until the lock is released.
* *
* @param[in] mutex The #Eina_RWLock to take. * @param[in] mutex The #Eina_RWLock to take.
* *
* @return Returns #EINA_LOCK_SUCCEED on success, #EINA_LOCK_FAIL on failure. * @return Returns #EINA_LOCK_SUCCEED on success, #EINA_LOCK_FAIL on failure.
* *
* @details This function attempts to gain a write lock on the indicated #Eina_RWLock. If
* the #Eina_RWLock is locked for reading or writing, this call can be
* blocked until the lock is released.
*
* @note This function never return #EINA_LOCK_DEADLOCK. * @note This function never return #EINA_LOCK_DEADLOCK.
* *
* @see eina_rwlock_release() * @see eina_rwlock_release()
@ -373,14 +358,13 @@ static inline Eina_Lock_Result eina_rwlock_take_write(Eina_RWLock *mutex);
/** /**
* @brief Releases a lock. * @brief Releases a lock.
* @details This function releases the lock on the indicated #Eina_RWLock.
* *
* @param[in] mutex The #Eina_RWLock to release. * @param[in] mutex The #Eina_RWLock to release.
* *
* @return Returns #EINA_LOCK_SUCCEED on success. If it fails, #EINA_LOCK_FAIL is * @return Returns #EINA_LOCK_SUCCEED on success. If it fails, #EINA_LOCK_FAIL is
* returned. * returned.
* *
* @details This function releases the lock on the indicated #Eina_RWLock.
*
* @see eina_rwlock_take_read() * @see eina_rwlock_take_read()
* @see eina_rwlock_take_write() * @see eina_rwlock_take_write()
*/ */
@ -389,15 +373,14 @@ static inline Eina_Lock_Result eina_rwlock_release(Eina_RWLock *mutex);
/** /**
* @brief Initializes a new #Eina_TLS, or thread level storage, to store thread * @brief Initializes a new #Eina_TLS, or thread level storage, to store thread
* specific data. * specific data.
* @details This function initializes an #Eina_TLS with @p key but does not set a
* callback to deallocate @p key when the thread exits. The implementation
* is platform dependent as is the structure of the #Eina_TLS itself.
* *
* @param[in] key The #Eina_TLS to be initialized. * @param[in] key The #Eina_TLS to be initialized.
* *
* @return #EINA_TRUE on success, #EINA_FALSE otherwise. * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
* *
* @details This function initializes an #Eina_TLS with @p key but does not set a
* callback to deallocate @p key when the thread exits. The implementation
* is platform dependent as is the structure of the #Eina_TLS itself.
*
* @note use eina_tls_cb_new() instead to set a callback for deallocating @p key. * @note use eina_tls_cb_new() instead to set a callback for deallocating @p key.
* *
* @see eina_tls_cb_new() * @see eina_tls_cb_new()
@ -408,16 +391,15 @@ static inline Eina_Bool eina_tls_new(Eina_TLS *key);
/** /**
* @brief Initializes a new #Eina_TLS, or thread level storage, to store thread * @brief Initializes a new #Eina_TLS, or thread level storage, to store thread
* specific data. * specific data.
* @details This function initializes an #Eina_TLS with @p key and sets a
* callback to deallocate @p key when the thread exits. The implementation
* is platform dependent as is the structure of the #Eina_TLS itself.
* *
* @param[in] key The #Eina_TLS to be initialized. * @param[in] key The #Eina_TLS to be initialized.
* @param[in] delete_cb A pointer to a function that deallocates @p key. * @param[in] delete_cb A pointer to a function that deallocates @p key.
* *
* @return #EINA_TRUE on success, #EINA_FALSE otherwise. * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
* *
* @details This function initializes an #Eina_TLS with @p key and sets a
* callback to deallocate @p key when the thread exits. The implementation
* is platform dependent as is the structure of the #Eina_TLS itself.
*
* @see eina_tls_new() * @see eina_tls_new()
* @see eina_tls_free() * @see eina_tls_free()
*/ */
@ -425,12 +407,11 @@ static inline Eina_Bool eina_tls_cb_new(Eina_TLS *key, Eina_TLS_Delete_Cb delete
/** /**
* @brief Frees an allocated #Eina_TLS. * @brief Frees an allocated #Eina_TLS.
*
* @param[in] key The #Eina_TLS to be freed.
*
* @details This function frees the #Eina_TLS @p key. The implementation * @details This function frees the #Eina_TLS @p key. The implementation
* is platform dependent. * is platform dependent.
* *
* @param[in] key The #Eina_TLS to be freed.
*
* @see eina_tls_new() * @see eina_tls_new()
* @see eina_tls_cb_new() * @see eina_tls_cb_new()
*/ */
@ -438,27 +419,25 @@ static inline void eina_tls_free(Eina_TLS key);
/** /**
* @brief Gets the value in #Eina_TLS for this thread. * @brief Gets the value in #Eina_TLS for this thread.
* @details This function gets a pointer to the data associated with #Eina_TLS @p key for
* this thread. The implementation is platform dependent.
* *
* @param[in] key The #Eina_TLS to be retrieved. * @param[in] key The #Eina_TLS to be retrieved.
* *
* @return A pointer to the data associated with @p key. * @return A pointer to the data associated with @p key.
* *
* @details This function gets a pointer to the data associated with #Eina_TLS @p key for
* this thread. The implementation is platform dependent.
*
* @see eina_tls_set() * @see eina_tls_set()
*/ */
static inline void *eina_tls_get(Eina_TLS key); static inline void *eina_tls_get(Eina_TLS key);
/** /**
* @brief Sets the value in Eina_TLS for this thread. * @brief Sets the value in Eina_TLS for this thread.
* @details This function sets the value associated with @p key to the pointer to the data
* @p data. The implementation is platform dependent.
* *
* @param[in] key The #Eina_TLS to be set. * @param[in] key The #Eina_TLS to be set.
* @param[in] data A pointer to the data to be stored. * @param[in] data A pointer to the data to be stored.
* *
* @details This function sets the value associated with @p key to the pointer to the data
* @p data. The implementation is platform dependent.
*
* @return #EINA_TRUE on success, #EINA_FALSE otherwise. * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
* *
* @see eina_tls_get() * @see eina_tls_get()
@ -466,113 +445,105 @@ static inline void *eina_tls_get(Eina_TLS key);
static inline Eina_Bool eina_tls_set(Eina_TLS key, const void *data); static inline Eina_Bool eina_tls_set(Eina_TLS key, const void *data);
/** /**
* @brief Initializes a new #Eina_Semaphore * @brief Initializes a new #Eina_Semaphore.
* @details This function initializes an unnamed #Eina_Semaphore with appropriate values.
* These values are platform dependent.
* *
* @param[in] sem The #Eina_Semaphore to be initialized. * @param[in] sem The #Eina_Semaphore to be initialized.
* @param[in] count_init Indicates the initial count of threads waiting on this semaphore. * @param[in] count_init Indicates the initial count of threads waiting on this semaphore.
* *
* @return #EINA_TRUE on success, #EINA_FALSE otherwise. * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
* *
* @details This function initializes an unnamed #Eina_Semaphore with appropriate values.
* These values are platform dependent.
*
* @see eina_semaphore_free() * @see eina_semaphore_free()
*/ */
static inline Eina_Bool eina_semaphore_new(Eina_Semaphore *sem, int count_init); static inline Eina_Bool eina_semaphore_new(Eina_Semaphore *sem, int count_init);
/** /**
* @brief Frees an allocated #Eina_Semaphore. * @brief Frees an allocated #Eina_Semaphore.
* @details This function frees the #Eina_Semaphore @p sem. The implementation
* is platform dependent.
* *
* @param[in] sem The #Eina_Semaphore to be freed. * @param[in] sem The #Eina_Semaphore to be freed.
* *
* @return #EINA_TRUE on success, #EINA_FALSE otherwise. * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
* *
* @details This function frees the #Eina_Semaphore @p sem. The implementation
* is platform dependent.
*
* @see eina_semaphore_new() * @see eina_semaphore_new()
*/ */
static inline Eina_Bool eina_semaphore_free(Eina_Semaphore *sem); static inline Eina_Bool eina_semaphore_free(Eina_Semaphore *sem);
/** /**
* @brief Gets a lock on an #Eina_Semaphore. * @brief Gets a lock on an #Eina_Semaphore.
* @details This function locks the #Eina_Semaphore @p sem. The implementation
* is platform dependent.
* *
* @param[in] sem The #Eina_Semaphore to lock. * @param[in] sem The #Eina_Semaphore to lock.
* *
* @return #EINA_TRUE on success, #EINA_FALSE otherwise. * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
* *
* @details This function locks the #Eina_Semaphore @p sem. The implementation
* is platform dependent.
*
* @see eina_semaphore_release() * @see eina_semaphore_release()
*/ */
static inline Eina_Bool eina_semaphore_lock(Eina_Semaphore *sem); static inline Eina_Bool eina_semaphore_lock(Eina_Semaphore *sem);
/** /**
* @brief Releases a lock on an #Eina_Semaphore. * @brief Releases a lock on an #Eina_Semaphore.
* @details This function releases a lock on the #Eina_Semaphore @p sem. The implementation
* is platform dependent.
* *
* @param[in] sem The #Eina_Semaphore to release. * @param[in] sem The #Eina_Semaphore to release.
* @param[in] count_release Not used. * @param[in] count_release Not used.
* *
* @return #EINA_TRUE on success, #EINA_FALSE otherwise. * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
* *
* @details This function releases a lock on the #Eina_Semaphore @p sem. The implementation
* is platform dependent.
*
* @see eina_semaphore_lock() * @see eina_semaphore_lock()
*/ */
static inline Eina_Bool eina_semaphore_release(Eina_Semaphore *sem, int count_release); static inline Eina_Bool eina_semaphore_release(Eina_Semaphore *sem, int count_release);
/** /**
* @brief Initializes a new #Eina_Barrier * @brief Initializes a new #Eina_Barrier.
* @details This function initializes a new #Eina_Barrier. It sets the @c needed flag
* to the value of @p needed, sets the barrier's @c count member to 0 and
* creates new #Eina_Lock and #Eina_Condition objects for the barrier.
* *
* @param[in] barrier The #Eina_Barrier to be initialized. * @param[in] barrier The #Eina_Barrier to be initialized.
* @param[in] needed The number of thread waits that causes this barrier to be reset. * @param[in] needed The number of thread waits that causes this barrier to be reset.
* *
* @return #EINA_TRUE on success, #EINA_FALSE otherwise. * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
* *
* @details This function initializes a new #Eina_Barrier. It sets the @c needed flag
* to the value of @p needed, sets the barrier's @c count member to 0 and
* creates new #Eina_Lock and #Eina_Condition objects for the barrier.
*
* @see eina_barrier_free() * @see eina_barrier_free()
*/ */
static inline Eina_Bool eina_barrier_new(Eina_Barrier *barrier, int needed); static inline Eina_Bool eina_barrier_new(Eina_Barrier *barrier, int needed);
/** /**
* @brief Frees an allocated #Eina_Barrier. * @brief Frees an allocated #Eina_Barrier.
* @details This function frees the #Eina_Barrier @p barrier.
* *
* @param[in] barrier The #Eina_Barrier to be freed. * @param[in] barrier The #Eina_Barrier to be freed.
* *
* @details This function frees the #Eina_Barrier @p barrier.
*
* @see eina_barrier_new() * @see eina_barrier_new()
*/ */
static inline void eina_barrier_free(Eina_Barrier *barrier); static inline void eina_barrier_free(Eina_Barrier *barrier);
/** /**
* @brief Increments the count of threads that are waiting on @p barrier. * @brief Increments the count of threads that are waiting on @p barrier.
* * @details When the count of threads reaches the @c needed value for the barrier, all
* waiting threads are notified via eina_condition_broadcast().
* @param[in] barrier The #Eina_Barrier to be incremented. * @param[in] barrier The #Eina_Barrier to be incremented.
* *
* @return #EINA_TRUE on success, else #EINA_FALSE otherwise. * @return #EINA_TRUE on success, else #EINA_FALSE otherwise.
* *
* @details When the count of threads reaches the @c needed value for the barrier, all
* waiting threads are notified via eina_condition_broadcast().
*/ */
static inline Eina_Bool eina_barrier_wait(Eina_Barrier *barrier); static inline Eina_Bool eina_barrier_wait(Eina_Barrier *barrier);
/** /**
* @brief Initializes a new #Eina_Spinlock * @brief Initializes a new #Eina_Spinlock.
* @details This function initializes a new #Eina_Spinlock, if spinlocks are available. If
* spinlocks are not available, it creates a new #Eina_Lock.
* *
* @param[in] spinlock The #Eina_Spinlock to be initialized. * @param[in] spinlock The #Eina_Spinlock to be initialized.
* *
* @return #EINA_TRUE on success, #EINA_FALSE otherwise. * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
* *
* @details This function initializes a new #Eina_Spinlock, if spinlocks are available. If
* spinlocks are not avialable, it creates a new #Eina_Lock.
*
* @note Spinlocks are only implemented on the POSIX platform and are only available * @note Spinlocks are only implemented on the POSIX platform and are only available
* if #EINA_HAVE_POSIX_SPINLOCK is defined. you get a new #Eina_Lock on All other platforms. * if #EINA_HAVE_POSIX_SPINLOCK is defined. you get a new #Eina_Lock on All other platforms.
* *
@ -582,6 +553,10 @@ static inline Eina_Bool eina_spinlock_new(Eina_Spinlock *spinlock);
/** /**
* @brief Attempts to take a spinlock. * @brief Attempts to take a spinlock.
* @details This function attempts to gain a lock on the indicated #Eina_Spinlock. If the
* underlying #Eina_Spinlock is locked already, this call can be blocked until
* the lock is released. This is appropriate in many cases, but consider using
* eina_spinlock_take_try() if you don't need to block.
* *
* @param[in] spinlock The #Eina_Spinlock to take. * @param[in] spinlock The #Eina_Spinlock to take.
* *
@ -589,11 +564,6 @@ static inline Eina_Bool eina_spinlock_new(Eina_Spinlock *spinlock);
* a deadlock condition exists, it returns #EINA_LOCK_DEADLOCK. If some other * a deadlock condition exists, it returns #EINA_LOCK_DEADLOCK. If some other
* condition causes the take to fail, #EINA_LOCK_FAIL is returned. * condition causes the take to fail, #EINA_LOCK_FAIL is returned.
* *
* @details This function attempts to gain a lock on the indicated #Eina_Spinlock. If the
* underlying #Eina_Spinlock is locked already, this call can be blocked until
* the lock is released. This is appropriate in many cases, but consider using
* eina_spinlock_take_try() if you don't need to block.
*
* @see eina_spinlock_take_try() * @see eina_spinlock_take_try()
* @see eina_spinlock_release() * @see eina_spinlock_release()
*/ */
@ -601,6 +571,8 @@ static inline Eina_Lock_Result eina_spinlock_take(Eina_Spinlock *spinlock);
/** /**
* @brief Attempts to take a spinlock if possible. * @brief Attempts to take a spinlock if possible.
* @details This function attempts to gain a lock on the indicated #Eina_Spinlock. Identical
* to eina_lock_take(), but returns immediately if the lock is already taken.
* *
* @param[in] spinlock The #Eina_Spinlock to take. * @param[in] spinlock The #Eina_Spinlock to take.
* *
@ -608,9 +580,6 @@ static inline Eina_Lock_Result eina_spinlock_take(Eina_Spinlock *spinlock);
* a deadlock condition exists, it returns #EINA_LOCK_DEADLOCK. If some other * a deadlock condition exists, it returns #EINA_LOCK_DEADLOCK. If some other
* condition causes the take to fail, #EINA_LOCK_FAIL is returned. * condition causes the take to fail, #EINA_LOCK_FAIL is returned.
* *
* @details This function attempts to gain a lock on the indicated #Eina_Spinlock. Identical
* to eina_lock_take(), but returns immediately if the lock is already taken.
*
* @see eina_spinlock_take_try() * @see eina_spinlock_take_try()
* @see eina_spinlock_release() * @see eina_spinlock_release()
*/ */
@ -618,15 +587,14 @@ static inline Eina_Lock_Result eina_spinlock_take_try(Eina_Spinlock *spinlock);
/** /**
* @brief Releases a spinlock. * @brief Releases a spinlock.
* @details This function will release the lock on the indicated #Eina_Spinlock. If successful,
* and @c EINA_HAVE_DEBUG_THREADS is defined, @p mutex is updated and information
* about the locking process is removed (e.g. thread number and backtrace for POSIX).
* *
* @param[in] spinlock The #Eina_Spinlock to release. * @param[in] spinlock The #Eina_Spinlock to release.
* *
* @return Returns #EINA_LOCK_SUCCEED on success, #EINA_LOCK_FAIL otherwise. * @return Returns #EINA_LOCK_SUCCEED on success, #EINA_LOCK_FAIL otherwise.
* *
* @details This function will release the lock on the indicated #Eina_Spinlock. If successful,
* and @c EINA_HAVE_DEBUG_THREADS is defined, @p mutex is updated and information
* about the locking process is removed (e.g. thread number and backtrace for POSIX).
*
* @see eina_spinlock_take() * @see eina_spinlock_take()
* @see eina_spinlock_take_try() * @see eina_spinlock_take_try()
@ -634,12 +602,12 @@ static inline Eina_Lock_Result eina_spinlock_take_try(Eina_Spinlock *spinlock);
static inline Eina_Lock_Result eina_spinlock_release(Eina_Spinlock *spinlock); static inline Eina_Lock_Result eina_spinlock_release(Eina_Spinlock *spinlock);
/** /**
* @brief Deallocates an #Eina_Spinlock * @brief Deallocates an #Eina_Spinlock.
* @details This function deallocates an #Eina_Spinlock and does any platform dependent
* cleanup that is required.
* *
* @param[in] spinlock The #Eina_Spinlock to be deallocated. * @param[in] spinlock The #Eina_Spinlock to be deallocated.
* *
* @details This function deallocates an #Eina_Spinlock and does any platform dependent
* cleanup that is required.
*/ */
static inline void eina_spinlock_free(Eina_Spinlock *spinlock); static inline void eina_spinlock_free(Eina_Spinlock *spinlock);
@ -671,13 +639,13 @@ static inline void eina_spinlock_free(Eina_Spinlock *spinlock);
#else #else
/** /**
* @def EINA_MAIN_LOOP_CHECK_RETURN_VAL * @def EINA_MAIN_LOOP_CHECK_RETURN_VAL
* @brief The macro doesn't do anything unless @c EINA_HAVE_DEBUG_THREADS is defined. * @brief Definition for the macro that doesn't do anything unless @c EINA_HAVE_DEBUG_THREADS is defined.
* @param[in] val The value to be returned * @param[in] val The value to be returned
*/ */
# define EINA_MAIN_LOOP_CHECK_RETURN_VAL(val) # define EINA_MAIN_LOOP_CHECK_RETURN_VAL(val)
/** /**
* @def EINA_MAIN_LOOP_CHECK_RETURN * @def EINA_MAIN_LOOP_CHECK_RETURN
* @brief The macro doesn't do anything unless @c EINA_HAVE_DEBUG_THREADS is defined. * @brief Definition for the macro that doesn't do anything unless @c EINA_HAVE_DEBUG_THREADS is defined.
*/ */
# define EINA_MAIN_LOOP_CHECK_RETURN # define EINA_MAIN_LOOP_CHECK_RETURN
#endif #endif

156
src/lib/eina/eina_log.h
View File

@ -289,7 +289,7 @@ EAPI extern int EINA_LOG_DOMAIN_GLOBAL;
* @def EINA_LOG(DOM, LEVEL, fmt, ...) * @def EINA_LOG(DOM, LEVEL, fmt, ...)
* Logs a message on the specified domain, level and format. * Logs a message on the specified domain, level and format.
* *
* @note if @c EINA_LOG_LEVEL_MAXIMUM is defined, then messages larger * @note If @c EINA_LOG_LEVEL_MAXIMUM is defined, then messages larger
* than this value will be ignored regardless of current domain * than this value will be ignored regardless of current domain
* level, the eina_log_print() is not even called! Most * level, the eina_log_print() is not even called! Most
* compilers will just detect the two integers make the branch * compilers will just detect the two integers make the branch
@ -498,9 +498,9 @@ typedef enum _Eina_Log_State
* *
* By default, eina_log_print_cb_stderr() is used. * By default, eina_log_print_cb_stderr() is used.
* *
* @note MT: safe to call from any thread. * @note MT: Safe to call from any thread.
* *
* @note MT: given function @a cb will be called protected by mutex. * @note MT: Given function @a cb will be called protected by mutex.
* This means you're safe from other calls but you should never * This means you're safe from other calls but you should never
* call eina_log_print(), directly or indirectly. * call eina_log_print(), directly or indirectly.
*/ */
@ -508,7 +508,7 @@ EAPI void eina_log_print_cb_set(Eina_Log_Print_Cb cb, void *data) EINA_ARG_NONNU
/** /**
* @brief Set the default log level. * @brief Sets the default log level.
* *
* @param level The log level. * @param level The log level.
* *
@ -522,16 +522,16 @@ EAPI void eina_log_print_cb_set(Eina_Log_Print_Cb cb, void *data) EINA_ARG_NONNU
EAPI void eina_log_level_set(int level); EAPI void eina_log_level_set(int level);
/** /**
* @brief Get the default log level. * @brief Gets the default log level.
* *
* @return the log level that limits eina_log_print(). * @return The log level that limits eina_log_print().
* *
* @see eina_log_level_set() * @see eina_log_level_set()
*/ */
EAPI int eina_log_level_get(void) EINA_WARN_UNUSED_RESULT; EAPI int eina_log_level_get(void) EINA_WARN_UNUSED_RESULT;
/** /**
* @brief Determine if a given @p level should be logged. * @brief Determines if a given @p level should be logged.
* *
* @return #EINA_TRUE if the @p level should be logged, else #EINA_FALSE. * @return #EINA_TRUE if the @p level should be logged, else #EINA_FALSE.
* *
@ -546,7 +546,7 @@ static inline Eina_Bool eina_log_level_check(int level);
* threads were not enabled, then #EINA_TRUE is returned. The only case where * 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 * #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 * current thread is not the one that called eina_log_threads_init() (the
* manin thread). * main thread).
* *
* @return #EINA_TRUE if the current thread is the one that called * @return #EINA_TRUE if the current thread is the one that called
* eina_log_threads_init(), otherwise #EINA_FALSE. * eina_log_threads_init(), otherwise #EINA_FALSE.
@ -555,7 +555,7 @@ EAPI Eina_Bool eina_log_main_thread_check(void) EINA_CONST EINA_WARN_UN
/** /**
* @brief Enable or disable colored text in the logs. * @brief Enables or disables colored text in the logs.
* *
* @param disabled If #EINA_TRUE, color logging should be disabled. * @param disabled If #EINA_TRUE, color logging should be disabled.
* *
@ -566,7 +566,7 @@ EAPI Eina_Bool eina_log_main_thread_check(void) EINA_CONST EINA_WARN_UN
EAPI void eina_log_color_disable_set(Eina_Bool disabled); EAPI void eina_log_color_disable_set(Eina_Bool disabled);
/** /**
* @brief Determine if color logging is enabled or disabled. * @brief Determines if color logging is enabled or disabled.
* *
* @return If #EINA_TRUE, color logging is disabled. * @return If #EINA_TRUE, color logging is disabled.
* *
@ -575,9 +575,9 @@ EAPI void eina_log_color_disable_set(Eina_Bool disabled);
EAPI Eina_Bool eina_log_color_disable_get(void) EINA_WARN_UNUSED_RESULT; 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 if originating file name logging should be disabled.
* *
* @param disabled if #EINA_TRUE, file name logging should be disabled. * @param disabled If #EINA_TRUE, file name logging should be disabled.
* *
* @note this is initially set to envvar EINA_LOG_FILE_DISABLE by eina_init(). * @note this is initially set to envvar EINA_LOG_FILE_DISABLE by eina_init().
* *
@ -586,18 +586,18 @@ EAPI Eina_Bool eina_log_color_disable_get(void) EINA_WARN_UNUSED_RESULT
EAPI void eina_log_file_disable_set(Eina_Bool disabled); EAPI void eina_log_file_disable_set(Eina_Bool disabled);
/** /**
* @brief Get if originating file name logging should be disabled. * @brief Gets if originating file name logging should be disabled.
* *
* @return if #EINA_TRUE, file name logging should be disabled. * @return If #EINA_TRUE, file name logging should be disabled.
* *
* @see eina_log_file_disable_set() * @see eina_log_file_disable_set()
*/ */
EAPI Eina_Bool eina_log_file_disable_get(void) EINA_WARN_UNUSED_RESULT; 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 if originating function name logging should be disabled.
* *
* @param disabled if #EINA_TRUE, function name logging should be disabled. * @param disabled If #EINA_TRUE, function name logging should be disabled.
* *
* @note this is initially set to envvar EINA_LOG_FUNCTION_DISABLE by * @note this is initially set to envvar EINA_LOG_FUNCTION_DISABLE by
* eina_init(). * eina_init().
@ -607,18 +607,18 @@ EAPI Eina_Bool eina_log_file_disable_get(void) EINA_WARN_UNUSED_RESULT;
EAPI void eina_log_function_disable_set(Eina_Bool disabled); EAPI void eina_log_function_disable_set(Eina_Bool disabled);
/** /**
* @brief Get if originating function name logging should be disabled. * @brief Gets if originating function name logging should be disabled.
* *
* @return if #EINA_TRUE, function name logging should be disabled. * @return If #EINA_TRUE, function name logging should be disabled.
* *
* @see eina_log_function_disable_set() * @see eina_log_function_disable_set()
*/ */
EAPI Eina_Bool eina_log_function_disable_get(void) EINA_WARN_UNUSED_RESULT; EAPI Eina_Bool eina_log_function_disable_get(void) EINA_WARN_UNUSED_RESULT;
/** /**
* @brief Set if critical messages should abort the program. * @brief Sets if critical messages should abort the program.
* *
* @param abort_on_critical if #EINA_TRUE, messages with level equal * @param abort_on_critical If #EINA_TRUE, messages with level equal
* or smaller than eina_log_abort_on_critical_level_get() will * or smaller than eina_log_abort_on_critical_level_get() will
* abort the program. * abort the program.
* *
@ -631,9 +631,9 @@ 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); EAPI void eina_log_abort_on_critical_set(Eina_Bool abort_on_critical);
/** /**
* @brief Get if critical messages should abort the program. * @brief Gets if critical messages should abort the program.
* *
* @return if #EINA_TRUE, any messages with level equal or smaller * @return If #EINA_TRUE, any messages with level equal or smaller
* than eina_log_abort_on_critical_level_get() will abort the * than eina_log_abort_on_critical_level_get() will abort the
* program. * program.
* *
@ -643,9 +643,9 @@ 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; 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 level that triggers abort if abort-on-critical is set.
* *
* @param critical_level levels equal or smaller than the given value * @param critical_level Levels equal or smaller than the given value
* will trigger program abortion if * will trigger program abortion if
* eina_log_abort_on_critical_get() returns #EINA_TRUE. * eina_log_abort_on_critical_get() returns #EINA_TRUE.
* *
@ -658,9 +658,9 @@ 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); 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 level that triggers abort if abort-on-critical is set.
* *
* @return critical level equal or smaller than value will trigger * @return Critical level equal or smaller than value will trigger
* program abortion if eina_log_abort_on_critical_get() * program abortion if eina_log_abort_on_critical_get()
* returns #EINA_TRUE. * returns #EINA_TRUE.
* *
@ -671,23 +671,23 @@ 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 its name.
* *
* This call has the same effect as setting * This call has the same effect as setting
* EINA_LOG_LEVELS=&lt;@p domain_name&gt;:&lt;@p level&gt; * EINA_LOG_LEVELS=&lt;@p domain_name&gt;:&lt;@p level&gt;
* *
* @param domain_name domain name to change the level. It may be of a * @param domain_name Domain name to change the level. It may be of a
* still not registered domain. If the domain is not registered * still not registered domain. If the domain is not registered
* yet, it will be saved as a pending set and applied upon * yet, it will be saved as a pending set and applied upon
* registration. * registration.
* @param level level to use to limit eina_log_print() for given domain. * @param level Level to use to limit eina_log_print() for given domain.
*/ */
EAPI void eina_log_domain_level_set(const char *domain_name, int level) EINA_ARG_NONNULL(1); 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 its name.
* *
* @param domain_name domain name to retrieve the level. It may be of * @param domain_name Domain name to retrieve the level. It may be of
* a still not registered domain. If the domain is not * a still not registered domain. If the domain is not
* registered yet, but there is a pending value, either from * registered yet, but there is a pending value, either from
* eina_log_domain_level_set(),EINA_LOG_LEVELS environment * eina_log_domain_level_set(),EINA_LOG_LEVELS environment
@ -695,7 +695,7 @@ EAPI void eina_log_domain_level_set(const char *domain_name, int l
* returned. If nothing else was found, then the global/default * returned. If nothing else was found, then the global/default
* level (eina_log_level_get()) is returned. * level (eina_log_level_get()) is returned.
* *
* @return level to use to limit eina_log_print() for given * @return Level to use to limit eina_log_print() for given
* domain. On error (@p domain_name == NULL), * domain. On error (@p domain_name == NULL),
* EINA_LOG_LEVEL_UNKNOWN is returned. * EINA_LOG_LEVEL_UNKNOWN is returned.
* *
@ -705,9 +705,9 @@ 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); 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 its identifier.
* *
* @param domain identifier, so it must be previously registered with * @param domain Identifier, so it must be previously registered with
* eina_log_domain_register(). It's a much faster version of * eina_log_domain_register(). It's a much faster version of
* eina_log_domain_level_get(), but relies on domain being * eina_log_domain_level_get(), but relies on domain being
* present. * present.
@ -718,13 +718,13 @@ EAPI int eina_log_domain_level_get(const char *domain_name) EINA_
EAPI int eina_log_domain_registered_level_get(int domain) EINA_WARN_UNUSED_RESULT; EAPI int eina_log_domain_registered_level_get(int domain) EINA_WARN_UNUSED_RESULT;
/** /**
* Set the domain level given its identifier. * @brief Sets the domain level given its identifier.
* *
* @param domain identifier, so it must be previously registered with * @param domain Identifier, so it must be previously registered with
* eina_log_domain_register(). It's a much faster version of * eina_log_domain_register(). It's a much faster version of
* eina_log_domain_level_get(), but relies on domain being * eina_log_domain_level_get(), but relies on domain being
* present. * present.
* @param level level to use to limit eina_log_print() for given domain. * @param level Level to use to limit eina_log_print() for given domain.
* @since 1.10 * @since 1.10
*/ */
EAPI void eina_log_domain_registered_level_set(int domain, int level); EAPI void eina_log_domain_registered_level_set(int domain, int level);
@ -742,17 +742,17 @@ static inline Eina_Bool eina_log_domain_level_check(int domain, int level);
* @return Domain index that will be used as the DOMAIN parameter on log * @return Domain index that will be used as the DOMAIN parameter on log
* macros. A negative return value means an log occurred. * macros. A negative return value means an log occurred.
* *
* @note MT: safe to call from any thread. * @note MT: Safe to call from any thread.
*/ */
EAPI int eina_log_domain_register(const char *name, const char *color) EINA_ARG_NONNULL(1); 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()
* *
* @param domain domain identifier as reported by eina_log_domain_register(), * @param domain Domain identifier as reported by eina_log_domain_register(),
* must be >= 0. * must be >= 0.
* *
* @note MT: safe to call from any thread. * @note MT: Safe to call from any thread.
*/ */
EAPI void eina_log_domain_unregister(int domain); EAPI void eina_log_domain_unregister(int domain);
@ -761,26 +761,26 @@ EAPI void eina_log_domain_unregister(int domain);
*/ */
/** /**
* Print out log message using given domain and level. * @brief Prints out log message using given domain and level.
* *
* @note Usually you'll not use this function directly but the helper * @note Usually you'll not use this function directly but the helper
* macros EINA_LOG(), EINA_LOG_DOM_CRIT(), EINA_LOG_CRIT() and * macros EINA_LOG(), EINA_LOG_DOM_CRIT(), EINA_LOG_CRIT() and
* so on. See eina_log.h * so on. See eina_log.h
* *
* @param domain logging domain to use or @c EINA_LOG_DOMAIN_GLOBAL if * @param domain Logging domain to use or @c EINA_LOG_DOMAIN_GLOBAL if
* you registered none. It is recommended that modules and * you registered none. It is recommended that modules and
* applications have their own logging domain. * applications have their own logging domain.
* @param level message level, those with level greater than user * @param level Message level, those with level greater than user
* specified value (eina_log_level_set() or environment * specified value (eina_log_level_set() or environment
* variables EINA_LOG_LEVEL, EINA_LOG_LEVELS) will be ignored. * variables EINA_LOG_LEVEL, EINA_LOG_LEVELS) will be ignored.
* @param file filename that originated the call, must @b not be @c NULL. * @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 function Function that originated the call, must @b not be @c NULL.
* @param line originating line in @a file. * @param line Originating line in @a file.
* @param fmt printf-like format to use. Should not provide trailing * @param fmt Printf-like format to use. Should not provide trailing
* '\n' as it is automatically included. * '\n' as it is automatically included.
* @param ... variadic args. * @param ... Variadic args.
* *
* @note MT: this function may be called from different threads if * @note MT: This function may be called from different threads if
* eina_log_threads_enable() was called before. * eina_log_threads_enable() was called before.
*/ */
EAPI void eina_log_print(int domain, EAPI void eina_log_print(int domain,
@ -792,24 +792,24 @@ EAPI void eina_log_print(int domain,
...) EINA_ARG_NONNULL(3, 4, 6) EINA_PRINTF(6, 7) EINA_NOINSTRUMENT; ...) 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 message using given domain and level.
* *
* @note Usually you'll not use this function directly but the helper * @note Usually you'll not use this function directly but the helper
* macros EINA_LOG(), EINA_LOG_DOM_CRIT(), EINA_LOG_CRIT() and * macros EINA_LOG(), EINA_LOG_DOM_CRIT(), EINA_LOG_CRIT() and
* so on. See eina_log.h * so on. See eina_log.h
* *
* @param domain logging domain to use or @c EINA_LOG_DOMAIN_GLOBAL if * @param domain Logging domain to use or @c EINA_LOG_DOMAIN_GLOBAL if
* you registered none. It is recommended that modules and * you registered none. It is recommended that modules and
* applications have their own logging domain. * applications have their own logging domain.
* @param level message level, those with level greater than user * @param level Message level, those with level greater than user
* specified value (eina_log_level_set() or environment * specified value (eina_log_level_set() or environment
* variables EINA_LOG_LEVEL, EINA_LOG_LEVELS) will be ignored. * variables EINA_LOG_LEVEL, EINA_LOG_LEVELS) will be ignored.
* @param file filename that originated the call, must @b not be @c NULL. * @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 fnc Function that originated the call, must @b not be @c NULL.
* @param line originating line in @a file. * @param line Originating line in @a file.
* @param fmt printf-like format to use. Should not provide trailing * @param fmt Printf-like format to use. Should not provide trailing
* '\n' as it is automatically included. * '\n' as it is automatically included.
* @param args the arguments needed by the format. * @param args The arguments needed by the format.
* *
* @note MT: this function may be called from different threads if * @note MT: this function may be called from different threads if
* eina_log_threads_enable() was called before. * eina_log_threads_enable() was called before.
@ -850,7 +850,7 @@ EAPI void eina_log_vprint(int domain,
* EINA_LOG_FUNCTION_DISABLE will be considered and file information * EINA_LOG_FUNCTION_DISABLE will be considered and file information
* will be printed anyways. * will be printed anyways.
* *
* @note MT: if threads are enabled, this function is called within locks. * @note MT: If threads are enabled, this function is called within locks.
* @note MT: Threads different from main thread will have thread id * @note MT: Threads different from main thread will have thread id
* appended to domain name. * appended to domain name.
*/ */
@ -893,7 +893,7 @@ EAPI void eina_log_print_cb_stdout(const Eina_Log_Domain *d,
* EINA_LOG_FUNCTION_DISABLE will be considered and file information * EINA_LOG_FUNCTION_DISABLE will be considered and file information
* will be printed anyways. * will be printed anyways.
* *
* @note MT: if threads are enabled, this function is called within locks. * @note MT: If threads are enabled, this function is called within locks.
* @note MT: Threads different from main thread will have thread id * @note MT: Threads different from main thread will have thread id
* appended to domain name. * appended to domain name.
*/ */
@ -907,7 +907,7 @@ EAPI void eina_log_print_cb_stderr(const Eina_Log_Domain *d,
va_list args) EINA_ARG_NONNULL(1); va_list args) EINA_ARG_NONNULL(1);
/** /**
* Alternative logging method, this will output to given file stream. * @brief Alternative logging method, this will output to given file stream.
* *
* @param d The domain. * @param d The domain.
* @param level Not used. * @param level Not used.
@ -920,7 +920,7 @@ EAPI void eina_log_print_cb_stderr(const Eina_Log_Domain *d,
* *
* This method will never output color. * This method will never output color.
* *
* @note MT: if threads are enabled, this function is called within locks. * @note MT: If threads are enabled, this function is called within locks.
* @note MT: Threads different from main thread will have thread id * @note MT: Threads different from main thread will have thread id
* appended to domain name. * appended to domain name.
*/ */
@ -935,7 +935,7 @@ EAPI void eina_log_print_cb_file(const Eina_Log_Domain *d,
/** /**
* Alternative logging method, this will output to systemd journal. * @brief Alternative logging method, this will output to systemd journal.
* *
* @param d The domain. * @param d The domain.
* @param level Not used. * @param level Not used.
@ -948,8 +948,8 @@ EAPI void eina_log_print_cb_file(const Eina_Log_Domain *d,
* *
* This method will never output color. * This method will never output color.
* *
* @note if systemd journal is not there it will display error on stderr. * @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. * @note If the process has been started by systemd this will be the default logging method.
* *
* @since 1.8 * @since 1.8
*/ */
@ -963,35 +963,37 @@ EAPI void eina_log_print_cb_journald(const Eina_Log_Domain *d,
va_list args) EINA_ARG_NONNULL(1); va_list args) EINA_ARG_NONNULL(1);
/** /**
* Configure console color of given file. * @brief Configures console color of given file.
* *
* @param fp file to configure console color (usually stderr or stdout). * @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. * @param color A VT color code such as EINA_COLOR_RED or EINA_COLOR_RESET.
* *
* @note if color is disabled, nothing is done. See * @note If color is disabled, nothing is done. See
* eina_log_color_disable_get() * eina_log_color_disable_get()
* @note on windows, both @a fp and @a color is converted automatically. * @note On windows, both @a fp and @a color is converted automatically.
* *
* @since 1.7 * @since 1.7
*/ */
EAPI void eina_log_console_color_set(FILE *fp, EAPI void eina_log_console_color_set(FILE *fp,
const char *color) EINA_ARG_NONNULL(1, 2); const char *color) EINA_ARG_NONNULL(1, 2);
/** String that indicates the log system is initializing */ /** String that indicates the log system is initializing. */
extern EAPI const char *_eina_log_state_init; extern EAPI const char *_eina_log_state_init;
/** String that indicates the log system is shutting down */ /** String that indicates the log system is shutting down. */
extern EAPI const char *_eina_log_state_shutdown; extern EAPI const char *_eina_log_state_shutdown;
/** @def EINA_LOG_STATE_INIT /**
*String that indicates the log system is initializing * @def EINA_LOG_STATE_INIT
* String that indicates the log system is initializing
*/ */
#define EINA_LOG_STATE_INIT _eina_log_state_init #define EINA_LOG_STATE_INIT _eina_log_state_init
/** @def EINA_LOG_STATE_SHUTDOWN /**
*String that indicates the log system is shutting down * @def EINA_LOG_STATE_SHUTDOWN
* String that indicates the log system is shutting down
*/ */
#define EINA_LOG_STATE_SHUTDOWN _eina_log_state_shutdown #define EINA_LOG_STATE_SHUTDOWN _eina_log_state_shutdown
/** /**
* @brief Start or stop the timing of a phase. * @brief Starts or stops the timing of a phase.
* *
* @param domain The domain. * @param domain The domain.
* @param state State indicating if we are starting or stopping a phase. * @param state State indicating if we are starting or stopping a phase.

40
src/lib/eina/eina_magic.h
View File

@ -134,14 +134,13 @@ typedef unsigned int Eina_Magic;
/** /**
* @brief Gets the string associated to the given magic identifier. * @brief Gets the string associated to the given magic identifier.
*
* @param[in] magic The magic identifier
* @return The string associated to the identifier
*
* @details This function returns the string associated to @p magic. Even if none are * @details This function returns the string associated to @p magic. Even if none are
* found this function still returns non @c NULL, in this case an identifier * found this function still returns non @c NULL, in this case an identifier
* such as "(none)", "(undefined)", or "(unknown)". * such as "(none)", "(undefined)", or "(unknown)".
* *
* @param[in] magic The magic identifier
* @return The string associated to the identifier
*
* @note The following identifiers may be returned whenever magic is * @note The following identifiers may be returned whenever magic is
* invalid, with their meanings: * invalid, with their meanings:
* *
@ -154,6 +153,9 @@ typedef unsigned int Eina_Magic;
EAPI const char *eina_magic_string_get(Eina_Magic magic) EINA_WARN_UNUSED_RESULT; EAPI const char *eina_magic_string_get(Eina_Magic magic) EINA_WARN_UNUSED_RESULT;
/** /**
* @brief Sets the string associated to the given magic identifier. * @brief Sets the string associated to the given magic identifier.
* @details This function sets the string @p magic_name to @p magic. It is not
* checked if number or string are already set, in which case you end with
* duplicates. Internally, eina makes a copy of @p magic_name.
* *
* @param[in] magic The magic identifier * @param[in] magic The magic identifier
* @param[in] magic_name The string associated to the identifier, must not * @param[in] magic_name The string associated to the identifier, must not
@ -161,10 +163,6 @@ EAPI const char *eina_magic_string_get(Eina_Magic magic) EINA_WARN_UNUSED_RESULT
* *
* @return #EINA_TRUE on success, otherwise #EINA_FALSE on failure * @return #EINA_TRUE on success, otherwise #EINA_FALSE on failure
* *
* @details This function sets the string @p magic_name to @p magic. It is not
* checked if number or string are already set, in which case you end with
* duplicates. Internally, eina makes a copy of @p magic_name.
*
* @see eina_magic_string_static_set() * @see eina_magic_string_static_set()
*/ */
EAPI Eina_Bool eina_magic_string_set(Eina_Magic magic, EAPI Eina_Bool eina_magic_string_set(Eina_Magic magic,
@ -172,6 +170,10 @@ EAPI Eina_Bool eina_magic_string_set(Eina_Magic magic,
/** /**
* @brief Sets the string associated to the given magic identifier. * @brief Sets the string associated to the given magic identifier.
* @details This function sets the string @p magic_name to @p magic. It is not checked if
* number or string are already set, in which case you might end with
* duplicates. Eina does @b not make a copy of @p magic_name, this means that
* @p magic_name has to be a valid pointer for as long as @p magic is used.
* *
* @param[in] magic The magic identifier * @param[in] magic The magic identifier
* @param[in] magic_name The string associated to the identifier, must not be * @param[in] magic_name The string associated to the identifier, must not be
@ -179,11 +181,6 @@ EAPI Eina_Bool eina_magic_string_set(Eina_Magic magic,
* *
* @return #EINA_TRUE on success, otherwise #EINA_FALSE on failure * @return #EINA_TRUE on success, otherwise #EINA_FALSE on failure
* *
* @details This function sets the string @p magic_name to @p magic. It is not checked if
* number or string are already set, in which case you might end with
* duplicates. Eina does @b not make a copy of @p magic_name, this means that
* @p magic_name has to be a valid pointer for as long as @p magic is used.
*
* @see eina_magic_string_set() * @see eina_magic_string_set()
*/ */
EAPI Eina_Bool eina_magic_string_static_set(Eina_Magic magic, EAPI Eina_Bool eina_magic_string_static_set(Eina_Magic magic,
@ -269,6 +266,14 @@ EAPI extern Eina_Error EINA_ERROR_MAGIC_FAILED;
/** /**
* @brief Displays a message or aborts if a magic check failed. * @brief Displays a message or aborts if a magic check failed.
* @details This function displays an error message if a magic check has
* failed, using the following logic in the following order:
* @li If @p d is @c NULL, a message warns about a @c NULL pointer.
* @li Otherwise, if @p m is equal to #EINA_MAGIC_NONE, a message
* warns about a handle that is already freed.
* @li Otherwise, if @p m is equal to @p req_m, a message warns about
* a handle that is of the wrong type.
* @li Otherwise, a message warns you about abusing that function...
* *
* @param[in] d The checked data pointer * @param[in] d The checked data pointer
* @param[in] m The magic identifier to check * @param[in] m The magic identifier to check
@ -280,15 +285,6 @@ EAPI extern Eina_Error EINA_ERROR_MAGIC_FAILED;
* @warning You should @b strongly consider using @ref EINA_MAGIC_FAIL(d, m) * @warning You should @b strongly consider using @ref EINA_MAGIC_FAIL(d, m)
* instead. * instead.
* *
* @details This function displays an error message if a magic check has
* failed, using the following logic in the following order:
* @li If @p d is @c NULL, a message warns about a @c NULL pointer.
* @li Otherwise, if @p m is equal to #EINA_MAGIC_NONE, a message
* warns about a handle that is already freed.
* @li Otherwise, if @p m is equal to @p req_m, a message warns about
* a handle that is of the wrong type.
* @li Otherwise, a message warns you about abusing that function...
*
* @note If the environment variable EINA_LOG_ABORT is set, abort() is * @note If the environment variable EINA_LOG_ABORT is set, abort() is
* called and the program stops. It is useful for debugging programs * called and the program stops. It is useful for debugging programs
* with gdb. * with gdb.

24
src/lib/eina/eina_main.h
View File

@ -44,13 +44,13 @@
/** /**
* @def EINA_VERSION_MAJOR * @def EINA_VERSION_MAJOR
* @brief Major version of Eina * @brief Definition for the major version of Eina.
*/ */
#define EINA_VERSION_MAJOR EFL_VERSION_MAJOR #define EINA_VERSION_MAJOR EFL_VERSION_MAJOR
/** /**
* @def EINA_VERSION_MINOR * @def EINA_VERSION_MINOR
* @brief Minor version of Eina * @brief Definition for the minor version of Eina.
*/ */
#define EINA_VERSION_MINOR EFL_VERSION_MINOR #define EINA_VERSION_MINOR EFL_VERSION_MINOR
@ -69,9 +69,9 @@ typedef struct _Eina_Version
EAPI extern Eina_Version *eina_version; EAPI extern Eina_Version *eina_version;
/** /**
* @brief Initialize the Eina library. * @brief Initializes the Eina library.
* *
* @return 1 or greater on success, 0 on error. * @return @c 1 or greater on success, @c 0 on error.
* *
* This function sets up all the eina modules. It returns 0 on * This function sets up all the eina modules. It returns 0 on
* failure (that is, when one of the module fails to initialize), * failure (that is, when one of the module fails to initialize),
@ -176,9 +176,9 @@ EAPI extern Eina_Version *eina_version;
EAPI int eina_init(void); EAPI int eina_init(void);
/** /**
* @brief Shut down the Eina library. * @brief Shuts down the Eina library.
* *
* @return 0 when all the modules are completely shut down, 1 or * @return @c 0 when all the modules are completely shut down, @c 1 or
* greater otherwise. * greater otherwise.
* *
* This function shuts down the Eina library. It returns 0 when it has * This function shuts down the Eina library. It returns 0 when it has
@ -192,9 +192,9 @@ EAPI int eina_init(void);
EAPI int eina_shutdown(void); 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. * @return @c 1 or greater on success, @c 0 on error.
* *
* This function sets up all the mutexes in all eina modules. It returns 0 on * 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), * failure (that is, when one of the module fails to initialize),
@ -209,9 +209,9 @@ EAPI int eina_shutdown(void);
EAPI int eina_threads_init(void); EAPI int eina_threads_init(void);
/** /**
* @brief Shut down mutexes in the Eina library. * @brief Shuts down mutexes in the Eina library.
* *
* @return 0 when all mutexes are completely shut down, 1 or * @return @c 0 when all mutexes are completely shut down, @c 1 or
* greater otherwise. * greater otherwise.
* *
* This function shuts down the mutexes in the Eina library. It returns 0 when it has * This function shuts down the mutexes in the Eina library. It returns 0 when it has
@ -227,7 +227,7 @@ EAPI int eina_threads_init(void);
EAPI int eina_threads_shutdown(void); EAPI int eina_threads_shutdown(void);
/** /**
* @brief Check if you are calling this function from the same thread Eina was initialized or not * @brief Checks 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. * @return #EINA_TRUE is the calling function is the same thread, #EINA_FALSE otherwise.
* *
@ -240,7 +240,7 @@ EAPI int eina_threads_shutdown(void);
EAPI Eina_Bool eina_main_loop_is(void); 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. * @brief You should never use that function except if you really really know what your are doing.
* @since 1.1.0 * @since 1.1.0
* *
* If you are reading this documentation, that certainly means you don't know what is the purpose of * If you are reading this documentation, that certainly means you don't know what is the purpose of

104
src/lib/eina/eina_matrix.h
View File

@ -54,7 +54,7 @@ typedef enum _Eina_Matrix_Type
/** /**
* @defgroup Eina_Matrix3_Group 3x3 Matrices in floating point * @defgroup Eina_Matrix3_Group 3x3 Matrices in floating point
* *
* @brief Matrix definition and operations * @brief Matrix definition and operations.
* *
* @{ * @{
*/ */
@ -91,7 +91,7 @@ struct _Eina_Matrix3
/** /**
* @defgroup Eina_Matrix4_Group 4x4 Matrices in floating point * @defgroup Eina_Matrix4_Group 4x4 Matrices in floating point
* *
* @brief Matrix definition and operations * @brief Matrix definition and operations.
* *
* @{ * @{
*/ */
@ -136,7 +136,7 @@ struct _Eina_Matrix4
/** /**
* @defgroup Eina_Matrix3_F16p16_Group 3x3 Matrices in fixed point * @defgroup Eina_Matrix3_F16p16_Group 3x3 Matrices in fixed point
* *
* @brief Fixed point matrix operations * @brief Fixed point matrix operations.
* @{ * @{
*/ */
@ -166,7 +166,7 @@ struct _Eina_Matrix3_F16p16
}; };
/** /**
* @brief Set the given fixed point matrix to the identity matrix. * @brief Sets the given fixed point matrix to the identity matrix.
* *
* @param m The fixed point matrix to set * @param m The fixed point matrix to set
* *
@ -185,7 +185,7 @@ EAPI void eina_matrix3_f16p16_compose(const Eina_Matrix3_F16p16 *m1,
Eina_Matrix3_F16p16 *dst); Eina_Matrix3_F16p16 *dst);
/** /**
* @brief Return the type of the given fixed point matrix. * @brief Returns the type of the given fixed point matrix.
* *
* @param m The fixed point matrix. * @param m The fixed point matrix.
* @return The type of the matrix. * @return The type of the matrix.
@ -217,7 +217,7 @@ EAPI Eina_Matrix_Type eina_matrix3_f16p16_type_get(const Eina_Matrix3_F16p16 *m)
/** /**
* @brief Return the type of the given floating point matrix. * @brief Returns the type of the given floating point matrix.
* *
* @param m The floating point matrix. * @param m The floating point matrix.
* @return The type of the matrix. * @return The type of the matrix.
@ -230,7 +230,7 @@ EAPI Eina_Matrix_Type eina_matrix3_f16p16_type_get(const Eina_Matrix3_F16p16 *m)
EAPI Eina_Matrix_Type eina_matrix3_type_get(const Eina_Matrix3 *m); EAPI Eina_Matrix_Type eina_matrix3_type_get(const Eina_Matrix3 *m);
/** /**
* @brief Set the values of the coefficients of the given floating * @brief Sets the values of the coefficients of the given floating
* point matrix. * point matrix.
* *
* @param m The floating point matrix. * @param m The floating point matrix.
@ -257,7 +257,7 @@ EAPI void eina_matrix3_values_set(Eina_Matrix3 *m,
double zx, double zy, double zz); double zx, double zy, double zz);
/** /**
* @brief Get the values of the coefficients of the given floating * @brief Gets the values of the coefficients of the given floating
* point matrix. * point matrix.
* *
* @param m The floating point matrix. * @param m The floating point matrix.
@ -284,7 +284,7 @@ EAPI void eina_matrix3_values_get(const Eina_Matrix3 *m,
double *zx, double *zy, double *zz); double *zx, double *zy, double *zz);
/** /**
* @brief Get the values of the coefficients of the given fixed * @brief Gets the values of the coefficients of the given fixed
* point matrix. * point matrix.
* *
* @param m The fixed point matrix. * @param m The fixed point matrix.
@ -311,7 +311,7 @@ EAPI void eina_matrix3_fixed_values_get(const Eina_Matrix3 *m,
Eina_F16p16 *zx, Eina_F16p16 *zy, Eina_F16p16 *zz); Eina_F16p16 *zx, Eina_F16p16 *zy, Eina_F16p16 *zz);
/** /**
* @brief Transform the given floating point matrix to the given fixed * @brief Transforms the given floating point matrix to the given fixed
* point matrix. * point matrix.
* *
* @param m The floating point matrix. * @param m The floating point matrix.
@ -327,11 +327,11 @@ EAPI void eina_matrix3_matrix3_f16p16_to(const Eina_Matrix3 *m,
Eina_Matrix3_F16p16 *fm); Eina_Matrix3_F16p16 *fm);
/** /**
* @brief Check whether the two given matrices are equal or not. * @brief Checks whether the two given matrices are equal or not.
* *
* @param m1 The first matrix. * @param m1 The first matrix.
* @param m2 The second matrix. * @param m2 The second matrix.
* @return EINA_TRUE if the two matrices are equal, 0 otherwise. * @return EINA_TRUE if the two matrices are equal, @c 0 otherwise.
* *
* This function return EINA_TRUE if thematrices @p m1 and @p m2 are * This function return EINA_TRUE if thematrices @p m1 and @p m2 are
* equal, EINA_FALSE otherwise. No check is done on the matrices. * equal, EINA_FALSE otherwise. No check is done on the matrices.
@ -348,7 +348,7 @@ EAPI void eina_matrix3_compose(const Eina_Matrix3 *m1,
Eina_Matrix3 *dst); Eina_Matrix3 *dst);
/** /**
* Set the matrix values for a translation * @brief Sets the matrix values for a translation.
* @param[in] m The matrix to set the translation values * @param[in] m The matrix to set the translation values
* @param[in] tx The X coordinate translate * @param[in] tx The X coordinate translate
* @param[in] ty The Y coordinate translate * @param[in] ty The Y coordinate translate
@ -358,7 +358,7 @@ EAPI void eina_matrix3_compose(const Eina_Matrix3 *m1,
EAPI void eina_matrix3_translate(Eina_Matrix3 *t, double tx, double ty); EAPI void eina_matrix3_translate(Eina_Matrix3 *t, double tx, double ty);
/** /**
* Set the matrix values for a scale * @brief Sets the matrix values for a scale.
* @param[in] m The matrix to set the scale values * @param[in] m The matrix to set the scale values
* @param[in] sx The X coordinate scale * @param[in] sx The X coordinate scale
* @param[in] sy The Y coordinate scale * @param[in] sy The Y coordinate scale
@ -368,7 +368,7 @@ EAPI void eina_matrix3_translate(Eina_Matrix3 *t, double tx, double ty);
EAPI void eina_matrix3_scale(Eina_Matrix3 *t, double sx, double sy); EAPI void eina_matrix3_scale(Eina_Matrix3 *t, double sx, double sy);
/** /**
* Set the matrix values for a rotation * @brief Sets the matrix values for a rotation.
* @param[in] t The matrix to set the rotation values * @param[in] t The matrix to set the rotation values
* @param[in] rad The radius to rotate the matrix * @param[in] rad The radius to rotate the matrix
* *
@ -377,7 +377,7 @@ EAPI void eina_matrix3_scale(Eina_Matrix3 *t, double sx, double sy);
EAPI void eina_matrix3_rotate(Eina_Matrix3 *t, double rad); EAPI void eina_matrix3_rotate(Eina_Matrix3 *t, double rad);
/** /**
* @brief Set the given floating point matrix to the identity matrix. * @brief Sets the given floating point matrix to the identity matrix.
* *
* @param m The floating point matrix to set * @param m The floating point matrix to set
* *
@ -389,7 +389,7 @@ EAPI void eina_matrix3_rotate(Eina_Matrix3 *t, double rad);
EAPI void eina_matrix3_identity(Eina_Matrix3 *t); EAPI void eina_matrix3_identity(Eina_Matrix3 *t);
/** /**
* @brief Return the determinant of the given matrix. * @brief Returns the determinant of the given matrix.
* *
* @param m The matrix. * @param m The matrix.
* @return The determinant. * @return The determinant.
@ -402,7 +402,7 @@ EAPI void eina_matrix3_identity(Eina_Matrix3 *t);
EAPI double eina_matrix3_determinant(const Eina_Matrix3 *m); EAPI double eina_matrix3_determinant(const Eina_Matrix3 *m);
/** /**
* @brief Divide the given matrix by the given scalar. * @brief Divides the given matrix by the given scalar.
* *
* @param m The matrix. * @param m The matrix.
* @param scalar The scalar number. * @param scalar The scalar number.
@ -415,7 +415,7 @@ EAPI double eina_matrix3_determinant(const Eina_Matrix3 *m);
EAPI void eina_matrix3_divide(Eina_Matrix3 *m, double scalar); EAPI void eina_matrix3_divide(Eina_Matrix3 *m, double scalar);
/** /**
* @brief Compute the inverse of the given matrix. * @brief Computes the inverse of the given matrix.
* *
* @param m The matrix to inverse. * @param m The matrix to inverse.
* @param m2 The inverse matrix. * @param m2 The inverse matrix.
@ -457,7 +457,7 @@ EAPI void eina_matrix3_rectangle_transform(const Eina_Matrix3 *m,
const Eina_Quad *q); const Eina_Quad *q);
/** /**
* @brief Creates a projective matrix that maps a quadrangle to a quadrangle * @brief Creates a projective matrix that maps a quadrangle to a quadrangle.
*/ */
EAPI Eina_Bool eina_matrix3_quad_quad_map(Eina_Matrix3 *m, EAPI Eina_Bool eina_matrix3_quad_quad_map(Eina_Matrix3 *m,
const Eina_Quad *src, const Eina_Quad *src,
@ -476,7 +476,7 @@ EAPI Eina_Bool eina_matrix3_quad_square_map(Eina_Matrix3 *m,
const Eina_Quad *q); const Eina_Quad *q);
/** /**
* @brief Set array to matrix. * @brief Sets array to matrix.
* *
* @param m The result matrix * @param m The result matrix
* @param v The the array[9] for set * @param v The the array[9] for set
@ -488,7 +488,7 @@ EAPI Eina_Bool eina_matrix3_quad_square_map(Eina_Matrix3 *m,
EAPI void eina_matrix3_array_set(Eina_Matrix3 *m, const double *v); EAPI void eina_matrix3_array_set(Eina_Matrix3 *m, const double *v);
/** /**
* @brief Copy matrix. * @brief Copies matrix.
* *
* @param dst The matrix copy * @param dst The matrix copy
* @param src The matrix for copy. * @param src The matrix for copy.
@ -498,7 +498,7 @@ EAPI void eina_matrix3_array_set(Eina_Matrix3 *m, const double *v);
EAPI void eina_matrix3_copy(Eina_Matrix3 *dst, const Eina_Matrix3 *src); EAPI void eina_matrix3_copy(Eina_Matrix3 *dst, const Eina_Matrix3 *src);
/** /**
* @brief Multiply two matrix * @brief Multiplies two matrix.
* *
* @param out The resulting matrix * @param out The resulting matrix
* @param mat_a The first member of the multiplication * @param mat_a The first member of the multiplication
@ -510,7 +510,7 @@ EAPI void eina_matrix3_multiply(Eina_Matrix3 *out, const Eina_Matrix3 *mat_a,
const Eina_Matrix3 *mat_b); const Eina_Matrix3 *mat_b);
/** /**
* @brief Multiply two matrix * @brief Multiplies two matrix.
* *
* @param out The resulting matrix * @param out The resulting matrix
* @param mat_a The first member of the multiplication * @param mat_a The first member of the multiplication
@ -522,7 +522,7 @@ EAPI void eina_matrix3_multiply_copy(Eina_Matrix3 *out, const Eina_Matrix3 *mat_
const Eina_Matrix3 *mat_b); const Eina_Matrix3 *mat_b);
/** /**
* @brief Transform scale of matrix * @brief Transforms scale of matrix.
* *
* @param out The resulting matrix * @param out The resulting matrix
* @param s_x The scale value for x * @param s_x The scale value for x
@ -533,7 +533,7 @@ EAPI void eina_matrix3_multiply_copy(Eina_Matrix3 *out, const Eina_Matrix3 *mat_
EAPI void eina_matrix3_scale_transform_set(Eina_Matrix3 *out, double s_x, double s_y); EAPI void eina_matrix3_scale_transform_set(Eina_Matrix3 *out, double s_x, double s_y);
/** /**
* @brief Transform position of matrix * @brief Transforms position of matrix.
* *
* @param out The resulting matrix * @param out The resulting matrix
* @param p_x The position value for x * @param p_x The position value for x
@ -545,7 +545,7 @@ EAPI void eina_matrix3_position_transform_set(Eina_Matrix3 *out, const double p_
const double p_y); const double p_y);
/** /**
* @brief Set normal of the given matrix. * @brief Sets normal of the given matrix.
* *
* @param out The result mtrix of normal * @param out The result mtrix of normal
* @param m The matrix * @param m The matrix
@ -555,7 +555,7 @@ EAPI void eina_matrix3_position_transform_set(Eina_Matrix3 *out, const double p_
EAPI void eina_normal3_matrix_get(Eina_Matrix3 *out, const Eina_Matrix4 *m); EAPI void eina_normal3_matrix_get(Eina_Matrix3 *out, const Eina_Matrix4 *m);
/** /**
* @brief Convert an Eina_Matrix3 into an Eina_Matrix4. * @brief Converts an Eina_Matrix3 into an Eina_Matrix4.
* *
* @param m3 The destination Eina_Matrix3. * @param m3 The destination Eina_Matrix3.
* @param m4 The source Eina_Matrix4. * @param m4 The source Eina_Matrix4.
@ -575,7 +575,7 @@ EAPI void eina_matrix3_matrix4_to(Eina_Matrix4 *m4, const Eina_Matrix3 *m3);
*/ */
/** /**
* @brief Return the type of the given floating point matrix. * @brief Returns the type of the given floating point matrix.
* *
* @param m The floating point matrix. * @param m The floating point matrix.
* @return The type of the matrix. * @return The type of the matrix.
@ -588,7 +588,7 @@ EAPI void eina_matrix3_matrix4_to(Eina_Matrix4 *m4, const Eina_Matrix3 *m3);
EAPI Eina_Matrix_Type eina_matrix4_type_get(const Eina_Matrix4 *m); EAPI Eina_Matrix_Type eina_matrix4_type_get(const Eina_Matrix4 *m);
/** /**
* @brief Set the values of the coefficients of the given floating * @brief Sets the values of the coefficients of the given floating
* point matrix. * point matrix.
* *
* @param m The floating point matrix. * @param m The floating point matrix.
@ -623,7 +623,7 @@ EAPI void eina_matrix4_values_set(Eina_Matrix4 *m,
double wx, double wy, double wz, double ww); double wx, double wy, double wz, double ww);
/** /**
* @brief Get the values of the coefficients of the given floating * @brief Gets the values of the coefficients of the given floating
* point matrix. * point matrix.
* *
* @param m The floating point matrix. * @param m The floating point matrix.
@ -658,7 +658,7 @@ EAPI void eina_matrix4_values_get(const Eina_Matrix4 *m,
double *wx, double *wy, double *wz, double *ww); double *wx, double *wy, double *wz, double *ww);
/** /**
* @brief Return the determinant of the given matrix. * @brief Returns the determinant of the given matrix.
* *
* @param m The matrix. * @param m The matrix.
* @return The determinant. * @return The determinant.
@ -671,7 +671,7 @@ EAPI void eina_matrix4_values_get(const Eina_Matrix4 *m,
EAPI double eina_matrix4_determinant(const Eina_Matrix4 *m); EAPI double eina_matrix4_determinant(const Eina_Matrix4 *m);
/** /**
* @brief Return the determinant of the given matrix. * @brief Returns the determinant of the given matrix.
* *
* @param m The matrix. * @param m The matrix.
* @return The determinant. * @return The determinant.
@ -685,7 +685,7 @@ EAPI Eina_Bool eina_matrix4_normalized(Eina_Matrix4 *out,
const Eina_Matrix4 *in); const Eina_Matrix4 *in);
/** /**
* @brief Return the inverse of the given matrix. * @brief Returns the inverse of the given matrix.
* *
* @param out The inverse matrix * @param out The inverse matrix
* @param in The matrix. * @param in The matrix.
@ -696,7 +696,7 @@ EAPI Eina_Bool eina_matrix4_normalized(Eina_Matrix4 *out,
EAPI Eina_Bool eina_matrix4_inverse(Eina_Matrix4 *out, const Eina_Matrix4 *in); EAPI Eina_Bool eina_matrix4_inverse(Eina_Matrix4 *out, const Eina_Matrix4 *in);
/** /**
* @brief Return the transpose of the given matrix. * @brief Returns the transpose of the given matrix.
* *
* @param out The transpose matrix * @param out The transpose matrix
* @param in The matrix. * @param in The matrix.
@ -708,7 +708,7 @@ EAPI Eina_Bool eina_matrix4_inverse(Eina_Matrix4 *out, const Eina_Matrix4 *in);
EAPI void eina_matrix4_transpose(Eina_Matrix4 *out, const Eina_Matrix4 *in); EAPI void eina_matrix4_transpose(Eina_Matrix4 *out, const Eina_Matrix4 *in);
/** /**
* @brief Convert an Eina_Matrix4 into an Eina_Matrix3. * @brief Converts an Eina_Matrix4 into an Eina_Matrix3.
* *
* @param m3 The destination Eina_Matrix3. * @param m3 The destination Eina_Matrix3.
* @param m4 The source Eina_Matrix4. * @param m4 The source Eina_Matrix4.
@ -718,7 +718,7 @@ EAPI void eina_matrix4_transpose(Eina_Matrix4 *out, const Eina_Matrix4 *in);
EAPI void eina_matrix4_matrix3_to(Eina_Matrix3 *m3, const Eina_Matrix4 *m4); EAPI void eina_matrix4_matrix3_to(Eina_Matrix3 *m3, const Eina_Matrix4 *m4);
/** /**
* @brief Set an identity matrix * @brief Sets an identity matrix
* *
* @param out The matrix to set * @param out The matrix to set
* *
@ -727,7 +727,7 @@ EAPI void eina_matrix4_matrix3_to(Eina_Matrix3 *m3, const Eina_Matrix4 *m4);
EAPI void eina_matrix4_identity(Eina_Matrix4 *out); EAPI void eina_matrix4_identity(Eina_Matrix4 *out);
/** /**
* @brief Multiply two matrix * @brief Multiplies two matrix.
* *
* @param out The resulting matrix * @param out The resulting matrix
* @param a The first member of the multiplication * @param a The first member of the multiplication
@ -739,7 +739,7 @@ EAPI void eina_matrix4_multiply_copy(Eina_Matrix4 *out,
const Eina_Matrix4 *mat_a, const Eina_Matrix4 *mat_b); const Eina_Matrix4 *mat_a, const Eina_Matrix4 *mat_b);
/** /**
* @brief Set array to matrix. * @brief Sets array to matrix.
* *
* @param m The result matrix * @param m The result matrix
* @param v The the array[16] for set * @param v The the array[16] for set
@ -751,7 +751,7 @@ EAPI void eina_matrix4_multiply_copy(Eina_Matrix4 *out,
EAPI void eina_matrix4_array_set(Eina_Matrix4 *m, const double *v); EAPI void eina_matrix4_array_set(Eina_Matrix4 *m, const double *v);
/** /**
* @brief Copy matrix. * @brief Copies matrix.
* *
* @param dst The matrix copy * @param dst The matrix copy
* @param src The matrix for copy. * @param src The matrix for copy.
@ -761,7 +761,7 @@ EAPI void eina_matrix4_array_set(Eina_Matrix4 *m, const double *v);
EAPI void eina_matrix4_copy(Eina_Matrix4 *dst, const Eina_Matrix4 *src); EAPI void eina_matrix4_copy(Eina_Matrix4 *dst, const Eina_Matrix4 *src);
/** /**
* @brief Multiply two matrix with check * @brief Multiplies two matrix with check.
* *
* @param out The resulting matrix * @param out The resulting matrix
* @param a The first member of the multiplication * @param a The first member of the multiplication
@ -773,7 +773,7 @@ EAPI void eina_matrix4_multiply(Eina_Matrix4 *out, const Eina_Matrix4 *mat_a,
const Eina_Matrix4 *mat_b); const Eina_Matrix4 *mat_b);
/** /**
* @brief Set orthogonality matrix * @brief Sets orthogonality matrix.
* *
* @param m The resulting matrix * @param m The resulting matrix
* @param right The right value * @param right The right value
@ -821,7 +821,7 @@ struct _Eina_Matrix2
}; };
/** /**
* @brief Set the values of the coefficients of the given floating * @brief Sets the values of the coefficients of the given floating
* point matrix. * point matrix.
* *
* @param m The floating point matrix. * @param m The floating point matrix.
@ -841,7 +841,7 @@ EAPI void eina_matrix2_values_set(Eina_Matrix2 *m, double xx, double xy,
double yx, double yy); double yx, double yy);
/** /**
* @brief Get the values of the coefficients of the given floating * @brief Gets the values of the coefficients of the given floating
* point matrix. * point matrix.
* *
* @param m The floating point matrix. * @param m The floating point matrix.
@ -861,7 +861,7 @@ EAPI void eina_matrix2_values_get(const Eina_Matrix2 *m, double *xx, double *xy,
double *yx, double *yy); double *yx, double *yy);
/** /**
* @brief Compute the inverse with check of the given matrix. * @brief Computes the inverse with check of the given matrix.
* *
* @param m The matrix to inverse. * @param m The matrix to inverse.
* @param m2 The inverse matrix. * @param m2 The inverse matrix.
@ -875,7 +875,7 @@ EAPI void eina_matrix2_values_get(const Eina_Matrix2 *m, double *xx, double *xy,
EAPI void eina_matrix2_inverse(Eina_Matrix2 *out, const Eina_Matrix2 *mat); EAPI void eina_matrix2_inverse(Eina_Matrix2 *out, const Eina_Matrix2 *mat);
/** /**
* @brief Set the given floating point matrix to the identity matrix. * @brief Sets the given floating point matrix to the identity matrix.
* *
* @param m The floating point matrix to set * @param m The floating point matrix to set
* *
@ -887,9 +887,9 @@ EAPI void eina_matrix2_inverse(Eina_Matrix2 *out, const Eina_Matrix2 *mat);
EAPI void eina_matrix2_identity(Eina_Matrix2 *m); EAPI void eina_matrix2_identity(Eina_Matrix2 *m);
/** /**
* @brief Set array to matrix. * @brief Sets array to matrix.
* *
* @param m The rsult matrix * @param m The result matrix
* @param v The the array[4] for set * @param v The the array[4] for set
* *
* Set to matrix first 4 elements from array * Set to matrix first 4 elements from array
@ -899,7 +899,7 @@ EAPI void eina_matrix2_identity(Eina_Matrix2 *m);
EAPI void eina_matrix2_array_set(Eina_Matrix2 *m, const double *v); EAPI void eina_matrix2_array_set(Eina_Matrix2 *m, const double *v);
/** /**
* @brief Copy matrix. * @brief Copies matrix.
* *
* @param dst The matrix copy * @param dst The matrix copy
* @param src The matrix for copy. * @param src The matrix for copy.
@ -909,7 +909,7 @@ EAPI void eina_matrix2_array_set(Eina_Matrix2 *m, const double *v);
EAPI void eina_matrix2_copy(Eina_Matrix2 *dst, const Eina_Matrix2 *src); EAPI void eina_matrix2_copy(Eina_Matrix2 *dst, const Eina_Matrix2 *src);
/** /**
* @brief Multiply two matrix * @brief Multiplies two matrix.
* *
* @param out The resulting matrix * @param out The resulting matrix
* @param a The first member of the multiplication * @param a The first member of the multiplication
@ -921,7 +921,7 @@ EAPI void eina_matrix2_multiply(Eina_Matrix2 *out, const Eina_Matrix2 *mat_a,
const Eina_Matrix2 *mat_b); const Eina_Matrix2 *mat_b);
/** /**
* @brief Multiply two matrix with check * @brief Multiplies two matrix with check.
* *
* @param out The resulting matrix * @param out The resulting matrix
* @param a The first member of the multiplication * @param a The first member of the multiplication
@ -933,7 +933,7 @@ EAPI void eina_matrix2_multiply_copy(Eina_Matrix2 *out, const Eina_Matrix2 *mat_
const Eina_Matrix2 *mat_b); const Eina_Matrix2 *mat_b);
/** /**
* @brief Return the type of the given floating point matrix. * @brief Returns the type of the given floating point matrix.
* *
* @param m The floating point matrix. * @param m The floating point matrix.
* @return The type of the matrix. * @return The type of the matrix.

138
src/lib/eina/eina_matrixsparse.h
View File

@ -74,20 +74,20 @@ typedef struct _Eina_Matrixsparse_Cell Eina_Matrixsparse_Cell;
/* constructors and destructors */ /* constructors and destructors */
/** /**
* @brief Create a new Sparse Matrix. * @brief Creates a new Sparse Matrix.
* *
* @param rows number of rows in matrix. Operations with rows greater than this * @param rows Number of rows in matrix. Operations with rows greater than this
* value will fail. * value will fail.
* @param cols number of columns in matrix. Operations with columns greater * @param cols Number of columns in matrix. Operations with columns greater
* than this value will fail. * than this value will fail.
* @param free_func used to delete cell data contents, used by * @param free_func Used to delete cell data contents, used by
* eina_matrixsparse_free(), eina_matrixsparse_size_set(), * eina_matrixsparse_free(), eina_matrixsparse_size_set(),
* eina_matrixsparse_row_idx_clear(), * eina_matrixsparse_row_idx_clear(),
* eina_matrixsparse_column_idx_clear(), * eina_matrixsparse_column_idx_clear(),
* eina_matrixsparse_cell_idx_clear() and possible others. * eina_matrixsparse_cell_idx_clear() and possible others.
* @param user_data given to @a free_func as first parameter. * @param user_data Given to @a free_func as first parameter.
* *
* @return Newly allocated matrix or @c NULL if allocation failed. * @return Newly allocated matrix, or @c NULL if allocation failed.
*/ */
EAPI Eina_Matrixsparse *eina_matrixsparse_new(unsigned long rows, EAPI Eina_Matrixsparse *eina_matrixsparse_new(unsigned long rows,
unsigned long cols, unsigned long cols,
@ -96,7 +96,7 @@ EAPI Eina_Matrixsparse *eina_matrixsparse_new(unsigned long rows,
const void *user_data); const void *user_data);
/** /**
* @brief Free resources allocated to Sparse Matrix. * @brief Frees resources allocated to Sparse Matrix.
* *
* @param m The Sparse Matrix instance to free, must @b not be @c NULL. * @param m The Sparse Matrix instance to free, must @b not be @c NULL.
*/ */
@ -105,15 +105,15 @@ 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 Sparse Matrix.
* *
* The given parameters are guaranteed to be set if they're not @c NULL, * 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). * even if this function fails (ie: @a m is not a valid matrix instance).
* *
* @param m the sparse matrix to operate on. * @param m The sparse matrix to operate on.
* @param rows returns the number of rows, may be @c NULL. If @a m is invalid, * @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. * 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 * @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. * invalid, returned value is zero, otherwise it's a positive integer.
*/ */
EAPI void eina_matrixsparse_size_get(const Eina_Matrixsparse *m, EAPI void eina_matrixsparse_size_get(const Eina_Matrixsparse *m,
@ -121,17 +121,17 @@ EAPI void eina_matrixsparse_size_get(const Eina_Matrixsparse *m,
unsigned long *cols); unsigned long *cols);
/** /**
* @brief Resize the Sparse Matrix. * @brief Resizes the Sparse Matrix.
* *
* This will resize the sparse matrix, possibly freeing cells on rows * This will resize the sparse matrix, possibly freeing cells on rows
* and columns that will cease to exist. * and columns that will cease to exist.
* *
* @param m the sparse matrix to operate on. * @param m The sparse matrix to operate on.
* @param rows the new number of rows, must be greater than zero. * @param rows The new number of rows, must be greater than zero.
* @param cols the new number of columns, 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. * @return #EINA_TRUE on success, #EINA_FALSE on failure.
* *
* @warning cells, rows or columns are not reference counted and thus * @warning Cells, rows or columns are not reference counted and thus
* after this call any reference might be invalid if instance were * after this call any reference might be invalid if instance were
* freed. * freed.
*/ */
@ -142,12 +142,12 @@ EAPI Eina_Bool eina_matrixsparse_size_set(Eina_Matrixsparse *m,
/* data getting */ /* data getting */
/** /**
* Get the cell reference inside Sparse Matrix. * @brief Gets the cell reference inside Sparse Matrix.
* *
* @param m the sparse matrix to operate on. * @param m The sparse matrix to operate on.
* @param row the new number of row to clear. * @param row The new number of row to clear.
* @param col the new number of column to clear. * @param col The new number of column to clear.
* @param cell pointer to return cell reference, if any exists. * @param cell Pointer to return cell reference, if any exists.
* *
* @return @c 1 on success, @c 0 on failure. It is considered success if did not * @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 * exist but index is inside matrix size, in this case @c *cell == NULL
@ -158,11 +158,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); 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 data associated with given cell reference.
* *
* @param cell given cell reference, must @b not be @c NULL. * @param cell Given cell reference, must @b not be @c NULL.
* *
* @return data associated with given cell. * @return Data associated with given cell.
* *
* @see eina_matrixsparse_cell_idx_get() * @see eina_matrixsparse_cell_idx_get()
* @see eina_matrixsparse_data_idx_get() * @see eina_matrixsparse_data_idx_get()
@ -170,11 +170,11 @@ 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); EAPI void *eina_matrixsparse_cell_data_get(const Eina_Matrixsparse_Cell *cell);
/** /**
* Get data associated with given cell given its indexes. * @brief Gets data associated with given cell given its indexes.
* *
* @param m the sparse matrix to operate on. * @param m The sparse matrix to operate on.
* @param row the new number of row to clear. * @param row The new number of row to clear.
* @param col the new number of column to clear. * @param col The new number of column to clear.
* *
* @return Data associated with given cell or @c NULL if nothing is associated. * @return Data associated with given cell or @c NULL if nothing is associated.
* *
@ -184,11 +184,11 @@ 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); 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 position (indexes) of the given cell.
* *
* @param cell the cell reference, must @b not be @c NULL. * @param cell The cell reference, must @b not be @c NULL.
* @param row where to store cell row number, may 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 col Where to store cell column number, may be @c NULL.
* *
* @return #EINA_TRUE on success, #EINA_FALSE otherwise (@c cell is @c NULL). * @return #EINA_TRUE on success, #EINA_FALSE otherwise (@c cell is @c NULL).
*/ */
@ -197,11 +197,11 @@ EAPI Eina_Bool eina_matrixsparse_cell_position_get(const Eina_Matrixsparse_Cell
/* data setting */ /* data setting */
/** /**
* Change cell reference value without freeing the possibly existing old value. * @brief Changes cell reference value without freeing the possibly existing old value.
* *
* @param cell the cell reference, must @b not be @c NULL. * @param cell The cell reference, must @b not be @c NULL.
* @param data new data to set. * @param data New data to set.
* @param p_old returns the old value intact (not freed). * @param p_old Returns the old value intact (not freed).
* *
* @return #EINA_TRUE on success, #EINA_FALSE otherwise (@a cell is @c NULL). * @return #EINA_TRUE on success, #EINA_FALSE otherwise (@a cell is @c NULL).
* *
@ -211,13 +211,13 @@ 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); 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 cell value freeing the possibly existing old value.
* *
* In contrast to eina_matrixsparse_cell_data_replace(), this function will * In contrast to eina_matrixsparse_cell_data_replace(), this function will
* call @c free_func() on existing value. * call @c free_func() on existing value.
* *
* @param cell the cell reference, must @b not be @c NULL. * @param cell The cell reference, must @b not be @c NULL.
* @param data new data to set. * @param data New data to set.
* *
* @return #EINA_TRUE on success, #EINA_FALSE otherwise (@a cell is @c NULL). * @return #EINA_TRUE on success, #EINA_FALSE otherwise (@a cell is @c NULL).
* *
@ -227,13 +227,13 @@ 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); 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 * @brief Changes cell value without freeing the possibly existing old value, using
* indexes. * indexes.
* *
* @param m the sparse matrix, must @b not be @c NULL. * @param m The sparse matrix, must @b not be @c NULL.
* @param row the row number to set the value. * @param row The row number to set the value.
* @param col the column number to set the value. * @param col The column number to set the value.
* @param data new data to set. * @param data New data to set.
* @param p_old returns the old value intact (not freed). * @param p_old returns the old value intact (not freed).
* *
* @return #EINA_TRUE on success, #EINA_FALSE otherwise (@a m is @c NULL, indexes are not valid). * @return #EINA_TRUE on success, #EINA_FALSE otherwise (@a m is @c NULL, indexes are not valid).
@ -244,16 +244,16 @@ 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); 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 * @brief Changes cell value freeing the possibly existing old value, using
* indexes. * indexes.
* *
* In contrast to eina_matrixsparse_data_idx_replace(), this function will * In contrast to eina_matrixsparse_data_idx_replace(), this function will
* call @c free_func() on existing value. * call @c free_func() on existing value.
* *
* @param m the sparse matrix, must @b not be @c NULL. * @param m The sparse matrix, must @b not be @c NULL.
* @param row the row number to set the value. * @param row The row number to set the value.
* @param col the column number to set the value. * @param col The column number to set the value.
* @param data new data to set. * @param data New data to set.
* *
* @return #EINA_TRUE on success, #EINA_FALSE otherwise (@a m is @c NULL, indexes are not valid). * @return #EINA_TRUE on success, #EINA_FALSE otherwise (@a m is @c NULL, indexes are not valid).
* *
@ -264,57 +264,57 @@ EAPI Eina_Bool eina_matrixsparse_data_idx_set(Eina_Matrixsparse *m, unsigned lon
/* data deleting */ /* data deleting */
/** /**
* Clear (erase all cells) of row given its index. * @brief Clears (erases all cells) of row given its index.
* *
* Existing cells will be cleared with @c free_func() given to * Existing cells will be cleared with @c free_func() given to
* eina_matrixsparse_new(). * eina_matrixsparse_new().
* *
* @param m the sparse matrix to operate on. * @param m The sparse matrix to operate on.
* @param row the new number of row to clear. * @param row The new number of row to clear.
* *
* @return #EINA_TRUE on success, #EINA_FALSE on failure. It is considered success if row * @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 * had no cells filled. Failure is asking for clear row outside
* matrix size. * matrix size.
* *
* @warning cells, rows or columns are not reference counted and thus * @warning Cells, rows or columns are not reference counted and thus
* after this call any reference might be invalid if instance were * after this call any reference might be invalid if instance were
* freed. * freed.
*/ */
EAPI Eina_Bool eina_matrixsparse_row_idx_clear(Eina_Matrixsparse *m, unsigned long row); 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 cells) of column given its index.
* *
* Existing cells will be cleared with @c free_func() given to * Existing cells will be cleared with @c free_func() given to
* eina_matrixsparse_new(). * eina_matrixsparse_new().
* *
* @param m the sparse matrix to operate on. * @param m The sparse matrix to operate on.
* @param col the new number of column to clear. * @param col The new number of column to clear.
* *
* @return #EINA_TRUE on success, #EINA_FALSE on failure. It is considered success if column * @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 * had no cells filled. Failure is asking for clear column outside
* matrix size. * matrix size.
* *
* @warning cells, rows or columns are not reference counted and thus * @warning Cells, rows or columns are not reference counted and thus
* after this call any reference might be invalid if instance were * after this call any reference might be invalid if instance were
* freed. * freed.
*/ */
EAPI Eina_Bool eina_matrixsparse_column_idx_clear(Eina_Matrixsparse *m, unsigned long col); EAPI Eina_Bool eina_matrixsparse_column_idx_clear(Eina_Matrixsparse *m, unsigned long col);
/** /**
* Clear (erase) cell given its indexes. * @brief Clears (erases) cell given its indexes.
* *
* Existing cell will be cleared with @c free_func() given to * Existing cell will be cleared with @c free_func() given to
* eina_matrixsparse_new(). * eina_matrixsparse_new().
* *
* @param m the sparse matrix to operate on. * @param m The sparse matrix to operate on.
* @param row the new number of row to clear. * @param row The new number of row to clear.
* @param col the new number of column to clear. * @param col The new number of column to clear.
* *
* @return #EINA_TRUE on success, #EINA_FALSE on failure. It is considered success if did not * @return #EINA_TRUE on success, #EINA_FALSE on failure. It is considered success if did not
* exist but index is inside matrix size. * exist but index is inside matrix size.
* *
* @warning cells, rows or columns are not reference counted and thus * @warning Cells, rows or columns are not reference counted and thus
* after this call any reference might be invalid if instance were * after this call any reference might be invalid if instance were
* freed. * freed.
* *
@ -324,13 +324,13 @@ EAPI Eina_Bool eina_matrixsparse_column_idx_clear(Eina_Matrixsparse *m, unsigned
EAPI Eina_Bool eina_matrixsparse_cell_idx_clear(Eina_Matrixsparse *m, unsigned long row, unsigned long col); 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) cell given its reference.
* *
* @param cell the cell reference, must @b not be @c NULL. * @param cell The cell reference, must @b not be @c NULL.
* *
* @return #EINA_TRUE on success, #EINA_FALSE on failure. * @return #EINA_TRUE on success, #EINA_FALSE on failure.
* *
* @warning cells, rows or columns are not reference counted and thus * @warning Cells, rows or columns are not reference counted and thus
* after this call any reference might be invalid if instance were * after this call any reference might be invalid if instance were
* freed. * freed.
* *
@ -342,7 +342,7 @@ 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.
* *
* This is a cheap walk, it will just report existing cells and holes * This is a cheap walk, it will just report existing cells and holes
* in the sparse matrix will be ignored. That means the reported * in the sparse matrix will be ignored. That means the reported
@ -355,14 +355,14 @@ EAPI Eina_Bool eina_matrixsparse_cell_clear(Eina_Matrixsparse_Cell *cell);
* @param m The Sparse Matrix reference, must @b not be @c NULL. * @param m The Sparse Matrix reference, must @b not be @c NULL.
* @return A new iterator. * @return A new iterator.
* *
* @warning if the matrix structure changes then the iterator becomes * @warning If the matrix structure changes then the iterator becomes
* invalid! That is, if you add or remove cells this iterator * invalid! That is, if you add or remove cells this iterator
* behavior is undefined and your program may crash! * behavior is undefined and your program may crash!
*/ */
EAPI Eina_Iterator *eina_matrixsparse_iterator_new(const Eina_Matrixsparse *m); 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 matrix cells.
* *
* Unlike eina_matrixsparse_iterator_new() this one will report all * Unlike eina_matrixsparse_iterator_new() this one will report all
* matrix cells, even those that are still empty (holes). These will * matrix cells, even those that are still empty (holes). These will
@ -381,7 +381,7 @@ EAPI Eina_Iterator *eina_matrixsparse_iterator_new(const Eina_Matrixsparse *m);
* @param m The Sparse Matrix reference, must @b not be @c NULL. * @param m The Sparse Matrix reference, must @b not be @c NULL.
* @return A new iterator. * @return A new iterator.
* *
* @warning if the matrix structure changes then the iterator becomes * @warning If the matrix structure changes then the iterator becomes
* invalid! That is, if you add or remove cells this iterator * invalid! That is, if you add or remove cells this iterator
* behavior is undefined and your program may crash! * behavior is undefined and your program may crash!
*/ */

10
src/lib/eina/eina_mempool.h
View File

@ -125,7 +125,7 @@ static inline void *eina_mempool_realloc(Eina_Mempool *mp, void *element, unsign
static inline void *eina_mempool_malloc(Eina_Mempool *mp, unsigned int size) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; static inline void *eina_mempool_malloc(Eina_Mempool *mp, unsigned int size) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
/** /**
* @brief Allocate and zero memory using the given mempool. * @brief Allocates and zeros memory using the given mempool.
* *
* @param[in] mp The mempool * @param[in] mp The mempool
* @param[in] size The size in bytes to allocate * @param[in] size The size in bytes to allocate
@ -142,7 +142,7 @@ static inline void *eina_mempool_malloc(Eina_Mempool *mp, unsigned int size) EIN
static inline void *eina_mempool_calloc(Eina_Mempool *mp, unsigned int size) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; static inline void *eina_mempool_calloc(Eina_Mempool *mp, unsigned int size) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
/** /**
* @brief Free resources previously allocated by the given mempool. * @brief Frees resources previously allocated by the given mempool.
* *
* @param[in] mp The mempool * @param[in] mp The mempool
* @param[in] element The data to free * @param[in] element The data to free
@ -172,14 +172,14 @@ static inline void eina_mempool_free(Eina_Mempool *mp, void *element) EINA_ARG_
EAPI void eina_mempool_repack(Eina_Mempool *mp, Eina_Mempool_Repack_Cb cb, void *data) EINA_ARG_NONNULL(1, 2); EAPI void eina_mempool_repack(Eina_Mempool *mp, Eina_Mempool_Repack_Cb cb, void *data) EINA_ARG_NONNULL(1, 2);
/** /**
* @brief Run a garbage collection cycle. * @brief Runs a garbage collection cycle.
* *
* @param[in] mp The mempool * @param[in] mp The mempool
*/ */
EAPI void eina_mempool_gc(Eina_Mempool *mp) EINA_ARG_NONNULL(1); EAPI void eina_mempool_gc(Eina_Mempool *mp) EINA_ARG_NONNULL(1);
/** /**
* @brief Have the backend update its internal statistics. * @brief Has the backend update its internal statistics.
* *
* @param[in] mp The mempool * @param[in] mp The mempool
* *
@ -203,7 +203,7 @@ EAPI Eina_Bool eina_mempool_register(Eina_Mempool_Backend *be) EINA_ARG_NON
EAPI void eina_mempool_unregister(Eina_Mempool_Backend *be) EINA_ARG_NONNULL(1); EAPI void eina_mempool_unregister(Eina_Mempool_Backend *be) EINA_ARG_NONNULL(1);
/** /**
* @brief Computers the alignment that would be used when allocating a object of size @p size. * @brief Computes the alignment that would be used when allocating a object of size @p size.
* *
* @param[in] size * @param[in] size
* @return The alignment for an allocation of size @p size. * @return The alignment for an allocation of size @p size.

6
src/lib/eina/eina_mmap.h
View File

@ -5,7 +5,7 @@
* @addtogroup Eina_Mmap_Group Mmap Group * @addtogroup Eina_Mmap_Group Mmap Group
* @ingroup Eina * @ingroup Eina
* *
* @brief These functions provide helpers for safe mmap handling * @brief These functions provide helpers for safe mmap handling.
* *
* @{ * @{
* *
@ -13,7 +13,7 @@
*/ */
/** /**
* @brief Enable or disable safe mmaped IO handling * @brief Enables or disables safe mmaped IO handling.
* *
* @param enabled The enabled state (to enable, pass #EINA_TRUE) * @param enabled The enabled state (to enable, pass #EINA_TRUE)
* @return #EINA_TRUE on success, #EINA_FALSE on failure. * @return #EINA_TRUE on success, #EINA_FALSE on failure.
@ -43,7 +43,7 @@ EAPI Eina_Bool
eina_mmap_safety_enabled_set(Eina_Bool enabled); eina_mmap_safety_enabled_set(Eina_Bool enabled);
/** /**
* @brief Get the enabled state of mmap safety. * @brief Gets the enabled state of mmap safety.
* *
* @return The safety state (#EINA_TRUE if enabled) * @return The safety state (#EINA_TRUE if enabled)
* *

32
src/lib/eina/eina_module.h
View File

@ -110,7 +110,7 @@ extern EAPI Eina_Error EINA_ERROR_WRONG_MODULE;
extern EAPI Eina_Error EINA_ERROR_MODULE_INIT_FAILED; 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. * @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, * @return A new module. If @p file is @c NULL, or if it does not exist,
@ -127,7 +127,7 @@ EAPI Eina_Module *
eina_module_new(const char *file) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); 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. * @param module The module to delete.
* @return #EINA_TRUE on success, #EINA_FALSE otherwise. * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
@ -141,7 +141,7 @@ EAPI Eina_Bool
eina_module_free(Eina_Module *module) EINA_ARG_NONNULL(1); eina_module_free(Eina_Module *module) EINA_ARG_NONNULL(1);
/** /**
* @brief Load a module. * @brief Loads a module.
* *
* @param module The module to load. * @param module The module to load.
* @return #EINA_TRUE on success, #EINA_FALSE otherwise. * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
@ -162,7 +162,7 @@ EAPI Eina_Bool
eina_module_load(Eina_Module *module) EINA_ARG_NONNULL(1); eina_module_load(Eina_Module *module) EINA_ARG_NONNULL(1);
/** /**
* @brief Unload a module. * @brief Unloads a module.
* *
* @param module The module to load. * @param module The module to load.
* @return #EINA_TRUE on success, #EINA_FALSE otherwise. * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
@ -171,7 +171,7 @@ EAPI Eina_Bool
* loaded by eina_module_load(). If the reference counter of @p module is * loaded by eina_module_load(). If the reference counter of @p module is
* strictly greater than @c 1, #EINA_FALSE is returned. Otherwise, the * 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 * 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 * is shut down just before. In that case, #EINA_TRUE is
* returned. In all case, the reference counter is decreased. If @p module * returned. In all case, the reference counter is decreased. If @p module
* is @c NULL, the function returns immediately #EINA_FALSE. * is @c NULL, the function returns immediately #EINA_FALSE.
*/ */
@ -179,7 +179,7 @@ EAPI Eina_Bool
eina_module_unload(Eina_Module *module) EINA_ARG_NONNULL(1); eina_module_unload(Eina_Module *module) EINA_ARG_NONNULL(1);
/** /**
* @brief Retrieve the data associated to a symbol. * @brief Retrieves the data associated to a symbol.
* *
* @param module The module. * @param module The module.
* @param symbol The symbol. * @param symbol The symbol.
@ -194,7 +194,7 @@ EAPI void *
eina_module_symbol_get(const Eina_Module *module, const char *symbol) EINA_PURE EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT; eina_module_symbol_get(const Eina_Module *module, const char *symbol) EINA_PURE EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT;
/** /**
* @brief Return the file name associated to the module. * @brief Returns the file name associated to the module.
* *
* @param module The module. * @param module The module.
* @return The file name. * @return The file name.
@ -207,7 +207,7 @@ EAPI const char *
eina_module_file_get(const Eina_Module *module) EINA_PURE EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); eina_module_file_get(const Eina_Module *module) EINA_PURE EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
/** /**
* @brief Define if on module load we should expose all symbol * @brief Defines if on module load we should expose all symbol
* *
* @param module The module to turn off/on symbol to be exposed * @param module The module to turn off/on symbol to be exposed
* @since 1.11 * @since 1.11
@ -215,7 +215,7 @@ EAPI const char *
EAPI void eina_module_symbol_global_set(Eina_Module *module, Eina_Bool global) EINA_ARG_NONNULL(1); EAPI void eina_module_symbol_global_set(Eina_Module *module, Eina_Bool global) EINA_ARG_NONNULL(1);
/** /**
* @brief Return the path built from the location of a library and a * @brief Returns the path built from the location of a library and a
* given sub directory. * given sub directory.
* *
* @param symbol The symbol to search for. * @param symbol The symbol to search for.
@ -232,7 +232,7 @@ EAPI char *
eina_module_symbol_path_get(const void *symbol, const char *sub_dir) EINA_PURE EINA_MALLOC EINA_ARG_NONNULL(1, 2); 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 * @brief Returns the path built from the value of an environment variable and a
* given sub directory. * given sub directory.
* *
* @param env The environment variable to expand. * @param env The environment variable to expand.
@ -250,7 +250,7 @@ EAPI char *
/** /**
* @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.
* *
* @param array The array that stores the list of the modules. * @param array The array that stores the list of the modules.
* @param path The directory's path to search for modules. * @param path The directory's path to search for modules.
@ -266,7 +266,7 @@ EAPI Eina_Array *
eina_module_arch_list_get(Eina_Array *array, const char *path, const char *arch); 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. * @brief Gets a list of modules found on the directory path.
* *
* @param array The array that stores the list of the modules. * @param array The array that stores the list of the modules.
* @param path The directory's path to search for modules. * @param path The directory's path to search for modules.
@ -288,7 +288,7 @@ 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; 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. * @param array The array of modules to load.
* *
@ -299,7 +299,7 @@ EAPI void
eina_module_list_load(Eina_Array *array) EINA_ARG_NONNULL(1); eina_module_list_load(Eina_Array *array) EINA_ARG_NONNULL(1);
/** /**
* @brief Unload every module on the list of modules. * @brief Unloads every module on the list of modules.
* *
* @param array The array of modules to unload. * @param array The array of modules to unload.
* *
@ -310,7 +310,7 @@ EAPI void
eina_module_list_unload(Eina_Array *array) EINA_ARG_NONNULL(1); eina_module_list_unload(Eina_Array *array) EINA_ARG_NONNULL(1);
/** /**
* @p Free every module on the list of modules. * @p Frees every module on the list of modules.
* *
* @param array The array of modules to free. * @param array The array of modules to free.
* *
@ -321,7 +321,7 @@ EAPI void
eina_module_list_free(Eina_Array *array) EINA_ARG_NONNULL(1); eina_module_list_free(Eina_Array *array) EINA_ARG_NONNULL(1);
/** /**
* @brief Find an module in array. * @brief Finds an module in array.
* *
* @param array The array to find the module. * @param array The array to find the module.
* @param module The name of module to be searched. * @param module The name of module to be searched.

2
src/lib/eina/eina_prefix.h
View File

@ -15,7 +15,7 @@
/** /**
* @typedef Eina_Prefix * @typedef Eina_Prefix
* @brief An opaque type for prefix handle * @brief An opaque type for prefix handle.
* @details This is a prefix object that is returned by eina_prefix_new() when trying * @details This is a prefix object that is returned by eina_prefix_new() when trying
* to determine the runtime location of the software in question so that other * to determine the runtime location of the software in question so that other
* data files such as images, sound files, other executable utilities, * data files such as images, sound files, other executable utilities,

2
src/lib/eina/eina_quad.h
View File

@ -34,7 +34,7 @@
/** /**
* @defgroup Eina_Quad_Group Quadrangles * @defgroup Eina_Quad_Group Quadrangles
* *
* @brief Quadrangles operations * @brief Quadrangles operations.
* *
* @{ * @{
*/ */

14
src/lib/eina/eina_rbtree.h
View File

@ -149,9 +149,9 @@ typedef void (*Eina_Rbtree_Free_Cb)(Eina_Rbtree *node, void *data);
/** /**
* @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 root The root of an existing valid red black tree.
* @param node The new node to insert. * @param node The new node to insert.
* @param cmp The callback that is able to compare two nodes. * @param cmp The callback that is able to compare two nodes.
* @param data Private data to help the compare function. * @param data Private data to help the compare function.
@ -164,7 +164,7 @@ typedef void (*Eina_Rbtree_Free_Cb)(Eina_Rbtree *node, void *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; 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.
* *
* @param root The root of a valid red black tree. * @param root The root of a valid red black tree.
* @param node The node to remove from the tree. * @param node The node to remove from the tree.
@ -179,7 +179,7 @@ EAPI Eina_Rbtree *eina_rbtree_inline_insert(Eina_Rbtree *root, Eina_Rbt
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; 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 nodes from a valid red black tree.
* *
* @param root The root of a valid red black tree. * @param root The root of a valid red black tree.
* @param func The callback that will free each node. * @param func The callback that will free each node.
@ -192,7 +192,7 @@ 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 a rbtree.
* *
* @param root The root of rbtree. * @param root The root of rbtree.
* @return A new iterator. * @return A new iterator.
@ -212,7 +212,7 @@ static inline Eina_Rbtree *eina_rbtree_inline_lookup(const Eina_Rbtree *root, co
EAPI Eina_Iterator *eina_rbtree_iterator_prefix(const Eina_Rbtree *root) EINA_MALLOC EINA_WARN_UNUSED_RESULT; 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 a rbtree.
* *
* @param root The root of rbtree. * @param root The root of rbtree.
* @return A new iterator. * @return A new iterator.
@ -232,7 +232,7 @@ EAPI Eina_Iterator *eina_rbtree_iterator_prefix(const Eina_Rbtree *root)
EAPI Eina_Iterator *eina_rbtree_iterator_infix(const Eina_Rbtree *root) EINA_MALLOC EINA_WARN_UNUSED_RESULT; 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 a rbtree.
* *
* @param root The root of rbtree. * @param root The root of rbtree.
* @return A new iterator. * @return A new iterator.

68
src/lib/eina/eina_rectangle.h
View File

@ -68,10 +68,10 @@ typedef struct _Eina_Rectangle_Pool Eina_Rectangle_Pool;
*/ */
typedef enum { typedef enum {
Eina_Packing_Descending, /**< Current */ Eina_Packing_Descending, /**< Current */
Eina_Packing_Ascending, /**< sorting in assending order */ Eina_Packing_Ascending, /**< sorting in ascending order */
Eina_Packing_Bottom_Left, /**< sorting in bottemleft fasion */ Eina_Packing_Bottom_Left, /**< sorting in bottom left fashion */
Eina_Packing_Bottom_Left_Skyline, /**< bottemleft skyline */ Eina_Packing_Bottom_Left_Skyline, /**< bottom left skyline */
Eina_Packing_Bottom_Left_Skyline_Improved /**< optimized bottemleft skyline */ Eina_Packing_Bottom_Left_Skyline_Improved /**< optimized bottom left skyline */
} Eina_Rectangle_Packing; } Eina_Rectangle_Packing;
/** /**
@ -88,7 +88,7 @@ typedef enum {
/** /**
* @brief Check if the given spans intersect. * @brief Checks if the given spans intersect.
* *
* @param c1 The column of the first span. * @param c1 The column of the first span.
* @param l1 The length of the first span. * @param l1 The length of the first span.
@ -102,7 +102,7 @@ typedef enum {
static inline int eina_spans_intersect(int c1, int l1, int c2, int l2) EINA_WARN_UNUSED_RESULT; 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. * @brief Checks if the given rectangle is empty.
* *
* @param r The rectangle to check. * @param r The rectangle to check.
* @return #EINA_TRUE if the rectangle is empty, #EINA_FALSE otherwise. * @return #EINA_TRUE if the rectangle is empty, #EINA_FALSE otherwise.
@ -114,7 +114,7 @@ static inline int eina_spans_intersect(int c1, int l1, int c2, int l2) E
static inline Eina_Bool eina_rectangle_is_empty(const Eina_Rectangle *r) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; 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. * @brief Sets the coordinates and size of the given rectangle.
* *
* @param r The rectangle. * @param r The rectangle.
* @param x The top-left x coordinate of the rectangle. * @param x The top-left x coordinate of the rectangle.
@ -129,7 +129,7 @@ static inline Eina_Bool eina_rectangle_is_empty(const Eina_Rectangle *r) EINA_
static inline void eina_rectangle_coords_from(Eina_Rectangle *r, int x, int y, int w, int h) EINA_ARG_NONNULL(1); 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. * @brief Checks if the given rectangles intersect.
* *
* @param r1 The first rectangle. * @param r1 The first rectangle.
* @param r2 The second rectangle. * @param r2 The second rectangle.
@ -142,7 +142,7 @@ static inline void eina_rectangle_coords_from(Eina_Rectangle *r, int x, i
static inline Eina_Bool eina_rectangles_intersect(const Eina_Rectangle *r1, const Eina_Rectangle *r2) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT; 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 . * @brief Checks if the given x-coordinate is in the rectangle .
* *
* @param r The rectangle. * @param r The rectangle.
* @param x The x coordinate. * @param x The x coordinate.
@ -155,7 +155,7 @@ static inline Eina_Bool eina_rectangles_intersect(const Eina_Rectangle *r1, co
static inline Eina_Bool eina_rectangle_xcoord_inside(const Eina_Rectangle *r, int x) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; 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 . * @brief Checks if the given y-coordinate is in the rectangle .
* *
* @param r The rectangle. * @param r The rectangle.
* @param y The y coordinate. * @param y The y coordinate.
@ -168,7 +168,7 @@ static inline Eina_Bool eina_rectangle_xcoord_inside(const Eina_Rectangle *r,
static inline Eina_Bool eina_rectangle_ycoord_inside(const Eina_Rectangle *r, int y) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; 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 . * @brief Checks if the given point is in the rectangle .
* *
* @param r The rectangle. * @param r The rectangle.
* @param x The x coordinate of the point. * @param x The x coordinate of the point.
@ -182,7 +182,7 @@ static inline Eina_Bool eina_rectangle_ycoord_inside(const Eina_Rectangle *r,
static inline Eina_Bool eina_rectangle_coords_inside(const Eina_Rectangle *r, int x, int y) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; 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. * @brief Gets the union of two rectangles.
* *
* @param dst The first rectangle. * @param dst The first rectangle.
* @param src The second rectangle. * @param src The second rectangle.
@ -194,7 +194,7 @@ static inline Eina_Bool eina_rectangle_coords_inside(const Eina_Rectangle *r,
static inline void eina_rectangle_union(Eina_Rectangle *dst, const Eina_Rectangle *src) EINA_ARG_NONNULL(1, 2); 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. * @brief Gets the intersection of two rectangles.
* *
* @param dst The first rectangle. * @param dst The first rectangle.
* @param src The second rectangle. * @param src The second rectangle.
@ -245,10 +245,10 @@ static inline Eina_Bool eina_rectangle_is_valid(const Eina_Rectangle *r) EINA_
* @brief Gives the rectangle maximum x coordinate. * @brief Gives the rectangle maximum x coordinate.
* *
* @param thiz The rectangle * @param thiz The rectangle
* @return the maximum x coordinate * @return The maximum x coordinate
* *
* This function calculates the maximum x coordinate of the rectangle by summing * This function calculates the maximum x coordinate of the rectangle by summing
* the @p width with the current @p x coodinate of the rectangle. * the @p width with the current @p x coordinate of the rectangle.
*/ */
static inline int eina_rectangle_max_x(Eina_Rectangle *thiz) EINA_ARG_NONNULL(1); static inline int eina_rectangle_max_x(Eina_Rectangle *thiz) EINA_ARG_NONNULL(1);
@ -257,7 +257,7 @@ static inline int eina_rectangle_max_x(Eina_Rectangle *thiz) EINA_ARG_NO
* @brief Gives the rectangle maximum y coordinate. * @brief Gives the rectangle maximum y coordinate.
* *
* @param thiz The rectangle * @param thiz The rectangle
* @return the maximum y coordinate * @return The maximum y coordinate
* *
* This function calculates the maximum y coordinate of the rectangle by summing * This function calculates the maximum y coordinate of the rectangle by summing
* the @p height with the current @p y coodinate of the rectangle. * the @p height with the current @p y coodinate of the rectangle.
@ -266,7 +266,7 @@ static inline int eina_rectangle_max_y(Eina_Rectangle *thiz) EINA_ARG_NO
/** /**
* *
* @brief Slices a rectangle vertically into two subrectangles starting from left edge * @brief Slices a rectangle vertically into two subrectangles starting from left edge.
* *
* @param thiz The rectangle to slice * @param thiz The rectangle to slice
* @param slice The sliced part of the rectangle * @param slice The sliced part of the rectangle
@ -340,7 +340,7 @@ static inline Eina_Bool eina_rectangle_width_cut(Eina_Rectangle *thiz, Eina_Re
static inline Eina_Bool eina_rectangle_height_cut(Eina_Rectangle *thiz, Eina_Rectangle *slice, Eina_Rectangle *remainder, int amount) EINA_ARG_NONNULL(1); static inline Eina_Bool eina_rectangle_height_cut(Eina_Rectangle *thiz, Eina_Rectangle *slice, Eina_Rectangle *remainder, int amount) EINA_ARG_NONNULL(1);
/** /**
* @brief Subtract two rectangles. * @brief Subtracts two rectangles.
* *
* @param thiz The minuend rectangle * @param thiz The minuend rectangle
* @param other The subtrahend rectangle * @param other The subtrahend rectangle
@ -352,7 +352,7 @@ static inline Eina_Bool eina_rectangle_height_cut(Eina_Rectangle *thiz, Eina_R
static inline Eina_Bool eina_rectangle_subtract(Eina_Rectangle *thiz, Eina_Rectangle *other, Eina_Rectangle out[4]) EINA_ARG_NONNULL(1); 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. * @brief Adds a rectangle in a new pool.
* *
* @param w The width of the rectangle. * @param w The width of the rectangle.
* @param h The height of the rectangle. * @param h The height of the rectangle.
@ -365,7 +365,7 @@ static inline Eina_Bool eina_rectangle_subtract(Eina_Rectangle *thiz, Eina_Rec
EAPI Eina_Rectangle_Pool *eina_rectangle_pool_new(int w, int h) EINA_MALLOC EINA_WARN_UNUSED_RESULT; EAPI Eina_Rectangle_Pool *eina_rectangle_pool_new(int w, int h) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
/** /**
* @brief Return the pool of the given rectangle. * @brief Returns the pool of the given rectangle.
* *
* @param rect The rectangle. * @param rect The rectangle.
* @return The pool of the given rectangle. * @return The pool of the given rectangle.
@ -376,7 +376,7 @@ EAPI Eina_Rectangle_Pool *eina_rectangle_pool_new(int w, int h) EINA_MALLOC EINA
EAPI Eina_Rectangle_Pool *eina_rectangle_pool_get(Eina_Rectangle *rect) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); 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. * @brief Returns the width and height of the given pool.
* *
* @param pool The pool. * @param pool The pool.
* @param w The returned width. * @param w The returned width.
@ -391,7 +391,7 @@ EAPI Eina_Rectangle_Pool *eina_rectangle_pool_get(Eina_Rectangle *rect) EINA_WAR
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 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 Get the data from the given pool. * @brief Gets the data from the given pool.
* *
* @param pool The pool. * @param pool The pool.
* @return The returned data. * @return The returned data.
@ -403,7 +403,7 @@ EAPI Eina_Bool eina_rectangle_pool_geometry_get(Eina_Rectangle_Pool *
EAPI void *eina_rectangle_pool_data_get(Eina_Rectangle_Pool *pool) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); 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. * @brief Sets the data to the given pool.
* *
* @param pool The pool. * @param pool The pool.
* @param data The data to set. * @param data The data to set.
@ -414,7 +414,7 @@ EAPI void *eina_rectangle_pool_data_get(Eina_Rectangle_Pool *pool
EAPI void eina_rectangle_pool_data_set(Eina_Rectangle_Pool *pool, const void *data) EINA_ARG_NONNULL(1); EAPI void eina_rectangle_pool_data_set(Eina_Rectangle_Pool *pool, const void *data) EINA_ARG_NONNULL(1);
/** /**
* @brief Free the given pool. * @brief Frees the given pool.
* *
* @param pool The pool to free. * @param pool The pool to free.
* *
@ -424,7 +424,7 @@ EAPI void eina_rectangle_pool_data_set(Eina_Rectangle_Pool *pool
EAPI void eina_rectangle_pool_free(Eina_Rectangle_Pool *pool) EINA_ARG_NONNULL(1); EAPI void eina_rectangle_pool_free(Eina_Rectangle_Pool *pool) EINA_ARG_NONNULL(1);
/** /**
* @brief Return the number of rectangles in the given pool. * @brief Returns the number of rectangles in the given pool.
* *
* @param pool The pool. * @param pool The pool.
* @return The number of rectangles in the pool. * @return The number of rectangles in the pool.
@ -434,7 +434,7 @@ EAPI void eina_rectangle_pool_free(Eina_Rectangle_Pool *pool) EI
EAPI int eina_rectangle_pool_count(Eina_Rectangle_Pool *pool) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; 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. * @brief Requests a rectangle of given size in the given pool.
* *
* @param pool The pool. * @param pool The pool.
* @param w The width of the rectangle to request. * @param w The width of the rectangle to request.
@ -451,7 +451,7 @@ EAPI int eina_rectangle_pool_count(Eina_Rectangle_Pool *pool) E
EAPI Eina_Rectangle *eina_rectangle_pool_request(Eina_Rectangle_Pool *pool, int w, int h) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); 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.
* *
* @param rect The rectangle to remove from the pool. * @param rect The rectangle to remove from the pool.
* *
@ -463,7 +463,7 @@ EAPI void eina_rectangle_pool_release(Eina_Rectangle *rect) EINA
/** /**
* @def EINA_RECTANGLE_SET * @def EINA_RECTANGLE_SET
* @brief Macro to set the values of a #Eina_Rectangle. * @brief Definition for the macro to set the values of a #Eina_Rectangle.
* *
* @param Rectangle The rectangle to set the values. * @param Rectangle The rectangle to set the values.
* @param X The X coordinate of the top left corner of the rectangle. * @param X The X coordinate of the top left corner of the rectangle.
@ -485,7 +485,7 @@ EAPI void eina_rectangle_pool_release(Eina_Rectangle *rect) EINA
/** /**
* @brief Create a new rectangle. * @brief Creates a new rectangle.
* *
* @param x The X coordinate of the top left corner of the 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 y The Y coordinate of the top left corner of the rectangle.
@ -496,12 +496,12 @@ EAPI void eina_rectangle_pool_release(Eina_Rectangle *rect) EINA
* This function creates a rectangle which top left corner has the * 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 * 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 * 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. * function returns a new rectangle on success, @c NULL otherwise.
*/ */
EAPI Eina_Rectangle *eina_rectangle_new(int x, int y, int w, int h) EINA_MALLOC EINA_WARN_UNUSED_RESULT; 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. * @param rect The rectangle to free.
* *
@ -521,10 +521,10 @@ EAPI void eina_rectangle_free(Eina_Rectangle *rect) EINA_ARG_NONNULL(
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);
/** /**
* @brief calculate where rect2 is outside of rect1 * @brief calculates where rect2 is outside of rect1.
* *
* @param rect1 the rect to use as anchor * @param rect1 The rect to use as anchor
* @param rect2 the rect to look for outside positions * @param rect2 The rect to look for outside positions
* *
* @return A or'ed map of Eina_Rectangle_Outside values * @return A or'ed map of Eina_Rectangle_Outside values
* @since 1.19 * @since 1.19

112
src/lib/eina/eina_simple_xml_parser.h
View File

@ -219,14 +219,14 @@ typedef Eina_Bool (*Eina_Simple_XML_Attribute_Cb)(void *data, const char *key, c
/** /**
* Parse a section of XML string text * @brief Parses a section of XML string text
* *
* @param buf the input string. May not contain \0 terminator. * @param buf The input string. May not contain \0 terminator.
* @param buflen the input string size. * @param buflen The input string size.
* @param strip whenever this parser should strip leading and trailing * @param strip Whenever this parser should strip leading and trailing
* whitespace. These whitespace will still be issued, but as type * whitespace. These whitespace will still be issued, but as type
* #EINA_SIMPLE_XML_IGNORED. * #EINA_SIMPLE_XML_IGNORED.
* @param func what to call back while parse to do some action. The * @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 * first parameter is the given user @a data, the second is the
* token type, the third is the pointer to content start (it's * token type, the third is the pointer to content start (it's
* not a NULL terminated string!), the forth is where this * not a NULL terminated string!), the forth is where this
@ -234,9 +234,9 @@ typedef Eina_Bool (*Eina_Simple_XML_Attribute_Cb)(void *data, const char *key, c
* start, for instance "<!DOCTYPE value>" the offset points at * start, for instance "<!DOCTYPE value>" the offset points at
* "value"), the fifth is the size of the content. Whenever this * "value"), the fifth is the size of the content. Whenever this
* function return #EINA_FALSE the parser will abort. * function return #EINA_FALSE the parser will abort.
* @param data what to give as context to @a func. * @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 * @return #EINA_TRUE on success, or #EINA_FALSE if it was aborted by user or
* parsing error. * parsing error.
*/ */
EAPI Eina_Bool eina_simple_xml_parse(const char *buf, unsigned buflen, EAPI Eina_Bool eina_simple_xml_parse(const char *buf, unsigned buflen,
@ -245,11 +245,11 @@ EAPI Eina_Bool eina_simple_xml_parse(const char *buf, unsigned buflen,
/** /**
* Given the contents of a tag, find where the attributes start. * @brief Given the contents of a tag, find where the attributes start.
* *
* @param buf the input string. May not contain \0 terminator. * @param buf The input string. May not contain \0 terminator.
* @param buflen the input string size. * @param buflen The input string size.
* @return pointer to the start of attributes, it can be used * @return Pointer to the start of attributes, it can be used
* to feed eina_simple_xml_attributes_parse(). @c NULL is returned * to feed eina_simple_xml_attributes_parse(). @c NULL is returned
* if no attributes were found. * if no attributes were found.
* *
@ -260,25 +260,25 @@ EAPI Eina_Bool eina_simple_xml_parse(const char *buf, unsigned buflen,
EAPI const char * eina_simple_xml_tag_attributes_find(const char *buf, unsigned buflen); 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. * @brief Given a buffer with xml attributes, parse them to key=value pairs.
* *
* @param buf the input string. May not contain \0 terminator. * @param buf The input string. May not contain \0 terminator.
* @param buflen the input string size. * @param buflen The input string size.
* @param func what to call back while parse to do some action. The * @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 * first parameter is the given user @a data, the second is the
* key (null-terminated) and the last is the value (null * key (null-terminated) and the last is the value (null
* terminated). These strings should not be modified and * terminated). These strings should not be modified and
* reference is just valid until the function return. * reference is just valid until the function return.
* @param data data to pass to the callback function. * @param data Data to pass to the callback function.
* *
* @return #EINA_TRUE on success or #EINA_FALSE if it was aborted by user or * @return #EINA_TRUE on success, or #EINA_FALSE if it was aborted by user or
* parsing error. * parsing error.
*/ */
EAPI Eina_Bool eina_simple_xml_attributes_parse(const char *buf, unsigned buflen, EAPI Eina_Bool eina_simple_xml_attributes_parse(const char *buf, unsigned buflen,
Eina_Simple_XML_Attribute_Cb func, const void *data); Eina_Simple_XML_Attribute_Cb func, const void *data);
/** /**
* Given a buffer with the xml value of an attributes, parse them to key:value pairs. * @brief Given a buffer with the xml value of an attributes, parse them to key:value pairs.
* *
* @param buf the input string. Need to contain \0 terminator. * @param buf the input string. Need to contain \0 terminator.
* @param func what to call back while parse to do some action. The * @param func what to call back while parse to do some action. The
@ -297,9 +297,9 @@ EAPI Eina_Bool
eina_simple_xml_attribute_w3c_parse(const char *buf, Eina_Simple_XML_Attribute_Cb func, const void *data); eina_simple_xml_attribute_w3c_parse(const char *buf, Eina_Simple_XML_Attribute_Cb func, const void *data);
/** /**
* Create (and append) new attribute to tag. * @brief Creates (and appends) new attribute to tag.
* *
* @param parent if provided, will be set in the resulting structure * @param parent If provided, will be set in the resulting structure
* as well as the attribute will be appended to attributes list. * as well as the attribute will be appended to attributes list.
* @param key Null-terminated string. Must not be @c NULL. * @param key Null-terminated string. Must not be @c NULL.
* @param value Null-terminated string. If @c NULL, the empty string will be used. * @param value Null-terminated string. If @c NULL, the empty string will be used.
@ -311,7 +311,7 @@ eina_simple_xml_attribute_w3c_parse(const char *buf, Eina_Simple_XML_Attribute_C
EAPI Eina_Simple_XML_Attribute * eina_simple_xml_attribute_new(Eina_Simple_XML_Node_Tag *parent, const char *key, const char *value); 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 attribute from parent and delete it.
* *
* @param attr attribute to release memory. * @param attr attribute to release memory.
*/ */
@ -319,9 +319,9 @@ 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 new tag. If parent is provided, it is automatically appended.
* *
* @param parent if provided, will be set in the resulting structure * @param parent If provided, will be set in the resulting structure
* as well as the tag will be appended to children list. * as well as the tag will be appended to children list.
* @param name Null-terminated string. Must not be @c NULL. * @param name Null-terminated string. Must not be @c NULL.
* *
@ -332,7 +332,7 @@ EAPI void eina_simple_xml_attribute_free(Eina_Simple_XML_Attribute *attr);
EAPI Eina_Simple_XML_Node_Tag * eina_simple_xml_node_tag_new(Eina_Simple_XML_Node_Tag *parent, const char *name); 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 tag from parent and delete it.
* *
* @param tag to release memory. * @param tag to release memory.
*/ */
@ -340,12 +340,12 @@ 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 parent is provided, it is automatically appended.
* *
* @param parent if provided, will be set in the resulting structure * @param parent If provided, will be set in the resulting structure
* as well as the data will be appended to children list. * as well as the data will be appended to children list.
* @param contents String to be used. Must not be @c NULL. * @param contents String to be used. Must not be @c NULL.
* @param length size in bytes of @a contents. * @param length Size in bytes of @a contents.
* *
* @return Newly allocated memory or NULL on error. This memory should be * @return Newly allocated memory or NULL on error. This memory should be
* released with eina_simple_xml_node_data_free() or indirectly * released with eina_simple_xml_node_data_free() or indirectly
@ -354,7 +354,7 @@ EAPI void eina_simple_xml_node_tag_free(Eina_Simple_XML_Node_Tag *tag);
EAPI Eina_Simple_XML_Node_Data * eina_simple_xml_node_data_new(Eina_Simple_XML_Node_Tag *parent, const char *contents, size_t length); 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 parent and delete it.
* *
* @param node to release memory. * @param node to release memory.
*/ */
@ -362,12 +362,12 @@ 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 parent is provided, it is automatically appended.
* *
* @param parent if provided, will be set in the resulting structure * @param parent If provided, will be set in the resulting structure
* as well as the cdata will be appended to children list. * as well as the cdata will be appended to children list.
* @param contents String to be used. Must not be @c NULL. * @param contents String to be used. Must not be @c NULL.
* @param length size in bytes of @a content. * @param length Size in bytes of @a content.
* *
* @return Newly allocated memory or @c NULL on error. This memory should be * @return Newly allocated memory or @c NULL on error. This memory should be
* released with eina_simple_xml_node_cdata_free() or indirectly * released with eina_simple_xml_node_cdata_free() or indirectly
@ -376,7 +376,7 @@ EAPI void eina_simple_xml_node_data_free(Eina_Simple_XML_Node_Data *node);
EAPI Eina_Simple_XML_Node_CData * eina_simple_xml_node_cdata_new(Eina_Simple_XML_Node_Tag *parent, const char *contents, size_t length); 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 parent and delete it.
* *
* @param node to release memory. * @param node to release memory.
*/ */
@ -384,9 +384,9 @@ 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 new doctype child. If parent is provided, it is automatically appended.
* *
* @param parent if provided, will be set in the resulting structure * @param parent If provided, will be set in the resulting structure
* as well as the doctype child will be appended to children list. * as well as the doctype child will be appended to children list.
* @param contents String to be used. Must not be @c NULL. * @param contents String to be used. Must not be @c NULL.
* @param length size in bytes of @a content. * @param length size in bytes of @a content.
@ -400,7 +400,7 @@ EAPI void eina_simple_xml_node_cdata_free(Eina_Simple_XML_Node_Data *node);
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); 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. * @brief Removes doctype child from parent and delete it.
* *
* @param node to release memory. * @param node to release memory.
* *
@ -410,12 +410,12 @@ EAPI void eina_simple_xml_node_doctype_child_free(Eina_Simple_XML_Node_Data *nod
/** /**
* Create new processing. If parent is provided, it is automatically appended. * @brief Creates new processing. If parent is provided, it is automatically appended.
* *
* @param parent if provided, will be set in the resulting structure * @param parent If provided, will be set in the resulting structure
* as well as the processing will be appended to children list. * as well as the processing will be appended to children list.
* @param contents String to be used. Must not be @c NULL. * @param contents String to be used. Must not be @c NULL.
* @param length size in bytes of @a contents. * @param length Size in bytes of @a contents.
* *
* @return Newly allocated memory or @c NULL on error. This memory should be * @return Newly allocated memory or @c NULL on error. This memory should be
* released with eina_simple_xml_node_processing_free() or indirectly * released with eina_simple_xml_node_processing_free() or indirectly
@ -424,7 +424,7 @@ EAPI void eina_simple_xml_node_doctype_child_free(Eina_Simple_XML_Node_Data *nod
EAPI Eina_Simple_XML_Node_Processing * eina_simple_xml_node_processing_new(Eina_Simple_XML_Node_Tag *parent, const char *contents, size_t length); 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 parent and delete it.
* *
* @param node processing to release memory. * @param node processing to release memory.
*/ */
@ -432,12 +432,12 @@ 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 new doctype. If parent is provided, it is automatically appended.
* *
* @param parent if provided, will be set in the resulting structure * @param parent If provided, will be set in the resulting structure
* as well as the doctype will be appended to children list. * as well as the doctype will be appended to children list.
* @param contents String to be used. Must not be @c NULL. * @param contents String to be used. Must not be @c NULL.
* @param length size in bytes of @a contents. * @param length Size in bytes of @a contents.
* *
* @return Newly allocated memory or @c NULL on error. This memory should be * @return Newly allocated memory or @c NULL on error. This memory should be
* released with eina_simple_xml_node_doctype_free() or indirectly * released with eina_simple_xml_node_doctype_free() or indirectly
@ -446,7 +446,7 @@ EAPI void eina_simple_xml_node_processing_free(Eina_Simple_XML_Node_Data *node);
EAPI Eina_Simple_XML_Node_Doctype * eina_simple_xml_node_doctype_new(Eina_Simple_XML_Node_Tag *parent, const char *contents, size_t length); 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 doctype from parent and delete it.
* *
* @param node doctype to release memory. * @param node doctype to release memory.
*/ */
@ -454,12 +454,12 @@ 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 new comment. If parent is provided, it is automatically appended.
* *
* @param parent if provided, will be set in the resulting structure * @param parent If provided, will be set in the resulting structure
* as well as the comment will be appended to children list. * as well as the comment will be appended to children list.
* @param contents String to be used. Must not be @c NULL. * @param contents String to be used. Must not be @c NULL.
* @param length size in bytes of @a contents. * @param length Size in bytes of @a contents.
* *
* @return Newly allocated memory or @c NULL on error. This memory should be * @return Newly allocated memory or @c NULL on error. This memory should be
* released with eina_simple_xml_node_comment_free() or indirectly * released with eina_simple_xml_node_comment_free() or indirectly
@ -468,7 +468,7 @@ EAPI void eina_simple_xml_node_doctype_free(Eina_Simple_XML_Node_Data *node);
EAPI Eina_Simple_XML_Node_Comment * eina_simple_xml_node_comment_new(Eina_Simple_XML_Node_Tag *parent, const char *contents, size_t length); 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 comment from parent and delete it.
* *
* @param node comment to release memory. * @param node comment to release memory.
*/ */
@ -476,11 +476,11 @@ 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 a XML node tree based on the given string.
* *
* @param buf the input string. May not contain \0 terminator. * @param buf The input string. May not contain \0 terminator.
* @param buflen the input string size. * @param buflen The input string size.
* @param strip whenever this parser should strip leading and trailing * @param strip Whenever this parser should strip leading and trailing
* whitespace. * whitespace.
* *
* @return Document root with children tags, or @c NULL on errors. * @return Document root with children tags, or @c NULL on errors.
@ -490,19 +490,19 @@ EAPI void eina_simple_xml_node_comment_free(Eina_Simple_XML_Node_Data *node);
EAPI Eina_Simple_XML_Node_Root * eina_simple_xml_node_load(const char *buf, unsigned buflen, Eina_Bool strip); 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 node tree build with eina_simple_xml_node_load()
* *
* @param root memory returned by eina_simple_xml_node_load() * @param root Memory returned by eina_simple_xml_node_load()
*/ */
EAPI void eina_simple_xml_node_root_free(Eina_Simple_XML_Node_Root *root); 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 a XML string.
* *
* @param node the base node to convert. * @param node The base node to convert.
* @param indent Indentation string, or @c NULL to disable it. * @param indent Indentation string, or @c NULL to disable it.
* *
* @return @c NULL on errors or a newly allocated string on success. * @return @c NULL on errors, or a newly allocated string on success.
*/ */
EAPI char * eina_simple_xml_node_dump(Eina_Simple_XML_Node *node, const char *indent); EAPI char * eina_simple_xml_node_dump(Eina_Simple_XML_Node *node, const char *indent);

40
src/lib/eina/eina_str.h
View File

@ -55,7 +55,7 @@
/** /**
* @addtogroup Eina_String_Group String * @addtogroup Eina_String_Group String
* *
* @brief Provide useful functions for C string manipulation. * @brief Provides useful functions for C string manipulation.
* *
* This group of functions allow you to more easily manipulate strings, they * This group of functions allow you to more easily manipulate strings, they
* provide functionality not available through string.h. * provide functionality not available through string.h.
@ -83,7 +83,7 @@
/* strlcpy implementation for libc's lacking it */ /* strlcpy implementation for libc's lacking it */
/** /**
* @brief Copy a c-string to another. * @brief Copies a c-string to another.
* *
* @param dst The destination string. * @param dst The destination string.
* @param src The source string. * @param src The source string.
@ -103,7 +103,7 @@
EAPI size_t eina_strlcpy(char *dst, const char *src, size_t siz) EINA_ARG_NONNULL(1, 2); 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.
* *
* @param dst The destination string. * @param dst The destination string.
* @param src The source string. * @param src The source string.
@ -121,7 +121,7 @@ EAPI size_t eina_strlcat(char *dst, const char *src, size_t siz) EINA_A
/** /**
* @brief Check if the given string has the given prefix. * @brief Checks if the given string has the given prefix.
* *
* @param str The string to work with. * @param str The string to work with.
* @param prefix The prefix to check for. * @param prefix The prefix to check for.
@ -134,7 +134,7 @@ EAPI size_t eina_strlcat(char *dst, const char *src, size_t siz) EINA_A
EAPI Eina_Bool eina_str_has_prefix(const char *str, const char *prefix) EINA_PURE EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT; 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 Checks if the given string has the given suffix.
* *
* @param str The string to work with. * @param str The string to work with.
* @param suffix The suffix to check for. * @param suffix The suffix to check for.
@ -147,7 +147,7 @@ EAPI Eina_Bool eina_str_has_prefix(const char *str, const char *prefix) EI
EAPI Eina_Bool eina_str_has_suffix(const char *str, const char *suffix) EINA_PURE EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT; 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 Checks if the given string has the given extension.
* *
* @param str The string to work with. * @param str The string to work with.
* @param ext The extension to check for. * @param ext The extension to check for.
@ -159,7 +159,7 @@ EAPI Eina_Bool eina_str_has_suffix(const char *str, const char *suffix) EI
EAPI Eina_Bool eina_str_has_extension(const char *str, const char *ext) EINA_PURE EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT; 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. * @brief Splits a string using a delimiter.
* *
* @param string The string to split. * @param string The string to split.
* @param delimiter The string which specifies the places at which to split the string. * @param delimiter The string which specifies the places at which to split the string.
@ -185,7 +185,7 @@ EAPI Eina_Bool eina_str_has_extension(const char *str, const char *ext) EI
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; 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. * @brief Splits a string using a delimiter and returns number of elements.
* *
* @param string The string to split. * @param string The string to split.
* @param delimiter The string which specifies the places at which to split the string. * @param delimiter The string which specifies the places at which to split the string.
@ -219,15 +219,15 @@ EAPI char **eina_str_split_full(const char *string, const char *delimit
/** /**
* @brief Join two strings of known length. * @brief Joins two strings of known length.
* *
* @param dst The buffer to store the result. * @param dst The buffer to store the result.
* @param size Size (in byte) of the buffer. * @param size Size (in byte) of the buffer.
* @param sep The separator character to use. * @param sep The separator character to use.
* @param a First string to use, before @p sep. * @param a First string to use, before @p sep.
* @param a_len length of @p a. * @param a_len Length of @p a.
* @param b Second string to use, after @p sep. * @param b Second string to use, after @p sep.
* @param b_len length of @p b. * @param b_len Length of @p b.
* @return The number of characters printed. * @return The number of characters printed.
* *
* This function joins the strings @p a and @p b (in that order) and * This function joins the strings @p a and @p b (in that order) and
@ -248,7 +248,7 @@ 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.
* *
* @param enc_from Encoding to convert from. * @param enc_from Encoding to convert from.
* @param enc_to Encoding to convert to. * @param enc_to Encoding to convert to.
@ -267,7 +267,7 @@ EAPI size_t eina_str_join_len(char *dst, size_t size, char sep, const c
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); 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. * @brief Uses Iconv to convert a text string from one encoding to another.
* *
* @param enc_from Encoding to convert from. * @param enc_from Encoding to convert from.
* @param enc_to Encoding to convert to. * @param enc_to Encoding to convert to.
@ -288,7 +288,7 @@ EAPI char *eina_str_convert_len(const char *enc_from, const char *enc_
/** /**
* @brief Escape slashes, spaces and apostrophes in strings. * @brief Escapes slashes, spaces and apostrophes in strings.
* *
* @param str The string to escape. * @param str The string to escape.
* @return The escaped string. * @return The escaped string.
@ -303,7 +303,7 @@ EAPI char *eina_str_escape(const char *str) EINA_WARN_UNUSED_RESULT EI
/** /**
* @brief Lowercase all the characters in range [A-Z] in the given string. * @brief Lowercases all the characters in range [A-Z] in the given string.
* *
* @param str The string to lowercase. * @param str The string to lowercase.
* *
@ -314,7 +314,7 @@ EAPI char *eina_str_escape(const char *str) EINA_WARN_UNUSED_RESULT EI
EAPI void eina_str_tolower(char **str); 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 range [a-z] in the given string.
* *
* @param str The string to uppercase. * @param str The string to uppercase.
* *
@ -328,7 +328,7 @@ static inline size_t eina_str_join(char *dst, size_t size, char sep, const char
/** /**
* @def eina_str_join_static(dst, sep, a, b) * @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 store the result in a static buffer.
* *
* @param dst The buffer to store the result. * @param dst The buffer to store the result.
* @param sep The separator character to use. * @param sep The separator character to use.
@ -347,17 +347,17 @@ static inline size_t eina_str_join(char *dst, size_t size, char sep, const char
static inline size_t eina_strlen_bounded(const char *str, size_t maxlen) EINA_PURE EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); static inline size_t eina_strlen_bounded(const char *str, size_t maxlen) EINA_PURE EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
/** /**
* @brief memory duplication function with optional termination for strings * @brief Memory duplication function with optional termination for strings
* @param mem The memory to copy * @param mem The memory to copy
* @param size The size of @p mem * @param size The size of @p mem
* @param terminate If true, the returned memory will be nul terminated with '\0' * @param terminate If true, the returned memory will be nul terminated with '\0'
* @return the copied memory, must be freed * @return The copied memory, must be freed
* @since 1.13 * @since 1.13
*/ */
EAPI unsigned char *eina_memdup(unsigned char *mem, size_t size, Eina_Bool terminate); EAPI unsigned char *eina_memdup(unsigned char *mem, size_t size, Eina_Bool terminate);
/** /**
* @brief Create and update the buffer based on strftime output. * @brief Creates and update the buffer based on strftime output.
* *
* @param tm Pointer to a tm structure needed by strftime. * @param tm Pointer to a tm structure needed by strftime.
* @param format String containing format specifiers needed by strftime. * @param format String containing format specifiers needed by strftime.

128
src/lib/eina/eina_strbuf.h
View File

@ -66,7 +66,7 @@
typedef struct _Eina_Strbuf Eina_Strbuf; typedef struct _Eina_Strbuf Eina_Strbuf;
/** /**
* @brief Create a new string buffer. * @brief Creates a new string buffer.
* *
* @return Newly allocated string buffer instance. * @return Newly allocated string buffer instance.
* *
@ -80,11 +80,11 @@ typedef struct _Eina_Strbuf Eina_Strbuf;
EAPI Eina_Strbuf *eina_strbuf_new(void) EINA_MALLOC EINA_WARN_UNUSED_RESULT; 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 * @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 * 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. * @ref eina_strbuf_string_steal . The passed string must be malloced.
* *
* @param str the string to manage * @param str The string to manage
* @return Newly allocated string buffer instance. * @return Newly allocated string buffer instance.
* *
* This function creates a new string buffer. On error, @c NULL is * This function creates a new string buffer. On error, @c NULL is
@ -98,12 +98,12 @@ EAPI Eina_Strbuf *eina_strbuf_new(void) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
EAPI Eina_Strbuf *eina_strbuf_manage_new(char *str) EINA_MALLOC EINA_WARN_UNUSED_RESULT; 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 * @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 * 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. * @ref eina_strbuf_string_steal . The passed string must be malloced.
* *
* @param str the string to manage * @param str The string to manage
* @param length the length of the string. * @param length The length of the string.
* @return Newly allocated string buffer instance. * @return Newly allocated string buffer instance.
* *
* This function creates a new string buffer. On error, @c NULL is * This function creates a new string buffer. On error, @c NULL is
@ -115,12 +115,12 @@ EAPI Eina_Strbuf *eina_strbuf_manage_new(char *str) EINA_MALLOC EINA_WARN_UNUSED
EAPI Eina_Strbuf *eina_strbuf_manage_new_length(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 Create a new string buffer using the passed string. The passed * @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 * 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. * @ref eina_strbuf_string_steal . The passed string must be malloced.
* *
* @param str the string to manage * @param str The string to manage
* @param length the length of the string. * @param length The length of the string.
* @return Newly allocated string buffer instance. * @return Newly allocated string buffer instance.
* *
* This function creates a new string buffer. On error, @c NULL is * This function creates a new string buffer. On error, @c NULL is
@ -132,7 +132,7 @@ EAPI Eina_Strbuf *eina_strbuf_manage_new_length(char *str, size_t length) EINA_M
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_read_only_new_length(const 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. * @param buf The string buffer to free.
* *
@ -142,7 +142,7 @@ EAPI Eina_Strbuf *eina_strbuf_manage_read_only_new_length(const char *str, size_
EAPI void eina_strbuf_free(Eina_Strbuf *buf) EINA_ARG_NONNULL(1); EAPI void eina_strbuf_free(Eina_Strbuf *buf) EINA_ARG_NONNULL(1);
/** /**
* @brief Reset a string buffer. * @brief Resets a string buffer.
* *
* @param buf The string buffer to reset. * @param buf The string buffer to reset.
* *
@ -152,7 +152,7 @@ EAPI void eina_strbuf_free(Eina_Strbuf *buf) EINA_ARG_NONNULL(1);
EAPI void eina_strbuf_reset(Eina_Strbuf *buf) EINA_ARG_NONNULL(1); 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.
* *
* @param buf The string buffer to append to. * @param buf The string buffer to append to.
* @param str The string to append. * @param str The string to append.
@ -170,7 +170,7 @@ 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); 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 buf The string buffer to append to.
* @param str The string to append. * @param str The string to append.
@ -183,7 +183,7 @@ EAPI Eina_Bool eina_strbuf_append(Eina_Strbuf *buf, const char *str) EINA_ARG_NO
EAPI Eina_Bool eina_strbuf_append_escaped(Eina_Strbuf *buf, const char *str) EINA_ARG_NONNULL(1, 2); 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, * @brief Appends a string to a buffer, reallocating as necessary,
* limited by the given length. * limited by the given length.
* *
* @param buf The string buffer to append to. * @param buf The string buffer to append to.
@ -206,7 +206,7 @@ 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); 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.
* *
* @param buf The string buffer to append to. * @param buf The string buffer to append to.
* @param str The string to append. * @param str The string to append.
@ -241,7 +241,7 @@ EAPI Eina_Bool eina_strbuf_append_length(Eina_Strbuf *buf, const char *str, size
EAPI Eina_Bool eina_strbuf_append_slice(Eina_Strbuf *buf, const Eina_Slice slice) EINA_ARG_NONNULL(1); EAPI Eina_Bool eina_strbuf_append_slice(Eina_Strbuf *buf, const Eina_Slice slice) EINA_ARG_NONNULL(1);
/** /**
* @brief Append an Eina_Strbuf to a buffer, reallocating as necessary. * @brief Appends an Eina_Strbuf to a buffer, reallocating as necessary.
* *
* @param buf The string buffer to append to. * @param buf The string buffer to append to.
* @param data The string buffer to append. * @param data The string buffer to append.
@ -260,7 +260,7 @@ EAPI Eina_Bool eina_strbuf_append_slice(Eina_Strbuf *buf, const Eina_Slice slice
EAPI Eina_Bool eina_strbuf_append_buffer(Eina_Strbuf *buf, const Eina_Strbuf *data) EINA_ARG_NONNULL(1, 2); 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 * @brief Appends a character to a string buffer, reallocating as
* necessary. * necessary.
* *
* @param buf The string buffer to append to. * @param buf The string buffer to append to.
@ -273,7 +273,7 @@ EAPI Eina_Bool eina_strbuf_append_buffer(Eina_Strbuf *buf, const Eina_Strbuf *da
EAPI Eina_Bool eina_strbuf_append_char(Eina_Strbuf *buf, char c) EINA_ARG_NONNULL(1); 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.
* *
* @param buf The string buffer to append to. * @param buf The string buffer to append to.
* @param fmt The string to append. * @param fmt The string to append.
@ -288,7 +288,7 @@ EAPI Eina_Bool eina_strbuf_append_char(Eina_Strbuf *buf, char c) EINA_ARG_NONNUL
EAPI Eina_Bool eina_strbuf_append_printf(Eina_Strbuf *buf, const char *fmt, ...) EINA_ARG_NONNULL(1, 2) EINA_PRINTF(2, 3); 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.
* *
* @param buf The string buffer to append to. * @param buf The string buffer to append to.
* @param fmt The string to append. * @param fmt The string to append.
@ -300,7 +300,7 @@ EAPI Eina_Bool eina_strbuf_append_printf(Eina_Strbuf *buf, const char *fmt, ...)
EAPI Eina_Bool eina_strbuf_append_vprintf(Eina_Strbuf *buf, const char *fmt, va_list args) EINA_ARG_NONNULL(1, 2); 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 to a buffer, reallocating as necessary.
* *
* @param buf The string buffer to insert. * @param buf The string buffer to insert.
* @param str The string to insert. * @param str The string to insert.
@ -316,7 +316,7 @@ EAPI Eina_Bool eina_strbuf_append_vprintf(Eina_Strbuf *buf, const char *fmt, va_
EAPI Eina_Bool eina_strbuf_insert(Eina_Strbuf *buf, const char *str, size_t pos) EINA_ARG_NONNULL(1, 2); EAPI Eina_Bool eina_strbuf_insert(Eina_Strbuf *buf, const char *str, size_t pos) EINA_ARG_NONNULL(1, 2);
/** /**
* @brief Insert an escaped string to a buffer, reallocating as * @brief Inserts an escaped string to a buffer, reallocating as
* necessary. * necessary.
* *
* @param buf The string buffer to insert to. * @param buf The string buffer to insert to.
@ -331,7 +331,7 @@ EAPI Eina_Bool eina_strbuf_insert(Eina_Strbuf *buf, const char *str, size_t pos)
EAPI Eina_Bool eina_strbuf_insert_escaped(Eina_Strbuf *buf, const char *str, size_t pos) EINA_ARG_NONNULL(1, 2); EAPI Eina_Bool eina_strbuf_insert_escaped(Eina_Strbuf *buf, const char *str, size_t pos) EINA_ARG_NONNULL(1, 2);
/** /**
* @brief Insert a string to a buffer, reallocating as necessary. Limited by maxlen. * @brief Inserts a string to a buffer, reallocating as necessary. Limited by maxlen.
* *
* @param buf The string buffer to insert to. * @param buf The string buffer to insert to.
* @param str The string to insert. * @param str The string to insert.
@ -351,7 +351,7 @@ EAPI Eina_Bool eina_strbuf_insert_escaped(Eina_Strbuf *buf, const char *str, siz
EAPI Eina_Bool eina_strbuf_insert_n(Eina_Strbuf *buf, const char *str, size_t maxlen, size_t pos) EINA_ARG_NONNULL(1, 2); EAPI Eina_Bool eina_strbuf_insert_n(Eina_Strbuf *buf, const char *str, size_t maxlen, size_t pos) EINA_ARG_NONNULL(1, 2);
/** /**
* @brief Insert a string of exact length to a buffer, reallocating as necessary. * @brief Inserts a string of exact length to a buffer, reallocating as necessary.
* *
* @param buf The string buffer to insert to. * @param buf The string buffer to insert to.
* @param str The string to insert. * @param str The string to insert.
@ -389,7 +389,7 @@ EAPI Eina_Bool eina_strbuf_insert_length(Eina_Strbuf *buf, const char *str, size
EAPI Eina_Bool eina_strbuf_insert_slice(Eina_Strbuf *buf, const Eina_Slice slice, size_t pos) EINA_ARG_NONNULL(1); EAPI Eina_Bool eina_strbuf_insert_slice(Eina_Strbuf *buf, const Eina_Slice slice, size_t pos) EINA_ARG_NONNULL(1);
/** /**
* @brief Insert a character to a string buffer, reallocating as * @brief Inserts a character to a string buffer, reallocating as
* necessary. * necessary.
* *
* @param buf The string buffer to insert to. * @param buf The string buffer to insert to.
@ -404,7 +404,7 @@ EAPI Eina_Bool eina_strbuf_insert_slice(Eina_Strbuf *buf, const Eina_Slice slice
EAPI Eina_Bool eina_strbuf_insert_char(Eina_Strbuf *buf, char c, size_t pos) EINA_ARG_NONNULL(1); EAPI Eina_Bool eina_strbuf_insert_char(Eina_Strbuf *buf, char c, size_t pos) EINA_ARG_NONNULL(1);
/** /**
* @brief Insert a string to a buffer, reallocating as necessary. * @brief Inserts a string to a buffer, reallocating as necessary.
* *
* @param buf The string buffer to insert. * @param buf The string buffer to insert.
* @param fmt The string to insert. * @param fmt The string to insert.
@ -419,7 +419,7 @@ EAPI Eina_Bool eina_strbuf_insert_char(Eina_Strbuf *buf, char c, size_t pos) EIN
EAPI Eina_Bool eina_strbuf_insert_printf(Eina_Strbuf *buf, const char *fmt, size_t pos, ...) EINA_ARG_NONNULL(1, 2) EINA_PRINTF(2, 4); EAPI Eina_Bool eina_strbuf_insert_printf(Eina_Strbuf *buf, const char *fmt, size_t pos, ...) EINA_ARG_NONNULL(1, 2) EINA_PRINTF(2, 4);
/** /**
* @brief Insert a string to a buffer, reallocating as necessary. * @brief Inserts a string to a buffer, reallocating as necessary.
* *
* @param buf The string buffer to insert. * @param buf The string buffer to insert.
* @param fmt The string to insert. * @param fmt The string to insert.
@ -433,7 +433,7 @@ EAPI Eina_Bool eina_strbuf_insert_vprintf(Eina_Strbuf *buf, const char *fmt, siz
/** /**
* @def eina_strbuf_prepend(buf, str) * @def eina_strbuf_prepend(buf, str)
* @brief Prepend the given string to the given buffer * @brief Prepends the given string to the given buffer.
* *
* @param buf The string buffer to prepend to. * @param buf The string buffer to prepend to.
* @param str The string to prepend. * @param str The string to prepend.
@ -447,7 +447,7 @@ EAPI Eina_Bool eina_strbuf_insert_vprintf(Eina_Strbuf *buf, const char *fmt, siz
/** /**
* @def eina_strbuf_prepend_escaped(buf, str) * @def eina_strbuf_prepend_escaped(buf, str)
* @brief Prepend the given escaped string to the given buffer * @brief Prepends the given escaped string to the given buffer.
* *
* @param buf The string buffer to prepend to. * @param buf The string buffer to prepend to.
* @param str The string to prepend. * @param str The string to prepend.
@ -461,7 +461,7 @@ EAPI Eina_Bool eina_strbuf_insert_vprintf(Eina_Strbuf *buf, const char *fmt, siz
/** /**
* @def eina_strbuf_prepend_n(buf, str) * @def eina_strbuf_prepend_n(buf, str)
* @brief Prepend the given escaped string to the given buffer * @brief Prepends the given escaped string to the given buffer.
* *
* @param buf The string buffer to prepend to. * @param buf The string buffer to prepend to.
* @param str The string to prepend. * @param str The string to prepend.
@ -476,7 +476,7 @@ EAPI Eina_Bool eina_strbuf_insert_vprintf(Eina_Strbuf *buf, const char *fmt, siz
/** /**
* @def eina_strbuf_prepend_length(buf, str) * @def eina_strbuf_prepend_length(buf, str)
* @brief Prepend the given escaped string to the given buffer * @brief Prepends the given escaped string to the given buffer.
* *
* @param buf The string buffer to prepend to. * @param buf The string buffer to prepend to.
* @param str The string to prepend. * @param str The string to prepend.
@ -491,7 +491,7 @@ EAPI Eina_Bool eina_strbuf_insert_vprintf(Eina_Strbuf *buf, const char *fmt, siz
/** /**
* @def eina_strbuf_prepend_char(buf, str) * @def eina_strbuf_prepend_char(buf, str)
* @brief Prepend the given character to the given buffer * @brief Prepends the given character to the given buffer.
* *
* @param buf The string buffer to prepend to. * @param buf The string buffer to prepend to.
* @param c The character to prepend. * @param c The character to prepend.
@ -505,7 +505,7 @@ EAPI Eina_Bool eina_strbuf_insert_vprintf(Eina_Strbuf *buf, const char *fmt, siz
/** /**
* @def eina_strbuf_prepend_printf(buf, fmt, ...) * @def eina_strbuf_prepend_printf(buf, fmt, ...)
* @brief Prepend the given string to the given buffer * @brief Prepends the given string to the given buffer.
* *
* @param buf The string buffer to prepend to. * @param buf The string buffer to prepend to.
* @param fmt The string to prepend. * @param fmt The string to prepend.
@ -519,7 +519,7 @@ EAPI Eina_Bool eina_strbuf_insert_vprintf(Eina_Strbuf *buf, const char *fmt, siz
/** /**
* @def eina_strbuf_prepend_vprintf(buf, fmt, args) * @def eina_strbuf_prepend_vprintf(buf, fmt, args)
* @brief Prepend the given string to the given buffer * @brief Prepends the given string to the given buffer.
* *
* @param buf The string buffer to prepend to. * @param buf The string buffer to prepend to.
* @param fmt The string to prepend. * @param fmt The string to prepend.
@ -533,7 +533,7 @@ EAPI Eina_Bool eina_strbuf_insert_vprintf(Eina_Strbuf *buf, const char *fmt, siz
#define eina_strbuf_prepend_vprintf(buf, fmt, args) eina_strbuf_insert_vprintf(buf, fmt, 0, args) #define eina_strbuf_prepend_vprintf(buf, fmt, args) eina_strbuf_insert_vprintf(buf, fmt, 0, args)
/** /**
* @brief Remove a slice of the given string buffer. * @brief Removes a slice of the given string buffer.
* *
* @param buf The string buffer to remove a slice. * @param buf The string buffer to remove a slice.
* @param start The initial (inclusive) slice position to start * @param start The initial (inclusive) slice position to start
@ -550,7 +550,7 @@ EAPI Eina_Bool eina_strbuf_insert_vprintf(Eina_Strbuf *buf, const char *fmt, siz
EAPI Eina_Bool eina_strbuf_remove(Eina_Strbuf *buf, size_t start, size_t end) EINA_ARG_NONNULL(1); EAPI Eina_Bool eina_strbuf_remove(Eina_Strbuf *buf, size_t start, size_t end) EINA_ARG_NONNULL(1);
/** /**
* @brief Retrieve a pointer to the contents of a string buffer * @brief Retrieves a pointer to the contents of a string buffer.
* *
* @param buf The string buffer. * @param buf The string buffer.
* @return The current string in the string buffer. * @return The current string in the string buffer.
@ -566,7 +566,7 @@ EAPI Eina_Bool eina_strbuf_remove(Eina_Strbuf *buf, size_t start, size_t end) EI
EAPI const char *eina_strbuf_string_get(const Eina_Strbuf *buf) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; EAPI const char *eina_strbuf_string_get(const Eina_Strbuf *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. * @param buf The string buffer to steal.
* @return The current string in the string buffer. * @return The current string in the string buffer.
@ -581,7 +581,7 @@ EAPI const char *eina_strbuf_string_get(const Eina_Strbuf *buf) EINA_ARG_NONNULL
EAPI char *eina_strbuf_string_steal(Eina_Strbuf *buf) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); EAPI char *eina_strbuf_string_steal(Eina_Strbuf *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.
* *
* @param buf The string buffer to free the string of. * @param buf The string buffer to free the string of.
* *
@ -591,7 +591,7 @@ EAPI char *eina_strbuf_string_steal(Eina_Strbuf *buf) EINA_MALLOC EINA_WARN_UNUS
EAPI void eina_strbuf_string_free(Eina_Strbuf *buf) EINA_ARG_NONNULL(1); EAPI void eina_strbuf_string_free(Eina_Strbuf *buf) EINA_ARG_NONNULL(1);
/** /**
* @brief Retrieve the length of the string buffer content. * @brief Retrieves the length of the string buffer content.
* *
* @param buf The string buffer. * @param buf The string buffer.
* @return The current length of the string, in bytes. * @return The current length of the string, in bytes.
@ -602,11 +602,11 @@ EAPI size_t eina_strbuf_length_get(const Eina_Strbuf *buf) EINA_ARG_NONNULL(1
/** /**
* @brief Replace the n-th string with an other string. * @brief Replaces the n-th string with an other string.
* *
* @param buf The string buffer to work with. * @param buf The string buffer to work with.
* @param str The string to replace. * @param str The string to replace.
* @param with The replaceing string. * @param with The replacing string.
* @param n The number of the fitting string. * @param n The number of the fitting string.
* @return #EINA_TRUE on success, #EINA_FALSE on failure. * @return #EINA_TRUE on success, #EINA_FALSE on failure.
* *
@ -617,7 +617,7 @@ EAPI Eina_Bool eina_strbuf_replace(Eina_Strbuf *buf, const char *str, const char
/** /**
* @def eina_strbuf_replace_first(buf, str, with) * @def eina_strbuf_replace_first(buf, str, with)
* @brief Prepend the given character to the given buffer * @brief Prepends the given character to the given buffer.
* *
* @param buf The string buffer to work with. * @param buf The string buffer to work with.
* @param str The string to replace. * @param str The string to replace.
@ -632,11 +632,11 @@ EAPI Eina_Bool eina_strbuf_replace(Eina_Strbuf *buf, const char *str, const char
/** /**
* @brief Replace all strings with an other string. * @brief Replaces all strings with an other string.
* @param buf the string buffer to work with. * @param buf The string buffer to work with.
* @param str The string to replace. * @param str The string to replace.
* @param with The replaceing string. * @param with The replacing string.
* @return How often the string was replaced. * @return How often the string was replaced.
* *
* This function replaces all the occurrences of @p str in @p buf with * This function replaces all the occurrences of @p str in @p buf with
@ -646,36 +646,36 @@ EAPI Eina_Bool eina_strbuf_replace(Eina_Strbuf *buf, const char *str, const char
EAPI int eina_strbuf_replace_all(Eina_Strbuf *buf, const char *str, const char *with) EINA_ARG_NONNULL(1, 2, 3); EAPI int eina_strbuf_replace_all(Eina_Strbuf *buf, const char *str, const char *with) EINA_ARG_NONNULL(1, 2, 3);
/** /**
* @brief Trim the string buffer * @brief Trims the string buffer.
* @param buf the string buffer to work with. * @param buf The string buffer to work with.
* *
* This function skips whitespaces in the beginning and the end of the buffer. * This function skips whitespaces in the beginning and the end of the buffer.
*/ */
EAPI void eina_strbuf_trim(Eina_Strbuf *buf) EINA_ARG_NONNULL(1); EAPI void eina_strbuf_trim(Eina_Strbuf *buf) EINA_ARG_NONNULL(1);
/** /**
* @brief Left trim the string buffer * @brief Left trims the string buffer.
* @param buf the string buffer to work with. * @param buf The string buffer to work with.
* *
* This function skips whitespaces in the beginning of the buffer. * This function skips whitespaces in the beginning of the buffer.
*/ */
EAPI void eina_strbuf_ltrim(Eina_Strbuf *buf) EINA_ARG_NONNULL(1); EAPI void eina_strbuf_ltrim(Eina_Strbuf *buf) EINA_ARG_NONNULL(1);
/** /**
* @brief Right trim the string buffer * @brief Right trims the string buffer.
* @param buf the string buffer to work with. * @param buf The string buffer to work with.
* *
* This function skips whitespaces in the end of the buffer. * This function skips whitespaces in the end of the buffer.
*/ */
EAPI void eina_strbuf_rtrim(Eina_Strbuf *buf) EINA_ARG_NONNULL(1); EAPI void eina_strbuf_rtrim(Eina_Strbuf *buf) EINA_ARG_NONNULL(1);
/** /**
* @brief Convert the string to lower case. * @brief Converts the string to lower case.
* *
* @param buf the string buffer to work with. * @param buf The string buffer to work with.
* *
* This function converts all the characters in the strbuf to lower case. * This function converts all the characters in the strbuf to lower case.
* *
@ -684,13 +684,13 @@ EAPI void eina_strbuf_rtrim(Eina_Strbuf *buf) EINA_ARG_NONNULL(1);
EAPI void eina_strbuf_tolower(Eina_Strbuf *buf) EINA_ARG_NONNULL(1); EAPI void eina_strbuf_tolower(Eina_Strbuf *buf) EINA_ARG_NONNULL(1);
/** /**
* @brief Obtain substring from the src. * @brief Obtains substring from the src.
* *
* @param buf the src string. * @param buf The src string.
* @param pos the position in the source string from which the substring * @param pos The position in the source string from which the substring
* should be created. The first character is denoted by a * should be created. The first character is denoted by a
* value of 0 (not 1). * value of 0 (not 1).
* @param len the length from pos that should be copied to substring. * @param len The length from pos that should be copied to substring.
* *
* This function creates a Eina_Strbuf which is a substring of buf which * This function creates a Eina_Strbuf which is a substring of buf which
* is passed from pos position with len length. * is passed from pos position with len length.
@ -702,10 +702,10 @@ EAPI void eina_strbuf_tolower(Eina_Strbuf *buf) EINA_ARG_NONNULL(1);
EAPI Eina_Strbuf * eina_strbuf_substr_get(Eina_Strbuf *buf, size_t pos, size_t len) EINA_MALLOC EINA_WARN_UNUSED_RESULT; EAPI Eina_Strbuf * eina_strbuf_substr_get(Eina_Strbuf *buf, size_t pos, size_t len) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
/** /**
* @brief Get a read-only slice representing the current strbuf contents. * @brief Gets a read-only slice representing the current strbuf contents.
* *
* @param buf the source string. * @param buf The source string.
* @return a read-only slice for the current contents. It may become * @return A read-only slice for the current contents. It may become
* invalid as soon as the @a buf is changed. * invalid as soon as the @a buf is changed.
* *
* @since 1.19 * @since 1.19
@ -713,10 +713,10 @@ EAPI Eina_Strbuf * eina_strbuf_substr_get(Eina_Strbuf *buf, size_t pos, size_t l
EAPI Eina_Slice eina_strbuf_slice_get(const Eina_Strbuf *buf) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); EAPI Eina_Slice eina_strbuf_slice_get(const Eina_Strbuf *buf) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
/** /**
* @brief Get a read-write slice representing the current strbuf contents. * @brief Gets a read-write slice representing the current strbuf contents.
* *
* @param buf the source string. * @param buf The source string.
* @return a read-write slice for the current contents. It may become * @return A read-write slice for the current contents. It may become
* invalid as soon as the @a buf is changed with calls such as * invalid as soon as the @a buf is changed with calls such as
* eina_strbuf_append(), eina_strbuf_remove() * eina_strbuf_append(), eina_strbuf_remove()
* *
@ -726,9 +726,9 @@ EAPI Eina_Rw_Slice eina_strbuf_rw_slice_get(const Eina_Strbuf *buf) EINA_WARN_UN
/** /**
* @brief Get the string of the buffer and free the buffer * @brief Gets the string of the buffer and free the buffer
* *
* @param buf the buffer to get the string from and which will be freed * @param buf The buffer to get the string from and which will be freed
* *
* @return The string contained by bug. The caller must release the memory of the returned string by calling * @return The string contained by bug. The caller must release the memory of the returned string by calling
* free(). * free().

38
src/lib/eina/eina_stringshare.h
View File

@ -29,9 +29,9 @@
* *
* The above copyright notice and this permission notice shall be included in * The above copyright notice and this permission notice shall be included in
* all copies of the Software and its Copyright notices. In addition publicly * all copies of the Software and its Copyright notices. In addition publicly
* documented acknowledgment must be given that this software has been used if no * documented acknowledgement must be given that this software has been used if no
* source code of this software is made available publicly. This includes * source code of this software is made available publicly. This includes
* acknowledgments in either Copyright notices, Manuals, Publicity and Marketing * acknowledgements in either Copyright notices, Manuals, Publicity and Marketing
* documents or any documentation provided with any product containing this * documents or any documentation provided with any product containing this
* software. This License does not apply to any software that links to the * software. This License does not apply to any software that links to the
* libraries provided by this software (statically or dynamically), but only to * libraries provided by this software (statically or dynamically), but only to
@ -93,7 +93,7 @@
* value you should use eina_stringshare_replace(): * value you should use eina_stringshare_replace():
* @until printf * @until printf
* @warning @b Don't use eina_stringshare_del() followed by * @warning @b Don't use eina_stringshare_del() followed by
* eina_share_common_add(), under some circunstances you might end up deleting * eina_share_common_add(), under some circumstances you might end up deleting
* a shared string some other piece of code is using. * a shared string some other piece of code is using.
* *
* We created str but haven't deleted it yet, and while we called * We created str but haven't deleted it yet, and while we called
@ -175,12 +175,12 @@
typedef const char Eina_Stringshare; typedef const char Eina_Stringshare;
/** /**
* @brief Retrieve an instance of a string with a specific size for use in a * @brief Retrieves an instance of a string with a specific size for use in a
* program. * program.
* *
* @param str The string to retrieve an instance of. * @param str The string to retrieve an instance of.
* @param slen The string size (<= strlen(str)). * @param slen The string size (<= strlen(str)).
* @return A pointer to an instance of the string on success. * @return A pointer to an instance of the string on success,
* @c NULL on failure. * @c NULL on failure.
* *
* This function retrieves an instance of @p str. If @p str is * This function retrieves an instance of @p str. If @p str is
@ -197,10 +197,10 @@ typedef const char Eina_Stringshare;
EAPI Eina_Stringshare *eina_stringshare_add_length(const char *str, unsigned int slen) EINA_WARN_UNUSED_RESULT; EAPI Eina_Stringshare *eina_stringshare_add_length(const char *str, unsigned int slen) EINA_WARN_UNUSED_RESULT;
/** /**
* @brief Retrieve an instance of a string for use in a program. * @brief Retrieves an instance of a string for use in a program.
* *
* @param str The NULL-terminated string to retrieve an instance of. * @param str The NULL-terminated string to retrieve an instance of.
* @return A pointer to an instance of the string on success. * @return A pointer to an instance of the string on success,
* @c NULL on failure. * @c NULL on failure.
* *
* This function retrieves an instance of @p str. If @p str is * This function retrieves an instance of @p str. If @p str is
@ -217,11 +217,11 @@ EAPI Eina_Stringshare *eina_stringshare_add_length(const char *str, unsigned in
EAPI Eina_Stringshare *eina_stringshare_add(const char *str) EINA_WARN_UNUSED_RESULT; EAPI Eina_Stringshare *eina_stringshare_add(const char *str) EINA_WARN_UNUSED_RESULT;
/** /**
* @brief Retrieve an instance of a string for use in a program * @brief Retrieves an instance of a string for use in a program
* from a format string. * from a format string.
* *
* @param fmt The NULL-terminated format string to retrieve an instance of. * @param fmt The NULL-terminated format string to retrieve an instance of.
* @return A pointer to an instance of the string on success. * @return A pointer to an instance of the string on success,
* @c NULL on failure. * @c NULL on failure.
* *
* This function retrieves an instance of @p fmt. If @p fmt is * This function retrieves an instance of @p fmt. If @p fmt is
@ -238,12 +238,12 @@ EAPI Eina_Stringshare *eina_stringshare_add(const char *str) EINA_WARN_UNUSED_R
EAPI Eina_Stringshare *eina_stringshare_printf(const char *fmt, ...) EINA_WARN_UNUSED_RESULT EINA_PRINTF(1, 2); EAPI Eina_Stringshare *eina_stringshare_printf(const char *fmt, ...) EINA_WARN_UNUSED_RESULT EINA_PRINTF(1, 2);
/** /**
* @brief Retrieve an instance of a string for use in a program * @brief Retrieves an instance of a string for use in a program
* from a format string. * from a format string.
* *
* @param fmt The NULL-terminated format string to retrieve an instance of. * @param fmt The NULL-terminated format string to retrieve an instance of.
* @param args The va_args for @p fmt * @param args The va_args for @p fmt
* @return A pointer to an instance of the string on success. * @return A pointer to an instance of the string on success,
* @c NULL on failure. * @c NULL on failure.
* *
* This function retrieves an instance of @p fmt with @p args. If @p fmt is * This function retrieves an instance of @p fmt with @p args. If @p fmt is
@ -260,11 +260,11 @@ EAPI Eina_Stringshare *eina_stringshare_printf(const char *fmt, ...) EINA_WARN_
EAPI Eina_Stringshare *eina_stringshare_vprintf(const char *fmt, va_list args) EINA_WARN_UNUSED_RESULT; EAPI Eina_Stringshare *eina_stringshare_vprintf(const char *fmt, va_list args) EINA_WARN_UNUSED_RESULT;
/** /**
* @brief Retrieve an instance of a string for use in a program * @brief Retrieves an instance of a string for use in a program
* from a format string with size limitation. * from a format string with size limitation.
* @param len The length of the format string to use * @param len The length of the format string to use
* @param fmt The format string to retrieve an instance of. * @param fmt The format string to retrieve an instance of.
* @return A pointer to an instance of the string on success. * @return A pointer to an instance of the string on success,
* @c NULL on failure. * @c NULL on failure.
* *
* This function retrieves an instance of @p fmt limited by @p len. If @p fmt is * This function retrieves an instance of @p fmt limited by @p len. If @p fmt is
@ -283,7 +283,7 @@ EAPI Eina_Stringshare *eina_stringshare_nprintf(unsigned int len, const char *f
* Increment references of the given shared string. * Increment references of the given shared string.
* *
* @param str The shared string. * @param str The shared string.
* @return A pointer to an instance of the string on success. * @return A pointer to an instance of the string on success,
* @c NULL on failure. * @c NULL on failure.
* *
* This is similar to eina_share_common_add(), but it's faster since it will * This is similar to eina_share_common_add(), but it's faster since it will
@ -296,9 +296,9 @@ EAPI Eina_Stringshare *eina_stringshare_nprintf(unsigned int len, const char *f
EAPI Eina_Stringshare *eina_stringshare_ref(Eina_Stringshare *str); EAPI Eina_Stringshare *eina_stringshare_ref(Eina_Stringshare *str);
/** /**
* @brief Note that the given string has lost an instance. * @brief Notes that the given string has lost an instance.
* *
* @param str string The given string. * @param str String the given string.
* *
* This function decreases the reference counter associated to @p str * This function decreases the reference counter associated to @p str
* if it exists. If that counter reaches 0, the memory associated to * if it exists. If that counter reaches 0, the memory associated to
@ -311,9 +311,9 @@ EAPI Eina_Stringshare *eina_stringshare_ref(Eina_Stringshare *str);
EAPI void eina_stringshare_del(Eina_Stringshare *str); EAPI void eina_stringshare_del(Eina_Stringshare *str);
/** /**
* @brief Note that the given string @b must be shared. * @brief Notes that the given string @b must be shared.
* *
* @param str the shared string to know the length. It is safe to * @param str The shared string to know the length. It is safe to
* give @c NULL, in that case @c 0 is returned. * give @c NULL, in that case @c 0 is returned.
* @return The length of a shared string. * @return The length of a shared string.
* *
@ -326,7 +326,7 @@ EAPI void eina_stringshare_del(Eina_Stringshare *str);
EAPI int eina_stringshare_strlen(Eina_Stringshare *str) EINA_PURE EINA_WARN_UNUSED_RESULT; EAPI int eina_stringshare_strlen(Eina_Stringshare *str) EINA_PURE EINA_WARN_UNUSED_RESULT;
/** /**
* @brief Dump the contents of the share_common. * @brief Dumps the contents of the share_common.
* *
* This function dumps all strings in the share_common to stdout with a * This function dumps all strings in the share_common to stdout with a
* DDD: prefix per line and a memory usage summary. * DDD: prefix per line and a memory usage summary.

34
src/lib/eina/eina_thread.h
View File

@ -34,7 +34,7 @@
/** /**
* @defgroup Eina_Thread_Group Thread * @defgroup Eina_Thread_Group Thread
* *
* Abstracts platform threads, providing an uniform API. It's modeled * Abstracts platform threads, providing an uniform API. It's modelled
* after POSIX THREADS (pthreads), on Linux they are almost 1:1 * after POSIX THREADS (pthreads), on Linux they are almost 1:1
* mapping. * mapping.
* *
@ -69,14 +69,14 @@ typedef enum _Eina_Thread_Priority
} Eina_Thread_Priority; } Eina_Thread_Priority;
/** /**
* Return identifier of the current thread. * @brief Returns identifier of the current thread.
* @return identifier of current thread. * @return identifier of current thread.
* @since 1.8 * @since 1.8
*/ */
EAPI Eina_Thread eina_thread_self(void) EINA_WARN_UNUSED_RESULT; EAPI Eina_Thread eina_thread_self(void) EINA_WARN_UNUSED_RESULT;
/** /**
* Check if two thread identifiers are the same. * @brief Checks if two thread identifiers are the same.
* @param t1 first thread identifier to compare. * @param t1 first thread identifier to compare.
* @param t2 second thread identifier to compare. * @param t2 second thread identifier to compare.
* @return #EINA_TRUE if they are equal, #EINA_FALSE otherwise. * @return #EINA_TRUE if they are equal, #EINA_FALSE otherwise.
@ -85,7 +85,7 @@ EAPI Eina_Thread eina_thread_self(void) EINA_WARN_UNUSED_RESULT;
EAPI Eina_Bool eina_thread_equal(Eina_Thread t1, Eina_Thread t2) EINA_WARN_UNUSED_RESULT; EAPI Eina_Bool eina_thread_equal(Eina_Thread t1, Eina_Thread t2) EINA_WARN_UNUSED_RESULT;
/** /**
* Create a new thread, setting its priority and affinity. * @brief Creates a new thread, setting its priority and affinity.
* *
* @param t[out] where to return the thread identifier. Must @b not be @c NULL. * @param t[out] where to return the thread identifier. Must @b not be @c NULL.
* @param prio thread priority to use, usually #EINA_THREAD_BACKGROUND * @param prio thread priority to use, usually #EINA_THREAD_BACKGROUND
@ -100,7 +100,7 @@ EAPI Eina_Bool eina_thread_create(Eina_Thread *t,
Eina_Thread_Cb func, const void *data) EINA_ARG_NONNULL(1, 4) EINA_WARN_UNUSED_RESULT; Eina_Thread_Cb func, const void *data) EINA_ARG_NONNULL(1, 4) EINA_WARN_UNUSED_RESULT;
/** /**
* The return value of eina_thread_join() if it was canceled with * @brief The return value of eina_thread_join() if it was canceled with
* eina_thread_cancel(). * eina_thread_cancel().
* *
* A thread must be explicitly flagged as cancellable with * A thread must be explicitly flagged as cancellable with
@ -114,7 +114,7 @@ EAPI Eina_Bool eina_thread_create(Eina_Thread *t,
EAPI extern const void *EINA_THREAD_JOIN_CANCELED; EAPI extern const void *EINA_THREAD_JOIN_CANCELED;
/** /**
* Join a currently running thread, waiting until it finishes. * @brief Joins a currently running thread, waiting until it finishes.
* *
* This function will block the current thread until @a t * This function will block the current thread until @a t
* finishes. The returned value is the one returned by @a t @c func() * finishes. The returned value is the one returned by @a t @c func()
@ -131,11 +131,11 @@ EAPI extern const void *EINA_THREAD_JOIN_CANCELED;
EAPI void *eina_thread_join(Eina_Thread t); EAPI void *eina_thread_join(Eina_Thread t);
/** /**
* Set the name of a given thread for debugging purposes. * @brief Sets the name of a given thread for debugging purposes.
* *
* This maps to the pthread_setname_np() GNU extension or similar * This maps to the pthread_setname_np() GNU extension or similar
* if available. The name may be limited in size (possibly 16 * if available. The name may be limited in size (possibly 16
* characters including the nul byte terminator). This is useful * characters including the null byte terminator). This is useful
* for debugging to name a thread so external tools can display a * for debugging to name a thread so external tools can display a
* meaningful name attached to the thread. * meaningful name attached to the thread.
* *
@ -148,7 +148,7 @@ EAPI void *eina_thread_join(Eina_Thread t);
EAPI Eina_Bool eina_thread_name_set(Eina_Thread t, const char *name); EAPI Eina_Bool eina_thread_name_set(Eina_Thread t, const char *name);
/** /**
* Attempt to cancel a running thread. * @brief Attempts to cancel a running thread.
* *
* This function sends a cancellation request to the thread, however * This function sends a cancellation request to the thread, however
* that request is only fulfilled if the thread is cancellable * that request is only fulfilled if the thread is cancellable
@ -160,7 +160,7 @@ EAPI Eina_Bool eina_thread_name_set(Eina_Thread t, const char *name);
* A thread that was canceled will return EINA_THREAD_JOIN_CANCELED * A thread that was canceled will return EINA_THREAD_JOIN_CANCELED
* when eina_thread_join() is called. * when eina_thread_join() is called.
* *
* @param t thread to cancel. * @param t Thread to cancel.
* *
* @return EINA_FALSE if thread was not running, EINA_TRUE * @return EINA_FALSE if thread was not running, EINA_TRUE
* otherwise. Note that if a thread is not cancellable and it * otherwise. Note that if a thread is not cancellable and it
@ -171,7 +171,7 @@ EAPI Eina_Bool eina_thread_name_set(Eina_Thread t, const char *name);
EAPI Eina_Bool eina_thread_cancel(Eina_Thread t); EAPI Eina_Bool eina_thread_cancel(Eina_Thread t);
/** /**
* Enable or disable if the current thread can be canceled. * @brief Enables or disables if the current thread can be canceled.
* *
* By default eina_thread_create() will return a thread with * By default eina_thread_create() will return a thread with
* cancellation disabled. One can enable the cancellation by using * cancellation disabled. One can enable the cancellation by using
@ -189,10 +189,10 @@ EAPI Eina_Bool eina_thread_cancel(Eina_Thread t);
* or the helper function eina_thread_cancellable_run() which does the * or the helper function eina_thread_cancellable_run() which does the
* pair for you. * pair for you.
* *
* @param cancellable if EINA_TRUE, this thread will be accept * @param cancellable If EINA_TRUE, this thread will be accept
* cancellation requests. If EINA_FALSE -- the default, it will * cancellation requests. If EINA_FALSE -- the default, it will
* ignore cancellation requests. * ignore cancellation requests.
* @param was_cancellable if non-NULL, will return the previous state, * @param was_cancellable If non-NULL, will return the previous state,
* shall you want to restore. * shall you want to restore.
* *
* @return EINA_TRUE if it succeeds in setting the cancellable state * @return EINA_TRUE if it succeeds in setting the cancellable state
@ -227,7 +227,7 @@ EAPI void eina_thread_cancel_checkpoint(void);
/** /**
* @def EINA_THREAD_CLEANUP_PUSH(cleanup, data) * @def EINA_THREAD_CLEANUP_PUSH(cleanup, data)
* *
* @brief Push a cleanup function to be executed when the thread is * @brief Pushes a cleanup function to be executed when the thread is
* canceled. * canceled.
* *
* This macro will schedule a function cleanup(data) to be executed if * This macro will schedule a function cleanup(data) to be executed if
@ -246,8 +246,8 @@ EAPI void eina_thread_cancel_checkpoint(void);
* @b not be executed! To avoid problems prefer to use * @b not be executed! To avoid problems prefer to use
* eina_thread_cancellable_run()! * eina_thread_cancellable_run()!
* *
* @param cleanup the function to execute on cancellation. * @param cleanup The function to execute on cancellation.
* @param data the context to give to cleanup function. * @param data The context to give to cleanup function.
* *
* @see eina_thread_cancellable_run() * @see eina_thread_cancellable_run()
* *
@ -259,7 +259,7 @@ EAPI void eina_thread_cancel_checkpoint(void);
/** /**
* @def EINA_THREAD_CLEANUP_POP(exec_cleanup) * @def EINA_THREAD_CLEANUP_POP(exec_cleanup)
* *
* @brief Pop a cleanup function to be executed when the thread is * @brief Pops a cleanup function to be executed when the thread is
* canceled. * canceled.
* *
* This macro will remove a previously pushed cleanup function, thus * This macro will remove a previously pushed cleanup function, thus

30
src/lib/eina/eina_thread_queue.h
View File

@ -48,7 +48,7 @@ typedef struct _Eina_Thread_Queue_Msg Eina_Thread_Queue_Msg;
* queues. This is the only Message type for a parent message queue and * queues. This is the only Message type for a parent message queue and
* it indicates which child queue was woken up with a new message to read. * it indicates which child queue was woken up with a new message to read.
* When this message is retrieved, the caller should then also fetch the * When this message is retrieved, the caller should then also fetch the
* message from the inidcated child queue too. * message from the indicated child queue too.
* *
* @since 1.11 * @since 1.11
*/ */
@ -66,7 +66,7 @@ struct _Eina_Thread_Queue_Msg_Sub
}; };
/** /**
* @brief Create a new thread queue * @brief Creates a new thread queue.
* *
* @return A valid new thread queue, or NULL on failure * @return A valid new thread queue, or NULL on failure
* *
@ -76,7 +76,7 @@ EAPI Eina_Thread_Queue *
eina_thread_queue_new(void); eina_thread_queue_new(void);
/** /**
* @brief Free a thread queue * @brief Frees a thread queue.
* *
* This frees a thread queue. It must no longer be in use by anything waiting * This frees a thread queue. It must no longer be in use by anything waiting
* on messages or sending them. Any pending messages will be freed without * on messages or sending them. Any pending messages will be freed without
@ -90,7 +90,7 @@ EAPI void
eina_thread_queue_free(Eina_Thread_Queue *thq) EINA_ARG_NONNULL(1); eina_thread_queue_free(Eina_Thread_Queue *thq) EINA_ARG_NONNULL(1);
/** /**
* @brief Allocate a message to send down a thread queue * @brief Allocates a message to send down a thread queue.
* *
* @param thq The thread queue to allocate the message on * @param thq The thread queue to allocate the message on
* @param size The size, in bytes, of the message, including standard header * @param size The size, in bytes, of the message, including standard header
@ -109,7 +109,7 @@ EAPI void *
eina_thread_queue_send(Eina_Thread_Queue *thq, int size, void **allocref) EINA_ARG_NONNULL(1, 3); eina_thread_queue_send(Eina_Thread_Queue *thq, int size, void **allocref) EINA_ARG_NONNULL(1, 3);
/** /**
* @brief Finish sending the allocated message * @brief Finishes sending the allocated message.
* *
* @param thq The thread queue the message was placed on * @param thq The thread queue the message was placed on
* @param allocref The allocref returned by eina_thread_queue_send() * @param allocref The allocref returned by eina_thread_queue_send()
@ -123,7 +123,7 @@ EAPI void
eina_thread_queue_send_done(Eina_Thread_Queue *thq, void *allocref) EINA_ARG_NONNULL(1, 2); eina_thread_queue_send_done(Eina_Thread_Queue *thq, void *allocref) EINA_ARG_NONNULL(1, 2);
/** /**
* @brief Fetch a message from a thread queue * @brief Fetches a message from a thread queue.
* *
* @param thq The thread queue to fetch the message from * @param thq The thread queue to fetch the message from
* @param allocref A pointer to store a general reference handle for the message * @param allocref A pointer to store a general reference handle for the message
@ -143,7 +143,7 @@ EAPI void *
eina_thread_queue_wait(Eina_Thread_Queue *thq, void **allocref) EINA_ARG_NONNULL(1, 2); eina_thread_queue_wait(Eina_Thread_Queue *thq, void **allocref) EINA_ARG_NONNULL(1, 2);
/** /**
* @brief Finish fetching a message from a thread queue * @brief Finishes fetching a message from a thread queue.
* *
* @param thq The thread queue the message was fetched from * @param thq The thread queue the message was fetched from
* @param allocref The allocref returned by eina_thread_queue_wait() * @param allocref The allocref returned by eina_thread_queue_wait()
@ -157,7 +157,7 @@ EAPI void
eina_thread_queue_wait_done(Eina_Thread_Queue *thq, void *allocref) EINA_ARG_NONNULL(1, 2); eina_thread_queue_wait_done(Eina_Thread_Queue *thq, void *allocref) EINA_ARG_NONNULL(1, 2);
/** /**
* @brief Fetch a message from a thread queue, but return immediately if there is none with NULL * @brief Fetches a message from a thread queue, but return immediately if there is none with NULL.
* *
* @param thq The thread queue to fetch the message from * @param thq The thread queue to fetch the message from
* @param allocref A pointer to store a general reference handle for the message * @param allocref A pointer to store a general reference handle for the message
@ -175,7 +175,7 @@ EAPI void *
eina_thread_queue_poll(Eina_Thread_Queue *thq, void **allocref) EINA_ARG_NONNULL(1, 2); eina_thread_queue_poll(Eina_Thread_Queue *thq, void **allocref) EINA_ARG_NONNULL(1, 2);
/** /**
* @brief Get the number of messages on a queue as yet unfetched * @brief Gets the number of messages on a queue as yet unfetched.
* *
* @param thq The thread queue to query for pending count * @param thq The thread queue to query for pending count
* @return The number of messages waiting to be fetched * @return The number of messages waiting to be fetched
@ -189,7 +189,7 @@ EAPI int
eina_thread_queue_pending_get(const Eina_Thread_Queue *thq) EINA_ARG_NONNULL(1); eina_thread_queue_pending_get(const Eina_Thread_Queue *thq) EINA_ARG_NONNULL(1);
/** /**
* @brief Set the parent of a thread queue (make this one a child) * @brief Sets the parent of a thread queue (make this one a child).
* *
* @param thq The thread queue to alter the parent of * @param thq The thread queue to alter the parent of
* @param thq_parent The new parent to set * @param thq_parent The new parent to set
@ -206,12 +206,12 @@ EAPI void
eina_thread_queue_parent_set(Eina_Thread_Queue *thq, Eina_Thread_Queue *thq_parent) EINA_ARG_NONNULL(1); eina_thread_queue_parent_set(Eina_Thread_Queue *thq, Eina_Thread_Queue *thq_parent) EINA_ARG_NONNULL(1);
/** /**
* @brief Get the parent of a thread queue * @brief Gets the parent of a thread queue.
* *
* @param thq The thread queue to get the parent of * @param thq The thread queue to get the parent of
* @return The parent thread queue * @return The parent thread queue
* *
* This gets the paren set by eina_thread_queue_parent_get(). If no parent * This gets the parent set by eina_thread_queue_parent_get(). If no parent
* is set, NULL is returned. * is set, NULL is returned.
* *
* @see eina_thread_queue_parent_set() * @see eina_thread_queue_parent_set()
@ -222,14 +222,14 @@ EAPI Eina_Thread_Queue *
eina_thread_queue_parent_get(const Eina_Thread_Queue *thq) EINA_ARG_NONNULL(1); eina_thread_queue_parent_get(const Eina_Thread_Queue *thq) EINA_ARG_NONNULL(1);
/** /**
* @brief Set a file descriptor to write a byte to on a message send * @brief Sets a file descriptor to write a byte to on a message send.
* *
* @param thq The thread queue to set the file descriptor of * @param thq The thread queue to set the file descriptor of
* @param fd The fd to set, or -1 to unset it * @param fd The fd to set, or -1 to unset it
* *
* This sets a file descriptor to write to when a message is written to the * This sets a file descriptor to write to when a message is written to the
* thread queue. This can be used to glue a thread queue to something like * thread queue. This can be used to glue a thread queue to something like
* an Ecore_Pipe that can wake up the mainloop and call a callbck whenever * an Ecore_Pipe that can wake up the mainloop and call a callback whenever
* data is available on the pipe. The number of bytes available will be * data is available on the pipe. The number of bytes available will be
* the number of messages to fetch from the associated thread queue. * the number of messages to fetch from the associated thread queue.
* *
@ -242,7 +242,7 @@ EAPI void
eina_thread_queue_fd_set(Eina_Thread_Queue *thq, int fd) EINA_ARG_NONNULL(1); eina_thread_queue_fd_set(Eina_Thread_Queue *thq, int fd) EINA_ARG_NONNULL(1);
/** /**
* @brief Get the file descriptor written to on message sends * @brief Gets the file descriptor written to on message sends.
* *
* @param thq The thread queue to get the file descriptor of * @param thq The thread queue to get the file descriptor of
* @return The file descriptor set (or -1 if none is set). * @return The file descriptor set (or -1 if none is set).

36
src/lib/eina/eina_tiler.h
View File

@ -207,7 +207,7 @@ EAPI void eina_tiler_free(Eina_Tiler *t);
EAPI void eina_tiler_tile_size_set(Eina_Tiler *t, int w, int h); EAPI void eina_tiler_tile_size_set(Eina_Tiler *t, int w, int h);
/** /**
* @brief Change the size of the area covered by the tiler. * @brief Changes the size of the area covered by the tiler.
* *
* @param t The tiler whose area size will be set. * @param t The tiler whose area size will be set.
* @param w Width of the area. * @param w Width of the area.
@ -220,7 +220,7 @@ EAPI void eina_tiler_tile_size_set(Eina_Tiler *t, int w, int h);
EAPI void eina_tiler_area_size_set(Eina_Tiler *t, int w, int h); EAPI void eina_tiler_area_size_set(Eina_Tiler *t, int w, int h);
/** /**
* @brief Get the size of the area covered by the tiler. * @brief Gets the size of the area covered by the tiler.
* *
* @param t The tiler whose area size will be fetched. * @param t The tiler whose area size will be fetched.
* @param w Width of the area. * @param w Width of the area.
@ -231,19 +231,19 @@ EAPI void eina_tiler_area_size_set(Eina_Tiler *t, int w, int h);
EAPI void eina_tiler_area_size_get(const Eina_Tiler *t, int *w, int *h); EAPI void eina_tiler_area_size_get(const Eina_Tiler *t, int *w, int *h);
/** /**
* @brief Define if we need to follow a strict grid of tile or a loosy one * @brief Defines if we need to follow a strict grid of tile or a loose one.
* *
* @param t The tiler to apply the strict rules to. * @param t The tiler to apply the strict rules to.
* @param strict Define if it will be strict or loosy * @param strict Define if it will be strict or loose
* *
* By default it will be loosy. * By default it will be loose.
* *
* @since 1.8 * @since 1.8
*/ */
EAPI void eina_tiler_strict_set(Eina_Tiler *t, Eina_Bool strict); EAPI void eina_tiler_strict_set(Eina_Tiler *t, Eina_Bool strict);
/** /**
* @brief Tell if a tiler is empty or not * @brief Tells if a tiler is empty or not.
* *
* @param t The tiler to apply the strict rules to. * @param t The tiler to apply the strict rules to.
* @return EINA_TRUE when empty, EINA_FALSE when not. * @return EINA_TRUE when empty, EINA_FALSE when not.
@ -281,7 +281,7 @@ EAPI void eina_tiler_rect_del(Eina_Tiler *t, const Eina_Rectangle
*/ */
EAPI void eina_tiler_clear(Eina_Tiler *t); EAPI void eina_tiler_clear(Eina_Tiler *t);
/** /**
* @brief Create a iterator to access the tilers calculated rectangles. * @brief Creates a iterator to access the tilers calculated rectangles.
* *
* @param t The tiler to iterate over. * @param t The tiler to iterate over.
* @return A iterator containing Eina_Rectangle. * @return A iterator containing Eina_Rectangle.
@ -293,10 +293,10 @@ EAPI Eina_Iterator *eina_tiler_iterator_new(const Eina_Tiler *t);
* *
* @param x X axis coordinate. * @param x X axis coordinate.
* @param y Y axis coordinate. * @param y Y axis coordinate.
* @param w width. * @param w Width.
* @param h height. * @param h Height.
* @param tile_w tile width. * @param tile_w Tile width.
* @param tile_h tile height. * @param tile_h Tile height.
* @return A pointer to the Eina_Iterator. @c NULL on failure. * @return A pointer to the Eina_Iterator. @c NULL on failure.
* *
* The region defined by @a x, @a y, @a w, @a h will be divided in to a grid of * The region defined by @a x, @a y, @a w, @a h will be divided in to a grid of
@ -305,7 +305,7 @@ EAPI Eina_Iterator *eina_tiler_iterator_new(const Eina_Tiler *t);
* *
* @note This is a convenience function, iterating over the returned iterator is * @note This is a convenience function, iterating over the returned iterator is
* equivalent to calling eina_tile_grid_slicer_setup() and calling * equivalent to calling eina_tile_grid_slicer_setup() and calling
* eina_tile_grid_slicer_next() untill it returns #EINA_FALSE. * eina_tile_grid_slicer_next() until it returns #EINA_FALSE.
*/ */
EAPI Eina_Iterator *eina_tile_grid_slicer_iterator_new(int x, int y, int w, int h, int tile_w, int tile_h); EAPI Eina_Iterator *eina_tile_grid_slicer_iterator_new(int x, int y, int w, int h, int tile_w, int tile_h);
@ -377,16 +377,16 @@ EAPI Eina_Bool eina_tiler_equal(Eina_Tiler *t1, Eina_Tiler *t2);
*/ */
static inline Eina_Bool eina_tile_grid_slicer_next(Eina_Tile_Grid_Slicer *slc, const Eina_Tile_Grid_Info **rect); static inline Eina_Bool eina_tile_grid_slicer_next(Eina_Tile_Grid_Slicer *slc, const Eina_Tile_Grid_Info **rect);
/** /**
* @brief Setup an Eina_Tile_Grid_Slicer struct. * @brief Sets up an Eina_Tile_Grid_Slicer struct.
* *
* @param slc Pointer to an Eina_Tile_Grid_Slicer struct. * @param slc Pointer to an Eina_Tile_Grid_Slicer struct.
* @param x X axis coordinate. * @param x X axis coordinate.
* @param y Y axis coordinate. * @param y Y axis coordinate.
* @param w width. * @param w Width.
* @param h height. * @param h Height.
* @param tile_w tile width. * @param tile_w Tile width.
* @param tile_h tile height. * @param tile_h Tile height.
* @return A pointer to the Eina_Iterator. @c NULL on failure. * @return A pointer to the Eina_Iterator, @c NULL on failure.
* *
* The region defined by @a x, @a y, @a w, @a h will be divided in to a grid of * The region defined by @a x, @a y, @a w, @a h will be divided in to a grid of
* tiles of width @a tile_w and height @p tile_h, @p slc can then be used with * tiles of width @a tile_w and height @p tile_h, @p slc can then be used with

24
src/lib/eina/eina_tmpstr.h
View File

@ -58,11 +58,11 @@
* *
* Eina tmpstr is intended for being able to conveniently pass strings back * Eina tmpstr is intended for being able to conveniently pass strings back
* to a calling parent without having to use single static buffers (which * to a calling parent without having to use single static buffers (which
* don't work with multiple threads or when returning multilpe times as * don't work with multiple threads or when returning multiple times as
* parameters to a single function. * parameters to a single function.
* *
* The traditional way to "return" a string in C is either to provide a buffer * The traditional way to "return" a string in C is either to provide a buffer
* as a paramater to return it in, return a pointer to a single static buffer, * as a parameter to return it in, return a pointer to a single static buffer,
* which has issues, or return a duplicated string. All cases are inconvenient * which has issues, or return a duplicated string. All cases are inconvenient
* and return special handling. This is intended to make this easier. Now you * and return special handling. This is intended to make this easier. Now you
* can do something like this: * can do something like this:
@ -121,7 +121,7 @@
typedef const char Eina_Tmpstr; typedef const char Eina_Tmpstr;
/** /**
* @brief Add a new temporary string based on the input string. * @brief Adds a new temporary string based on the input string.
* *
* @param str This is the input stringthat is copied into the temp string. * @param str This is the input stringthat is copied into the temp string.
* @return A pointer to the tmp string that is a standard C string. * @return A pointer to the tmp string that is a standard C string.
@ -165,7 +165,7 @@ typedef const char Eina_Tmpstr;
EAPI Eina_Tmpstr *eina_tmpstr_add(const char *str) EINA_WARN_UNUSED_RESULT; EAPI Eina_Tmpstr *eina_tmpstr_add(const char *str) EINA_WARN_UNUSED_RESULT;
/** /**
* @brief Add a new temporary string based on the input string and length. * @brief Adds a new temporary string based on the input string and length.
* *
* @param str This is the input string that is copied into the temp string. * @param str This is the input string that is copied into the temp string.
* @param length This is the maximum length and the allocated length of the temp string. * @param length This is the maximum length and the allocated length of the temp string.
@ -202,7 +202,7 @@ EAPI Eina_Tmpstr *eina_tmpstr_add_length(const char *str, size_t length);
* *
* @param tmpstr This is any C string pointer, but if it is a tmp string * @param tmpstr This is any C string pointer, but if it is a tmp string
* it will return the length faster. * it will return the length faster.
* @return The length of the string including the '\0'; * @return The length of the string including the '\0'
* *
* @deprecated * @deprecated
* @see eina_tmpstr_len() * @see eina_tmpstr_len()
@ -211,7 +211,7 @@ EAPI Eina_Tmpstr *eina_tmpstr_add_length(const char *str, size_t length);
EINA_DEPRECATED EAPI size_t eina_tmpstr_strlen(Eina_Tmpstr *tmpstr); EINA_DEPRECATED EAPI size_t eina_tmpstr_strlen(Eina_Tmpstr *tmpstr);
/** /**
* @brief Return the length of a temporary string. * @brief Returns the length of a temporary string.
* *
* @param tmpstr This is any C string pointer, but if it is a tmp string * @param tmpstr This is any C string pointer, but if it is a tmp string
* it will return the length faster. * it will return the length faster.
@ -222,7 +222,7 @@ EINA_DEPRECATED EAPI size_t eina_tmpstr_strlen(Eina_Tmpstr *tmpstr);
EAPI size_t eina_tmpstr_len(Eina_Tmpstr *tmpstr); EAPI size_t eina_tmpstr_len(Eina_Tmpstr *tmpstr);
/** /**
* @brief Delete the temporary string if it is one, or ignore it if it is not. * @brief Deletes the temporary string if it is one, or ignore it if it is not.
* *
* @param tmpstr This is any C string pointer, but if it is a tmp string * @param tmpstr This is any C string pointer, but if it is a tmp string
* it is freed. * it is freed.
@ -238,10 +238,10 @@ EAPI size_t eina_tmpstr_len(Eina_Tmpstr *tmpstr);
EAPI void eina_tmpstr_del(Eina_Tmpstr *tmpstr) EINA_ARG_NONNULL(1); EAPI void eina_tmpstr_del(Eina_Tmpstr *tmpstr) EINA_ARG_NONNULL(1);
/** /**
* @brief Add a new temporary string using the passed string. The passed * @brief Adds a new temporary string using the passed string. The passed
* string is used directly as the buffer. The passed string must be malloced. * string is used directly as the buffer. The passed string must be malloced.
* *
* @param str the input string to manage. * @param str The input string to manage.
* @return A pointer to the tmp string that is a standard C string. * @return A pointer to the tmp string that is a standard C string.
* *
* This function creates a new temporary string. On error, @c NULL is * This function creates a new temporary string. On error, @c NULL is
@ -253,11 +253,11 @@ EAPI void eina_tmpstr_del(Eina_Tmpstr *tmpstr) EINA_ARG_NONNULL(1);
EAPI Eina_Tmpstr *eina_tmpstr_manage_new(char *str) EINA_WARN_UNUSED_RESULT; EAPI Eina_Tmpstr *eina_tmpstr_manage_new(char *str) EINA_WARN_UNUSED_RESULT;
/** /**
* @brief Add a new temporary string using the passed string. The passed * @brief Adds a new temporary string using the passed string. The passed
* string is used directly as the buffer. The passed string must be malloced. * string is used directly as the buffer. The passed string must be malloced.
* *
* @param str the input string to manage. * @param str The input string to manage.
* @param length the length of the string. * @param length The length of the string.
* @return A pointer to the tmp string that is a standard C string. * @return A pointer to the tmp string that is a standard C string.
* *
* This function creates a new temporary string. On error, @c NULL is * This function creates a new temporary string. On error, @c NULL is

26
src/lib/eina/eina_trash.h
View File

@ -29,7 +29,7 @@
/** /**
* @typedef Eina_Trash * @typedef Eina_Trash
* @brief The type for strcuture #_Eina_Trash. * @brief The type for structure #_Eina_Trash.
*/ */
typedef struct _Eina_Trash Eina_Trash; typedef struct _Eina_Trash Eina_Trash;
@ -44,12 +44,11 @@ struct _Eina_Trash
/** /**
* @brief Initializes a trash before using it. * @brief Initializes a trash before using it.
*
* @param[in] trash The trash
*
* @details This function just set to zero the trash to correctly * @details This function just set to zero the trash to correctly
* initialize it. * initialize it.
* *
* @param[in] trash The trash
*
* @note You can just set *trash to @c NULL and you will have * @note You can just set *trash to @c NULL and you will have
* the same result. * the same result.
*/ */
@ -57,14 +56,13 @@ static inline void eina_trash_init(Eina_Trash **trash) EINA_ARG_NONNULL(1);
/** /**
* @brief Pushes an unused pointer in the trash instead of freeing it. * @brief Pushes an unused pointer in the trash instead of freeing it.
*
* @param[in] trash A pointer to an Eina_Trash
* @param data An unused pointer big enougth to put a (void*)
*
* @details Instead of freeing a pointer and put pressure on malloc/free * @details Instead of freeing a pointer and put pressure on malloc/free
* you can push it in a trash for a later use. This function just * you can push it in a trash for a later use. This function just
* provide a fast way to push a now unused pointer into a trash. * provide a fast way to push a now unused pointer into a trash.
* *
* @param[in] trash A pointer to an Eina_Trash
* @param data An unused pointer big enough to put a (void*)
*
* @note Do not use the pointer after insertion or bad things will * @note Do not use the pointer after insertion or bad things will
* happens. * happens.
* *
@ -75,12 +73,11 @@ static inline void eina_trash_push(Eina_Trash **trash, void *data) EINA_ARG_NON
/** /**
* @brief Pops an available pointer from the trash if possible. * @brief Pops an available pointer from the trash if possible.
*
* @param[in] trash A #Eina_Trash handle
*
* @details Instead of calling malloc, and putting pressure on malloc/free * @details Instead of calling malloc, and putting pressure on malloc/free
* you can recycle the content of the trash, if it's not empty. * you can recycle the content of the trash, if it's not empty.
* *
* @param[in] trash A #Eina_Trash handle
*
* @note This trash will not resize, nor do anything with the size of * @note This trash will not resize, nor do anything with the size of
* the region pointed by pointer inside the trash, so it's your duty * the region pointed by pointer inside the trash, so it's your duty
* to manage the size of the returned pointer. * to manage the size of the returned pointer.
@ -89,14 +86,13 @@ static inline void *eina_trash_pop(Eina_Trash **trash) EINA_ARG_NONNULL(1) EINA_
/** /**
* @def EINA_TRASH_CLEAN * @def EINA_TRASH_CLEAN
* @brief Definition of a macro to remove all the pointers from the trash. * @brief Definition for a macro to remove all the pointers from the trash.
* @details This macro allows the cleaning of @a trash in an easy way. It
* removes all the pointers from @a trash until it's empty.
* *
* @param trash The trash to clean * @param trash The trash to clean
* @param data The pointer extracted from the trash * @param data The pointer extracted from the trash
* *
* @details This macro allows the cleaning of @a trash in an easy way. It
* removes all the pointers from @a trash until it's empty.
*
* @note This macro can be used for freeing the data in the trash, like in * @note This macro can be used for freeing the data in the trash, like in
* the following example: * the following example:
* *

4
src/lib/eina/eina_types.h
View File

@ -293,7 +293,7 @@
* *
* @param ... Oridnals of the parameters to check for nullity (1..n) * @param ... Oridnals of the parameters to check for nullity (1..n)
* *
* @returns Nothing, but Doxygen will complain if it's not documented :-P * @return Nothing, but Doxygen will complain if it's not documented :-P
* *
*/ */
# define EINA_ARG_NONNULL(...) # define EINA_ARG_NONNULL(...)
@ -454,7 +454,7 @@ typedef int (*Eina_Compare_Cb)(const void *data1, const void *data2);
/** /**
* @typedef Eina_Random_Cb * @typedef Eina_Random_Cb
* Function used in shuffling functions. An integer betwen min and max * Function used in shuffling functions. An integer between min and max
* inclusive must be returned. * inclusive must be returned.
* *
* @since 1.8 * @since 1.8

2
src/lib/eina/eina_unicode.h
View File

@ -127,6 +127,7 @@ EAPI Eina_Unicode *eina_unicode_escape(const Eina_Unicode *str) EINA_ARG_NONNULL
static inline Eina_Unicode eina_unicode_utf8_next_get(const char *buf, int *iindex) EINA_ARG_NONNULL(1, 2); static inline Eina_Unicode eina_unicode_utf8_next_get(const char *buf, int *iindex) EINA_ARG_NONNULL(1, 2);
/** /**
* @deprecated use eina_unicode_utf8_next_get
* Reads UTF8 bytes from @p buf, starting at @p iindex and returns * Reads UTF8 bytes from @p buf, starting at @p iindex and returns
* the decoded code point at @p iindex offset, and advances @p iindex * the decoded code point at @p iindex offset, and advances @p iindex
* to the next code point after this. @p iindex is always advanced, * to the next code point after this. @p iindex is always advanced,
@ -138,7 +139,6 @@ static inline Eina_Unicode eina_unicode_utf8_next_get(const char *buf, int *iind
* @param iindex the index to look at and return by. * @param iindex the index to look at and return by.
* @return the codepoint found, 0 if @p buf or @p iindex are NULL * @return the codepoint found, 0 if @p buf or @p iindex are NULL
* @since 1.1.0 * @since 1.1.0
* @deprecated use eina_unicode_utf8_next_get
*/ */
EAPI Eina_Unicode eina_unicode_utf8_get_next(const char *buf, int *iindex) EINA_ARG_NONNULL(1, 2) EINA_DEPRECATED; EAPI Eina_Unicode eina_unicode_utf8_get_next(const char *buf, int *iindex) EINA_ARG_NONNULL(1, 2) EINA_DEPRECATED;

78
src/lib/eina/eina_ustrbuf.h
View File

@ -34,7 +34,7 @@
typedef struct _Eina_Strbuf Eina_UStrbuf; typedef struct _Eina_Strbuf Eina_UStrbuf;
/** /**
* @brief Create a new string buffer. * @brief Creates a new string buffer.
* *
* @return Newly allocated string buffer instance. * @return Newly allocated string buffer instance.
* *
@ -48,12 +48,12 @@ typedef struct _Eina_Strbuf Eina_UStrbuf;
EAPI Eina_UStrbuf *eina_ustrbuf_new(void) EINA_MALLOC EINA_WARN_UNUSED_RESULT; EAPI Eina_UStrbuf *eina_ustrbuf_new(void) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
/** /**
* @brief Create a new string buffer using the passed string. The passed * @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 * string is used directly as the buffer, it's somehow the opposite function of
* @ref eina_ustrbuf_string_steal . The passed string must be malloced. * @ref eina_ustrbuf_string_steal . The passed string must be malloced.
* *
* @param str the string to manage * @param str The string to manage
* @return Newly allocated string buffer instance. * @return Newly allocated string buffer instance
* *
* This function creates a new string buffer. On error, @c NULL is * This function creates a new string buffer. On error, @c NULL is
* returned. To free the resources, use eina_strbuf_free(). * returned. To free the resources, use eina_strbuf_free().
@ -66,12 +66,12 @@ EAPI Eina_UStrbuf *eina_ustrbuf_new(void) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
EAPI Eina_UStrbuf *eina_ustrbuf_manage_new(Eina_Unicode *str) EINA_MALLOC EINA_WARN_UNUSED_RESULT; EAPI Eina_UStrbuf *eina_ustrbuf_manage_new(Eina_Unicode *str) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
/** /**
* @brief Create a new string buffer using the passed string. The passed * @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 * string is used directly as the buffer, it's somehow the opposite function of
* @ref eina_ustrbuf_string_steal . The passed string must be malloced. * @ref eina_ustrbuf_string_steal . The passed string must be malloced.
* *
* @param str the string to manage * @param str The string to manage
* @param length the length of the string. * @param length The length of the string.
* @return Newly allocated string buffer instance. * @return Newly allocated string buffer instance.
* *
* This function creates a new string buffer. On error, @c NULL is * This function creates a new string buffer. On error, @c NULL is
@ -83,7 +83,7 @@ EAPI Eina_UStrbuf *eina_ustrbuf_manage_new(Eina_Unicode *str) EINA_MALLOC EINA_W
EAPI Eina_UStrbuf *eina_ustrbuf_manage_new_length(Eina_Unicode *str, size_t length) EINA_MALLOC EINA_WARN_UNUSED_RESULT; EAPI Eina_UStrbuf *eina_ustrbuf_manage_new_length(Eina_Unicode *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. * @param buf The string buffer to free.
* *
@ -93,7 +93,7 @@ EAPI Eina_UStrbuf *eina_ustrbuf_manage_new_length(Eina_Unicode *str, size_t leng
EAPI void eina_ustrbuf_free(Eina_UStrbuf *buf) EINA_ARG_NONNULL(1); EAPI void eina_ustrbuf_free(Eina_UStrbuf *buf) EINA_ARG_NONNULL(1);
/** /**
* @brief Reset a string buffer. * @brief Resets a string buffer.
* *
* @param buf The string buffer to reset. * @param buf The string buffer to reset.
* *
@ -103,7 +103,7 @@ EAPI void eina_ustrbuf_free(Eina_UStrbuf *buf) EINA_ARG_NONNULL(1);
EAPI void eina_ustrbuf_reset(Eina_UStrbuf *buf) EINA_ARG_NONNULL(1); EAPI void eina_ustrbuf_reset(Eina_UStrbuf *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.
* *
* @param buf The string buffer to append to. * @param buf The string buffer to append to.
* @param str The string to append. * @param str The string to append.
@ -121,7 +121,7 @@ EAPI void eina_ustrbuf_reset(Eina_UStrbuf *buf) EINA_ARG_NONNULL(1);
EAPI Eina_Bool eina_ustrbuf_append(Eina_UStrbuf *buf, const Eina_Unicode *str) EINA_ARG_NONNULL(1, 2); EAPI Eina_Bool eina_ustrbuf_append(Eina_UStrbuf *buf, const Eina_Unicode *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 buf The string buffer to append to.
* @param str The string to append. * @param str The string to append.
@ -134,7 +134,7 @@ EAPI Eina_Bool eina_ustrbuf_append(Eina_UStrbuf *buf, const Eina_Unicode *str) E
EAPI Eina_Bool eina_ustrbuf_append_escaped(Eina_UStrbuf *buf, const Eina_Unicode *str) EINA_ARG_NONNULL(1, 2); EAPI Eina_Bool eina_ustrbuf_append_escaped(Eina_UStrbuf *buf, const Eina_Unicode *str) EINA_ARG_NONNULL(1, 2);
/** /**
* @brief Append a string to a buffer, reallocating as necessary, * @brief Appends a string to a buffer, reallocating as necessary,
* limited by the given length. * limited by the given length.
* *
* @param buf The string buffer to append to. * @param buf The string buffer to append to.
@ -157,7 +157,7 @@ EAPI Eina_Bool eina_ustrbuf_append_escaped(Eina_UStrbuf *buf, const Eina_Unicode
EAPI Eina_Bool eina_ustrbuf_append_n(Eina_UStrbuf *buf, const Eina_Unicode *str, size_t maxlen) EINA_ARG_NONNULL(1, 2); EAPI Eina_Bool eina_ustrbuf_append_n(Eina_UStrbuf *buf, const Eina_Unicode *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.
* *
* @param buf The string buffer to append to. * @param buf The string buffer to append to.
* @param str The string to append. * @param str The string to append.
@ -178,7 +178,7 @@ EAPI Eina_Bool eina_ustrbuf_append_n(Eina_UStrbuf *buf, const Eina_Unicode *str,
EAPI Eina_Bool eina_ustrbuf_append_length(Eina_UStrbuf *buf, const Eina_Unicode *str, size_t length) EINA_ARG_NONNULL(1, 2); EAPI Eina_Bool eina_ustrbuf_append_length(Eina_UStrbuf *buf, const Eina_Unicode *str, size_t length) EINA_ARG_NONNULL(1, 2);
/** /**
* @brief Append a slice to a buffer, reallocating as necessary. * @brief Appends a slice to a buffer, reallocating as necessary.
* *
* @param buf The string buffer to append to. * @param buf The string buffer to append to.
* @param slice The slice to append. * @param slice The slice to append.
@ -192,7 +192,7 @@ EAPI Eina_Bool eina_ustrbuf_append_length(Eina_UStrbuf *buf, const Eina_Unicode
EAPI Eina_Bool eina_ustrbuf_append_slice(Eina_UStrbuf *buf, const Eina_Slice slice) EINA_ARG_NONNULL(1); EAPI Eina_Bool eina_ustrbuf_append_slice(Eina_UStrbuf *buf, const Eina_Slice slice) EINA_ARG_NONNULL(1);
/** /**
* @brief Append a character to a string buffer, reallocating as * @brief Appends a character to a string buffer, reallocating as
* necessary. * necessary.
* *
* @param buf The string buffer to append to. * @param buf The string buffer to append to.
@ -205,7 +205,7 @@ EAPI Eina_Bool eina_ustrbuf_append_slice(Eina_UStrbuf *buf, const Eina_Slice sli
EAPI Eina_Bool eina_ustrbuf_append_char(Eina_UStrbuf *buf, Eina_Unicode c) EINA_ARG_NONNULL(1); EAPI Eina_Bool eina_ustrbuf_append_char(Eina_UStrbuf *buf, Eina_Unicode c) EINA_ARG_NONNULL(1);
/** /**
* @brief Insert a string to a buffer, reallocating as necessary. * @brief Inserts a string to a buffer, reallocating as necessary.
* *
* @param buf The string buffer to insert. * @param buf The string buffer to insert.
* @param str The string to insert. * @param str The string to insert.
@ -221,7 +221,7 @@ EAPI Eina_Bool eina_ustrbuf_append_char(Eina_UStrbuf *buf, Eina_Unicode c) EINA_
EAPI Eina_Bool eina_ustrbuf_insert(Eina_UStrbuf *buf, const Eina_Unicode *str, size_t pos) EINA_ARG_NONNULL(1, 2); EAPI Eina_Bool eina_ustrbuf_insert(Eina_UStrbuf *buf, const Eina_Unicode *str, size_t pos) EINA_ARG_NONNULL(1, 2);
/** /**
* @brief Insert an escaped string to a buffer, reallocating as * @brief Inserts an escaped string to a buffer, reallocating as
* necessary. * necessary.
* *
* @param buf The string buffer to insert to. * @param buf The string buffer to insert to.
@ -236,7 +236,7 @@ EAPI Eina_Bool eina_ustrbuf_insert(Eina_UStrbuf *buf, const Eina_Unicode *str, s
EAPI Eina_Bool eina_ustrbuf_insert_escaped(Eina_UStrbuf *buf, const Eina_Unicode *str, size_t pos) EINA_ARG_NONNULL(1, 2); EAPI Eina_Bool eina_ustrbuf_insert_escaped(Eina_UStrbuf *buf, const Eina_Unicode *str, size_t pos) EINA_ARG_NONNULL(1, 2);
/** /**
* @brief Insert a string to a buffer, reallocating as necessary. Limited by maxlen. * @brief Inserts a string to a buffer, reallocating as necessary. Limited by maxlen.
* *
* @param buf The string buffer to insert to. * @param buf The string buffer to insert to.
* @param str The string to insert. * @param str The string to insert.
@ -256,7 +256,7 @@ EAPI Eina_Bool eina_ustrbuf_insert_escaped(Eina_UStrbuf *buf, const Eina_Unicode
EAPI Eina_Bool eina_ustrbuf_insert_n(Eina_UStrbuf *buf, const Eina_Unicode *str, size_t maxlen, size_t pos) EINA_ARG_NONNULL(1, 2); EAPI Eina_Bool eina_ustrbuf_insert_n(Eina_UStrbuf *buf, const Eina_Unicode *str, size_t maxlen, size_t pos) EINA_ARG_NONNULL(1, 2);
/** /**
* @brief Insert a string of exact length to a buffer, reallocating as necessary. * @brief Inserts a string of exact length to a buffer, reallocating as necessary.
* *
* @param buf The string buffer to insert to. * @param buf The string buffer to insert to.
* @param str The string to insert. * @param str The string to insert.
@ -278,7 +278,7 @@ EAPI Eina_Bool eina_ustrbuf_insert_n(Eina_UStrbuf *buf, const Eina_Unicode *str,
EAPI Eina_Bool eina_ustrbuf_insert_length(Eina_UStrbuf *buf, const Eina_Unicode *str, size_t length, size_t pos) EINA_ARG_NONNULL(1, 2); EAPI Eina_Bool eina_ustrbuf_insert_length(Eina_UStrbuf *buf, const Eina_Unicode *str, size_t length, size_t pos) EINA_ARG_NONNULL(1, 2);
/** /**
* @brief Insert a slice to a buffer, reallocating as necessary. * @brief Inserts a slice to a buffer, reallocating as necessary.
* *
* @param buf The string buffer to insert to. * @param buf The string buffer to insert to.
* @param slice The slice to insert. * @param slice The slice to insert.
@ -294,7 +294,7 @@ EAPI Eina_Bool eina_ustrbuf_insert_length(Eina_UStrbuf *buf, const Eina_Unicode
EAPI Eina_Bool eina_ustrbuf_insert_slice(Eina_UStrbuf *buf, const Eina_Slice slice, size_t pos) EINA_ARG_NONNULL(1); EAPI Eina_Bool eina_ustrbuf_insert_slice(Eina_UStrbuf *buf, const Eina_Slice slice, size_t pos) EINA_ARG_NONNULL(1);
/** /**
* @brief Insert a character to a string buffer, reallocating as * @brief Inserts a character to a string buffer, reallocating as
* necessary. * necessary.
* *
* @param buf The string buffer to insert to. * @param buf The string buffer to insert to.
@ -310,7 +310,7 @@ EAPI Eina_Bool eina_ustrbuf_insert_char(Eina_UStrbuf *buf, Eina_Unicode c, size_
/** /**
* @def eina_ustrbuf_prepend(buf, str) * @def eina_ustrbuf_prepend(buf, str)
* @brief Prepend the given string to the given buffer * @brief Prepends the given string to the given buffer.
* *
* @param buf The string buffer to prepend to. * @param buf The string buffer to prepend to.
* @param str The string to prepend. * @param str The string to prepend.
@ -324,7 +324,7 @@ EAPI Eina_Bool eina_ustrbuf_insert_char(Eina_UStrbuf *buf, Eina_Unicode c, size_
/** /**
* @def eina_ustrbuf_prepend_escaped(buf, str) * @def eina_ustrbuf_prepend_escaped(buf, str)
* @brief Prepend the given escaped string to the given buffer * @brief Prepends the given escaped string to the given buffer.
* *
* @param buf The string buffer to prepend to. * @param buf The string buffer to prepend to.
* @param str The string to prepend. * @param str The string to prepend.
@ -338,7 +338,7 @@ EAPI Eina_Bool eina_ustrbuf_insert_char(Eina_UStrbuf *buf, Eina_Unicode c, size_
/** /**
* @def eina_ustrbuf_prepend_n(buf, str) * @def eina_ustrbuf_prepend_n(buf, str)
* @brief Prepend the given escaped string to the given buffer * @brief Prepends the given escaped string to the given buffer.
* *
* @param buf The string buffer to prepend to. * @param buf The string buffer to prepend to.
* @param str The string to prepend. * @param str The string to prepend.
@ -353,7 +353,7 @@ EAPI Eina_Bool eina_ustrbuf_insert_char(Eina_UStrbuf *buf, Eina_Unicode c, size_
/** /**
* @def eina_ustrbuf_prepend_length(buf, str) * @def eina_ustrbuf_prepend_length(buf, str)
* @brief Prepend the given escaped string to the given buffer * @brief Prepends the given escaped string to the given buffer.
* *
* @param buf The string buffer to prepend to. * @param buf The string buffer to prepend to.
* @param str The string to prepend. * @param str The string to prepend.
@ -368,7 +368,7 @@ EAPI Eina_Bool eina_ustrbuf_insert_char(Eina_UStrbuf *buf, Eina_Unicode c, size_
/** /**
* @def eina_ustrbuf_prepend_char(buf, c) * @def eina_ustrbuf_prepend_char(buf, c)
* @brief Prepend the given unicode character to the given buffer * @brief Prepends the given unicode character to the given buffer.
* *
* @param buf The string buffer to prepend to. * @param buf The string buffer to prepend to.
* @param c The Eina_Unicode character to prepend. * @param c The Eina_Unicode character to prepend.
@ -381,7 +381,7 @@ EAPI Eina_Bool eina_ustrbuf_insert_char(Eina_UStrbuf *buf, Eina_Unicode c, size_
#define eina_ustrbuf_prepend_char(buf, c) eina_ustrbuf_insert_char(buf, c, 0) #define eina_ustrbuf_prepend_char(buf, c) eina_ustrbuf_insert_char(buf, c, 0)
/** /**
* @brief Remove a slice of the given string buffer. * @brief Removes a slice of the given string buffer.
* *
* @param buf The string buffer to remove a slice. * @param buf The string buffer to remove a slice.
* @param start The initial (inclusive) slice position to start * @param start The initial (inclusive) slice position to start
@ -398,7 +398,7 @@ EAPI Eina_Bool
eina_ustrbuf_remove(Eina_UStrbuf *buf, size_t start, size_t end) EINA_ARG_NONNULL(1); eina_ustrbuf_remove(Eina_UStrbuf *buf, size_t start, size_t end) EINA_ARG_NONNULL(1);
/** /**
* @brief Retrieve a pointer to the contents of a string buffer * @brief Retrieves a pointer to the contents of a string buffer.
* *
* @param buf The string buffer. * @param buf The string buffer.
* @return The current string in the string buffer. * @return The current string in the string buffer.
@ -414,7 +414,7 @@ EAPI const Eina_Unicode *
eina_ustrbuf_string_get(const Eina_UStrbuf *buf) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; eina_ustrbuf_string_get(const Eina_UStrbuf *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. * @param buf The string buffer to steal.
* @return The current string in the string buffer. * @return The current string in the string buffer.
@ -430,7 +430,7 @@ EAPI Eina_Unicode *
eina_ustrbuf_string_steal(Eina_UStrbuf *buf) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); eina_ustrbuf_string_steal(Eina_UStrbuf *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.
* *
* @param buf The string buffer to free the string of. * @param buf The string buffer to free the string of.
* *
@ -441,7 +441,7 @@ EAPI void
eina_ustrbuf_string_free(Eina_UStrbuf *buf) EINA_ARG_NONNULL(1); eina_ustrbuf_string_free(Eina_UStrbuf *buf) EINA_ARG_NONNULL(1);
/** /**
* @brief Retrieve the length of the string buffer content. * @brief Retrieves the length of the string buffer content.
* *
* @param buf The string buffer. * @param buf The string buffer.
* @return The current length of the string, in bytes. * @return The current length of the string, in bytes.
@ -452,10 +452,10 @@ EAPI size_t
eina_ustrbuf_length_get(const Eina_UStrbuf *buf) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; eina_ustrbuf_length_get(const Eina_UStrbuf *buf) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
/** /**
* @brief Get a read-only slice representing the current ustrbuf contents. * @brief Gets a read-only slice representing the current ustrbuf contents.
* *
* @param buf the source string. * @param buf The source string.
* @return a read-only slice for the current contents. It may become * @return A read-only slice for the current contents. It may become
* invalid as soon as the @a buf is changed. * invalid as soon as the @a buf is changed.
* *
* @since 1.19 * @since 1.19
@ -463,10 +463,10 @@ eina_ustrbuf_length_get(const Eina_UStrbuf *buf) EINA_ARG_NONNULL(1) EINA_WARN_U
EAPI Eina_Slice eina_ustrbuf_slice_get(const Eina_UStrbuf *buf) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); EAPI Eina_Slice eina_ustrbuf_slice_get(const Eina_UStrbuf *buf) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
/** /**
* @brief Get a read-write slice representing the current ustrbuf contents. * @brief Gets a read-write slice representing the current ustrbuf contents.
* *
* @param buf the source string. * @param buf The source string.
* @return a read-write slice for the current contents. It may become * @return A read-write slice for the current contents. It may become
* invalid as soon as the @a buf is changed with calls such as * invalid as soon as the @a buf is changed with calls such as
* eina_ustrbuf_append(), eina_ustrbuf_remove() * eina_ustrbuf_append(), eina_ustrbuf_remove()
* *
@ -475,9 +475,9 @@ EAPI Eina_Slice eina_ustrbuf_slice_get(const Eina_UStrbuf *buf) EINA_WARN_UNUSED
EAPI Eina_Rw_Slice eina_ustrbuf_rw_slice_get(const Eina_UStrbuf *buf) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); EAPI Eina_Rw_Slice eina_ustrbuf_rw_slice_get(const Eina_UStrbuf *buf) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
/** /**
* @brief Get the string of the buffer and free the buffer * @brief Gets the string of the buffer and free the buffer
* *
* @param buf the buffer to get the string from and which will be freed * @param buf The buffer to get the string from and which will be freed
* *
* @return The string contained by buf. The caller must release the memory of the returned string by calling * @return The string contained by buf. The caller must release the memory of the returned string by calling
* free(). * free().

26
src/lib/eina/eina_ustringshare.h
View File

@ -29,9 +29,9 @@
* *
* The above copyright notice and this permission notice shall be included in * The above copyright notice and this permission notice shall be included in
* all copies of the Software and its Copyright notices. In addition publicly * all copies of the Software and its Copyright notices. In addition publicly
* documented acknowledgment must be given that this software has been used if no * documented acknowledgement must be given that this software has been used if no
* source code of this software is made available publicly. This includes * source code of this software is made available publicly. This includes
* acknowledgments in either Copyright notices, Manuals, Publicity and Marketing * acknowledgements in either Copyright notices, Manuals, Publicity and Marketing
* documents or any documentation provided with any product containing this * documents or any documentation provided with any product containing this
* software. This License does not apply to any software that links to the * software. This License does not apply to any software that links to the
* libraries provided by this software (statically or dynamically), but only to * libraries provided by this software (statically or dynamically), but only to
@ -90,11 +90,11 @@
/** /**
* @brief Retrieve an instance of a string for use in a program. * @brief Retrieves an instance of a string for use in a program.
* *
* @param str The string to retrieve an instance of. * @param str The string to retrieve an instance of.
* @param slen The string size (<= strlen(str)). * @param slen The string size (<= strlen(str)).
* @return A pointer to an instance of the string on success. * @return A pointer to an instance of the string on success,
* @c NULL on failure. * @c NULL on failure.
* *
* This function retrieves an instance of @p str. If @p str is * This function retrieves an instance of @p str. If @p str is
@ -112,10 +112,10 @@
EAPI const Eina_Unicode *eina_ustringshare_add_length(const Eina_Unicode *str, unsigned int slen) EINA_WARN_UNUSED_RESULT; EAPI const Eina_Unicode *eina_ustringshare_add_length(const Eina_Unicode *str, unsigned int slen) EINA_WARN_UNUSED_RESULT;
/** /**
* @brief Retrieve an instance of a string for use in a program. * @brief Retrieves an instance of a string for use in a program.
* *
* @param str The NULL-terminated string to retrieve an instance of. * @param str The NULL-terminated string to retrieve an instance of.
* @return A pointer to an instance of the string on success. * @return A pointer to an instance of the string on success,
* @c NULL on failure. * @c NULL on failure.
* *
* This function retrieves an instance of @p str. If @p str is * This function retrieves an instance of @p str. If @p str is
@ -133,10 +133,10 @@ EAPI const Eina_Unicode *eina_ustringshare_add_length(const Eina_Unicode *str, u
EAPI const Eina_Unicode *eina_ustringshare_add(const Eina_Unicode *str) EINA_WARN_UNUSED_RESULT; EAPI const Eina_Unicode *eina_ustringshare_add(const Eina_Unicode *str) EINA_WARN_UNUSED_RESULT;
/** /**
* Increment references of the given shared string. * @brief Increments references of the given shared string.
* *
* @param str The shared string. * @param str The shared string.
* @return A pointer to an instance of the string on success. * @return A pointer to an instance of the string on success,
* @c NULL on failure. * @c NULL on failure.
* *
* This is similar to eina_share_common_add(), but it's faster since it will * This is similar to eina_share_common_add(), but it's faster since it will
@ -149,9 +149,9 @@ EAPI const Eina_Unicode *eina_ustringshare_add(const Eina_Unicode *str) EINA_WAR
EAPI const Eina_Unicode *eina_ustringshare_ref(const Eina_Unicode *str); EAPI const Eina_Unicode *eina_ustringshare_ref(const Eina_Unicode *str);
/** /**
* @brief Note that the given string has lost an instance. * @brief Notes that the given string has lost an instance.
* *
* @param str string The given string. * @param str String The given string.
* *
* This function decreases the reference counter associated to @p str * This function decreases the reference counter associated to @p str
* if it exists. If that counter reaches 0, the memory associated to * if it exists. If that counter reaches 0, the memory associated to
@ -164,9 +164,9 @@ EAPI const Eina_Unicode *eina_ustringshare_ref(const Eina_Unicode *str);
EAPI void eina_ustringshare_del(const Eina_Unicode *str); EAPI void eina_ustringshare_del(const Eina_Unicode *str);
/** /**
* @brief Note that the given string @b must be shared. * @brief Notes that the given string @b must be shared.
* *
* @param str the shared string to know the length. It is safe to * @param str The shared string to know the length. It is safe to
* give @c NULL, in that case @c -1 is returned. * give @c NULL, in that case @c -1 is returned.
* *
* This function is a cheap way to known the length of a shared * This function is a cheap way to known the length of a shared
@ -178,7 +178,7 @@ EAPI void eina_ustringshare_del(const Eina_Unicode *str);
EAPI int eina_ustringshare_strlen(const Eina_Unicode *str) EINA_PURE EINA_WARN_UNUSED_RESULT; EAPI int eina_ustringshare_strlen(const Eina_Unicode *str) EINA_PURE EINA_WARN_UNUSED_RESULT;
/** /**
* @brief Dump the contents of the share_common. * @brief Dumps the contents of the share_common.
* *
* This function dumps all strings in the share_common to stdout with a * This function dumps all strings in the share_common to stdout with a
* DDD: prefix per line and a memory usage summary. * DDD: prefix per line and a memory usage summary.

8
src/lib/eina/eina_util.h
View File

@ -29,7 +29,7 @@
*/ */
/** /**
* @brief Return the content of the environment refered by HOME on this system. * @brief Returns the content of the environment referred by HOME on this system.
* @return A temporary string to the content refered by HOME on this system. * @return A temporary string to the content refered by HOME on this system.
* *
* @note The result of this call is highly system dependent and you better use * @note The result of this call is highly system dependent and you better use
@ -40,7 +40,7 @@
EAPI const char *eina_environment_home_get(void); EAPI const char *eina_environment_home_get(void);
/** /**
* @brief Return the content of the environment refered as TMPDIR on this system. * @brief Returns the content of the environment referred as TMPDIR on this system.
* @return A temporary string to the content refered by TMPDIR on this system. * @return A temporary string to the content refered by TMPDIR on this system.
* *
* @note The result of this call is highly system dependent and you better use * @note The result of this call is highly system dependent and you better use
@ -81,7 +81,7 @@ static inline Eina_Bool eina_flt_exact(float a, float b);
#define EINA_FLT_EQ(a, b) (!!(fabsf((float)a - (float)b) <= FLT_EPSILON)) #define EINA_FLT_EQ(a, b) (!!(fabsf((float)a - (float)b) <= FLT_EPSILON))
/** /**
* @brief Determine if a float is not zero * @brief Determines if a float is not zero
* @param a The float * @param a The float
* *
* @return @c true if float is not zero * @return @c true if float is not zero
@ -100,7 +100,7 @@ static inline Eina_Bool eina_flt_exact(float a, float b);
#define EINA_DBL_EQ(a, b) (!!(fabs((double)a - (double)b) <= DBL_EPSILON)) #define EINA_DBL_EQ(a, b) (!!(fabs((double)a - (double)b) <= DBL_EPSILON))
/** /**
* @brief Determine if a double is not zero * @brief Determines if a double is not zero
* @param a The double * @param a The double
* *
* @return @c true if double is not zero * @return @c true if double is not zero

470
src/lib/eina/eina_value.h
View File

File diff suppressed because it is too large Load Diff

4
src/lib/eina/eina_value_util.h
View File

@ -29,14 +29,14 @@
*/ */
/** /**
* @brief Create a basic #Eina_Value struct desc with refcounting * @brief Creates a basic #Eina_Value struct desc with refcounting.
* @return The #Eina_Value_Struct_Desc on success, @c NULL on failure * @return The #Eina_Value_Struct_Desc on success, @c NULL on failure
* @since 1.12 * @since 1.12
*/ */
EAPI Eina_Value_Struct_Desc *eina_value_util_struct_desc_new(void); EAPI Eina_Value_Struct_Desc *eina_value_util_struct_desc_new(void);
/** /**
* @brief Create a new #Eina_Value containing the passed parameter * @brief Creates a new #Eina_Value containing the passed parameter.
* @param timestr The value to use * @param timestr The value to use
* @return The #Eina_Value * @return The #Eina_Value
* @since 1.12 * @since 1.12

40
src/lib/eina/eina_xattr.h
View File

@ -49,7 +49,7 @@ struct _Eina_Xattr
}; };
/** /**
* @brief Get an iterator that list all extended attribute of a file. * @brief Gets an iterator that list all extended attribute of a file.
* *
* @param file The filename to retrieve the extended attribute list from. * @param file The filename to retrieve the extended attribute list from.
* @return an iterator. * @return an iterator.
@ -62,10 +62,10 @@ struct _Eina_Xattr
EAPI Eina_Iterator *eina_xattr_ls(const char *file) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; EAPI Eina_Iterator *eina_xattr_ls(const char *file) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
/** /**
* @brief Get an iterator that list all extended attribute value related to a fd. * @brief Gets an iterator that list all extended attribute value related to a fd.
* *
* @param file The filename to retrieve the extended attribute list from. * @param file The filename to retrieve the extended attribute list from.
* @return an iterator. * @return An iterator.
* *
* The iterator will not allocate any data during the iteration step, so you need to copy them yourself * The iterator will not allocate any data during the iteration step, so you need to copy them yourself
* if you need. The iterator will provide an Eina_Xattr structure. * if you need. The iterator will provide an Eina_Xattr structure.
@ -75,7 +75,7 @@ EAPI Eina_Iterator *eina_xattr_ls(const char *file) EINA_ARG_NONNULL(1) EINA_WAR
EAPI Eina_Iterator *eina_xattr_value_ls(const char *file) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; EAPI Eina_Iterator *eina_xattr_value_ls(const char *file) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
/** /**
* @brief Get an iterator that list all extended attribute related to a fd. * @brief Gets an iterator that list all extended attribute related to a fd.
* *
* @param fd The file descriptor to retrieve the extended attribute list from. * @param fd The file descriptor to retrieve the extended attribute list from.
* @return an iterator. * @return an iterator.
@ -88,10 +88,10 @@ EAPI Eina_Iterator *eina_xattr_value_ls(const char *file) EINA_ARG_NONNULL(1) EI
EAPI Eina_Iterator *eina_xattr_fd_ls(int fd) EINA_WARN_UNUSED_RESULT; EAPI Eina_Iterator *eina_xattr_fd_ls(int fd) EINA_WARN_UNUSED_RESULT;
/** /**
* @brief Get an iterator that list all extended attribute value related to a fd. * @brief Gets an iterator that list all extended attribute value related to a fd.
* *
* @param fd The file descriptor to retrieve the extended attribute list from. * @param fd The file descriptor to retrieve the extended attribute list from.
* @return an iterator. * @return An iterator.
* *
* The iterator will not allocate any data during the iteration step, so you need to copy them yourself * The iterator will not allocate any data during the iteration step, so you need to copy them yourself
* if you need. The iterator will provide an Eina_Xattr structure. * if you need. The iterator will provide an Eina_Xattr structure.
@ -101,7 +101,7 @@ EAPI Eina_Iterator *eina_xattr_fd_ls(int fd) EINA_WARN_UNUSED_RESULT;
EAPI Eina_Iterator *eina_xattr_value_fd_ls(int fd) EINA_WARN_UNUSED_RESULT; EAPI Eina_Iterator *eina_xattr_value_fd_ls(int fd) EINA_WARN_UNUSED_RESULT;
/** /**
* @brief Copy the extended attribute from one file to another. * @brief Copies the extended attribute from one file to another.
* @param src source file to use as input. * @param src source file to use as input.
* @param dst destination file to use as output. * @param dst destination file to use as output.
* @return #EINA_TRUE on success, #EINA_FALSE otherwise. * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
@ -111,7 +111,7 @@ EAPI Eina_Iterator *eina_xattr_value_fd_ls(int fd) EINA_WARN_UNUSED_RESULT;
EAPI Eina_Bool eina_xattr_copy(const char *src, const char *dst) EINA_ARG_NONNULL(1, 2); EAPI Eina_Bool eina_xattr_copy(const char *src, const char *dst) EINA_ARG_NONNULL(1, 2);
/** /**
* @brief Copy the extended attribute from one file descriptor to another. * @brief Copies the extended attribute from one file descriptor to another.
* @param src source file descriptor to use as input. * @param src source file descriptor to use as input.
* @param dst destination file descriptor to use as output. * @param dst destination file descriptor to use as output.
* @return #EINA_TRUE on success, #EINA_FALSE otherwise. * @return #EINA_TRUE on success, #EINA_FALSE otherwise.
@ -121,7 +121,7 @@ EAPI Eina_Bool eina_xattr_copy(const char *src, const char *dst) EINA_ARG_NONNUL
EAPI Eina_Bool eina_xattr_fd_copy(int src, int dst); EAPI Eina_Bool eina_xattr_fd_copy(int src, int dst);
/** /**
* @brief Retrieve an extended attribute from a file. * @brief Retrieves an extended attribute from a file.
* *
* @param file The file to retrieve the extended attribute from. * @param file The file to retrieve the extended attribute from.
* @param attribute The extended attribute name to retrieve. * @param attribute The extended attribute name to retrieve.
@ -135,7 +135,7 @@ EAPI Eina_Bool eina_xattr_fd_copy(int src, int dst);
EAPI void *eina_xattr_get(const char *file, const char *attribute, ssize_t *size) EINA_ARG_NONNULL(1, 2, 3) EINA_WARN_UNUSED_RESULT; EAPI void *eina_xattr_get(const char *file, const char *attribute, ssize_t *size) EINA_ARG_NONNULL(1, 2, 3) EINA_WARN_UNUSED_RESULT;
/** /**
* @brief Retrieve an extended attribute from a file descriptor. * @brief Retrieves an extended attribute from a file descriptor.
* *
* @param fd The file descriptor to retrieve the extended attribute from. * @param fd The file descriptor to retrieve the extended attribute from.
* @param attribute The extended attribute name to retrieve. * @param attribute The extended attribute name to retrieve.
@ -149,7 +149,7 @@ EAPI void *eina_xattr_get(const char *file, const char *attribute, ssize_t *size
EAPI void *eina_xattr_fd_get(int fd, const char *attribute, ssize_t *size) EINA_ARG_NONNULL(2, 3) EINA_WARN_UNUSED_RESULT; EAPI void *eina_xattr_fd_get(int fd, const char *attribute, ssize_t *size) EINA_ARG_NONNULL(2, 3) EINA_WARN_UNUSED_RESULT;
/** /**
* @brief Set an extended attribute on a file. * @brief Sets an extended attribute on a file.
* *
* @param file The file to set the extended attribute to. * @param file The file to set the extended attribute to.
* @param attribute The attribute to set. * @param attribute The attribute to set.
@ -163,7 +163,7 @@ EAPI void *eina_xattr_fd_get(int fd, const char *attribute, ssize_t *size) EINA_
EAPI Eina_Bool eina_xattr_set(const char *file, const char *attribute, const void *data, ssize_t length, Eina_Xattr_Flags flags) EINA_ARG_NONNULL(1, 2, 3); EAPI Eina_Bool eina_xattr_set(const char *file, const char *attribute, const void *data, ssize_t length, Eina_Xattr_Flags flags) EINA_ARG_NONNULL(1, 2, 3);
/** /**
* @brief Set an extended attribute on a file descriptor. * @brief Sets an extended attribute on a file descriptor.
* *
* @param fd The file descriptor to set the extended attribute to. * @param fd The file descriptor to set the extended attribute to.
* @param attribute The attribute to set. * @param attribute The attribute to set.
@ -178,7 +178,7 @@ EAPI Eina_Bool eina_xattr_fd_set(int fd, const char *attribute, const void *data
/** /**
* @brief Delete (remove) an extended attribute from a file. * @brief Deletes (removes) an extended attribute from a file.
* *
* @param file The file to del the extended attribute from. * @param file The file to del the extended attribute from.
* @param attribute The attribute to del. * @param attribute The attribute to del.
@ -189,7 +189,7 @@ EAPI Eina_Bool eina_xattr_fd_set(int fd, const char *attribute, const void *data
EAPI Eina_Bool eina_xattr_del(const char *file, const char *attribute) EINA_ARG_NONNULL(1, 2); EAPI Eina_Bool eina_xattr_del(const char *file, const char *attribute) EINA_ARG_NONNULL(1, 2);
/** /**
* @brief Delete (remove) an extended attribute from a file descriptor. * @brief Deletes (removes) an extended attribute from a file descriptor.
* *
* @param fd The file descriptor to del the extended attribute from. * @param fd The file descriptor to del the extended attribute from.
* @param attribute The attribute to del. * @param attribute The attribute to del.
@ -200,7 +200,7 @@ EAPI Eina_Bool eina_xattr_del(const char *file, const char *attribute) EINA_ARG_
EAPI Eina_Bool eina_xattr_fd_del(int fd, const char *attribute) EINA_ARG_NONNULL(2); EAPI Eina_Bool eina_xattr_fd_del(int fd, const char *attribute) EINA_ARG_NONNULL(2);
/** /**
* @brief Set a string as a extended attribute properties. * @brief Sets a string as a extended attribute properties.
* *
* @param file The file to set the string to. * @param file The file to set the string to.
* @param attribute The attribute to set. * @param attribute The attribute to set.
@ -213,7 +213,7 @@ EAPI Eina_Bool eina_xattr_fd_del(int fd, const char *attribute) EINA_ARG_NONNULL
EAPI Eina_Bool eina_xattr_string_set(const char *file, const char *attribute, const char *data, Eina_Xattr_Flags flags); EAPI Eina_Bool eina_xattr_string_set(const char *file, const char *attribute, const char *data, Eina_Xattr_Flags flags);
/** /**
* @brief Get a string from an extended attribute properties. * @brief Gets a string from an extended attribute properties.
* *
* @param file The file to get the string from. * @param file The file to get the string from.
* @param attribute The attribute to get. * @param attribute The attribute to get.
@ -226,7 +226,7 @@ EAPI Eina_Bool eina_xattr_string_set(const char *file, const char *attribute, co
EAPI char *eina_xattr_string_get(const char *file, const char *attribute); EAPI char *eina_xattr_string_get(const char *file, const char *attribute);
/** /**
* @brief Set a double as a extended attribute properties. * @brief Sets a double as a extended attribute properties.
* *
* @param file The file to set the double to. * @param file The file to set the double to.
* @param attribute The attribute to set. * @param attribute The attribute to set.
@ -239,7 +239,7 @@ EAPI char *eina_xattr_string_get(const char *file, const char *attribute);
EAPI Eina_Bool eina_xattr_double_set(const char *file, const char *attribute, double value, Eina_Xattr_Flags flags); EAPI Eina_Bool eina_xattr_double_set(const char *file, const char *attribute, double value, Eina_Xattr_Flags flags);
/** /**
* @brief Get a double from an extended attribute properties. * @brief Gets a double from an extended attribute properties.
* *
* @param file The file to get the string from. * @param file The file to get the string from.
* @param attribute The attribute to get. * @param attribute The attribute to get.
@ -253,7 +253,7 @@ EAPI Eina_Bool eina_xattr_double_set(const char *file, const char *attribute, do
EAPI Eina_Bool eina_xattr_double_get(const char *file, const char *attribute, double *value); EAPI Eina_Bool eina_xattr_double_get(const char *file, const char *attribute, double *value);
/** /**
* @brief Set an int as a extended attribute properties. * @brief Sets an int as a extended attribute properties.
* *
* @param file The file to set the int to. * @param file The file to set the int to.
* @param attribute The attribute to set. * @param attribute The attribute to set.
@ -266,7 +266,7 @@ EAPI Eina_Bool eina_xattr_double_get(const char *file, const char *attribute, do
EAPI Eina_Bool eina_xattr_int_set(const char *file, const char *attribute, int value, Eina_Xattr_Flags flags); EAPI Eina_Bool eina_xattr_int_set(const char *file, const char *attribute, int value, Eina_Xattr_Flags flags);
/** /**
* @brief Get a int from an extended attribute properties. * @brief Gets a int from an extended attribute properties.
* *
* @param file The file to get the string from. * @param file The file to get the string from.
* @param attribute The attribute to get. * @param attribute The attribute to get.