From fae761b84634db1e77700dd634f10c5d2ed1b63f Mon Sep 17 00:00:00 2001 From: Matt Wilson Date: Mon, 12 Oct 2026 18:00:33 +1100 Subject: [PATCH 1/6] docs(stlsoft): track lowercase _C_ prefix normalisation in TODO Add 1.11.12 capturing the house form _C_, the known mixed/UPPER exception pockets (STLSoft_C_, WinSTL_C_, PathType, PATH_CLASSIFY_IMPL), and an open decision on STLSOFT_C_* macros. --- TODO.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/TODO.md b/TODO.md index fae197b5..ee21cc50 100644 --- a/TODO.md +++ b/TODO.md @@ -17,6 +17,7 @@ - [1.11.9](#1119) - [1.11.10](#11110) - [1.11.11](#11111) + - [1.11.12](#11112) - [1.12](#112) - [Requires clarification by project maintainers](#requires-clarification-by-project-maintainers) - [Abandoned](#abandoned) @@ -96,6 +97,18 @@ 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 to the house form **`_C_`** (all-lowercase project key). Survey of **include/** own-prefixes: lowercase already dominates (`comstl`, `mfcstl`, `platformstl`, and the bulk of `stlsoft` / `unixstl` / `winstl`); mixed (`STLSoft_C_`, `WinSTL_C_`) and UPPER (`STLSOFT_C_`, `UNIXSTL_C_`, `WINSTL_C_`) are local exceptions only. No `PlatformSTL_C_` / `UnixSTL_C_` / `ComSTL_C_` forms exist. + +* [ ] Establish and document the rule: new C functions / C-facing enums use lowercase `_C_`; do not introduce `WinSTL_C_`, `STLSoft_C_`, or similar mixed forms; +* [ ] Rename `STLSoft_C_string_copy*` / `STLSoft_C_string_copy_with_nul*` → `stlsoft_C_*` in **include/stlsoft/string/copy_functions.h** and all call sites; +* [ ] Rename `WinSTL_C_FileInformation_*` → `winstl_C_*` in **include/winstl/filesystem/file_information_functions.h** and call sites; +* [ ] Rename path-classify `PathType` enumerators: `WinSTL_C_PathType_*` → `winstl_C_PathType_*`, and `UNIXSTL_C_PathType_*` → `unixstl_C_PathType_*`; +* [ ] Rename path-classify impl macros `WINSTL_C_PATH_CLASSIFY_IMPL_*` / `UNIXSTL_C_PATH_CLASSIFY_IMPL_*` → lowercase `_C_*` forms; +* [ ] Decide policy for remaining UPPER macro tokens such as `STLSOFT_C_AUTO_BUFFER_*` and `STLSOFT_C_CAST` (keep UPPER as macro convention, or migrate to `stlsoft_C_*`); then apply consistently; + + ## 1.12 From **1.12** onwards, every new component or feature must ship with an **example**, **unit tests**, and a **blog entry** on the new Website (website work is contemporaneous with 1.12). See **oss-library-modernisation** (STLSoft 1.12+ feature completeness). From 01fea1ed88fa0845cb80af68fb3c4a6eeb4de674 Mon Sep 17 00:00:00 2001 From: Matt Wilson Date: Mon, 12 Oct 2026 18:18:52 +1100 Subject: [PATCH 2/6] refactor(stlsoft): lowercase C API prefixes with deprecated aliases MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rename STLSoft_C_string_copy* → stlsoft_C_* and WinSTL_C_FileInformation_* → winstl_C_*, retaining deprecated wrappers via STLSOFT_DECLARE_FUNCTION_DEPRECATION_IN_FAVOUR_OF; update unixstl directory_functions call sites; bump per-file REVISION/EDIT. --- TODO.md | 4 +- include/stlsoft/string/copy_functions.h | 109 ++++++++++++++---- include/unixstl/system/directory_functions.h | 16 +-- .../filesystem/file_information_functions.h | 99 +++++++++++++--- 4 files changed, 177 insertions(+), 51 deletions(-) diff --git a/TODO.md b/TODO.md index ee21cc50..467c6974 100644 --- a/TODO.md +++ b/TODO.md @@ -102,8 +102,8 @@ Dedicated increment: **test analysis and coverage only** — no other product ch Normalise C API (and related C-facing) identifier prefixes to the house form **`_C_`** (all-lowercase project key). Survey of **include/** own-prefixes: lowercase already dominates (`comstl`, `mfcstl`, `platformstl`, and the bulk of `stlsoft` / `unixstl` / `winstl`); mixed (`STLSoft_C_`, `WinSTL_C_`) and UPPER (`STLSOFT_C_`, `UNIXSTL_C_`, `WINSTL_C_`) are local exceptions only. No `PlatformSTL_C_` / `UnixSTL_C_` / `ComSTL_C_` forms exist. * [ ] Establish and document the rule: new C functions / C-facing enums use lowercase `_C_`; do not introduce `WinSTL_C_`, `STLSoft_C_`, or similar mixed forms; -* [ ] Rename `STLSoft_C_string_copy*` / `STLSoft_C_string_copy_with_nul*` → `stlsoft_C_*` in **include/stlsoft/string/copy_functions.h** and all call sites; -* [ ] Rename `WinSTL_C_FileInformation_*` → `winstl_C_*` in **include/winstl/filesystem/file_information_functions.h** and call sites; +* [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)~~~ - ✅; +* [x] ~~~Rename `WinSTL_C_FileInformation_*` → `winstl_C_*` in **include/winstl/filesystem/file_information_functions.h** and call sites (deprecated wrappers retained)~~~ - ✅; * [ ] Rename path-classify `PathType` enumerators: `WinSTL_C_PathType_*` → `winstl_C_PathType_*`, and `UNIXSTL_C_PathType_*` → `unixstl_C_PathType_*`; * [ ] Rename path-classify impl macros `WINSTL_C_PATH_CLASSIFY_IMPL_*` / `UNIXSTL_C_PATH_CLASSIFY_IMPL_*` → lowercase `_C_*` forms; * [ ] Decide policy for remaining UPPER macro tokens such as `STLSOFT_C_AUTO_BUFFER_*` and `STLSOFT_C_CAST` (keep UPPER as macro convention, or migrate to `stlsoft_C_*`); then apply consistently; diff --git a/include/stlsoft/string/copy_functions.h b/include/stlsoft/string/copy_functions.h index 313a0105..1b4ed28b 100644 --- a/include/stlsoft/string/copy_functions.h +++ b/include/stlsoft/string/copy_functions.h @@ -4,11 +4,11 @@ * Purpose: String copy functions. * * Created: 29th September 2016 - * Updated: 26th April 2025 + * Updated: 12th October 2026 * * Home: http://stlsoft.org/ * - * Copyright (c) 2019-2025, Matthew Wilson and Synesis Information Systems + * Copyright (c) 2019-2026, Matthew Wilson and Synesis Information Systems * Copyright (c) 2016-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -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 15 +# define STLSOFT_VER_STLSOFT_STRING_H_COPY_FUNCTIONS_REVISION 6 +# define STLSOFT_VER_STLSOFT_STRING_H_COPY_FUNCTIONS_EDIT 16 #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,73 @@ 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 + */ + +#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 */ diff --git a/include/unixstl/system/directory_functions.h b/include/unixstl/system/directory_functions.h index ee78e61a..f873e31b 100644 --- a/include/unixstl/system/directory_functions.h +++ b/include/unixstl/system/directory_functions.h @@ -4,11 +4,11 @@ * Purpose: Directory functions. * * Created: 1st October 2016 - * Updated: 26th April 2025 + * Updated: 12th October 2026 * * Home: http://stlsoft.org/ * - * Copyright (c) 2019-2025, Matthew Wilson and Synesis Information Systems + * Copyright (c) 2019-2026, Matthew Wilson and Synesis Information Systems * Copyright (c) 2016-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -53,8 +53,8 @@ #ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION # define UNIXSTL_VER_UNIXSTL_SYSTEM_H_DIRECTORY_FUNCTIONS_MAJOR 1 # define UNIXSTL_VER_UNIXSTL_SYSTEM_H_DIRECTORY_FUNCTIONS_MINOR 0 -# define UNIXSTL_VER_UNIXSTL_SYSTEM_H_DIRECTORY_FUNCTIONS_REVISION 13 -# define UNIXSTL_VER_UNIXSTL_SYSTEM_H_DIRECTORY_FUNCTIONS_EDIT 23 +# define UNIXSTL_VER_UNIXSTL_SYSTEM_H_DIRECTORY_FUNCTIONS_REVISION 14 +# define UNIXSTL_VER_UNIXSTL_SYSTEM_H_DIRECTORY_FUNCTIONS_EDIT 24 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -172,18 +172,18 @@ unixstl_C_get_home_directory_invoke_getenv_a_( us_size_t s = buff.size; us_size_t n; - n = STLSoft_C_string_copy_a(p, s, s_szHomeUnique, cchHomeUnique); + n = stlsoft_C_string_copy_a(p, s, s_szHomeUnique, cchHomeUnique); p += n; s -= n; *p++ = '='; --s; - n = STLSoft_C_string_copy_a(p, s, homeDrive, cchHomeDrive); + n = stlsoft_C_string_copy_a(p, s, homeDrive, cchHomeDrive); p += n; s -= n; - n = STLSoft_C_string_copy_a(p, s, homePath, cchHomePath); + n = stlsoft_C_string_copy_a(p, s, homePath, cchHomePath); p += n; s -= n; @@ -233,7 +233,7 @@ unixstl_C_get_home_directory_a( return cchHome + 1; } - return STLSoft_C_string_copy_with_nul_a(buffer, cchBuffer, home, cchHome); + return stlsoft_C_string_copy_with_nul_a(buffer, cchBuffer, home, cchHome); } } diff --git a/include/winstl/filesystem/file_information_functions.h b/include/winstl/filesystem/file_information_functions.h index 8b7051c2..eb49d459 100644 --- a/include/winstl/filesystem/file_information_functions.h +++ b/include/winstl/filesystem/file_information_functions.h @@ -4,11 +4,11 @@ * Purpose: File functions. * * Created: 7th November 2014 - * Updated: 11th March 2024 + * Updated: 12th October 2026 * * Home: http://stlsoft.org/ * - * Copyright (c) 2019-2024, Matthew Wilson and Synesis Information Systems + * Copyright (c) 2019-2026, Matthew Wilson and Synesis Information Systems * Copyright (c) 2014-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -53,8 +53,8 @@ #ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION # define WINSTL_VER_WINSTL_H_FILE_INFORMATION_FUNCTIONS_MAJOR 2 # define WINSTL_VER_WINSTL_H_FILE_INFORMATION_FUNCTIONS_MINOR 0 -# define WINSTL_VER_WINSTL_H_FILE_INFORMATION_FUNCTIONS_REVISION 4 -# define WINSTL_VER_WINSTL_H_FILE_INFORMATION_FUNCTIONS_EDIT 10 +# define WINSTL_VER_WINSTL_H_FILE_INFORMATION_FUNCTIONS_REVISION 5 +# define WINSTL_VER_WINSTL_H_FILE_INFORMATION_FUNCTIONS_EDIT 11 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -105,7 +105,7 @@ namespace winstl_project STLSOFT_INLINE SECURITY_DESCRIPTOR* -WinSTL_C_FileInformation_alloc_( +winstl_C_FileInformation_alloc_( ws_size_t cb ) { @@ -114,7 +114,7 @@ WinSTL_C_FileInformation_alloc_( STLSOFT_INLINE void -WinSTL_C_FileInformation_free_( +winstl_C_FileInformation_free_( void* pv ) { @@ -130,16 +130,16 @@ WinSTL_C_FileInformation_free_( STLSOFT_INLINE void -WinSTL_C_FileInformation_free_SECURITY_DESCRIPTOR( +winstl_C_FileInformation_free_SECURITY_DESCRIPTOR( SECURITY_DESCRIPTOR* psd ) { - WinSTL_C_FileInformation_free_(psd); + winstl_C_FileInformation_free_(psd); } STLSOFT_INLINE BOOL -WinSTL_C_FileInformation_get_SECURITY_DESCRIPTOR_a( +winstl_C_FileInformation_get_SECURITY_DESCRIPTOR_a( ws_char_a_t const* path , SECURITY_INFORMATION si , SECURITY_DESCRIPTOR** ppsd @@ -172,7 +172,7 @@ WinSTL_C_FileInformation_get_SECURITY_DESCRIPTOR_a( return FALSE; } - *ppsd = WinSTL_C_FileInformation_alloc_(dwSize); + *ppsd = winstl_C_FileInformation_alloc_(dwSize); if (NULL == *ppsd) { @@ -186,7 +186,7 @@ WinSTL_C_FileInformation_get_SECURITY_DESCRIPTOR_a( return TRUE; } - WinSTL_C_FileInformation_free_(*ppsd); + winstl_C_FileInformation_free_(*ppsd); *pcbsd = 0; } @@ -196,7 +196,7 @@ WinSTL_C_FileInformation_get_SECURITY_DESCRIPTOR_a( STLSOFT_INLINE BOOL -WinSTL_C_FileInformation_get_SECURITY_DESCRIPTOR_w( +winstl_C_FileInformation_get_SECURITY_DESCRIPTOR_w( ws_char_w_t const* path , SECURITY_INFORMATION si , SECURITY_DESCRIPTOR** ppsd @@ -229,7 +229,7 @@ WinSTL_C_FileInformation_get_SECURITY_DESCRIPTOR_w( return FALSE; } - *ppsd = WinSTL_C_FileInformation_alloc_(dwSize); + *ppsd = winstl_C_FileInformation_alloc_(dwSize); if (NULL == *ppsd) { @@ -243,7 +243,7 @@ WinSTL_C_FileInformation_get_SECURITY_DESCRIPTOR_w( return TRUE; } - WinSTL_C_FileInformation_free_(*ppsd); + winstl_C_FileInformation_free_(*ppsd); *pcbsd = 0; } @@ -276,7 +276,7 @@ free_SECURITY_DESCRIPTOR( SECURITY_DESCRIPTOR* psd ) { - WinSTL_C_FileInformation_free_SECURITY_DESCRIPTOR(psd); + winstl_C_FileInformation_free_SECURITY_DESCRIPTOR(psd); } inline @@ -288,7 +288,7 @@ get_SECURITY_DESCRIPTOR( , ws_size_t* pcbsd = NULL ) { - return WinSTL_C_FileInformation_get_SECURITY_DESCRIPTOR_a(path, si, ppsd, pcbsd); + return winstl_C_FileInformation_get_SECURITY_DESCRIPTOR_a(path, si, ppsd, pcbsd); } inline @@ -300,12 +300,77 @@ get_SECURITY_DESCRIPTOR( , ws_size_t* pcbsd = NULL ) { - return WinSTL_C_FileInformation_get_SECURITY_DESCRIPTOR_w(path, si, ppsd, pcbsd); + return winstl_C_FileInformation_get_SECURITY_DESCRIPTOR_w(path, si, ppsd, pcbsd); } } /* namespace file_information */ #endif /* !WINSTL_NO_NAMESPACE */ + +/* ///////////////////////////////////////////////////////////////////////// + * backwards compatibility + */ + +#ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION + +STLSOFT_DECLARE_FUNCTION_DEPRECATION_IN_FAVOUR_OF(WinSTL_C_FileInformation_alloc_, winstl_C_FileInformation_alloc_) +STLSOFT_INLINE +SECURITY_DESCRIPTOR* +WinSTL_C_FileInformation_alloc_( + ws_size_t cb +) +{ + return winstl_C_FileInformation_alloc_(cb); +} + +STLSOFT_DECLARE_FUNCTION_DEPRECATION_IN_FAVOUR_OF(WinSTL_C_FileInformation_free_, winstl_C_FileInformation_free_) +STLSOFT_INLINE +void +WinSTL_C_FileInformation_free_( + void* pv +) +{ + winstl_C_FileInformation_free_(pv); +} + +STLSOFT_DECLARE_FUNCTION_DEPRECATION_IN_FAVOUR_OF(WinSTL_C_FileInformation_free_SECURITY_DESCRIPTOR, winstl_C_FileInformation_free_SECURITY_DESCRIPTOR) +STLSOFT_INLINE +void +WinSTL_C_FileInformation_free_SECURITY_DESCRIPTOR( + SECURITY_DESCRIPTOR* psd +) +{ + winstl_C_FileInformation_free_SECURITY_DESCRIPTOR(psd); +} + +STLSOFT_DECLARE_FUNCTION_DEPRECATION_IN_FAVOUR_OF(WinSTL_C_FileInformation_get_SECURITY_DESCRIPTOR_a, winstl_C_FileInformation_get_SECURITY_DESCRIPTOR_a) +STLSOFT_INLINE +BOOL +WinSTL_C_FileInformation_get_SECURITY_DESCRIPTOR_a( + ws_char_a_t const* path +, SECURITY_INFORMATION si +, SECURITY_DESCRIPTOR** ppsd +, ws_size_t* pcbsd +) +{ + return winstl_C_FileInformation_get_SECURITY_DESCRIPTOR_a(path, si, ppsd, pcbsd); +} + +STLSOFT_DECLARE_FUNCTION_DEPRECATION_IN_FAVOUR_OF(WinSTL_C_FileInformation_get_SECURITY_DESCRIPTOR_w, winstl_C_FileInformation_get_SECURITY_DESCRIPTOR_w) +STLSOFT_INLINE +BOOL +WinSTL_C_FileInformation_get_SECURITY_DESCRIPTOR_w( + ws_char_w_t const* path +, SECURITY_INFORMATION si +, SECURITY_DESCRIPTOR** ppsd +, ws_size_t* pcbsd +) +{ + return winstl_C_FileInformation_get_SECURITY_DESCRIPTOR_w(path, si, ppsd, pcbsd); +} + +#endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ + /* ////////////////////////////////////////////////////////////////////// */ #if !defined(WINSTL_NO_NAMESPACE) && \ From eeaafff348811b064baf7fa70eeeeb4e90fd1ad6 Mon Sep 17 00:00:00 2001 From: Matt Wilson Date: Tue, 13 Oct 2026 09:21:31 +1100 Subject: [PATCH 3/6] chore: tidying --- TODO.md | 9 +++++---- include/stlsoft/string/copy_functions.h | 9 ++++++--- .../filesystem/file_information_functions.h | 17 ++++++++++------- 3 files changed, 21 insertions(+), 14 deletions(-) diff --git a/TODO.md b/TODO.md index 467c6974..99c5483c 100644 --- a/TODO.md +++ b/TODO.md @@ -102,11 +102,12 @@ Dedicated increment: **test analysis and coverage only** — no other product ch Normalise C API (and related C-facing) identifier prefixes to the house form **`_C_`** (all-lowercase project key). Survey of **include/** own-prefixes: lowercase already dominates (`comstl`, `mfcstl`, `platformstl`, and the bulk of `stlsoft` / `unixstl` / `winstl`); mixed (`STLSoft_C_`, `WinSTL_C_`) and UPPER (`STLSOFT_C_`, `UNIXSTL_C_`, `WINSTL_C_`) are local exceptions only. No `PlatformSTL_C_` / `UnixSTL_C_` / `ComSTL_C_` forms exist. * [ ] Establish and document the rule: new C functions / C-facing enums use lowercase `_C_`; do not introduce `WinSTL_C_`, `STLSoft_C_`, or similar mixed forms; -* [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)~~~ - ✅; -* [x] ~~~Rename `WinSTL_C_FileInformation_*` → `winstl_C_*` in **include/winstl/filesystem/file_information_functions.h** and call sites (deprecated wrappers retained)~~~ - ✅; -* [ ] Rename path-classify `PathType` enumerators: `WinSTL_C_PathType_*` → `winstl_C_PathType_*`, and `UNIXSTL_C_PathType_*` → `unixstl_C_PathType_*`; -* [ ] Rename path-classify impl macros `WINSTL_C_PATH_CLASSIFY_IMPL_*` / `UNIXSTL_C_PATH_CLASSIFY_IMPL_*` → lowercase `_C_*` forms; +* [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**)~~~ - ✅; +* [ ] Rename path-classify `PathType` enumerators: `WinSTL_C_PathType_*` → `winstl_C_PathType_*`, and `UNIXSTL_C_PathType_*` → `unixstl_C_PathType_*` (retain deprecated older forms until at least **1.13**); +* [ ] Rename path-classify impl macros `WINSTL_C_PATH_CLASSIFY_IMPL_*` / `UNIXSTL_C_PATH_CLASSIFY_IMPL_*` → lowercase `_C_*` forms (retain deprecated older forms until at least **1.13** where applicable); * [ ] Decide policy for remaining UPPER macro tokens such as `STLSOFT_C_AUTO_BUFFER_*` and `STLSOFT_C_CAST` (keep UPPER as macro convention, or migrate to `stlsoft_C_*`); then apply consistently; +* [ ] **1.13+**: consider removing deprecated mixed-case C API wrappers (`STLSoft_C_*`, `WinSTL_C_*`, and any later-deprecated forms) — not before; ## 1.12 diff --git a/include/stlsoft/string/copy_functions.h b/include/stlsoft/string/copy_functions.h index 1b4ed28b..2fdb9d8a 100644 --- a/include/stlsoft/string/copy_functions.h +++ b/include/stlsoft/string/copy_functions.h @@ -4,7 +4,7 @@ * Purpose: String copy functions. * * Created: 29th September 2016 - * Updated: 12th 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 6 -# define STLSOFT_VER_STLSOFT_STRING_H_COPY_FUNCTIONS_EDIT 16 +# define STLSOFT_VER_STLSOFT_STRING_H_COPY_FUNCTIONS_REVISION 7 +# define STLSOFT_VER_STLSOFT_STRING_H_COPY_FUNCTIONS_EDIT 17 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -490,6 +490,9 @@ string_copy_with_nul( /* ///////////////////////////////////////////////////////////////////////// * backwards compatibility + * + * Older mixed-case names are retained (deprecated) until at least STLSoft + * 1.13. */ #ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION diff --git a/include/winstl/filesystem/file_information_functions.h b/include/winstl/filesystem/file_information_functions.h index eb49d459..d93926c2 100644 --- a/include/winstl/filesystem/file_information_functions.h +++ b/include/winstl/filesystem/file_information_functions.h @@ -1,12 +1,12 @@ /* ///////////////////////////////////////////////////////////////////////// - * File: winstl/filesystem/file_information_functions.h + * File: winstl/filesystem/file_information_functions.h * - * Purpose: File functions. + * Purpose: File functions. * - * Created: 7th November 2014 - * Updated: 12th October 2026 + * Created: 7th November 2014 + * Updated: 13th October 2026 * - * Home: http://stlsoft.org/ + * Home: http://stlsoft.org/ * * Copyright (c) 2019-2026, Matthew Wilson and Synesis Information Systems * Copyright (c) 2014-2019, Matthew Wilson and Synesis Software @@ -53,8 +53,8 @@ #ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION # define WINSTL_VER_WINSTL_H_FILE_INFORMATION_FUNCTIONS_MAJOR 2 # define WINSTL_VER_WINSTL_H_FILE_INFORMATION_FUNCTIONS_MINOR 0 -# define WINSTL_VER_WINSTL_H_FILE_INFORMATION_FUNCTIONS_REVISION 5 -# define WINSTL_VER_WINSTL_H_FILE_INFORMATION_FUNCTIONS_EDIT 11 +# define WINSTL_VER_WINSTL_H_FILE_INFORMATION_FUNCTIONS_REVISION 6 +# define WINSTL_VER_WINSTL_H_FILE_INFORMATION_FUNCTIONS_EDIT 12 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -309,6 +309,9 @@ get_SECURITY_DESCRIPTOR( /* ///////////////////////////////////////////////////////////////////////// * backwards compatibility + * + * Older mixed-case names are retained (deprecated) until at least STLSoft + * 1.13. */ #ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION From 70469ee93c8bafa1e49fba115f4c279c10bd9360 Mon Sep 17 00:00:00 2001 From: Matt Wilson Date: Sun, 18 Oct 2026 17:13:06 +1100 Subject: [PATCH 4/6] TODO.md --- TODO.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/TODO.md b/TODO.md index a8983c9b..25dc0583 100644 --- a/TODO.md +++ b/TODO.md @@ -32,9 +32,6 @@ * [x] ~~~ACESTL: implement `invoke_ACE_OS_snprintf` in terms of `stlsoft_C_snprintf()`~~~ - ✅; * [x] ~~~CI: exercise **ATLSTL** on a Windows cell~~~ - ✅; * [x] ~~~Unit/component tests — adopt **xTests** terse API throughout~~~ - ✅; -* [ ] 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.2 @@ -46,6 +43,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 @@ -81,7 +81,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 From 23ab22f7b75f48e215af370c2e86826030c58a8b Mon Sep 17 00:00:00 2001 From: Matt Wilson Date: Sun, 18 Oct 2026 17:21:33 +1100 Subject: [PATCH 5/6] refactor(stlsoft): lowercase PathType enumerators with BC macros Rename WinSTL_C_PathType_* / UNIXSTL_C_PathType_* to winstl_C_PathType_* / unixstl_C_PathType_*; retain legacy names as documentation-hidden macros until at least STLSoft 1.13. --- TODO.md | 2 +- .../filesystem/path_classify_functions.h | 70 +++++++++++----- .../path_functions/classify_functions_X_.h | 26 +++--- include/winstl/filesystem/path.hpp | 42 +++++----- .../filesystem/path_classify_functions.h | 80 +++++++++++++------ .../path_functions/classify_functions_X_.h | 70 ++++++++-------- 6 files changed, 173 insertions(+), 117 deletions(-) diff --git a/TODO.md b/TODO.md index 25dc0583..948cc614 100644 --- a/TODO.md +++ b/TODO.md @@ -106,7 +106,7 @@ Normalise C API (and related C-facing) identifier prefixes to the house form **` * [ ] Establish and document the rule: new C functions / C-facing enums use lowercase `_C_`; do not introduce `WinSTL_C_`, `STLSoft_C_`, or similar mixed forms; * [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**)~~~ - ✅; -* [ ] Rename path-classify `PathType` enumerators: `WinSTL_C_PathType_*` → `winstl_C_PathType_*`, and `UNIXSTL_C_PathType_*` → `unixstl_C_PathType_*` (retain deprecated older forms 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**)~~~ - ✅; * [ ] Rename path-classify impl macros `WINSTL_C_PATH_CLASSIFY_IMPL_*` / `UNIXSTL_C_PATH_CLASSIFY_IMPL_*` → lowercase `_C_*` forms (retain deprecated older forms until at least **1.13** where applicable); * [ ] Decide policy for remaining UPPER macro tokens such as `STLSOFT_C_AUTO_BUFFER_*` and `STLSOFT_C_CAST` (keep UPPER as macro convention, or migrate to `stlsoft_C_*`); then apply consistently; * [ ] **1.13+**: consider removing deprecated mixed-case C API wrappers (`STLSoft_C_*`, `WinSTL_C_*`, and any later-deprecated forms) — not before; diff --git a/include/unixstl/filesystem/path_classify_functions.h b/include/unixstl/filesystem/path_classify_functions.h index b1233cde..f22d4717 100644 --- a/include/unixstl/filesystem/path_classify_functions.h +++ b/include/unixstl/filesystem/path_classify_functions.h @@ -4,11 +4,11 @@ * Purpose: Path classification functions * * Created: 21st December 2020 - * Updated: 20th October 2024 + * Updated: 18th October 2026 * * Home: http://stlsoft.org/ * - * Copyright (c) 2020-2024, Matthew Wilson and Synesis Information Systems + * Copyright (c) 2020-2026, Matthew Wilson and Synesis Information Systems * All rights reserved. * * Redistribution and use in source and binary forms, with or without @@ -52,8 +52,8 @@ #ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION # define UNIXSTL_VER_UNIXSTL_FILESYSTEM_H_PATH_CLASSIFY_FUNCTIONS_MAJOR 1 # define UNIXSTL_VER_UNIXSTL_FILESYSTEM_H_PATH_CLASSIFY_FUNCTIONS_MINOR 0 -# define UNIXSTL_VER_UNIXSTL_FILESYSTEM_H_PATH_CLASSIFY_FUNCTIONS_REVISION 6 -# define UNIXSTL_VER_UNIXSTL_FILESYSTEM_H_PATH_CLASSIFY_FUNCTIONS_EDIT 9 +# define UNIXSTL_VER_UNIXSTL_FILESYSTEM_H_PATH_CLASSIFY_FUNCTIONS_REVISION 7 +# define UNIXSTL_VER_UNIXSTL_FILESYSTEM_H_PATH_CLASSIFY_FUNCTIONS_EDIT 10 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -88,28 +88,29 @@ enum unixstl_C_path_classification_t { - UNIXSTL_C_PathType_MIN_VALUE = -10000 - - , UNIXSTL_C_PathType_InvalidSlashRuns = -3 - , UNIXSTL_C_PathType_InvalidChars = -2 - , UNIXSTL_C_PathType_Invalid = -1 - , UNIXSTL_C_PathType_Unknown = 0 - , UNIXSTL_C_PathType_Empty - , UNIXSTL_C_PathType_Relative - , UNIXSTL_C_PathType_SlashRooted - , UNIXSTL_C_PathType_reserved_1 - , UNIXSTL_C_PathType_reserved_2 - , UNIXSTL_C_PathType_reserved_3 - , UNIXSTL_C_PathType_reserved_4 - , UNIXSTL_C_PathType_HomeRooted + unixstl_C_PathType_MIN_VALUE = -10000 + + , unixstl_C_PathType_InvalidSlashRuns = -3 + , unixstl_C_PathType_InvalidChars = -2 + , unixstl_C_PathType_Invalid = -1 + , unixstl_C_PathType_Unknown = 0 + , unixstl_C_PathType_Empty + , unixstl_C_PathType_Relative + , unixstl_C_PathType_SlashRooted + , unixstl_C_PathType_reserved_1 + , unixstl_C_PathType_reserved_2 + , unixstl_C_PathType_reserved_3 + , unixstl_C_PathType_reserved_4 + , unixstl_C_PathType_HomeRooted /* no enumerator to be placed AFTER this one */ - , UNIXSTL_C_PathType_MAX_VALUE + , unixstl_C_PathType_MAX_VALUE }; #ifndef __cplusplus typedef enum unixstl_C_path_classification_t unixstl_C_path_classification_t; #endif /* !__cplusplus */ + struct unixstl_C_path_classification_results_m_t { stlsoft_C_string_slice_m_t input; @@ -208,8 +209,8 @@ unixstl_C_path_is_rooted( { switch (pc) { - case UNIXSTL_C_PathType_SlashRooted: - case UNIXSTL_C_PathType_HomeRooted: + case unixstl_C_PathType_SlashRooted: + case unixstl_C_PathType_HomeRooted: return 1; default: @@ -319,6 +320,33 @@ path_is_rooted( #endif /* !UNIXSTL_NO_NAMESPACE */ +/* ///////////////////////////////////////////////////////////////////////// + * backwards compatibility + * + * Older UPPER-case enumerator names are retained (as macros) until at + * least STLSoft 1.13. + */ + +#ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION + +# define UNIXSTL_C_PathType_Empty unixstl_C_PathType_Empty +# define UNIXSTL_C_PathType_HomeRooted unixstl_C_PathType_HomeRooted +# define UNIXSTL_C_PathType_Invalid unixstl_C_PathType_Invalid +# define UNIXSTL_C_PathType_InvalidChars unixstl_C_PathType_InvalidChars +# define UNIXSTL_C_PathType_InvalidSlashRuns unixstl_C_PathType_InvalidSlashRuns +# define UNIXSTL_C_PathType_MAX_VALUE unixstl_C_PathType_MAX_VALUE +# define UNIXSTL_C_PathType_MIN_VALUE unixstl_C_PathType_MIN_VALUE +# define UNIXSTL_C_PathType_Relative unixstl_C_PathType_Relative +# define UNIXSTL_C_PathType_SlashRooted unixstl_C_PathType_SlashRooted +# define UNIXSTL_C_PathType_Unknown unixstl_C_PathType_Unknown +# define UNIXSTL_C_PathType_reserved_1 unixstl_C_PathType_reserved_1 +# define UNIXSTL_C_PathType_reserved_2 unixstl_C_PathType_reserved_2 +# define UNIXSTL_C_PathType_reserved_3 unixstl_C_PathType_reserved_3 +# define UNIXSTL_C_PathType_reserved_4 unixstl_C_PathType_reserved_4 + +#endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ + + /* ///////////////////////////////////////////////////////////////////////// * inclusion control */ diff --git a/include/unixstl/filesystem/path_functions/classify_functions_X_.h b/include/unixstl/filesystem/path_functions/classify_functions_X_.h index 680dab2a..c149a1d7 100644 --- a/include/unixstl/filesystem/path_functions/classify_functions_X_.h +++ b/include/unixstl/filesystem/path_functions/classify_functions_X_.h @@ -4,11 +4,11 @@ * Purpose: Path classification functions char-X implementation * * Created: 21st December 2020 - * Updated: 20th October 2024 + * Updated: 18th October 2026 * * Home: http://stlsoft.org/ * - * Copyright (c) 2020-2024, Matthew Wilson and Synesis Information Systems + * Copyright (c) 2020-2026, Matthew Wilson and Synesis Information Systems * All rights reserved. * * Redistribution and use in source and binary forms, with or without @@ -163,7 +163,7 @@ unixstl_C_path_classify_root_X_( { /* "/" */ - return UNIXSTL_C_PathType_SlashRooted; + return unixstl_C_PathType_SlashRooted; } if ('~' == s0[0]) @@ -175,7 +175,7 @@ unixstl_C_path_classify_root_X_( *ppS1 = s0 + 1; *pCch1 = cch0 - 1; - return UNIXSTL_C_PathType_HomeRooted; + return unixstl_C_PathType_HomeRooted; } else switch (s0[1]) @@ -185,12 +185,12 @@ unixstl_C_path_classify_root_X_( *ppS1 = s0 + 1; *pCch1 = cch0 - 1; - return UNIXSTL_C_PathType_HomeRooted; + return unixstl_C_PathType_HomeRooted; } } } - return UNIXSTL_C_PathType_Relative; + return unixstl_C_PathType_Relative; } STLSOFT_INLINE @@ -236,7 +236,7 @@ unixstl_C_path_classify_impl_X_( if (0 == cch0) { - return UNIXSTL_C_PathType_Empty; + return unixstl_C_PathType_Empty; } rcRoot = unixstl_C_path_classify_root_X_( @@ -251,9 +251,9 @@ unixstl_C_path_classify_impl_X_( switch (rcRoot) { - case UNIXSTL_C_PathType_Relative: - case UNIXSTL_C_PathType_SlashRooted: - case UNIXSTL_C_PathType_HomeRooted: + case unixstl_C_PathType_Relative: + case unixstl_C_PathType_SlashRooted: + case unixstl_C_PathType_HomeRooted: break; default: @@ -270,7 +270,7 @@ unixstl_C_path_classify_impl_X_( results->firstInvalid.len = 1; results->firstInvalid.ptr = invalidChar; - return UNIXSTL_C_PathType_InvalidChars; + return unixstl_C_PathType_InvalidChars; } if (ss_nullptr_k != (invalidChar = UNIXSTL_C_PATH_CLASSIFY_IMPL_stlsoft_C_strnchr_X_(s1, cch1, ':'))) @@ -278,7 +278,7 @@ unixstl_C_path_classify_impl_X_( results->firstInvalid.len = 1; results->firstInvalid.ptr = invalidChar; - return UNIXSTL_C_PathType_InvalidChars; + return unixstl_C_PathType_InvalidChars; } } @@ -336,7 +336,7 @@ unixstl_C_path_classify_impl_X_( results->firstInvalid.len = 1; results->firstInvalid.ptr = p0; - return UNIXSTL_C_PathType_InvalidSlashRuns; + return unixstl_C_PathType_InvalidSlashRuns; } } diff --git a/include/winstl/filesystem/path.hpp b/include/winstl/filesystem/path.hpp index e670876b..fcce78a5 100644 --- a/include/winstl/filesystem/path.hpp +++ b/include/winstl/filesystem/path.hpp @@ -4,7 +4,7 @@ * Purpose: Simple class that represents a path. * * Created: 1st May 1993 - * Updated: 15th October 2026 + * Updated: 18th October 2026 * * Thanks: Pablo Aguilar for reporting defect in push_ext() (which * doesn't work for wide-string builds). @@ -56,8 +56,8 @@ #ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION # define WINSTL_VER_WINSTL_FILESYSTEM_HPP_PATH_MAJOR 7 # define WINSTL_VER_WINSTL_FILESYSTEM_HPP_PATH_MINOR 1 -# define WINSTL_VER_WINSTL_FILESYSTEM_HPP_PATH_REVISION 11 -# define WINSTL_VER_WINSTL_FILESYSTEM_HPP_PATH_EDIT 330 +# define WINSTL_VER_WINSTL_FILESYSTEM_HPP_PATH_REVISION 12 +# define WINSTL_VER_WINSTL_FILESYSTEM_HPP_PATH_EDIT 331 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -1602,7 +1602,7 @@ basic_path::push_( goto take_rhs; } else - if (WinSTL_C_PathType_DriveLetterRelative == pcls2) + if (winstl_C_PathType_DriveLetterRelative == pcls2) { // 4. if rhs is drive-letter-relative, then take rhs @@ -1610,7 +1610,7 @@ basic_path::push_( } else { - if (WinSTL_C_PathType_DriveLetterRelative == pcls1 && + if (winstl_C_PathType_DriveLetterRelative == pcls1 && 0 == results1.directory.len && 0 == results1.entry.len) { @@ -1967,10 +1967,10 @@ basic_path::make_absolute( switch (pcls) { - case WinSTL_C_PathType_Empty: - case WinSTL_C_PathType_DriveLetterRooted: - case WinSTL_C_PathType_UncRooted: - case WinSTL_C_PathType_HomeRooted: + case winstl_C_PathType_Empty: + case winstl_C_PathType_DriveLetterRooted: + case winstl_C_PathType_UncRooted: + case winstl_C_PathType_HomeRooted: #ifdef STLSOFT_CF_EXCEPTION_SUPPORT @@ -2063,11 +2063,11 @@ basic_path::canonicalise( switch (pcls) { - case WinSTL_C_PathType_InvalidSlashRuns: - case WinSTL_C_PathType_InvalidChars: - case WinSTL_C_PathType_Invalid: - case WinSTL_C_PathType_Unknown: - case WinSTL_C_PathType_Empty: + case winstl_C_PathType_InvalidSlashRuns: + case winstl_C_PathType_InvalidChars: + case winstl_C_PathType_Invalid: + case winstl_C_PathType_Unknown: + case winstl_C_PathType_Empty: #ifdef STLSOFT_CF_EXCEPTION_SUPPORT @@ -2076,13 +2076,13 @@ basic_path::canonicalise( return true; #endif /* STLSOFT_CF_EXCEPTION_SUPPORT */ - case WinSTL_C_PathType_Relative: - case WinSTL_C_PathType_SlashRooted: - case WinSTL_C_PathType_DriveLetterRelative: - case WinSTL_C_PathType_DriveLetterRooted: - case WinSTL_C_PathType_UncIncomplete: - case WinSTL_C_PathType_UncRooted: - case WinSTL_C_PathType_HomeRooted: + case winstl_C_PathType_Relative: + case winstl_C_PathType_SlashRooted: + case winstl_C_PathType_DriveLetterRelative: + case winstl_C_PathType_DriveLetterRooted: + case winstl_C_PathType_UncIncomplete: + case winstl_C_PathType_UncRooted: + case winstl_C_PathType_HomeRooted: default: break; diff --git a/include/winstl/filesystem/path_classify_functions.h b/include/winstl/filesystem/path_classify_functions.h index df5d8fe7..d96a9e2a 100644 --- a/include/winstl/filesystem/path_classify_functions.h +++ b/include/winstl/filesystem/path_classify_functions.h @@ -4,11 +4,11 @@ * Purpose: Path classification functions * * Created: 28th November 2020 - * Updated: 27th December 2024 + * Updated: 18th October 2026 * * Home: http://stlsoft.org/ * - * Copyright (c) 2020-2024, Matthew Wilson and Synesis Information Systems + * Copyright (c) 2020-2026, Matthew Wilson and Synesis Information Systems * All rights reserved. * * Redistribution and use in source and binary forms, with or without @@ -52,8 +52,8 @@ #ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION # define WINSTL_VER_WINSTL_FILESYSTEM_H_PATH_CLASSIFY_FUNCTIONS_MAJOR 1 # define WINSTL_VER_WINSTL_FILESYSTEM_H_PATH_CLASSIFY_FUNCTIONS_MINOR 3 -# define WINSTL_VER_WINSTL_FILESYSTEM_H_PATH_CLASSIFY_FUNCTIONS_REVISION 4 -# define WINSTL_VER_WINSTL_FILESYSTEM_H_PATH_CLASSIFY_FUNCTIONS_EDIT 14 +# define WINSTL_VER_WINSTL_FILESYSTEM_H_PATH_CLASSIFY_FUNCTIONS_REVISION 5 +# define WINSTL_VER_WINSTL_FILESYSTEM_H_PATH_CLASSIFY_FUNCTIONS_EDIT 15 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -93,28 +93,29 @@ enum winstl_C_path_classification_t { - WinSTL_C_PathType_MIN_VALUE = -10000 - - , WinSTL_C_PathType_InvalidSlashRuns = -3 - , WinSTL_C_PathType_InvalidChars = -2 - , WinSTL_C_PathType_Invalid = -1 - , WinSTL_C_PathType_Unknown = 0 - , WinSTL_C_PathType_Empty - , WinSTL_C_PathType_Relative - , WinSTL_C_PathType_SlashRooted - , WinSTL_C_PathType_DriveLetterRelative - , WinSTL_C_PathType_DriveLetterRooted - , WinSTL_C_PathType_UncIncomplete - , WinSTL_C_PathType_UncRooted - , WinSTL_C_PathType_HomeRooted + winstl_C_PathType_MIN_VALUE = -10000 + + , winstl_C_PathType_InvalidSlashRuns = -3 + , winstl_C_PathType_InvalidChars = -2 + , winstl_C_PathType_Invalid = -1 + , winstl_C_PathType_Unknown = 0 + , winstl_C_PathType_Empty + , winstl_C_PathType_Relative + , winstl_C_PathType_SlashRooted + , winstl_C_PathType_DriveLetterRelative + , winstl_C_PathType_DriveLetterRooted + , winstl_C_PathType_UncIncomplete + , winstl_C_PathType_UncRooted + , winstl_C_PathType_HomeRooted /* no enumerator to be placed AFTER this one */ - , WinSTL_C_PathType_MAX_VALUE + , winstl_C_PathType_MAX_VALUE }; #ifndef __cplusplus typedef enum winstl_C_path_classification_t winstl_C_path_classification_t; #endif /* !__cplusplus */ + struct winstl_C_path_classification_results_m_t { stlsoft_C_string_slice_m_t input; @@ -336,10 +337,10 @@ winstl_C_path_is_rooted( { switch (pc) { - case WinSTL_C_PathType_SlashRooted: - case WinSTL_C_PathType_DriveLetterRooted: - case WinSTL_C_PathType_UncRooted: - case WinSTL_C_PathType_HomeRooted: + case winstl_C_PathType_SlashRooted: + case winstl_C_PathType_DriveLetterRooted: + case winstl_C_PathType_UncRooted: + case winstl_C_PathType_HomeRooted: return ws_true_v; default: @@ -356,9 +357,9 @@ winstl_C_path_is_absolute( { switch (pc) { - case WinSTL_C_PathType_DriveLetterRooted: - case WinSTL_C_PathType_UncRooted: - case WinSTL_C_PathType_HomeRooted: + case winstl_C_PathType_DriveLetterRooted: + case winstl_C_PathType_UncRooted: + case winstl_C_PathType_HomeRooted: return ws_true_v; default: @@ -530,6 +531,33 @@ path_is_absolute( #endif /* !WINSTL_NO_NAMESPACE */ +/* ///////////////////////////////////////////////////////////////////////// + * backwards compatibility + * + * Older mixed-case enumerator names are retained (as macros) until at + * least STLSoft 1.13. + */ + +#ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION + +# define WinSTL_C_PathType_DriveLetterRelative winstl_C_PathType_DriveLetterRelative +# define WinSTL_C_PathType_DriveLetterRooted winstl_C_PathType_DriveLetterRooted +# define WinSTL_C_PathType_Empty winstl_C_PathType_Empty +# define WinSTL_C_PathType_HomeRooted winstl_C_PathType_HomeRooted +# define WinSTL_C_PathType_Invalid winstl_C_PathType_Invalid +# define WinSTL_C_PathType_InvalidChars winstl_C_PathType_InvalidChars +# define WinSTL_C_PathType_InvalidSlashRuns winstl_C_PathType_InvalidSlashRuns +# define WinSTL_C_PathType_MAX_VALUE winstl_C_PathType_MAX_VALUE +# define WinSTL_C_PathType_MIN_VALUE winstl_C_PathType_MIN_VALUE +# define WinSTL_C_PathType_Relative winstl_C_PathType_Relative +# define WinSTL_C_PathType_SlashRooted winstl_C_PathType_SlashRooted +# define WinSTL_C_PathType_UncIncomplete winstl_C_PathType_UncIncomplete +# define WinSTL_C_PathType_UncRooted winstl_C_PathType_UncRooted +# define WinSTL_C_PathType_Unknown winstl_C_PathType_Unknown + +#endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ + + /* ///////////////////////////////////////////////////////////////////////// * inclusion control */ diff --git a/include/winstl/filesystem/path_functions/classify_functions_X_.h b/include/winstl/filesystem/path_functions/classify_functions_X_.h index 0d5a87b8..3e5f38b1 100644 --- a/include/winstl/filesystem/path_functions/classify_functions_X_.h +++ b/include/winstl/filesystem/path_functions/classify_functions_X_.h @@ -4,11 +4,11 @@ * Purpose: Path classification functions char-X implementation * * Created: 28th November 2020 - * Updated: 27th December 2024 + * Updated: 18th October 2026 * * Home: http://stlsoft.org/ * - * Copyright (c) 2020-2024, Matthew Wilson and Synesis Information Systems + * Copyright (c) 2020-2026, Matthew Wilson and Synesis Information Systems * All rights reserved. * * Redistribution and use in source and binary forms, with or without @@ -252,7 +252,7 @@ winstl_C_path_classify_root_X_( { /* "/" */ - return WinSTL_C_PathType_SlashRooted; + return winstl_C_PathType_SlashRooted; } if ('~' == s0[0]) @@ -264,7 +264,7 @@ winstl_C_path_classify_root_X_( *ppS1 = s0 + 1; *pCch1 = cch0 - 1; - return WinSTL_C_PathType_HomeRooted; + return winstl_C_PathType_HomeRooted; } else switch (s0[1]) @@ -275,7 +275,7 @@ winstl_C_path_classify_root_X_( *ppS1 = s0 + 1; *pCch1 = cch0 - 1; - return WinSTL_C_PathType_HomeRooted; + return winstl_C_PathType_HomeRooted; } } } @@ -286,7 +286,7 @@ winstl_C_path_classify_root_X_( { /* "\" */ - return WinSTL_C_PathType_SlashRooted; + return winstl_C_PathType_SlashRooted; } else { @@ -341,7 +341,7 @@ winstl_C_path_classify_root_X_( if (0 != winstl_C_path_classify_find_UNC_server_and_share_X_(s0 + 8, cch0 - 8, &server, &share, &dir0)) { - return WinSTL_C_PathType_UncIncomplete; + return winstl_C_PathType_UncIncomplete; } else { @@ -374,7 +374,7 @@ winstl_C_path_classify_root_X_( if (0 != winstl_C_path_classify_find_UNC_server_and_share_X_(s0 + 4, cch0 - 4, &server, &share, &dir0)) { - return WinSTL_C_PathType_Invalid; + return winstl_C_PathType_Invalid; } } #endif @@ -391,7 +391,7 @@ winstl_C_path_classify_root_X_( results->firstInvalid.len = 1; results->firstInvalid.ptr = s0 + 2; - return WinSTL_C_PathType_Invalid; + return winstl_C_PathType_Invalid; } } } @@ -400,7 +400,7 @@ winstl_C_path_classify_root_X_( maybe_regular_UNC: if (0 != winstl_C_path_classify_find_UNC_server_and_share_X_(s0 + 2, cch0 - 2, &server, &share, &dir0)) { - return WinSTL_C_PathType_UncIncomplete; + return winstl_C_PathType_UncIncomplete; } else { @@ -416,22 +416,22 @@ winstl_C_path_classify_root_X_( *ppS1 = dir0; *pCch1 = cch0 - (dir0 - s0); - return WinSTL_C_PathType_UncRooted; + return winstl_C_PathType_UncRooted; } else { - return WinSTL_C_PathType_UncIncomplete; + return winstl_C_PathType_UncIncomplete; } } } else { - return WinSTL_C_PathType_Invalid; + return winstl_C_PathType_Invalid; } } else { - return WinSTL_C_PathType_SlashRooted; + return winstl_C_PathType_SlashRooted; } } } @@ -448,7 +448,7 @@ winstl_C_path_classify_root_X_( *ppS1 = s0 + 2; *pCch1 = cch0 - 2; - return WinSTL_C_PathType_DriveLetterRelative; + return winstl_C_PathType_DriveLetterRelative; } else { @@ -458,7 +458,7 @@ winstl_C_path_classify_root_X_( *ppS1 = s0 + 2; *pCch1 = cch0 - 2; - return WinSTL_C_PathType_DriveLetterRooted; + return winstl_C_PathType_DriveLetterRooted; } else { @@ -474,7 +474,7 @@ winstl_C_path_classify_root_X_( } } - return WinSTL_C_PathType_Relative; + return winstl_C_PathType_Relative; } STLSOFT_INLINE @@ -521,7 +521,7 @@ winstl_C_path_classify_impl_X_( if (0 == cch0) { - return WinSTL_C_PathType_Empty; + return winstl_C_PathType_Empty; } rcRoot = winstl_C_path_classify_root_X_( @@ -537,12 +537,12 @@ winstl_C_path_classify_impl_X_( switch (rcRoot) { - case WinSTL_C_PathType_Relative: - case WinSTL_C_PathType_SlashRooted: - case WinSTL_C_PathType_DriveLetterRelative: - case WinSTL_C_PathType_DriveLetterRooted: - case WinSTL_C_PathType_UncRooted: - case WinSTL_C_PathType_HomeRooted: + case winstl_C_PathType_Relative: + case winstl_C_PathType_SlashRooted: + case winstl_C_PathType_DriveLetterRelative: + case winstl_C_PathType_DriveLetterRooted: + case winstl_C_PathType_UncRooted: + case winstl_C_PathType_HomeRooted: break; default: @@ -559,7 +559,7 @@ winstl_C_path_classify_impl_X_( results->firstInvalid.len = 1; results->firstInvalid.ptr = invalidChar; - return WinSTL_C_PathType_InvalidChars; + return winstl_C_PathType_InvalidChars; } if (ss_nullptr_k != (invalidChar = WINSTL_C_PATH_CLASSIFY_IMPL_stlsoft_C_strnchr_X_(s1, cch1, ':'))) @@ -567,7 +567,7 @@ winstl_C_path_classify_impl_X_( results->firstInvalid.len = 1; results->firstInvalid.ptr = invalidChar; - return WinSTL_C_PathType_InvalidChars; + return winstl_C_PathType_InvalidChars; } } @@ -615,7 +615,7 @@ winstl_C_path_classify_impl_X_( results->firstInvalid.len = 1; results->firstInvalid.ptr = p0; - return WinSTL_C_PathType_InvalidChars; + return winstl_C_PathType_InvalidChars; } /* fall through */ @@ -637,7 +637,7 @@ winstl_C_path_classify_impl_X_( results->firstInvalid.len = 1; results->firstInvalid.ptr = p0; - return WinSTL_C_PathType_InvalidSlashRuns; + return winstl_C_PathType_InvalidSlashRuns; } } @@ -792,7 +792,7 @@ winstl_C_path_classify_root_impl_X_( if (0 == cch0) { - return WinSTL_C_PathType_Empty; + return winstl_C_PathType_Empty; } rcRoot = winstl_C_path_classify_root_X_( @@ -810,18 +810,18 @@ winstl_C_path_classify_root_impl_X_( switch (rcRoot) { - case WinSTL_C_PathType_SlashRooted: - case WinSTL_C_PathType_DriveLetterRooted: - case WinSTL_C_PathType_UncRooted: - case WinSTL_C_PathType_HomeRooted: + case winstl_C_PathType_SlashRooted: + case winstl_C_PathType_DriveLetterRooted: + case winstl_C_PathType_UncRooted: + case winstl_C_PathType_HomeRooted: root->ptr = s0; break; - case WinSTL_C_PathType_DriveLetterRelative: + case winstl_C_PathType_DriveLetterRelative: root->ptr = s0; break; - case WinSTL_C_PathType_UncIncomplete: + case winstl_C_PathType_UncIncomplete: root->len = cch0; root->ptr = s0; From 17df866521963e826b8d545e64fa174862b8b5a7 Mon Sep 17 00:00:00 2001 From: Matt Wilson Date: Sun, 18 Oct 2026 17:24:07 +1100 Subject: [PATCH 6/6] TODO.md --- TODO.md | 25 ++++++++++++++++--------- 1 file changed, 16 insertions(+), 9 deletions(-) diff --git a/TODO.md b/TODO.md index 948cc614..6ee39208 100644 --- a/TODO.md +++ b/TODO.md @@ -101,15 +101,22 @@ Dedicated increment: **test analysis and coverage only** — no other product ch ### 1.11.12 -Normalise C API (and related C-facing) identifier prefixes to the house form **`_C_`** (all-lowercase project key). Survey of **include/** own-prefixes: lowercase already dominates (`comstl`, `mfcstl`, `platformstl`, and the bulk of `stlsoft` / `unixstl` / `winstl`); mixed (`STLSoft_C_`, `WinSTL_C_`) and UPPER (`STLSOFT_C_`, `UNIXSTL_C_`, `WINSTL_C_`) are local exceptions only. No `PlatformSTL_C_` / `UnixSTL_C_` / `ComSTL_C_` forms exist. +Normalise C API (and related C-facing) identifier prefixes. **House rule** +(documented in **c-cpp-standards** → *STLSoft C API identifier prefixes*): -* [ ] Establish and document the rule: new C functions / C-facing enums use lowercase `_C_`; do not introduce `WinSTL_C_`, `STLSoft_C_`, or similar mixed forms; +* **Functions**, **types**, and **enumerators** — lowercase `_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**)~~~ - ✅; -* [ ] Rename path-classify impl macros `WINSTL_C_PATH_CLASSIFY_IMPL_*` / `UNIXSTL_C_PATH_CLASSIFY_IMPL_*` → lowercase `_C_*` forms (retain deprecated older forms until at least **1.13** where applicable); -* [ ] Decide policy for remaining UPPER macro tokens such as `STLSOFT_C_AUTO_BUFFER_*` and `STLSOFT_C_CAST` (keep UPPER as macro convention, or migrate to `stlsoft_C_*`); then apply consistently; -* [ ] **1.13+**: consider removing deprecated mixed-case C API wrappers (`STLSoft_C_*`, `WinSTL_C_*`, and any later-deprecated forms) — not before; +* [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; ## 1.12 @@ -142,10 +149,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);