# HG changeset patch
# User Mike Becker <universe@uap-core.de>
# Date 1740246925 -3600
# Node ID 304f4f7b37d1defd0a5c7c5d34766cf06615db5b
# Parent  e9dfb1e924812b47fb7ff8132afe7f57abdafab9
document cx_strreplace() family of functions and improve docstrings

relates to #451

diff -r e9dfb1e92481 -r 304f4f7b37d1 docs/Writerside/topics/string.h.md
--- a/docs/Writerside/topics/string.h.md	Fri Feb 21 21:06:07 2025 +0100
+++ b/docs/Writerside/topics/string.h.md	Sat Feb 22 18:55:25 2025 +0100
@@ -178,20 +178,27 @@
 ```C
 #include <cx/string.h>
 
-cxmutstr cx_strreplace(cxstring str, cxstring pattern, cxstring repl);
+cxmutstr cx_strreplace(cxstring str,
+        cxstring search, cxstring replacement);
 
 cxmutstr cx_strreplace_a(const CxAllocator *allocator, cxstring str,
-        cxstring pattern, cxstring repl);
+        cxstring search, cxstring replacement);
 
-cxmutstr cx_strreplacen(cxstring str, cxstring pattern, cxstring repl,
-        size_t replmax);
+cxmutstr cx_strreplacen(cxstring str,
+        cxstring search, cxstring replacement, size_t replmax);
 
 cxmutstr cx_strreplacen_a(const CxAllocator *allocator, cxstring str,
-        cxstring pattern, cxstring repl, size_t replmax);
+        cxstring search, cxstring replacement, size_t replmax);
 ```
 
-> Documentation work in progress.
->{style="warning"}
+The function `cx_strreplace()` allocates a new string which will contain a copy of `str`
+where every occurrence of `search` is replaced with `replacement`.
+The new string is guaranteed to be zero-terminated even if `str` is not.
+
+The function `cx_strreplace_a()` uses the specified `allocator` to allocate the new string.
+
+The functions `cx_strreplacen()` and `cx_strreplacen_a()` are equivalent, except that they stop
+after `replmax` number of replacements.
 
 ## Basic Splitting
 
diff -r e9dfb1e92481 -r 304f4f7b37d1 src/cx/string.h
--- a/src/cx/string.h	Fri Feb 21 21:06:07 2025 +0100
+++ b/src/cx/string.h	Sat Feb 22 18:55:25 2025 +0100
@@ -983,9 +983,8 @@
 );
 
 /**
- * Replaces a pattern in a string with another string.
+ * Replaces a string with another string.
  *
- * The pattern is taken literally and is no regular expression.
  * Replaces at most @p replmax occurrences.
  *
  * The returned string will be allocated by @p allocator and is guaranteed
@@ -996,7 +995,7 @@
  *
  * @param allocator the allocator to use
  * @param str the string where replacements should be applied
- * @param pattern the pattern to search for
+ * @param search the string to search for
  * @param replacement the replacement string
  * @param replmax maximum number of replacements
  * @return the resulting string after applying the replacements
@@ -1007,15 +1006,14 @@
 cxmutstr cx_strreplacen_a(
         const CxAllocator *allocator,
         cxstring str,
-        cxstring pattern,
+        cxstring search,
         cxstring replacement,
         size_t replmax
 );
 
 /**
- * Replaces a pattern in a string with another string.
+ * Replaces a string with another string.
  *
- * The pattern is taken literally and is no regular expression.
  * Replaces at most @p replmax occurrences.
  *
  * The returned string will be allocated by @c malloc() and is guaranteed
@@ -1025,18 +1023,16 @@
  * the returned string will be empty.
  *
  * @param str (@c cxstring) the string where replacements should be applied
- * @param pattern (@c cxstring) the pattern to search for
+ * @param search (@c cxstring) the string to search for
  * @param replacement (@c cxstring) the replacement string
  * @param replmax (@c size_t) maximum number of replacements
  * @return (@c cxmutstr) the resulting string after applying the replacements
  */
