diff options
Diffstat (limited to '')
-rw-r--r-- | libraries/eina/src/include/eina_convert.h | 374 |
1 files changed, 374 insertions, 0 deletions
diff --git a/libraries/eina/src/include/eina_convert.h b/libraries/eina/src/include/eina_convert.h new file mode 100644 index 0000000..af839e2 --- /dev/null +++ b/libraries/eina/src/include/eina_convert.h | |||
@@ -0,0 +1,374 @@ | |||
1 | /* EINA - EFL data type library | ||
2 | * Copyright (C) 2008 Cedric BAIL, Vincent Torri | ||
3 | * | ||
4 | * This library is free software; you can redistribute it and/or | ||
5 | * modify it under the terms of the GNU Lesser General Public | ||
6 | * License as published by the Free Software Foundation; either | ||
7 | * version 2.1 of the License, or (at your option) any later version. | ||
8 | * | ||
9 | * This library is distributed in the hope that it will be useful, | ||
10 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
11 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||
12 | * Lesser General Public License for more details. | ||
13 | * | ||
14 | * You should have received a copy of the GNU Lesser General Public | ||
15 | * License along with this library; | ||
16 | * if not, see <http://www.gnu.org/licenses/>. | ||
17 | */ | ||
18 | |||
19 | #ifndef EINA_CONVERT_H_ | ||
20 | #define EINA_CONVERT_H_ | ||
21 | |||
22 | #include "eina_types.h" | ||
23 | #include "eina_error.h" | ||
24 | |||
25 | #include "eina_fp.h" | ||
26 | |||
27 | |||
28 | /** | ||
29 | * @addtogroup Eina_Convert_Group Convert | ||
30 | * | ||
31 | * These functions allow you to convert integer or real numbers to | ||
32 | * string or conversely. | ||
33 | * | ||
34 | * To use these functions, you have to call eina_init() | ||
35 | * first, and eina_shutdown() when eina is not used anymore. | ||
36 | * | ||
37 | * @section Eina_Convert_From_Integer_To_Sring Conversion from integer to string | ||
38 | * | ||
39 | * To convert an integer to a string in the decimal base, | ||
40 | * eina_convert_itoa() should be used. If the hexadecimal base is | ||
41 | * wanted, eina_convert_xtoa() should be used. They all need a bufffer | ||
42 | * sufficiently large to store all the cyphers. | ||
43 | * | ||
44 | * Here is an example of use: | ||
45 | * | ||
46 | * @code | ||
47 | * #include <stdlib.h> | ||
48 | * #include <stdio.h> | ||
49 | * | ||
50 | * #include <Eina.h> | ||
51 | * | ||
52 | * int main(void) | ||
53 | * { | ||
54 | * char tmp[128]; | ||
55 | * | ||
56 | * if (!eina_init()) | ||
57 | * { | ||
58 | * printf ("Error during the initialization of eina.\n"); | ||
59 | * return EXIT_FAILURE; | ||
60 | * } | ||
61 | * | ||
62 | * eina_convert_itoa(45, tmp); | ||
63 | * printf("value: %s\n", tmp); | ||
64 | * eina_convert_xtoa(0xA1, tmp); | ||
65 | * printf("value: %s\n", tmp); | ||
66 | * | ||
67 | * eina_shutdown(); | ||
68 | * | ||
69 | * return EXIT_SUCCESS; | ||
70 | * } | ||
71 | * @endcode | ||
72 | * | ||
73 | * Compile this code with the following command: | ||
74 | * | ||
75 | * @code | ||
76 | * gcc -Wall -o test_eina_convert test_eina.c `pkg-config --cflags --libs eina` | ||
77 | * @endcode | ||
78 | * | ||
79 | * @note | ||
80 | * The alphabetical cyphers are in lower case. | ||
81 | * | ||
82 | * @section Eina_Convert_Double Conversion double / string | ||
83 | * | ||
84 | * To convert a double to a string, eina_convert_dtoa() should be | ||
85 | * used. Like with the integer functions, a buffer must be used. The | ||
86 | * resulting string ghas the following format (which is the result | ||
87 | * obtained with snprintf() and the @%a modifier): | ||
88 | * | ||
89 | * @code | ||
90 | * [-]0xh.hhhhhp[+-]e | ||
91 | * @endcode | ||
92 | * | ||
93 | * To convert a string to a double, eina_convert_atod() should be | ||
94 | * used. The format of the string must be as above. Then, the double | ||
95 | * has the following mantiss and exponent: | ||
96 | * | ||
97 | * @code | ||
98 | * mantiss : [-]hhhhhh | ||
99 | * exponent : 2^([+-]e - 4 * n) | ||
100 | * @endcode | ||
101 | * | ||
102 | * with n being number of cypers after the point in the string | ||
103 | * format. To obtain the double number from the mantiss and exponent, | ||
104 | * use ldexp(). | ||
105 | * | ||
106 | * Here is an example of use: | ||
107 | * | ||
108 | * @code | ||
109 | * #include <stdlib.h> | ||
110 | * #include <stdio.h> | ||
111 | * #include <math.h> | ||
112 | * | ||
113 | * #include <Eina.h> | ||
114 | * | ||
115 | * int main(void) | ||
116 | * { | ||
117 | * char tmp[128]; | ||
118 | * long long int m = 0; | ||
119 | * long int e = 0; | ||
120 | * double r; | ||
121 | * | ||
122 | * if (!eina_init()) | ||
123 | * { | ||
124 | * printf ("Error during the initialization of eina.\n"); | ||
125 | * return EXIT_FAILURE; | ||
126 | * } | ||
127 | * | ||
128 | * printf("initial value : 40.56\n"); | ||
129 | * eina_convert_dtoa(40.56, tmp); | ||
130 | * printf("result dtoa : %s\n", tmp); | ||
131 | |||
132 | * eina_convert_atod(tmp, 128, &m, &e); | ||
133 | * r = ldexp((double)m, e); | ||
134 | * printf("result atod : %f\n", r); | ||
135 | * | ||
136 | * eina_shutdown(); | ||
137 | * | ||
138 | * return EXIT_SUCCESS; | ||
139 | * } | ||
140 | * @endcode | ||
141 | * | ||
142 | * Compile this code with the following command: | ||
143 | * | ||
144 | * @code | ||
145 | * gcc -Wall -o test_eina_convert test_eina.c `pkg-config --cflags --libs eina` -lm | ||
146 | * @endcode | ||
147 | */ | ||
148 | |||
149 | /** | ||
150 | * @addtogroup Eina_Tools_Group Tools | ||
151 | * | ||
152 | * @{ | ||
153 | */ | ||
154 | |||
155 | /** | ||
156 | * @defgroup Eina_Convert_Group Convert | ||
157 | * | ||
158 | * @{ | ||
159 | */ | ||
160 | |||
161 | /** | ||
162 | * @var EINA_ERROR_CONVERT_P_NOT_FOUND | ||
163 | * Error identifier corresponding to string not containing 'p'. | ||
164 | */ | ||
165 | |||
166 | EAPI extern Eina_Error EINA_ERROR_CONVERT_P_NOT_FOUND; | ||
167 | |||
168 | /** | ||
169 | * @var EINA_ERROR_CONVERT_0X_NOT_FOUND | ||
170 | * Error identifier corresponding to string not containing '0x'. | ||
171 | */ | ||
172 | EAPI extern Eina_Error EINA_ERROR_CONVERT_0X_NOT_FOUND; | ||
173 | |||
174 | /** | ||
175 | * @var EINA_ERROR_CONVERT_OUTRUN_STRING_LENGTH | ||
176 | * Error identifier corresponding to length of the string being too small. | ||
177 | */ | ||
178 | EAPI extern Eina_Error EINA_ERROR_CONVERT_OUTRUN_STRING_LENGTH; | ||
179 | |||
180 | /** | ||
181 | * @brief Convert an integer number to a string in decimal base. | ||
182 | * | ||
183 | * @param n The integer to convert. | ||
184 | * @param s The buffer to store the converted integer. | ||
185 | * @return The length of the string, including the nul terminated | ||
186 | * character. | ||
187 | * | ||
188 | * This function converts @p n to a nul terminated string. The | ||
189 | * converted string is in decimal base. As no check is done, @p s must | ||
190 | * be a buffer that is sufficiently large to store the integer. | ||
191 | * | ||
192 | * The returned value is the length of the string, including the nul | ||
193 | * terminated character. | ||
194 | */ | ||
195 | EAPI int eina_convert_itoa(int n, char *s) EINA_ARG_NONNULL(2); | ||
196 | |||
197 | /** | ||
198 | * @brief Convert an integer number to a string in hexadecimal base. | ||
199 | * | ||
200 | * @param n The integer to convert. | ||
201 | * @param s The buffer to store the converted integer. | ||
202 | * @return The length of the string, including the nul terminated | ||
203 | * character. | ||
204 | * | ||
205 | * This function converts @p n to a nul terminated string. The | ||
206 | * converted string is in hexadecimal base and the alphabetical | ||
207 | * cyphers are in lower case. As no check is done, @p s must be a | ||
208 | * buffer that is sufficiently large to store the integer. | ||
209 | * | ||
210 | * The returned value is the length of the string, including the nul | ||
211 | * terminated character. | ||
212 | */ | ||
213 | EAPI int eina_convert_xtoa(unsigned int n, char *s) EINA_ARG_NONNULL(2); | ||
214 | |||
215 | |||
216 | /** | ||
217 | * @brief Convert a double to a string. | ||
218 | * | ||
219 | * @param d The double to convert. | ||
220 | * @param des The destination buffer to store the converted double. | ||
221 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
222 | * | ||
223 | * This function converts the double @p d to a string. The string is | ||
224 | * stored in the buffer pointed by @p des and must be sufficiently | ||
225 | * large to contain the converted double. The returned string is nul | ||
226 | * terminated and has the following format: | ||
227 | * | ||
228 | * @code | ||
229 | * [-]0xh.hhhhhp[+-]e | ||
230 | * @endcode | ||
231 | * | ||
232 | * where the h are the hexadecimal cyphers of the mantiss and e the | ||
233 | * exponent (a decimal number). | ||
234 | * | ||
235 | * The returned value is the length of the string, including the nul | ||
236 | * character. | ||
237 | */ | ||
238 | EAPI int eina_convert_dtoa(double d, char *des) EINA_ARG_NONNULL(2); | ||
239 | |||
240 | /** | ||
241 | * @brief Convert a string to a double. | ||
242 | * | ||
243 | * @param src The string to convert. | ||
244 | * @param length The length of the string. | ||
245 | * @param m The mantisse. | ||
246 | * @param e The exponent. | ||
247 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
248 | * | ||
249 | * This function converts the string @p s of length @p length that | ||
250 | * represent a double in hexadecimal base to a double. It is used to | ||
251 | * replace the use of snprintf() with the \%a modifier, which is | ||
252 | * missing on some platform (like Windows (tm) or OpenBSD). | ||
253 | * | ||
254 | * The string must have the following format: | ||
255 | * | ||
256 | * @code | ||
257 | * [-]0xh.hhhhhp[+-]e | ||
258 | * @endcode | ||
259 | * | ||
260 | * where the h are the hexadecimal cyphers of the mantiss and e the | ||
261 | * exponent (a decimal number). If n is the number of cypers after the | ||
262 | * point, the returned mantiss and exponents are: | ||
263 | * | ||
264 | * @code | ||
265 | * mantiss : [-]hhhhhh | ||
266 | * exponent : 2^([+-]e - 4 * n) | ||
267 | * @endcode | ||
268 | * | ||
269 | * The mantiss and exponent are stored in the buffers pointed | ||
270 | * respectively by @p m and @p e. | ||
271 | * | ||
272 | * If the string is invalid, the error is set to: | ||
273 | * | ||
274 | * @li #EINA_ERROR_CONVERT_0X_NOT_FOUND if no 0x is found, | ||
275 | * @li #EINA_ERROR_CONVERT_P_NOT_FOUND if no p is found, | ||
276 | * @li #EINA_ERROR_CONVERT_OUTRUN_STRING_LENGTH if @p length is not | ||
277 | * correct. | ||
278 | * | ||
279 | * In those cases, #EINA_FALSE is returned, otherwise #EINA_TRUE is | ||
280 | * returned. | ||
281 | */ | ||
282 | EAPI Eina_Bool eina_convert_atod(const char *src, | ||
283 | int length, | ||
284 | long long *m, | ||
285 | long *e) EINA_ARG_NONNULL(1, 3, 4); | ||
286 | |||
287 | |||
288 | /** | ||
289 | * @brief Convert a 32.32 fixed point number to a string. | ||
290 | * | ||
291 | * @param fp The fixed point number to convert. | ||
292 | * @param des The destination buffer to store the converted fixed point number. | ||
293 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
294 | * | ||
295 | * This function converts the 32.32 fixed point number @p fp to a | ||
296 | * string. The string is stored in the buffer pointed by @p des and | ||
297 | * must be sufficiently large to contain the converted fixed point | ||
298 | * number. The returned string is terminated and has the following | ||
299 | * format: | ||
300 | * | ||
301 | * @code | ||
302 | * [-]0xh.hhhhhp[+-]e | ||
303 | * @endcode | ||
304 | * | ||
305 | * where the h are the hexadecimal cyphers of the mantiss and e the | ||
306 | * exponent (a decimal number). | ||
307 | * | ||
308 | * The returned value is the length of the string, including the nul | ||
309 | * character. | ||
310 | * | ||
311 | * @note The code is the same than eina_convert_dtoa() except that it | ||
312 | * implements the frexp() function for fixed point numbers and does | ||
313 | * some optimisations. | ||
314 | */ | ||
315 | EAPI int eina_convert_fptoa(Eina_F32p32 fp, | ||
316 | char *des) EINA_ARG_NONNULL(2); | ||
317 | |||
318 | /** | ||
319 | * @brief Convert a string to a 32.32 fixed point number. | ||
320 | * | ||
321 | * @param src The string to convert. | ||
322 | * @param length The length of the string. | ||
323 | * @param fp The fixed point number. | ||
324 | * @return #EINA_TRUE on success, #EINA_FALSE otherwise. | ||
325 | * | ||
326 | * This function converts the string @p src of length @p length that | ||
327 | * represent a double in hexadecimal base to a 32.32 fixed point | ||
328 | * number stored in @p fp. The function always tries to convert the | ||
329 | * string with eina_convert_atod(). | ||
330 | * | ||
331 | * The string must have the following format: | ||
332 | * | ||
333 | * @code | ||
334 | * [-]0xh.hhhhhp[+-]e | ||
335 | * @endcode | ||
336 | * | ||
337 | * where the h are the hexadecimal cyphers of the mantiss and e the | ||
338 | * exponent (a decimal number). If n is the number of cypers after the | ||
339 | * point, the returned mantiss and exponents are: | ||
340 | * | ||
341 | * @code | ||
342 | * mantiss : [-]hhhhhh | ||
343 | * exponent : 2^([+-]e - 4 * n) | ||
344 | * @endcode | ||
345 | * | ||
346 | * The mantiss and exponent are stored in the buffers pointed | ||
347 | * respectively by @p m and @p e. | ||
348 | * | ||
349 | * If the string is invalid, the error is set to: | ||
350 | * | ||
351 | * @li #EINA_ERROR_CONVERT_0X_NOT_FOUND if no 0x is found, | ||
352 | * @li #EINA_ERROR_CONVERT_P_NOT_FOUND if no p is found, | ||
353 | * @li #EINA_ERROR_CONVERT_OUTRUN_STRING_LENGTH if @p length is not | ||
354 | * correct. | ||
355 | * | ||
356 | * In those cases, or if @p fp is @c NULL, #EINA_FALSE is returned, | ||
357 | * otherwise @p fp is computed and #EINA_TRUE is returned. | ||
358 | * | ||
359 | * @note The code uses eina_convert_atod() and do the correct bit | ||
360 | * shift to compute the fixed point number. | ||
361 | */ | ||
362 | EAPI Eina_Bool eina_convert_atofp(const char *src, | ||
363 | int length, | ||
364 | Eina_F32p32 *fp) EINA_ARG_NONNULL(1, 3); | ||
365 | |||
366 | /** | ||
367 | * @} | ||
368 | */ | ||
369 | |||
370 | /** | ||
371 | * @} | ||
372 | */ | ||
373 | |||
374 | #endif /* EINA_CONVERT_H_ */ | ||