aboutsummaryrefslogtreecommitdiffstats
path: root/src/lib/eina/eina_convert.h
diff options
context:
space:
mode:
authorthe81.kim@samsung.com <ohpowel@gmail.com>2014-11-21 14:55:46 +0900
committerTae-Hwan Kim <ohpowel@gmail.com>2014-11-21 14:55:46 +0900
commit2853f0221716603dc8241b52e111e65d4017d84e (patch)
tree3a7b6f8bc51cc25901ce6a86c30cc59ef61395fe /src/lib/eina/eina_convert.h
parentelua: update eolian bindings (diff)
downloadefl-devs/bluezery/doc.tar.gz
Documentation from Tizendevs/bluezery/doc
Diffstat (limited to 'src/lib/eina/eina_convert.h')
-rw-r--r--src/lib/eina/eina_convert.h253
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_ */