-#define cx_strreplacen(str, pattern, replacement, replmax) \
-cx_strreplacen_a(cxDefaultAllocator, str, pattern, replacement, replmax)
+#define cx_strreplacen(str, search, replacement, replmax) \
+cx_strreplacen_a(cxDefaultAllocator, str, search, replacement, replmax)
 
 /**
- * Replaces a pattern in a string with another string.
- *
- * The pattern is taken literally and is no regular expression.
+ * Replaces a string with another string.
  *
  * The returned string will be allocated by @p allocator and is guaranteed
  * to be zero-terminated.
@@ -1046,18 +1042,15 @@
  *
  * @param allocator (@c CxAllocator*) the allocator to use
  * @param str (@c cxstring) the string where replacements should be applied
- * @param pattern (@c cxstring) the pattern to search for
+ * @param search (@c cxstring) the string to search for
  * @param replacement (@c cxstring) the replacement string
  * @return (@c cxmutstr) the resulting string after applying the replacements
  */
-#define cx_strreplace_a(allocator, str, pattern, replacement) \
-cx_strreplacen_a(allocator, str, pattern, replacement, SIZE_MAX)
+#define cx_strreplace_a(allocator, str, search, replacement) \
+cx_strreplacen_a(allocator, str, search, replacement, SIZE_MAX)
 
 /**
- * Replaces a pattern in a string with another string.
- *
- * The pattern is taken literally and is no regular expression.
- * Replaces at most @p replmax occurrences.
+ * Replaces a string with another string.
  *
  * The returned string will be allocated by @c malloc() and is guaranteed
  * to be zero-terminated.
@@ -1066,12 +1059,12 @@
  * the returned string will be empty.
  *
  * @param str (@c cxstring) the string where replacements should be applied
- * @param pattern (@c cxstring) the pattern to search for
+ * @param search (@c cxstring) the string to search for
  * @param replacement (@c cxstring) the replacement string
  * @return (@c cxmutstr) the resulting string after applying the replacements
  */
-#define cx_strreplace(str, pattern, replacement) \
-cx_strreplacen_a(cxDefaultAllocator, str, pattern, replacement, SIZE_MAX)
+#define cx_strreplace(str, search, replacement) \
+cx_strreplacen_a(cxDefaultAllocator, str, search, replacement, SIZE_MAX)
 
 /**
  * Creates a string tokenization context.
diff -r e9dfb1e92481 -r 304f4f7b37d1 src/string.c
--- a/src/string.c	Fri Feb 21 21:06:07 2025 +0100
+++ b/src/string.c	Sat Feb 22 18:55:25 2025 +0100
@@ -612,16 +612,16 @@
 cxmutstr cx_strreplacen_a(
         const CxAllocator *allocator,
         cxstring str,
-        cxstring pattern,
+        cxstring search,
         cxstring replacement,
         size_t replmax
 ) {
 
-    if (pattern.length == 0 || pattern.length > str.length || replmax == 0)
+    if (search.length == 0 || search.length > str.length || replmax == 0)
         return cx_strdup_a(allocator, str);
 
     // Compute expected buffer length
-    size_t ibufmax = str.length / pattern.length;
+    size_t ibufmax = str.length / search.length;
     size_t ibuflen = replmax < ibufmax ? replmax : ibufmax;
     if (ibuflen > CX_STRREPLACE_INDEX_BUFFER_SIZE) {
         ibuflen = CX_STRREPLACE_INDEX_BUFFER_SIZE;
@@ -638,7 +638,7 @@
     cxstring searchstr = str;
     size_t found = 0;
     do {
-        cxstring match = cx_strstr(searchstr, pattern);
+        cxstring match = cx_strstr(searchstr, search);
         if (match.length > 0) {
             // Allocate next buffer in chain, if required
             if (curbuf->len == ibuflen) {
@@ -662,8 +662,8 @@
             found++;
             size_t idx = match.ptr - str.ptr;
             curbuf->buf[curbuf->len++] = idx;
-            searchstr.ptr = match.ptr + pattern.length;
-            searchstr.length = str.length - idx - pattern.length;
+            searchstr.ptr = match.ptr + search.length;
+            searchstr.length = str.length - idx - search.length;
         } else {
             break;
         }
@@ -672,7 +672,7 @@
     // Allocate result string
     cxmutstr result;
     {
-        long long adjlen = (long long) replacement.length - (long long) pattern.length;
+        long long adjlen = (long long) replacement.length - (long long) search.length;
         size_t rcount = 0;
         curbuf = &ibuf;
         do {
@@ -703,7 +703,7 @@
             }
 
             // Copy the replacement and skip the source pattern
-            srcidx += pattern.length;
+            srcidx += search.length;
             memcpy(destptr, replacement.ptr, replacement.length);
             destptr += replacement.length;
         }