Boilerplate

CHANGES.md

@@ -1,6 +1,12 @@
 # cstring - Changes <!-- omit in toc -->
 
 
+## 4.1.0-beta1 - 21st October 2026
+
+* Brought the tip CMake runners up to **misc-dev-scripts** 0.6.2 and merged that gold into **prepare_cmake.sh**, keeping the cstring `-D` flags and `--gap-groups`;
+* Defined `CSTRING_VER_RELSTATUS` (`0x81`, beta 1) and aliased `CSTRING_VER_ALPHABETA` to it;
+
+
 ## 4.1.0-alpha1 - 6th October 2026
 
 * Added 64-bit `djb2` hash functions: `cstring_hash_djb2()`, `cstring_hash_djb2_case()`, `cstring_hash_djb2_buf()`, and `cstring_hash_djb2_buf_case()`;

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.1.0-alpha1
+PROJECT_NUMBER         = 4.1.0-beta1
 
 # 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):  |
+| 21st October 2026   | Release of [cstring 4.1.0-beta1](https://github.com/synesissoftware/cstring/releases/tag/4.1.0-beta1) | helper gold 0.6.2; `CSTRING_VER_RELSTATUS` |
 | 6th October 2026    | Release of [cstring 4.1.0-alpha1](https://github.com/synesissoftware/cstring/releases/tag/4.1.0-alpha1) | `djb2`, `FNV-1a`, and `SDBM`; `cstring_equal()` / `cstring_compare()`; `--wide-strings`; counted copies stop at `cch` |
 | 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**) |

include/cstring/cstring.h

@@ -4,7 +4,7 @@
  * Purpose: Definition of the cstring.core API.
  *
  * Created: 16th June 1994
- * Updated: 6th October 2026
+ * Updated: 21st October 2026
  *
  * Home:    http://synesis.com.au/software/
  *
@@ -56,7 +56,7 @@
 # define CSTRING_VER_CSTRING_H_CSTRING_MAJOR    3
 # define CSTRING_VER_CSTRING_H_CSTRING_MINOR    13
 # define CSTRING_VER_CSTRING_H_CSTRING_REVISION 3
-# define CSTRING_VER_CSTRING_H_CSTRING_EDIT     100
+# define CSTRING_VER_CSTRING_H_CSTRING_EDIT     103
 #endif /* !CSTRING_DOCUMENTATION_SKIP_SECTION */
 
 
@@ -105,6 +105,8 @@
 # define CSTRING_VER_4_0_18     0x040012ff
 # define CSTRING_VER_4_0_19     0x040013ff
 # define CSTRING_VER_4_1_0_A1   0x04010041
+# define CSTRING_VER_4_1_0_A2   0x04010042
+# define CSTRING_VER_4_1_0_B1   0x04010081
 #endif /* !CSTRING_DOCUMENTATION_SKIP_SECTION */
 
 /** \def CSTRING_VER_MAJOR
@@ -119,24 +121,29 @@
  * The patch version number of **cstring**
  */
 
+/** \def CSTRING_VER_RELSTATUS
+ * The release-status number of **cstring**
+ */
+
 /** \def CSTRING_VER
  * The current composite version number of **cstring**
  */
 
 #define CSTRING_VER_MAJOR                                   4
 #define CSTRING_VER_MINOR                                   1
 #define CSTRING_VER_PATCH                                   0
-#define CSTRING_VER_ALPHABETA                               0x41
+#define CSTRING_VER_RELSTATUS                               0x81
 
 #define CSTRING_VER \
     (0\
         |   (   CSTRING_VER_MAJOR      << 24   ) \
         |   (   CSTRING_VER_MINOR      << 16   ) \
         |   (   CSTRING_VER_PATCH      <<  8   ) \
-        |   (   CSTRING_VER_ALPHABETA  <<  0   ) \
+        |   (   CSTRING_VER_RELSTATUS  <<  0   ) \
     )
 
 #ifndef CSTRING_DOCUMENTATION_SKIP_SECTION
+# define CSTRING_VER_ALPHABETA                              CSTRING_VER_RELSTATUS
 # define CSTRING_VER_REVISION                               CSTRING_VER_PATCH
 #endif /* !CSTRING_DOCUMENTATION_SKIP_SECTION */
 

prepare_cmake.sh

@@ -34,16 +34,24 @@ Configuration=Release
 ExamplesDisabled=0
 MinGW=$(sis_cmake_is_truey "${SIS_CMAKE_MINGW:-}" && echo 1 || echo 0)
 MSVC_MT=0
-NO_cxx=0
-NO_p99=0
-NO_shwild=0
 RunMake=0
 SisUseColours=0
-STLSoftDirGiven=
 TestingDisabled=0
 VerboseMakefile=0
-WideStrings=0
 
+# ##########################################################
+# PROJECT-SPECIFIC FLAGS (customise per library; keep marker)
+#
+# Add project-only options here (e.g. --no-cpp, --stlsoft-root-dir,
+# --no-shwild). The common body below must stay aligned with
+# misc-dev-scripts/shell-scripts/cmake-helpers/prepare_cmake.sh.
+
+
+NO_cxx=0
+NO_p99=0
+NO_shwild=0
+STLSoftDirGiven=
+WideStrings=0
 
 # ##########################################################
 # colours

run_all_examples.cmd

@@ -4,6 +4,8 @@ SETLOCAL
 
 SET SCRIPT_DIRECTORY=%~dp0
 SET SCRIPT_PATH_DOC=%~n0[%~x0]
+SET "ALLOWED_TO_FAIL_FILE=%SCRIPT_DIRECTORY%.sis\ci_examples_allowed_to_fail.txt"
+SET "PROGRAM_STATUS=0"
 
 IF DEFINED SIS_CMAKE_BUILD_DIR (
 
@@ -45,6 +47,22 @@ Flags/options: ^
 
             displays this help and terminates ^
 
+^
+
+    files: ^
+
+^
+
+        .sis\ci_examples_allowed_to_fail.txt ^
+
+            optional list of example programs ^(one name per line; ^
+
+            lines beginning with '#' are ignored^) that are allowed to fail; ^
+
+            such a program is still executed, but a non-zero exit is ^
+
+            reported as anticipated and does not stop the run ^
+
 
 		EXIT /B 0
 	) ELSE (
@@ -78,12 +96,36 @@ SET SIS_EXAMPLE_SMOKE=1
 
 ECHO Running all %ProjectName% example programs
 
-FOR /F "usebackq" %%f IN (`DIR /A:-D /B /S "%CMAKE_DIR%" ^| FINDSTR /I example.*\.exe$`) DO (
-
-	ECHO .
-	ECHO executing %%f
-	%%f
-	IF ERRORLEVEL 1 EXIT /B %ERRORLEVEL%
-)
-
-ENDLOCAL
+FOR /F "usebackq" %%f IN (`DIR /A:-D /B /S "%CMAKE_DIR%" ^| FINDSTR /I example.*\.exe$`) DO CALL :run_program "%%f"
+
+ENDLOCAL & EXIT /B %PROGRAM_STATUS%
+
+
+REM ##########################################################
+REM subroutines
+
+:run_program
+IF %PROGRAM_STATUS% NEQ 0 EXIT /B 0
+ECHO .
+ECHO executing %~1
+"%~1"
+SET "FAILURE_STATUS=%ERRORLEVEL%"
+IF %FAILURE_STATUS% EQU 0 EXIT /B 0
+CALL :is_allowed_to_fail "%~1"
+IF NOT DEFINED ALLOWED_TO_FAIL GOTO run_program_failed
+ECHO anticipated failure: %~1 exited with status %FAILURE_STATUS%; it is listed in .sis\ci_examples_allowed_to_fail.txt
+EXIT /B 0
+:run_program_failed
+SET "PROGRAM_STATUS=%FAILURE_STATUS%"
+EXIT /B 0
+
+:is_allowed_to_fail
+SET "ALLOWED_TO_FAIL="
+IF NOT EXIST "%ALLOWED_TO_FAIL_FILE%" EXIT /B 0
+FOR /F "usebackq eol=# tokens=1" %%n IN ("%ALLOWED_TO_FAIL_FILE%") DO CALL :match_allowed "%%n" "%~n1" "%~nx1"
+EXIT /B 0
+
+:match_allowed
+IF /I "%~1"=="%~2" SET "ALLOWED_TO_FAIL=1"
+IF /I "%~1"=="%~3" SET "ALLOWED_TO_FAIL=1"
+EXIT /B 0

run_all_examples.sh

@@ -27,6 +27,7 @@ CMakeDir=${SIS_CMAKE_BUILD_DIR:-$Dir/_build}
 ProjectNameFile="$Dir/.sis/project_name.txt"
 ProjectName=$(tr -d '[:space:]' < "$ProjectNameFile")
 ScriptPath=$0
+AllowedToFailFile="$Dir/.sis/ci_examples_allowed_to_fail.txt"
 
 AlwaysUseColours=${SIS_CMAKE_ALWAYS_USE_COLOURS:-${SIS_ALWAYS_USE_COLOURS:-0}}
 ListOnly=0
@@ -115,6 +116,49 @@ sis_cmake_build() {
   cmake "${args[@]}"
 }
 
+# Reduces a program path to its (lowercase) name, without any directory or
+# .exe suffix.
+sis_program_stem() {
+
+  local p="${1//\\//}"
+
+  p="${p##*/}"
+
+  case "$p" in
+    *.exe|*.EXE) p="${p%.*}" ;;
+  esac
+
+  printf '%s' "$p" | tr '[:upper:]' '[:lower:]'
+}
+
+# Succeeds if the program is named (by name or stem, case-insensitively) in
+# the optional .sis/ci_examples_allowed_to_fail.txt file; blank lines and
+# lines beginning with '#' are ignored.
+sis_is_allowed_to_fail() {
+
+  local name line
+
+  [ -f "$AllowedToFailFile" ] || return 1
+
+  name=$(sis_program_stem "$1")
+
+  while IFS= read -r line || [ -n "$line" ]; do
+
+    line="${line//$'\r'/}"
+
+    case "$line" in
+      ''|\#*) continue ;;
+    esac
+
+    if [ "$name" = "$(sis_program_stem "$line")" ]; then
+
+      return 0
+    fi
+  done < "$AllowedToFailFile"
+
+  return 1
+}
+
 
 # ##########################################################
 # command-line handling
@@ -160,6 +204,15 @@ Flags/options:
         does not execute a build before running programs
 
 
+    files:
+
+    .sis/ci_examples_allowed_to_fail.txt
+        optional list of example programs (one name per line; blank lines
+        and lines beginning with '#' are ignored) that are allowed to fail;
+        such a program is still executed, but a non-zero exit is reported as
+        anticipated and neither stops the run nor affects the exit status
+
+
     standard flags:
 
     --help
@@ -247,7 +300,13 @@ if [ $status -eq 0 ]; then
 
     if [ $ListOnly -ne 0 ]; then
 
-      echo "would execute ${fClr}:"
+      if sis_is_allowed_to_fail "$f"; then
+
+        echo "would execute ${fClr} (allowed to fail):"
+      else
+
+        echo "would execute ${fClr}:"
+      fi
 
       continue
     fi
@@ -260,11 +319,25 @@ if [ $status -eq 0 ]; then
       :
     else
 
-      status=$?
+      fStatus=$?
+
+      if sis_is_allowed_to_fail "$f"; then
+
+        echo "${SisClr_Yellow}${SisClr_Bold}anticipated failure${SisClr_None}: ${fClr} exited with status ${fStatus}; it is listed in .sis/ci_examples_allowed_to_fail.txt"
+
+        continue
+      fi
+
+      status=$fStatus
 
       break 1
     fi
-  done < <(find "$CMakeDir" -type f \( -name 'example*' ! -name '*.md' \) \( -perm -100 -o -name '*.exe' \) -print0 2>/dev/null | sort -z)
+  done < <(find "$CMakeDir" -type f \( -name 'example*' ! -name '*.md' \) \
+    ! -path '*/CMakeFiles/*' \
+    ! -name '*.a' \
+    ! -name '*.d' \
+    ! -name '*.lib' \
+    \( -perm -100 -o -name '*.exe' \) -print0 2>/dev/null | sort -z)
 
   if [ $NumPrograms -eq 0 ]; then