Perf optimisations

CHANGES.md

@@ -1,6 +1,11 @@
 # cstring - Changes <!-- omit in toc -->
 
 
+## 4.2.0 - 6th October 2026
+
+* performance optimisations;
+
+
 ## 4.0.19 - 4th October 2026
 
 * Corrected `cstring_readline()` so `numRead` counts every character read from the stream for the line, including the terminator; CR and LF are not stored;

Doxyfile

@@ -2,7 +2,7 @@
 
 PROJECT_NAME           = "cstring"
 PROJECT_BRIEF          = "Extensible C-style strings and vectors of such, for Unix and Windows"
-PROJECT_NUMBER         = 4.0.19
+PROJECT_NUMBER         = 4.2.0
 
 # Prefer SIS_CMAKE_BUILD_DIR-aligned output (same convention as Diagnosticism).
 # ./dox/ remains gitignored for legacy/local runs that override OUTPUT_DIRECTORY.

NEWS.md

@@ -4,6 +4,7 @@
 | Date                | News Item                        | Details |
 | ------------------- | -------------------------------- | ------- |
 | Available from [**cstring** project on GitHub](https://synesissoftware.com/cstring):  |
+| 5th October 2026    | Release of [cstring 4.2.0](https://github.com/synesissoftware/cstring/releases/tag/4.2.0) | Performance optimisations |
 | 4th October 2026    | Release of [cstring 4.0.19](https://github.com/synesissoftware/cstring/releases/tag/4.0.19) | lone CR ends a line; `numRead` includes EOL; readonly truncate; zero-size realloc frees; **test.performance.cstring_readline**; shortened test and example directories; **test.unit.cstring**; README usage modes |
 | 29th September 2026 | Release of [cstring 4.0.18](https://github.com/synesissoftware/cstring/releases/tag/4.0.18) | `_WIN32` arena gate; **win.c**; static `CoTaskMem*` (**ole32**) |
 | 29th September 2026 | Release of [cstring 4.0.17](https://github.com/synesissoftware/cstring/releases/tag/4.0.17) | Perf tests; `insertAt` fix; component I/O; Windows arena rename |

include/cstring/cstring.h

@@ -104,6 +104,7 @@
 # define CSTRING_VER_4_0_17     0x040011ff
 # define CSTRING_VER_4_0_18     0x040012ff
 # define CSTRING_VER_4_0_19     0x040013ff
+# define CSTRING_VER_4_2_0_A1   0x04020041
 #endif /* !CSTRING_DOCUMENTATION_SKIP_SECTION */
 
 /** \def CSTRING_VER_MAJOR
@@ -123,9 +124,9 @@
  */
 
 #define CSTRING_VER_MAJOR                                   4
-#define CSTRING_VER_MINOR                                   0
-#define CSTRING_VER_PATCH                                   19
-#define CSTRING_VER_ALPHABETA                               0xFF
+#define CSTRING_VER_MINOR                                   2
+#define CSTRING_VER_PATCH                                   0
+#define CSTRING_VER_ALPHABETA                               0x41
 
 #define CSTRING_VER \
     (0\

include/cstring/cstring.vector.h

@@ -4,7 +4,7 @@
  * Purpose: Definition of the cstring.vector API.
  *
  * Created: 21st January 2012
- * Updated: 28th September 2026
+ * Updated: 29th September 2026
  *
  * Home:    http://synesis.com.au/software/
  *

src/cstring.core.c

@@ -169,12 +169,10 @@ convert_negative_index_(
  * \param src Source. May be \c NULL;
  * \param lim Maximum number of elements in \c dst;
  *
- * \return The actual length of src if not \c NULL; 0 otherwise
- *
  * \pre NULL != dst
  */
 static
-size_t
+void
 cstring_strlcpy_safe_(
     cstring_char_t          dst[]
 ,   cstring_char_t const*   src
@@ -186,30 +184,10 @@ cstring_strlcpy_safe_(
     if (NULL == src)
     {
         memset(dst, 0, sizeof(cstring_char_t) * lim);
-
-        return 0;
     }
     else
     {
-        size_t i;
-
-        for (i = 0; i != lim; ++i, ++dst, ++src)
-        {
-            *dst = *src;
-
-            if ('\0' == src[0])
-            {
-                break;
-            }
-        }
-
-        memset(dst, 0, sizeof(cstring_char_t) * (lim - i));
-
-        for (; '\0' != src[0]; ++i, ++src)
-        {
-        }
-
-        return i;
+        memcpy(dst, src, sizeof(cstring_char_t) * lim);
     }
 }
 
@@ -287,7 +265,11 @@ cstring_realloc_2_(
              */
             if (0 == cb)
             {
-                free(pv);
+                if (NULL != pv)
+                {
+                    free(pv);
+                }
+
                 return NULL;
             }
 
@@ -359,6 +341,31 @@ cstring_realloc_(
     return cstring_realloc_2_(pv, cch, flags, prc, NULL, NULL);
 }
 
+/** Releases owned storage and leaves \c pcs empty with a NULL pointer. */
+static
+CSTRING_RC
+cstring_release_to_empty_(
+    struct cstring_t*   pcs
+)
+{
+    CSTRING_RC rc = CSTRING_RC_SUCCESS;
+
+    CSTRING_ASSERT(NULL != pcs);
+
+    if (!(CSTRING_F_MEMORY_IS_BORROWED & pcs->flags) &&
+        NULL != pcs->ptr)
+    {
+        (void)cstring_realloc_(pcs->ptr, 0, pcs->flags, &rc);
+    }
+
+    pcs->len        =   0;
+    pcs->ptr        =   NULL;
+    pcs->capacity   =   0;
+    pcs->flags      =   0;
+
+    return rc;
+}
+
 
 /* /////////////////////////////////////////////////////////////////////////
  * API
@@ -469,7 +476,17 @@ cstring_create(
 
     CSTRING_ASSERT(NULL != pcs);
 
-    cch =   (0 == len) ? 1u : len;
+    if (0 == len)
+    {
+        pcs->len        =   0;
+        pcs->ptr        =   NULL;
+        pcs->capacity   =   0;
+        pcs->flags      =   0;
+
+        return CSTRING_RC_SUCCESS;
+    }
+
+    cch =   len;
     cch =   (cch + (CSTRING_ALLOC_GRANULARITY - 1)) & ~(CSTRING_ALLOC_GRANULARITY - 1);
 
     pcs->ptr = (cstring_char_t*)cstring_realloc_(NULL, cch + 1, 0, &rc);
@@ -503,7 +520,17 @@ cstring_createLen(
 
     CSTRING_ASSERT(NULL != pcs);
 
-    cch =   sizeof(cstring_char_t) * ((0 == len) ? 1u : len);
+    if (0 == len)
+    {
+        pcs->len        =   0;
+        pcs->ptr        =   NULL;
+        pcs->capacity   =   0;
+        pcs->flags      =   0;
+
+        return CSTRING_RC_SUCCESS;
+    }
+
+    cch =   len;
     cch =   (cch + (CSTRING_ALLOC_GRANULARITY - 1)) & ~(CSTRING_ALLOC_GRANULARITY - 1);
 
     pcs->ptr = (cstring_char_t*)cstring_realloc_(NULL, cch + 1, 0, &rc);
@@ -644,6 +671,16 @@ cstring_createLenFn(
             pcs->ptr        =   (cstring_char_t*)arena;
             pcs->capacity   =   capacity - 1;
         }
+        else if (0 == len &&
+                0 == capacity)
+        {
+            pcs->len        =   0;
+            pcs->ptr        =   NULL;
+            pcs->capacity   =   0;
+            pcs->flags      =   0;
+
+            return CSTRING_RC_SUCCESS;
+        }
         else
         {
             size_t      cch;
@@ -681,21 +718,9 @@ cstring_destroy(
     struct cstring_t* pcs
 )
 {
-    CSTRING_RC  rc  =   CSTRING_RC_SUCCESS;
-
     CSTRING_ASSERT(NULL != pcs);
 
-    if (!(CSTRING_F_MEMORY_IS_BORROWED & pcs->flags))
-    {
-        (void)cstring_realloc_(pcs->ptr, 0, pcs->flags, &rc);
-    }
-
-    pcs->len        =   0;
-    pcs->ptr        =   NULL;
-    pcs->capacity   =   0;
-    pcs->flags      =   0;
-
-    return rc;
+    return cstring_release_to_empty_(pcs);
 }
 
 #ifndef CSTRING_OBSOLETE
@@ -896,12 +921,30 @@ cstring_assignFn(
     {
         const size_t len = cstring_strlen_safe_(s);
 
+        if (0 == len)
+        {
+            if (NULL != pcs->ptr)
+            {
+                pcs->len = 0;
+                pcs->ptr[0] = '\0';
+
+                return CSTRING_RC_SUCCESS;
+            }
+
+            pcs->len        =   0;
+            pcs->ptr        =   NULL;
+            pcs->capacity   =   0;
+            pcs->flags      =   0;
+
+            return CSTRING_RC_SUCCESS;
+        }
+
         if (0 == pcs->capacity ||
             pcs->capacity < len)
         {
             size_t cch;
 
-            cch =   (0 == len) ? 1u : len;
+            cch =   len;
             cch =   (cch + (CSTRING_ALLOC_GRANULARITY - 1)) & ~(CSTRING_ALLOC_GRANULARITY - 1);
 
             if (cch < pcs->capacity * 2)
@@ -996,12 +1039,30 @@ cstring_assignLenFn(
     }
     else
     {
+        if (0 == len)
+        {
+            if (NULL != pcs->ptr)
+            {
+                pcs->len = 0;
+                pcs->ptr[0] = '\0';
+
+                return CSTRING_RC_SUCCESS;
+            }
+
+            pcs->len        =   0;
+            pcs->ptr        =   NULL;
+            pcs->capacity   =   0;
+            pcs->flags      =   0;
+
+            return CSTRING_RC_SUCCESS;
+        }
+
         if (0 == pcs->capacity ||
             pcs->capacity < len)
         {
             size_t cch;
 
-            cch =   (0 == len) ? 1u : len;
+            cch =   len;
             cch =   (cch + (CSTRING_ALLOC_GRANULARITY - 1)) & ~(CSTRING_ALLOC_GRANULARITY - 1);
 
             if (cch < pcs->capacity * 2)
@@ -1108,7 +1169,23 @@ cstring_appendFn(
         size_t const    len     =   cstring_strlen_safe_(s);
         size_t const    newLen  =   pcs->len + len;
 
-        if (pcs->capacity < newLen)
+        if (0 == len)
+        {
+            return CSTRING_RC_SUCCESS;
+        }
+
+        /* Capacity already covers the write: copy in place. */
+        if (pcs->capacity >= newLen)
+        {
+            CSTRING_ASSERT(NULL != pcs->ptr);
+
+            cstring_memcpy_safe_(pcs->ptr + pcs->len, s, len * sizeof(cstring_char_t));
+            pcs->len            =   newLen;
+            pcs->ptr[pcs->len]  =   '\0';
+
+            return CSTRING_RC_SUCCESS;
+        }
+
         {
             size_t cch;
 
@@ -1214,13 +1291,29 @@ cstring_appendLenFn(
     }
     else
     {
-        size_t newLen = pcs->len + len;
+        size_t const newLen = pcs->len + len;
+
+        if (0 == len)
+        {
+            return CSTRING_RC_SUCCESS;
+        }
+
+        /* Capacity already covers the write: copy in place. */
+        if (pcs->capacity >= newLen)
+        {
+            CSTRING_ASSERT(NULL != pcs->ptr);
+
+            cstring_memcpy_safe_(pcs->ptr + pcs->len, s, len * sizeof(cstring_char_t));
+            pcs->len            =   newLen;
+            pcs->ptr[pcs->len]  =   '\0';
+
+            return CSTRING_RC_SUCCESS;
+        }
 
-        if (pcs->capacity < newLen)
         {
             size_t cch;
 
-            cch  =   pcs->len + len;
+            cch  =   newLen;
             cch  =   (cch + (CSTRING_ALLOC_GRANULARITY - 1)) & ~(CSTRING_ALLOC_GRANULARITY - 1);
 
             if (cch < pcs->capacity * 2)
@@ -1285,7 +1378,7 @@ cstring_appendLenFn(
             }
         }
 
-        cstring_strlcpy_safe_(pcs->ptr + pcs->len, s, len);
+        cstring_memcpy_safe_(pcs->ptr + pcs->len, s, len * sizeof(cstring_char_t));
         pcs->len            +=  len;
         pcs->ptr[pcs->len]  =   '\0';
 
@@ -1373,6 +1466,8 @@ cstring_readline(
         numRead = &dummy;
     }
 
+    *numRead = 0u;
+
     if (NULL == stm ||
         0 != ferror(stm))
     {
@@ -1477,7 +1572,12 @@ cstring_write_(
 
     *numWritten = 0u;
 
-    r = fprintf(stm, fmt, (int)pcs->len, pcs->ptr);
+    r = fprintf(
+            stm
+        ,   fmt
+        ,   (int)pcs->len
+        ,   (NULL != pcs->ptr) ? pcs->ptr : ""
+        );
 
     if (r < 0)
     {