diff --git a/.vscode/settings.json b/.vscode/settings.json index 6aa78f6c..e30f6b86 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -59,6 +59,9 @@ "C_Cpp.clang_format_style": "file", "C_Cpp.default.cStandard": "c17", "C_Cpp.default.cppStandard": "c++17", + "C_Cpp.default.defines": [ + // "STLSOFT_DOCUMENTATION_SKIP_SECTION", + ], "C_Cpp.enhancedColorization": "enabled", "C_Cpp.errorSquiggles": "enabled", "C_Cpp.formatting": "clangFormat", diff --git a/CHANGES.md b/CHANGES.md index 45a2339e..77f1ad08 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -1,6 +1,37 @@ # STLSoft - CHANGES +## 1.11.1-rc9 - 18th October 2026 + +* additions: + * Added `unixstl::system_traits<>::get_current_process_path()` and `winstl::system_traits<>::get_current_process_path()` (multibyte and wide), obtaining the current process image path with an optional basename path-separator out-parameter; + * Added `T_resizeableBuffer` overloads of `get_current_process_path()` on **unixstl** / **winstl** `system_traits` (query → `stlsoft::resizeable_buffer_resize()` → fill; `ppFile` only after the final fill; resize failure sets `ENOMEM` / `ERROR_OUTOFMEMORY` and leaves the buffer unchanged); + * **unixstl::filesystem_traits** — implemented `find_last_path_name_separator()` / `find_next_path_name_separator()` and `is_path_rooted()` / `is_path_absolute()` / `is_path_UNC()` (NUL-terminated and counted), including Windows drive-letter and UNC classification; + * **unixstl::filesystem_traits** — path-resolve, current-directory, and directory-enumeration members remain declared, pending one conversion policy for that group; + * **unixstl_C_get_home_directory_w()** (**unixstl/system/directory_functions.h**) — reads `HOME` via `getenv()` and converts with `mbstowcs()` (locale multibyte encoding); a short buffer keeps a NUL in the last slot and returns `cchBuffer - 1`, matching the narrow copy; + * **unixstl::system_traits** — implemented `path_str_compare()` and `path_str_n_compare()` (on Windows, case-folded with `towupper()` and treating `/` and `\` as equivalent); + * **unixstl::system_traits** — implemented `get_environment_variable()` (raw and resizeable-buffer) by converting the name with `wcstombs()`, reading it with `getenv()`, and converting the value with `mbstowcs()`; implemented the resizeable-buffer overload of `get_home_directory()`; + * **unixstl::system_traits** — `load_library()` and `free_library()` stay declared together pending one conversion policy (`free_library()` no longer calls `dlclose()` alone); `expand_environment_strings()` remains declared; +* testing: + * Component tests **test/component/unixstl/system/process_paths** (multibyte; multi-OS raw path oracle; resizeable-buffer overloads for `auto_buffer` / `vector`, `ppFile`, and resize-failure) and **test/component/winstl/system/process_paths** (multibyte and wide; `GetModuleFileName` oracle; same resizeable-buffer coverage); + * Unit tests **test.unit.unixstl.filesystem.filesystem_traits** cover wide separator finding and path classification, and agreement with the narrow specialisation; + * Unit tests **test.unit.unixstl.system.system_traits** cover wide `path_str_compare()` and `path_str_n_compare()`; + * Component tests **test.component.unixstl.system.system_traits** cover wide `get_home_directory()` and `get_environment_variable()` (probe, fixed buffer, and `std::vector` resizeable overload) via `platformstl::environment_variable_scope`; + * Resizeable-buffer cases shared with the resizeable-buffer line (`ensure_dir_end()` / `remove_dir_end()`, and the narrow resizeable `get_home_directory()` / `get_environment_variable()` overloads) remain empty pending that merge; + * **test.unit.versions** — aligned with **1.11.1-rc9** (**_STLSOFT_VER_1_11_1_RC9**); +* docs: + * Normalised Doxygen `\pre` comments to bare boolean expressions (no outer parentheses; no trailing `;` / `.`); + * Prefer `nullptr` over `NULL` / prose in `\pre` text; optional-buffer forms use zero-length check first (`0 == n || nullptr != s`); + * Converted expressible prose preconditions (e.g. `!empty()`, `n <= size()`, `nullptr != p`) where applicable; retained soft COM / prior-init / exception-gated contracts as prose; +* version: + * **test.unit.versions** — aligned with **1.11.1-rc9** (**_STLSOFT_VER_1_11_1_RC9**); + * **comstl** — **1.10.4** (**_COMSTL_VER_1_10_4**), with **STLSoft 1.11.1-rc9**; + * **inetstl** — **1.5.0 alpha 4** (**_INETSTL_VER_1_5_0_A04**), with **STLSoft 1.11.1-rc9**; + * **platformstl** — **1.10.0 beta 3** (**_PLATFORMSTL_VER_1_10_0_B03**), with **STLSoft 1.11.1-rc9**; + * **unixstl** — **1.8.6 beta 8** (**_UNIXSTL_VER_1_8_6_B08**), with **STLSoft 1.11.1-rc9**; + * **winstl** — **1.13.0 beta 5** (**_WINSTL_VER_1_13_0_B05**), with **STLSoft 1.11.1-rc9**; + + ## 1.11.1-rc8 - 10th October 2026 * additions: diff --git a/Doxyfile b/Doxyfile index 2b908973..7ba982b9 100644 --- a/Doxyfile +++ b/Doxyfile @@ -2,7 +2,7 @@ PROJECT_NAME = "STLSoft" PROJECT_BRIEF = "Robust, lightweight, cross-platform, template software" -PROJECT_NUMBER = 1.11.1-rc8 +PROJECT_NUMBER = 1.11.1-rc9 # Overridden at generation time by generate_doxygen.sh (respects # SIS_CMAKE_BUILD_DIR). diff --git a/INSTALL.md b/INSTALL.md index 13e5c0ee..7b04011e 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -23,17 +23,17 @@ There are three options for installing **STLSoft**, depending on how you obtain If you obtain the latest release as an archive from the [**STLSoft** GitHub Releases](https://github.com/synesissoftware/STLSoft/releases) page (legacy archives may also still appear on [SourceForge](https://sourceforge.net/projects/stlsoft/)): -1. Download the latest distribution, e.g. [**STLSoft-1.11.1-rc8.zip**](https://github.com/synesissoftware/STLSoft/archive/refs/tags/1.11.1-rc8.zip); +1. Download the latest distribution, e.g. [**STLSoft-1.11.1-rc9.zip**](https://github.com/synesissoftware/STLSoft/archive/refs/tags/1.11.1-rc9.zip); 2. Unzip it to a directory of your choice, as in: ```bash $ mkdir -p ~/open-source $ cd ~/open-source -$ unzip STLSoft-1.11.1-rc8.zip +$ unzip STLSoft-1.11.1-rc9.zip ``` -3. Define an environment variable `STLSOFT`, whose value is the directory in which you unzipped it, e.g. `STLSOFT=~/open-source/STLSoft-1.11.1-rc8`, and then specify `$(STLSOFT)/include` (**UNIX**) or `%STLSOFT%\include` (**Windows**) in your project files and makefiles; +3. Define an environment variable `STLSOFT`, whose value is the directory in which you unzipped it, e.g. `STLSOFT=~/open-source/STLSoft-1.11.1-rc9`, and then specify `$(STLSOFT)/include` (**UNIX**) or `%STLSOFT%\include` (**Windows**) in your project files and makefiles; ### Cloning project, using environment variables @@ -100,16 +100,16 @@ $ sudo cmake --install ${SIS_CMAKE_BUILD_DIR:-./_build} --config Release Unless you are certain that your projects, and all the projects upon which they depend, all use **STLSoft** via **CMake** then it is recommended that you define an `STLSOFT` environment variable. For example, if you're using **UNIX** and you install to -**/usr/local/stlsoft/STLSoft-1.11.1-rc8** +**/usr/local/stlsoft/STLSoft-1.11.1-rc9** then you should set the environment variable `STLSOFT` to -**/usr/local/stlsoft/STLSoft-1.11.1-rc8** -in which case the file `stlsoft/stlsoft.h`, for example, will be located in `/usr/local/stlsoft/STLSoft-1.11.1-rc8/include/stlsoft/stlsoft.h`. +**/usr/local/stlsoft/STLSoft-1.11.1-rc9** +in which case the file `stlsoft/stlsoft.h`, for example, will be located in `/usr/local/stlsoft/STLSoft-1.11.1-rc9/include/stlsoft/stlsoft.h`. Conversely, if you're using **Windows** and you install to -**C:\3pty\STLSoft\STLSoft-1.11.1-rc8** +**C:\3pty\STLSoft\STLSoft-1.11.1-rc9** then you should set the environment variable `STLSOFT` to -**C:\3pty\STLSoft\STLSoft-1.11.1-rc8** -in which case the file `stlsoft/stlsoft.h`, for example, will be located in `C:\3pty\STLSoft\STLSoft-1.11.1-rc8\include\stlsoft\stlsoft.h`. +**C:\3pty\STLSoft\STLSoft-1.11.1-rc9** +in which case the file `stlsoft/stlsoft.h`, for example, will be located in `C:\3pty\STLSoft\STLSoft-1.11.1-rc9\include\stlsoft\stlsoft.h`. The makefiles / project files of several other open-source projects expect this symbol, including: diff --git a/NEWS.md b/NEWS.md index 74839ad5..f4fa50a6 100644 --- a/NEWS.md +++ b/NEWS.md @@ -3,6 +3,7 @@ | Date | News Item | Details | | ------------------- | ----------------------------------- | ------- | +| 18th October 2026 | Release of [STLSoft 1.11.1-rc9](https://github.com/synesissoftware/STLSoft/releases/tag/1.11.1-rc9) | `get_current_process_path()` (+ resizeable-buffer overloads) on **unixstl** / **winstl** `system_traits` with component tests; zero-first optional buffers; **unixstl** `wchar_t` path classification and separators; `path_str_*`; wide `get_home_directory()` and `get_environment_variable()`; `\pre` normalised to bare exprs with `nullptr`; subproject version bumps | | 10th October 2026 | Release of [STLSoft 1.11.1-rc8](https://github.com/synesissoftware/STLSoft/releases/tag/1.11.1-rc8) | environment_variable_strtoll()`; `unixstl::filesystem_traits<>::rewind_dir()`; `class_type` and `getenv_s()` empty-variable fixes; component tests; `cmake --build` helper scripts; **run_all_component_tests.sh** / **run_all_automated_tests.sh**; **generate_doxygen.sh**; Linguist classification | | 30th September 2026 | Release of [STLSoft 1.11.1-rc7](https://github.com/synesissoftware/STLSoft/releases/tag/1.11.1-rc7) | counted NULs; `wchar_t` `string_begins_with`; bit intrinsics; `write_binary()`; `file_lines` mmap (~10–20× vs `fgetc`); compare and allocator units; MinGW static runtime; short test directories; nested **test/performance** | | 21st September 2026 | Release of [STLSoft 1.11.1-rc6](https://github.com/synesissoftware/STLSoft/releases/tag/1.11.1-rc6) | ACE/ATL/MFC CI; Clang/macOS `stricmp` aliases | diff --git a/TODO.md b/TODO.md index fae197b5..e96c4958 100644 --- a/TODO.md +++ b/TODO.md @@ -17,6 +17,8 @@ - [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) - [Abandoned](#abandoned) @@ -34,6 +36,14 @@ * [ ] 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; +* [ ] Being the CONCEPTS documentation: + * [ ] auto-buffer; + * [ ] resizeable-buffer; + * [ ] string-access-shims; + * [ ] Null Object (variable); + * [ ] Externals (esp. not introducing sub-project's headers proper); + * [ ] Conformance: Structural, Semantic, Intersecting; + * [ ] ... ### 1.11.2 @@ -43,6 +53,11 @@ Dedicated increment: **test analysis and coverage only** — no other product ch * [ ] Existing test consistency (deep analysis); * [ ] Complete coverage of currently tested components (improvement / completion); * [ ] 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 @@ -78,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 @@ -96,6 +111,33 @@ 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 `_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). + +* [ ] Cross-publish the completed tip **1.11** tree into **STLSoft-1.11**, including the unknown-newer Visual C++ warn-not-error forward-warning from the **`prospective-msvc`** branch (and any related recognition / semi-freeze messaging needed for historical consumers); + + ## 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). @@ -126,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); diff --git a/include/acestl/reactor/custom_event_handler.hpp b/include/acestl/reactor/custom_event_handler.hpp index 1777f645..5221d793 100644 --- a/include/acestl/reactor/custom_event_handler.hpp +++ b/include/acestl/reactor/custom_event_handler.hpp @@ -4,11 +4,11 @@ * Purpose: Event handler class for custom event notifications. * * Created: 1st October 2004 - * Updated: 21st March 2025 + * Updated: 15th 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) 2004-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -55,7 +55,7 @@ # define ACESTL_VER_ACESTL_REACTOR_HPP_CUSTOM_EVENT_HANDLER_MAJOR 2 # define ACESTL_VER_ACESTL_REACTOR_HPP_CUSTOM_EVENT_HANDLER_MINOR 1 # define ACESTL_VER_ACESTL_REACTOR_HPP_CUSTOM_EVENT_HANDLER_REVISION 13 -# define ACESTL_VER_ACESTL_REACTOR_HPP_CUSTOM_EVENT_HANDLER_EDIT 47 +# define ACESTL_VER_ACESTL_REACTOR_HPP_CUSTOM_EVENT_HANDLER_EDIT 48 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -347,7 +347,7 @@ class custom_event_handler * * \return \c nullptr on failure, the event id on success * - * \remarks The custom event can be cancelled via cancel_custom_event() + * \note The custom event can be cancelled via cancel_custom_event(). * * \note Custom events are "one-shot". When the event delay elapses and the * handle_custom_event() callback is called, the event has been deregistered from @@ -365,7 +365,7 @@ class custom_event_handler * * \return \c nullptr on failure, the event id on success * - * \remarks The custom event can be cancelled via cancel_custom_event() + * \note The custom event can be cancelled via cancel_custom_event(). * * \note Custom events are "one-shot". When the event delay elapses and the * handle_custom_event() callback is called, the event has been deregistered from diff --git a/include/atlstl/automation/multiple_dispatch.hpp b/include/atlstl/automation/multiple_dispatch.hpp index e9a3229d..836a9869 100644 --- a/include/atlstl/automation/multiple_dispatch.hpp +++ b/include/atlstl/automation/multiple_dispatch.hpp @@ -5,11 +5,11 @@ * through multiple IDispatch interfaces visible to script clients. * * Created: 15th May 2006 - * Updated: 20th March 2025 + * Updated: 15th 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) 2007-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -57,7 +57,7 @@ # define ATLSTL_VER_ATLSTL_AUTOMATION_HPP_MULTIPLE_DISPATCH_MAJOR 2 # define ATLSTL_VER_ATLSTL_AUTOMATION_HPP_MULTIPLE_DISPATCH_MINOR 1 # define ATLSTL_VER_ATLSTL_AUTOMATION_HPP_MULTIPLE_DISPATCH_REVISION 5 -# define ATLSTL_VER_ATLSTL_AUTOMATION_HPP_MULTIPLE_DISPATCH_EDIT 30 +# define ATLSTL_VER_ATLSTL_AUTOMATION_HPP_MULTIPLE_DISPATCH_EDIT 31 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -214,7 +214,7 @@ class IDispatchImpl2 * which has thus undertaken to interpret them. This stripe is then * detected * - * \remarks Names are matched en bloc: they are either all matched by one + * \note Names are matched en bloc: they are either all matched by one * interface, or all by the other. It is never the case that * some part are matched by one and the remainder by the other. * @@ -274,7 +274,7 @@ class IDispatchImpl2 * from which the appropriate dispiniterface is determined. The * stripe is then removed, and the method invoked. * - * \remarks Names are matched en bloc: they are either all matched by one + * \note Names are matched en bloc: they are either all matched by one * interface, or all by the other. It is never the case that * some part are matched by one and the remainder by the other. * @@ -365,7 +365,7 @@ class IDispatchImpl3 * which has thus undertaken to interpret them. This stripe is then * detected * - * \remarks Names are matched en bloc: they are either all matched by one + * \note Names are matched en bloc: they are either all matched by one * interface, or all by the other. It is never the case that * some part are matched by one and the remainder by the other. * @@ -433,7 +433,7 @@ class IDispatchImpl3 * from which the appropriate dispiniterface is determined. The * stripe is then removed, and the method invoked. * - * \remarks Names are matched en bloc: they are either all matched by one + * \note Names are matched en bloc: they are either all matched by one * interface, or all by the other. It is never the case that * some part are matched by one and the remainder by the other. * @@ -540,7 +540,7 @@ class IDispatchImpl4 * which has thus undertaken to interpret them. This stripe is then * detected * - * \remarks Names are matched en bloc: they are either all matched by one + * \note Names are matched en bloc: they are either all matched by one * interface, or all by the other. It is never the case that * some part are matched by one and the remainder by the other. * @@ -616,7 +616,7 @@ class IDispatchImpl4 * from which the appropriate dispiniterface is determined. The * stripe is then removed, and the method invoked. * - * \remarks Names are matched en bloc: they are either all matched by one + * \note Names are matched en bloc: they are either all matched by one * interface, or all by the other. It is never the case that * some part are matched by one and the remainder by the other. * diff --git a/include/comstl/collections/collection_sequence.hpp b/include/comstl/collections/collection_sequence.hpp index 93b6dfeb..973b38fd 100644 --- a/include/comstl/collections/collection_sequence.hpp +++ b/include/comstl/collections/collection_sequence.hpp @@ -4,7 +4,7 @@ * Purpose: STL sequence for COM collection interfaces. * * Created: 17th September 1998 - * Updated: 20th March 2025 + * Updated: 15th October 2026 * * Thanks: To Eduardo Bezerra and Vivi Orunitia for reporting * incompatibilities with Borland's 5.82 (Turbo C++). The awful @@ -12,7 +12,7 @@ * * 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) 1998-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -59,7 +59,7 @@ # define COMSTL_VER_COMSTL_COLLECTIONS_HPP_COLLECTION_SEQUENCE_MAJOR 6 # define COMSTL_VER_COMSTL_COLLECTIONS_HPP_COLLECTION_SEQUENCE_MINOR 1 # define COMSTL_VER_COMSTL_COLLECTIONS_HPP_COLLECTION_SEQUENCE_REVISION 19 -# define COMSTL_VER_COMSTL_COLLECTIONS_HPP_COLLECTION_SEQUENCE_EDIT 126 +# define COMSTL_VER_COMSTL_COLLECTIONS_HPP_COLLECTION_SEQUENCE_EDIT 127 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -185,7 +185,7 @@ typedef collection_sequence< * \note The iterator instances returned by begin() and end() are valid outside * the lifetime of the collection instance from which they are obtained * - * \remarks A detailed examination of the design and implementation of this + * \note A detailed examination of the design and implementation of this * class template is described in Chapters 28 and 29 of * Extended STL, volume 1 * (published by Addison-Wesley, June 2007). diff --git a/include/comstl/collections/enumeration_policies.hpp b/include/comstl/collections/enumeration_policies.hpp index b123d09d..6c1ad92d 100644 --- a/include/comstl/collections/enumeration_policies.hpp +++ b/include/comstl/collections/enumeration_policies.hpp @@ -4,11 +4,11 @@ * Purpose: Policies for enumerator interface handling. * * Created: 20th December 2003 - * Updated: 21st March 2025 + * Updated: 15th 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) 2003-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -54,7 +54,7 @@ # define COMSTL_VER_COMSTL_COLLECTIONS_HPP_ENUMERATION_POLICIES_MAJOR 6 # define COMSTL_VER_COMSTL_COLLECTIONS_HPP_ENUMERATION_POLICIES_MINOR 1 # define COMSTL_VER_COMSTL_COLLECTIONS_HPP_ENUMERATION_POLICIES_REVISION 16 -# define COMSTL_VER_COMSTL_COLLECTIONS_HPP_ENUMERATION_POLICIES_EDIT 76 +# define COMSTL_VER_COMSTL_COLLECTIONS_HPP_ENUMERATION_POLICIES_EDIT 77 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -205,7 +205,7 @@ struct input_cloning_policy public: /// Gets a working "copy" of the given enumerator root /// - /// \remarks For this policy, this simply calls AddRef() + /// \note For this policy, this simply calls AddRef(). static interface_type *get_working_instance(interface_type *root) { COMSTL_ASSERT(NULL != root); @@ -254,7 +254,7 @@ struct cloneable_cloning_policy public: /// Gets a working "copy" of the given enumerator root /// - /// \remarks For this policy, this calls Clone(), and returns \c nullptr + /// \note For this policy, this calls Clone(), and returns \c nullptr /// if that fails. static interface_type *get_working_instance(interface_type *root) { @@ -324,7 +324,7 @@ struct forward_cloning_policy public: /// Gets a working "copy" of the given enumerator root /// - /// \remarks For this policy, this calls Clone(), and throws an + /// \note For this policy, this calls Clone(), and throws an /// instance of comstl::clone_failure if that fails (or returns /// \c nullptr if exception support is disabled). static interface_type *get_working_instance(interface_type *root) @@ -443,7 +443,7 @@ struct policy_adaptor * * \ingroup group__library__Collection * - * \remarks Invokes the the get__NewEnum() method + * \note Invokes the the get__NewEnum() method. */ template struct new_enum_property_policy @@ -475,7 +475,7 @@ struct new_enum_property_policy * * \ingroup group__library__Collection * - * \remarks Invokes the the _NewEnum() method + * \note Invokes the the _NewEnum() method. */ template struct new_enum_method_policy @@ -497,7 +497,7 @@ struct new_enum_method_policy * * \ingroup group__library__Collection * - * \remarks Calls IDispatch::Invoke(DISPID_NEWENUM, . . . , DISPATCH_METHOD | DISPATCH_PROPERTYGET, . . . ); + * \note Calls IDispatch::Invoke(DISPID_NEWENUM, . . . , DISPATCH_METHOD | DISPATCH_PROPERTYGET, . . . ); */ template struct new_enum_by_dispid_policy diff --git a/include/comstl/collections/enumerator_sequence.hpp b/include/comstl/collections/enumerator_sequence.hpp index fa223b91..956efee0 100644 --- a/include/comstl/collections/enumerator_sequence.hpp +++ b/include/comstl/collections/enumerator_sequence.hpp @@ -4,7 +4,7 @@ * Purpose: STL sequence for IEnumXXXX enumerator interfaces. * * Created: 17th September 1998 - * Updated: 20th March 2025 + * Updated: 15th October 2026 * * Thanks: To Eduardo Bezerra and Vivi Orunitia for reporting * incompatibilities with Borland's 5.82 (Turbo C++). The awful @@ -12,7 +12,7 @@ * * 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) 1998-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -59,7 +59,7 @@ # define COMSTL_VER_COMSTL_COLLECTIONS_HPP_ENUMERATOR_SEQUENCE_MAJOR 6 # define COMSTL_VER_COMSTL_COLLECTIONS_HPP_ENUMERATOR_SEQUENCE_MINOR 1 # define COMSTL_VER_COMSTL_COLLECTIONS_HPP_ENUMERATOR_SEQUENCE_REVISION 15 -# define COMSTL_VER_COMSTL_COLLECTIONS_HPP_ENUMERATOR_SEQUENCE_EDIT 280 +# define COMSTL_VER_COMSTL_COLLECTIONS_HPP_ENUMERATOR_SEQUENCE_EDIT 281 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -186,7 +186,7 @@ std::for_each(guids.begin(), guids.end(), dump_GUID); * \note The iterator instances returned by begin() and end() are valid outside * the lifetime of the collection instance from which they are obtained * - * \remarks A detailed examination of the design and implementation of this + * \note A detailed examination of the design and implementation of this * class template is described in Chapters 28 and 29 of * Extended STL, volume 1 * (published by Addison-Wesley, June 2007). diff --git a/include/comstl/comstl.h b/include/comstl/comstl.h index 39af63a0..fd86bbdc 100644 --- a/include/comstl/comstl.h +++ b/include/comstl/comstl.h @@ -5,7 +5,7 @@ * platform discriminations, and definitions of types. * * Created: 15th January 2002 - * Updated: 17th September 2026 + * Updated: 17th October 2026 * * Home: http://stlsoft.org/ * @@ -56,7 +56,7 @@ # define COMSTL_VER_COMSTL_H_COMSTL_MAJOR 3 # define COMSTL_VER_COMSTL_H_COMSTL_MINOR 9 # define COMSTL_VER_COMSTL_H_COMSTL_REVISION 10 -# define COMSTL_VER_COMSTL_H_COMSTL_EDIT 134 +# define COMSTL_VER_COMSTL_H_COMSTL_EDIT 135 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ /** \file comstl/comstl.h @@ -170,11 +170,12 @@ # define _COMSTL_VER_1_10_1 0x010a01ff /*!< Version 1.10.1 (with STLSoft 1.10.3) */ # define _COMSTL_VER_1_10_2 0x010a02ff /*!< Version 1.10.2 (with STLSoft 1.11.1 alpha 8) */ # define _COMSTL_VER_1_10_3 0x010a03ff /*!< Version 1.10.3 (with STLSoft 1.11.1 alpha 17) */ +# define _COMSTL_VER_1_10_4 0x010a04ff /*!< Version 1.10.4 (with STLSoft 1.11.1 rc 9) */ #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ #define _COMSTL_VER_MAJOR 1 #define _COMSTL_VER_MINOR 10 -#define _COMSTL_VER_PATCH 3 +#define _COMSTL_VER_PATCH 4 #define _COMSTL_VER_ALPHABETA 0xFF #define _COMSTL_VER \ diff --git a/include/comstl/exception/variant_type_exception.hpp b/include/comstl/exception/variant_type_exception.hpp index b306ea41..3d5391b9 100644 --- a/include/comstl/exception/variant_type_exception.hpp +++ b/include/comstl/exception/variant_type_exception.hpp @@ -4,11 +4,11 @@ * Purpose: COM-related exception classes, and their policy classes * * Created: 8th December 2004 - * Updated: 20th March 2025 + * Updated: 15th 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) 2004-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -55,7 +55,7 @@ # define COMSTL_VER_COMSTL_EXCEPTION_HPP_VARIANT_TYPE_EXCEPTION_MAJOR 3 # define COMSTL_VER_COMSTL_EXCEPTION_HPP_VARIANT_TYPE_EXCEPTION_MINOR 0 # define COMSTL_VER_COMSTL_EXCEPTION_HPP_VARIANT_TYPE_EXCEPTION_REVISION 5 -# define COMSTL_VER_COMSTL_EXCEPTION_HPP_VARIANT_TYPE_EXCEPTION_EDIT 61 +# define COMSTL_VER_COMSTL_EXCEPTION_HPP_VARIANT_TYPE_EXCEPTION_EDIT 62 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -103,7 +103,7 @@ namespace comstl_project * * \ingroup group__library__Exception * - * \remarks This is thrown by comstl::safearray_sequence on variant type + * \note This is thrown by comstl::safearray_sequence on variant type * mismatches. */ class variant_type_exception diff --git a/include/comstl/util/CY_functions.h b/include/comstl/util/CY_functions.h index 3f3a1e67..b8dff623 100644 --- a/include/comstl/util/CY_functions.h +++ b/include/comstl/util/CY_functions.h @@ -4,11 +4,11 @@ * Purpose: CY helper functions. * * Created: 23rd August 2008 - * Updated: 24th December 2024 + * Updated: 11th 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) 2008-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -54,7 +54,7 @@ # define COMSTL_VER_COMSTL_UTIL_H_CY_FUNCTIONS_MAJOR 1 # define COMSTL_VER_COMSTL_UTIL_H_CY_FUNCTIONS_MINOR 1 # define COMSTL_VER_COMSTL_UTIL_H_CY_FUNCTIONS_REVISION 2 -# define COMSTL_VER_COMSTL_UTIL_H_CY_FUNCTIONS_EDIT 18 +# define COMSTL_VER_COMSTL_UTIL_H_CY_FUNCTIONS_EDIT 19 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -101,8 +101,8 @@ namespace comstl_project * \param lhs Pointer to the left-hand instances to compare * \param rhs Pointer to the right-hand instances to compare * - * \pre \c lhs must not be \c nullptr. - * \pre \c rhs must not be \c nullptr. + * \pre nullptr != lhs + * \pre nullptr != rhs */ STLSOFT_INLINE int @@ -181,8 +181,8 @@ namespace comstl * \param lhs Pointer to the left-hand instances to compare * \param rhs Pointer to the right-hand instances to compare * - * \pre \c lhs must not be \c nullptr. - * \pre \c rhs must not be \c nullptr. + * \pre nullptr != lhs + * \pre nullptr != rhs */ inline int diff --git a/include/comstl/util/DECIMAL_functions.h b/include/comstl/util/DECIMAL_functions.h index e8780276..982a658c 100644 --- a/include/comstl/util/DECIMAL_functions.h +++ b/include/comstl/util/DECIMAL_functions.h @@ -4,11 +4,11 @@ * Purpose: DECIMAL helper functions. * * Created: 23rd August 2008 - * Updated: 24th December 2024 + * Updated: 11th 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) 2008-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -54,7 +54,7 @@ # define COMSTL_VER_COMSTL_UTIL_H_DECIMAL_FUNCTIONS_MAJOR 1 # define COMSTL_VER_COMSTL_UTIL_H_DECIMAL_FUNCTIONS_MINOR 0 # define COMSTL_VER_COMSTL_UTIL_H_DECIMAL_FUNCTIONS_REVISION 7 -# define COMSTL_VER_COMSTL_UTIL_H_DECIMAL_FUNCTIONS_EDIT 19 +# define COMSTL_VER_COMSTL_UTIL_H_DECIMAL_FUNCTIONS_EDIT 20 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -110,8 +110,8 @@ namespace comstl_project * \param lhs Pointer to the left-hand instances to compare * \param rhs Pointer to the right-hand instances to compare * - * \pre \c lhs must not be \c nullptr. - * \pre \c rhs must not be \c nullptr. + * \pre nullptr != lhs + * \pre nullptr != rhs */ STLSOFT_INLINE int @@ -265,8 +265,8 @@ namespace comstl * \param lhs Pointer to the left-hand instances to compare * \param rhs Pointer to the right-hand instances to compare * - * \pre \c lhs must not be \c nullptr. - * \pre \c rhs must not be \c nullptr. + * \pre nullptr != lhs + * \pre nullptr != rhs */ inline int diff --git a/include/comstl/util/VARIANT_functions.h b/include/comstl/util/VARIANT_functions.h index a0432d2b..28b146ca 100644 --- a/include/comstl/util/VARIANT_functions.h +++ b/include/comstl/util/VARIANT_functions.h @@ -4,11 +4,11 @@ * Purpose: VARIANT helper functions. * * Created: 23rd August 2008 - * Updated: 24th December 2024 + * Updated: 11th 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) 2008-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -54,7 +54,7 @@ # define COMSTL_VER_COMSTL_UTIL_H_VARIANT_FUNCTIONS_MAJOR 1 # define COMSTL_VER_COMSTL_UTIL_H_VARIANT_FUNCTIONS_MINOR 2 # define COMSTL_VER_COMSTL_UTIL_H_VARIANT_FUNCTIONS_REVISION 2 -# define COMSTL_VER_COMSTL_UTIL_H_VARIANT_FUNCTIONS_EDIT 22 +# define COMSTL_VER_COMSTL_UTIL_H_VARIANT_FUNCTIONS_EDIT 23 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -121,8 +121,8 @@ namespace comstl_project * \retval 0 The structures are not equal * \retval >0 The structures are equal * - * \pre \c lhs must not be \c nullptr. - * \pre \c rhs must not be \c nullptr. + * \pre nullptr != lhs + * \pre nullptr != rhs */ STLSOFT_INLINE int @@ -291,8 +291,8 @@ namespace comstl * \retval 0 The structures are not equal * \retval >0 The structures are equal * - * \pre \c lhs must not be \c nullptr. - * \pre \c rhs must not be \c nullptr. + * \pre nullptr != lhs + * \pre nullptr != rhs */ inline bool diff --git a/include/comstl/util/object_functions.h b/include/comstl/util/object_functions.h index b05e2c49..be3b045f 100644 --- a/include/comstl/util/object_functions.h +++ b/include/comstl/util/object_functions.h @@ -4,11 +4,11 @@ * Purpose: Reference-counting helper functions. * * Created: 2nd March 1996 - * Updated: 24th December 2024 + * Updated: 15th 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) 1996-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -54,7 +54,7 @@ # define COMSTL_VER_COMSTL_UTIL_H_OBJECT_FUNCTIONS_MAJOR 3 # define COMSTL_VER_COMSTL_UTIL_H_OBJECT_FUNCTIONS_MINOR 2 # define COMSTL_VER_COMSTL_UTIL_H_OBJECT_FUNCTIONS_REVISION 1 -# define COMSTL_VER_COMSTL_UTIL_H_OBJECT_FUNCTIONS_EDIT 81 +# define COMSTL_VER_COMSTL_UTIL_H_OBJECT_FUNCTIONS_EDIT 82 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -106,9 +106,9 @@ namespace comstl_project * \retval any-other-code Indicates an error from the call to * QueryInterface() * - * \pre \c p is a \c nullptr pointer, or a valid pointer to a COM interface. + * \pre p is nullptr, or a valid pointer to a COM interface * - * \remarks If the function success, the caller must release the reference + * \note If the function success, the caller must release the reference * count associated with the interface pointer in \c *identity. * * \note Intended for use in C-compilation units only. For C++, use @@ -149,8 +149,8 @@ comstl_C_get_object_identity( * \retval any-other-code Indicates an error from one of the calls to * QueryInterface() * - * \pre \c p1 and \c p2 are \c nullptr pointers, or are valid pointers to - * COM interfaces. + * \pre p1 is nullptr, or a valid pointer to a COM interface + * \pre p2 is nullptr, or a valid pointer to a COM interface */ STLSOFT_INLINE HRESULT @@ -210,7 +210,7 @@ comstl_C_is_same_object( * \retval any-other-code Indicates an error from the call to * QueryInterface() * - * \pre \c p is a non-\c nullptr pointer to a COM interface. + * \pre nullptr != p */ STLSOFT_INLINE HRESULT @@ -304,9 +304,9 @@ namespace comstl * \retval any-other-code Indicates an error from the call to * QueryInterface() * - * \pre \c p is a \c nullptr pointer, or a valid pointer to a COM interface. + * \pre p is nullptr, or a valid pointer to a COM interface * - * \remarks If the function success, the caller must release the reference + * \note If the function success, the caller must release the reference * count associated with the interface pointer in \c *identity. * * \note Implemented in terms of the C-compatible function @@ -332,8 +332,8 @@ get_object_identity( * \retval any-other-code Indicates an error from one of the calls to * QueryInterface() * - * \pre \c p1 and \c p2 are \c nullptr pointers, or are valid pointers to - * COM interfaces. + * \pre p1 is nullptr, or a valid pointer to a COM interface + * \pre p2 is nullptr, or a valid pointer to a COM interface */ inline HRESULT @@ -355,7 +355,7 @@ is_same_object( * \retval any-other-code Indicates an error from the call to * QueryInterface() * - * \pre \c p is a non-\c nullptr pointer to a COM interface. + * \pre nullptr != p */ inline HRESULT diff --git a/include/comstl/util/refcount_functions.h b/include/comstl/util/refcount_functions.h index 59a6e46d..42564831 100644 --- a/include/comstl/util/refcount_functions.h +++ b/include/comstl/util/refcount_functions.h @@ -4,11 +4,11 @@ * Purpose: Reference-counting helper functions. * * Created: 25th June 2002 - * Updated: 24th December 2024 + * Updated: 11th 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) 2002-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -54,7 +54,7 @@ # define COMSTL_VER_COMSTL_UTIL_H_REFCOUNT_FUNCTIONS_MAJOR 4 # define COMSTL_VER_COMSTL_UTIL_H_REFCOUNT_FUNCTIONS_MINOR 1 # define COMSTL_VER_COMSTL_UTIL_H_REFCOUNT_FUNCTIONS_REVISION 6 -# define COMSTL_VER_COMSTL_UTIL_H_REFCOUNT_FUNCTIONS_EDIT 74 +# define COMSTL_VER_COMSTL_UTIL_H_REFCOUNT_FUNCTIONS_EDIT 75 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -100,7 +100,7 @@ namespace comstl_project * * \param punk The interface pointer on which to add the reference. Cannot be null * - * \pre \c punk must not be \c nullptr. + * \pre nullptr != punk */ STLSOFT_INLINE void @@ -179,7 +179,7 @@ namespace comstl * * \param punk The interface pointer on which to add the reference. Cannot be null * - * \pre \c punk must not be \c nullptr. + * \pre nullptr != punk */ inline void diff --git a/include/comstl/util/variant.hpp b/include/comstl/util/variant.hpp index 58b576da..99a4e8a8 100644 --- a/include/comstl/util/variant.hpp +++ b/include/comstl/util/variant.hpp @@ -4,11 +4,11 @@ * Purpose: variant class. * * Created: 12th December 1996 - * Updated: 20th March 2025 + * Updated: 15th 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) 1996-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -54,7 +54,7 @@ # define _COMSTL_VER_COMSTL_UTIL_HPP_COMSTL_VARIANT_MAJOR 2 # define _COMSTL_VER_COMSTL_UTIL_HPP_COMSTL_VARIANT_MINOR 3 # define _COMSTL_VER_COMSTL_UTIL_HPP_COMSTL_VARIANT_REVISION 15 -# define _COMSTL_VER_COMSTL_UTIL_HPP_COMSTL_VARIANT_EDIT 180 +# define _COMSTL_VER_COMSTL_UTIL_HPP_COMSTL_VARIANT_EDIT 181 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -127,7 +127,7 @@ namespace comstl_project * * \ingroup group__library__COM_Utility * - * \remarks comstl::variant publicly derives from \c VARIANT as a measure of + * \note comstl::variant publicly derives from \c VARIANT as a measure of * expedience, rather than as an act of design sophistication. Any manual * manipulation of the instances, or their member variables, is at the * user's risk. Notwithstanding, this is helped by the fact that @@ -422,7 +422,7 @@ class variant * \retval E_INTERFACE The interface is not supported: the * value of *ppv is undefined. * - * \pre nullptr != ppv + * \pre nullptr != ppv */ HRESULT QueryInterface(REFIID riid, void** ppv) const; @@ -436,7 +436,7 @@ class variant * \retval E_INTERFACE The interface is not supported: the * value of *ppi is undefined. * - * \pre nullptr != ppi + * \pre nullptr != ppi */ template HRESULT QueryInterfaceValue(I** ppi) diff --git a/include/inetstl/inetstl.h b/include/inetstl/inetstl.h index aca3309d..7aafdef8 100644 --- a/include/inetstl/inetstl.h +++ b/include/inetstl/inetstl.h @@ -5,7 +5,7 @@ * platform discriminations, and definitions of types. * * Created: 24th April 2004 - * Updated: 8th October 2026 + * Updated: 17th October 2026 * * Home: http://stlsoft.org/ * @@ -51,7 +51,7 @@ # define INETSTL_VER_INETSTL_H_INETSTL_MAJOR 3 # define INETSTL_VER_INETSTL_H_INETSTL_MINOR 11 # define INETSTL_VER_INETSTL_H_INETSTL_REVISION 4 -# define INETSTL_VER_INETSTL_H_INETSTL_EDIT 579 +# define INETSTL_VER_INETSTL_H_INETSTL_EDIT 580 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ /** \file inetstl/inetstl.h @@ -146,12 +146,13 @@ # define _INETSTL_VER_1_5_0_A01 0x01050041 /*!< Version 1.5.0 alpha 1 (with STLSoft 1.11.1 beta 2) */ # define _INETSTL_VER_1_5_0_A02 0x01050042 /*!< Version 1.5.0 alpha 2 (with STLSoft 1.11.1 rc 2) */ # define _INETSTL_VER_1_5_0_A03 0x01050043 /*!< Version 1.5.0 alpha 3 (with STLSoft 1.11.1 rc 8) */ +# define _INETSTL_VER_1_5_0_A04 0x01050044 /*!< Version 1.5.0 alpha 4 (with STLSoft 1.11.1 rc 9) */ #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ #define _INETSTL_VER_MAJOR 1 #define _INETSTL_VER_MINOR 5 #define _INETSTL_VER_PATCH 0 -#define _INETSTL_VER_ALPHABETA 0x43 +#define _INETSTL_VER_ALPHABETA 0x44 #define _INETSTL_VER \ (0\ @@ -195,8 +196,8 @@ * STLSoft version compatibility check(s) */ -#if _STLSOFT_VER < 0x010B01C8 -# error This version of the InetSTL libraries requires STLSoft version 1.11.1 rc 8, or later +#if _STLSOFT_VER < 0x010B01C9 +# error This version of the InetSTL libraries requires STLSoft version 1.11.1 rc 9, or later #endif /* _STLSOFT_VER */ diff --git a/include/inetstl/util/uds_helpers.h b/include/inetstl/util/uds_helpers.h index e12a5b1f..beeacd87 100644 --- a/include/inetstl/util/uds_helpers.h +++ b/include/inetstl/util/uds_helpers.h @@ -4,7 +4,7 @@ * Purpose: Unix Domain Sockets helper functions * * Created: 21st February 2025 - * Updated: 29th May 2025 + * Updated: 15th October 2026 * * Home: http://stlsoft.org/ * @@ -53,7 +53,7 @@ # define INETSTL_VER_INETSTL_UTIL_H_UDS_HELPERS_MAJOR 1 # define INETSTL_VER_INETSTL_UTIL_H_UDS_HELPERS_MINOR 0 # define INETSTL_VER_INETSTL_UTIL_H_UDS_HELPERS_REVISION 2 -# define INETSTL_VER_INETSTL_UTIL_H_UDS_HELPERS_EDIT 4 +# define INETSTL_VER_INETSTL_UTIL_H_UDS_HELPERS_EDIT 5 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -159,7 +159,7 @@ inetstl_c_sockaddr_un_init_from_path( * - on macOS, `sockaddr_un` has field `sun_len`, which is not * present on Linux; * - the field `sun_path` has a fixed size (of 104, or 108, or ...), - * and there are some differences in whether a NUL-terminator is + * and there are some differences in whether a NUL character is * required, hence if the path length is exactly the same as the * available fixed space then there is an issue; * diff --git a/include/mfcstl/shims/attribute/get_kernel_handle.hpp b/include/mfcstl/shims/attribute/get_kernel_handle.hpp index f030aada..5a924bb2 100644 --- a/include/mfcstl/shims/attribute/get_kernel_handle.hpp +++ b/include/mfcstl/shims/attribute/get_kernel_handle.hpp @@ -4,11 +4,11 @@ * Purpose: Contains classes and functions for dealing with Win32 handles. * * Created: 24th December 2006 - * Updated: 20th March 2025 + * Updated: 15th 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) 2006-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -55,7 +55,7 @@ # define MFCSTL_VER_MFCSTL_SHIMS_ATTRIBUTE_HPP_GET_KERNEL_HANDLE_MAJOR 1 # define MFCSTL_VER_MFCSTL_SHIMS_ATTRIBUTE_HPP_GET_KERNEL_HANDLE_MINOR 1 # define MFCSTL_VER_MFCSTL_SHIMS_ATTRIBUTE_HPP_GET_KERNEL_HANDLE_REVISION 7 -# define MFCSTL_VER_MFCSTL_SHIMS_ATTRIBUTE_HPP_GET_KERNEL_HANDLE_EDIT 25 +# define MFCSTL_VER_MFCSTL_SHIMS_ATTRIBUTE_HPP_GET_KERNEL_HANDLE_EDIT 26 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -112,11 +112,6 @@ namespace winstl_project * \param ev The event instance * * \retval The handle \c h - * - * \remarks We cannot simply define the shim overload in terms of - * CEvent for two reasons. First, the template - * mechanism requires a precise shim when the - * */ inline HANDLE get_kernel_handle(CEvent &ev) { @@ -131,11 +126,6 @@ inline HANDLE get_kernel_handle(CEvent &ev) * \param mx The mutex instance * * \retval The handle \c h - * - * \remarks We cannot simply define the shim overload in terms of - * CMutex for two reasons. First, the template - * mechanism requires a precise shim when the - * */ inline HANDLE get_kernel_handle(CMutex &mx) { @@ -150,11 +140,6 @@ inline HANDLE get_kernel_handle(CMutex &mx) * \param sem The semaphore instance * * \retval The handle \c h - * - * \remarks We cannot simply define the shim overload in terms of - * CSemaphore for two reasons. First, the template - * mechanism requires a precise shim when the - * */ inline HANDLE get_kernel_handle(CSemaphore &sem) { diff --git a/include/mfcstl/shims/attribute/get_synch_handle.hpp b/include/mfcstl/shims/attribute/get_synch_handle.hpp index 174b0822..1f7bfe1a 100644 --- a/include/mfcstl/shims/attribute/get_synch_handle.hpp +++ b/include/mfcstl/shims/attribute/get_synch_handle.hpp @@ -4,11 +4,11 @@ * Purpose: Contains classes and functions for dealing with Win32 handles. * * Created: 24th December 2006 - * Updated: 20th March 2025 + * Updated: 15th 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) 2006-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -55,7 +55,7 @@ # define MFCSTL_VER_MFCSTL_SHIMS_ATTRIBUTE_HPP_GET_SYNCH_HANDLE_MAJOR 1 # define MFCSTL_VER_MFCSTL_SHIMS_ATTRIBUTE_HPP_GET_SYNCH_HANDLE_MINOR 2 # define MFCSTL_VER_MFCSTL_SHIMS_ATTRIBUTE_HPP_GET_SYNCH_HANDLE_REVISION 4 -# define MFCSTL_VER_MFCSTL_SHIMS_ATTRIBUTE_HPP_GET_SYNCH_HANDLE_EDIT 22 +# define MFCSTL_VER_MFCSTL_SHIMS_ATTRIBUTE_HPP_GET_SYNCH_HANDLE_EDIT 23 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -120,7 +120,7 @@ namespace winstl_project * * \retval The synchronisation handle associated with the event * - * \remarks We cannot simply define the shim overload in terms of + * \note We cannot simply define the shim overload in terms of * CSyncObject for two reasons. First, the template * mechanism requires a precise type for the shim, not an * inheritance-related group of types. Second, the class @@ -147,7 +147,7 @@ get_synch_handle( * * \retval The synchronisation handle associated with the mutex * - * \remarks We cannot simply define the shim overload in terms of + * \note We cannot simply define the shim overload in terms of * CSyncObject for two reasons. First, the template * mechanism requires a precise type for the shim, not an * inheritance-related group of types. Second, the class @@ -174,7 +174,7 @@ get_synch_handle( * * \retval The synchronisation handle associated with the semaphore * - * \remarks We cannot simply define the shim overload in terms of + * \note We cannot simply define the shim overload in terms of * CSyncObject for two reasons. First, the template * mechanism requires a precise type for the shim, not an * inheritance-related group of types. Second, the class diff --git a/include/platformstl/filesystem/cwd_stack.hpp b/include/platformstl/filesystem/cwd_stack.hpp index bfd4c249..e51c8fd3 100644 --- a/include/platformstl/filesystem/cwd_stack.hpp +++ b/include/platformstl/filesystem/cwd_stack.hpp @@ -4,11 +4,11 @@ * Purpose: Platform header for the filesystem_traits components. * * Created: 16th July 2006 - * Updated: 20th March 2025 + * Updated: 15th 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) 2006-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -56,7 +56,7 @@ # define PLATFORMSTL_VER_PLATFORMSTL_FILESYSTEM_HPP_CWD_STACK_MAJOR 2 # define PLATFORMSTL_VER_PLATFORMSTL_FILESYSTEM_HPP_CWD_STACK_MINOR 2 # define PLATFORMSTL_VER_PLATFORMSTL_FILESYSTEM_HPP_CWD_STACK_REVISION 1 -# define PLATFORMSTL_VER_PLATFORMSTL_FILESYSTEM_HPP_CWD_STACK_EDIT 42 +# define PLATFORMSTL_VER_PLATFORMSTL_FILESYSTEM_HPP_CWD_STACK_EDIT 43 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -147,7 +147,8 @@ class basic_cwd_stack /// /// - /// \remarks If fails, then platformstl::system_traits::get_last_error() gives the error + /// \note If fails, then platformstl::system_traits::get_last_error() + /// gives the error. bool_type try_pop(); public: diff --git a/include/platformstl/platformstl.h b/include/platformstl/platformstl.h index d2862a2d..f58926ea 100644 --- a/include/platformstl/platformstl.h +++ b/include/platformstl/platformstl.h @@ -5,7 +5,7 @@ * platform discriminations, and definitions of types. * * Created: 20th March 2005 - * Updated: 10th October 2026 + * Updated: 17th October 2026 * * Home: http://stlsoft.org/ * @@ -50,7 +50,7 @@ # define PLATFORMSTL_VER_PLATFORMSTL_H_PLATFORMSTL_MAJOR 1 # define PLATFORMSTL_VER_PLATFORMSTL_H_PLATFORMSTL_MINOR 15 # define PLATFORMSTL_VER_PLATFORMSTL_H_PLATFORMSTL_REVISION 9 -# define PLATFORMSTL_VER_PLATFORMSTL_H_PLATFORMSTL_EDIT 64 +# define PLATFORMSTL_VER_PLATFORMSTL_H_PLATFORMSTL_EDIT 65 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ /** \file platformstl/platformstl.h @@ -147,12 +147,13 @@ # define _PLATFORMSTL_VER_1_10_0_A01 0x010a0041 /*!< Version 1.10.0 alpha 1 (with STLSoft 1.11.1 alpha 15) */ # define _PLATFORMSTL_VER_1_10_0_B01 0x010A0081 /*!< Version 1.10.0 beta 1 (with STLSoft 1.11.1 rc 3) */ # define _PLATFORMSTL_VER_1_10_0_B02 0x010A0082 /*!< Version 1.10.0 beta 2 (with STLSoft 1.11.1 rc 8) */ +# define _PLATFORMSTL_VER_1_10_0_B03 0x010A0083 /*!< Version 1.10.0 beta 3 (with STLSoft 1.11.1 rc 9) */ #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ #define _PLATFORMSTL_VER_MAJOR 1 #define _PLATFORMSTL_VER_MINOR 10 #define _PLATFORMSTL_VER_PATCH 0 -#define _PLATFORMSTL_VER_ALPHABETA 0x82 +#define _PLATFORMSTL_VER_ALPHABETA 0x83 #define _PLATFORMSTL_VER \ (0\ @@ -331,7 +332,7 @@ * * \param expr Must be non-zero, or an assertion will be fired * - * \remarks By default this is defined to \ref STLSOFT_ASSERT. However, this + * \note By default this is defined to \ref STLSOFT_ASSERT. However, this * can be overriden if a prior definition is encountered, allowing the * runtime assertion of WinSTL components to use a different mechanism to * those in the other \ref group__projects "projects". @@ -353,7 +354,7 @@ * * \param expr A compile-time evaluatable condition that must be non-zero, or compilation will fail. * - * \remarks This is defined to \ref STLSOFT_STATIC_ASSERT. + * \note This is defined to \ref STLSOFT_STATIC_ASSERT. */ #define PLATFORMSTL_STATIC_ASSERT(expr) STLSOFT_STATIC_ASSERT(expr) diff --git a/include/stlsoft/containers/frequency_map.hpp b/include/stlsoft/containers/frequency_map.hpp index 5828d1a2..a5c390dc 100644 --- a/include/stlsoft/containers/frequency_map.hpp +++ b/include/stlsoft/containers/frequency_map.hpp @@ -5,11 +5,11 @@ * it contains. * * Created: 1st October 2005 - * Updated: 20th March 2025 + * Updated: 15th 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) 2005-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -56,7 +56,7 @@ # define STLSOFT_VER_STLSOFT_CONTAINERS_HPP_FREQUENCY_MAP_MAJOR 2 # define STLSOFT_VER_STLSOFT_CONTAINERS_HPP_FREQUENCY_MAP_MINOR 10 # define STLSOFT_VER_STLSOFT_CONTAINERS_HPP_FREQUENCY_MAP_REVISION 1 -# define STLSOFT_VER_STLSOFT_CONTAINERS_HPP_FREQUENCY_MAP_EDIT 57 +# define STLSOFT_VER_STLSOFT_CONTAINERS_HPP_FREQUENCY_MAP_EDIT 58 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -549,8 +549,8 @@ class frequency_map /// The number of unique entries in the map /// - /// \remarks This may not be the same as the number of calls to - /// push() + /// \note This may not be the same as the number of calls to + /// push(). size_type size() const STLSOFT_NOEXCEPT { STLSOFT_ASSERT(is_valid()); @@ -560,8 +560,8 @@ class frequency_map /// The number of non-unique entries in the map /// - /// \remarks This may not be the same as the number of calls to - /// push() + /// \note This may not be the same as the number of calls to + /// push(). count_type total() const STLSOFT_NOEXCEPT { STLSOFT_ASSERT(is_valid()); diff --git a/include/stlsoft/conversion/integer_to_string/integer_to_base32_string.hpp b/include/stlsoft/conversion/integer_to_string/integer_to_base32_string.hpp index 93202a46..89e2ba91 100644 --- a/include/stlsoft/conversion/integer_to_string/integer_to_base32_string.hpp +++ b/include/stlsoft/conversion/integer_to_string/integer_to_base32_string.hpp @@ -5,7 +5,7 @@ * representation. * * Created: 17th February 2024 - * Updated: 20th March 2025 + * Updated: 15th October 2026 * * Home: http://stlsoft.org/ * @@ -55,7 +55,7 @@ # define STLSOFT_VER_STLSOFT_CONVERSION_INTEGER_TO_STRING_HPP_INTEGER_TO_BASE32_STRING_MAJOR 1 # define STLSOFT_VER_STLSOFT_CONVERSION_INTEGER_TO_STRING_HPP_INTEGER_TO_BASE32_STRING_MINOR 0 # define STLSOFT_VER_STLSOFT_CONVERSION_INTEGER_TO_STRING_HPP_INTEGER_TO_BASE32_STRING_REVISION 2 -# define STLSOFT_VER_STLSOFT_CONVERSION_INTEGER_TO_STRING_HPP_INTEGER_TO_BASE32_STRING_EDIT 3 +# define STLSOFT_VER_STLSOFT_CONVERSION_INTEGER_TO_STRING_HPP_INTEGER_TO_BASE32_STRING_EDIT 4 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -237,8 +237,7 @@ unsigned_integer_to_base32_string_3_( T_character* end = buf + (cchBuf - 1); - // Whichever we do it, we write the nul-terminator (and move down - // one) + // Whichever we do it, we write the NUL character (and move down one) *end-- = '\0'; STLSOFT_COVER_MARK_LINE(); @@ -635,7 +634,7 @@ STLSOFT_CLOSE_WORKER_NS_(ximpl_I2S) /** Converts an integer value into a base-32 string representation in the * given character buffer, assigning the number of characters (excluding - * the nul-terminator) written into the given size variable. + * the NUL character) written into the given size variable. * * \tparam T_integer Type of the integer to be converted * \tparam T_character Type of the character array into which the conversion @@ -645,7 +644,7 @@ STLSOFT_CLOSE_WORKER_NS_(ximpl_I2S) * \param cchBuf Number of character available in \c buf * \param i The value to be converted to octal string * \param numWritten Pointer to a variable to receive the number of - * characters written (excluding nul-terminator) + * characters written (excluding NUL character); * * \pre nullptr != buf * \pre cchBuf > integral_format_width_limits::maxDuotrigesimalWidth diff --git a/include/stlsoft/conversion/integer_to_string/integer_to_base36_string.hpp b/include/stlsoft/conversion/integer_to_string/integer_to_base36_string.hpp index 71dabd47..5714a856 100644 --- a/include/stlsoft/conversion/integer_to_string/integer_to_base36_string.hpp +++ b/include/stlsoft/conversion/integer_to_string/integer_to_base36_string.hpp @@ -5,7 +5,7 @@ * representation. * * Created: 14th February 2024 - * Updated: 20th March 2025 + * Updated: 15th October 2026 * * Home: http://stlsoft.org/ * @@ -55,7 +55,7 @@ # define STLSOFT_VER_STLSOFT_CONVERSION_INTEGER_TO_STRING_HPP_INTEGER_TO_BASE36_STRING_MAJOR 1 # define STLSOFT_VER_STLSOFT_CONVERSION_INTEGER_TO_STRING_HPP_INTEGER_TO_BASE36_STRING_MINOR 0 # define STLSOFT_VER_STLSOFT_CONVERSION_INTEGER_TO_STRING_HPP_INTEGER_TO_BASE36_STRING_REVISION 2 -# define STLSOFT_VER_STLSOFT_CONVERSION_INTEGER_TO_STRING_HPP_INTEGER_TO_BASE36_STRING_EDIT 3 +# define STLSOFT_VER_STLSOFT_CONVERSION_INTEGER_TO_STRING_HPP_INTEGER_TO_BASE36_STRING_EDIT 4 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -245,8 +245,7 @@ unsigned_integer_to_base36_string_3_( T_character* end = buf + (cchBuf - 1); - // Whichever we do it, we write the nul-terminator (and move down - // one) + // Whichever we do it, we write the NUL character (and move down one) *end-- = '\0'; STLSOFT_COVER_MARK_LINE(); @@ -649,7 +648,7 @@ STLSOFT_CLOSE_WORKER_NS_(ximpl_I2S) /** Converts an integer value into a base-36 string representation in the * given character buffer, assigning the number of characters (excluding - * the nul-terminator) written into the given size variable. + * the NUL character) written into the given size variable. * * \tparam T_integer Type of the integer to be converted * \tparam T_character Type of the character array into which the conversion @@ -659,7 +658,7 @@ STLSOFT_CLOSE_WORKER_NS_(ximpl_I2S) * \param cchBuf Number of character available in \c buf * \param i The value to be converted to octal string * \param numWritten Pointer to a variable to receive the number of - * characters written (excluding nul-terminator) + * characters written (excluding NUL character); * * \pre nullptr != buf * \pre cchBuf > integral_format_width_limits::maxHexatridecimalWidth diff --git a/include/stlsoft/conversion/integer_to_string/integer_to_decimal_string.hpp b/include/stlsoft/conversion/integer_to_string/integer_to_decimal_string.hpp index 2b493752..6a118545 100644 --- a/include/stlsoft/conversion/integer_to_string/integer_to_decimal_string.hpp +++ b/include/stlsoft/conversion/integer_to_string/integer_to_decimal_string.hpp @@ -5,11 +5,11 @@ * decimal representation. * * Created: 7th April 2002 - * Updated: 20th March 2025 + * Updated: 15th 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) 2002-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -56,7 +56,7 @@ # define STLSOFT_VER_STLSOFT_CONVERSION_INTEGER_TO_STRING_HPP_INTEGER_TO_DECIMAL_STRING_MAJOR 5 # define STLSOFT_VER_STLSOFT_CONVERSION_INTEGER_TO_STRING_HPP_INTEGER_TO_DECIMAL_STRING_MINOR 0 # define STLSOFT_VER_STLSOFT_CONVERSION_INTEGER_TO_STRING_HPP_INTEGER_TO_DECIMAL_STRING_REVISION 20 -# define STLSOFT_VER_STLSOFT_CONVERSION_INTEGER_TO_STRING_HPP_INTEGER_TO_DECIMAL_STRING_EDIT 97 +# define STLSOFT_VER_STLSOFT_CONVERSION_INTEGER_TO_STRING_HPP_INTEGER_TO_DECIMAL_STRING_EDIT 98 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -197,8 +197,7 @@ unsigned_integer_to_decimal_string( C* end = buf + (cchBuf - 1); - // Whichever we do it, we write the nul-terminator (and move down - // one) + // Whichever we do it, we write the NUL character (and move down one) *end-- = '\0'; STLSOFT_COVER_MARK_LINE(); @@ -606,13 +605,13 @@ STLSOFT_CLOSE_WORKER_NS_(ximpl_I2S) /** Converts an integer value into a decimal string representation in the * given character buffer, assigning the number of characters (excluding - * the nul-terminator) written into the given size variable. + * the NUL character) written into the given size variable. * * \param buf Pointer to the buffer * \param cchBuf Number of character available in \c buf * \param i The value to be converted to octal string * \param numWritten Pointer to a variable to receive the number of - * characters written (excluding nul-terminator) + * characters written (excluding NUL character); * * \pre nullptr != buf * \pre cchBuf > integral_format_width_limits::maxDecimalWidth diff --git a/include/stlsoft/conversion/integer_to_string/integer_to_hexadecimal_string.hpp b/include/stlsoft/conversion/integer_to_string/integer_to_hexadecimal_string.hpp index 49c5797c..8e9e3b90 100644 --- a/include/stlsoft/conversion/integer_to_string/integer_to_hexadecimal_string.hpp +++ b/include/stlsoft/conversion/integer_to_string/integer_to_hexadecimal_string.hpp @@ -5,11 +5,11 @@ * hexadecimal representation. * * Created: 7th April 2002 - * Updated: 20th March 2025 + * Updated: 15th 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) 2002-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -56,7 +56,7 @@ # define STLSOFT_VER_STLSOFT_CONVERSION_INTEGER_TO_STRING_HPP_INTEGER_TO_HEXADECIMAL_STRING_MAJOR 5 # define STLSOFT_VER_STLSOFT_CONVERSION_INTEGER_TO_STRING_HPP_INTEGER_TO_HEXADECIMAL_STRING_MINOR 0 # define STLSOFT_VER_STLSOFT_CONVERSION_INTEGER_TO_STRING_HPP_INTEGER_TO_HEXADECIMAL_STRING_REVISION 22 -# define STLSOFT_VER_STLSOFT_CONVERSION_INTEGER_TO_STRING_HPP_INTEGER_TO_HEXADECIMAL_STRING_EDIT 101 +# define STLSOFT_VER_STLSOFT_CONVERSION_INTEGER_TO_STRING_HPP_INTEGER_TO_HEXADECIMAL_STRING_EDIT 102 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -209,8 +209,7 @@ unsigned_integer_to_hexadecimal_string( C* end = buf + (cchBuf - 1); - // Whichever we do it, we write the nul-terminator (and move down - // one) + // Whichever we do it, we write the NUL character (and move down one) *end-- = '\0'; STLSOFT_COVER_MARK_LINE(); @@ -613,13 +612,13 @@ STLSOFT_CLOSE_WORKER_NS_(ximpl_I2S) /** Converts an integer value into a hexadecimal string representation in the * given character buffer, assigning the number of characters (excluding - * the nul-terminator) written into the given size variable. + * the NUL character) written into the given size variable. * * \param buf Pointer to the buffer * \param cchBuf Number of character available in \c buf * \param i The value to be converted to octal string * \param numWritten Pointer to a variable to receive the number of - * characters written (excluding nul-terminator) + * characters written (excluding NUL character); * * \pre nullptr != buf * \pre cchBuf > integral_format_width_limits::maxHexadecimalWidth diff --git a/include/stlsoft/conversion/integer_to_string/integer_to_lc_string.hpp b/include/stlsoft/conversion/integer_to_string/integer_to_lc_string.hpp index 44fa9e03..c4d50547 100644 --- a/include/stlsoft/conversion/integer_to_string/integer_to_lc_string.hpp +++ b/include/stlsoft/conversion/integer_to_string/integer_to_lc_string.hpp @@ -5,11 +5,11 @@ * for decimal representation. * * Created: 1st November 2011 - * Updated: 20th March 2025 + * Updated: 15th 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) 2011-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -56,7 +56,7 @@ # define STLSOFT_VER_STLSOFT_CONVERSION_INTEGER_TO_STRING_HPP_INTEGER_TO_LC_STRING_MAJOR 1 # define STLSOFT_VER_STLSOFT_CONVERSION_INTEGER_TO_STRING_HPP_INTEGER_TO_LC_STRING_MINOR 0 # define STLSOFT_VER_STLSOFT_CONVERSION_INTEGER_TO_STRING_HPP_INTEGER_TO_LC_STRING_REVISION 13 -# define STLSOFT_VER_STLSOFT_CONVERSION_INTEGER_TO_STRING_HPP_INTEGER_TO_LC_STRING_EDIT 23 +# define STLSOFT_VER_STLSOFT_CONVERSION_INTEGER_TO_STRING_HPP_INTEGER_TO_LC_STRING_EDIT 24 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -98,7 +98,7 @@ namespace stlsoft /** Converts an integer value into a decimal string representation in the * given character buffer with grouping characters according to the given * picture, assigning the number of characters (excluding the - * nul-terminator) written into the given size variable. + * NUL character) written into the given size variable. * * \tparam C1 Character type 1 * \tparam C2 Character type 2 @@ -113,7 +113,7 @@ namespace stlsoft * \param cchDest Size of available buffer. Ignored if dest is \c nullptr; * \param value The number to be converted; * \param numWritten Pointer to a variable to receive the number of - * characters written (excluding nul-terminator) + * characters written (excluding NUL character); * * \pre nullptr != buf * \pre cchBuf > integral_format_width_limits::maxDecimalWidth diff --git a/include/stlsoft/conversion/integer_to_string/integer_to_octal_string.hpp b/include/stlsoft/conversion/integer_to_string/integer_to_octal_string.hpp index 0793fcc8..a9cb1dcd 100644 --- a/include/stlsoft/conversion/integer_to_string/integer_to_octal_string.hpp +++ b/include/stlsoft/conversion/integer_to_string/integer_to_octal_string.hpp @@ -5,11 +5,11 @@ * octal representation. * * Created: 7th April 2002 - * Updated: 20th March 2025 + * Updated: 15th 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) 2002-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -56,7 +56,7 @@ # define STLSOFT_VER_STLSOFT_CONVERSION_INTEGER_TO_STRING_HPP_INTEGER_TO_OCTAL_STRING_MAJOR 5 # define STLSOFT_VER_STLSOFT_CONVERSION_INTEGER_TO_STRING_HPP_INTEGER_TO_OCTAL_STRING_MINOR 0 # define STLSOFT_VER_STLSOFT_CONVERSION_INTEGER_TO_STRING_HPP_INTEGER_TO_OCTAL_STRING_REVISION 23 -# define STLSOFT_VER_STLSOFT_CONVERSION_INTEGER_TO_STRING_HPP_INTEGER_TO_OCTAL_STRING_EDIT 102 +# define STLSOFT_VER_STLSOFT_CONVERSION_INTEGER_TO_STRING_HPP_INTEGER_TO_OCTAL_STRING_EDIT 103 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -193,8 +193,7 @@ unsigned_integer_to_octal_string( C* end = buf + (cchBuf - 1); - // Whichever we do it, we write the nul-terminator (and move down - // one) + // Whichever we do it, we write the NUL character (and move down one) *end-- = '\0'; STLSOFT_COVER_MARK_LINE(); @@ -595,13 +594,13 @@ STLSOFT_CLOSE_WORKER_NS_(ximpl_I2S) /** Converts an integer value into an octal string representation in the * given character buffer, assigning the number of characters (excluding - * the nul-terminator) written into the given size variable. + * the NUL character) written into the given size variable. * * \param buf Pointer to the buffer * \param cchBuf Number of character available in \c buf * \param i The value to be converted to octal string * \param numWritten Pointer to a variable to receive the number of - * characters written (excluding nul-terminator) + * characters written (excluding NUL character); * * \pre nullptr != buf * \pre cchBuf > integral_format_width_limits::maxOctalWidth diff --git a/include/stlsoft/conversion/sap_cast.hpp b/include/stlsoft/conversion/sap_cast.hpp index 74e15afa..7e2f9aac 100644 --- a/include/stlsoft/conversion/sap_cast.hpp +++ b/include/stlsoft/conversion/sap_cast.hpp @@ -5,11 +5,11 @@ * the same cv-qualification. * * Created: 25th February 2004 - * Updated: 20th March 2025 + * Updated: 15th 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) 2004-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -55,7 +55,7 @@ # define STLSOFT_VER_STLSOFT_CONVERSION_HPP_SAP_CAST_MAJOR 4 # define STLSOFT_VER_STLSOFT_CONVERSION_HPP_SAP_CAST_MINOR 0 # define STLSOFT_VER_STLSOFT_CONVERSION_HPP_SAP_CAST_REVISION 8 -# define STLSOFT_VER_STLSOFT_CONVERSION_HPP_SAP_CAST_EDIT 61 +# define STLSOFT_VER_STLSOFT_CONVERSION_HPP_SAP_CAST_EDIT 62 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -131,7 +131,7 @@ short* ps = stlsoft::sap_cast(pi); * * \param from The pointer to cast from. * - * \remarks The cast operator was inspired by an item in the + * \note The cast operator was inspired by an item in the * Sutter/Alexandrescu coding standards book, and its names stands for * Sutter-Alexandrescu-Pointer cast. The acronym is overloaded, since one * might also be said to be a sap if one made injudicious use of the cast, diff --git a/include/stlsoft/diagnostics/std_chrono_hrc_stopwatch.hpp b/include/stlsoft/diagnostics/std_chrono_hrc_stopwatch.hpp index 19902a84..07ffd949 100644 --- a/include/stlsoft/diagnostics/std_chrono_hrc_stopwatch.hpp +++ b/include/stlsoft/diagnostics/std_chrono_hrc_stopwatch.hpp @@ -4,7 +4,7 @@ * Purpose: stopwatch class based on std::chrono::high_resolution_clock. * * Created: 17th March 2024 - * Updated: 20th March 2025 + * Updated: 15th October 2026 * * Home: http://stlsoft.org/ * @@ -57,7 +57,7 @@ # define STLSOFT_VER_STLSOFT_DIAGNOSTICS_HPP_STD_CHRONO_HRC_STOPWATCH_MAJOR 1 # define STLSOFT_VER_STLSOFT_DIAGNOSTICS_HPP_STD_CHRONO_HRC_STOPWATCH_MINOR 1 # define STLSOFT_VER_STLSOFT_DIAGNOSTICS_HPP_STD_CHRONO_HRC_STOPWATCH_REVISION 1 -# define STLSOFT_VER_STLSOFT_DIAGNOSTICS_HPP_STD_CHRONO_HRC_STOPWATCH_EDIT 5 +# define STLSOFT_VER_STLSOFT_DIAGNOSTICS_HPP_STD_CHRONO_HRC_STOPWATCH_EDIT 6 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -140,8 +140,8 @@ class std_chrono_hrc_stopwatch void stop(); /// Ends the current measurement period and start the next /// - /// \remarks This is equivalent to an atomic invocation of stop() and - /// start() + /// \note This is equivalent to an atomic invocation of stop() and + /// start(). void restart(); public: // attributes diff --git a/include/stlsoft/filesystem/io_functions/read_line.hpp b/include/stlsoft/filesystem/io_functions/read_line.hpp index 2cd9b0bc..a2f8690a 100644 --- a/include/stlsoft/filesystem/io_functions/read_line.hpp +++ b/include/stlsoft/filesystem/io_functions/read_line.hpp @@ -4,11 +4,11 @@ * Purpose: Definition of stlsoft::read_line() function template. * * Created: 2nd January 2007 - * Updated: 20th March 2025 + * Updated: 15th 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) 2007-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -55,7 +55,7 @@ # define STLSOFT_VER_STLSOFT_FILESYSTEM_IO_FUNCTIONS_HPP_READ_LINE_MAJOR 3 # define STLSOFT_VER_STLSOFT_FILESYSTEM_IO_FUNCTIONS_HPP_READ_LINE_MINOR 0 # define STLSOFT_VER_STLSOFT_FILESYSTEM_IO_FUNCTIONS_HPP_READ_LINE_REVISION 3 -# define STLSOFT_VER_STLSOFT_FILESYSTEM_IO_FUNCTIONS_HPP_READ_LINE_EDIT 30 +# define STLSOFT_VER_STLSOFT_FILESYSTEM_IO_FUNCTIONS_HPP_READ_LINE_EDIT 31 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -440,7 +440,7 @@ namespace read_line_impl { * \retval true The parsing is not complete * \retval false The parsing is complete * - * \remarks The function can recognise any or all of the following as + * \note The function can recognise any or all of the following as * line-termination sequences: carriage-return ('\\r'), * line-feed ('\\n'), or carriage-return+line-feed * ("\\r\\n"). diff --git a/include/stlsoft/filesystem/path_buffer.hpp b/include/stlsoft/filesystem/path_buffer.hpp index 85eace07..c331b985 100644 --- a/include/stlsoft/filesystem/path_buffer.hpp +++ b/include/stlsoft/filesystem/path_buffer.hpp @@ -4,11 +4,11 @@ * Purpose: Contains the basic_path_buffer template class. * * Created: 27th May 2020 - * Updated: 20th March 2025 + * Updated: 15th October 2026 * * Home: http://stlsoft.org/ * - * Copyright (c) 2020-2025, 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 @@ -54,7 +54,7 @@ # define STLSOFT_VER_STLSOFT_FILESYSTEM_HPP_PATH_BUFFER_MAJOR 1 # define STLSOFT_VER_STLSOFT_FILESYSTEM_HPP_PATH_BUFFER_MINOR 3 # define STLSOFT_VER_STLSOFT_FILESYSTEM_HPP_PATH_BUFFER_REVISION 5 -# define STLSOFT_VER_STLSOFT_FILESYSTEM_HPP_PATH_BUFFER_EDIT 13 +# define STLSOFT_VER_STLSOFT_FILESYSTEM_HPP_PATH_BUFFER_EDIT 14 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -289,7 +289,7 @@ class basic_path_buffer public: // operations /// /// - /// \pre (0 == n || nullptr != s) + /// \pre 0 == n || nullptr != s class_type& assign( char_type const* s @@ -490,7 +490,7 @@ class basic_path_buffer } /// \return The number of characters written, including the - /// NUL-terminator if included + /// NUL character if included. size_type copy( char_type buffer[] diff --git a/include/stlsoft/iterator/FILE_iterator.hpp b/include/stlsoft/iterator/FILE_iterator.hpp index 13b14e12..3b1ddb3d 100644 --- a/include/stlsoft/iterator/FILE_iterator.hpp +++ b/include/stlsoft/iterator/FILE_iterator.hpp @@ -4,11 +4,11 @@ * Purpose: FILE* output iterator. * * Created: 21st April 2009 - * Updated: 28th May 2025 + * Updated: 15th 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) 2009-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -55,7 +55,7 @@ # define STLSOFT_VER_STLSOFT_ITERATOR_HPP_FILE_ITERATOR_MAJOR 1 # define STLSOFT_VER_STLSOFT_ITERATOR_HPP_FILE_ITERATOR_MINOR 0 # define STLSOFT_VER_STLSOFT_ITERATOR_HPP_FILE_ITERATOR_REVISION 12 -# define STLSOFT_VER_STLSOFT_ITERATOR_HPP_FILE_ITERATOR_EDIT 24 +# define STLSOFT_VER_STLSOFT_ITERATOR_HPP_FILE_ITERATOR_EDIT 25 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -162,8 +162,8 @@ std::copy(ints.begin(), ints.end() * \param T The traits type. Defaults to std::char_traits<C>. * \param S The string type. Defaults to std::basic_string<C>. * - * \remarks The class template avoids fatuous assignment syntax by using the - * \ref group__pattern__dereference_proxy "Dereference Proxy" pattern. + * \note The class template avoids fatuous assignment syntax by using + * the \ref group__pattern__dereference_proxy "Dereference Proxy" pattern. * * \warn There is no protection against a mismatched format string. You must * ensure that the assigned type matches the format string. diff --git a/include/stlsoft/iterators/ostream_iterator.hpp b/include/stlsoft/iterators/ostream_iterator.hpp index 50801332..e063b186 100644 --- a/include/stlsoft/iterators/ostream_iterator.hpp +++ b/include/stlsoft/iterators/ostream_iterator.hpp @@ -4,11 +4,11 @@ * Purpose: Enhanced ostream iterator. * * Created: 16th December 2005 - * Updated: 20th March 2025 + * Updated: 15th 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) 2005-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -55,7 +55,7 @@ # define STLSOFT_VER_STLSOFT_ITERATORS_HPP_OSTREAM_ITERATOR_MAJOR 1 # define STLSOFT_VER_STLSOFT_ITERATORS_HPP_OSTREAM_ITERATOR_MINOR 3 # define STLSOFT_VER_STLSOFT_ITERATORS_HPP_OSTREAM_ITERATOR_REVISION 12 -# define STLSOFT_VER_STLSOFT_ITERATORS_HPP_OSTREAM_ITERATOR_EDIT 56 +# define STLSOFT_VER_STLSOFT_ITERATORS_HPP_OSTREAM_ITERATOR_EDIT 57 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -147,8 +147,8 @@ std::copy(ints.begin(), ints.end(), stlsoft::ostream_iterator(std::cout, "\ * \param T The traits type. Defaults to std::char_traits<C>. * \param S The string type. Defaults to std::basic_string<C>. * - * \remarks The class template avoids fatuous assignment syntax by using the - * \ref group__pattern__dereference_proxy "Dereference Proxy" pattern. + * \note The class template avoids fatuous assignment syntax by using + * the \ref group__pattern__dereference_proxy "Dereference Proxy" pattern. */ template< ss_typename_param_k V , ss_typename_param_k C = char diff --git a/include/stlsoft/limits/integral_format_width_limits.hpp b/include/stlsoft/limits/integral_format_width_limits.hpp index 3debba08..0d7b1ced 100644 --- a/include/stlsoft/limits/integral_format_width_limits.hpp +++ b/include/stlsoft/limits/integral_format_width_limits.hpp @@ -4,13 +4,13 @@ * Purpose: integral_format_width_limits traits class template. * * Created: 10th July 2012 - * Updated: 28th May 2025 + * Updated: 15th October 2026 * * Thanks: To Jonathan Wakely for help with Solaris compatibility. * * 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) 2012-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -57,7 +57,7 @@ # define STLSOFT_VER_STLSOFT_LIMITS_HPP_INTEGRAL_FORMAT_WIDTH_LIMITS_MAJOR 1 # define STLSOFT_VER_STLSOFT_LIMITS_HPP_INTEGRAL_FORMAT_WIDTH_LIMITS_MINOR 1 # define STLSOFT_VER_STLSOFT_LIMITS_HPP_INTEGRAL_FORMAT_WIDTH_LIMITS_REVISION 2 -# define STLSOFT_VER_STLSOFT_LIMITS_HPP_INTEGRAL_FORMAT_WIDTH_LIMITS_EDIT 16 +# define STLSOFT_VER_STLSOFT_LIMITS_HPP_INTEGRAL_FORMAT_WIDTH_LIMITS_EDIT 17 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -99,7 +99,7 @@ namespace stlsoft /// functions such as printf(). /// /// \note The lengths given do not count the -/// nul-terminator character. +/// NUL character character. /// /// \param I The integral type for which the template diff --git a/include/stlsoft/memory/allocator_base.hpp b/include/stlsoft/memory/allocator_base.hpp index 397510fa..81e7001b 100644 --- a/include/stlsoft/memory/allocator_base.hpp +++ b/include/stlsoft/memory/allocator_base.hpp @@ -4,11 +4,11 @@ * Purpose: Allocator commmon features. * * Created: 20th August 2003 - * Updated: 28th July 2026 + * Updated: 15th 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) 2003-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -55,7 +55,7 @@ # define STLSOFT_VER_STLSOFT_MEMORY_HPP_ALLOCATOR_BASE_MAJOR 4 # define STLSOFT_VER_STLSOFT_MEMORY_HPP_ALLOCATOR_BASE_MINOR 1 # define STLSOFT_VER_STLSOFT_MEMORY_HPP_ALLOCATOR_BASE_REVISION 17 -# define STLSOFT_VER_STLSOFT_MEMORY_HPP_ALLOCATOR_BASE_EDIT 71 +# define STLSOFT_VER_STLSOFT_MEMORY_HPP_ALLOCATOR_BASE_EDIT 72 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -134,10 +134,10 @@ namespace stlsoft * winstl::processheap_allocator | * winstl::shell_allocator * - * \remarks This uses the SCTP/CRTP (Simulated Compile-time Polymorphism / Curiously - * Recurring Template Pattern) technique, such that derived classes inherit from - * specialisations of the adaptor template which specify their fully derived - * template-id as the first parameter + * \note This uses the SCTP/CRTP (Simulated Compile-time Polymorphism / + * Curiously Recurring Template Pattern) technique, such that derived + * classes inherit from specialisations of the adaptor template which + * specify their fully derived template-id as the first parameter. * * \note By default, an allocation failure results in a thrown std::bad_alloc. If * the compiler does not throwing std::bad_alloc by default, this behaviour can be @@ -264,8 +264,8 @@ class allocator_base /// The method is functionally identical to /// static_cast(allocate(n, NULL)) /// - /// \remarks This method is only defined when the symbol - /// \ref STLSOFT_CF_ALLOCATOR_CHARALLOC_METHOD is defined. + /// \note This method is only defined when the + /// symbol \ref STLSOFT_CF_ALLOCATOR_CHARALLOC_METHOD is defined. char* _Charalloc(size_type n) { # ifdef STLSOFT_LF_ALLOCATOR_ALLOCATE_HAS_HINT diff --git a/include/stlsoft/memory/auto_buffer.h b/include/stlsoft/memory/auto_buffer.h index 201a4cd7..18887f9e 100644 --- a/include/stlsoft/memory/auto_buffer.h +++ b/include/stlsoft/memory/auto_buffer.h @@ -4,11 +4,11 @@ * Purpose: auto_buffer functionality for C. * * Created: 5th August 2011 - * Updated: 19th November 2024 + * Updated: 11th 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) 2011-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -54,7 +54,7 @@ # define STLSOFT_VER_STLSOFT_MEMORY_H_AUTO_BUFFER_MAJOR 2 # define STLSOFT_VER_STLSOFT_MEMORY_H_AUTO_BUFFER_MINOR 0 # define STLSOFT_VER_STLSOFT_MEMORY_H_AUTO_BUFFER_REVISION 3 -# define STLSOFT_VER_STLSOFT_MEMORY_H_AUTO_BUFFER_EDIT 22 +# define STLSOFT_VER_STLSOFT_MEMORY_H_AUTO_BUFFER_EDIT 23 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -127,7 +127,7 @@ namespace stlsoft \endhtmlonly * - * \pre (0 < internalSize) + * \pre 0 < internalSize * * \see STLSOFT_C_AUTO_BUFFER_INITIALISE, STLSOFT_C_AUTO_BUFFER_INITIALISE_FROM_INTERNAL, STLSOFT_C_AUTO_BUFFER_RESIZE, STLSOFT_C_AUTO_BUFFER_RESIZE_FROM_INTERNAL, STLSOFT_C_AUTO_BUFFER_FREE */ diff --git a/include/stlsoft/memory/auto_buffer.hpp b/include/stlsoft/memory/auto_buffer.hpp index b24e3a44..92a66dcc 100644 --- a/include/stlsoft/memory/auto_buffer.hpp +++ b/include/stlsoft/memory/auto_buffer.hpp @@ -4,7 +4,7 @@ * Purpose: Contains the auto_buffer template class. * * Created: 19th January 2002 - * Updated: 29th June 2025 + * Updated: 15th October 2026 * * Thanks: To Magnificent Imbecil for pointing out error in documentation, * and for suggesting swap() optimisation. To Thorsten Ottosen for @@ -12,7 +12,7 @@ * * 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) 2002-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -58,7 +58,7 @@ # define STLSOFT_VER_STLSOFT_MEMORY_HPP_AUTO_BUFFER_MAJOR 5 # define STLSOFT_VER_STLSOFT_MEMORY_HPP_AUTO_BUFFER_MINOR 9 # define STLSOFT_VER_STLSOFT_MEMORY_HPP_AUTO_BUFFER_REVISION 1 -# define STLSOFT_VER_STLSOFT_MEMORY_HPP_AUTO_BUFFER_EDIT 233 +# define STLSOFT_VER_STLSOFT_MEMORY_HPP_AUTO_BUFFER_EDIT 234 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -339,12 +339,12 @@ int pantheios_log_n( * and * shwild. * - * \remarks auto_buffer works correctly whether the given allocator throws + * \note auto_buffer works correctly whether the given allocator throws * an exception on allocation failure, or returns \c nullptr. In the * latter case, construction failure to allocate is reflected by the * size() method returning 0. * - * \remarks The design of auto_buffer is described in Chapter 32 of + * \note The design of auto_buffer is described in Chapter 32 of * Imperfect C++, and its * interface is discussed in detail in Section 16.2 of * Extended STL, volume 1. @@ -1422,7 +1422,7 @@ class auto_buffer /// Returns a reference to the last element in the buffer /// - /// \pre The buffer instance must not be empty + /// \pre !empty() ss_constexpr_2014_k reference front() { @@ -1434,7 +1434,7 @@ class auto_buffer } /// Returns a reference to the last element in the buffer /// - /// \pre The buffer instance must not be empty + /// \pre !empty() ss_constexpr_2014_k reference back() { @@ -1447,7 +1447,7 @@ class auto_buffer /// Returns a non-mutating (const) reference to the last element /// in the buffer /// - /// \pre The buffer instance must not be empty + /// \pre !empty() ss_constexpr_2014_k const_reference front() const { @@ -1460,7 +1460,7 @@ class auto_buffer /// Returns a non-mutating (const) reference to the last element /// in the buffer /// - /// \pre The buffer instance must not be empty + /// \pre !empty() ss_constexpr_2014_k const_reference back() const { diff --git a/include/stlsoft/meta/is_class_type.hpp b/include/stlsoft/meta/is_class_type.hpp index ba328a72..8e9b40b7 100644 --- a/include/stlsoft/meta/is_class_type.hpp +++ b/include/stlsoft/meta/is_class_type.hpp @@ -4,11 +4,11 @@ * Purpose: is_class_type meta class. * * Created: 19th November 1998 - * Updated: 20th March 2025 + * Updated: 15th 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) 2005-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -55,7 +55,7 @@ # define STLSOFT_VER_STLSOFT_META_HPP_IS_CLASS_TYPE_MAJOR 1 # define STLSOFT_VER_STLSOFT_META_HPP_IS_CLASS_TYPE_MINOR 0 # define STLSOFT_VER_STLSOFT_META_HPP_IS_CLASS_TYPE_REVISION 7 -# define STLSOFT_VER_STLSOFT_META_HPP_IS_CLASS_TYPE_EDIT 22 +# define STLSOFT_VER_STLSOFT_META_HPP_IS_CLASS_TYPE_EDIT 23 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -128,15 +128,15 @@ two_t is_class_type_func(...); /** Traits type used to determine whether the given type is * of class type. * - * \remarks Compatibility: - * - Borland C/C++ 5.6 compiles but thinks everything is a class type - * - CodePlay compiles but thinks that nothing is a class type - * - Comeau works with most things (not references) - * - CodeWarrior 3.0+ compiles and works from version 8 onwards - * - Digital Mars 8.40+ compiles and works with most things (not references) - * - GCC works with most things (not references) - * - Intel works with most things (not references) - * - Visual C++ compiles and works from version 7.1 onwards with most things (not references) + * \note Compatibility: + * - Borland C/C++ 5.6 compiles but thinks everything is a class type; + * - CodePlay compiles but thinks that nothing is a class type; + * - Comeau works with most things (not references); + * - CodeWarrior 3.0+ compiles and works from version 8 onwards; + * - Digital Mars 8.40+ compiles and works with most things (not references); + * - GCC works with most things (not references); + * - Intel works with most things (not references); + * - Visual C++ compiles and works from version 7.1 onwards with most things (not references); * * \ingroup group__library__Metaprogramming */ diff --git a/include/stlsoft/obsolete/proxy_iterator.hpp b/include/stlsoft/obsolete/proxy_iterator.hpp index 8c2eefed..45c5b574 100644 --- a/include/stlsoft/obsolete/proxy_iterator.hpp +++ b/include/stlsoft/obsolete/proxy_iterator.hpp @@ -4,11 +4,11 @@ * Purpose: proxy_iterator template class. * * Created: 28th June 2004 - * Updated: 20th March 2025 + * Updated: 15th 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) 2004-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -52,7 +52,7 @@ # define STLSOFT_VER_STLSOFT_OBSOLETE_HPP_PROXY_ITERATOR_MAJOR 3 # define STLSOFT_VER_STLSOFT_OBSOLETE_HPP_PROXY_ITERATOR_MINOR 0 # define STLSOFT_VER_STLSOFT_OBSOLETE_HPP_PROXY_ITERATOR_REVISION 6 -# define STLSOFT_VER_STLSOFT_OBSOLETE_HPP_PROXY_ITERATOR_EDIT 66 +# define STLSOFT_VER_STLSOFT_OBSOLETE_HPP_PROXY_ITERATOR_EDIT 67 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -110,7 +110,7 @@ namespace stlsoft * \param R The reference type * \param P The pointer type * - * \remarks Iterator for proxy_sequence + * \note Iterator for proxy_sequence. * * \deprecated This is maintained for backwards compatibility with the * recls/COM library. New users should instead use diff --git a/include/stlsoft/shims/access/string/std/exception.hpp b/include/stlsoft/shims/access/string/std/exception.hpp index 3444e51b..f1e8d740 100644 --- a/include/stlsoft/shims/access/string/std/exception.hpp +++ b/include/stlsoft/shims/access/string/std/exception.hpp @@ -4,11 +4,11 @@ * Purpose: Contains the string access shims for std::exception. * * Created: 2nd May 2003 - * Updated: 20th March 2025 + * Updated: 15th 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) 2003-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -55,7 +55,7 @@ # define _STLSOFT_VER_STLSOFT_SHIMS_ACCESS_STRING_STD_HPP_EXCEPTION_MAJOR 2 # define _STLSOFT_VER_STLSOFT_SHIMS_ACCESS_STRING_STD_HPP_EXCEPTION_MINOR 2 # define _STLSOFT_VER_STLSOFT_SHIMS_ACCESS_STRING_STD_HPP_EXCEPTION_REVISION 15 -# define _STLSOFT_VER_STLSOFT_SHIMS_ACCESS_STRING_STD_HPP_EXCEPTION_EDIT 61 +# define _STLSOFT_VER_STLSOFT_SHIMS_ACCESS_STRING_STD_HPP_EXCEPTION_EDIT 62 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -123,7 +123,7 @@ struct ximpl_stlsoft_shims_access_string_std_exception_ { public: // - // *numConverted excludes the nul-terminator + // *numConverted excludes the NUL character static int mbstowcs_( @@ -146,7 +146,7 @@ struct ximpl_stlsoft_shims_access_string_std_exception_ { STLSOFT_ASSERT(0 != *numConverted); - --*numConverted; // mbstowcs_s() always adds one for nul-terminator + --*numConverted; // mbstowcs_s() always adds one for NUL character } return r; @@ -167,7 +167,7 @@ struct ximpl_stlsoft_shims_access_string_std_exception_ } // - // *numConverted excludes the nul-terminator + // *numConverted excludes the NUL character static int mbstowcs_len( @@ -185,7 +185,7 @@ struct ximpl_stlsoft_shims_access_string_std_exception_ { STLSOFT_ASSERT(0 != *len); - --*len; // mbstowcs_s() always adds one for nul-terminator + --*len; // mbstowcs_s() always adds one for NUL character } return r; diff --git a/include/stlsoft/shims/access/string/std/type_info.hpp b/include/stlsoft/shims/access/string/std/type_info.hpp index 2d413b53..c50627cb 100644 --- a/include/stlsoft/shims/access/string/std/type_info.hpp +++ b/include/stlsoft/shims/access/string/std/type_info.hpp @@ -4,11 +4,11 @@ * Purpose: Contains the string access shims for std::type_info. * * Created: 19th December 2011 - * Updated: 20th March 2025 + * Updated: 15th 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) 2011-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -55,7 +55,7 @@ # define _STLSOFT_VER_STLSOFT_SHIMS_ACCESS_STRING_STD_HPP_TYPE_INFO_MAJOR 2 # define _STLSOFT_VER_STLSOFT_SHIMS_ACCESS_STRING_STD_HPP_TYPE_INFO_MINOR 3 # define _STLSOFT_VER_STLSOFT_SHIMS_ACCESS_STRING_STD_HPP_TYPE_INFO_REVISION 4 -# define _STLSOFT_VER_STLSOFT_SHIMS_ACCESS_STRING_STD_HPP_TYPE_INFO_EDIT 58 +# define _STLSOFT_VER_STLSOFT_SHIMS_ACCESS_STRING_STD_HPP_TYPE_INFO_EDIT 59 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -130,7 +130,7 @@ struct ximpl_stlsoft_shims_access_string_std_type_info_ { public: // - // *numConverted excludes the nul-terminator + // *numConverted excludes the NUL character static int mbstowcs_( @@ -141,7 +141,7 @@ struct ximpl_stlsoft_shims_access_string_std_type_info_ , ss_size_t* numConverted ) { - // Always assume the nul-terminator + // Always assume the NUL character STLSOFT_ASSERT(NULL != mbs); STLSOFT_ASSERT(NULL != numConverted); @@ -154,7 +154,7 @@ struct ximpl_stlsoft_shims_access_string_std_type_info_ { STLSOFT_ASSERT(0 != *numConverted); - --*numConverted; // mbstowcs_s() always adds one for nul-terminator + --*numConverted; // mbstowcs_s() always adds one for NUL character } return r; @@ -175,7 +175,7 @@ struct ximpl_stlsoft_shims_access_string_std_type_info_ } // - // *numConverted excludes the nul-terminator + // *numConverted excludes the NUL character static int mbstowcs_len( @@ -193,7 +193,7 @@ struct ximpl_stlsoft_shims_access_string_std_type_info_ { STLSOFT_ASSERT(0 != *len); - --*len; // mbstowcs_s() always adds one for nul-terminator + --*len; // mbstowcs_s() always adds one for NUL character } return r; diff --git a/include/stlsoft/smartptr/ref_ptr.hpp b/include/stlsoft/smartptr/ref_ptr.hpp index be1817bd..df0d4194 100644 --- a/include/stlsoft/smartptr/ref_ptr.hpp +++ b/include/stlsoft/smartptr/ref_ptr.hpp @@ -4,11 +4,11 @@ * Purpose: Contains the ref_ptr template class. * * Created: 2nd November 1994 - * Updated: 21st March 2025 + * Updated: 11th 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) 1994-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -55,7 +55,7 @@ # define STLSOFT_VER_STLSOFT_SMARTPTR_HPP_REF_PTR_MAJOR 5 # define STLSOFT_VER_STLSOFT_SMARTPTR_HPP_REF_PTR_MINOR 5 # define STLSOFT_VER_STLSOFT_SMARTPTR_HPP_REF_PTR_REVISION 1 -# define STLSOFT_VER_STLSOFT_SMARTPTR_HPP_REF_PTR_EDIT 517 +# define STLSOFT_VER_STLSOFT_SMARTPTR_HPP_REF_PTR_EDIT 518 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -511,8 +511,7 @@ class ref_ptr /// Returns the interface pointer /// - /// \pre The instance must not be empty; otherwise behaviour is - /// undefined + /// \pre !empty() counted_type* operator ->() { STLSOFT_MESSAGE_ASSERT("Dereferencing a NULL pointer!", NULL != m_pi); @@ -522,8 +521,7 @@ class ref_ptr /// Returns the interface pointer /// - /// \pre The instance must not be empty; otherwise behaviour is - /// undefined + /// \pre !empty() counted_type const* operator ->() const { STLSOFT_MESSAGE_ASSERT("Dereferencing a NULL pointer!", NULL != m_pi); @@ -533,8 +531,7 @@ class ref_ptr /// Returns a reference to the managed instance /// - /// \pre The instance must not be empty; otherwise behaviour is - /// undefined + /// \pre !empty() counted_type& operator *() { STLSOFT_MESSAGE_ASSERT("Dereferencing a NULL pointer!", NULL != m_pi); @@ -544,8 +541,7 @@ class ref_ptr /// Returns a reference to the managed instance /// - /// \pre The instance must not be empty; otherwise behaviour is - /// undefined + /// \pre !empty() counted_type const& operator *() const { STLSOFT_MESSAGE_ASSERT("Dereferencing a NULL pointer!", NULL != m_pi); diff --git a/include/stlsoft/smartptr/scoped_handle/scoped_handle_cc.hpp b/include/stlsoft/smartptr/scoped_handle/scoped_handle_cc.hpp index 4a854a55..1998494b 100644 --- a/include/stlsoft/smartptr/scoped_handle/scoped_handle_cc.hpp +++ b/include/stlsoft/smartptr/scoped_handle/scoped_handle_cc.hpp @@ -5,13 +5,13 @@ * types. * * Created: 1st November 1994 - * Updated: 20th March 2025 + * Updated: 15th October 2026 * * Thanks: Adi Shavit, for requesting the indirect functionality * * 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) 1994-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -58,7 +58,7 @@ # define STLSOFT_VER_STLSOFT_SMARTPTR_SCOPED_HANDLE_HPP_SCOPED_HANDLE_CC_MAJOR 5 # define STLSOFT_VER_STLSOFT_SMARTPTR_SCOPED_HANDLE_HPP_SCOPED_HANDLE_CC_MINOR 7 # define STLSOFT_VER_STLSOFT_SMARTPTR_SCOPED_HANDLE_HPP_SCOPED_HANDLE_CC_REVISION 3 -# define STLSOFT_VER_STLSOFT_SMARTPTR_SCOPED_HANDLE_HPP_SCOPED_HANDLE_CC_EDIT 694 +# define STLSOFT_VER_STLSOFT_SMARTPTR_SCOPED_HANDLE_HPP_SCOPED_HANDLE_CC_EDIT 695 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -618,7 +618,7 @@ class scoped_handle /// Detaches the resource, and returns it to the caller. /// - /// \remarks Calling this method removes the resource from the managing + /// \note Calling this method removes the resource from the managing /// instance, so it will not be automatically closed. resource_type detach() STLSOFT_NOEXCEPT { @@ -834,7 +834,7 @@ class scoped_handle /// Detaches the resource, and returns it to the caller. /// - /// \remarks Calling this method removes the resource from the managing + /// \note Calling this method removes the resource from the managing /// instance, so it will not be automatically closed. resource_type detach() STLSOFT_NOEXCEPT { diff --git a/include/stlsoft/stlsoft.h b/include/stlsoft/stlsoft.h index 51d82f0c..eaffb4b3 100644 --- a/include/stlsoft/stlsoft.h +++ b/include/stlsoft/stlsoft.h @@ -5,7 +5,7 @@ * and platform discriminations, and definitions of types. * * Created: 15th January 2002 - * Updated: 10th October 2026 + * Updated: 18th October 2026 * * Home: http://stlsoft.org/ * @@ -55,8 +55,8 @@ #ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION # define STLSOFT_VER_STLSOFT_H_STLSOFT_MAJOR 3 # define STLSOFT_VER_STLSOFT_H_STLSOFT_MINOR 57 -# define STLSOFT_VER_STLSOFT_H_STLSOFT_REVISION 20 -# define STLSOFT_VER_STLSOFT_H_STLSOFT_EDIT 608 +# define STLSOFT_VER_STLSOFT_H_STLSOFT_REVISION 21 +# define STLSOFT_VER_STLSOFT_H_STLSOFT_EDIT 610 #else /* ? STLSOFT_DOCUMENTATION_SKIP_SECTION */ /* # include "./internal/doxygen_defs.h" */ #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -423,12 +423,13 @@ # define _STLSOFT_VER_1_11_1_RC6 0x010b01c6 /*!< Version 1.11.1 rc 6 (21st September 2026) */ # define _STLSOFT_VER_1_11_1_RC7 0x010B01C7 /*!< Version 1.11.1 rc 7 (30th September 2026) */ # define _STLSOFT_VER_1_11_1_RC8 0x010B01C8 /*!< Version 1.11.1 rc 8 (10th October 2026) */ +# define _STLSOFT_VER_1_11_1_RC9 0x010B01C9 /*!< Version 1.11.1 rc 9 (18th October 2026) */ #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ #define _STLSOFT_VER_MAJOR 1 #define _STLSOFT_VER_MINOR 11 #define _STLSOFT_VER_PATCH 1 -#define _STLSOFT_VER_ALPHABETA 0xC8 +#define _STLSOFT_VER_ALPHABETA 0xC9 #define _STLSOFT_VER \ (0\ diff --git a/include/stlsoft/string/char_traits.hpp b/include/stlsoft/string/char_traits.hpp index b7a81bbf..8c645f0b 100644 --- a/include/stlsoft/string/char_traits.hpp +++ b/include/stlsoft/string/char_traits.hpp @@ -4,7 +4,7 @@ * Purpose: char_traits classes. * * Created: 19th November 1998 - * Updated: 29th September 2026 + * Updated: 15th October 2026 * * Home: http://stlsoft.org/ * @@ -55,7 +55,7 @@ # define STLSOFT_VER_STLSOFT_STRING_HPP_CHAR_TRAITS_MAJOR 4 # define STLSOFT_VER_STLSOFT_STRING_HPP_CHAR_TRAITS_MINOR 3 # define STLSOFT_VER_STLSOFT_STRING_HPP_CHAR_TRAITS_REVISION 3 -# define STLSOFT_VER_STLSOFT_STRING_HPP_CHAR_TRAITS_EDIT 102 +# define STLSOFT_VER_STLSOFT_STRING_HPP_CHAR_TRAITS_EDIT 103 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -266,7 +266,7 @@ struct stlsoft_char_traits } /// Compares up to \c cch characters of \c s1 with \c, stopping at the - /// first difference or until the NUL-terminator is reached + /// first difference or until the NUL character is reached. /// /// \param s1 The first string to compare /// \param s2 The second string to compare diff --git a/include/stlsoft/string/copy_functions.h b/include/stlsoft/string/copy_functions.h index 313a0105..fdfa54bf 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: 13th 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 7 +# define STLSOFT_VER_STLSOFT_STRING_H_COPY_FUNCTIONS_EDIT 18 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -109,12 +109,12 @@ namespace stlsoft * * \note Always applies a terminating nul character if cchDest > cchSrc * - * \pre (0 == cchDest || NULL != dest); - * \pre (0 == cchSrc || NULL != src); + * \pre 0 == cchDest || nullptr != dest + * \pre 0 == cchSrc || nullptr != src */ 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 @@ -185,12 +185,12 @@ STLSoft_C_string_copy_w( * * \note Always applies a terminating nul character if cchDest > 0 * - * \pre (0 == cchDest || NULL != dest); - * \pre (0 == cchSrc || NULL != src); + * \pre 0 == cchDest || nullptr != dest + * \pre 0 == cchSrc || nullptr != src */ 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 */ diff --git a/include/stlsoft/string/cstring_maker.hpp b/include/stlsoft/string/cstring_maker.hpp index 08a2fcb2..37ca28e3 100644 --- a/include/stlsoft/string/cstring_maker.hpp +++ b/include/stlsoft/string/cstring_maker.hpp @@ -4,11 +4,11 @@ * Purpose: Simple utility class for creating (constant) C-strings. * * Created: 14th May 2004 - * Updated: 20th March 2025 + * Updated: 15th 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) 2004-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -54,7 +54,7 @@ # define STLSOFT_VER_STLSOFT_STRING_HPP_CSTRING_MAKER_MAJOR 5 # define STLSOFT_VER_STLSOFT_STRING_HPP_CSTRING_MAKER_MINOR 0 # define STLSOFT_VER_STLSOFT_STRING_HPP_CSTRING_MAKER_REVISION 6 -# define STLSOFT_VER_STLSOFT_STRING_HPP_CSTRING_MAKER_EDIT 68 +# define STLSOFT_VER_STLSOFT_STRING_HPP_CSTRING_MAKER_EDIT 69 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -194,7 +194,7 @@ struct cstring_maker public: /// Allocates storage for writing into a string, optionally initialising /// - /// \note Includes space for a nul-terminator character + /// \note Includes space for a NUL character character. /// /// \param s The optional string to be copied into the block. May be /// \c null; if not, must be of at least \c cch characters long @@ -254,7 +254,7 @@ struct cstring_maker /// Allocates storage for writing into a string, optionally /// initialising, or returns \c nullptr if \c cch is 0 /// - /// \note Includes space for a nul-terminator character + /// \note Includes space for a NUL character character. /// /// \param s The optional string to be copied into the block. May be /// \c null; if not, must be of at least \c cch characters long diff --git a/include/stlsoft/string/shim_string.hpp b/include/stlsoft/string/shim_string.hpp index 6e330cb1..5b1c0bbd 100644 --- a/include/stlsoft/string/shim_string.hpp +++ b/include/stlsoft/string/shim_string.hpp @@ -4,13 +4,13 @@ * Purpose: Contains the basic_shim_string template class. * * Created: 9th July 2004 - * Updated: 20th March 2025 + * Updated: 15th October 2026 * * Thanks: Dimitri Kaparis, for spotting a typo in the string access shims. * * 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) 2004-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -57,7 +57,7 @@ # define STLSOFT_VER_STLSOFT_STRING_HPP_SHIM_STRING_MAJOR 3 # define STLSOFT_VER_STLSOFT_STRING_HPP_SHIM_STRING_MINOR 7 # define STLSOFT_VER_STLSOFT_STRING_HPP_SHIM_STRING_REVISION 4 -# define STLSOFT_VER_STLSOFT_STRING_HPP_SHIM_STRING_EDIT 74 +# define STLSOFT_VER_STLSOFT_STRING_HPP_SHIM_STRING_EDIT 76 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -199,7 +199,7 @@ class basic_shim_string public: /// Creates an empty instance /// - /// \remarks the 0th element is assigned the nul terminator + /// \note the 0th element is assigned the NUL character. basic_shim_string() : m_len(0) , m_buffer(1) @@ -214,8 +214,8 @@ class basic_shim_string /// Creates an instance with the given number of characters /// - /// \remarks the 0th and nth elements are assigned - /// the nul terminator + /// \note the 0th and nth elements are assigned the + /// NUL character. ss_explicit_k basic_shim_string( size_type n @@ -235,7 +235,7 @@ class basic_shim_string /// Creates an instance containing the given number of characters from /// the given string /// - /// \remarks the nth element is assigned the nul terminator + /// \note the nth element is assigned the NUL character. basic_shim_string( char_type const* s , size_type n @@ -379,8 +379,7 @@ class basic_shim_string /// Truncates the string to the given length /// - /// \pre The length specified must be less than or equal to the current - /// length + /// \pre n <= size() void truncate(size_type n) { STLSOFT_COVER_MARK_LINE(); @@ -422,7 +421,7 @@ class basic_shim_string } /// Changes the size of the storage to at least the given size, and - /// applies the nul-terminator + /// applies the NUL character. /// /// \note No elements in the range [0, n) are affected, which means that /// the string may contain embedded nuls. It is entirely the user's diff --git a/include/stlsoft/string/simple_string.hpp b/include/stlsoft/string/simple_string.hpp index b9c2c132..2b688549 100644 --- a/include/stlsoft/string/simple_string.hpp +++ b/include/stlsoft/string/simple_string.hpp @@ -4,7 +4,7 @@ * Purpose: basic_simple_string class template. * * Created: 19th March 1993 - * Updated: 29th September 2026 + * Updated: 15th October 2026 * * Home: http://stlsoft.org/ * @@ -55,7 +55,7 @@ # define STLSOFT_VER_STLSOFT_STRING_HPP_SIMPLE_STRING_MAJOR 5 # define STLSOFT_VER_STLSOFT_STRING_HPP_SIMPLE_STRING_MINOR 0 # define STLSOFT_VER_STLSOFT_STRING_HPP_SIMPLE_STRING_REVISION 1 -# define STLSOFT_VER_STLSOFT_STRING_HPP_SIMPLE_STRING_EDIT 287 +# define STLSOFT_VER_STLSOFT_STRING_HPP_SIMPLE_STRING_EDIT 288 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -1747,7 +1747,7 @@ basic_simple_string::alloc_buffer_( ss_size_t const members = (STLSOFT_RAW_OFFSETOF(string_buffer, contents) + (sizeof(char_type) - 1)) / sizeof(char_type); - capacity += 1; // for NUL-terminator + capacity += 1; // for NUL character capacity += members; // include the internal members. capacity = (alloc_quantum + capacity) & ~alloc_quantum; // round up to (alloc_quantum + 1) @@ -3036,7 +3036,7 @@ inline ss_typename_type_ret_k basic_simple_string::const_reference basic_simple_string::operator [](ss_typename_type_k basic_simple_string::size_type index) const STLSOFT_NOEXCEPT { - STLSOFT_MESSAGE_ASSERT("index access out of range in simple_string", index < size() + 1); // Valid to return (const) reference to NUL-terminator + STLSOFT_MESSAGE_ASSERT("index access out of range in simple_string", index < size() + 1); // Valid to return (const) reference to NUL character STLSOFT_ASSERT(is_valid()); diff --git a/include/stlsoft/string/static_string.hpp b/include/stlsoft/string/static_string.hpp index 550ec376..51e7327f 100644 --- a/include/stlsoft/string/static_string.hpp +++ b/include/stlsoft/string/static_string.hpp @@ -4,7 +4,7 @@ * Purpose: basic_static_string class template. * * Created: 11th June 1994 - * Updated: 31st July 2026 + * Updated: 15th October 2026 * * Thanks: To Cláudio Albuquerque for supplying the pop_back() member. * @@ -57,7 +57,7 @@ # define STLSOFT_VER_STLSOFT_STRING_HPP_STATIC_STRING_MAJOR 5 # define STLSOFT_VER_STLSOFT_STRING_HPP_STATIC_STRING_MINOR 5 # define STLSOFT_VER_STLSOFT_STRING_HPP_STATIC_STRING_REVISION 3 -# define STLSOFT_VER_STLSOFT_STRING_HPP_STATIC_STRING_EDIT 233 +# define STLSOFT_VER_STLSOFT_STRING_HPP_STATIC_STRING_EDIT 234 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -2434,7 +2434,7 @@ inline ss_typename_type_ret_k basic_static_string::const_reference basic_static_string::operator [](ss_typename_type_k basic_static_string::size_type index) const STLSOFT_NOEXCEPT { - STLSOFT_MESSAGE_ASSERT("index access out of range in static_string", index < size() + 1); // Valid to return (const) reference to nul-terminator + STLSOFT_MESSAGE_ASSERT("index access out of range in static_string", index < size() + 1); // Valid to return (const) reference to NUL character STLSOFT_ASSERT(is_valid()); diff --git a/include/stlsoft/system/environment/functions.h b/include/stlsoft/system/environment/functions.h index ce665a09..d5207bd2 100644 --- a/include/stlsoft/system/environment/functions.h +++ b/include/stlsoft/system/environment/functions.h @@ -4,7 +4,7 @@ * Purpose: Environment functions. * * Created: 4th March 2011 - * Updated: 8th October 2026 + * Updated: 11th October 2026 * * Home: http://stlsoft.org/ * @@ -54,7 +54,7 @@ # define STLSOFT_VER_STLSOFT_SYSTEM_ENVIRONMENT_H_FUNCTIONS_MAJOR 1 # define STLSOFT_VER_STLSOFT_SYSTEM_ENVIRONMENT_H_FUNCTIONS_MINOR 1 # define STLSOFT_VER_STLSOFT_SYSTEM_ENVIRONMENT_H_FUNCTIONS_REVISION 0 -# define STLSOFT_VER_STLSOFT_SYSTEM_ENVIRONMENT_H_FUNCTIONS_EDIT 18 +# define STLSOFT_VER_STLSOFT_SYSTEM_ENVIRONMENT_H_FUNCTIONS_EDIT 20 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -112,7 +112,7 @@ namespace stlsoft * \retval 0 The environment variable does not exist; * \retval !0 The environment variable does exist; * - * \pre NULL != name; + * \pre nullptr != name */ STLSOFT_INLINE ss_truthy_t @@ -184,8 +184,8 @@ stlsoft_C_environment_variable_exists_a( * ERANGE; * \retval !0 The value was parsed and written through \c result; * - * \pre NULL != name; - * \pre NULL != result; + * \pre nullptr != name + * \pre nullptr != result * * \note Interpreted with base 0, as with strtoll(): optional leading * whitespace, an optional sign, then decimal, octal (leading 0), or diff --git a/include/stlsoft/system/environment/functions.hpp b/include/stlsoft/system/environment/functions.hpp index 541830f4..b46620c4 100644 --- a/include/stlsoft/system/environment/functions.hpp +++ b/include/stlsoft/system/environment/functions.hpp @@ -4,7 +4,7 @@ * Purpose: Environment functions. * * Created: 31st October 2019 - * Updated: 28th September 2026 + * Updated: 11th October 2026 * * Home: http://stlsoft.org/ * @@ -54,7 +54,7 @@ # define STLSOFT_VER_STLSOFT_SYSTEM_ENVIRONMENT_HPP_FUNCTIONS_MAJOR 1 # define STLSOFT_VER_STLSOFT_SYSTEM_ENVIRONMENT_HPP_FUNCTIONS_MINOR 0 # define STLSOFT_VER_STLSOFT_SYSTEM_ENVIRONMENT_HPP_FUNCTIONS_REVISION 2 -# define STLSOFT_VER_STLSOFT_SYSTEM_ENVIRONMENT_HPP_FUNCTIONS_EDIT 5 +# define STLSOFT_VER_STLSOFT_SYSTEM_ENVIRONMENT_HPP_FUNCTIONS_EDIT 7 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -127,7 +127,7 @@ struct ximpl_stlsoft_environment_functions_hpp_ * \retval 0 The environment variable does not exist * \retval !0 The environment variable does exist * - * \pre (NULL != name) + * \pre nullptr != name */ template inline diff --git a/include/stlsoft/time/fast_strftime.hpp b/include/stlsoft/time/fast_strftime.hpp index c5b3e956..2d67e1d1 100644 --- a/include/stlsoft/time/fast_strftime.hpp +++ b/include/stlsoft/time/fast_strftime.hpp @@ -4,11 +4,11 @@ * Purpose: Efficient drop-in replacement for strftime(). * * Created: 23rd December 2018 - * Updated: 20th March 2025 + * Updated: 15th 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) 2018-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -55,7 +55,7 @@ # define STLSOFT_VER_STLSOFT_TIME_HPP_FAST_STRFTIME_MAJOR 1 # define STLSOFT_VER_STLSOFT_TIME_HPP_FAST_STRFTIME_MINOR 3 # define STLSOFT_VER_STLSOFT_TIME_HPP_FAST_STRFTIME_REVISION 1 -# define STLSOFT_VER_STLSOFT_TIME_HPP_FAST_STRFTIME_EDIT 17 +# define STLSOFT_VER_STLSOFT_TIME_HPP_FAST_STRFTIME_EDIT 18 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -1095,7 +1095,7 @@ fast_strftime_( * \pre nullptr != tm * \pre 0 == cchDest || nullptr != dest * - * \remarks The following formatting codes (supported by VC++ 6) are supported: + * \note The following formatting codes (supported by VC++ 6) are supported: * \li \c \% - a percent sign * \li \c a - weekday name (abbreviated) * \li \c A - weekday name (full) @@ -1116,7 +1116,8 @@ fast_strftime_( * \li \c y - year without century, as decimal number [0-99] * \li \c Y - year with century, as decimal number * - * \remarks The following formatting codes (supported by VC++ 10) are supported: + * \note The following formatting codes (supported by VC++ 10) are + * supported: * \li \c D - equivalent to "%m/%d/%y" * \li \c e - day of month as space-padded decimal number [ 1-31] * \li \c F - equivalent to "%Y-%m-%d" @@ -1126,7 +1127,7 @@ fast_strftime_( * \li \c T - equivalent to "%H:%M:%S" * \li \c u - weekday, with Monday as 1, as decimal number [1-7] * - * \remarks The following formatting codes are not supported + * \note The following formatting codes are not supported * \li \c c - * \li \c g - * \li \c G - @@ -1138,7 +1139,7 @@ fast_strftime_( * \li \c z - * \li \c Z - * - * \remarks The following supported codes are modified by the '#' + * \note The following supported codes are modified by the '#' * character - e.g. "%#d" - to remove leading 0, if any: * \li \c d * \li \c D @@ -1158,7 +1159,7 @@ fast_strftime_( * \li \c y * \li \c Y * - * \remarks The following supported codes are unmodified by the '#' + * \note The following supported codes are unmodified by the '#' * character - e.g. "%#a": * \li \c \% * \li \c a diff --git a/include/stlsoft/util/exception_string.hpp b/include/stlsoft/util/exception_string.hpp index 0dbe9d21..c85a7681 100644 --- a/include/stlsoft/util/exception_string.hpp +++ b/include/stlsoft/util/exception_string.hpp @@ -4,11 +4,11 @@ * Purpose: Contains the exception_string limited functionality string class. * * Created: 26th December 2005 - * Updated: 20th March 2025 + * Updated: 15th 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) 2005-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -54,7 +54,7 @@ # define STLSOFT_VER_STLSOFT_UTIL_HPP_EXCEPTION_STRING_MAJOR 1 # define STLSOFT_VER_STLSOFT_UTIL_HPP_EXCEPTION_STRING_MINOR 4 # define STLSOFT_VER_STLSOFT_UTIL_HPP_EXCEPTION_STRING_REVISION 10 -# define STLSOFT_VER_STLSOFT_UTIL_HPP_EXCEPTION_STRING_EDIT 39 +# define STLSOFT_VER_STLSOFT_UTIL_HPP_EXCEPTION_STRING_EDIT 40 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -196,8 +196,8 @@ class exception_string /// /// \param n The length to which the string's contents will be truncated /// - /// \remarks This method is a no-op if the length specified is greater - /// than the current length + /// \note This method is a no-op if the length specified is greater than + /// the current length. void truncate(size_type n) { if (n < m_message.size() - 1) diff --git a/include/stlsoft/util/exception_string_creator.hpp b/include/stlsoft/util/exception_string_creator.hpp index b7bc3983..103e220c 100644 --- a/include/stlsoft/util/exception_string_creator.hpp +++ b/include/stlsoft/util/exception_string_creator.hpp @@ -4,11 +4,11 @@ * Purpose: Contains the exception_string_creator class. * * Created: 25th May 2010 - * Updated: 20th March 2025 + * Updated: 15th 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) 2010-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -54,7 +54,7 @@ # define STLSOFT_VER_STLSOFT_UTIL_HPP_EXCEPTION_STRING_CREATOR_MAJOR 1 # define STLSOFT_VER_STLSOFT_UTIL_HPP_EXCEPTION_STRING_CREATOR_MINOR 1 # define STLSOFT_VER_STLSOFT_UTIL_HPP_EXCEPTION_STRING_CREATOR_REVISION 11 -# define STLSOFT_VER_STLSOFT_UTIL_HPP_EXCEPTION_STRING_CREATOR_EDIT 32 +# define STLSOFT_VER_STLSOFT_UTIL_HPP_EXCEPTION_STRING_CREATOR_EDIT 34 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -211,8 +211,8 @@ class basic_exception_string_creator /// /// \param n The length to which the string's contents will be truncated /// - /// \remarks This method is a no-op if the length specified is greater - /// than the current length + /// \note This method is a no-op if the length specified is greater than + /// the current length. class_type& truncate(size_type n) { if (n < m_message.size()) @@ -477,7 +477,7 @@ class basic_exception_string_creator if (0 == err) { - // wcstombs_s() always included nul-terminator in count + // wcstombs_s() always included NUL character in count --numConverted; } else diff --git a/include/stlsoft/util/must_init.hpp b/include/stlsoft/util/must_init.hpp index 38639f38..b2bf656f 100644 --- a/include/stlsoft/util/must_init.hpp +++ b/include/stlsoft/util/must_init.hpp @@ -9,11 +9,11 @@ * coverage. * * Created: 18th June 2006 - * Updated: 20th March 2025 + * Updated: 15th 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) 2006-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -59,7 +59,7 @@ # define STLSOFT_VER_STLSOFT_UTIL_HPP_MUST_INIT_MAJOR 1 # define STLSOFT_VER_STLSOFT_UTIL_HPP_MUST_INIT_MINOR 1 # define STLSOFT_VER_STLSOFT_UTIL_HPP_MUST_INIT_REVISION 9 -# define STLSOFT_VER_STLSOFT_UTIL_HPP_MUST_INIT_EDIT 32 +# define STLSOFT_VER_STLSOFT_UTIL_HPP_MUST_INIT_EDIT 33 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -192,7 +192,7 @@ class must_init_builtin public: /// The underlying value /// - /// \remarks Since the purpose of must_init is to guard against a + /// \note Since the purpose of must_init is to guard against a /// forgotten initialisation in composition involving fundamental /// types, rather than encapsulation in any wider sense, the member /// value is public, to simplify manipulation of the actual value by @@ -274,7 +274,7 @@ class must_init public: /// The underlying value /// - /// \remarks Since the purpose of must_init is to guard against a + /// \note Since the purpose of must_init is to guard against a /// forgotten initialisation in composition involving fundamental /// types, rather than encapsulation in any wider sense, the member /// value is public, to simplify manipulation of the actual value by diff --git a/include/stlsoft/util/printf_traits.hpp b/include/stlsoft/util/printf_traits.hpp index a900c81a..56f1e90d 100644 --- a/include/stlsoft/util/printf_traits.hpp +++ b/include/stlsoft/util/printf_traits.hpp @@ -4,11 +4,11 @@ * Purpose: printf_traits classes. * * Created: 16th January 2002 - * Updated: 20th March 2025 + * Updated: 15th 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) 2002-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -55,7 +55,7 @@ # define STLSOFT_VER_STLSOFT_UTIL_HPP_PRINTF_TRAITS_MAJOR 5 # define STLSOFT_VER_STLSOFT_UTIL_HPP_PRINTF_TRAITS_MINOR 0 # define STLSOFT_VER_STLSOFT_UTIL_HPP_PRINTF_TRAITS_REVISION 5 -# define STLSOFT_VER_STLSOFT_UTIL_HPP_PRINTF_TRAITS_EDIT 75 +# define STLSOFT_VER_STLSOFT_UTIL_HPP_PRINTF_TRAITS_EDIT 76 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -162,7 +162,7 @@ namespace stlsoft * printf_traits is a traits class for acquiring enum values representing the * lengths, when expressed in string form, of the minimum and maximum values of * the type, and the maximum of the two. The lengths are inclusive of the - * null terminator. + * NUL character. * \code assert(stlsoft::printf_traits::size_min == 6); diff --git a/include/stlsoft/util/true_typedef.hpp b/include/stlsoft/util/true_typedef.hpp index 156ce2ae..6f8ed407 100644 --- a/include/stlsoft/util/true_typedef.hpp +++ b/include/stlsoft/util/true_typedef.hpp @@ -4,11 +4,11 @@ * Purpose: Contains the true_typedef class template. * * Created: 16th January 2002 - * Updated: 21st March 2025 + * Updated: 15th 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) 2002-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -54,7 +54,7 @@ # define STLSOFT_VER_STLSOFT_UTIL_HPP_TRUE_TYPEDEF_MAJOR 4 # define STLSOFT_VER_STLSOFT_UTIL_HPP_TRUE_TYPEDEF_MINOR 3 # define STLSOFT_VER_STLSOFT_UTIL_HPP_TRUE_TYPEDEF_REVISION 1 -# define STLSOFT_VER_STLSOFT_UTIL_HPP_TRUE_TYPEDEF_EDIT 97 +# define STLSOFT_VER_STLSOFT_UTIL_HPP_TRUE_TYPEDEF_EDIT 98 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -123,8 +123,8 @@ namespace stlsoft * \tparam T The base type, e.g. \c int, \c std::wstring * \tparam U The unique type, usually created by using STLSOFT_GEN_OPAQUE() * - * \remarks U is the unique type, and is usually a type generated by the - * STLSOFT_GEN_OPAQUE() macro, as in: + * \note U is the unique type, and is usually a type generated by the + * STLSOFT_GEN_OPAQUE() macro, as in: \code STLSOFT_GEN_OPAQUE(h_uniquelong_tt) typedef true_typedef uniquelong_tt; diff --git a/include/unixstl/diagnostics/stopwatch.hpp b/include/unixstl/diagnostics/stopwatch.hpp index 708ca450..a1c5a1c9 100644 --- a/include/unixstl/diagnostics/stopwatch.hpp +++ b/include/unixstl/diagnostics/stopwatch.hpp @@ -4,11 +4,11 @@ * Purpose: stopwatch class. * * Created: 16th January 2002 - * Updated: 28th April 2025 + * Updated: 15th 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) 2002-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -55,7 +55,7 @@ # define UNIXSTL_VER_UNIXSTL_DIAGNOSTICS_HPP_STOPWATCH_MAJOR 5 # define UNIXSTL_VER_UNIXSTL_DIAGNOSTICS_HPP_STOPWATCH_MINOR 2 # define UNIXSTL_VER_UNIXSTL_DIAGNOSTICS_HPP_STOPWATCH_REVISION 3 -# define UNIXSTL_VER_UNIXSTL_DIAGNOSTICS_HPP_STOPWATCH_EDIT 84 +# define UNIXSTL_VER_UNIXSTL_DIAGNOSTICS_HPP_STOPWATCH_EDIT 85 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -150,8 +150,8 @@ class stopwatch void stop(); /// Ends the current measurement period and start the next /// - /// \remarks This is equivalent to an atomic invocation of stop() and - /// start() + /// \note This is equivalent to an atomic invocation of stop() and + /// start(). void restart(); diff --git a/include/unixstl/filesystem/filesystem_traits.hpp b/include/unixstl/filesystem/filesystem_traits.hpp index c392cdd0..a839e6c3 100644 --- a/include/unixstl/filesystem/filesystem_traits.hpp +++ b/include/unixstl/filesystem/filesystem_traits.hpp @@ -5,7 +5,7 @@ * Unicode specialisations thereof. * * Created: 15th November 2002 - * Updated: 8th October 2026 + * Updated: 15th October 2026 * * Thanks: To Sergey Nikulov, for spotting a preprocessor typo that broke * GCC -pedantic; to Michal Makowski and Zar Eindl for reporting @@ -58,10 +58,10 @@ #define UNIXSTL_INCL_UNIXSTL_FILESYSTEM_HPP_FILESYSTEM_TRAITS #ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION -# define UNIXSTL_VER_UNIXSTL_FILESYSTEM_HPP_FILESYSTEM_TRAITS_MAJOR 4 -# define UNIXSTL_VER_UNIXSTL_FILESYSTEM_HPP_FILESYSTEM_TRAITS_MINOR 17 +# define UNIXSTL_VER_UNIXSTL_FILESYSTEM_HPP_FILESYSTEM_TRAITS_MAJOR 5 +# define UNIXSTL_VER_UNIXSTL_FILESYSTEM_HPP_FILESYSTEM_TRAITS_MINOR 0 # define UNIXSTL_VER_UNIXSTL_FILESYSTEM_HPP_FILESYSTEM_TRAITS_REVISION 1 -# define UNIXSTL_VER_UNIXSTL_FILESYSTEM_HPP_FILESYSTEM_TRAITS_EDIT 190 +# define UNIXSTL_VER_UNIXSTL_FILESYSTEM_HPP_FILESYSTEM_TRAITS_EDIT 193 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -109,6 +109,7 @@ #ifdef _WIN32 # include +# include #endif /* _WIN32 */ #ifndef STLSOFT_INCL_H_ERRNO # define STLSOFT_INCL_H_ERRNO @@ -332,7 +333,7 @@ struct filesystem_traits /// \pre nullptr != dir /// /// \note \c dir is assumed to contain space for an additional - /// character (if required) and NUL-terminator + /// character (if required) and NUL character. /// /// \see \link #path_name_separator path_name_separator() \endlink static @@ -734,7 +735,7 @@ struct filesystem_traits /// Resets the file-system search to the first entry, such that the /// next call to read_dir() returns the first entry /// - /// \pre NULL != h + /// \pre nullptr != h static void rewind_dir(DIR* h); /// Closes the handle of the file-system search static void close_dir(DIR* h); @@ -868,7 +869,7 @@ struct filesystem_traits static large_size_type get_file_size(stat_data_type const& sd); /// Gets the size of the file /// - /// \pre (nullptr != psd) + /// \pre nullptr != psd static large_size_type get_file_size(stat_data_type const* psd); #else /* ? STLSOFT_CF_64BIT_INT_SUPPORT */ private: @@ -3010,7 +3011,21 @@ struct filesystem_traits find_last_path_name_separator( char_type const* path ) - ; + { + UNIXSTL_ASSERT(NULL != path); + + char_type const* last = NULL; + + for (; L'\0' != *path; ++path) + { + if (is_path_name_separator(*path)) + { + last = path; + } + } + + return last; + } static char_type const* @@ -3018,14 +3033,43 @@ struct filesystem_traits char_type const* path , size_t len ) - ; + { + UNIXSTL_ASSERT(0 == len || NULL != path); + + if (0 == len) + { + return NULL; + } + + for (path += (len - 1); 0 != len; --len, --path) + { + if (is_path_name_separator(*path)) + { + return path; + } + } + + return NULL; + } static char_type const* find_next_path_name_separator( char_type const* path ) - ; + { + UNIXSTL_ASSERT(NULL != path); + + for (; L'\0' != *path; ++path) + { + if (is_path_name_separator(*path)) + { + return path; + } + } + + return NULL; + } static char_type const* @@ -3033,7 +3077,19 @@ struct filesystem_traits char_type const* path , size_t len ) - ; + { + UNIXSTL_ASSERT(0 == len || NULL != path); + + for (; 0 != len; --len, ++path) + { + if (is_path_name_separator(*path)) + { + return path; + } + } + + return NULL; + } static bool_type is_dots(char_type const* dir) { @@ -3061,31 +3117,153 @@ struct filesystem_traits } static bool_type is_path_rooted(char_type const* path) - ; + { + UNIXSTL_ASSERT(NULL != path); +#ifdef _WIN32 + + if (L'\\' == path[0] && + L'\\' == path[1]) + { + return true; + } + + if (0 != ::iswalpha(path[0]) && + L':' == path[1]) + { + path += 2; + } +#endif /* _WIN32 */ + + return is_path_name_separator(*path); + } static bool_type is_path_rooted( char_type const* path , size_t len ) - ; + { + UNIXSTL_ASSERT(NULL != path); +#ifdef _WIN32 + + if (len >= 2) + { + if (L'\\' == path[0] && + L'\\' == path[1]) + { + return true; + } + } + + if (len >= 2) + { + if (0 != ::iswalpha(path[0]) && + L':' == path[1]) + { + path += 2; + len -= 2; + } + } +#endif /* _WIN32 */ + + return 0 != len && is_path_name_separator(*path); + } static bool_type is_path_absolute(char_type const* path) - ; + { + UNIXSTL_ASSERT(NULL != path); +#ifdef _WIN32 + + if (is_path_UNC(path)) + { + return true; + } + if (0 != ::iswalpha(path[0]) && + L':' == path[1] && + is_path_name_separator(path[2])) + { + return true; + } + + return false; +#else /* ? _WIN32 */ + + return is_path_rooted(path); +#endif /* _WIN32 */ + } static bool_type is_path_absolute( char_type const* path , size_t len ) - ; + { + if (0 == len) + { + return false; + } +#ifdef _WIN32 + + if (is_path_UNC(path, len)) + { + return true; + } + if (len >= 3) + { + if (0 != ::iswalpha(path[0]) && + L':' == path[1] && + is_path_name_separator(path[2])) + { + return true; + } + } + + return false; +#else /* ? _WIN32 */ + + return is_path_rooted(path, len); +#endif /* _WIN32 */ + } static bool_type is_path_UNC(char_type const* path) - ; + { + UNIXSTL_ASSERT(NULL != path); +#ifdef _WIN32 + + size_type const len = str_len(path); + + return is_path_UNC(path, len); +#else /* ? _WIN32 */ + + STLSOFT_SUPPRESS_UNUSED(path); + + return false; +#endif /* _WIN32 */ + } static bool_type is_path_UNC( char_type const* path , size_t len ) - ; + { +#ifdef _WIN32 + + switch (len) + { + case 0: + case 1: + + return false; + default: + + return L'\\' == path[0] && L'\\' == path[1]; + } +#else /* ? _WIN32 */ + + STLSOFT_SUPPRESS_UNUSED(path); + STLSOFT_SUPPRESS_UNUSED(len); + + return false; +#endif /* _WIN32 */ + } static bool_type is_path_name_separator(char_type ch) { @@ -3120,6 +3298,10 @@ struct filesystem_traits return filesystem_traits_::path_max(); } + /* The following path-resolve, cwd, and dir-enumeration members remain + * declared (for API / metaprogramming compatibility) pending a finished + * conversion-policy implementation for the whole group. + */ static size_type get_full_path_name( diff --git a/include/unixstl/filesystem/path.hpp b/include/unixstl/filesystem/path.hpp index b8b2f94f..c8c8c89d 100644 --- a/include/unixstl/filesystem/path.hpp +++ b/include/unixstl/filesystem/path.hpp @@ -4,14 +4,14 @@ * Purpose: Simple class that represents a path. * * Created: 1st May 1993 - * Updated: 20th March 2025 + * Updated: 15th October 2026 * * Thanks: Pablo Aguilar for reporting defect in push_ext() (which doesn't * work for wide-string builds). * * 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) 1993-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -57,7 +57,7 @@ # define UNIXSTL_VER_UNIXSTL_FILESYSTEM_HPP_PATH_MAJOR 7 # define UNIXSTL_VER_UNIXSTL_FILESYSTEM_HPP_PATH_MINOR 1 # define UNIXSTL_VER_UNIXSTL_FILESYSTEM_HPP_PATH_REVISION 8 -# define UNIXSTL_VER_UNIXSTL_FILESYSTEM_HPP_PATH_EDIT 282 +# define UNIXSTL_VER_UNIXSTL_FILESYSTEM_HPP_PATH_EDIT 283 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -417,7 +417,7 @@ class basic_path size_type length() const STLSOFT_NOEXCEPT; /// Returns the length of the converted path /// - /// \remarks Equivalent to length() + /// \note Equivalent to length(). size_type size() const STLSOFT_NOEXCEPT; /// The maximum possible length of a path static size_type max_size() STLSOFT_NOEXCEPT; @@ -465,7 +465,7 @@ class basic_path /// Evaluates whether the two instances hold strings that refer /// to the same file-system entity. /// - /// \remarks See \link winstl::basic_path::equivalent(C const* ) equivalent()\endlink for an example. + /// \note See \link winstl::basic_path::equivalent(C const* ) equivalent()\endlink for an example. /// /// \note The string comparison is case-insensitive. bool_type equivalent(class_type const& rhs) const STLSOFT_NOEXCEPT; 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/unixstl/process/functions.h b/include/unixstl/process/functions.h index ddf65e78..530b2f49 100644 --- a/include/unixstl/process/functions.h +++ b/include/unixstl/process/functions.h @@ -4,7 +4,7 @@ * Purpose: Process functions. * * Created: 8th October 2026 - * Updated: 8th October 2026 + * Updated: 15th October 2026 * * Home: http://stlsoft.org/ * @@ -51,9 +51,9 @@ #ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION # define UNIXSTL_VER_UNIXSTL_PROCESS_H_FUNCTIONS_MAJOR 1 -# define UNIXSTL_VER_UNIXSTL_PROCESS_H_FUNCTIONS_MINOR 0 -# define UNIXSTL_VER_UNIXSTL_PROCESS_H_FUNCTIONS_REVISION 1 -# define UNIXSTL_VER_UNIXSTL_PROCESS_H_FUNCTIONS_EDIT 1 +# define UNIXSTL_VER_UNIXSTL_PROCESS_H_FUNCTIONS_MINOR 1 +# define UNIXSTL_VER_UNIXSTL_PROCESS_H_FUNCTIONS_REVISION 3 +# define UNIXSTL_VER_UNIXSTL_PROCESS_H_FUNCTIONS_EDIT 4 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -68,17 +68,78 @@ # pragma message(__FILE__) #endif /* STLSOFT_TRACE_INCLUDE */ +#ifndef STLSOFT_INCL_STLSOFT_MEMORY_H_AUTO_BUFFER +# include +#endif /* !STLSOFT_INCL_STLSOFT_MEMORY_H_AUTO_BUFFER */ + +#ifndef STLSOFT_INCL_H_ERRNO +# define STLSOFT_INCL_H_ERRNO +# include +#endif /* !STLSOFT_INCL_H_ERRNO */ +#ifndef STLSOFT_INCL_H_LIMITS +# define STLSOFT_INCL_H_LIMITS +# include +#endif /* !STLSOFT_INCL_H_LIMITS */ +#ifndef STLSOFT_INCL_H_STDLIB +# define STLSOFT_INCL_H_STDLIB +# include +#endif /* !STLSOFT_INCL_H_STDLIB */ +#ifndef STLSOFT_INCL_H_STRING +# define STLSOFT_INCL_H_STRING +# include +#endif /* !STLSOFT_INCL_H_STRING */ + #if 0 -#elif defined(_WIN32) &&\ - ( 0 ||\ - defined(STLSOFT_COMPILER_IS_MSVC) ||\ - defined(STLSOFT_COMPILER_IS_INTEL) ||\ - 0) +#elif defined(_WIN32) + +# ifndef WINSTL_INCL_WINSTL_API_external_h_DynamicLinkLibrary +# include +# endif /* !WINSTL_INCL_WINSTL_API_external_h_DynamicLinkLibrary */ # ifndef STLSOFT_INCL_H_PROCESS # define STLSOFT_INCL_H_PROCESS # include # endif /* !STLSOFT_INCL_H_PROCESS */ +#elif defined(__APPLE__) + +# ifndef STLSOFT_INCL_H_LIBPROC +# define STLSOFT_INCL_H_LIBPROC +# include +# endif /* !STLSOFT_INCL_H_LIBPROC */ +# ifndef STLSOFT_INCL_MACH_O_H_DYLD +# define STLSOFT_INCL_MACH_O_H_DYLD +# include +# endif /* !STLSOFT_INCL_MACH_O_H_DYLD */ +# ifndef STLSOFT_INCL_H_UNISTD +# define STLSOFT_INCL_H_UNISTD +# include +# endif /* !STLSOFT_INCL_H_UNISTD */ +#elif defined(__linux__) + +# ifndef STLSOFT_INCL_H_UNISTD +# define STLSOFT_INCL_H_UNISTD +# include +# endif /* !STLSOFT_INCL_H_UNISTD */ +#elif 0 ||\ + defined(__FreeBSD__) ||\ + defined(__NetBSD__) ||\ + defined(__OpenBSD__) ||\ + 0 + +# ifndef STLSOFT_INCL_SYS_H_SYSCTL +# define STLSOFT_INCL_SYS_H_SYSCTL +# include +# endif /* !STLSOFT_INCL_SYS_H_SYSCTL */ +# ifndef STLSOFT_INCL_SYS_H_TYPES +# define STLSOFT_INCL_SYS_H_TYPES +# include +# endif /* !STLSOFT_INCL_SYS_H_TYPES */ +#elif defined(__sun) + +# ifndef STLSOFT_INCL_H_UNISTD +# define STLSOFT_INCL_H_UNISTD +# include +# endif /* !STLSOFT_INCL_H_UNISTD */ #else # ifndef STLSOFT_INCL_SYS_H_TYPES @@ -92,6 +153,19 @@ #endif +/* ///////////////////////////////////////////////////////////////////////// + * constants + */ + +#ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION +# if !defined(PATH_MAX) +# define UNIXSTL_C_GET_CURRENT_PROCESS_PATH_INTERNAL_SIZE_ 4096 +# else +# define UNIXSTL_C_GET_CURRENT_PROCESS_PATH_INTERNAL_SIZE_ PATH_MAX +# endif +#endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ + + /* ///////////////////////////////////////////////////////////////////////// * namespace */ @@ -128,11 +202,7 @@ int unixstl_C_get_current_process_id(void) { #if 0 -#elif defined(_WIN32) && \ - ( 0 ||\ - defined(STLSOFT_COMPILER_IS_MSVC) ||\ - defined(STLSOFT_COMPILER_IS_INTEL) ||\ - 0) +#elif defined(_WIN32) return STLSOFT_NS_GLOBAL(_getpid)(); #else @@ -143,6 +213,262 @@ unixstl_C_get_current_process_id(void) #endif } +/** \brief Obtains the fully qualified path of the current process image + * (multibyte). + * + * \ingroup group__library__System + * + * \param buff Destination buffer. May be \c NULL if and only if \c cch is + * 0; + * \param cch Number of characters available in \c buff, including space for + * a terminating NUL; + * + * \return If \c buff is sufficient for the full path and a terminating NUL + * character then this returns the length of the path (excluding the NUL + * character). Otherwise, as much of the result as can be written is done + * so and a character count of at least the full length + 1 (for + * the NUL character) is returned. The returned demand may exceed that + * minimum. Returns 0 on failure; + * + * \pre 0 == cch || NULL != buff + * + * \note The normative client pattern is to call with \c cch of 0 to obtain + * a sufficient size, allocate, then call again. + */ +STLSOFT_INLINE +us_size_t +unixstl_C_get_current_process_path_m( + us_char_a_t* buff +, us_size_t cch +) +{ + STLSOFT_C_AUTO_BUFFER_DECLARE(us_char_a_t, UNIXSTL_C_GET_CURRENT_PROCESS_PATH_INTERNAL_SIZE_, ab); + us_size_t len = 0; + us_size_t result = 0; + + UNIXSTL_ASSERT(0 == cch || NULL != buff); + + STLSOFT_C_AUTO_BUFFER_INITIALISE_FROM_INTERNAL(ab); + +#if 0 +#elif defined(_WIN32) + + /* NOTE: this only for UNIXem-ulation, so we don't care about its + * performance + */ + + /* Windows / UNIXem: GetModuleFileNameA */ + for (;;) + { + DWORD const n = WINSTL_API_EXTERNAL_DynamicLinkLibrary_GetModuleFileNameA( + NULL + , ab.ptr + , STLSOFT_STATIC_CAST(DWORD, ab.size) + ); + + if (0 == n) + { + goto done; + } + + if (n < ab.size) + { + len = STLSOFT_STATIC_CAST(us_size_t, n); + break; + } + + if (0 != STLSOFT_C_AUTO_BUFFER_RESIZE(ab, ab.size * 2)) + { + errno = ENOMEM; + + goto done; + } + } +#elif defined(__APPLE__) + + /* macOS: prefer proc_pidpath; fallback to _NSGetExecutablePath (+ realpath). */ + { + int const ret = STLSOFT_NS_GLOBAL(proc_pidpath)( + STLSOFT_NS_GLOBAL(getpid)() + , ab.ptr + , STLSOFT_STATIC_CAST(uint32_t, ab.size) + ); + + if (ret <= 0) + { + uint32_t size = STLSOFT_STATIC_CAST(uint32_t, ab.size); + + if (0 != STLSOFT_NS_GLOBAL(_NSGetExecutablePath)(ab.ptr, &size)) + { + if (0 != STLSOFT_C_AUTO_BUFFER_RESIZE(ab, size)) + { + errno = ENOMEM; + + goto done; + } + + size = STLSOFT_STATIC_CAST(uint32_t, ab.size); + + if (0 != STLSOFT_NS_GLOBAL(_NSGetExecutablePath)(ab.ptr, &size)) + { + goto done; + } + } + + { + char* const resolved = STLSOFT_NS_GLOBAL(realpath)(ab.ptr, NULL); + + if (NULL != resolved) + { + us_size_t const cchResolved = STLSOFT_NS_GLOBAL(strlen)(resolved); + + if (cchResolved + 1 > ab.size) + { + if (0 != STLSOFT_C_AUTO_BUFFER_RESIZE(ab, cchResolved + 1)) + { + STLSOFT_NS_GLOBAL(free)(resolved); + + errno = ENOMEM; + + goto done; + } + } + + STLSOFT_NS_GLOBAL(memcpy)(ab.ptr, resolved, cchResolved + 1); + STLSOFT_NS_GLOBAL(free)(resolved); + } + } + } + + len = STLSOFT_NS_GLOBAL(strlen)(ab.ptr); + } +#elif defined(__linux__) + + /* Linux: readlink("/proc/self/exe") */ + for (;;) + { + ssize_t const n = STLSOFT_NS_GLOBAL(readlink)("/proc/self/exe", ab.ptr, ab.size); + + if (n < 0) + { + goto done; + } + + if (STLSOFT_STATIC_CAST(us_size_t, n) < ab.size) + { + ab.ptr[n] = '\0'; + len = STLSOFT_STATIC_CAST(us_size_t, n); + break; + } + + if (0 != STLSOFT_C_AUTO_BUFFER_RESIZE(ab, ab.size * 2)) + { + errno = ENOMEM; + + goto done; + } + } +#elif 0 ||\ + defined(__FreeBSD__) ||\ + defined(__NetBSD__) ||\ + defined(__OpenBSD__) ||\ + 0 + + /* BSD: sysctl(KERN_PROC_PATHNAME) */ + { + int mib[4]; + size_t cb = ab.size; + + mib[0] = CTL_KERN; + mib[1] = KERN_PROC; + mib[2] = KERN_PROC_PATHNAME; + mib[3] = -1; + + if (0 != STLSOFT_NS_GLOBAL(sysctl)(mib, 4, ab.ptr, &cb, NULL, 0)) + { + if (ENOMEM == errno) + { + if (0 != STLSOFT_C_AUTO_BUFFER_RESIZE(ab, cb)) + { + errno = ENOMEM; + + goto done; + } + + cb = ab.size; + + if (0 != STLSOFT_NS_GLOBAL(sysctl)(mib, 4, ab.ptr, &cb, NULL, 0)) + { + goto done; + } + } + else + { + goto done; + } + } + + len = STLSOFT_NS_GLOBAL(strlen)(ab.ptr); + } +#elif defined(__sun) + + /* Solaris: getexecname() + realpath() */ + { + char const* const exe = STLSOFT_NS_GLOBAL(getexecname)(); + + if (NULL == exe) + { + goto done; + } + + if (NULL == STLSOFT_NS_GLOBAL(realpath)(exe, ab.ptr)) + { + goto done; + } + + len = STLSOFT_NS_GLOBAL(strlen)(ab.ptr); + } +#else + + errno = ENOSYS; + + goto done; +#endif + + if (0 == cch) + { + result = len + 1; + } + else if (cch <= len) + { + us_size_t const nCopy = cch - 1; + + if (0 != nCopy) + { + STLSOFT_NS_GLOBAL(memcpy)(buff, ab.ptr, nCopy * sizeof(us_char_a_t)); + } + + buff[nCopy] = '\0'; + result = len + 1; + } + else + { + if (0 != len) + { + STLSOFT_NS_GLOBAL(memcpy)(buff, ab.ptr, len * sizeof(us_char_a_t)); + } + + buff[len] = '\0'; + result = len; + } + +done: + + STLSOFT_C_AUTO_BUFFER_FREE(ab); + + return result; +} + /* ///////////////////////////////////////////////////////////////////////// * namespace diff --git a/include/unixstl/system/directory_functions.h b/include/unixstl/system/directory_functions.h index ee78e61a..13b62210 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: 18th 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. * @@ -52,9 +52,9 @@ #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_MINOR 1 +# define UNIXSTL_VER_UNIXSTL_SYSTEM_H_DIRECTORY_FUNCTIONS_REVISION 1 +# define UNIXSTL_VER_UNIXSTL_SYSTEM_H_DIRECTORY_FUNCTIONS_EDIT 25 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -80,6 +80,10 @@ # define STLSOFT_INCL_H_ERRNO # include #endif /* !STLSOFT_INCL_H_ERRNO */ +#ifndef STLSOFT_INCL_H_WCHAR +# define STLSOFT_INCL_H_WCHAR +# include +#endif /* !STLSOFT_INCL_H_WCHAR */ #ifndef STLSOFT_INCL_STLSOFT_API_external_h_string # include @@ -172,18 +176,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,18 +237,62 @@ 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); } } -#if 0 /* TODO: implement this */ +/* Policy: read HOME via getenv() (multibyte) and convert to wide with + * mbstowcs() using the locale multibyte encoding. + */ STLSOFT_INLINE -#endif us_size_t unixstl_C_get_home_directory_w( us_char_w_t buffer[] , us_size_t cchBuffer -); +) +{ + us_char_a_t const* const home = unixstl_C_get_home_directory_invoke_getenv_a_("HOME"); + + if (NULL == home) + { + return 0; + } + else + { + size_t const cchHome = STLSOFT_NS_GLOBAL(mbstowcs)(NULL, home, 0); + + if ((size_t)-1 == cchHome) + { + return 0; + } + + if (0 == cchBuffer) + { + return cchHome + 1; + } + + { + size_t const n = STLSOFT_NS_GLOBAL(mbstowcs)(buffer, home, cchBuffer); + + if ((size_t)-1 == n) + { + return 0; + } + + if (cchHome < cchBuffer) + { + return n; + } + + /* Insufficient space: match narrow string_copy_with_nul — + * leave a NUL in the last slot and return cchBuffer - 1. + */ + buffer[cchBuffer - 1] = L'\0'; + + return cchBuffer - 1; + } + } +} /* ///////////////////////////////////////////////////////////////////////// diff --git a/include/unixstl/system/system_traits.hpp b/include/unixstl/system/system_traits.hpp index 3be24177..e5ac6dc9 100644 --- a/include/unixstl/system/system_traits.hpp +++ b/include/unixstl/system/system_traits.hpp @@ -5,7 +5,7 @@ * Unicode specialisations thereof. * * Created: 15th November 2002 - * Updated: 8th October 2026 + * Updated: 15th October 2026 * * Home: http://stlsoft.org/ * @@ -53,10 +53,10 @@ #define UNIXSTL_INCL_UNIXSTL_SYSTEM_HPP_SYSTEM_TRAITS #ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION -# define UNIXSTL_VER_UNIXSTL_SYSTEM_HPP_SYSTEM_TRAITS_MAJOR 6 -# define UNIXSTL_VER_UNIXSTL_SYSTEM_HPP_SYSTEM_TRAITS_MINOR 2 -# define UNIXSTL_VER_UNIXSTL_SYSTEM_HPP_SYSTEM_TRAITS_REVISION 3 -# define UNIXSTL_VER_UNIXSTL_SYSTEM_HPP_SYSTEM_TRAITS_EDIT 141 +# define UNIXSTL_VER_UNIXSTL_SYSTEM_HPP_SYSTEM_TRAITS_MAJOR 7 +# define UNIXSTL_VER_UNIXSTL_SYSTEM_HPP_SYSTEM_TRAITS_MINOR 0 +# define UNIXSTL_VER_UNIXSTL_SYSTEM_HPP_SYSTEM_TRAITS_REVISION 1 +# define UNIXSTL_VER_UNIXSTL_SYSTEM_HPP_SYSTEM_TRAITS_EDIT 146 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -71,10 +71,19 @@ # pragma message(__FILE__) #endif /* STLSOFT_TRACE_INCLUDE */ +#ifndef UNIXSTL_INCL_UNIXSTL_FILESYSTEM_H_PATH_PARSE_FUNCTIONS +# include +#endif /* !UNIXSTL_INCL_UNIXSTL_FILESYSTEM_H_PATH_PARSE_FUNCTIONS */ +#ifndef UNIXSTL_INCL_UNIXSTL_PROCESS_H_FUNCTIONS +# include +#endif /* !UNIXSTL_INCL_UNIXSTL_PROCESS_H_FUNCTIONS */ #ifndef UNIXSTL_INCL_UNIXSTL_SYSTEM_H_DIRECTORY_FUNCTIONS # include #endif /* !UNIXSTL_INCL_UNIXSTL_SYSTEM_H_DIRECTORY_FUNCTIONS */ +#ifndef STLSOFT_INCL_STLSOFT_MEMORY_HPP_AUTO_BUFFER +# include +#endif /* !STLSOFT_INCL_STLSOFT_MEMORY_HPP_AUTO_BUFFER */ #ifndef STLSOFT_INCL_STLSOFT_STRING_HPP_C_STRING_TRAITS # include #endif /* !STLSOFT_INCL_STLSOFT_STRING_HPP_C_STRING_TRAITS */ @@ -90,6 +99,7 @@ #elif defined(_WIN32) ||\ defined(_WIN64) # include +# include #endif /* Windows */ #ifndef STLSOFT_INCL_H_ERRNO # define STLSOFT_INCL_H_ERRNO @@ -124,6 +134,10 @@ # define STLSOFT_INCL_H_STDLIB # include #endif /* !STLSOFT_INCL_H_STDLIB */ +#ifndef STLSOFT_INCL_H_WCHAR +# define STLSOFT_INCL_H_WCHAR +# include +#endif /* !STLSOFT_INCL_H_WCHAR */ #ifndef STLSOFT_INCL_H_UNISTD # define STLSOFT_INCL_H_UNISTD # include @@ -250,6 +264,74 @@ struct system_traits ); /// @} +/// \name Process Paths +/// @{ +public: + /// Attempt to obtain the current process's path. + /// + /// \param cch The number of elements available in \c buff available for + /// writing; + /// \param buff Pointer to the buffer into which \c cch result can be + /// written. May not be \c nullptr except when \c cch is 0; + /// \param ppFile Optional pointer to receive a mutating pointer. When + /// non-nullptr, *ppFile is always set to + /// nullptr; then, if and only if the full path was + /// written into \c buff, *ppFile is set to the last + /// path-name separator in \c buff, if any; + /// + /// \return If \c buff is sufficient for the full path and a terminating + /// NUL character then this returns the length of the path (excluding + /// the NUL character). Otherwise, as much of the result as can be + /// written is done so and a character count of at least the + /// full length + 1 (for the NUL character) is returned, in order that + /// client code can allocate all required space. The returned demand + /// may exceed that minimum; + /// \retval 0 The function failed, and more information can be obtained + /// from get_last_error(); + /// + /// \note The normative client pattern is to call with \c cch of 0 to + /// obtain a sufficient size, allocate, then call again. + /// + /// \pre 0 == cch || nullptr != buff + static + size_type + get_current_process_path( + size_type cch + , char_type buff[/* cch */] + , char_type** ppFile + ) STLSOFT_NOEXCEPT; + + /// Attempt to obtain the current process's path into a resizeable + /// buffer. + /// + /// \param rb Reference to a resizeable buffer that will be resized as + /// required to hold the path and a terminating NUL character; + /// \param ppFile Optional pointer to receive a mutating pointer into + /// the final contents of \c rb. When non-nullptr, + /// *ppFile is set as for the raw overload, after the + /// final fill; + /// + /// \return The length of the path (excluding the NUL character) on + /// success; 0 on failure; + /// \retval 0 The function failed (query or resize). On query failure + /// \c rb is left unchanged; on resize failure + /// ENOMEM is set and \c rb is left unchanged. In neither + /// failure case is &rb[0] taken on an empty buffer; + /// + /// \note The normative pattern is a size query via the raw overload + /// with \c cch of 0, then resize, then fill — this overload performs + /// that sequence. \c ppFile is computed only after the final fill. + template< + ss_typename_param_k T_resizeableBuffer + > + static + size_type + get_current_process_path( + T_resizeableBuffer& rb + , char_type** ppFile = NULL + ); +/// @} + /// \name System Paths /// @{ public: @@ -580,6 +662,70 @@ struct system_traits return 0; } +public: + static + size_type + get_current_process_path( + size_type cch + , char_type buff[/* cch */] + , char_type** ppFile + ) STLSOFT_NOEXCEPT + { + UNIXSTL_ASSERT(0 == cch || NULL != buff); + + if (NULL != ppFile) + { + *ppFile = NULL; + } + + size_type const n = unixstl_C_get_current_process_path_m(buff, cch); + + if (0 != n && + n < cch) + { + if (NULL != ppFile) + { + *ppFile = const_cast(unixstl_C_find_last_path_name_separator_len_m(buff, n)); + } + } + + return n; + } + + template< + ss_typename_param_k T_resizeableBuffer + > + static + size_type + get_current_process_path( + T_resizeableBuffer& rb + , char_type** ppFile = NULL + ) + { + size_type const cchRequired = get_current_process_path( + 0 + , static_cast(NULL) + , static_cast(NULL) + ); + + if (0 == cchRequired) + { + return 0; + } + + if (rb.size() < cchRequired) + { + if (!STLSOFT_NS_QUAL(resizeable_buffer_resize)(rb, cchRequired)) + { + set_last_error(ENOMEM); + + return 0; + } + } + + return get_current_process_path(rb.size(), &rb[0], ppFile); + } + public: static size_type @@ -760,7 +906,54 @@ struct system_traits path_str_compare( char_type const* ps1 , char_type const* ps2 - ); + ) + { + UNIXSTL_ASSERT(NULL != ps1); + UNIXSTL_ASSERT(NULL != ps2); + + for (;; ++ps1, ++ps2) + { + int_type d = int_type(*ps1) - int_type(*ps2); +#ifdef _WIN32 + + if (0 != d) + { + d = towupper(*ps1) - towupper(*ps2); + } + + if (0 != d) + { + switch (*ps1) + { + case L'/': + case L'\\': + + switch (*ps2) + { + case L'/': + case L'\\': + + d = 0; + break; + } + break; + } + } +#endif + + if (0 != d) + { + return d; + } + + if (L'\0' == *ps1) + { + break; + } + } + + return 0; + } static int @@ -768,7 +961,49 @@ struct system_traits char_type const* ps1 , char_type const* ps2 , size_type cch - ); + ) + { + UNIXSTL_ASSERT(NULL != ps1); + UNIXSTL_ASSERT(NULL != ps2); + + for (; 0 != cch; ++ps1, ++ps2, --cch) + { + int_type d = int_type(*ps1) - int_type(*ps2); +#ifdef _WIN32 + + if (0 != d) + { + d = towupper(*ps1) - towupper(*ps2); + } + + if (0 != d) + { + switch (*ps1) + { + case L'/': + case L'\\': + + switch (*ps2) + { + case L'/': + case L'\\': + + d = 0; + break; + } + break; + } + } +#endif + + if (0 != d) + { + return d; + } + } + + return 0; + } public: static @@ -783,13 +1018,31 @@ struct system_traits return unixstl_C_get_home_directory_w(buffer, cchBuffer); } + template< + ss_typename_param_k T_resizeableBuffer + > + static + size_type + get_home_directory( + T_resizeableBuffer& rb + ) + { + size_type const cchRequired = get_home_directory(static_cast(NULL), 0); + + rb.resize(cchRequired); + + return get_home_directory(&rb[0], rb.size()); + } + public: - static module_type load_library(char_type const* name); + /* Dynamic loading stays declare-only on W until load_library and + * free_library can land together with one conversion policy. + */ + static module_type load_library(char_type const* name) + ; static bool_type free_library(module_type hModule) - { - return 0 == ::dlclose(hModule); - } + ; static void* @@ -826,6 +1079,10 @@ struct system_traits } public: + /* Policy: convert wide name/value via the locale multibyte encoding + * for getenv(). expand_environment_strings remains declared (compat) + * pending a finished group implementation aligned with ANSI. + */ static size_type get_environment_variable( @@ -833,7 +1090,77 @@ struct system_traits , char_type buffer[] , size_type cchBuffer ) - ; + { + UNIXSTL_ASSERT(NULL != name); + + size_t const cchName = ::wcstombs(NULL, name, 0); + + if (static_cast(-1) == cchName) + { + return 0; + } + + STLSOFT_NS_QUAL(auto_buffer) name_m(cchName + 1); + + if (name_m.empty()) + { + return 0; + } + + if (static_cast(-1) == ::wcstombs(&name_m[0], name, name_m.size())) + { + return 0; + } + +# include + + char const* const var = ::getenv(name_m.data()); + +# include + + if (NULL == var) + { + return 0; + } + else + { + size_t const cchValue = ::mbstowcs(NULL, var, 0); + + if (static_cast(-1) == cchValue) + { + return 0; + } + + if (NULL == buffer) + { + return cchValue; + } + else + { + STLSOFT_NS_QUAL(auto_buffer) value_w(cchValue + 1); + + if (value_w.empty()) + { + return 0; + } + + if (static_cast(-1) == ::mbstowcs(&value_w[0], var, value_w.size())) + { + return 0; + } + + size_type const writtenLen = (cchValue < cchBuffer) ? cchValue : cchBuffer; + + char_copy(buffer, value_w.data(), writtenLen); + if (writtenLen < cchBuffer) + { + buffer[writtenLen] = L'\0'; + } + + return (cchValue < cchBuffer) ? cchValue : cchBuffer; + } + } + } template< ss_typename_param_k T_resizeableBuffer @@ -844,7 +1171,18 @@ struct system_traits char_type const* name , T_resizeableBuffer& rb ) - ; + { + size_type const cchRequired = get_environment_variable(name, static_cast(NULL), 0); + + if (0 == cchRequired) + { + return 0; + } + + rb.resize(cchRequired); + + return get_environment_variable(name, &rb[0], rb.size()); + } static size_type diff --git a/include/unixstl/unixstl.h b/include/unixstl/unixstl.h index 33335107..2492fe3f 100644 --- a/include/unixstl/unixstl.h +++ b/include/unixstl/unixstl.h @@ -5,7 +5,7 @@ * platform discriminations, and definitions of types. * * Created: 15th January 2002 - * Updated: 10th October 2026 + * Updated: 17th October 2026 * * Home: http://stlsoft.org/ * @@ -50,8 +50,8 @@ #ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION # define UNIXSTL_VER_UNIXSTL_H_UNIXSTL_MAJOR 3 # define UNIXSTL_VER_UNIXSTL_H_UNIXSTL_MINOR 11 -# define UNIXSTL_VER_UNIXSTL_H_UNIXSTL_REVISION 5 -# define UNIXSTL_VER_UNIXSTL_H_UNIXSTL_EDIT 132 +# define UNIXSTL_VER_UNIXSTL_H_UNIXSTL_REVISION 6 +# define UNIXSTL_VER_UNIXSTL_H_UNIXSTL_EDIT 134 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ /** \file unixstl/unixstl.h @@ -164,12 +164,13 @@ # define _UNIXSTL_VER_1_8_6_B05 0x01080685 /*!< Version 1.8.8 beta 5 (with STLSoft 1.11.1 rc 2) */ # define _UNIXSTL_VER_1_8_6_B06 0x01080686 /*!< Version 1.8.8 beta 6 (with STLSoft 1.11.1 rc 3) */ # define _UNIXSTL_VER_1_8_6_B07 0x01080687 /*!< Version 1.8.8 beta 7 (with STLSoft 1.11.1 rc 8) */ +# define _UNIXSTL_VER_1_8_6_B08 0x01080688 /*!< Version 1.8.8 beta 8 (with STLSoft 1.11.1 rc 9) */ #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ #define _UNIXSTL_VER_MAJOR 1 #define _UNIXSTL_VER_MINOR 8 #define _UNIXSTL_VER_PATCH 6 -#define _UNIXSTL_VER_ALPHABETA 0x87 +#define _UNIXSTL_VER_ALPHABETA 0x88 #define _UNIXSTL_VER \ (0\ @@ -200,8 +201,8 @@ * STLSoft version compatibility check(s) */ -#if _STLSOFT_VER < 0x010B01C8 -# error This version of the UNIXSTL libraries requires STLSoft version 1.11.1 rc 8, or later +#if _STLSOFT_VER < 0x010B01C9 +# error This version of the UNIXSTL libraries requires STLSoft version 1.11.1 rc 9, or later #endif /* _STLSOFT_VER */ diff --git a/include/winstl/api/internal/DynamicLinkLibrary.h b/include/winstl/api/internal/DynamicLinkLibrary.h index a8aa905b..c1e5787e 100644 --- a/include/winstl/api/internal/DynamicLinkLibrary.h +++ b/include/winstl/api/internal/DynamicLinkLibrary.h @@ -5,11 +5,11 @@ * Library Functions API. * * Created: 30th November 2020 - * Updated: 26th May 2025 + * Updated: 15th October 2026 * * Home: http://stlsoft.org/ * - * Copyright (c) 2020-2025, 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 @@ -79,18 +79,18 @@ * specified module (that must have been loaded by the current process). * * \param hModule A handle to the loaded module for which the path is to be - * obtained; + * obtained; * \param filename A pointer to the buffer into which to write the path. May - * not be NULL unless \c cchFilename is 0; + * not be NULL unless \c cchFilename is 0; * \param cchFilename Number of available bytes in \c filename; * * \return The number of characters written if cchFilename is sufficient to - * hold the entire string; the number of characters required (including for - * terminating NUL character) if not. + * hold the entire string; the number of characters required (including + * for terminating NUL character) if not. * * \note The number of characters required returned is 2 (not 1) more than - * the number of characters in the string, due to the underlying API - * function not providing any direct indication as to (in)sufficient size. + * the number of characters in the string, due to the underlying API + * function not providing any direct indication as to (in)sufficient size. */ STLSOFT_INLINE DWORD @@ -238,18 +238,18 @@ WINSTL_API_INTERNAL_DynamicLinkLibrary_GetModuleFileNameA( * specified module (that must have been loaded by the current process). * * \param hModule A handle to the loaded module for which the path is to be - * obtained; + * obtained; * \param filename A pointer to the buffer into which to write the path. May - * not be NULL unless \c cchFilename is 0; + * not be NULL unless \c cchFilename is 0; * \param cchFilename Number of available characters in \c filename; * * \return The number of characters written if cchFilename is sufficient to - * hold the entire string; the number of characters required (including for - * terminating NUL character) if not. + * hold the entire string; the number of characters required (including + * for terminating NUL character) if not. * * \note The number of characters required returned is 2 (not 1) more than - * the number of characters in the string, due to the underlying API - * function not providing any direct indication as to (in)sufficient size. + * the number of characters in the string, due to the underlying API + * function not providing any direct indication as to (in)sufficient size. */ STLSOFT_INLINE DWORD diff --git a/include/winstl/diagnostics/stopwatch.hpp b/include/winstl/diagnostics/stopwatch.hpp index 5fa39ee2..65094643 100644 --- a/include/winstl/diagnostics/stopwatch.hpp +++ b/include/winstl/diagnostics/stopwatch.hpp @@ -6,11 +6,11 @@ * otherwise using the tick-count facilities. * * Created: 31st July 2002 - * Updated: 20th March 2025 + * Updated: 15th 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) 2002-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -57,7 +57,7 @@ # define WINSTL_VER_WINSTL_DIAGNOSTICS_HPP_STOPWATCH_MAJOR 5 # define WINSTL_VER_WINSTL_DIAGNOSTICS_HPP_STOPWATCH_MINOR 1 # define WINSTL_VER_WINSTL_DIAGNOSTICS_HPP_STOPWATCH_REVISION 2 -# define WINSTL_VER_WINSTL_DIAGNOSTICS_HPP_STOPWATCH_EDIT 54 +# define WINSTL_VER_WINSTL_DIAGNOSTICS_HPP_STOPWATCH_EDIT 55 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -158,10 +158,10 @@ std::cout << "Number of nanoseconds: " << static_cast(sw.get_nan \endcode * * - * \remarks This class attempts to use the high performance hardware - * stopwatch as its measurement resource, but failing that it defaults to - * less accurate resources in order to guarantee that meaningful - * measurements are always available to application code. + * \note This class attempts to use the high performance hardware stopwatch + * as its measurement resource, but failing that it defaults to less + * accurate resources in order to guarantee that meaningful measurements + * are always available to application code. */ class stopwatch { @@ -221,8 +221,8 @@ class stopwatch void stop(); /// Ends the current measurement period and start the next /// - /// \remarks This is equivalent to an atomic invocation of stop() and - /// start() + /// \note This is equivalent to an atomic invocation of stop() and + /// start(). void restart(); public: // attributes diff --git a/include/winstl/filesystem/file_functions.hpp b/include/winstl/filesystem/file_functions.hpp index e7463a13..07a14e7b 100644 --- a/include/winstl/filesystem/file_functions.hpp +++ b/include/winstl/filesystem/file_functions.hpp @@ -4,11 +4,11 @@ * Purpose: Helper functions for file handling * * Created: 1st January 2005 - * Updated: 20th March 2025 + * Updated: 15th 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) 2005-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -54,7 +54,7 @@ # define WINSTL_VER_WINSTL_FILESYSTEM_HPP_FILE_FUNCTIONS_MAJOR 2 # define WINSTL_VER_WINSTL_FILESYSTEM_HPP_FILE_FUNCTIONS_MINOR 3 # define WINSTL_VER_WINSTL_FILESYSTEM_HPP_FILE_FUNCTIONS_REVISION 19 -# define WINSTL_VER_WINSTL_FILESYSTEM_HPP_FILE_FUNCTIONS_EDIT 75 +# define WINSTL_VER_WINSTL_FILESYSTEM_HPP_FILE_FUNCTIONS_EDIT 76 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -153,9 +153,9 @@ std::string contents; winstl::uint64_t numBytes = winstl::load_text_file("mytextfile.ext", contents); \endcode * - * \remarks The character type of the text file is assumed (and controlled) - * to be that of the \c contents parameter. For example, if \c contents is - * of type \c std::wstring then the file will be processed as if it + * \note The character type of the text file is assumed (and controlled) to + * be that of the \c contents parameter. For example, if \c contents is of + * type \c std::wstring then the file will be processed as if it * contains \c wchar_t. * * \note When used with a compiler that does not support partial template @@ -425,13 +425,12 @@ winstl::readlines("mytextfile.ext", lines); \endcode * * - * \remarks The container type's value_type must provide - * a two-parameter constructor whose parameters types are - * char_type const* (where char_type is the - * value_type of the string type S) and - * size_t, indicating the pointer to the beginning and the - * length of the C-style string that represents the line read from the - * file denoted by fileName. + * \note The container type's value_type must provide a + * two-parameter constructor whose parameters types are + * char_type const* (where \c char_type is the \c value_type + * of the string type \c S) and \c size_t, indicating the pointer to the + * beginning and the length of the C-style string that represents the line + * read from the file denoted by \c fileName. * * \note When used with a compiler that does not support partial template * specialisation, the use of string types for which explicit diff --git a/include/winstl/filesystem/file_information_functions.h b/include/winstl/filesystem/file_information_functions.h index 8b7051c2..d93926c2 100644 --- a/include/winstl/filesystem/file_information_functions.h +++ b/include/winstl/filesystem/file_information_functions.h @@ -1,14 +1,14 @@ /* ///////////////////////////////////////////////////////////////////////// - * 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: 11th March 2024 + * Created: 7th November 2014 + * Updated: 13th October 2026 * - * Home: http://stlsoft.org/ + * 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 6 +# define WINSTL_VER_WINSTL_H_FILE_INFORMATION_FUNCTIONS_EDIT 12 #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,80 @@ 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 + * + * 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(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) && \ diff --git a/include/winstl/filesystem/filesystem_traits.hpp b/include/winstl/filesystem/filesystem_traits.hpp index fe194b8a..70c1ec21 100644 --- a/include/winstl/filesystem/filesystem_traits.hpp +++ b/include/winstl/filesystem/filesystem_traits.hpp @@ -5,11 +5,11 @@ * Unicode specialisations thereof. * * Created: 15th November 2002 - * Updated: 28th May 2025 + * Updated: 15th 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) 2002-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -56,7 +56,7 @@ # define WINSTL_VER_WINSTL_FILESYSTEM_HPP_FILESYSTEM_TRAITS_MAJOR 4 # define WINSTL_VER_WINSTL_FILESYSTEM_HPP_FILESYSTEM_TRAITS_MINOR 22 # define WINSTL_VER_WINSTL_FILESYSTEM_HPP_FILESYSTEM_TRAITS_REVISION 11 -# define WINSTL_VER_WINSTL_FILESYSTEM_HPP_FILESYSTEM_TRAITS_EDIT 194 +# define WINSTL_VER_WINSTL_FILESYSTEM_HPP_FILESYSTEM_TRAITS_EDIT 195 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -299,7 +299,7 @@ struct filesystem_traits /// \pre nullptr != dir /// /// \note \c dir is assumed to contain space for an additional - /// character (if required) and NUL-terminator + /// character (if required) and NUL character. /// /// \see \link #path_name_separator path_name_separator() \endlink static @@ -803,13 +803,13 @@ struct filesystem_traits static bool_type fstat(file_handle_type fd, fstat_data_type* fstat_data); /// Gets the file attributes for the given path /// - /// \pre (nullptr != path); - /// \pre (nullptr != attr); + /// \pre nullptr != path + /// \pre nullptr != attr static bool_type get_file_attributes(char_type const* path, file_attributes_type* attr); /// Sets the file attributes for the given path /// - /// \pre (nullptr != path); - /// \pre (INVALID_FILE_ATTRIBUTES != attr); + /// \pre nullptr != path + /// \pre INVALID_FILE_ATTRIBUTES != attr static bool_type set_file_attributes(char_type const* path, file_attributes_type const attr); /// Returns whether the given stat info represents a file @@ -868,7 +868,7 @@ struct filesystem_traits static large_size_type get_file_size(stat_data_type const& sd); /// Gets the size of the file /// - /// \pre (nullptr != psd) + /// \pre nullptr != psd static large_size_type get_file_size(stat_data_type const* psd); #else /* ? STLSOFT_CF_64BIT_INT_SUPPORT */ private: @@ -1947,7 +1947,7 @@ struct filesystem_traits if (r + 2 < cchBuffer) { - // There's enough space for the result and the closing quote and the nul-terminator + // There's enough space for the result and the closing quote and the NUL character buffer[r + 2] = '\0'; n = r + 2; @@ -2316,8 +2316,8 @@ struct filesystem_traits } #if 0 - /// \pre (nullptr != path); - /// \pre (INVALID_FILE_ATTRIBUTES != attr); + /// \pre nullptr != path + /// \pre INVALID_FILE_ATTRIBUTES != attr #endif static bool_type is_file(stat_data_type const* stat_data) diff --git a/include/winstl/filesystem/memory_map_functions.h b/include/winstl/filesystem/memory_map_functions.h index 1288ca71..5c8b1a47 100644 --- a/include/winstl/filesystem/memory_map_functions.h +++ b/include/winstl/filesystem/memory_map_functions.h @@ -4,11 +4,11 @@ * Purpose: Windows memory mapping functions. * * Created: 15th December 1996 - * Updated: 27th December 2024 + * Updated: 11th 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) 1996-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -52,7 +52,7 @@ # define WINSTL_VER_WINSTL_FILESYSTEM_H_MEMORY_MAP_FUNCTIONS_MAJOR 5 # define WINSTL_VER_WINSTL_FILESYSTEM_H_MEMORY_MAP_FUNCTIONS_MINOR 3 # define WINSTL_VER_WINSTL_FILESYSTEM_H_MEMORY_MAP_FUNCTIONS_REVISION 9 -# define WINSTL_VER_WINSTL_FILESYSTEM_H_MEMORY_MAP_FUNCTIONS_EDIT 126 +# define WINSTL_VER_WINSTL_FILESYSTEM_H_MEMORY_MAP_FUNCTIONS_EDIT 127 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -203,7 +203,7 @@ winstl_C_map_named_view_of_file_by_handle_v_( * the calling thread's last-error code, even if successful (when it will * set it to ERROR_SUCCESS). * - * \pre (INVALID_HANDLE_VALUE != hFile) + * \pre INVALID_HANDLE_VALUE != hFile */ STLSOFT_INLINE void* diff --git a/include/winstl/filesystem/path.hpp b/include/winstl/filesystem/path.hpp index 1921d253..fcce78a5 100644 --- a/include/winstl/filesystem/path.hpp +++ b/include/winstl/filesystem/path.hpp @@ -4,14 +4,14 @@ * Purpose: Simple class that represents a path. * * Created: 1st May 1993 - * Updated: 20th March 2025 + * Updated: 18th October 2026 * * Thanks: Pablo Aguilar for reporting defect in push_ext() (which * doesn't work for wide-string builds). * * 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) 1993-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -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 329 +# define WINSTL_VER_WINSTL_FILESYSTEM_HPP_PATH_REVISION 12 +# define WINSTL_VER_WINSTL_FILESYSTEM_HPP_PATH_EDIT 331 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -238,7 +238,7 @@ class basic_path #ifdef STLSOFT_CF_MEMBER_TEMPLATE_CTOR_SUPPORT /// Constructs a path from a string object. /// - /// \remarks The string object may be any type for which the + /// \note The string object may be any type for which the /// c_str_len and c_str_data /// \ref group__concept__Shim__string_access "String Access Shims" are /// defined. The following example shows the use of a window handle @@ -362,9 +362,9 @@ class basic_path class_type& push_ext(char_type const* rhs, bool_type bAddPathNameSeparator = false); /// Ensures that the path has a trailing path name separator /// - /// \remarks If the path currently contains path name separators, and - /// they are all forward slashes '/', then a forward slash will be - /// used; otherwise a backslash '\\' will be used. + /// \note If the path currently contains path name separators, and they + /// are all forward slashes '/', then a forward slash will be used; + // otherwise a backslash '\\' will be used. class_type& push_sep(); /// Pops the last path element from the path /// @@ -464,7 +464,7 @@ class basic_path size_type length() const STLSOFT_NOEXCEPT; /// Returns the length of the converted path /// - /// \remarks Equivalent to length() + /// \note Equivalent to length(). size_type size() const STLSOFT_NOEXCEPT; /// The maximum possible length of a path static size_type max_size() STLSOFT_NOEXCEPT; @@ -521,7 +521,7 @@ class basic_path /// Evaluates whether the two instances hold strings that refer /// to the same file-system entity. /// - /// \remarks See \link winstl::basic_path::equivalent(C const* ) equivalent()\endlink for an example. + /// \note See \link winstl::basic_path::equivalent(C const* ) equivalent()\endlink for an example. /// /// \note The string comparison is case-insensitive. bool_type equivalent(class_type const& rhs) const STLSOFT_NOEXCEPT; @@ -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; diff --git a/include/winstl/filesystem/squeeze_functions.hpp b/include/winstl/filesystem/squeeze_functions.hpp index 8fd99f96..b21cd15b 100644 --- a/include/winstl/filesystem/squeeze_functions.hpp +++ b/include/winstl/filesystem/squeeze_functions.hpp @@ -4,11 +4,11 @@ * Purpose: Path squeeze functions * * Created: 6th June 2006 - * Updated: 15th April 2025 + * Updated: 15th 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) 2006-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -54,7 +54,7 @@ # define WINSTL_VER_WINSTL_FILESYSTEM_HPP_SQUEEZE_FUNCTIONS_MAJOR 2 # define WINSTL_VER_WINSTL_FILESYSTEM_HPP_SQUEEZE_FUNCTIONS_MINOR 0 # define WINSTL_VER_WINSTL_FILESYSTEM_HPP_SQUEEZE_FUNCTIONS_REVISION 6 -# define WINSTL_VER_WINSTL_FILESYSTEM_HPP_SQUEEZE_FUNCTIONS_EDIT 39 +# define WINSTL_VER_WINSTL_FILESYSTEM_HPP_SQUEEZE_FUNCTIONS_EDIT 40 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -299,7 +299,7 @@ STLSOFT_CLOSE_WORKER_NS_(ximpl_winstl_squeeze_functions_) * the number of characters written (if buffer is non-\c nullptr). In both * cases, it includes the one required for the NUL-terminator * - * \remarks The squeeze algorithm is as follows. The path is split into + * \note The squeeze algorithm is as follows. The path is split into * volume+directory and file+ext. If the buffer is too small to fit the * file+ext, then the result will be a squeezed form of file+ext. If the * buffer is too small to fit the volume+...+file+ext, then the result diff --git a/include/winstl/registry/functions.hpp b/include/winstl/registry/functions.hpp index 16b413b1..ed41e13b 100644 --- a/include/winstl/registry/functions.hpp +++ b/include/winstl/registry/functions.hpp @@ -4,11 +4,11 @@ * Purpose: Registry functions. * * Created: 20th November 1995 - * Updated: 20th March 2025 + * Updated: 15th 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) 1995-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -54,7 +54,7 @@ # define WINSTL_VER_WINSTL_REGISTRY_HPP_FUNCTIONS_MAJOR 3 # define WINSTL_VER_WINSTL_REGISTRY_HPP_FUNCTIONS_MINOR 1 # define WINSTL_VER_WINSTL_REGISTRY_HPP_FUNCTIONS_REVISION 7 -# define WINSTL_VER_WINSTL_REGISTRY_HPP_FUNCTIONS_EDIT 65 +# define WINSTL_VER_WINSTL_REGISTRY_HPP_FUNCTIONS_EDIT 66 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -158,7 +158,7 @@ reg_get_string_value( * \retval "any other value" The function failed, and the error code * indicates why * - * \remarks If the function fails, the value of value is + * \note If the function fails, the value of value is * unchanged. */ template diff --git a/include/winstl/registry/reg_key.hpp b/include/winstl/registry/reg_key.hpp index 881fc442..c26df4fd 100644 --- a/include/winstl/registry/reg_key.hpp +++ b/include/winstl/registry/reg_key.hpp @@ -5,14 +5,14 @@ * specialisations thereof. * * Created: 19th January 2002 - * Updated: 20th March 2025 + * Updated: 15th October 2026 * * Thanks: To Sam Fisher for spotting the defect in the set_value_() * overload for REG_MULTI_SZ values (widestring only). * * 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) 2002-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -58,7 +58,7 @@ # define WINSTL_VER_WINSTL_REGISTRY_HPP_REG_KEY_MAJOR 3 # define WINSTL_VER_WINSTL_REGISTRY_HPP_REG_KEY_MINOR 10 # define WINSTL_VER_WINSTL_REGISTRY_HPP_REG_KEY_REVISION 16 -# define WINSTL_VER_WINSTL_REGISTRY_HPP_REG_KEY_EDIT 169 +# define WINSTL_VER_WINSTL_REGISTRY_HPP_REG_KEY_EDIT 170 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -1547,7 +1547,7 @@ basic_reg_key::set_value_( ); #endif - // Create a buffer of sufficient size: total length + a nul-terminator for each value + a double nul-terminator + // Create a buffer of sufficient size: total length + a NUL character for each value + a double NUL character STLSOFT_NS_QUAL(auto_buffer) buff(totalLen + numValues * 1 + 2); if (buff.empty()) diff --git a/include/winstl/registry/reg_value.hpp b/include/winstl/registry/reg_value.hpp index c1224822..790c4deb 100644 --- a/include/winstl/registry/reg_value.hpp +++ b/include/winstl/registry/reg_value.hpp @@ -10,7 +10,7 @@ * regretably now implemented as independent classes. * * Created: 19th January 2002 - * Updated: 21st March 2025 + * Updated: 15th October 2026 * * Thanks: To Diego Chanoux for spotting a defect in the value_sz() method. * @@ -23,7 +23,7 @@ * * 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) 2002-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -70,7 +70,7 @@ # define WINSTL_VER_WINSTL_REGISTRY_HPP_REG_VALUE_MAJOR 3 # define WINSTL_VER_WINSTL_REGISTRY_HPP_REG_VALUE_MINOR 5 # define WINSTL_VER_WINSTL_REGISTRY_HPP_REG_VALUE_REVISION 14 -# define WINSTL_VER_WINSTL_REGISTRY_HPP_REG_VALUE_EDIT 136 +# define WINSTL_VER_WINSTL_REGISTRY_HPP_REG_VALUE_EDIT 137 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -654,7 +654,7 @@ basic_reg_value::value_sz() const { WINSTL_ASSERT(0 != data_size); - --data_size; // This is required since the size contains space for the nul-terminator + --data_size; // This is required since the size contains space for the NUL character buffer[data_size / sizeof(char_type)] = 0; // The site of a former bug. Thanks to Diego Chanoux for spotting this diff --git a/include/winstl/shell/memory/functions.h b/include/winstl/shell/memory/functions.h index 16c02a2c..0bf7a59d 100644 --- a/include/winstl/shell/memory/functions.h +++ b/include/winstl/shell/memory/functions.h @@ -4,11 +4,11 @@ * Purpose: Shell memory functions. * * Created: 2nd March 1996 - * Updated: 26th December 2024 + * Updated: 15th 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) 1996-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -54,7 +54,7 @@ # define WINSTL_VER_WINSTL_SHELL_MEMORY_H_FUNCTIONS_MAJOR 6 # define WINSTL_VER_WINSTL_SHELL_MEMORY_H_FUNCTIONS_MINOR 0 # define WINSTL_VER_WINSTL_SHELL_MEMORY_H_FUNCTIONS_REVISION 10 -# define WINSTL_VER_WINSTL_SHELL_MEMORY_H_FUNCTIONS_EDIT 70 +# define WINSTL_VER_WINSTL_SHELL_MEMORY_H_FUNCTIONS_EDIT 71 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -113,7 +113,7 @@ namespace winstl_project * \return Pointer to the allocated memory block, or \c nullptr if the * request failed. * - * \remarks On failure, the function will set the thread error information, + * \note On failure, the function will set the thread error information, * which may be retrieved by the Win32 API function * ::GetLastError() * @@ -158,7 +158,7 @@ winstl__SHMemAlloc(ws_size_t cb) * * \param pv Pointer to the memory block to be deallocated * - * \remarks On failure, the function will set the thread error information, + * \note On failure, the function will set the thread error information, * which may be retrieved by the Win32 API function * ::GetLastError() * @@ -224,7 +224,7 @@ DECLARE_INTERFACE_(IMallocGcc32,IUnknown) * \return Pointer to the allocated memory block, or \c nullptr if the * request failed or cb is 0 and pv is not \c nullptr. * - * \remarks On failure, the function will set the thread error information, + * \note On failure, the function will set the thread error information, * which may be retrieved by the Win32 API function * ::GetLastError() * diff --git a/include/winstl/shims/access/string/time.hpp b/include/winstl/shims/access/string/time.hpp index 10e3c6f8..25334f45 100644 --- a/include/winstl/shims/access/string/time.hpp +++ b/include/winstl/shims/access/string/time.hpp @@ -4,13 +4,13 @@ * Purpose: Helper functions for the Windows time types. * * Created: 2nd December 2004 - * Updated: 20th March 2025 + * Updated: 15th October 2026 * * Thanks: David Wang, for spotting an error in one of the shim functions. * * 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) 2004-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -57,7 +57,7 @@ # define WINSTL_VER_WINSTL_SHIMS_ACCESS_STRING_HPP_TIME_MAJOR 2 # define WINSTL_VER_WINSTL_SHIMS_ACCESS_STRING_HPP_TIME_MINOR 3 # define WINSTL_VER_WINSTL_SHIMS_ACCESS_STRING_HPP_TIME_REVISION 18 -# define WINSTL_VER_WINSTL_SHIMS_ACCESS_STRING_HPP_TIME_EDIT 78 +# define WINSTL_VER_WINSTL_SHIMS_ACCESS_STRING_HPP_TIME_EDIT 79 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -270,7 +270,7 @@ stream_insert(S &stm, SYSTEMTIME const& t) // Because it's possible for external action to change the date // and/or time pictures between the call to calc_sizes and the // two preceeding calls, we guard against an unterminated - // C-style string by forcibly appending the nul-terminator that + // C-style string by forcibly appending the NUL character that // GetTimeFormat() will do for us normally. s.data()[cchTotal] = '\0'; } @@ -345,7 +345,7 @@ c_str_ptr_a( // Because it's possible for external action to change the date // and/or time pictures between the call to calc_sizes and the // two preceeding calls, we guard against an unterminated - // C-style string by forcibly appending the nul-terminator that + // C-style string by forcibly appending the NUL character that // GetTimeFormat() will do for us normally. s.data()[cchTotal] = '\0'; } @@ -395,7 +395,7 @@ c_str_ptr_w( // Because it's possible for external action to change the date // and/or time pictures between the call to calc_sizes and the // two preceeding calls, we guard against an unterminated - // C-style string by forcibly appending the nul-terminator that + // C-style string by forcibly appending the NUL character that // GetTimeFormat() will do for us normally. s.data()[cchTotal] = '\0'; } diff --git a/include/winstl/system/console_functions.h b/include/winstl/system/console_functions.h index 9db95fa8..9f8aa096 100644 --- a/include/winstl/system/console_functions.h +++ b/include/winstl/system/console_functions.h @@ -4,11 +4,11 @@ * Purpose: Windows console functions. * * Created: 3rd December 2005 - * Updated: 22nd August 2025 + * Updated: 11th 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) 2005-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -54,7 +54,7 @@ # define WINSTL_VER_WINSTL_SYSTEM_H_CONSOLE_FUNCTIONS_MAJOR 2 # define WINSTL_VER_WINSTL_SYSTEM_H_CONSOLE_FUNCTIONS_MINOR 6 # define WINSTL_VER_WINSTL_SYSTEM_H_CONSOLE_FUNCTIONS_REVISION 2 -# define WINSTL_VER_WINSTL_SYSTEM_H_CONSOLE_FUNCTIONS_EDIT 55 +# define WINSTL_VER_WINSTL_SYSTEM_H_CONSOLE_FUNCTIONS_EDIT 57 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -414,7 +414,7 @@ winstl_C_isatty_stm( * \param hConsole T.B.C. * \param slice Pointer to the multibyte slice to be written; * - * \pre NULL != slice + * \pre nullptr != slice */ STLSOFT_INLINE ss_truthy_t @@ -440,7 +440,7 @@ winstl_C_write_console_string_m( * \param hConsole T.B.C. * \param slice Pointer to the wide slice to be written; * - * \pre NULL != slice + * \pre nullptr != slice */ STLSOFT_INLINE ss_truthy_t @@ -467,7 +467,7 @@ winstl_C_write_console_string_w( * \param hConsole T.B.C. * \param slice Pointer to the multibyte slice to be written; * - * \pre NULL != slice + * \pre nullptr != slice */ STLSOFT_INLINE ss_truthy_t @@ -516,7 +516,7 @@ winstl_C_write_console_line_m( * \param hConsole T.B.C. * \param slice Pointer to the wide slice to be written; * - * \pre NULL != slice + * \pre nullptr != slice */ STLSOFT_INLINE ss_truthy_t @@ -675,7 +675,7 @@ isatty( * \param s Pointer to the first character in the multibyte string; * \param n Number of characters in the string; * - * \pre NULL != s || 0 == n + * \pre 0 == n || nullptr != s */ inline bool @@ -696,7 +696,7 @@ write_console_string( * \param s Pointer to the first character in the wide string; * \param n Number of characters in the string; * - * \pre NULL != s || 0 == n + * \pre 0 == n || nullptr != s */ inline bool @@ -718,7 +718,7 @@ write_console_string( * \param s Pointer to the first character in the multibyte string; * \param n Number of characters in the string; * - * \pre NULL != s || 0 == n + * \pre 0 == n || nullptr != s */ inline bool @@ -740,7 +740,7 @@ write_console_line( * \param s Pointer to the first character in the wide string; * \param n Number of characters in the string; * - * \pre NULL != s || 0 == n + * \pre 0 == n || nullptr != s */ inline bool diff --git a/include/winstl/system/system_information_functions.h b/include/winstl/system/system_information_functions.h index 3b9f19b9..4cdb3702 100644 --- a/include/winstl/system/system_information_functions.h +++ b/include/winstl/system/system_information_functions.h @@ -4,11 +4,11 @@ * Purpose: System information functions. * * Created: 5th November 2014 - * Updated: 11th March 2024 + * Updated: 15th 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. * @@ -54,7 +54,7 @@ # define WINSTL_VER_WINSTL_SYSTEM_H_SYSTEM_INFORMATION_FUNCTIONS_MAJOR 1 # define WINSTL_VER_WINSTL_SYSTEM_H_SYSTEM_INFORMATION_FUNCTIONS_MINOR 1 # define WINSTL_VER_WINSTL_SYSTEM_H_SYSTEM_INFORMATION_FUNCTIONS_REVISION 4 -# define WINSTL_VER_WINSTL_SYSTEM_H_SYSTEM_INFORMATION_FUNCTIONS_EDIT 13 +# define WINSTL_VER_WINSTL_SYSTEM_H_SYSTEM_INFORMATION_FUNCTIONS_EDIT 14 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -148,16 +148,16 @@ winstl_C_system_information_functions_MORE_DATA_( * written * \param cchBuffer Number of character spaces available in \c buffer * - * \return The number of characters excluding the nul-terminator written if + * \return The number of characters excluding the NUL character written if * cchBuffer is sufficient; the number of characters including the - * nul-terminator if cchBuffer is insufficient. + * NUL character if cchBuffer is insufficient. * * \note There is a defect in GetComputerNameA(), in that the required size * is not returned when the buffer is insufficient. This is handled by * providing an empty buffer of maximum size and then returning the actual * length (+1) * - * \pre 0 == cchBuffer || NULL != buffer + * \pre 0 == cchBuffer || nullptr != buffer */ STLSOFT_INLINE ws_size_t @@ -258,15 +258,15 @@ winstl_C_get_computer_name_w( * written * \param cchBuffer Number of character spaces available in \c buffer * - * \return The number of characters excluding the nul-terminator written if + * \return The number of characters excluding the NUL character written if * cchBuffer is sufficient; the number of characters including the - * nul-terminator if cchBuffer is insufficient. + * NUL character if cchBuffer is insufficient. * * \note GetUserNameA() has the unpleasant semantics that it returns double * the required number of characters when \c buffer is insufficient. This * is corrected in this implementation * - * \pre 0 == cchBuffer || NULL != buffer + * \pre 0 == cchBuffer || nullptr != buffer */ STLSOFT_INLINE ws_size_t diff --git a/include/winstl/system/system_traits.hpp b/include/winstl/system/system_traits.hpp index bc65f0af..a2e4ecf2 100644 --- a/include/winstl/system/system_traits.hpp +++ b/include/winstl/system/system_traits.hpp @@ -5,14 +5,14 @@ * Unicode specialisations thereof. * * Created: 15th November 2002 - * Updated: 27th May 2025 + * Updated: 15th October 2026 * * Thanks: Austin Ziegler for spotting the defective pre-condition * enforcement of expand_environment_strings(). * * 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) 2002-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -57,9 +57,9 @@ #ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION # define WINSTL_VER_WINSTL_SYSTEM_HPP_SYSTEM_TRAITS_MAJOR 6 -# define WINSTL_VER_WINSTL_SYSTEM_HPP_SYSTEM_TRAITS_MINOR 0 -# define WINSTL_VER_WINSTL_SYSTEM_HPP_SYSTEM_TRAITS_REVISION 6 -# define WINSTL_VER_WINSTL_SYSTEM_HPP_SYSTEM_TRAITS_EDIT 171 +# define WINSTL_VER_WINSTL_SYSTEM_HPP_SYSTEM_TRAITS_MINOR 1 +# define WINSTL_VER_WINSTL_SYSTEM_HPP_SYSTEM_TRAITS_REVISION 4 +# define WINSTL_VER_WINSTL_SYSTEM_HPP_SYSTEM_TRAITS_EDIT 175 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -104,6 +104,10 @@ # include #endif /* !STLSOFT_INCL_STLSOFT_UTIL_HPP_RESIZEABLE_BUFFER_HELPERS */ +#ifndef WINSTL_INCL_WINSTL_FILESYSTEM_H_PATH_PARSE_FUNCTIONS +# include +#endif /*! WINSTL_INCL_WINSTL_FILESYSTEM_H_PATH_PARSE_FUNCTIONS */ + #if STLSOFT_LEAD_VER >= 0x010a0000 # ifndef WINSTL_INCL_WINSTL_SYSTEM_H_DIRECTORY_FUNCTIONS # include @@ -266,6 +270,81 @@ struct system_traits #endif /* !NONLS */ /// @} +/// \name Process Paths +/// @{ +public: + /// Attempt to obtain the current process's path. + /// + /// \param cch The number of elements available in \c buff available for + /// writing; + /// \param buff Pointer to the buffer into which \c cch result can be + /// written. May not be \c nullptr except when \c cch is 0; + /// \param ppFile Optional pointer to receive a mutating pointer. When + /// non-nullptr, *ppFile is always set to + /// nullptr; then, if and only if the full path was + /// written into \c buff, *ppFile is set to the last + /// path-name separator in \c buff, if any; + /// + /// \return If \c buff is sufficient for the full path and a terminating + /// NUL character then this returns the length of the path (excluding + /// the NUL character). Otherwise, as much of the result as can be + /// written is done so and a character count of at least the + /// full length + 1 (for the NUL character) is returned, in order that + /// client code can allocate all required space. The returned demand + /// may exceed that minimum; + /// \retval 0 The function failed, and more information can be obtained + /// from get_last_error(); + /// + /// \note The normative client pattern is to call with \c cch of 0 to + /// obtain a sufficient size, allocate, then call again. + /// + /// \note Due to idiosynchracies of the Windows API, you must use the + /// the function to query the required length, or pass PATH_MAX, and + /// not rely on any a priori knowledge you may have of the presumed + /// process path length. + /// + /// \pre 0 == cch || nullptr != buff + static + size_type + get_current_process_path( + size_type cch + , char_type buff[/* cch */] + , char_type** ppFile + ) STLSOFT_NOEXCEPT; + + /// Attempt to obtain the current process's path into a resizeable + /// buffer. + /// + /// \param rb Reference to a resizeable buffer that will be resized as + /// required to hold the path and a terminating NUL character; + /// \param ppFile Optional pointer to receive a mutating pointer into + /// the final contents of \c rb. When non-nullptr, + /// *ppFile is set as for the raw overload, after the + /// final fill; + /// + /// \return The length of the path (excluding the NUL character) on + /// success; 0 on failure; + /// \retval 0 The function failed (query or resize). On query failure + /// \c rb is left unchanged; on resize failure + /// ERROR_OUTOFMEMORY is set and \c rb is left unchanged. + /// In neither failure case is &rb[0] taken on an empty + /// buffer; + /// + /// \note The normative pattern is a size query via the raw overload + /// with \c cch of 0, then resize, then fill — this overload performs + /// that sequence (required on Windows; see the note on the raw + /// overload). \c ppFile is computed only after the final fill. + template< + ss_typename_param_k T_resizeableBuffer + > + static + size_type + get_current_process_path( + T_resizeableBuffer& rb + , char_type** ppFile = NULL + ); +/// @} + /// \name System Paths /// @{ public: @@ -728,6 +807,70 @@ struct system_traits } #endif /* !NONLS */ +public: + static + size_type + get_current_process_path( + size_type cch + , char_type buff[/* cch */] + , char_type** ppFile + ) STLSOFT_NOEXCEPT + { + WINSTL_ASSERT(0 == cch || NULL != buff); + + if (NULL != ppFile) + { + *ppFile = NULL; + } + + size_type const n = class_type::GetModuleFileNameA(NULL, buff, cch); + + if (0 != n && + n < cch) + { + if (NULL != ppFile) + { + *ppFile = const_cast(winstl_C_find_last_path_name_separator_len_m(buff, n)); + } + } + + return n; + } + + template< + ss_typename_param_k T_resizeableBuffer + > + static + size_type + get_current_process_path( + T_resizeableBuffer& rb + , char_type** ppFile = NULL + ) + { + size_type const cchRequired = get_current_process_path( + 0 + , static_cast(NULL) + , static_cast(NULL) + ); + + if (0 == cchRequired) + { + return 0; + } + + if (rb.size() < cchRequired) + { + if (!STLSOFT_NS_QUAL(resizeable_buffer_resize)(rb, cchRequired)) + { + set_last_error(ERROR_OUTOFMEMORY); + + return 0; + } + } + + return get_current_process_path(rb.size(), &rb[0], ppFile); + } + public: static size_type @@ -1349,6 +1492,70 @@ struct system_traits } #endif /* !NONLS */ +public: + static + size_type + get_current_process_path( + size_type cch + , char_type buff[/* cch */] + , char_type** ppFile + ) STLSOFT_NOEXCEPT + { + WINSTL_ASSERT(0 == cch || NULL != buff); + + if (NULL != ppFile) + { + *ppFile = NULL; + } + + size_type const n = class_type::GetModuleFileNameW(NULL, buff, cch); + + if (0 != n && + n < cch) + { + if (NULL != ppFile) + { + *ppFile = const_cast(winstl_C_find_last_path_name_separator_len_w(buff, n)); + } + } + + return n; + } + + template< + ss_typename_param_k T_resizeableBuffer + > + static + size_type + get_current_process_path( + T_resizeableBuffer& rb + , char_type** ppFile = NULL + ) + { + size_type const cchRequired = get_current_process_path( + 0 + , static_cast(NULL) + , static_cast(NULL) + ); + + if (0 == cchRequired) + { + return 0; + } + + if (rb.size() < cchRequired) + { + if (!STLSOFT_NS_QUAL(resizeable_buffer_resize)(rb, cchRequired)) + { + set_last_error(ERROR_OUTOFMEMORY); + + return 0; + } + } + + return get_current_process_path(rb.size(), &rb[0], ppFile); + } + public: static size_type diff --git a/include/winstl/time/conversion_functions.h b/include/winstl/time/conversion_functions.h index ae58e776..208c7a4d 100644 --- a/include/winstl/time/conversion_functions.h +++ b/include/winstl/time/conversion_functions.h @@ -4,11 +4,11 @@ * Purpose: Comparison functions for Windows time structures. * * Created: 21st November 2003 - * Updated: 21st December 2024 + * Updated: 11th 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) 2003-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -54,7 +54,7 @@ # define WINSTL_VER_WINSTL_TIME_H_CONVERSION_FUNCTIONS_MAJOR 4 # define WINSTL_VER_WINSTL_TIME_H_CONVERSION_FUNCTIONS_MINOR 1 # define WINSTL_VER_WINSTL_TIME_H_CONVERSION_FUNCTIONS_REVISION 8 -# define WINSTL_VER_WINSTL_TIME_H_CONVERSION_FUNCTIONS_EDIT 69 +# define WINSTL_VER_WINSTL_TIME_H_CONVERSION_FUNCTIONS_EDIT 71 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -105,7 +105,7 @@ namespace winstl_project * * \note This follows the algorithm provided in MSDN Q167296 * - * \pre (NULL != ft) + * \pre nullptr != ft */ STLSOFT_INLINE void @@ -128,7 +128,7 @@ winstl_C_UNIXTimeToFILETIME( * * \note This follows the algorithm provided in MSDN Q167296 * - * \pre (NULL != ft) + * \pre nullptr != ft */ STLSOFT_INLINE void @@ -152,7 +152,7 @@ winstl_C_UNIXTimeToFILETIME_us( * * \note This follows the algorithm provided in MSDN Q167296 * - * \pre (NULL != ft) + * \pre nullptr != ft */ STLSOFT_INLINE time_t diff --git a/include/winstl/time/creation_functions.h b/include/winstl/time/creation_functions.h index c5e20935..d27ee74d 100644 --- a/include/winstl/time/creation_functions.h +++ b/include/winstl/time/creation_functions.h @@ -4,11 +4,11 @@ * Purpose: Creation functions for Windows time structures. * * Created: 25th February 2017 - * Updated: 24th December 2024 + * Updated: 11th 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) 2017-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -54,7 +54,7 @@ # define WINSTL_VER_WINSTL_TIME_H_CREATION_FUNCTIONS_MAJOR 1 # define WINSTL_VER_WINSTL_TIME_H_CREATION_FUNCTIONS_MINOR 0 # define WINSTL_VER_WINSTL_TIME_H_CREATION_FUNCTIONS_REVISION 2 -# define WINSTL_VER_WINSTL_TIME_H_CREATION_FUNCTIONS_EDIT 7 +# define WINSTL_VER_WINSTL_TIME_H_CREATION_FUNCTIONS_EDIT 8 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -107,9 +107,9 @@ namespace winstl_project * * \note No validation on values is performed * - * \pre (year >= 1601 && year <= 30827) - * \pre (month >= 1 && month <= 12) - * \pre (day >= 1 && day <= 31) + * \pre year >= 1601 && year <= 30827 + * \pre month >= 1 && month <= 12 + * \pre day >= 1 && day <= 31 * \pre hour < 24 * \pre minute < 60 * \pre second < 60 @@ -164,9 +164,9 @@ winstl_C_create_SYSTEMTIME_ms( * \note No validation on values is performed * * \pre nullptr != ft - * \pre (year >= 1601 && year <= 30827) - * \pre (month >= 1 && month <= 12) - * \pre (day >= 1 && day <= 31) + * \pre year >= 1601 && year <= 30827 + * \pre month >= 1 && month <= 12 + * \pre day >= 1 && day <= 31 * \pre hour < 24 * \pre minute < 60 * \pre second < 60 diff --git a/include/winstl/time/elicitation_functions.h b/include/winstl/time/elicitation_functions.h index eb75326e..7dbbdc18 100644 --- a/include/winstl/time/elicitation_functions.h +++ b/include/winstl/time/elicitation_functions.h @@ -4,11 +4,11 @@ * Purpose: Elicitation functions for Windows time structures. * * Created: 26th May 2014 - * Updated: 11th March 2024 + * Updated: 11th 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. * @@ -54,7 +54,7 @@ # define WINSTL_VER_WINSTL_TIME_H_ELICITATION_FUNCTIONS_MAJOR 2 # define WINSTL_VER_WINSTL_TIME_H_ELICITATION_FUNCTIONS_MINOR 0 # define WINSTL_VER_WINSTL_TIME_H_ELICITATION_FUNCTIONS_REVISION 1 -# define WINSTL_VER_WINSTL_TIME_H_ELICITATION_FUNCTIONS_EDIT 12 +# define WINSTL_VER_WINSTL_TIME_H_ELICITATION_FUNCTIONS_EDIT 14 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -101,7 +101,7 @@ namespace winstl_project * * \ingroup group__library__Time * - * \pre (NULL != st) + * \pre nullptr != st */ STLSOFT_INLINE void @@ -118,7 +118,7 @@ winstl_C_get_UTC_time_as_SYSTEMTIME( * * \ingroup group__library__Time * - * \pre (NULL != ft) + * \pre nullptr != ft */ STLSOFT_INLINE void @@ -135,7 +135,7 @@ winstl_C_get_UTC_time_as_FILETIME( * * \ingroup group__library__Time * - * \pre (NULL != st) + * \pre nullptr != st */ STLSOFT_INLINE void @@ -152,7 +152,7 @@ winstl_C_get_local_time_as_SYSTEMTIME( * * \ingroup group__library__Time * - * \pre (NULL != ft) + * \pre nullptr != ft */ STLSOFT_INLINE BOOL @@ -190,7 +190,7 @@ namespace winstl * * \ingroup group__library__Time * - * \pre (NULL != st) + * \pre nullptr != st */ inline void @@ -205,7 +205,7 @@ get_UTC_time_as_SYSTEMTIME( * * \ingroup group__library__Time * - * \pre (NULL != ft) + * \pre nullptr != ft */ inline void @@ -220,7 +220,7 @@ get_UTC_time_as_FILETIME( * * \ingroup group__library__Time * - * \pre (NULL != st) + * \pre nullptr != st */ inline void @@ -235,7 +235,7 @@ get_local_time_as_SYSTEMTIME( * * \ingroup group__library__Time * - * \pre (NULL != ft) + * \pre nullptr != ft */ inline void @@ -252,7 +252,7 @@ get_local_time_as_FILETIME( * * \ingroup group__library__Time * - * \pre (NULL != st) + * \pre nullptr != st */ inline SYSTEMTIME @@ -269,7 +269,7 @@ get_UTC_time_as_SYSTEMTIME() * * \ingroup group__library__Time * - * \pre (NULL != ft) + * \pre nullptr != ft */ inline FILETIME @@ -286,7 +286,7 @@ get_UTC_time_as_FILETIME() * * \ingroup group__library__Time * - * \pre (NULL != st) + * \pre nullptr != st */ inline SYSTEMTIME @@ -303,7 +303,7 @@ get_local_time_as_SYSTEMTIME() * * \ingroup group__library__Time * - * \pre (NULL != ft) + * \pre nullptr != ft */ inline FILETIME diff --git a/include/winstl/time/localisation_functions.h b/include/winstl/time/localisation_functions.h index 03eb17cc..d51ad80d 100644 --- a/include/winstl/time/localisation_functions.h +++ b/include/winstl/time/localisation_functions.h @@ -4,11 +4,11 @@ * Purpose: Localisation functions for Windows time structures. * * Created: 9th October 2014 - * Updated: 11th March 2024 + * Updated: 11th 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. * @@ -54,7 +54,7 @@ # define WINSTL_VER_WINSTL_TIME_H_LOCALISATION_FUNCTIONS_MAJOR 2 # define WINSTL_VER_WINSTL_TIME_H_LOCALISATION_FUNCTIONS_MINOR 0 # define WINSTL_VER_WINSTL_TIME_H_LOCALISATION_FUNCTIONS_REVISION 2 -# define WINSTL_VER_WINSTL_TIME_H_LOCALISATION_FUNCTIONS_EDIT 13 +# define WINSTL_VER_WINSTL_TIME_H_LOCALISATION_FUNCTIONS_EDIT 15 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -117,8 +117,8 @@ namespace winstl_project * \retval false The function failed * \retval !false The function succeeded * - * \pre (NULL != utcTime) - * \pre (NULL != localTime) + * \pre nullptr != utcTime + * \pre nullptr != localTime * * \note The caller may pass pointers to the same structure, in which case * the instance is converted in place @@ -164,8 +164,8 @@ winstl_C_localise_UTC_FILETIME_to_local_FILETIME( * \retval false The function failed * \retval !false The function succeeded * - * \pre (NULL != localTime) - * \pre (NULL != utcTime) + * \pre nullptr != localTime + * \pre nullptr != utcTime * * \note The caller may pass pointers to the same structure, in which case * the instance is converted in place @@ -229,8 +229,8 @@ namespace winstl * \retval false The function failed * \retval !false The function succeeded * - * \pre (NULL != utcTime) - * \pre (NULL != localTime) + * \pre nullptr != utcTime + * \pre nullptr != localTime * * \note The caller may pass pointers to the same structure, in which case * the instance is converted in place @@ -275,8 +275,8 @@ localise_UTC_time_to_local_time( * \retval false The function failed * \retval !false The function succeeded * - * \pre (NULL != localTime) - * \pre (NULL != utcTime) + * \pre nullptr != localTime + * \pre nullptr != utcTime * * \note The caller may pass pointers to the same structure, in which case * the instance is converted in place @@ -321,7 +321,7 @@ localise_local_time_to_UTC_time( * * \return The local time * - * \pre (NULL != utcTime) + * \pre nullptr != utcTime * * \exception winstl::conversion_error Thrown if the conversion cannot be * performed @@ -365,7 +365,7 @@ localise_UTC_time_to_local_time( * * \return The local time * - * \pre (NULL != utcTime) + * \pre nullptr != utcTime * * \exception winstl::conversion_error Thrown if the conversion cannot be * performed diff --git a/include/winstl/time/modification_functions.h b/include/winstl/time/modification_functions.h index 315901e1..016a9c7e 100644 --- a/include/winstl/time/modification_functions.h +++ b/include/winstl/time/modification_functions.h @@ -4,11 +4,11 @@ * Purpose: Modification functions for Windows time structures. * * Created: 2nd February 2011 - * Updated: 24th December 2024 + * Updated: 11th 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) 2011-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -54,7 +54,7 @@ # define WINSTL_VER_WINSTL_TIME_H_MODIFICATION_FUNCTIONS_MAJOR 2 # define WINSTL_VER_WINSTL_TIME_H_MODIFICATION_FUNCTIONS_MINOR 0 # define WINSTL_VER_WINSTL_TIME_H_MODIFICATION_FUNCTIONS_REVISION 1 -# define WINSTL_VER_WINSTL_TIME_H_MODIFICATION_FUNCTIONS_EDIT 14 +# define WINSTL_VER_WINSTL_TIME_H_MODIFICATION_FUNCTIONS_EDIT 16 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -121,8 +121,8 @@ namespace winstl_project * NULL, and no validity checking is performed on the offset * parameter values. * - * \pre (NULL != result) - * \pre (NULL != origin) + * \pre nullptr != result + * \pre nullptr != origin */ STLSOFT_INLINE void @@ -191,8 +191,8 @@ winstl_C_increment_FILETIME_us( * \c nullptr, and no validity checking is performed on the offset * parameter values. * - * \pre (NULL != result) - * \pre (NULL != origin) + * \pre nullptr != result + * \pre nullptr != origin */ STLSOFT_INLINE void diff --git a/include/winstl/winstl.h b/include/winstl/winstl.h index 592659ec..441af00c 100644 --- a/include/winstl/winstl.h +++ b/include/winstl/winstl.h @@ -5,7 +5,7 @@ * platform discriminations, and definitions of types. * * Created: 15th January 2002 - * Updated: 8th October 2026 + * Updated: 17th October 2026 * * Home: http://stlsoft.org/ * @@ -50,8 +50,8 @@ #ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION # define WINSTL_VER_WINSTL_H_WINSTL_MAJOR 3 # define WINSTL_VER_WINSTL_H_WINSTL_MINOR 18 -# define WINSTL_VER_WINSTL_H_WINSTL_REVISION 15 -# define WINSTL_VER_WINSTL_H_WINSTL_EDIT 245 +# define WINSTL_VER_WINSTL_H_WINSTL_REVISION 16 +# define WINSTL_VER_WINSTL_H_WINSTL_EDIT 247 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ /** \file winstl/winstl.h @@ -185,12 +185,13 @@ # define _WINSTL_VER_1_13_0_B02 0x010d0082 /*!< Version 1.13.0 beta 2 (with STLSoft 1.11.1 rc 4) */ # define _WINSTL_VER_1_13_0_B03 0x010d0083 /*!< Version 1.13.0 beta 3 (with STLSoft 1.11.1 rc 7) */ # define _WINSTL_VER_1_13_0_B04 0x010d0084 /*!< Version 1.13.0 beta 4 (with STLSoft 1.11.1 rc 8) */ +# define _WINSTL_VER_1_13_0_B05 0x010d0085 /*!< Version 1.13.0 beta 5 (with STLSoft 1.11.1 rc 9) */ #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ #define _WINSTL_VER_MAJOR 1 #define _WINSTL_VER_MINOR 13 #define _WINSTL_VER_PATCH 0 -#define _WINSTL_VER_ALPHABETA 0x84 +#define _WINSTL_VER_ALPHABETA 0x85 #define _WINSTL_VER \ (0\ @@ -291,8 +292,8 @@ * STLSoft version compatibility check(s) */ -#if _STLSOFT_VER < 0x010B01C8 -# error This version of the WinSTL libraries requires STLSoft version 1.11.1 rc 8, or later +#if _STLSOFT_VER < 0x010B01C9 +# error This version of the WinSTL libraries requires STLSoft version 1.11.1 rc 9, or later #endif /* _STLSOFT_VER */ @@ -631,7 +632,7 @@ x86-64 * * \param expr Must be non-zero, or an assertion will be fired * - * \remarks By default this is defined to \ref STLSOFT_ASSERT. However, this + * \note By default this is defined to \ref STLSOFT_ASSERT. However, this * can be overriden if a prior definition is encountered, allowing the * runtime assertion of WinSTL components to use a different mechanism to * those in the other \ref group__projects "projects". @@ -653,7 +654,7 @@ x86-64 * * \param expr A compile-time evaluatable condition that must be non-zero, or compilation will fail. * - * \remarks This is defined to \ref STLSOFT_STATIC_ASSERT. + * \note This is defined to \ref STLSOFT_STATIC_ASSERT. */ #define WINSTL_STATIC_ASSERT(expr) STLSOFT_STATIC_ASSERT(expr) @@ -841,7 +842,7 @@ int main() } \endcode * - * \remarks These macros are used throughout the implementation of the + * \note These macros are used throughout the implementation of the * STLSoft libraries. However, we do not recommend their use in application * code for the simple reason that they are ugly and do not represent a * widely recognised idiom. Of course, if they suit your purposes, then by diff --git a/test/component/stlsoft/system/test.component.stlsoft.system.environment_variable_exists/CMakeLists.txt b/test/component/stlsoft/system/test.component.stlsoft.system.environment_variable_exists/CMakeLists.txt deleted file mode 100644 index 9107eda8..00000000 --- a/test/component/stlsoft/system/test.component.stlsoft.system.environment_variable_exists/CMakeLists.txt +++ /dev/null @@ -1,2 +0,0 @@ -# SIS:AUTO_GENERATED: Remove this line if you edit the file, otherwise it will be overwritten -define_automated_test_program(test.component.stlsoft.system.environment_variable_exists entry.cpp) diff --git a/test/component/stlsoft/system/test.component.stlsoft.system.environment_variable_exists/entry.cpp b/test/component/stlsoft/system/test.component.stlsoft.system.environment_variable_exists/entry.cpp deleted file mode 100644 index 7f7bbca0..00000000 --- a/test/component/stlsoft/system/test.component.stlsoft.system.environment_variable_exists/entry.cpp +++ /dev/null @@ -1,259 +0,0 @@ -/* ///////////////////////////////////////////////////////////////////////// - * File: test.component.stlsoft.system.environment_variable_exists/entry.cpp - * - * Purpose: Component-tests for `stlsoft::environment_variable_exists()`. - * - * Created: 28th September 2026 - * Updated: 28th September 2026 - * - * ////////////////////////////////////////////////////////////////////// */ - - -/* ///////////////////////////////////////////////////////////////////////// - * includes - */ - -/* ///////////////////////////////////// - * test component header file include(s) - */ - -/* String-access shims must be visible before functions.hpp so the template - * overload can bind c_str_ptr() for these types. - */ -#include -#include -#include - -/* ///////////////////////////////////// - * general includes - */ - -/* xTests header files */ -#include -#include - -/* STLSoft header files */ -#include -#include - -/* Standard C++ header files */ -#include - -/* Standard C header files */ -#include - - -/* ///////////////////////////////////////////////////////////////////////// - * forward declarations - */ - -namespace { - - static void TEST_environment_variable_exists_WHEN_ABSENT(); - static void TEST_environment_variable_exists_WHEN_PRESENT(); - static void TEST_environment_variable_exists_WHEN_ERASED(); - static void TEST_environment_variable_exists_WHEN_VALUE_REPLACED(); - static void TEST_environment_variable_exists_EXACT_NAME(); - static void TEST_environment_variable_exists_WITH_std_string(); - static void TEST_environment_variable_exists_WITH_simple_string(); -#ifndef _WIN32 - static void TEST_environment_variable_exists_WHEN_EMPTY(); -#endif /* !_WIN32 */ - static void TEST_environment_variable_exists_CASE_SENSITIVITY(); -} // anonymous namespace - - -/* ///////////////////////////////////////////////////////////////////////// - * main() - */ - -int main(int argc, char* argv[]) -{ - int retCode = EXIT_SUCCESS; - int verbosity = 2; - - XTESTS_COMMANDLINE_PARSEVERBOSITY(argc, argv, &verbosity); - - if (XTESTS_START_RUNNER("test.component.stlsoft.system.environment_variable_exists", verbosity)) - { - XTESTS_RUN_CASE(TEST_environment_variable_exists_WHEN_ABSENT); - XTESTS_RUN_CASE(TEST_environment_variable_exists_WHEN_PRESENT); - XTESTS_RUN_CASE(TEST_environment_variable_exists_WHEN_ERASED); - XTESTS_RUN_CASE(TEST_environment_variable_exists_WHEN_VALUE_REPLACED); - XTESTS_RUN_CASE(TEST_environment_variable_exists_EXACT_NAME); - XTESTS_RUN_CASE(TEST_environment_variable_exists_WITH_std_string); - XTESTS_RUN_CASE(TEST_environment_variable_exists_WITH_simple_string); -#ifndef _WIN32 - XTESTS_RUN_CASE(TEST_environment_variable_exists_WHEN_EMPTY); -#endif /* !_WIN32 */ - XTESTS_RUN_CASE(TEST_environment_variable_exists_CASE_SENSITIVITY); - - XTESTS_PRINT_RESULTS(); - - XTESTS_END_RUNNER_UPDATE_EXITCODE(&retCode); - } - - return retCode; -} - - -/* ///////////////////////////////////////////////////////////////////////// - * constants - */ - -namespace { - - using platformstl::environment_variable_scope; - - char const VAR_NAME[] = "STLSOFT_CT_ENV_VAR_EXISTS"; - char const VAR_NAME_EXTRA[] = "STLSOFT_CT_ENV_VAR_EXISTS_EXTRA"; - char const VAR_NAME_PREFIX[] = "STLSOFT_CT_ENV_VAR"; - char const VAR_NAME_UPPER[] = "STLSOFT_CT_ENV_VAR_EXISTS_CASE"; - char const VAR_NAME_LOWER[] = "stlsoft_ct_env_var_exists_case"; -} // anonymous namespace - - -/* ///////////////////////////////////////////////////////////////////////// - * test function implementations - */ - -namespace { - -static void TEST_environment_variable_exists_WHEN_ABSENT() -{ - environment_variable_scope const absent(VAR_NAME, ss_nullptr_k); - - char const* const name = VAR_NAME; - - TEST_BOOLEAN_FALSE(stlsoft::environment_variable_exists(name)); - TEST_BOOLEAN_FALSE(stlsoft::stlsoft_C_environment_variable_exists_m(name)); - TEST_BOOLEAN_FALSE(stlsoft::environment_variable_exists("STLSOFT_CT_ENV_VAR_EXISTS_NO_SUCH")); -} - -static void TEST_environment_variable_exists_WHEN_PRESENT() -{ - environment_variable_scope const present(VAR_NAME, "present"); - - char const* const name = VAR_NAME; - - TEST_BOOLEAN_TRUE(stlsoft::environment_variable_exists(name)); - TEST_BOOLEAN_TRUE(stlsoft::stlsoft_C_environment_variable_exists_m(name)); -} - -static void TEST_environment_variable_exists_WHEN_ERASED() -{ - environment_variable_scope const present(VAR_NAME, "present"); - - TEST_BOOLEAN_TRUE(stlsoft::environment_variable_exists(VAR_NAME)); - - environment_variable_scope const erased(VAR_NAME, ss_nullptr_k); - - char const* const name = VAR_NAME; - - TEST_BOOLEAN_FALSE(stlsoft::environment_variable_exists(name)); -} - -static void TEST_environment_variable_exists_WHEN_VALUE_REPLACED() -{ - environment_variable_scope const first(VAR_NAME, "one"); - - char const* const name = VAR_NAME; - - TEST_BOOLEAN_TRUE(stlsoft::environment_variable_exists(name)); - - environment_variable_scope const second(VAR_NAME, "two"); - - TEST_BOOLEAN_TRUE(stlsoft::environment_variable_exists(name)); -} - -static void TEST_environment_variable_exists_EXACT_NAME() -{ - environment_variable_scope const extra_absent(VAR_NAME_EXTRA, ss_nullptr_k); - environment_variable_scope const prefix_absent(VAR_NAME_PREFIX, ss_nullptr_k); - environment_variable_scope const present(VAR_NAME, "value"); - - TEST_BOOLEAN_TRUE(stlsoft::environment_variable_exists(VAR_NAME)); - TEST_BOOLEAN_FALSE(stlsoft::environment_variable_exists(VAR_NAME_EXTRA)); - TEST_BOOLEAN_FALSE(stlsoft::environment_variable_exists(VAR_NAME_PREFIX)); - - environment_variable_scope const erased(VAR_NAME, ss_nullptr_k); - environment_variable_scope const extra(VAR_NAME_EXTRA, "extra"); - - TEST_BOOLEAN_FALSE(stlsoft::environment_variable_exists(VAR_NAME)); - TEST_BOOLEAN_TRUE(stlsoft::environment_variable_exists(VAR_NAME_EXTRA)); -} - -static void TEST_environment_variable_exists_WITH_std_string() -{ - { - environment_variable_scope const absent(VAR_NAME, ss_nullptr_k); - - std::string const name(VAR_NAME); - - TEST_BOOLEAN_FALSE(stlsoft::environment_variable_exists(name)); - } - - environment_variable_scope const present(VAR_NAME, "present"); - - std::string const name(VAR_NAME); - - TEST_BOOLEAN_TRUE(stlsoft::environment_variable_exists(name)); -} - -static void TEST_environment_variable_exists_WITH_simple_string() -{ - { - environment_variable_scope const absent(VAR_NAME, ss_nullptr_k); - - stlsoft::simple_string const name(VAR_NAME); - - TEST_BOOLEAN_FALSE(stlsoft::environment_variable_exists(name)); - } - - environment_variable_scope const present(VAR_NAME, "present"); - - stlsoft::simple_string const name(VAR_NAME); - - TEST_BOOLEAN_TRUE(stlsoft::environment_variable_exists(name)); -} -#ifndef _WIN32 - -/* An empty value is a defined variable on UNIX. The Windows CRT treats an - * empty assignment as erasure, so this case is UNIX-only. - */ -static void TEST_environment_variable_exists_WHEN_EMPTY() -{ - environment_variable_scope const empty(VAR_NAME, ""); - - char const* const value = ::getenv(VAR_NAME); - - XTESTS_REQUIRE(TEST_PTR_NE(NULL, value)); - TEST_MS_EQ("", value); - - char const* const name = VAR_NAME; - - TEST_BOOLEAN_TRUE(stlsoft::environment_variable_exists(name)); -} -#endif /* !_WIN32 */ - -/* UNIX names are case-sensitive; the Windows CRT folds case. - */ -static void TEST_environment_variable_exists_CASE_SENSITIVITY() -{ - environment_variable_scope const lower(VAR_NAME_LOWER, ss_nullptr_k); - environment_variable_scope const upper(VAR_NAME_UPPER, "1"); - - TEST_BOOLEAN_TRUE(stlsoft::environment_variable_exists(VAR_NAME_UPPER)); -#ifdef _WIN32 - - TEST_BOOLEAN_TRUE(stlsoft::environment_variable_exists(VAR_NAME_LOWER)); -#else - - TEST_BOOLEAN_FALSE(stlsoft::environment_variable_exists(VAR_NAME_LOWER)); -#endif -} -} // anonymous namespace - - -/* ///////////////////////////// end of file //////////////////////////// */ - diff --git a/test/component/unixstl/system/CMakeLists.txt b/test/component/unixstl/system/CMakeLists.txt index eefe07f3..dfc29b03 100644 --- a/test/component/unixstl/system/CMakeLists.txt +++ b/test/component/unixstl/system/CMakeLists.txt @@ -1,2 +1,4 @@ # SIS:AUTO_GENERATED: Remove this line if you edit the file, otherwise it will be overwritten add_subdirectory(environment_variable) +add_subdirectory(process_paths) +add_subdirectory(system_traits) diff --git a/test/component/unixstl/system/process_paths/CMakeLists.txt b/test/component/unixstl/system/process_paths/CMakeLists.txt new file mode 100644 index 00000000..cadc56ac --- /dev/null +++ b/test/component/unixstl/system/process_paths/CMakeLists.txt @@ -0,0 +1,2 @@ +# SIS:AUTO_GENERATED: Remove this line if you edit the file, otherwise it will be overwritten +define_automated_test_program(test.component.unixstl.system.process_paths entry.cpp) diff --git a/test/component/unixstl/system/process_paths/entry.cpp b/test/component/unixstl/system/process_paths/entry.cpp new file mode 100644 index 00000000..f32271f4 --- /dev/null +++ b/test/component/unixstl/system/process_paths/entry.cpp @@ -0,0 +1,562 @@ +/* ///////////////////////////////////////////////////////////////////////// + * File: test/component/unixstl/system/process_paths/entry.cpp + * + * Purpose: Component-tests for + * `unixstl::system_traits::get_current_process_path()` (multibyte), + * including resizeable-buffer overloads. + * + * Created: 15th October 2026 + * Updated: 18th October 2026 + * + * ////////////////////////////////////////////////////////////////////// */ + + +/* ///////////////////////////////////////////////////////////////////////// + * includes + */ + +/* ///////////////////////////////////// + * test component header file include(s) + */ + +#include + +/* ///////////////////////////////////// + * general includes + */ + +/* xTests header files */ +#include +#include + +/* STLSoft header files */ +#include +#include + +/* Standard C++ header files */ +#include +#include + +/* Standard C header files */ +#include +#include +#include +#include + +#if 0 +#elif defined(_WIN32) + +# include +#elif defined(__APPLE__) + +# include +# include +# include +#elif defined(__linux__) + +# include +#elif 0 ||\ + defined(__FreeBSD__) ||\ + defined(__NetBSD__) ||\ + defined(__OpenBSD__) ||\ + 0 + +# include +# include +#elif defined(__sun) + +# include +#endif + +#if !defined(PATH_MAX) +# define PATH_MAX 4096 +#endif + + +/* ///////////////////////////////////////////////////////////////////////// + * forward declarations + */ + +namespace { + + static void TEST_SIZE_QUERY(); + static void TEST_EXACT_FIT(); + static void TEST_EXCESS_SPACE(); + static void TEST_INSUFFICIENT_SPACE(); + static void TEST_ppFile_NULL_ON_SUCCESS(); + static void TEST_ppFile_separator_on_success(); + static void TEST_ppFile_NULL_WHEN_INSUFFICIENT(); + static void TEST_RESIZEABLE_auto_buffer_SUCCESS(); + static void TEST_RESIZEABLE_vector_SUCCESS(); + static void TEST_RESIZEABLE_ppFile_NULL(); + static void TEST_RESIZEABLE_ppFile_separator(); + static void TEST_RESIZEABLE_resize_FAILURE_leaves_rb_untouched(); +} // anonymous namespace + + +/* ///////////////////////////////////////////////////////////////////////// + * main() + */ + +int main(int argc, char* argv[]) +{ + int retCode = EXIT_SUCCESS; + int verbosity = 2; + + XTESTS_COMMANDLINE_PARSEVERBOSITY(argc, argv, &verbosity); + + if (XTESTS_START_RUNNER("test.component.unixstl.system.process_paths", verbosity)) + { + XTESTS_RUN_CASE(TEST_SIZE_QUERY); + XTESTS_RUN_CASE(TEST_EXACT_FIT); + XTESTS_RUN_CASE(TEST_EXCESS_SPACE); + XTESTS_RUN_CASE(TEST_INSUFFICIENT_SPACE); + XTESTS_RUN_CASE(TEST_ppFile_NULL_ON_SUCCESS); + XTESTS_RUN_CASE(TEST_ppFile_separator_on_success); + XTESTS_RUN_CASE(TEST_ppFile_NULL_WHEN_INSUFFICIENT); + XTESTS_RUN_CASE(TEST_RESIZEABLE_auto_buffer_SUCCESS); + XTESTS_RUN_CASE(TEST_RESIZEABLE_vector_SUCCESS); + XTESTS_RUN_CASE(TEST_RESIZEABLE_ppFile_NULL); + XTESTS_RUN_CASE(TEST_RESIZEABLE_ppFile_separator); + XTESTS_RUN_CASE(TEST_RESIZEABLE_resize_FAILURE_leaves_rb_untouched); + + XTESTS_PRINT_RESULTS(); + + XTESTS_END_RUNNER_UPDATE_EXITCODE(&retCode); + } + + return retCode; +} + + +/* ///////////////////////////////////////////////////////////////////////// + * helpers + */ + +namespace { + +typedef unixstl::filesystem_traits fs_traits_m_t; +typedef unixstl::system_traits traits_m_t; + +/** Retrieves the full path of the current executable from the ambient OS + * API (not via STLSoft). + * + * \return 0 on success; -1 on failure. + */ +static +int +get_executable_path_( + char* path +, size_t size +) +{ + if (NULL == path || + 0 == size) + { + return -1; + } + +#if 0 +#elif defined(_WIN32) + + /* Windows / UNIXem: GetModuleFileNameA */ + { + DWORD const len = ::GetModuleFileNameA(NULL, path, static_cast(size - 1)); + + if (0 == len) + { + return -1; + } + + if (len == static_cast(size - 1) && + ERROR_INSUFFICIENT_BUFFER == ::GetLastError()) + { + return -1; + } + + path[len] = '\0'; + + return 0; + } +#elif defined(__APPLE__) + + /* macOS: prefer proc_pidpath; fallback to _NSGetExecutablePath (+ realpath). */ + { + pid_t const pid = ::getpid(); + int const ret = ::proc_pidpath(pid, path, static_cast(size)); + + if (ret <= 0) + { + uint32_t len = static_cast(size); + + if (0 != ::_NSGetExecutablePath(path, &len)) + { + return -1; + } + + { + char* const resolved = ::realpath(path, NULL); + + if (NULL != resolved) + { + ::strncpy(path, resolved, size - 1); + path[size - 1] = '\0'; + ::free(resolved); + } + } + } + + return 0; + } +#elif defined(__linux__) + + /* Linux: readlink("/proc/self/exe") */ + { + ssize_t const len = ::readlink("/proc/self/exe", path, size - 1); + + if (-1 == len) + { + return -1; + } + + path[len] = '\0'; + + return 0; + } +#elif 0 || \ + defined(__FreeBSD__) ||\ + defined(__NetBSD__) ||\ + defined(__OpenBSD__) ||\ + 0 + + /* BSD: sysctl(KERN_PROC_PATHNAME) */ + { + int mib[4]; + size_t len = size - 1; + + mib[0] = CTL_KERN; + mib[1] = KERN_PROC; + mib[2] = KERN_PROC_PATHNAME; + mib[3] = -1; + + if (0 != ::sysctl(mib, 4, path, &len, NULL, 0)) + { + return -1; + } + + path[len] = '\0'; + + return 0; + } +#elif defined(__sun) + + /* Solaris: getexecname() + realpath() */ + { + char const* const exe = ::getexecname(); + + if (NULL == exe) + { + return -1; + } + + if (NULL == ::realpath(exe, path)) + { + return -1; + } + + return 0; + } +#else + + STLSOFT_SUPPRESS_UNUSED(path); + STLSOFT_SUPPRESS_UNUSED(size); + + return -1; +#endif +} + +/** Obtains the current process image path from the ambient OS API, without + * going through STLSoft. + */ +static +std::string +obtain_raw_current_process_path() +{ + char path[PATH_MAX]; + + if (0 != get_executable_path_(path, sizeof(path))) + { + return std::string(); + } + + return std::string(path); +} + +static +char* +invalid_file_pointer() +{ + return reinterpret_cast(static_cast(-1)); +} + +/** Minimal resizeable buffer whose #resize() always fails. */ +struct fail_on_resize_buffer +{ + typedef char value_type; + + std::vector storage; + + size_t size() const + { + return storage.size(); + } + + char& operator [](size_t i) + { + return storage[i]; + } + + char const& operator [](size_t i) const + { + return storage[i]; + } + + bool resize(size_t /* newSize */) + { + return false; + } +}; +} // anonymous namespace + + +/* ///////////////////////////////////////////////////////////////////////// + * test function implementations + */ + +namespace { + +static void TEST_SIZE_QUERY() +{ + std::string const expected = obtain_raw_current_process_path(); + + XTESTS_REQUIRE(TEST_BOOLEAN_TRUE(!expected.empty())); + + char* pFile = invalid_file_pointer(); + size_t const cch = traits_m_t::get_current_process_path(0, NULL, &pFile); + + TEST_INT_EQ(expected.size() + 1, cch); + TEST_PTR_EQ(NULL, pFile); +} + +static void TEST_EXACT_FIT() +{ + std::string const expected = obtain_raw_current_process_path(); + + XTESTS_REQUIRE(TEST_BOOLEAN_TRUE(!expected.empty())); + + size_t const len = expected.size(); + stlsoft::auto_buffer buff(len + 1); + char* pFile = invalid_file_pointer(); + size_t const cch = traits_m_t::get_current_process_path(buff.size(), &buff[0], &pFile); + + TEST_INT_EQ(len, cch); + TEST_MS_EQ(expected.c_str(), &buff[0]); + TEST_CHAR_EQ('\0', buff[len]); +} + +static void TEST_EXCESS_SPACE() +{ + std::string const expected = obtain_raw_current_process_path(); + + XTESTS_REQUIRE(TEST_BOOLEAN_TRUE(!expected.empty())); + + size_t const len = expected.size(); + stlsoft::auto_buffer buff(len + 64); + + ::memset(&buff[0], '~', buff.size()); + + char* pFile = invalid_file_pointer(); + size_t const cch = traits_m_t::get_current_process_path(buff.size(), &buff[0], &pFile); + + TEST_INT_EQ(len, cch); + TEST_MS_EQ(expected.c_str(), &buff[0]); + TEST_CHAR_EQ('\0', buff[len]); +} + +static void TEST_INSUFFICIENT_SPACE() +{ + std::string const expected = obtain_raw_current_process_path(); + + XTESTS_REQUIRE(TEST_BOOLEAN_TRUE(!expected.empty())); + + size_t const len = expected.size(); + + /* One character short of an exact fit. */ + { + size_t const cchBuff = len; + stlsoft::auto_buffer buff(cchBuff); + + ::memset(&buff[0], '~', buff.size()); + + char* pFile = invalid_file_pointer(); + size_t const cch = traits_m_t::get_current_process_path(buff.size(), &buff[0], &pFile); + + TEST_INT_EQ(len + 1, cch); + TEST_PTR_EQ(NULL, pFile); + TEST_CHAR_EQ('\0', buff[cchBuff - 1]); + TEST_MS_EQ_N(expected.c_str(), &buff[0], cchBuff - 1); + } + + /* Single-character buffer: only the terminating NUL. */ + { + char buff[1] = { '~' }; + char* pFile = invalid_file_pointer(); + size_t const cch = traits_m_t::get_current_process_path(STLSOFT_NUM_ELEMENTS(buff), buff, &pFile); + + TEST_INT_EQ(len + 1, cch); + TEST_PTR_EQ(NULL, pFile); + TEST_CHAR_EQ('\0', buff[0]); + } +} + +static void TEST_ppFile_NULL_ON_SUCCESS() +{ + std::string const expected = obtain_raw_current_process_path(); + + XTESTS_REQUIRE(TEST_BOOLEAN_TRUE(!expected.empty())); + + stlsoft::auto_buffer buff(expected.size() + 1); + size_t const cch = traits_m_t::get_current_process_path(buff.size(), &buff[0], NULL); + + TEST_INT_EQ(expected.size(), cch); + TEST_MS_EQ(expected.c_str(), &buff[0]); +} + +static void TEST_ppFile_separator_on_success() +{ + std::string const expected = obtain_raw_current_process_path(); + + XTESTS_REQUIRE(TEST_BOOLEAN_TRUE(!expected.empty())); + + stlsoft::auto_buffer buff(expected.size() + 1); + char* pFile = invalid_file_pointer(); + size_t const cch = traits_m_t::get_current_process_path(buff.size(), &buff[0], &pFile); + + TEST_INT_EQ(expected.size(), cch); + TEST_MS_EQ(expected.c_str(), &buff[0]); + + char const* const expectedSep = fs_traits_m_t::find_last_path_name_separator(&buff[0]); + + TEST_PTR_EQ(expectedSep, pFile); + + if (NULL != pFile) + { + TEST_MS_EQ(expectedSep + 1, pFile + 1); + } +} + +static void TEST_ppFile_NULL_WHEN_INSUFFICIENT() +{ + std::string const expected = obtain_raw_current_process_path(); + + XTESTS_REQUIRE(TEST_BOOLEAN_TRUE(!expected.empty())); + + size_t const len = expected.size(); + stlsoft::auto_buffer buff(len); /* one short */ + char* pFile = invalid_file_pointer(); + size_t const cch = traits_m_t::get_current_process_path(buff.size(), &buff[0], &pFile); + + TEST_INT_EQ(len + 1, cch); + TEST_PTR_EQ(NULL, pFile); +} + +static void TEST_RESIZEABLE_auto_buffer_SUCCESS() +{ + std::string const expected = obtain_raw_current_process_path(); + + XTESTS_REQUIRE(TEST_BOOLEAN_TRUE(!expected.empty())); + + stlsoft::auto_buffer rb(0); + size_t const cch = traits_m_t::get_current_process_path(rb); + + TEST_INT_EQ(expected.size(), cch); + TEST_INT_GE(expected.size() + 1, rb.size()); + TEST_MS_EQ(expected.c_str(), &rb[0]); +} + +static void TEST_RESIZEABLE_vector_SUCCESS() +{ + std::string const expected = obtain_raw_current_process_path(); + + XTESTS_REQUIRE(TEST_BOOLEAN_TRUE(!expected.empty())); + + std::vector rb; + size_t const cch = traits_m_t::get_current_process_path(rb); + + TEST_INT_EQ(expected.size(), cch); + TEST_INT_GE(expected.size() + 1, rb.size()); + TEST_MS_EQ(expected.c_str(), &rb[0]); +} + +static void TEST_RESIZEABLE_ppFile_NULL() +{ + std::string const expected = obtain_raw_current_process_path(); + + XTESTS_REQUIRE(TEST_BOOLEAN_TRUE(!expected.empty())); + + stlsoft::auto_buffer rb(0); + size_t const cch = traits_m_t::get_current_process_path(rb, NULL); + + TEST_INT_EQ(expected.size(), cch); + TEST_MS_EQ(expected.c_str(), &rb[0]); +} + +static void TEST_RESIZEABLE_ppFile_separator() +{ + std::string const expected = obtain_raw_current_process_path(); + + XTESTS_REQUIRE(TEST_BOOLEAN_TRUE(!expected.empty())); + + stlsoft::auto_buffer rb(0); + char* pFile = invalid_file_pointer(); + size_t const cch = traits_m_t::get_current_process_path(rb, &pFile); + + TEST_INT_EQ(expected.size(), cch); + TEST_MS_EQ(expected.c_str(), &rb[0]); + + char const* const expectedSep = fs_traits_m_t::find_last_path_name_separator(&rb[0]); + + TEST_PTR_EQ(expectedSep, pFile); + + if (NULL != pFile) + { + TEST_MS_EQ(expectedSep + 1, pFile + 1); + } +} + +static void TEST_RESIZEABLE_resize_FAILURE_leaves_rb_untouched() +{ + fail_on_resize_buffer rb; + + rb.storage.assign(4, 'X'); + + size_t const priorSize = rb.size(); + int const priorErrno = errno; + + errno = 0; + + size_t const cch = traits_m_t::get_current_process_path(rb); + + TEST_INT_EQ(0, cch); + TEST_INT_EQ(ENOMEM, errno); + TEST_INT_EQ(priorSize, rb.size()); + TEST_CHAR_EQ('X', rb.storage[0]); + TEST_CHAR_EQ('X', rb.storage[3]); + + errno = priorErrno; +} +} // anonymous namespace + + +/* ///////////////////////////// end of file //////////////////////////// */ + diff --git a/test/component/unixstl/system/system_traits/CMakeLists.txt b/test/component/unixstl/system/system_traits/CMakeLists.txt new file mode 100644 index 00000000..abafd193 --- /dev/null +++ b/test/component/unixstl/system/system_traits/CMakeLists.txt @@ -0,0 +1,2 @@ +# SIS:AUTO_GENERATED: Remove this line if you edit the file, otherwise it will be overwritten +define_automated_test_program(test.component.unixstl.system.system_traits entry.cpp) diff --git a/test/component/unixstl/system/system_traits/entry.cpp b/test/component/unixstl/system/system_traits/entry.cpp new file mode 100644 index 00000000..afcec26c --- /dev/null +++ b/test/component/unixstl/system/system_traits/entry.cpp @@ -0,0 +1,232 @@ +/* ///////////////////////////////////////////////////////////////////////// + * File: test/component/unixstl/system/system_traits/entry.cpp + * + * Purpose: Component-tests for `unixstl::system_traits` — ANSI + * resizeable-buffer overloads (`get_home_directory`, + * `get_environment_variable`) and wide home / environment APIs. + * + * Created: 15th October 2026 + * Updated: 15th October 2026 + * + * ////////////////////////////////////////////////////////////////////// */ + + +/* ///////////////////////////////////////////////////////////////////////// + * includes + */ + +/* ///////////////////////////////////// + * test component header file include(s) + */ + +#include + +/* ///////////////////////////////////// + * general includes + */ + +/* xTests header files */ +#include +#include + +/* STLSoft header files */ +#include +#include +#include + +/* Standard C++ header files */ +#include + +/* Standard C header files */ +#include +#include +#include + + +/* ///////////////////////////////////////////////////////////////////////// + * forward declarations + */ + +namespace { + + static void TEST_get_environment_variable_MISSING(); + static void TEST_get_environment_variable_RESIZEABLE_auto_buffer(); + static void TEST_get_environment_variable_RESIZEABLE_vector(); + static void TEST_get_environment_variable_w(); + static void TEST_get_home_directory_RESIZEABLE_auto_buffer(); + static void TEST_get_home_directory_RESIZEABLE_vector(); + static void TEST_get_home_directory_w(); +} // anonymous namespace + + +/* ///////////////////////////////////////////////////////////////////////// + * main() + */ + +int main(int argc, char* argv[]) +{ + int retCode = EXIT_SUCCESS; + int verbosity = 2; + + XTESTS_COMMANDLINE_PARSEVERBOSITY(argc, argv, &verbosity); + + if (XTESTS_START_RUNNER("test.component.unixstl.system.system_traits", verbosity)) + { + XTESTS_RUN_CASE(TEST_get_environment_variable_MISSING); + XTESTS_RUN_CASE(TEST_get_environment_variable_RESIZEABLE_auto_buffer); + XTESTS_RUN_CASE(TEST_get_environment_variable_RESIZEABLE_vector); + XTESTS_RUN_CASE(TEST_get_environment_variable_w); + XTESTS_RUN_CASE(TEST_get_home_directory_RESIZEABLE_auto_buffer); + XTESTS_RUN_CASE(TEST_get_home_directory_RESIZEABLE_vector); + XTESTS_RUN_CASE(TEST_get_home_directory_w); + + XTESTS_PRINT_RESULTS(); + + XTESTS_END_RUNNER_UPDATE_EXITCODE(&retCode); + } + + return retCode; +} + + +/* ///////////////////////////////////////////////////////////////////////// + * test function implementations + */ + +namespace { + + typedef stlsoft::auto_buffer ab_m_t; + typedef stlsoft::auto_buffer ab_w_t; + typedef unixstl::system_traits traits_m_t; + typedef unixstl::system_traits traits_w_t; + typedef std::vector vec_w_t; + + static wchar_t const s_wide_missing_name_w[] = + L"UNIXSTL_SYSTEM_TRAITS_W_TEST_MISSING_9F3C2B1A_7E4D_4A6F_9C08_1D2E3F4A5B6C"; + + static char const s_wide_present_name[] = + "UNIXSTL_SYSTEM_TRAITS_W_TEST_9F3C2B1A_7E4D_4A6F_9C08_1D2E3F4A5B6C"; + + static wchar_t const s_wide_present_name_w[] = + L"UNIXSTL_SYSTEM_TRAITS_W_TEST_9F3C2B1A_7E4D_4A6F_9C08_1D2E3F4A5B6C"; + + static char const s_wide_present_value[] = "wide-env-value"; + + static wchar_t const s_wide_present_value_w[] = L"wide-env-value"; + + +/* Shared with resizeable_buffer branch — bodies and ANSI name/value + * constants land at merge (rb size including NUL / probe-then-fill). + */ +static void TEST_get_environment_variable_MISSING() +{ +} + +static void TEST_get_environment_variable_RESIZEABLE_auto_buffer() +{ +} + +static void TEST_get_environment_variable_RESIZEABLE_vector() +{ +} + +static void TEST_get_environment_variable_w() +{ + platformstl::environment_variable_scope const scope( + s_wide_present_name + , s_wide_present_value + ); + + size_t const cch_probe = traits_w_t::get_environment_variable( + s_wide_present_name_w + , static_cast(NULL) + , 0 + ); + + TEST_INT_EQ(::strlen(s_wide_present_value), cch_probe); + + wchar_t buff[64]; + size_t const cch = traits_w_t::get_environment_variable( + s_wide_present_name_w + , buff + , STLSOFT_NUM_ELEMENTS(buff) + ); + + TEST_INT_EQ(cch_probe, cch); + TEST_WS_EQ(s_wide_present_value_w, buff); + + { + vec_w_t rb; + + size_t const n = traits_w_t::get_environment_variable( + s_wide_present_name_w + , rb + ); + + TEST_INT_EQ(cch_probe, n); + TEST_INT_EQ(cch_probe, rb.size()); + TEST_INT_EQ(0, ::wcsncmp(s_wide_present_value_w, rb.data(), cch_probe)); + } + + TEST_INT_EQ( + 0 + , traits_w_t::get_environment_variable( + s_wide_missing_name_w + , buff + , STLSOFT_NUM_ELEMENTS(buff) + ) + ); +} + +static void TEST_get_home_directory_RESIZEABLE_auto_buffer() +{ +} + +static void TEST_get_home_directory_RESIZEABLE_vector() +{ +} + +static void TEST_get_home_directory_w() +{ + size_t const required_m = traits_m_t::get_home_directory(static_cast(NULL), 0); + size_t const required_w = traits_w_t::get_home_directory(static_cast(NULL), 0); + + if (0 == required_m) + { + TEST_INT_EQ(0, required_w); + return; + } + + TEST_INT_EQ(required_m, required_w); + + ab_m_t buff_m(required_m); + ab_w_t buff_w(required_w); + + size_t const cch_m = traits_m_t::get_home_directory(&buff_m[0], buff_m.size()); + size_t const cch_w = traits_w_t::get_home_directory(&buff_w[0], buff_w.size()); + + TEST_INT_EQ(required_m - 1, cch_m); + TEST_INT_EQ(required_w - 1, cch_w); + TEST_INT_EQ(cch_m, cch_w); + + { + ab_w_t expected(cch_m + 1); + + TEST_INT_NE(static_cast(-1), ::mbstowcs(&expected[0], buff_m.data(), expected.size())); + TEST_WS_EQ(expected.data(), buff_w.data()); + } + + { + vec_w_t rb; + + size_t const n = traits_w_t::get_home_directory(rb); + + TEST_INT_EQ(cch_w, n); + TEST_INT_EQ(required_w, rb.size()); + TEST_WS_EQ(buff_w.data(), rb.data()); + } +} +} // anonymous namespace + + +/* ///////////////////////////// end of file //////////////////////////// */ diff --git a/test/component/winstl/system/CMakeLists.txt b/test/component/winstl/system/CMakeLists.txt index f200ec6e..331d1e0f 100644 --- a/test/component/winstl/system/CMakeLists.txt +++ b/test/component/winstl/system/CMakeLists.txt @@ -1,2 +1,3 @@ # SIS:AUTO_GENERATED: Remove this line if you edit the file, otherwise it will be overwritten add_subdirectory(directory_functions) +add_subdirectory(process_paths) diff --git a/test/component/winstl/system/process_paths/CMakeLists.txt b/test/component/winstl/system/process_paths/CMakeLists.txt new file mode 100644 index 00000000..056b6aa3 --- /dev/null +++ b/test/component/winstl/system/process_paths/CMakeLists.txt @@ -0,0 +1,2 @@ +# SIS:AUTO_GENERATED: Remove this line if you edit the file, otherwise it will be overwritten +define_automated_test_program(test.component.winstl.system.process_paths entry.cpp) diff --git a/test/component/winstl/system/process_paths/entry.cpp b/test/component/winstl/system/process_paths/entry.cpp new file mode 100644 index 00000000..c4360129 --- /dev/null +++ b/test/component/winstl/system/process_paths/entry.cpp @@ -0,0 +1,710 @@ +/* ///////////////////////////////////////////////////////////////////////// + * File: test/component/winstl/system/process_paths/entry.cpp + * + * Purpose: Component-tests for + * `winstl::system_traits::get_current_process_path()` (multibyte + * and wide-character), including resizeable-buffer overloads. + * + * Created: 15th October 2026 + * Updated: 18th October 2026 + * + * ////////////////////////////////////////////////////////////////////// */ + + +/* ///////////////////////////////////////////////////////////////////////// + * includes + */ + +/* ///////////////////////////////////// + * test component header file include(s) + */ + +#include + +/* ///////////////////////////////////// + * general includes + */ + +/* xTests header files */ +#include +#include + +/* STLSoft header files */ +#include +#include + +/* Standard C++ header files */ +#include +#include + +/* Standard C / Windows header files */ +#include +#include + + +/* ///////////////////////////////////////////////////////////////////////// + * forward declarations + */ + +namespace { + + static void TEST_size_QUERY_m(); + static void TEST_size_QUERY_w(); + static void TEST_size_THEN_SUFFICIENT_m(); + static void TEST_size_THEN_SUFFICIENT_w(); + static void TEST_EXCESS_SPACE_m(); + static void TEST_EXCESS_SPACE_w(); + static void TEST_INSUFFICIENT_SPACE_m(); + static void TEST_INSUFFICIENT_SPACE_w(); + static void TEST_ppFile_NULL_ON_SUCCESS_m(); + static void TEST_ppFile_NULL_ON_SUCCESS_w(); + static void TEST_ppFile_separator_ON_SUCCESS_m(); + static void TEST_ppFile_separator_ON_SUCCESS_w(); + static void TEST_ppFile_NULL_WHEN_INSUFFICIENT_m(); + static void TEST_ppFile_NULL_WHEN_INSUFFICIENT_w(); + static void TEST_RESIZEABLE_auto_buffer_SUCCESS_m(); + static void TEST_RESIZEABLE_auto_buffer_SUCCESS_w(); + static void TEST_RESIZEABLE_vector_SUCCESS_m(); + static void TEST_RESIZEABLE_vector_SUCCESS_w(); + static void TEST_RESIZEABLE_ppFile_NULL_m(); + static void TEST_RESIZEABLE_ppFile_NULL_w(); + static void TEST_RESIZEABLE_ppFile_separator_m(); + static void TEST_RESIZEABLE_ppFile_separator_w(); + static void TEST_RESIZEABLE_resize_FAILURE_leaves_rb_untouched_m(); + static void TEST_RESIZEABLE_resize_FAILURE_leaves_rb_untouched_w(); +} // anonymous namespace + + +/* ///////////////////////////////////////////////////////////////////////// + * main() + */ + +int main(int argc, char* argv[]) +{ + int retCode = EXIT_SUCCESS; + int verbosity = 2; + + XTESTS_COMMANDLINE_PARSEVERBOSITY(argc, argv, &verbosity); + + if (XTESTS_START_RUNNER("test.component.winstl.system.process_paths", verbosity)) + { + XTESTS_RUN_CASE(TEST_size_QUERY_m); + XTESTS_RUN_CASE(TEST_size_QUERY_w); + XTESTS_RUN_CASE(TEST_size_THEN_SUFFICIENT_m); + XTESTS_RUN_CASE(TEST_size_THEN_SUFFICIENT_w); + XTESTS_RUN_CASE(TEST_EXCESS_SPACE_m); + XTESTS_RUN_CASE(TEST_EXCESS_SPACE_w); + XTESTS_RUN_CASE(TEST_INSUFFICIENT_SPACE_m); + XTESTS_RUN_CASE(TEST_INSUFFICIENT_SPACE_w); + XTESTS_RUN_CASE(TEST_ppFile_NULL_ON_SUCCESS_m); + XTESTS_RUN_CASE(TEST_ppFile_NULL_ON_SUCCESS_w); + XTESTS_RUN_CASE(TEST_ppFile_separator_ON_SUCCESS_m); + XTESTS_RUN_CASE(TEST_ppFile_separator_ON_SUCCESS_w); + XTESTS_RUN_CASE(TEST_ppFile_NULL_WHEN_INSUFFICIENT_m); + XTESTS_RUN_CASE(TEST_ppFile_NULL_WHEN_INSUFFICIENT_w); + XTESTS_RUN_CASE(TEST_RESIZEABLE_auto_buffer_SUCCESS_m); + XTESTS_RUN_CASE(TEST_RESIZEABLE_auto_buffer_SUCCESS_w); + XTESTS_RUN_CASE(TEST_RESIZEABLE_vector_SUCCESS_m); + XTESTS_RUN_CASE(TEST_RESIZEABLE_vector_SUCCESS_w); + XTESTS_RUN_CASE(TEST_RESIZEABLE_ppFile_NULL_m); + XTESTS_RUN_CASE(TEST_RESIZEABLE_ppFile_NULL_w); + XTESTS_RUN_CASE(TEST_RESIZEABLE_ppFile_separator_m); + XTESTS_RUN_CASE(TEST_RESIZEABLE_ppFile_separator_w); + XTESTS_RUN_CASE(TEST_RESIZEABLE_resize_FAILURE_leaves_rb_untouched_m); + XTESTS_RUN_CASE(TEST_RESIZEABLE_resize_FAILURE_leaves_rb_untouched_w); + + XTESTS_PRINT_RESULTS(); + + XTESTS_END_RUNNER_UPDATE_EXITCODE(&retCode); + } + + return retCode; +} + + +/* ///////////////////////////////////////////////////////////////////////// + * helpers + */ + +namespace { + +typedef winstl::filesystem_traits fs_traits_m_t; +typedef winstl::filesystem_traits fs_traits_w_t; +typedef winstl::system_traits traits_m_t; +typedef winstl::system_traits traits_w_t; + + +/** Obtains the current process image path via GetModuleFileNameA. */ +static +std::string +obtain_raw_current_process_path_m() +{ + stlsoft::auto_buffer buff(MAX_PATH); + + for (;;) + { + DWORD const n = ::GetModuleFileNameA(NULL, &buff[0], static_cast(buff.size())); + + if (0 == n) + { + return std::string(); + } + + if (n < buff.size()) + { + return std::string(&buff[0], static_cast(n)); + } + + if (!buff.resize(buff.size() * 2)) + { + return std::string(); + } + } +} + +/** Obtains the current process image path via GetModuleFileNameW. */ +static +std::wstring +obtain_raw_current_process_path_w() +{ + stlsoft::auto_buffer buff(MAX_PATH); + + for (;;) + { + DWORD const n = ::GetModuleFileNameW(NULL, &buff[0], static_cast(buff.size())); + + if (0 == n) + { + return std::wstring(); + } + + if (n < buff.size()) + { + return std::wstring(&buff[0], static_cast(n)); + } + + if (!buff.resize(buff.size() * 2)) + { + return std::wstring(); + } + } +} + +template +static +C* +invalid_file_pointer() +{ + return reinterpret_cast(static_cast(-1)); +} + +/** Minimal resizeable buffer whose #resize() always fails. */ +template +struct fail_on_resize_buffer +{ + typedef C value_type; + + std::vector storage; + + size_t size() const + { + return storage.size(); + } + + C& operator [](size_t i) + { + return storage[i]; + } + + C const& operator [](size_t i) const + { + return storage[i]; + } + + bool resize(size_t /* newSize */) + { + return false; + } +}; +} // anonymous namespace + + +/* ///////////////////////////////////////////////////////////////////////// + * test function implementations + */ + +namespace { + +static void TEST_size_QUERY_m() +{ + std::string const expected = obtain_raw_current_process_path_m(); + + XTESTS_REQUIRE(TEST_BOOLEAN_TRUE(!expected.empty())); + + char* pFile = invalid_file_pointer(); + size_t const cch = traits_m_t::get_current_process_path(0, NULL, &pFile); + + /* Demand may exceed len+1 (WinSTL GetModuleFileName size protocol). */ + TEST_INT_GE(expected.size() + 1, cch); + TEST_PTR_EQ(NULL, pFile); +} + +static void TEST_size_QUERY_w() +{ + std::wstring const expected = obtain_raw_current_process_path_w(); + + XTESTS_REQUIRE(TEST_BOOLEAN_TRUE(!expected.empty())); + + wchar_t* pFile = invalid_file_pointer(); + size_t const cch = traits_w_t::get_current_process_path(0, NULL, &pFile); + + TEST_INT_GE(expected.size() + 1, cch); + TEST_PTR_EQ(NULL, pFile); +} + +static void TEST_size_THEN_SUFFICIENT_m() +{ + std::string const expected = obtain_raw_current_process_path_m(); + + XTESTS_REQUIRE(TEST_BOOLEAN_TRUE(!expected.empty())); + + size_t const len = expected.size(); + size_t const need = traits_m_t::get_current_process_path(0, NULL, NULL); + + XTESTS_REQUIRE(TEST_INT_GE(len + 1, need)); + + stlsoft::auto_buffer buff(need); + char* pFile = invalid_file_pointer(); + size_t const cch = traits_m_t::get_current_process_path(buff.size(), &buff[0], &pFile); + + TEST_INT_EQ(len, cch); + TEST_MS_EQ(expected.c_str(), &buff[0]); + TEST_CHAR_EQ('\0', buff[len]); +} + +static void TEST_size_THEN_SUFFICIENT_w() +{ + std::wstring const expected = obtain_raw_current_process_path_w(); + + XTESTS_REQUIRE(TEST_BOOLEAN_TRUE(!expected.empty())); + + size_t const len = expected.size(); + size_t const need = traits_w_t::get_current_process_path(0, NULL, NULL); + + XTESTS_REQUIRE(TEST_INT_GE(len + 1, need)); + + stlsoft::auto_buffer buff(need); + wchar_t* pFile = invalid_file_pointer(); + size_t const cch = traits_w_t::get_current_process_path(buff.size(), &buff[0], &pFile); + + TEST_INT_EQ(len, cch); + TEST_WS_EQ(expected.c_str(), &buff[0]); + TEST_CHAR_EQ(L'\0', buff[len]); +} + +static void TEST_EXCESS_SPACE_m() +{ + std::string const expected = obtain_raw_current_process_path_m(); + + XTESTS_REQUIRE(TEST_BOOLEAN_TRUE(!expected.empty())); + + size_t const len = expected.size(); + stlsoft::auto_buffer buff(len + 64); + + ::memset(&buff[0], '~', buff.size()); + + char* pFile = invalid_file_pointer(); + size_t const cch = traits_m_t::get_current_process_path(buff.size(), &buff[0], &pFile); + + TEST_INT_EQ(len, cch); + TEST_MS_EQ(expected.c_str(), &buff[0]); + TEST_CHAR_EQ('\0', buff[len]); +} + +static void TEST_EXCESS_SPACE_w() +{ + std::wstring const expected = obtain_raw_current_process_path_w(); + + XTESTS_REQUIRE(TEST_BOOLEAN_TRUE(!expected.empty())); + + size_t const len = expected.size(); + stlsoft::auto_buffer buff(len + 64); + + for (size_t i = 0; i != buff.size(); ++i) + { + buff[i] = L'~'; + } + + wchar_t* pFile = invalid_file_pointer(); + size_t const cch = traits_w_t::get_current_process_path(buff.size(), &buff[0], &pFile); + + TEST_INT_EQ(len, cch); + TEST_WS_EQ(expected.c_str(), &buff[0]); + TEST_CHAR_EQ(L'\0', buff[len]); +} + +static void TEST_INSUFFICIENT_SPACE_m() +{ + std::string const expected = obtain_raw_current_process_path_m(); + + XTESTS_REQUIRE(TEST_BOOLEAN_TRUE(!expected.empty())); + + size_t const len = expected.size(); + + { + size_t const cchBuff = len; + stlsoft::auto_buffer buff(cchBuff); + + ::memset(&buff[0], '~', buff.size()); + + char* pFile = invalid_file_pointer(); + size_t const cch = traits_m_t::get_current_process_path(buff.size(), &buff[0], &pFile); + + TEST_INT_GE(len + 1, cch); + TEST_PTR_EQ(NULL, pFile); + TEST_CHAR_EQ('\0', buff[cchBuff - 1]); + TEST_MS_EQ_N(expected.c_str(), &buff[0], cchBuff - 1); + } + + { + char buff[1] = { '~' }; + char* pFile = invalid_file_pointer(); + size_t const cch = traits_m_t::get_current_process_path(STLSOFT_NUM_ELEMENTS(buff), buff, &pFile); + + TEST_INT_GE(len + 1, cch); + TEST_PTR_EQ(NULL, pFile); + TEST_CHAR_EQ('\0', buff[0]); + } +} + +static void TEST_INSUFFICIENT_SPACE_w() +{ + std::wstring const expected = obtain_raw_current_process_path_w(); + + XTESTS_REQUIRE(TEST_BOOLEAN_TRUE(!expected.empty())); + + size_t const len = expected.size(); + + { + size_t const cchBuff = len; + stlsoft::auto_buffer buff(cchBuff); + + for (size_t i = 0; i != buff.size(); ++i) + { + buff[i] = L'~'; + } + + wchar_t* pFile = invalid_file_pointer(); + size_t const cch = traits_w_t::get_current_process_path(buff.size(), &buff[0], &pFile); + + TEST_INT_GE(len + 1, cch); + TEST_PTR_EQ(NULL, pFile); + TEST_CHAR_EQ(L'\0', buff[cchBuff - 1]); + TEST_WS_EQ_N(expected.c_str(), &buff[0], cchBuff - 1); + } + + { + wchar_t buff[1] = { L'~' }; + wchar_t* pFile = invalid_file_pointer(); + size_t const cch = traits_w_t::get_current_process_path(STLSOFT_NUM_ELEMENTS(buff), buff, &pFile); + + TEST_INT_GE(len + 1, cch); + TEST_PTR_EQ(NULL, pFile); + TEST_CHAR_EQ(L'\0', buff[0]); + } +} + +static void TEST_ppFile_NULL_ON_SUCCESS_m() +{ + std::string const expected = obtain_raw_current_process_path_m(); + + XTESTS_REQUIRE(TEST_BOOLEAN_TRUE(!expected.empty())); + + size_t const need = traits_m_t::get_current_process_path(0, NULL, NULL); + + XTESTS_REQUIRE(TEST_INT_GE(expected.size() + 1, need)); + + stlsoft::auto_buffer buff(need); + size_t const cch = traits_m_t::get_current_process_path(buff.size(), &buff[0], NULL); + + TEST_INT_EQ(expected.size(), cch); + TEST_MS_EQ(expected.c_str(), &buff[0]); +} + +static void TEST_ppFile_NULL_ON_SUCCESS_w() +{ + std::wstring const expected = obtain_raw_current_process_path_w(); + + XTESTS_REQUIRE(TEST_BOOLEAN_TRUE(!expected.empty())); + + size_t const need = traits_w_t::get_current_process_path(0, NULL, NULL); + + XTESTS_REQUIRE(TEST_INT_GE(expected.size() + 1, need)); + + stlsoft::auto_buffer buff(need); + size_t const cch = traits_w_t::get_current_process_path(buff.size(), &buff[0], NULL); + + TEST_INT_EQ(expected.size(), cch); + TEST_WS_EQ(expected.c_str(), &buff[0]); +} + +static void TEST_ppFile_separator_ON_SUCCESS_m() +{ + std::string const expected = obtain_raw_current_process_path_m(); + + XTESTS_REQUIRE(TEST_BOOLEAN_TRUE(!expected.empty())); + + size_t const need = traits_m_t::get_current_process_path(0, NULL, NULL); + + XTESTS_REQUIRE(TEST_INT_GE(expected.size() + 1, need)); + + stlsoft::auto_buffer buff(need); + char* pFile = invalid_file_pointer(); + size_t const cch = traits_m_t::get_current_process_path(buff.size(), &buff[0], &pFile); + + TEST_INT_EQ(expected.size(), cch); + TEST_MS_EQ(expected.c_str(), &buff[0]); + + char const* const expectedSep = fs_traits_m_t::find_last_path_name_separator(&buff[0]); + + TEST_PTR_EQ(expectedSep, pFile); + + if (NULL != pFile) + { + TEST_MS_EQ(expectedSep + 1, pFile + 1); + } +} + +static void TEST_ppFile_separator_ON_SUCCESS_w() +{ + std::wstring const expected = obtain_raw_current_process_path_w(); + + XTESTS_REQUIRE(TEST_BOOLEAN_TRUE(!expected.empty())); + + size_t const need = traits_w_t::get_current_process_path(0, NULL, NULL); + + XTESTS_REQUIRE(TEST_INT_GE(expected.size() + 1, need)); + + stlsoft::auto_buffer buff(need); + wchar_t* pFile = invalid_file_pointer(); + size_t const cch = traits_w_t::get_current_process_path(buff.size(), &buff[0], &pFile); + + TEST_INT_EQ(expected.size(), cch); + TEST_WS_EQ(expected.c_str(), &buff[0]); + + wchar_t const* const expectedSep = fs_traits_w_t::find_last_path_name_separator(&buff[0]); + + TEST_PTR_EQ(expectedSep, pFile); + + if (NULL != pFile) + { + TEST_WS_EQ(expectedSep + 1, pFile + 1); + } +} + +static void TEST_ppFile_NULL_WHEN_INSUFFICIENT_m() +{ + std::string const expected = obtain_raw_current_process_path_m(); + + XTESTS_REQUIRE(TEST_BOOLEAN_TRUE(!expected.empty())); + + size_t const len = expected.size(); + stlsoft::auto_buffer buff(len); + char* pFile = invalid_file_pointer(); + size_t const cch = traits_m_t::get_current_process_path(buff.size(), &buff[0], &pFile); + + TEST_INT_GE(len + 1, cch); + TEST_PTR_EQ(NULL, pFile); +} + +static void TEST_ppFile_NULL_WHEN_INSUFFICIENT_w() +{ + std::wstring const expected = obtain_raw_current_process_path_w(); + + XTESTS_REQUIRE(TEST_BOOLEAN_TRUE(!expected.empty())); + + size_t const len = expected.size(); + stlsoft::auto_buffer buff(len); + wchar_t* pFile = invalid_file_pointer(); + size_t const cch = traits_w_t::get_current_process_path(buff.size(), &buff[0], &pFile); + + TEST_INT_GE(len + 1, cch); + TEST_PTR_EQ(NULL, pFile); +} + +static void TEST_RESIZEABLE_auto_buffer_SUCCESS_m() +{ + std::string const expected = obtain_raw_current_process_path_m(); + + XTESTS_REQUIRE(TEST_BOOLEAN_TRUE(!expected.empty())); + + stlsoft::auto_buffer rb(0); + size_t const cch = traits_m_t::get_current_process_path(rb); + + TEST_INT_EQ(expected.size(), cch); + TEST_INT_GE(expected.size() + 1, rb.size()); + TEST_MS_EQ(expected.c_str(), &rb[0]); +} + +static void TEST_RESIZEABLE_auto_buffer_SUCCESS_w() +{ + std::wstring const expected = obtain_raw_current_process_path_w(); + + XTESTS_REQUIRE(TEST_BOOLEAN_TRUE(!expected.empty())); + + stlsoft::auto_buffer rb(0); + size_t const cch = traits_w_t::get_current_process_path(rb); + + TEST_INT_EQ(expected.size(), cch); + TEST_INT_GE(expected.size() + 1, rb.size()); + TEST_WS_EQ(expected.c_str(), &rb[0]); +} + +static void TEST_RESIZEABLE_vector_SUCCESS_m() +{ + std::string const expected = obtain_raw_current_process_path_m(); + + XTESTS_REQUIRE(TEST_BOOLEAN_TRUE(!expected.empty())); + + std::vector rb; + size_t const cch = traits_m_t::get_current_process_path(rb); + + TEST_INT_EQ(expected.size(), cch); + TEST_INT_GE(expected.size() + 1, rb.size()); + TEST_MS_EQ(expected.c_str(), &rb[0]); +} + +static void TEST_RESIZEABLE_vector_SUCCESS_w() +{ + std::wstring const expected = obtain_raw_current_process_path_w(); + + XTESTS_REQUIRE(TEST_BOOLEAN_TRUE(!expected.empty())); + + std::vector rb; + size_t const cch = traits_w_t::get_current_process_path(rb); + + TEST_INT_EQ(expected.size(), cch); + TEST_INT_GE(expected.size() + 1, rb.size()); + TEST_WS_EQ(expected.c_str(), &rb[0]); +} + +static void TEST_RESIZEABLE_ppFile_NULL_m() +{ + std::string const expected = obtain_raw_current_process_path_m(); + + XTESTS_REQUIRE(TEST_BOOLEAN_TRUE(!expected.empty())); + + stlsoft::auto_buffer rb(0); + size_t const cch = traits_m_t::get_current_process_path(rb, NULL); + + TEST_INT_EQ(expected.size(), cch); + TEST_MS_EQ(expected.c_str(), &rb[0]); +} + +static void TEST_RESIZEABLE_ppFile_NULL_w() +{ + std::wstring const expected = obtain_raw_current_process_path_w(); + + XTESTS_REQUIRE(TEST_BOOLEAN_TRUE(!expected.empty())); + + stlsoft::auto_buffer rb(0); + size_t const cch = traits_w_t::get_current_process_path(rb, NULL); + + TEST_INT_EQ(expected.size(), cch); + TEST_WS_EQ(expected.c_str(), &rb[0]); +} + +static void TEST_RESIZEABLE_ppFile_separator_m() +{ + std::string const expected = obtain_raw_current_process_path_m(); + + XTESTS_REQUIRE(TEST_BOOLEAN_TRUE(!expected.empty())); + + stlsoft::auto_buffer rb(0); + char* pFile = invalid_file_pointer(); + size_t const cch = traits_m_t::get_current_process_path(rb, &pFile); + + TEST_INT_EQ(expected.size(), cch); + TEST_MS_EQ(expected.c_str(), &rb[0]); + + char const* const expectedSep = fs_traits_m_t::find_last_path_name_separator(&rb[0]); + + TEST_PTR_EQ(expectedSep, pFile); + + if (NULL != pFile) + { + TEST_MS_EQ(expectedSep + 1, pFile + 1); + } +} + +static void TEST_RESIZEABLE_ppFile_separator_w() +{ + std::wstring const expected = obtain_raw_current_process_path_w(); + + XTESTS_REQUIRE(TEST_BOOLEAN_TRUE(!expected.empty())); + + stlsoft::auto_buffer rb(0); + wchar_t* pFile = invalid_file_pointer(); + size_t const cch = traits_w_t::get_current_process_path(rb, &pFile); + + TEST_INT_EQ(expected.size(), cch); + TEST_WS_EQ(expected.c_str(), &rb[0]); + + wchar_t const* const expectedSep = fs_traits_w_t::find_last_path_name_separator(&rb[0]); + + TEST_PTR_EQ(expectedSep, pFile); + + if (NULL != pFile) + { + TEST_WS_EQ(expectedSep + 1, pFile + 1); + } +} + +static void TEST_RESIZEABLE_resize_FAILURE_leaves_rb_untouched_m() +{ + fail_on_resize_buffer rb; + + rb.storage.assign(4, 'X'); + + size_t const priorSize = rb.size(); + DWORD const priorError = ::GetLastError(); + + ::SetLastError(ERROR_SUCCESS); + + size_t const cch = traits_m_t::get_current_process_path(rb); + + TEST_INT_EQ(0, cch); + TEST_INT_EQ(ERROR_OUTOFMEMORY, ::GetLastError()); + TEST_INT_EQ(priorSize, rb.size()); + TEST_CHAR_EQ('X', rb.storage[0]); + TEST_CHAR_EQ('X', rb.storage[3]); + + ::SetLastError(priorError); +} + +static void TEST_RESIZEABLE_resize_FAILURE_leaves_rb_untouched_w() +{ + fail_on_resize_buffer rb; + + rb.storage.assign(4, L'X'); + + size_t const priorSize = rb.size(); + DWORD const priorError = ::GetLastError(); + + ::SetLastError(ERROR_SUCCESS); + + size_t const cch = traits_w_t::get_current_process_path(rb); + + TEST_INT_EQ(0, cch); + TEST_INT_EQ(ERROR_OUTOFMEMORY, ::GetLastError()); + TEST_INT_EQ(priorSize, rb.size()); + TEST_BOOLEAN_TRUE(L'X' == rb.storage[0]); + TEST_BOOLEAN_TRUE(L'X' == rb.storage[3]); + + ::SetLastError(priorError); +} +} // anonymous namespace + + +/* ///////////////////////////// end of file //////////////////////////// */ + diff --git a/test/unit/unixstl/CMakeLists.txt b/test/unit/unixstl/CMakeLists.txt index ba184416..d98de204 100644 --- a/test/unit/unixstl/CMakeLists.txt +++ b/test/unit/unixstl/CMakeLists.txt @@ -2,3 +2,4 @@ add_subdirectory(filesystem) add_subdirectory(process) add_subdirectory(shims) +add_subdirectory(system) diff --git a/test/unit/unixstl/filesystem/CMakeLists.txt b/test/unit/unixstl/filesystem/CMakeLists.txt index 7bfdcb84..fb368025 100644 --- a/test/unit/unixstl/filesystem/CMakeLists.txt +++ b/test/unit/unixstl/filesystem/CMakeLists.txt @@ -1,3 +1,4 @@ # SIS:AUTO_GENERATED: Remove this line if you edit the file, otherwise it will be overwritten +add_subdirectory(filesystem_traits) add_subdirectory(path) add_subdirectory(squeeze_functions) diff --git a/test/unit/unixstl/filesystem/filesystem_traits/CMakeLists.txt b/test/unit/unixstl/filesystem/filesystem_traits/CMakeLists.txt new file mode 100644 index 00000000..c5ad72a1 --- /dev/null +++ b/test/unit/unixstl/filesystem/filesystem_traits/CMakeLists.txt @@ -0,0 +1,2 @@ +# SIS:AUTO_GENERATED: Remove this line if you edit the file, otherwise it will be overwritten +define_automated_test_program(test.unit.unixstl.filesystem.filesystem_traits entry.cpp) diff --git a/test/unit/unixstl/filesystem/filesystem_traits/entry.cpp b/test/unit/unixstl/filesystem/filesystem_traits/entry.cpp new file mode 100644 index 00000000..375f83c7 --- /dev/null +++ b/test/unit/unixstl/filesystem/filesystem_traits/entry.cpp @@ -0,0 +1,208 @@ +/* ///////////////////////////////////////////////////////////////////////// + * File: test/unit/unixstl/filesystem/filesystem_traits/entry.cpp + * + * Purpose: Unit-tests for `unixstl::filesystem_traits` resizeable-buffer + * `ensure_dir_end` / `remove_dir_end` (C2 empty-`""` behaviour; + * buffer size after remove); and wide path classification / + * separator finders. + * + * Created: 15th October 2026 + * Updated: 15th October 2026 + * + * ////////////////////////////////////////////////////////////////////// */ + + +/* ///////////////////////////////////////////////////////////////////////// + * includes + */ + +/* ///////////////////////////////////// + * test component header file include(s) + */ + +#include + +/* ///////////////////////////////////// + * general includes + */ + +/* xTests header files */ +#include +#include + +/* STLSoft header files */ +#include + +/* Standard C header files */ +#include +#include +#include + + +/* ///////////////////////////////////////////////////////////////////////// + * forward declarations + */ + +namespace { + + static void TEST_ensure_dir_end_EMPTY_stays_empty(); + static void TEST_ensure_dir_end_APPENDS_separator(); + static void TEST_remove_dir_end_SHRINKS_buffer(); + static void TEST_remove_then_ensure_round_trip(); + + static void TEST_find_path_name_separators_w(); + static void TEST_path_classification_w(); + static void TEST_path_classification_m_matches_w(); +} // anonymous namespace + + +/* ///////////////////////////////////////////////////////////////////////// + * main() + */ + +int main(int argc, char* argv[]) +{ + int retCode = EXIT_SUCCESS; + int verbosity = 2; + + XTESTS_COMMANDLINE_PARSEVERBOSITY(argc, argv, &verbosity); + + if (XTESTS_START_RUNNER("test.unit.unixstl.filesystem.filesystem_traits", verbosity)) + { + XTESTS_RUN_CASE(TEST_ensure_dir_end_EMPTY_stays_empty); + XTESTS_RUN_CASE(TEST_ensure_dir_end_APPENDS_separator); + XTESTS_RUN_CASE(TEST_remove_dir_end_SHRINKS_buffer); + XTESTS_RUN_CASE(TEST_remove_then_ensure_round_trip); + + XTESTS_RUN_CASE(TEST_find_path_name_separators_w); + XTESTS_RUN_CASE(TEST_path_classification_w); + XTESTS_RUN_CASE(TEST_path_classification_m_matches_w); + + XTESTS_PRINT_RESULTS(); + + XTESTS_END_RUNNER_UPDATE_EXITCODE(&retCode); + } + + return retCode; +} + + +/* ///////////////////////////////////////////////////////////////////////// + * test function implementations + */ + +namespace { + + typedef unixstl::filesystem_traits traits_m_t; + typedef unixstl::filesystem_traits traits_w_t; + + +/* Shared with resizeable_buffer branch — bodies land at merge (C2/C3). */ +static void TEST_ensure_dir_end_EMPTY_stays_empty() +{ +} + +static void TEST_ensure_dir_end_APPENDS_separator() +{ +} + +static void TEST_remove_dir_end_SHRINKS_buffer() +{ +} + +static void TEST_remove_then_ensure_round_trip() +{ +} + + +static void TEST_find_path_name_separators_w() +{ + { + wchar_t const* const path = L"/usr/local/bin"; + wchar_t const* const last = traits_w_t::find_last_path_name_separator(path); + wchar_t const* const next = traits_w_t::find_next_path_name_separator(path); + + TEST_PTR_NE(NULL, last); + TEST_PTR_NE(NULL, next); + TEST_PTR_EQ(path + 0, next); + TEST_PTR_EQ(path + 10, last); + TEST_PTR_EQ(last, traits_w_t::find_last_path_name_separator(path, ::wcslen(path))); + TEST_PTR_EQ(next, traits_w_t::find_next_path_name_separator(path, ::wcslen(path))); + } + + { + wchar_t const* const path = L"relative"; + + TEST_PTR_EQ(NULL, traits_w_t::find_last_path_name_separator(path)); + TEST_PTR_EQ(NULL, traits_w_t::find_next_path_name_separator(path)); + TEST_PTR_EQ(NULL, traits_w_t::find_last_path_name_separator(path, 0)); + TEST_PTR_EQ(NULL, traits_w_t::find_next_path_name_separator(path, 0)); + } +} + +static void TEST_path_classification_w() +{ + TEST_BOOLEAN_TRUE(traits_w_t::is_path_rooted(L"/")); + TEST_BOOLEAN_TRUE(traits_w_t::is_path_rooted(L"/tmp")); + TEST_BOOLEAN_FALSE(traits_w_t::is_path_rooted(L"tmp")); + TEST_BOOLEAN_FALSE(traits_w_t::is_path_rooted(L"", 0)); + + TEST_BOOLEAN_TRUE(traits_w_t::is_path_absolute(L"/tmp")); + TEST_BOOLEAN_FALSE(traits_w_t::is_path_absolute(L"tmp")); + TEST_BOOLEAN_FALSE(traits_w_t::is_path_absolute(L"", 0)); + + TEST_BOOLEAN_FALSE(traits_w_t::is_path_UNC(L"/tmp")); + TEST_BOOLEAN_FALSE(traits_w_t::is_path_UNC(L"\\\\server\\share")); + TEST_BOOLEAN_FALSE(traits_w_t::is_path_UNC(L"/tmp", 4)); +} + +static void TEST_path_classification_m_matches_w() +{ + char const* const paths_m[] = + { + "/", + "/tmp", + "tmp", + "a/b", + "", + }; + wchar_t const* const paths_w[] = + { + L"/", + L"/tmp", + L"tmp", + L"a/b", + L"", + }; + + { for (size_t i = 0; i != STLSOFT_NUM_ELEMENTS(paths_m); ++i) + { + size_t const len_m = ::strlen(paths_m[i]); + size_t const len_w = ::wcslen(paths_w[i]); + + TEST_BOOLEAN_EQ( + traits_m_t::is_path_rooted(paths_m[i]) + , traits_w_t::is_path_rooted(paths_w[i]) + ); + TEST_BOOLEAN_EQ( + traits_m_t::is_path_rooted(paths_m[i], len_m) + , traits_w_t::is_path_rooted(paths_w[i], len_w) + ); + TEST_BOOLEAN_EQ( + traits_m_t::is_path_absolute(paths_m[i]) + , traits_w_t::is_path_absolute(paths_w[i]) + ); + TEST_BOOLEAN_EQ( + traits_m_t::is_path_absolute(paths_m[i], len_m) + , traits_w_t::is_path_absolute(paths_w[i], len_w) + ); + TEST_BOOLEAN_EQ( + traits_m_t::is_path_UNC(paths_m[i]) + , traits_w_t::is_path_UNC(paths_w[i]) + ); + }} +} +} // anonymous namespace + + +/* ///////////////////////////// end of file //////////////////////////// */ diff --git a/test/unit/unixstl/system/CMakeLists.txt b/test/unit/unixstl/system/CMakeLists.txt new file mode 100644 index 00000000..aabe6a2b --- /dev/null +++ b/test/unit/unixstl/system/CMakeLists.txt @@ -0,0 +1,2 @@ +# SIS:AUTO_GENERATED: Remove this line if you edit the file, otherwise it will be overwritten +add_subdirectory(system_traits) diff --git a/test/unit/unixstl/system/system_traits/CMakeLists.txt b/test/unit/unixstl/system/system_traits/CMakeLists.txt new file mode 100644 index 00000000..32b277bf --- /dev/null +++ b/test/unit/unixstl/system/system_traits/CMakeLists.txt @@ -0,0 +1,2 @@ +# SIS:AUTO_GENERATED: Remove this line if you edit the file, otherwise it will be overwritten +define_automated_test_program(test.unit.unixstl.system.system_traits entry.cpp) diff --git a/test/unit/unixstl/system/system_traits/entry.cpp b/test/unit/unixstl/system/system_traits/entry.cpp new file mode 100644 index 00000000..a8877e36 --- /dev/null +++ b/test/unit/unixstl/system/system_traits/entry.cpp @@ -0,0 +1,95 @@ +/* ///////////////////////////////////////////////////////////////////////// + * File: test/unit/unixstl/system/system_traits/entry.cpp + * + * Purpose: Unit-tests for `unixstl::system_traits` wide `path_str_*`. + * Environment-dependent coverage lives in + * `test/component/unixstl/system/system_traits`. + * + * Created: 15th October 2026 + * Updated: 15th October 2026 + * + * ////////////////////////////////////////////////////////////////////// */ + + +/* ///////////////////////////////////////////////////////////////////////// + * includes + */ + +/* ///////////////////////////////////// + * test component header file include(s) + */ + +#include + +/* ///////////////////////////////////// + * general includes + */ + +/* xTests header files */ +#include +#include + +/* Standard C header files */ +#include + + +/* ///////////////////////////////////////////////////////////////////////// + * forward declarations + */ + +namespace { + + static void TEST_path_str_compare_w(); +} // anonymous namespace + + +/* ///////////////////////////////////////////////////////////////////////// + * main() + */ + +int main(int argc, char* argv[]) +{ + int retCode = EXIT_SUCCESS; + int verbosity = 2; + + XTESTS_COMMANDLINE_PARSEVERBOSITY(argc, argv, &verbosity); + + if (XTESTS_START_RUNNER("test.unit.unixstl.system.system_traits", verbosity)) + { + XTESTS_RUN_CASE(TEST_path_str_compare_w); + + XTESTS_PRINT_RESULTS(); + + XTESTS_END_RUNNER_UPDATE_EXITCODE(&retCode); + } + + return retCode; +} + + +/* ///////////////////////////////////////////////////////////////////////// + * test function implementations + */ + +namespace { + + typedef unixstl::system_traits traits_m_t; + typedef unixstl::system_traits traits_w_t; + + +static void TEST_path_str_compare_w() +{ + TEST_INT_EQ(0, traits_w_t::path_str_compare(L"/a/b", L"/a/b")); + TEST_INT_NE(0, traits_w_t::path_str_compare(L"/a/b", L"/a/c")); + TEST_INT_EQ(0, traits_w_t::path_str_n_compare(L"/a/b", L"/a/c", 3)); + TEST_INT_NE(0, traits_w_t::path_str_n_compare(L"/a/b", L"/a/c", 4)); + + TEST_BOOLEAN_EQ( + traits_m_t::path_str_compare("/tmp/x", "/tmp/y") < 0 + , traits_w_t::path_str_compare(L"/tmp/x", L"/tmp/y") < 0 + ); +} +} // anonymous namespace + + +/* ///////////////////////////// end of file //////////////////////////// */ diff --git a/test/unit/versions/entry.cpp b/test/unit/versions/entry.cpp index 4f1128d1..4c5c1638 100644 --- a/test/unit/versions/entry.cpp +++ b/test/unit/versions/entry.cpp @@ -4,7 +4,7 @@ * Purpose: Unit-tests for versions * * Created: 23rd August 2025 - * Updated: 10th October 2026 + * Updated: 17th October 2026 * * ////////////////////////////////////////////////////////////////////// */ @@ -133,7 +133,7 @@ namespace { static void TEST__STLSOFT_VER() { - TEST_INT_EQ(_STLSOFT_VER_1_11_1_RC8, _STLSOFT_VER); + TEST_INT_EQ(_STLSOFT_VER_1_11_1_RC9, _STLSOFT_VER); } #ifdef STLSOFT_HAS_ACE @@ -152,7 +152,7 @@ static void TEST__ATLSTL_VER() static void TEST__PLATFORMSTL_VER() { - TEST_INT_EQ(_PLATFORMSTL_VER_1_10_0_B02, _PLATFORMSTL_VER); + TEST_INT_EQ(_PLATFORMSTL_VER_1_10_0_B03, _PLATFORMSTL_VER); } #if 0 @@ -160,18 +160,18 @@ static void TEST__PLATFORMSTL_VER() static void TEST__UNIXSTL_VER() { - TEST_INT_EQ(_UNIXSTL_VER_1_8_6_B07, _UNIXSTL_VER); + TEST_INT_EQ(_UNIXSTL_VER_1_8_6_B08, _UNIXSTL_VER); } #elif defined(PLATFORMSTL_OS_IS_WINDOWS) static void TEST__COMSTL_VER() { - TEST_INT_EQ(_COMSTL_VER_1_10_3, _COMSTL_VER); + TEST_INT_EQ(_COMSTL_VER_1_10_4, _COMSTL_VER); } static void TEST__WINSTL_VER() { - TEST_INT_EQ(_WINSTL_VER_1_13_0_B04, _WINSTL_VER); + TEST_INT_EQ(_WINSTL_VER_1_13_0_B05, _WINSTL_VER); } #endif #ifdef STLSOFT_HAS_MFC