1.1 --- a/src/cx/string.h Sat Sep 03 15:11:23 2022 +0200
1.2 +++ b/src/cx/string.h Fri Sep 09 20:19:08 2022 +0200
1.3 @@ -78,6 +78,15 @@
1.4 */
1.5 typedef struct cx_string_s cxstring;
1.6
1.7 +/**
1.8 + * A literal initializer for an UCX string structure.
1.9 + *
1.10 + * The argument MUST be a string (const char*) \em literal.
1.11 + *
1.12 + * @param literal the string literal
1.13 + */
1.14 +#define CX_STR(literal) {literal, sizeof(literal) - 1}
1.15 +
1.16 #ifdef __cplusplus
1.17 extern "C" {
1.18 #endif
1.19 @@ -190,9 +199,28 @@
1.20 *
1.21 * @param str the string to free
1.22 */
1.23 +__attribute__((__nonnull__))
1.24 void cx_strfree(cxmutstr *str);
1.25
1.26 /**
1.27 + * Passes the pointer in this string to the allocators free function.
1.28 + *
1.29 + * The pointer in the struct is set to \c NULL and the length is set to zero.
1.30 + *
1.31 + * \note There is no implementation for cxstring, because it is unlikely that
1.32 + * you ever have a \c char \c const* you are really supposed to free. If you
1.33 + * encounter such situation, you should double-check your code.
1.34 + *
1.35 + * @param alloc the allocator
1.36 + * @param str the string to free
1.37 + */
1.38 +__attribute__((__nonnull__))
1.39 +void cx_strfree_a(
1.40 + CxAllocator *alloc,
1.41 + cxmutstr *str
1.42 +);
1.43 +
1.44 +/**
1.45 * Returns the accumulated length of all specified strings.
1.46 *
1.47 * \attention if the count argument is larger than the number of the
1.48 @@ -720,7 +748,7 @@
1.49 * The returned string will be allocated by \p allocator.
1.50 *
1.51 * If allocation fails, or the input string is empty,
1.52 - * the returned string will point to \c NULL.
1.53 + * the returned string will be empty.
1.54 *
1.55 * @param allocator the allocator to use
1.56 * @param str the string where replacements should be applied
1.57 @@ -730,7 +758,7 @@
1.58 * @return the resulting string after applying the replacements
1.59 */
1.60 __attribute__((__warn_unused_result__, __nonnull__))
1.61 -cxmutstr cx_strreplace_a(
1.62 +cxmutstr cx_strreplacen_a(
1.63 CxAllocator *allocator,
1.64 cxstring str,
1.65 cxstring pattern,
1.66 @@ -748,7 +776,7 @@
1.67 * to cx_strfree() eventually.
1.68 *
1.69 * If allocation fails, or the input string is empty,
1.70 - * the returned string will point to \c NULL.
1.71 + * the returned string will be empty.
1.72 *
1.73 * @param str the string where replacements should be applied
1.74 * @param pattern the pattern to search for
1.75 @@ -756,8 +784,47 @@
1.76 * @param replmax maximum number of replacements
1.77 * @return the resulting string after applying the replacements
1.78 */
1.79 -#define cx_strreplace(str, pattern, replacement, replmax) \
1.80 -cx_strreplace_a(cxDefaultAllocator, str, pattern, replacement, replmax)
1.81 +#define cx_strreplacen(str, pattern, replacement, replmax) \
1.82 +cx_strreplacen_a(cxDefaultAllocator, str, pattern, replacement, replmax)
1.83 +
1.84 +/**
1.85 + * Replaces a pattern in a string with another string.
1.86 + *
1.87 + * The pattern is taken literally and is no regular expression.
1.88 + *
1.89 + * The returned string will be allocated by \p allocator.
1.90 + *
1.91 + * If allocation fails, or the input string is empty,
1.92 + * the returned string will be empty.
1.93 + *
1.94 + * @param allocator the allocator to use
1.95 + * @param str the string where replacements should be applied
1.96 + * @param pattern the pattern to search for
1.97 + * @param replacement the replacement string
1.98 + * @return the resulting string after applying the replacements
1.99 + */
1.100 +#define cx_strreplace_a(allocator, str, pattern, replacement) \
1.101 +cx_strreplacen_a(allocator, str, pattern, replacement, SIZE_MAX)
1.102 +
1.103 +/**
1.104 + * Replaces a pattern in a string with another string.
1.105 + *
1.106 + * The pattern is taken literally and is no regular expression.
1.107 + * Replaces at most \p replmax occurrences.
1.108 + *
1.109 + * The returned string will be allocated by \c malloc() and \em must be passed
1.110 + * to cx_strfree() eventually.
1.111 + *
1.112 + * If allocation fails, or the input string is empty,
1.113 + * the returned string will be empty.
1.114 + *
1.115 + * @param str the string where replacements should be applied
1.116 + * @param pattern the pattern to search for
1.117 + * @param replacement the replacement string
1.118 + * @return the resulting string after applying the replacements
1.119 + */
1.120 +#define cx_strreplace(str, pattern, replacement) \
1.121 +cx_strreplacen_a(cxDefaultAllocator, str, pattern, replacement, SIZE_MAX)
1.122
1.123 #ifdef __cplusplus
1.124 } // extern "C"
