comparison: src/cx/string.h
src/cx/string.h
- changeset 1127
- 1fd31909a3f8
- parent 1107
- 9d77c7a99441
equal
deleted
inserted
replaced
| 1126:20c9212b3a47 | 1127:1fd31909a3f8 |
|---|---|
| 296 #endif | 296 #endif |
| 297 | 297 |
| 298 /** | 298 /** |
| 299 * Passes the pointer in this string to @c free(). | 299 * Passes the pointer in this string to @c free(). |
| 300 * | 300 * |
| 301 * The pointer in the struct is set to @c NULL and the length is set to zero. | 301 * The pointer in the struct is set to @c NULL and the length is set to zero |
| 302 * which means that this function protects you against double-free. | |
| 302 * | 303 * |
| 303 * @note There is no implementation for cxstring, because it is unlikely that | 304 * @note There is no implementation for cxstring, because it is unlikely that |
| 304 * you ever have a <code>const char*</code> you are really supposed to free. | 305 * you ever have a <code>const char*</code> you are really supposed to free. |
| 305 * If you encounter such situation, you should double-check your code. | 306 * If you encounter such situation, you should double-check your code. |
| 306 * | 307 * |
| 309 void cx_strfree(cxmutstr *str); | 310 void cx_strfree(cxmutstr *str); |
| 310 | 311 |
| 311 /** | 312 /** |
| 312 * Passes the pointer in this string to the allocators free function. | 313 * Passes the pointer in this string to the allocators free function. |
| 313 * | 314 * |
| 314 * The pointer in the struct is set to @c NULL and the length is set to zero. | 315 * The pointer in the struct is set to @c NULL and the length is set to zero |
| 316 * which means that this function protects you against double-free. | |
| 315 * | 317 * |
| 316 * @note There is no implementation for cxstring, because it is unlikely that | 318 * @note There is no implementation for cxstring, because it is unlikely that |
| 317 * you ever have a <code>const char*</code> you are really supposed to free. | 319 * you ever have a <code>const char*</code> you are really supposed to free. |
| 318 * If you encounter such situation, you should double-check your code. | 320 * If you encounter such situation, you should double-check your code. |
| 319 * | 321 * |
| 843 * The new string will contain a copy allocated by standard | 845 * The new string will contain a copy allocated by standard |
| 844 * @c malloc(). So developers @em must pass the return value to cx_strfree(). | 846 * @c malloc(). So developers @em must pass the return value to cx_strfree(). |
| 845 * | 847 * |
| 846 * @note The returned string is guaranteed to be zero-terminated. | 848 * @note The returned string is guaranteed to be zero-terminated. |
| 847 * | 849 * |
| 848 * @param string (@c cxstring) the string to duplicate | 850 * @param string the string to duplicate |
| 849 * @return (@c cxmutstr) a duplicate of the string | 851 * @return (@c cxmutstr) a duplicate of the string |
| 850 * @see cx_strdup_a() | 852 * @see cx_strdup_a() |
| 853 * @see cx_strfree() | |
| 851 */ | 854 */ |
| 852 #define cx_strdup(string) cx_strdup_a(cxDefaultAllocator, string) | 855 #define cx_strdup(string) cx_strdup_a(cxDefaultAllocator, string) |
| 853 | |
| 854 | |
| 855 /** | |
| 856 * Creates a duplicate of the specified string. | |
| 857 * | |
| 858 * The new string will contain a copy allocated by @p allocator. | |
| 859 * | |
| 860 * @note The returned string is guaranteed to be zero-terminated. | |
| 861 * | |
| 862 * @param allocator (@c CxAllocator*) the allocator to use | |
| 863 * @param string (@c cxmutstr) the string to duplicate | |
| 864 * @return (@c cxmutstr) a duplicate of the string | |
| 865 * @see cx_strdup_m() | |
| 866 */ | |
| 867 #define cx_strdup_ma(allocator, string) cx_strdup_a(allocator, cx_strcast(string)) | |
| 868 | |
| 869 /** | |
| 870 * Creates a duplicate of the specified string. | |
| 871 * | |
| 872 * The new string will contain a copy allocated by standard | |
| 873 * @c malloc(). So developers @em must pass the return value to cx_strfree(). | |
| 874 * | |
| 875 * @note The returned string is guaranteed to be zero-terminated. | |
| 876 * | |
| 877 * @param string (@c cxmutstr) the string to duplicate | |
| 878 * @return (@c cxmutstr) a duplicate of the string | |
| 879 * @see cx_strdup_ma() | |
| 880 */ | |
| 881 #define cx_strdup_m(string) cx_strdup_a(cxDefaultAllocator, cx_strcast(string)) | |
| 882 | 856 |
| 883 /** | 857 /** |
| 884 * Omits leading and trailing spaces. | 858 * Omits leading and trailing spaces. |
| 885 * | 859 * |
| 886 * @note the returned string references the same memory, thus you | 860 * @note the returned string references the same memory, thus you |
| 1084 cxstring delim, | 1058 cxstring delim, |
| 1085 size_t limit | 1059 size_t limit |
| 1086 ); | 1060 ); |
| 1087 | 1061 |
| 1088 /** | 1062 /** |
| 1089 * Creates a string tokenization context for a mutable string. | |
| 1090 * | |
| 1091 * @param str the string to tokenize | |
| 1092 * @param delim the delimiter (must not be empty) | |
| 1093 * @param limit the maximum number of tokens that shall be returned | |
| 1094 * @return a new string tokenization context | |
| 1095 */ | |
| 1096 cx_attr_nodiscard | |
| 1097 CxStrtokCtx cx_strtok_m( | |
| 1098 cxmutstr str, | |
| 1099 cxstring delim, | |
| 1100 size_t limit | |
| 1101 ); | |
| 1102 | |
| 1103 /** | |
| 1104 * Returns the next token. | 1063 * Returns the next token. |
| 1105 * | 1064 * |
| 1106 * The token will point to the source string. | 1065 * The token will point to the source string. |
| 1107 * | 1066 * |
| 1108 * @param ctx the tokenization context | 1067 * @param ctx the tokenization context |
| 1120 | 1079 |
| 1121 /** | 1080 /** |
| 1122 * Returns the next token of a mutable string. | 1081 * Returns the next token of a mutable string. |
| 1123 * | 1082 * |
| 1124 * The token will point to the source string. | 1083 * The token will point to the source string. |
| 1084 * | |
| 1085 * @attention | |
| 1125 * If the context was not initialized over a mutable string, modifying | 1086 * If the context was not initialized over a mutable string, modifying |
| 1126 * the data of the returned token is undefined behavior. | 1087 * the data of the returned token is undefined behavior. |
| 1127 * | 1088 * |
| 1128 * @param ctx the tokenization context | 1089 * @param ctx the tokenization context |
| 1129 * @param token a pointer to memory where the next token shall be stored | 1090 * @param token a pointer to memory where the next token shall be stored |
| 1543 * @retval zero success | 1504 * @retval zero success |
| 1544 * @retval non-zero conversion was not possible | 1505 * @retval non-zero conversion was not possible |
| 1545 */ | 1506 */ |
| 1546 #define cx_strtod(str, output) cx_strtod_lc(str, output, '.', ",") | 1507 #define cx_strtod(str, output) cx_strtod_lc(str, output, '.', ",") |
| 1547 | 1508 |
| 1509 /** | |
| 1510 * Creates a duplicate of the specified string. | |
| 1511 * | |
| 1512 * The new string will contain a copy allocated by @p allocator. | |
| 1513 * | |
| 1514 * @note The returned string is guaranteed to be zero-terminated. | |
| 1515 * | |
| 1516 * @param allocator (@c CxAllocator*) the allocator to use | |
| 1517 * @param string the string to duplicate | |
| 1518 * @return (@c cxmutstr) a duplicate of the string | |
| 1519 * @see cx_strdup() | |
| 1520 * @see cx_strfree_a() | |
| 1521 */ | |
| 1522 #define cx_strdup_a(allocator, string) \ | |
| 1523 cx_strdup_a((allocator), cx_strcast(string)) | |
| 1524 | |
| 1525 /** | |
| 1526 * Creates a string tokenization context. | |
| 1527 * | |
| 1528 * @param str the string to tokenize | |
| 1529 * @param delim the delimiter string (must not be empty) | |
| 1530 * @param limit (@c @size_t) the maximum number of tokens that shall be returned | |
| 1531 * @return (@c CxStrtokCtx) a new string tokenization context | |
| 1532 */ | |
| 1533 #define cx_strtok(str, delim, limit) \ | |
| 1534 cx_strtok(cx_strcast(str), cx_strcast(delim), (limit)) | |
| 1535 | |
| 1548 #endif | 1536 #endif |
| 1549 | 1537 |
| 1550 #ifdef __cplusplus | 1538 #ifdef __cplusplus |
| 1551 } // extern "C" | 1539 } // extern "C" |
| 1552 #endif | 1540 #endif |
