1.11.1-rc9 : Canonicalise C-API function prefixes

TODO.md

@@ -17,6 +17,7 @@
   - [1.11.9](#1119)
   - [1.11.10](#11110)
   - [1.11.11](#11111)
+  - [1.11.12](#11112)
   - [Cross-publish to STLSoft-1.11](#cross-publish-to-stlsoft-111)
 - [1.12](#112)
 - [Requires clarification by project maintainers](#requires-clarification-by-project-maintainers)
@@ -54,6 +55,9 @@ Dedicated increment: **test analysis and coverage only** — no other product ch
 * [ ] Coverage of currently untested components;
 * [ ] All precondition enforcements => \pre;
 * [ ] All \pre => precondition enforcements;
+* [ ] Remove **WTL**;
+* [ ] Resolve finally the structure and semantics of the top-level execution scripts (**run_all_unit_tests.sh**, **run_all_scratch_tests.sh**, **run_all_examples.sh**, **execute_performance_tests.sh**, and Windows `.cmd` counterparts) on all platforms — discovery globs, execute-bit / artifact restore, zero-match failure, verbosity, and CI wiring;
+* [ ] bring in some essential unit-tests from interal repo;
 
 
 ### 1.11.3
@@ -89,7 +93,7 @@ Dedicated increment: **test analysis and coverage only** — no other product ch
 
 ### 1.11.8
 
-* [ ] Move **include/stlsoft/util/string/**`*printf.h` into **api/internal** and deprecate the old headers;
+* [ ] Move **include/stlsoft/util/string/**\***printf.h** into **api/internal** and deprecate the old headers;
 
 
 ### 1.11.9
@@ -107,6 +111,26 @@ Dedicated increment: **test analysis and coverage only** — no other product ch
 * [ ] Doxygen build (**Doxyfile**, **generate_doxygen.sh**) and deeper API documentation — see also [**KNOWN_ISSUES.md**](./KNOWN_ISSUES.md);
 
 
+### 1.11.12
+
+Normalise C API (and related C-facing) identifier prefixes. **House rule**
+(documented in **c-cpp-standards** → *STLSoft C API identifier prefixes*):
+
+* **Functions**, **types**, and **enumerators** — lowercase `<subproject>_C_`;
+* **Macros** — ALL_UPPERCASE (including the project key);
+* Do not introduce mixed forms such as `WinSTL_C_` / `STLSoft_C_`;
+* When renaming, retain older public names (deprecated wrappers or
+  documentation-hidden `#define` aliases) until at least **STLSoft 1.13**.
+
+* [x] ~~~Establish and document the rule (see **c-cpp-standards**)~~~ - ✅;
+* [x] ~~~Rename `STLSoft_C_string_copy*` / `STLSoft_C_string_copy_with_nul*` → `stlsoft_C_*` in **include/stlsoft/string/copy_functions.h** and all call sites (deprecated wrappers retained until at least **1.13**)~~~ - ✅;
+* [x] ~~~Rename `WinSTL_C_FileInformation_*` → `winstl_C_*` in **include/winstl/filesystem/file_information_functions.h** and call sites (deprecated wrappers retained until at least **1.13**)~~~ - ✅;
+* [x] ~~~Rename path-classify `PathType` enumerators: `WinSTL_C_PathType_*` → `winstl_C_PathType_*`, and `UNIXSTL_C_PathType_*` → `unixstl_C_PathType_*` (legacy names retained as documentation-hidden macros until at least **1.13**)~~~ - ✅;
+* [x] ~~~Rename path-classify impl macros `WINSTL_C_PATH_CLASSIFY_IMPL_*` / `UNIXSTL_C_PATH_CLASSIFY_IMPL_*` to lowercase~~~ - ❌ (ALL_UPPERCASE macros are house style; no rename);
+* [x] ~~~Decide policy for `STLSOFT_C_AUTO_BUFFER_*` / `STLSOFT_C_CAST`~~~ - ❌ (ALL_UPPERCASE is the house form; keep);
+* [ ] **1.13+**: consider removing deprecated mixed-case C API wrappers / enumerator aliases (`STLSoft_C_*`, `WinSTL_C_*`, `UNIXSTL_C_PathType_*`, and any later-deprecated forms) — not before;
+
+
 ### Cross-publish to STLSoft-1.11
 
 When tip **1.11** is finally complete, cross-publish into the versioned line **[synesissoftware/STLSoft-1.11](https://github.com/synesissoftware/STLSoft-1.11)** (not done for the interim VOLE / historical-consumer recognition work — that line was left unpushed on purpose).
@@ -144,10 +168,10 @@ From **1.12** onwards, every new component or feature must ship with an **exampl
 
 ## Abandoned
 
-* [-] ~~~custom radix in integer_to_string - abandoned for performance reasons, and obviated by new conversion functions (oct, dec, hex) in 1.10~~~ - ❌;
-* [-] ~~~SourceSafe-era “do not branch the whole monorepo” note~~~ - ❌ (obsolete under Git; superseded by assessing the separate 1.12 internal repository for inclusion);
-* [-] ~~~Manual C/C++ dialect compatibility matrix in **TODO.md**~~~ - ❌ (CI is the record of actively exercised builds; automated/semi-automated reporting deferred to **1.12**);
-* [-] ~~~Migrate/deprecate **include/stlsoft/std/**`*` in parallel with `*printf.h`~~~ - ❌ (cut);
+* [x] ~~~custom radix in integer_to_string - abandoned for performance reasons, and obviated by new conversion functions (oct, dec, hex) in 1.10~~~ - ❌;
+* [x] ~~~SourceSafe-era “do not branch the whole monorepo” note~~~ - ❌ (obsolete under Git; superseded by assessing the separate 1.12 internal repository for inclusion);
+* [x] ~~~Manual C/C++ dialect compatibility matrix in **TODO.md**~~~ - ❌ (CI is the record of actively exercised builds; automated/semi-automated reporting deferred to **1.12**);
+* [x] ~~~Migrate/deprecate **include/stlsoft/std/**`*` in parallel with `*printf.h`~~~ - ❌ (cut);
 
 
 <!-- ########################### end of file ########################### -->

include/stlsoft/string/copy_functions.h

@@ -4,7 +4,7 @@
  * Purpose: String copy functions.
  *
  * Created: 29th September 2016
- * Updated: 11th October 2026
+ * Updated: 13th October 2026
  *
  * Home:    http://stlsoft.org/
  *
@@ -54,8 +54,8 @@
 #ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION
 # define STLSOFT_VER_STLSOFT_STRING_H_COPY_FUNCTIONS_MAJOR      2
 # define STLSOFT_VER_STLSOFT_STRING_H_COPY_FUNCTIONS_MINOR      0
-# define STLSOFT_VER_STLSOFT_STRING_H_COPY_FUNCTIONS_REVISION   5
-# define STLSOFT_VER_STLSOFT_STRING_H_COPY_FUNCTIONS_EDIT       17
+# define STLSOFT_VER_STLSOFT_STRING_H_COPY_FUNCTIONS_REVISION   7
+# define STLSOFT_VER_STLSOFT_STRING_H_COPY_FUNCTIONS_EDIT       18
 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */
 
 
@@ -114,7 +114,7 @@ namespace stlsoft
  */
 STLSOFT_INLINE
 ss_size_t
-STLSoft_C_string_copy_a(
+stlsoft_C_string_copy_a(
     ss_char_a_t             dest[]
 ,   ss_size_t               cchDest
 ,   ss_char_a_t const*      src
@@ -144,7 +144,7 @@ STLSoft_C_string_copy_a(
 
 STLSOFT_INLINE
 ss_size_t
-STLSoft_C_string_copy_w(
+stlsoft_C_string_copy_w(
     ss_char_w_t             dest[]
 ,   ss_size_t               cchDest
 ,   ss_char_w_t const*      src
@@ -190,7 +190,7 @@ STLSoft_C_string_copy_w(
  */
 STLSOFT_INLINE
 ss_size_t
-STLSoft_C_string_copy_with_nul_a(
+stlsoft_C_string_copy_with_nul_a(
     ss_char_a_t             dest[]
 ,   ss_size_t               cchDest
 ,   ss_char_a_t const*      src
@@ -230,7 +230,7 @@ STLSoft_C_string_copy_with_nul_a(
 
 STLSOFT_INLINE
 ss_size_t
-STLSoft_C_string_copy_with_nul_w(
+stlsoft_C_string_copy_with_nul_w(
     ss_char_w_t             dest[]
 ,   ss_size_t               cchDest
 ,   ss_char_w_t const*      src
@@ -289,7 +289,7 @@ string_copy(
 ,   ss_size_t               cchSrc
 )
 {
-    return STLSoft_C_string_copy_a(dest, cchDest, src, cchSrc);
+    return stlsoft_C_string_copy_a(dest, cchDest, src, cchSrc);
 }
 
 inline
@@ -301,7 +301,7 @@ string_copy(
 ,   ss_size_t               cchSrc
 )
 {
-    return STLSoft_C_string_copy_w(dest, cchDest, src, cchSrc);
+    return stlsoft_C_string_copy_w(dest, cchDest, src, cchSrc);
 }
 
 inline
@@ -312,7 +312,7 @@ string_copy(
 ,   string_slice_a_t const& src
 )
 {
-    return STLSoft_C_string_copy_a(&dest[0], cchDest, src.ptr, src.len);
+    return stlsoft_C_string_copy_a(&dest[0], cchDest, src.ptr, src.len);
 }
 
 inline
@@ -323,7 +323,7 @@ string_copy(
 ,   string_slice_w_t const& src
 )
 {
-    return STLSoft_C_string_copy_w(&dest[0], cchDest, src.ptr, src.len);
+    return stlsoft_C_string_copy_w(&dest[0], cchDest, src.ptr, src.len);
 }
 # ifdef STLSOFT_CF_STATIC_ARRAY_SIZE_DETERMINATION_SUPPORT
 
@@ -338,7 +338,7 @@ string_copy(
 ,   ss_char_a_t const     (&src)[N_src]
 )
 {
-    return STLSoft_C_string_copy_a(&dest[0], N_dest, &src[0], N_src);
+    return stlsoft_C_string_copy_a(&dest[0], N_dest, &src[0], N_src);
 }
 
 template<
@@ -352,7 +352,7 @@ string_copy(
 ,   ss_char_w_t const     (&src)[N_src]
 )
 {
-    return STLSoft_C_string_copy_w(&dest[0], N_dest, &src[0], N_src);
+    return stlsoft_C_string_copy_w(&dest[0], N_dest, &src[0], N_src);
 }
 
 template<
@@ -365,7 +365,7 @@ string_copy(
 ,   string_slice_a_t const& src
 )
 {
-    return STLSoft_C_string_copy_a(&dest[0], N_dest, src.ptr, src.len);
+    return stlsoft_C_string_copy_a(&dest[0], N_dest, src.ptr, src.len);
 }
 
 template<
@@ -378,7 +378,7 @@ string_copy(
 ,   string_slice_w_t const& src
 )
 {
-    return STLSoft_C_string_copy_w(&dest[0], N_dest, src.ptr, src.len);
+    return stlsoft_C_string_copy_w(&dest[0], N_dest, src.ptr, src.len);
 }
 # endif /* !STLSOFT_CF_STATIC_ARRAY_SIZE_DETERMINATION_SUPPORT */
 
@@ -393,7 +393,7 @@ string_copy_with_nul(
 ,   ss_size_t               cchSrc
 )
 {
-    return STLSoft_C_string_copy_with_nul_a(dest, cchDest, src, cchSrc);
+    return stlsoft_C_string_copy_with_nul_a(dest, cchDest, src, cchSrc);
 }
 
 inline
@@ -405,7 +405,7 @@ string_copy_with_nul(
 ,   ss_size_t               cchSrc
 )
 {
-    return STLSoft_C_string_copy_with_nul_w(dest, cchDest, src, cchSrc);
+    return stlsoft_C_string_copy_with_nul_w(dest, cchDest, src, cchSrc);
 }
 
 inline
@@ -416,7 +416,7 @@ string_copy_with_nul(
 ,   string_slice_a_t const& src
 )
 {
-    return STLSoft_C_string_copy_with_nul_a(&dest[0], cchDest, src.ptr, src.len);
+    return stlsoft_C_string_copy_with_nul_a(&dest[0], cchDest, src.ptr, src.len);
 }
 
 inline
@@ -427,7 +427,7 @@ string_copy_with_nul(
 ,   string_slice_w_t const& src
 )
 {
-    return STLSoft_C_string_copy_with_nul_w(&dest[0], cchDest, src.ptr, src.len);
+    return stlsoft_C_string_copy_with_nul_w(&dest[0], cchDest, src.ptr, src.len);
 }
 # ifdef STLSOFT_CF_STATIC_ARRAY_SIZE_DETERMINATION_SUPPORT
 
@@ -442,7 +442,7 @@ string_copy_with_nul(
 ,   ss_char_a_t const     (&src)[N_src]
 )
 {
-    return STLSoft_C_string_copy_with_nul_a(&dest[0], N_dest, &src[0], N_src);
+    return stlsoft_C_string_copy_with_nul_a(&dest[0], N_dest, &src[0], N_src);
 }
 
 template<
@@ -456,7 +456,7 @@ string_copy_with_nul(
 ,   ss_char_w_t const     (&src)[N_src]
 )
 {
-    return STLSoft_C_string_copy_with_nul_w(&dest[0], N_dest, &src[0], N_src);
+    return stlsoft_C_string_copy_with_nul_w(&dest[0], N_dest, &src[0], N_src);
 }
 
 template<
@@ -469,7 +469,7 @@ string_copy_with_nul(
 ,   string_slice_a_t const& src
 )
 {
-    return STLSoft_C_string_copy_with_nul_a(&dest[0], N_dest, src.ptr, src.len);
+    return stlsoft_C_string_copy_with_nul_a(&dest[0], N_dest, src.ptr, src.len);
 }
 
 template<
@@ -482,12 +482,76 @@ string_copy_with_nul(
 ,   string_slice_w_t const& src
 )
 {
-    return STLSoft_C_string_copy_with_nul_w(&dest[0], N_dest, src.ptr, src.len);
+    return stlsoft_C_string_copy_with_nul_w(&dest[0], N_dest, src.ptr, src.len);
 }
 # endif /* !STLSOFT_CF_STATIC_ARRAY_SIZE_DETERMINATION_SUPPORT */
 #endif /* __cplusplus */
 
 
+/* /////////////////////////////////////////////////////////////////////////
+ * backwards compatibility
+ *
+ * Older mixed-case names are retained (deprecated) until at least STLSoft
+ * 1.13.
+ */
+
+#ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION
+
+STLSOFT_DECLARE_FUNCTION_DEPRECATION_IN_FAVOUR_OF(STLSoft_C_string_copy_a, stlsoft_C_string_copy_a)
+STLSOFT_INLINE
+ss_size_t
+STLSoft_C_string_copy_a(
+    ss_char_a_t             dest[]
+,   ss_size_t               cchDest
+,   ss_char_a_t const*      src
+,   ss_size_t               cchSrc
+)
+{
+    return stlsoft_C_string_copy_a(dest, cchDest, src, cchSrc);
+}
+
+STLSOFT_DECLARE_FUNCTION_DEPRECATION_IN_FAVOUR_OF(STLSoft_C_string_copy_w, stlsoft_C_string_copy_w)
+STLSOFT_INLINE
+ss_size_t
+STLSoft_C_string_copy_w(
+    ss_char_w_t             dest[]
+,   ss_size_t               cchDest
+,   ss_char_w_t const*      src
+,   ss_size_t               cchSrc
+)
+{
+    return stlsoft_C_string_copy_w(dest, cchDest, src, cchSrc);
+}
+
+STLSOFT_DECLARE_FUNCTION_DEPRECATION_IN_FAVOUR_OF(STLSoft_C_string_copy_with_nul_a, stlsoft_C_string_copy_with_nul_a)
+STLSOFT_INLINE
+ss_size_t
+STLSoft_C_string_copy_with_nul_a(
+    ss_char_a_t             dest[]
+,   ss_size_t               cchDest
+,   ss_char_a_t const*      src
+,   ss_size_t               cchSrc
+)
+{
+    return stlsoft_C_string_copy_with_nul_a(dest, cchDest, src, cchSrc);
+}
+
+STLSOFT_DECLARE_FUNCTION_DEPRECATION_IN_FAVOUR_OF(STLSoft_C_string_copy_with_nul_w, stlsoft_C_string_copy_with_nul_w)
+STLSOFT_INLINE
+ss_size_t
+STLSoft_C_string_copy_with_nul_w(
+    ss_char_w_t             dest[]
+,   ss_size_t               cchDest
+,   ss_char_w_t const*      src
+,   ss_size_t               cchSrc
+)
+{
+    return stlsoft_C_string_copy_with_nul_w(dest, cchDest, src, cchSrc);
+}
+
+#endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */
+
+
 /* /////////////////////////////////////////////////////////////////////////
  * namespace
  */