--- a/src/cx/string.h Wed Jan 15 19:32:53 2025 +0100 +++ b/src/cx/string.h Wed Jan 15 19:42:49 2025 +0100 @@ -298,7 +298,8 @@ /** * Passes the pointer in this string to @c free(). * - * The pointer in the struct is set to @c NULL and the length is set to zero. + * The pointer in the struct is set to @c NULL and the length is set to zero + * which means that this function protects you against double-free. * * @note There is no implementation for cxstring, because it is unlikely that * you ever have a <code>const char*</code> you are really supposed to free. @@ -311,7 +312,8 @@ /** * Passes the pointer in this string to the allocators free function. * - * The pointer in the struct is set to @c NULL and the length is set to zero. + * The pointer in the struct is set to @c NULL and the length is set to zero + * which means that this function protects you against double-free. * * @note There is no implementation for cxstring, because it is unlikely that * you ever have a <code>const char*</code> you are really supposed to free. @@ -845,41 +847,13 @@ * * @note The returned string is guaranteed to be zero-terminated. * - * @param string (@c cxstring) the string to duplicate + * @param string the string to duplicate * @return (@c cxmutstr) a duplicate of the string * @see cx_strdup_a() + * @see cx_strfree() */ #define cx_strdup(string) cx_strdup_a(cxDefaultAllocator, string) - -/** - * Creates a duplicate of the specified string. - * - * The new string will contain a copy allocated by @p allocator. - * - * @note The returned string is guaranteed to be zero-terminated. - * - * @param allocator (@c CxAllocator*) the allocator to use - * @param string (@c cxmutstr) the string to duplicate - * @return (@c cxmutstr) a duplicate of the string - * @see cx_strdup_m() - */ -#define cx_strdup_ma(allocator, string) cx_strdup_a(allocator, cx_strcast(string)) - -/** - * Creates a duplicate of the specified string. - * - * The new string will contain a copy allocated by standard - * @c malloc(). So developers @em must pass the return value to cx_strfree(). - * - * @note The returned string is guaranteed to be zero-terminated. - * - * @param string (@c cxmutstr) the string to duplicate - * @return (@c cxmutstr) a duplicate of the string - * @see cx_strdup_ma() - */ -#define cx_strdup_m(string) cx_strdup_a(cxDefaultAllocator, cx_strcast(string)) - /** * Omits leading and trailing spaces. * @@ -1086,21 +1060,6 @@ ); /** -* Creates a string tokenization context for a mutable string. -* -* @param str the string to tokenize -* @param delim the delimiter (must not be empty) -* @param limit the maximum number of tokens that shall be returned -* @return a new string tokenization context -*/ -cx_attr_nodiscard -CxStrtokCtx cx_strtok_m( - cxmutstr str, - cxstring delim, - size_t limit -); - -/** * Returns the next token. * * The token will point to the source string. @@ -1122,6 +1081,8 @@ * Returns the next token of a mutable string. * * The token will point to the source string. + * + * @attention * If the context was not initialized over a mutable string, modifying * the data of the returned token is undefined behavior. * @@ -1545,6 +1506,33 @@ */ #define cx_strtod(str, output) cx_strtod_lc(str, output, '.', ",") +/** + * Creates a duplicate of the specified string. + * + * The new string will contain a copy allocated by @p allocator. + * + * @note The returned string is guaranteed to be zero-terminated. + * + * @param allocator (@c CxAllocator*) the allocator to use + * @param string the string to duplicate + * @return (@c cxmutstr) a duplicate of the string + * @see cx_strdup() + * @see cx_strfree_a() + */ +#define cx_strdup_a(allocator, string) \ + cx_strdup_a((allocator), cx_strcast(string)) + +/** + * Creates a string tokenization context. + * + * @param str the string to tokenize + * @param delim the delimiter string (must not be empty) + * @param limit (@c @size_t) the maximum number of tokens that shall be returned + * @return (@c CxStrtokCtx) a new string tokenization context + */ +#define cx_strtok(str, delim, limit) \ + cx_strtok(cx_strcast(str), cx_strcast(delim), (limit)) + #endif #ifdef __cplusplus