diff options
author | Christian Grothoff <christian@grothoff.org> | 2013-10-08 06:55:36 +0000 |
---|---|---|
committer | Christian Grothoff <christian@grothoff.org> | 2013-10-08 06:55:36 +0000 |
commit | 8657dfcfcf8d1c4c9861e414a793d9759dd5c4c0 (patch) | |
tree | 8166827913f6b3eb685ae7ac7f6d6a23220b6d54 /src/include/gnunet_strings_lib.h | |
parent | 06f3ffeab2cf652874a0539eaafa34762fe360b3 (diff) | |
download | gnunet-8657dfcfcf8d1c4c9861e414a793d9759dd5c4c0.tar.gz gnunet-8657dfcfcf8d1c4c9861e414a793d9759dd5c4c0.zip |
more strings documentation
Diffstat (limited to 'src/include/gnunet_strings_lib.h')
-rw-r--r-- | src/include/gnunet_strings_lib.h | 68 |
1 files changed, 39 insertions, 29 deletions
diff --git a/src/include/gnunet_strings_lib.h b/src/include/gnunet_strings_lib.h index 6fbdb6e8e..7927ade30 100644 --- a/src/include/gnunet_strings_lib.h +++ b/src/include/gnunet_strings_lib.h | |||
@@ -76,6 +76,7 @@ GNUNET_STRINGS_fancy_time_to_relative (const char *fancy_time, | |||
76 | 76 | ||
77 | 77 | ||
78 | /** | 78 | /** |
79 | * @ingroup time | ||
79 | * Convert a given fancy human-readable time to our internal | 80 | * Convert a given fancy human-readable time to our internal |
80 | * representation. The human-readable time is expected to be | 81 | * representation. The human-readable time is expected to be |
81 | * in local time, whereas the returned value will be in UTC. | 82 | * in local time, whereas the returned value will be in UTC. |
@@ -103,6 +104,11 @@ GNUNET_STRINGS_byte_size_fancy (unsigned long long size); | |||
103 | * Convert the len characters long character sequence | 104 | * Convert the len characters long character sequence |
104 | * given in input that is in the given input charset | 105 | * given in input that is in the given input charset |
105 | * to a string in given output charset. | 106 | * to a string in given output charset. |
107 | * | ||
108 | * @param input input string | ||
109 | * @param len number of bytes in @a input | ||
110 | * @param input_charset character set used for @a input | ||
111 | * @param ouptut_charset desired character set for the return value | ||
106 | * @return the converted string (0-terminated), | 112 | * @return the converted string (0-terminated), |
107 | * if conversion fails, a copy of the orignal | 113 | * if conversion fails, a copy of the orignal |
108 | * string is returned. | 114 | * string is returned. |
@@ -119,7 +125,7 @@ GNUNET_STRINGS_conv (const char *input, size_t len, | |||
119 | * to UTF-8. | 125 | * to UTF-8. |
120 | * | 126 | * |
121 | * @param input the input string (not necessarily 0-terminated) | 127 | * @param input the input string (not necessarily 0-terminated) |
122 | * @param len the number of bytes in the input | 128 | * @param len the number of bytes in the @a input |
123 | * @param charset character set to convert from | 129 | * @param charset character set to convert from |
124 | * @return the converted string (0-terminated) | 130 | * @return the converted string (0-terminated) |
125 | */ | 131 | */ |
@@ -132,7 +138,10 @@ GNUNET_STRINGS_to_utf8 (const char *input, | |||
132 | /** | 138 | /** |
133 | * Convert the len bytes-long UTF-8 string | 139 | * Convert the len bytes-long UTF-8 string |
134 | * given in input to the given charset. | 140 | * given in input to the given charset. |
135 | 141 | * | |
142 | * @param input the input string (not necessarily 0-terminated) | ||
143 | * @param len the number of bytes in the @a input | ||
144 | * @param charset character set to convert to | ||
136 | * @return the converted string (0-terminated), | 145 | * @return the converted string (0-terminated), |
137 | * if conversion fails, a copy of the orignal | 146 | * if conversion fails, a copy of the orignal |
138 | * string is returned. | 147 | * string is returned. |
@@ -211,23 +220,25 @@ GNUNET_STRINGS_buffer_fill (char *buffer, | |||
211 | * to the locations of the respective strings in the buffer. | 220 | * to the locations of the respective strings in the buffer. |
212 | * | 221 | * |
213 | * @param buffer the buffer to parse | 222 | * @param buffer the buffer to parse |
214 | * @param size size of the buffer | 223 | * @param size size of the @a buffer |
215 | * @param count number of strings to locate | 224 | * @param count number of strings to locate |
216 | * @param ... pointers to where to store the strings | 225 | * @param ... pointers to where to store the strings |
217 | * @return offset of the character after the last 0-termination | 226 | * @return offset of the character after the last 0-termination |
218 | * in the buffer, or 0 on error. | 227 | * in the buffer, or 0 on error. |
219 | */ | 228 | */ |
220 | unsigned int | 229 | unsigned int |
221 | GNUNET_STRINGS_buffer_tokenize (const char *buffer, size_t size, | 230 | GNUNET_STRINGS_buffer_tokenize (const char *buffer, |
231 | size_t size, | ||
222 | unsigned int count, ...); | 232 | unsigned int count, ...); |
223 | 233 | ||
224 | 234 | ||
225 | 235 | ||
226 | /** | 236 | /** |
227 | * "asctime", except for GNUnet time. Converts a GNUnet internal | 237 | * @ingroup time |
238 | * Like `asctime`, except for GNUnet time. Converts a GNUnet internal | ||
228 | * absolute time (which is in UTC) to a string in local time. | 239 | * absolute time (which is in UTC) to a string in local time. |
229 | * This is one of the very few calls in the entire API that is | 240 | * Note that the returned value will be overwritten if this function |
230 | * NOT reentrant! | 241 | * is called again. |
231 | * | 242 | * |
232 | * @param t the absolute time to convert | 243 | * @param t the absolute time to convert |
233 | * @return timestamp in human-readable form in local time | 244 | * @return timestamp in human-readable form in local time |
@@ -237,6 +248,7 @@ GNUNET_STRINGS_absolute_time_to_string (struct GNUNET_TIME_Absolute t); | |||
237 | 248 | ||
238 | 249 | ||
239 | /** | 250 | /** |
251 | * @ingroup time | ||
240 | * Give relative time in human-readable fancy format. | 252 | * Give relative time in human-readable fancy format. |
241 | * This is one of the very few calls in the entire API that is | 253 | * This is one of the very few calls in the entire API that is |
242 | * NOT reentrant! | 254 | * NOT reentrant! |
@@ -294,8 +306,8 @@ GNUNET_STRINGS_data_to_string (const void *data, | |||
294 | * @param enc the encoding | 306 | * @param enc the encoding |
295 | * @param enclen number of characters in 'enc' (without 0-terminator, which can be missing) | 307 | * @param enclen number of characters in 'enc' (without 0-terminator, which can be missing) |
296 | * @param out location where to store the decoded data | 308 | * @param out location where to store the decoded data |
297 | * @param out_size size of the output buffer | 309 | * @param out_size size of the output buffer @a out |
298 | * @return GNUNET_OK on success, GNUNET_SYSERR if result has the wrong encoding | 310 | * @return #GNUNET_OK on success, #GNUNET_SYSERR if result has the wrong encoding |
299 | */ | 311 | */ |
300 | int | 312 | int |
301 | GNUNET_STRINGS_string_to_data (const char *enc, | 313 | GNUNET_STRINGS_string_to_data (const char *enc, |
@@ -316,7 +328,7 @@ GNUNET_STRINGS_string_to_data (const char *enc, | |||
316 | * part of the URI will be stored. Can be NULL. Points to the same block | 328 | * part of the URI will be stored. Can be NULL. Points to the same block |
317 | * of memory as 'path', and thus must not be freed. Might point to '\0', | 329 | * of memory as 'path', and thus must not be freed. Might point to '\0', |
318 | * if path part is zero-length. | 330 | * if path part is zero-length. |
319 | * @return GNUNET_YES if it's an URI, GNUNET_NO otherwise. If 'path' is not | 331 | * @return #GNUNET_YES if it's an URI, #GNUNET_NO otherwise. If 'path' is not |
320 | * an URI, '* scheme_part' and '*path_part' will remain unchanged | 332 | * an URI, '* scheme_part' and '*path_part' will remain unchanged |
321 | * (if they weren't NULL). | 333 | * (if they weren't NULL). |
322 | */ | 334 | */ |
@@ -330,15 +342,15 @@ GNUNET_STRINGS_parse_uri (const char *path, | |||
330 | * Check whether filename is absolute or not, and if it's an URI | 342 | * Check whether filename is absolute or not, and if it's an URI |
331 | * | 343 | * |
332 | * @param filename filename to check | 344 | * @param filename filename to check |
333 | * @param can_be_uri GNUNET_YES to check for being URI, GNUNET_NO - to | 345 | * @param can_be_uri #GNUNET_YES to check for being URI, #GNUNET_NO - to |
334 | * assume it's not URI | 346 | * assume it's not URI |
335 | * @param r_is_uri a pointer to an int that is set to GNUNET_YES if 'filename' | 347 | * @param r_is_uri a pointer to an int that is set to #GNUNET_YES if 'filename' |
336 | * is URI and to GNUNET_NO otherwise. Can be NULL. If 'can_be_uri' is | 348 | * is URI and to GNUNET_NO otherwise. Can be NULL. If 'can_be_uri' is |
337 | * not GNUNET_YES, *r_is_uri is set to GNUNET_NO. | 349 | * not #GNUNET_YES, *r_is_uri is set to #GNUNET_NO. |
338 | * @param r_uri_scheme a pointer to a char * that is set to a pointer to URI scheme. | 350 | * @param r_uri_scheme a pointer to a char * that is set to a pointer to URI scheme. |
339 | * The string is allocated by the function, and should be freed with | 351 | * The string is allocated by the function, and should be freed with |
340 | * GNUNET_free (). Can be NULL. | 352 | * GNUNET_free (). Can be NULL. |
341 | * @return GNUNET_YES if 'filename' is absolute, GNUNET_NO otherwise. | 353 | * @return #GNUNET_YES if 'filename' is absolute, #GNUNET_NO otherwise. |
342 | */ | 354 | */ |
343 | int | 355 | int |
344 | GNUNET_STRINGS_path_is_absolute (const char *filename, | 356 | GNUNET_STRINGS_path_is_absolute (const char *filename, |
@@ -375,7 +387,7 @@ enum GNUNET_STRINGS_FilenameCheck | |||
375 | 387 | ||
376 | 388 | ||
377 | /** | 389 | /** |
378 | * Perform checks on 'filename'. FIXME: some duplication with | 390 | * Perform checks on @a filename. FIXME: some duplication with |
379 | * "GNUNET_DISK_"-APIs. We should unify those. | 391 | * "GNUNET_DISK_"-APIs. We should unify those. |
380 | * | 392 | * |
381 | * @param filename file to check | 393 | * @param filename file to check |
@@ -389,14 +401,14 @@ GNUNET_STRINGS_check_filename (const char *filename, | |||
389 | 401 | ||
390 | 402 | ||
391 | /** | 403 | /** |
392 | * Tries to convert 'zt_addr' string to an IPv6 address. | 404 | * Tries to convert @a zt_addr string to an IPv6 address. |
393 | * The string is expected to have the format "[ABCD::01]:80". | 405 | * The string is expected to have the format "[ABCD::01]:80". |
394 | * | 406 | * |
395 | * @param zt_addr 0-terminated string. May be mangled by the function. | 407 | * @param zt_addr 0-terminated string. May be mangled by the function. |
396 | * @param addrlen length of zt_addr (not counting 0-terminator). | 408 | * @param addrlen length of zt_addr (not counting 0-terminator). |
397 | * @param r_buf a buffer to fill. Initially gets filled with zeroes, | 409 | * @param r_buf a buffer to fill. Initially gets filled with zeroes, |
398 | * then its sin6_port, sin6_family and sin6_addr are set appropriately. | 410 | * then its sin6_port, sin6_family and sin6_addr are set appropriately. |
399 | * @return GNUNET_OK if conversion succeded. GNUNET_SYSERR otherwise, in which | 411 | * @return #GNUNET_OK if conversion succeded. #GNUNET_SYSERR otherwise, in which |
400 | * case the contents of r_buf are undefined. | 412 | * case the contents of r_buf are undefined. |
401 | */ | 413 | */ |
402 | int | 414 | int |
@@ -406,13 +418,13 @@ GNUNET_STRINGS_to_address_ipv6 (const char *zt_addr, | |||
406 | 418 | ||
407 | 419 | ||
408 | /** | 420 | /** |
409 | * Tries to convert 'zt_addr' string to an IPv4 address. | 421 | * Tries to convert @a zt_addr string to an IPv4 address. |
410 | * The string is expected to have the format "1.2.3.4:80". | 422 | * The string is expected to have the format "1.2.3.4:80". |
411 | * | 423 | * |
412 | * @param zt_addr 0-terminated string. May be mangled by the function. | 424 | * @param zt_addr 0-terminated string. May be mangled by the function. |
413 | * @param addrlen length of zt_addr (not counting 0-terminator). | 425 | * @param addrlen length of zt_addr (not counting 0-terminator). |
414 | * @param r_buf a buffer to fill. | 426 | * @param r_buf a buffer to fill. |
415 | * @return GNUNET_OK if conversion succeded. GNUNET_SYSERR otherwise, in which case | 427 | * @return #GNUNET_OK if conversion succeded. #GNUNET_SYSERR otherwise, in which case |
416 | * the contents of r_buf are undefined. | 428 | * the contents of r_buf are undefined. |
417 | */ | 429 | */ |
418 | int | 430 | int |
@@ -422,14 +434,14 @@ GNUNET_STRINGS_to_address_ipv4 (const char *zt_addr, | |||
422 | 434 | ||
423 | 435 | ||
424 | /** | 436 | /** |
425 | * Tries to convert 'addr' string to an IP (v4 or v6) address. | 437 | * Tries to convert @a addr string to an IP (v4 or v6) address. |
426 | * Will automatically decide whether to treat 'addr' as v4 or v6 address. | 438 | * Will automatically decide whether to treat 'addr' as v4 or v6 address. |
427 | * | 439 | * |
428 | * @param addr a string, may not be 0-terminated. | 440 | * @param addr a string, may not be 0-terminated. |
429 | * @param addrlen number of bytes in addr (if addr is 0-terminated, | 441 | * @param addrlen number of bytes in @a addr (if addr is 0-terminated, |
430 | * 0-terminator should not be counted towards addrlen). | 442 | * 0-terminator should not be counted towards addrlen). |
431 | * @param r_buf a buffer to fill. | 443 | * @param r_buf a buffer to fill. |
432 | * @return GNUNET_OK if conversion succeded. GNUNET_SYSERR otherwise, in which | 444 | * @return #GNUNET_OK if conversion succeded. #GNUNET_SYSERR otherwise, in which |
433 | * case the contents of r_buf are undefined. | 445 | * case the contents of r_buf are undefined. |
434 | */ | 446 | */ |
435 | int | 447 | int |
@@ -439,18 +451,16 @@ GNUNET_STRINGS_to_address_ip (const char *addr, | |||
439 | 451 | ||
440 | 452 | ||
441 | /** | 453 | /** |
442 | * Returns utf-8 encoded arguments. | 454 | * Returns utf-8 encoded arguments. Does nothing (returns a copy of |
443 | * Does nothing (returns a copy of argc and argv) on any platform | 455 | * @a argc and @a argv) on any platform other than W32. Returned @a |
444 | * other than W32. | 456 | * argv has `u8argv[u8argc] == NULL`. Returned @a argv is a single |
445 | * Returned argv has u8argv[u8argc] == NULL. | 457 | * memory block, and can be freed with a single GNUNET_free() call. |
446 | * Returned argv is a single memory block, and can be freed with a single | ||
447 | * GNUNET_free () call. | ||
448 | * | 458 | * |
449 | * @param argc argc (as given by main()) | 459 | * @param argc argc (as given by main()) |
450 | * @param argv argv (as given by main()) | 460 | * @param argv argv (as given by main()) |
451 | * @param u8argc a location to store new argc in (though it's th same as argc) | 461 | * @param u8argc a location to store new argc in (though it's th same as argc) |
452 | * @param u8argv a location to store new argv in | 462 | * @param u8argv a location to store new argv in |
453 | * @return GNUNET_OK on success, GNUNET_SYSERR on failure | 463 | * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure |
454 | */ | 464 | */ |
455 | int | 465 | int |
456 | GNUNET_STRINGS_get_utf8_args (int argc, | 466 | GNUNET_STRINGS_get_utf8_args (int argc, |