diff options
Diffstat (limited to 'src/lib/eina/eina_convert.h')
| -rw-r--r-- | src/lib/eina/eina_convert.h | 253 |
1 files changed, 142 insertions, 111 deletions
diff --git a/src/lib/eina/eina_convert.h b/src/lib/eina/eina_convert.h index be65cc404e..588a7e185c 100644 --- a/src/lib/eina/eina_convert.h +++ b/src/lib/eina/eina_convert.h @@ -1,14 +1,14 @@ /* EINA - EFL data type library * Copyright (C) 2008 Cedric BAIL, Vincent Torri * - * This library is free software; you can redistribute it and/or + * This library is a free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public @@ -26,22 +26,23 @@ /** - * @addtogroup Eina_Convert_Group Convert + * @defgroup Eina_Convert_Group Convert + * @ingroup Eina_Tools_Group * - * These functions allow you to convert integer or real numbers to - * string or conversely. + * @brief This group discusses the functions that allow you to convert an + * integer or real numbers to a string or conversely. * * To use these functions, you have to call eina_init() - * first, and eina_shutdown() when eina is not used anymore. + * first, and then eina_shutdown() when eina is not used anymore. * * @section Eina_Convert_From_Integer_To_Sring Conversion from integer to string * * To convert an integer to a string in the decimal base, * eina_convert_itoa() should be used. If the hexadecimal base is - * wanted, eina_convert_xtoa() should be used. They all need a buffer + * wanted, eina_convert_xtoa() should be used. They all need a buffer that is * sufficiently large to store all the cyphers. * - * Here is an example of use: + * Here is an example for use: * * @code * #include <stdlib.h> @@ -76,15 +77,14 @@ * gcc -Wall -o test_eina_convert test_eina.c `pkg-config --cflags --libs eina` * @endcode * - * @note - * The alphabetical cyphers are in lower case. + * @remarks The alphabetical cyphers are in lower case. * * @section Eina_Convert_Double Conversion double / string * * To convert a double to a string, eina_convert_dtoa() should be * used. Like with the integer functions, a buffer must be used. The * resulting string has the following format (which is the result - * obtained with snprintf() and the @%a modifier): + * obtained with snprintf() and the modifier): * * @code * [-]0xh.hhhhhp[+-]e @@ -92,18 +92,18 @@ * * To convert a string to a double, eina_convert_atod() should be * used. The format of the string must be as above. Then, the double - * has the following mantiss and exponent: + * has the following mantissa and exponent: * * @code * mantiss : [-]hhhhhh * exponent : 2^([+-]e - 4 * n) * @endcode * - * with n being number of cypers after the point in the string - * format. To obtain the double number from the mantiss and exponent, + * with n being the number of cyphers after the point in the string + * format. To obtain the double number from the mantissa and exponent, * use ldexp(). * - * Here is an example of use: + * Here is an example for use: * * @code * #include <stdlib.h> @@ -144,97 +144,107 @@ * @code * gcc -Wall -o test_eina_convert test_eina.c `pkg-config --cflags --libs eina` -lm * @endcode + * + * @{ */ /** - * @addtogroup Eina_Tools_Group Tools - * - * @{ + * @var EINA_ERROR_CONVERT_P_NOT_FOUND + * @brief Error identifier corresponding to string not containing 'p'. */ +EAPI extern Eina_Error EINA_ERROR_CONVERT_P_NOT_FOUND; + /** - * @defgroup Eina_Convert_Group Convert - * - * @{ + * @var EINA_ERROR_CONVERT_0X_NOT_FOUND + * @brief The error identifier corresponding to the string not containing '0x'. */ +EAPI extern Eina_Error EINA_ERROR_CONVERT_0X_NOT_FOUND; -EAPI extern Eina_Error EINA_ERROR_CONVERT_P_NOT_FOUND; /**< Not used, perhaps a placeholder? Defined as 0 in eina_convert.c*/ -EAPI extern Eina_Error EINA_ERROR_CONVERT_0X_NOT_FOUND; /**< Not used, perhaps a placeholder? Defined as 0 in eina_convert.c*/ -EAPI extern Eina_Error EINA_ERROR_CONVERT_OUTRUN_STRING_LENGTH; /**< Not used, perhaps a placeholder? Defined as 0 in eina_convert.c*/ +/** + * @var EINA_ERROR_CONVERT_OUTRUN_STRING_LENGTH + * @brief The error identifier corresponding to the length of the string being too small. + */ +EAPI extern Eina_Error EINA_ERROR_CONVERT_OUTRUN_STRING_LENGTH; /** - * @brief Convert an integer number to a string in decimal base. + * @brief Converts an integer number to a string in decimal base. + * + * @details This function converts @a n to a null terminated string. The + * converted string is in decimal base. As no check is done, @a s must + * be a buffer that is sufficiently large to store the integer. * - * @param n The integer to convert. - * @param s The buffer to store the converted integer. - * @return The length of the string, including the nul terminated - * character. + * @since_tizen 2.3 * - * This function converts @p n to a nul terminated string. The - * converted string is in decimal base. As no check is done, @p s must - * be a buffer that is sufficiently large to store the integer. + * @remarks The returned value is the length of the string, including the null + * terminated character. + * + * @param[in] n The integer to convert + * @param[in] s The buffer to store the converted integer + * @return The length of the string, including the null terminated + * character * - * The returned value is the length of the string, including the nul - * terminated character. */ EAPI int eina_convert_itoa(int n, char *s) EINA_ARG_NONNULL(2); /** - * @brief Convert an integer number to a string in hexadecimal base. + * @brief Converts an integer number to a string in hexadecimal base. + * + * @details This function converts @a n to a null terminated string. The + * converted string is in hexadecimal base and the alphabetical + * cyphers are in lower case. As no check is done, @a s must be a + * buffer that is sufficiently large to store the integer. * - * @param n The integer to convert. - * @param s The buffer to store the converted integer. - * @return The length of the string, including the nul terminated - * character. + * @since_tizen 2.3 * - * This function converts @p n to a nul terminated string. The - * converted string is in hexadecimal base and the alphabetical - * cyphers are in lower case. As no check is done, @p s must be a - * buffer that is sufficiently large to store the integer. + * @remarks The returned value is the length of the string, including the null + * terminated character. + * + * @param[in] n The integer to convert + * @param[in] s The buffer to store the converted integer + * @return The length of the string, including the null terminated + * character * - * The returned value is the length of the string, including the nul - * terminated character. */ EAPI int eina_convert_xtoa(unsigned int n, char *s) EINA_ARG_NONNULL(2); /** - * @brief Convert a double to a string. + * @brief Converts a double to a string. * - * @param d The double to convert. - * @param des The destination buffer to store the converted double. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @details This function converts the double @a d to a string. The string is + * stored in the buffer pointed by @a des and must be sufficiently + * large to contain the converted double. The returned string is null + * terminated and has the following format: * - * This function converts the double @p d to a string. The string is - * stored in the buffer pointed by @p des and must be sufficiently - * large to contain the converted double. The returned string is nul - * terminated and has the following format: + * @since_tizen 2.3 * * @code * [-]0xh.hhhhhp[+-]e * @endcode * - * where the h are the hexadecimal cyphers of the mantiss and e the + * where h are the hexadecimal cyphers of the mantissa and e is the * exponent (a decimal number). * - * The returned value is the length of the string, including the nul - * character. + * @remarks The returned value is the length of the string, including the null + * terminated character. + * + * @param[in] d The double to convert + * @param[in] des The destination buffer to store the converted double + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE + * */ EAPI int eina_convert_dtoa(double d, char *des) EINA_ARG_NONNULL(2); /** - * @brief Convert a string to a double. + * @brief Converts a string to a double. * - * @param src The string to convert. - * @param length The length of the string. - * @param m The mantisse. - * @param e The exponent. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * @details This function converts the string @a s of length @a length that + * represents a double in hexadecimal base to a double. It is used to + * replace the use of snprintf() with the modifier, which is + * missing on some platform (like Windows (tm) or OpenBSD). * - * This function converts the string @p s of length @p length that - * represent a double in hexadecimal base to a double. It is used to - * replace the use of snprintf() with the \%a modifier, which is - * missing on some platform (like Windows (tm) or OpenBSD). + * @since_tizen 2.3 * * The string must have the following format: * @@ -242,20 +252,33 @@ EAPI int eina_convert_dtoa(double d, char *des) EINA_ARG_NONNULL(2); * [-]0xh.hhhhhp[+-]e * @endcode * - * where the h are the hexadecimal cyphers of the mantiss and e the - * exponent (a decimal number). If n is the number of cypers after the - * point, the returned mantiss and exponents are: + * where h are the hexadecimal cyphers of the mantissa and e is the + * exponent (a decimal number). If n is the number of cyphers after the + * point, the returned mantissa and exponent are: * * @code * mantiss : [-]hhhhhh * exponent : 2^([+-]e - 4 * n) * @endcode * - * The mantiss and exponent are stored in the buffers pointed - * respectively by @p m and @p e. + * The mantissa and exponent are stored in the buffers pointed + * by @a m and @a e respectively. + * + * If the string is invalid, the error is set to: * - * If the string is invalid #EINA_FALSE is returned, otherwise #EINA_TRUE is + * @li #EINA_ERROR_CONVERT_0X_NOT_FOUND - If no 0x is found, + * @li #EINA_ERROR_CONVERT_P_NOT_FOUND - If no p is found, + * @li #EINA_ERROR_CONVERT_OUTRUN_STRING_LENGTH If @a length is not correct. + * + * In those cases, @c EINA_FALSE is returned, otherwise @c EINA_TRUE is * returned. + * + * @param[in] src The string to convert + * @param[in] length The length of the string + * @param[out] m The mantissa + * @param[out] e The exponent + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE + * */ EAPI Eina_Bool eina_convert_atod(const char *src, int length, @@ -264,47 +287,45 @@ EAPI Eina_Bool eina_convert_atod(const char *src, /** - * @brief Convert a 32.32 fixed point number to a string. + * @brief Converts a 32.32 fixed point number to a string. * - * @param fp The fixed point number to convert. - * @param des The destination buffer to store the converted fixed point number. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. - * - * This function converts the 32.32 fixed point number @p fp to a - * string. The string is stored in the buffer pointed by @p des and - * must be sufficiently large to contain the converted fixed point - * number. The returned string is terminated and has the following - * format: + * @details This function converts the 32.32 fixed point number @a fp to a + * string. The string is stored in the buffer pointed by @a des and + * must be sufficiently large to contain the converted fixed point + * number. The returned string is terminated and has the following + * format: * * @code * [-]0xh.hhhhhp[+-]e * @endcode * - * where the h are the hexadecimal cyphers of the mantiss and e the + * where h are the hexadecimal cyphers of the mantissa and e is the * exponent (a decimal number). * - * The returned value is the length of the string, including the nul - * character. + * @since_tizen 2.3 + * + * @remarks The returned value is the length of the string, including the null + * terminating character. + * + * @remarks The code is the same as eina_convert_dtoa() except that it + * implements the frexp() function for fixed point numbers and does + * some optimisations. + * + * @param[in] fp The fixed point number to convert + * @param[in] des The destination buffer to store the converted fixed point number + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE * - * @note The code is the same than eina_convert_dtoa() except that it - * implements the frexp() function for fixed point numbers and does - * some optimisations. */ EAPI int eina_convert_fptoa(Eina_F32p32 fp, char *des) EINA_ARG_NONNULL(2); /** - * @brief Convert a string to a 32.32 fixed point number. + * @brief Converts a string to a 32.32 fixed point number. * - * @param src The string to convert. - * @param length The length of the string. - * @param fp The fixed point number. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. - * - * This function converts the string @p src of length @p length that - * represent a double in hexadecimal base to a 32.32 fixed point - * number stored in @p fp. The function always tries to convert the - * string with eina_convert_atod(). + * @details This function converts the string @a src of length @a length that + * represents a double in hexadecimal base to a 32.32 fixed point + * number stored in @a fp. The function always tries to convert the + * string with eina_convert_atod(). * * The string must have the following format: * @@ -312,23 +333,37 @@ EAPI int eina_convert_fptoa(Eina_F32p32 fp, * [-]0xh.hhhhhp[+-]e * @endcode * - * where the h are the hexadecimal cyphers of the mantiss and e the - * exponent (a decimal number). If n is the number of cypers after the - * point, the returned mantiss and exponents are: + * where h are the hexadecimal cyphers of the mantissa and e is the + * exponent (a decimal number). If n is the number of cyphers after the + * point, the returned mantissa and exponent are: * * @code * mantiss : [-]hhhhhh * exponent : 2^([+-]e - 4 * n) * @endcode * - * The mantiss and exponent are stored in the buffers pointed - * respectively by @p m and @p e. + * The mantissa and exponent are stored in the buffers pointed + * by @a m and @a e respectively. + * + * @remarks If the string is invalid, the error is set to: * - * If the string is invalid, #EINA_FALSE is returned, - * otherwise @p fp is computed and #EINA_TRUE is returned. + * @li #EINA_ERROR_CONVERT_0X_NOT_FOUND - If no 0x is found, + * @li #EINA_ERROR_CONVERT_P_NOT_FOUND If no p is found, + * @li #EINA_ERROR_CONVERT_OUTRUN_STRING_LENGTH If @a length is not correct. + * + * In those cases, or if @a fp is @c NULL, @c EINA_FALSE is returned, + * otherwise @a fp is computed and @c EINA_TRUE is returned. + * + * @since_tizen 2.3 + * + * @remarks The code uses eina_convert_atod() and does the correct bit + * shift to compute the fixed point number. + * + * @param[in] src The string to convert + * @param[in] length The length of the string + * @param[out] fp The fixed point number + * @return @c EINA_TRUE on success, otherwise @c EINA_FALSE * - * @note The code uses eina_convert_atod() and do the correct bit - * shift to compute the fixed point number. */ EAPI Eina_Bool eina_convert_atofp(const char *src, int length, @@ -338,8 +373,4 @@ EAPI Eina_Bool eina_convert_atofp(const char *src, * @} */ -/** - * @} - */ - #endif /* EINA_CONVERT_H_ */ |