From f5e5d41b47f64dfc8dc9a08e2b6d3317a92f256d Mon Sep 17 00:00:00 2001 From: caro Date: Tue, 23 Sep 2008 15:57:57 +0000 Subject: [PATCH] add main doc for eina_convert git-svn-id: http://svn.enlightenment.org/svn/e/trunk/PROTO/eina@36187 7cbeb6ba-43b4-40fd-8cce-4c39aea84d33 --- src/include/eina_lalloc.h | 22 +++++++-- src/lib/eina_convert.c | 114 +++++++++++++++++++++++++++++++++++++++++++++- src/lib/eina_lalloc.c | 36 ++++++++------- 3 files changed, 149 insertions(+), 23 deletions(-) diff --git a/src/include/eina_lalloc.h b/src/include/eina_lalloc.h index 91bdcaa..99de0fd 100644 --- a/src/include/eina_lalloc.h +++ b/src/include/eina_lalloc.h @@ -22,7 +22,14 @@ #include "eina_types.h" /** - * @defgroup Lalloc_Group Lazy allocator + * @addtogroup Eina_Tools_Group Tools + * + * @{ + */ + +/** + * @defgroup Eina_Lalloc_Group Lazy allocator + * * @{ */ @@ -32,11 +39,18 @@ typedef void (*Eina_Lalloc_Free) (void *user_data); #define EINA_LALLOC_FREE(function) ((Eina_Lalloc_Free)function) typedef struct _Eina_Lalloc Eina_Lalloc; -EAPI void eina_lalloc_delete(Eina_Lalloc *a); + EAPI Eina_Lalloc *eina_lalloc_new(void *data, Eina_Lalloc_Alloc alloc_cb, Eina_Lalloc_Free free_cb, int num_init); +EAPI void eina_lalloc_delete(Eina_Lalloc *a); EAPI Eina_Bool eina_lalloc_elements_add(Eina_Lalloc *a, int num); EAPI Eina_Bool eina_lalloc_element_add(Eina_Lalloc *a); -/** @} */ +/** + * @} + */ + +/** + * @} + */ -#endif +#endif /* EINA_LALLOC_H_ */ diff --git a/src/lib/eina_convert.c b/src/lib/eina_convert.c index ce96f01..ef9a46b 100644 --- a/src/lib/eina_convert.c +++ b/src/lib/eina_convert.c @@ -89,6 +89,115 @@ EAPI Eina_Error EINA_ERROR_CONVERT_OUTRUN_STRING_LENGTH = 0; * These functions allow you to convert integer or real numbers to * string or conversely. * + * To use these function, you have to call eina_convert_init() + * first, and eina_convert_shutdown() when they are not used anymore. + * + * @section Eina_Convert_From_Integer_To_Sring Conversion from integer to string + * + * To convert an integer to a string in the decimal base, + * eina_convert_itoa() should be used. If the hexadecimal base is + * wanted, eina_convert_xtoa() should be used. They all need a bufffer + * sufficiently large to store all the cyphers. + * + * Here is an exemple of use: + * + * @code + * #include + * #include + * + * #include + * + * int main(void) + * { + * char *tmp[128]; + * + * if (!eina_convert_init()) + * { + * printf ("Error during the initialization of eina_convert module\n"); + * return EXIT_FAILURE; + * } + * + * eina_convert_itoa(45, tmp); + * printf("value: %s\n", tmp); + + * eina_convert_xtoa(0xA1, tmp); + * printf("value: %s\n", tmp); + * + * eina_convert_shutdown(); + * + * return EXIT_SUCCESS; + * } + * @endcode + * + * Compile this code with the following commant: + * + * @code + * gcc -Wall -o test_eina_convert test_eina.c `pkg-config --cflags --libs eina` + * @endcode + * + * @note + * The alphabetical cyphers are in lower case. + * + * @section Eina_Convert_Double Conversion double / string + * + * To convert a double to a string, eina_convert_dtoa() should be + * used. Like with the integer functions, a buffer must be used. The + * resulting string ghas the following format (which is the result + * obtained with snprintf() and the @%a modifier): + * + * @code + * [-]0xh.hhhhhp[+-]e + * @endcode + * + * To convert a string to a double, eina_convert_atod() should be + * used. The format of the string must be as above. Then, the double + * has the following mantiss and exponent: + * + * @code + * mantiss : [-]hhhhhh + * exponent : 2^([+-]e - 4 * n) + * @endcode + * + * with n being number of cypers after the point in the string + * format. To obtain the double number from the mantiss and exponent, + * use ldexp(). + * + * Here is an exemple of use: + * + * @code + * #include + * #include + * + * #include + * + * int main(void) + * { + * char *tmp[128]; + * long long int m = 0; + * long int e = 0; + * doule r; + * + * if (!eina_convert_init()) + * { + * printf ("Error during the initialization of eina_convert module\n"); + * return EXIT_FAILURE; + * } + * + * eina_convert_dtoa(40.56, tmp); + * printf("value: %s\n", tmp); + + * eina_convert_atod(tmp, 128, &m, &e); + * r = ldexp((double)m, e); + * printf("value: %s\n", tmp); + * + * eina_convert_shutdown(); + * + * return EXIT_SUCCESS; + * } + * @endcode + * + * Compile this code with the same command as above. + * * @{ */ @@ -195,8 +304,9 @@ eina_convert_itoa(int n, char *s) * character. * * This function converts @p n to a nul terminated string. The - * converted string is in hexadecimal base. As no check is done, @p s - * must be a buffer that is sufficiently large to store the integer. + * converted string is in hexadecimal base and the alphabetical + * cyphers are in lower case. As no check is done, @p s must be a + * buffer that is sufficiently large to store the integer. * * The returned value is the length os the string, including the nul * terminated character. diff --git a/src/lib/eina_lalloc.c b/src/lib/eina_lalloc.c index c78e92f..50f5699 100644 --- a/src/lib/eina_lalloc.c +++ b/src/lib/eina_lalloc.c @@ -29,6 +29,10 @@ * Local * *============================================================================*/ +/** + * @cond LOCAL + */ + struct _Eina_Lalloc { void *data; @@ -39,6 +43,10 @@ struct _Eina_Lalloc Eina_Lalloc_Free free_cb; }; +/** + * @endcond + */ + /*============================================================================* * Global * *============================================================================*/ @@ -48,9 +56,11 @@ struct _Eina_Lalloc *============================================================================*/ /** - * To be documented - * FIXME: To be fixed + * @addtogroup Eina_Lalloc_Group Lazy allocator + * + * @{ */ + EAPI Eina_Lalloc * eina_lalloc_new(void *data, Eina_Lalloc_Alloc alloc_cb, Eina_Lalloc_Free free_cb, int num_init) { Eina_Lalloc *a; @@ -67,10 +77,12 @@ EAPI Eina_Lalloc * eina_lalloc_new(void *data, Eina_Lalloc_Alloc alloc_cb, Eina_ return a; } -/** - * To be documented - * FIXME: To be fixed - */ +EAPI void eina_lalloc_delete(Eina_Lalloc *a) +{ + a->free_cb(a->data); + free(a); +} + EAPI Eina_Bool eina_lalloc_element_add(Eina_Lalloc *a) { if (a->num_elements == a->num_allocated) @@ -88,10 +100,6 @@ EAPI Eina_Bool eina_lalloc_element_add(Eina_Lalloc *a) return EINA_TRUE; } -/** - * To be documented - * FIXME: To be fixed - */ EAPI Eina_Bool eina_lalloc_elements_add(Eina_Lalloc *a, int num) { int tmp; @@ -125,11 +133,5 @@ EAPI Eina_Bool eina_lalloc_elements_add(Eina_Lalloc *a, int num) } /** - * To be documented - * FIXME: To be fixed + * @} */ -EAPI void eina_lalloc_delete(Eina_Lalloc *a) -{ - a->free_cb(a->data); - free(a); -} -- 2.7.4