From d44242d02cf55120cb8b44918e6266e6d571ed98 Mon Sep 17 00:00:00 2001 From: Carsten Haitzler Date: Thu, 7 Apr 2011 11:39:20 +0000 Subject: [PATCH] more doxy -> h SVN revision: 58420 --- legacy/eina/src/include/eina_convert.h | 300 +++++++++++++++++++++++++ legacy/eina/src/lib/eina_convert.c | 290 ------------------------ 2 files changed, 300 insertions(+), 290 deletions(-) diff --git a/legacy/eina/src/include/eina_convert.h b/legacy/eina/src/include/eina_convert.h index 447ac7b8f2..b06d7d43e5 100644 --- a/legacy/eina/src/include/eina_convert.h +++ b/legacy/eina/src/include/eina_convert.h @@ -24,6 +24,130 @@ #include "eina_fp.h" + +/** + * @addtogroup Eina_Convert_Group Convert + * + * These functions allow you to convert integer or real numbers to + * string or conversely. + * + * To use these functions, you have to call eina_init() + * first, and eina_shutdown() when eina is not used anymore. + * + * @section Eina_Convert_From_Integer_To_Sring Conversion from integer to string + * + * To convert an integer to a string in the decimal base, + * eina_convert_itoa() should be used. If the hexadecimal base is + * wanted, eina_convert_xtoa() should be used. They all need a bufffer + * sufficiently large to store all the cyphers. + * + * Here is an example of use: + * + * @code + * #include + * #include + * + * #include + * + * int main(void) + * { + * char tmp[128]; + * + * if (!eina_init()) + * { + * printf ("Error during the initialization of eina.\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_shutdown(); + * + * return EXIT_SUCCESS; + * } + * @endcode + * + * Compile this code with the following command: + * + * @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 example of use: + * + * @code + * #include + * #include + * #include + * + * #include + * + * int main(void) + * { + * char tmp[128]; + * long long int m = 0; + * long int e = 0; + * double r; + * + * if (!eina_init()) + * { + * printf ("Error during the initialization of eina.\n"); + * return EXIT_FAILURE; + * } + * + * printf("initial value : 40.56\n"); + * eina_convert_dtoa(40.56, tmp); + * printf("result dtoa : %s\n", tmp); + + * eina_convert_atod(tmp, 128, &m, &e); + * r = ldexp((double)m, e); + * printf("result atod : %f\n", r); + * + * eina_shutdown(); + * + * return EXIT_SUCCESS; + * } + * @endcode + * + * Compile this code with the following command: + * + * @code + * gcc -Wall -o test_eina_convert test_eina.c `pkg-config --cflags --libs eina` -lm + * @endcode + * + * @{ + */ + /** * @addtogroup Eina_Tools_Group Tools * @@ -40,6 +164,7 @@ * @var EINA_ERROR_CONVERT_P_NOT_FOUND * Error identifier corresponding to string not containing 'p'. */ + EAPI extern Eina_Error EINA_ERROR_CONVERT_P_NOT_FOUND; /** @@ -54,17 +179,188 @@ EAPI extern Eina_Error EINA_ERROR_CONVERT_0X_NOT_FOUND; */ EAPI extern Eina_Error EINA_ERROR_CONVERT_OUTRUN_STRING_LENGTH; +/** + * @brief Convert an integer number to a string in decimal base. + * + * @param n The integer to convert. + * @param s The buffer to store the converted integer. + * @return The length of the string, including the nul terminated + * character. + * + * This function converts @p n to a nul terminated string. The + * converted string is in decimal base. As no check is done, @p s must + * be a buffer that is sufficiently large to store the integer. + * + * The returned value is the length of the string, including the nul + * terminated character. + */ EAPI int eina_convert_itoa(int n, char *s) EINA_ARG_NONNULL(2); + +/** + * @brief Convert an integer number to a string in hexadecimal base. + * + * @param n The integer to convert. + * @param s The buffer to store the converted integer. + * @return The length of the string, including the nul terminated + * character. + * + * This function converts @p n to a nul terminated string. The + * converted string is in hexadecimal base and the alphabetical + * cyphers are in lower case. As no check is done, @p s must be a + * buffer that is sufficiently large to store the integer. + * + * The returned value is the length of the string, including the nul + * terminated character. + */ EAPI int eina_convert_xtoa(unsigned int n, char *s) EINA_ARG_NONNULL(2); + +/** + * @brief Convert a double to a string. + * + * @param d The double to convert. + * @param des The destination buffer to store the converted double. + * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * + * This function converts the double @p d to a string. The string is + * stored in the buffer pointed by @p des and must be sufficiently + * large to contain the converted double. The returned string is nul + * terminated and has the following format: + * + * @code + * [-]0xh.hhhhhp[+-]e + * @endcode + * + * where the h are the hexadecimal cyphers of the mantiss and e the + * exponent (a decimal number). + * + * The returned value is the length of the string, including the nul + * character. + */ EAPI int eina_convert_dtoa(double d, char *des) EINA_ARG_NONNULL(2); + +/** + * @brief Convert a string to a double. + * + * @param src The string to convert. + * @param length The length of the string. + * @param m The mantisse. + * @param e The exponent. + * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * + * This function converts the string @p s of length @p length that + * represent a double in hexadecimal base to a double. It is used to + * replace the use of snprintf() with the \%a modifier, which is + * missing on some platform (like Windows (tm) or OpenBSD). + * + * The string must have the following format: + * + * @code + * [-]0xh.hhhhhp[+-]e + * @endcode + * + * where the h are the hexadecimal cyphers of the mantiss and e the + * exponent (a decimal number). If n is the number of cypers after the + * point, the returned mantiss and exponents are: + * + * @code + * mantiss : [-]hhhhhh + * exponent : 2^([+-]e - 4 * n) + * @endcode + * + * The mantiss and exponent are stored in the buffers pointed + * respectively by @p m and @p e. + * + * If the string is invalid, the error is set to: + * + * @li #EINA_ERROR_CONVERT_0X_NOT_FOUND if no 0x is found, + * @li #EINA_ERROR_CONVERT_P_NOT_FOUND if no p is found, + * @li #EINA_ERROR_CONVERT_OUTRUN_STRING_LENGTH if @p length is not + * correct. + * + * In those cases, #EINA_FALSE is returned, otherwise #EINA_TRUE is + * returned. + */ EAPI Eina_Bool eina_convert_atod(const char *src, int length, long long *m, long *e) EINA_ARG_NONNULL(1, 3, 4); + +/** + * @brief Convert a 32.32 fixed point number to a string. + * + * @param fp The fixed point number to convert. + * @param des The destination buffer to store the converted fixed point number. + * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * + * This function converts the 32.32 fixed point number @p fp to a + * string. The string is stored in the buffer pointed by @p des and + * must be sufficiently large to contain the converted fixed point + * number. The returned string is terminated and has the following + * format: + * + * @code + * [-]0xh.hhhhhp[+-]e + * @endcode + * + * where the h are the hexadecimal cyphers of the mantiss and e the + * exponent (a decimal number). + * + * The returned value is the length of the string, including the nul + * character. + * + * @note The code is the same than eina_convert_dtoa() except that it + * implements the frexp() function for fixed point numbers and does + * some optimisations. + */ EAPI int eina_convert_fptoa(Eina_F32p32 fp, char *des) EINA_ARG_NONNULL(2); + +/** + * @brief Convert a string to a 32.32 fixed point number. + * + * @param src The string to convert. + * @param length The length of the string. + * @param fp The fixed point number. + * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * + * This function converts the string @p src of length @p length that + * represent a double in hexadecimal base to a 32.32 fixed point + * number stored in @p fp. The function always tries to convert the + * string with eina_convert_atod(). + * + * The string must have the following format: + * + * @code + * [-]0xh.hhhhhp[+-]e + * @endcode + * + * where the h are the hexadecimal cyphers of the mantiss and e the + * exponent (a decimal number). If n is the number of cypers after the + * point, the returned mantiss and exponents are: + * + * @code + * mantiss : [-]hhhhhh + * exponent : 2^([+-]e - 4 * n) + * @endcode + * + * The mantiss and exponent are stored in the buffers pointed + * respectively by @p m and @p e. + * + * If the string is invalid, the error is set to: + * + * @li #EINA_ERROR_CONVERT_0X_NOT_FOUND if no 0x is found, + * @li #EINA_ERROR_CONVERT_P_NOT_FOUND if no p is found, + * @li #EINA_ERROR_CONVERT_OUTRUN_STRING_LENGTH if @p length is not + * correct. + * + * In those cases, or if @p fp is @c NULL, #EINA_FALSE is returned, + * otherwise @p fp is computed and #EINA_TRUE is returned. + * + * @note The code uses eina_convert_atod() and do the correct bit + * shift to compute the fixed point number. + */ EAPI Eina_Bool eina_convert_atofp(const char *src, int length, Eina_F32p32 *fp) EINA_ARG_NONNULL(1, 3); @@ -77,4 +373,8 @@ EAPI Eina_Bool eina_convert_atofp(const char *src, * @} */ +/** + * @} + */ + #endif /* EINA_CONVERT_H_ */ diff --git a/legacy/eina/src/lib/eina_convert.c b/legacy/eina/src/lib/eina_convert.c index 0d75469ca0..63b6654b93 100644 --- a/legacy/eina/src/lib/eina_convert.c +++ b/legacy/eina/src/lib/eina_convert.c @@ -162,149 +162,10 @@ eina_convert_shutdown(void) * API * *============================================================================*/ -/** - * @addtogroup Eina_Convert_Group Convert - * - * These functions allow you to convert integer or real numbers to - * string or conversely. - * - * To use these functions, you have to call eina_init() - * first, and eina_shutdown() when eina is not used anymore. - * - * @section Eina_Convert_From_Integer_To_Sring Conversion from integer to string - * - * To convert an integer to a string in the decimal base, - * eina_convert_itoa() should be used. If the hexadecimal base is - * wanted, eina_convert_xtoa() should be used. They all need a bufffer - * sufficiently large to store all the cyphers. - * - * Here is an example of use: - * - * @code - * #include - * #include - * - * #include - * - * int main(void) - * { - * char tmp[128]; - * - * if (!eina_init()) - * { - * printf ("Error during the initialization of eina.\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_shutdown(); - * - * return EXIT_SUCCESS; - * } - * @endcode - * - * Compile this code with the following command: - * - * @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 example of use: - * - * @code - * #include - * #include - * #include - * - * #include - * - * int main(void) - * { - * char tmp[128]; - * long long int m = 0; - * long int e = 0; - * double r; - * - * if (!eina_init()) - * { - * printf ("Error during the initialization of eina.\n"); - * return EXIT_FAILURE; - * } - * - * printf("initial value : 40.56\n"); - * eina_convert_dtoa(40.56, tmp); - * printf("result dtoa : %s\n", tmp); - - * eina_convert_atod(tmp, 128, &m, &e); - * r = ldexp((double)m, e); - * printf("result atod : %f\n", r); - * - * eina_shutdown(); - * - * return EXIT_SUCCESS; - * } - * @endcode - * - * Compile this code with the following command: - * - * @code - * gcc -Wall -o test_eina_convert test_eina.c `pkg-config --cflags --libs eina` -lm - * @endcode - * - * @{ - */ - /* * Come from the second edition of The C Programming Language ("K&R2") on page 64 */ -/** - * @brief Convert an integer number to a string in decimal base. - * - * @param n The integer to convert. - * @param s The buffer to store the converted integer. - * @return The length of the string, including the nul terminated - * character. - * - * This function converts @p n to a nul terminated string. The - * converted string is in decimal base. As no check is done, @p s must - * be a buffer that is sufficiently large to store the integer. - * - * The returned value is the length of the string, including the nul - * terminated character. - */ EAPI int eina_convert_itoa(int n, char *s) { @@ -331,22 +192,6 @@ eina_convert_itoa(int n, char *s) return i + r; } -/** - * @brief Convert an integer number to a string in hexadecimal base. - * - * @param n The integer to convert. - * @param s The buffer to store the converted integer. - * @return The length of the string, including the nul terminated - * character. - * - * This function converts @p n to a nul terminated string. The - * converted string is in hexadecimal base and the alphabetical - * cyphers are in lower case. As no check is done, @p s must be a - * buffer that is sufficiently large to store the integer. - * - * The returned value is the length of the string, including the nul - * terminated character. - */ EAPI int eina_convert_xtoa(unsigned int n, char *s) { @@ -366,48 +211,6 @@ eina_convert_xtoa(unsigned int n, char *s) return i; } -/** - * @brief Convert a string to a double. - * - * @param src The string to convert. - * @param length The length of the string. - * @param m The mantisse. - * @param e The exponent. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. - * - * This function converts the string @p s of length @p length that - * represent a double in hexadecimal base to a double. It is used to - * replace the use of snprintf() with the \%a modifier, which is - * missing on some platform (like Windows (tm) or OpenBSD). - * - * The string must have the following format: - * - * @code - * [-]0xh.hhhhhp[+-]e - * @endcode - * - * where the h are the hexadecimal cyphers of the mantiss and e the - * exponent (a decimal number). If n is the number of cypers after the - * point, the returned mantiss and exponents are: - * - * @code - * mantiss : [-]hhhhhh - * exponent : 2^([+-]e - 4 * n) - * @endcode - * - * The mantiss and exponent are stored in the buffers pointed - * respectively by @p m and @p e. - * - * If the string is invalid, the error is set to: - * - * @li #EINA_ERROR_CONVERT_0X_NOT_FOUND if no 0x is found, - * @li #EINA_ERROR_CONVERT_P_NOT_FOUND if no p is found, - * @li #EINA_ERROR_CONVERT_OUTRUN_STRING_LENGTH if @p length is not - * correct. - * - * In those cases, #EINA_FALSE is returned, otherwise #EINA_TRUE is - * returned. - */ EAPI Eina_Bool eina_convert_atod(const char *src, int length, long long *m, long *e) { @@ -506,28 +309,6 @@ on_length_error: return EINA_FALSE; } -/** - * @brief Convert a double to a string. - * - * @param d The double to convert. - * @param des The destination buffer to store the converted double. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. - * - * This function converts the double @p d to a string. The string is - * stored in the buffer pointed by @p des and must be sufficiently - * large to contain the converted double. The returned string is nul - * terminated and has the following format: - * - * @code - * [-]0xh.hhhhhp[+-]e - * @endcode - * - * where the h are the hexadecimal cyphers of the mantiss and e the - * exponent (a decimal number). - * - * The returned value is the length of the string, including the nul - * character. - */ EAPI int eina_convert_dtoa(double d, char *des) { @@ -591,33 +372,6 @@ eina_convert_dtoa(double d, char *des) return length + eina_convert_itoa(p, des); } -/** - * @brief Convert a 32.32 fixed point number to a string. - * - * @param fp The fixed point number to convert. - * @param des The destination buffer to store the converted fixed point number. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. - * - * This function converts the 32.32 fixed point number @p fp to a - * string. The string is stored in the buffer pointed by @p des and - * must be sufficiently large to contain the converted fixed point - * number. The returned string is terminated and has the following - * format: - * - * @code - * [-]0xh.hhhhhp[+-]e - * @endcode - * - * where the h are the hexadecimal cyphers of the mantiss and e the - * exponent (a decimal number). - * - * The returned value is the length of the string, including the nul - * character. - * - * @note The code is the same than eina_convert_dtoa() except that it - * implements the frexp() function for fixed point numbers and does - * some optimisations. - */ EAPI int eina_convert_fptoa(Eina_F32p32 fp, char *des) { @@ -702,50 +456,6 @@ eina_convert_fptoa(Eina_F32p32 fp, char *des) return length + eina_convert_itoa(p, des); } -/** - * @brief Convert a string to a 32.32 fixed point number. - * - * @param src The string to convert. - * @param length The length of the string. - * @param fp The fixed point number. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. - * - * This function converts the string @p src of length @p length that - * represent a double in hexadecimal base to a 32.32 fixed point - * number stored in @p fp. The function always tries to convert the - * string with eina_convert_atod(). - * - * The string must have the following format: - * - * @code - * [-]0xh.hhhhhp[+-]e - * @endcode - * - * where the h are the hexadecimal cyphers of the mantiss and e the - * exponent (a decimal number). If n is the number of cypers after the - * point, the returned mantiss and exponents are: - * - * @code - * mantiss : [-]hhhhhh - * exponent : 2^([+-]e - 4 * n) - * @endcode - * - * The mantiss and exponent are stored in the buffers pointed - * respectively by @p m and @p e. - * - * If the string is invalid, the error is set to: - * - * @li #EINA_ERROR_CONVERT_0X_NOT_FOUND if no 0x is found, - * @li #EINA_ERROR_CONVERT_P_NOT_FOUND if no p is found, - * @li #EINA_ERROR_CONVERT_OUTRUN_STRING_LENGTH if @p length is not - * correct. - * - * In those cases, or if @p fp is @c NULL, #EINA_FALSE is returned, - * otherwise @p fp is computed and #EINA_TRUE is returned. - * - * @note The code uses eina_convert_atod() and do the correct bit - * shift to compute the fixed point number. - */ EAPI Eina_Bool eina_convert_atofp(const char *src, int length, Eina_F32p32 *fp) {