From ce316296af3828506fa1dfcacc69ecb97a2390a5 Mon Sep 17 00:00:00 2001 From: Matt Wilson Date: Sat, 10 Oct 2026 17:00:44 +1100 Subject: [PATCH 01/23] chore(stlsoft): update for 1.11.1-rc9 release Update NEWS.md, CHANGES.md, and stlsoft.h to reflect the 1.11.1-rc9 release on 12th October 2026. --- CHANGES.md | 6 ++++++ NEWS.md | 1 + include/stlsoft/stlsoft.h | 1 + 3 files changed, 8 insertions(+) diff --git a/CHANGES.md b/CHANGES.md index 45a2339ed..282dca153 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -1,6 +1,12 @@ # STLSoft - CHANGES +## 1.11.1-rc9 - 12th October 2026 + +* version: + * Version change only; + + ## 1.11.1-rc8 - 10th October 2026 * additions: diff --git a/NEWS.md b/NEWS.md index 74839ad5f..3203c8be3 100644 --- a/NEWS.md +++ b/NEWS.md @@ -3,6 +3,7 @@ | Date | News Item | Details | | ------------------- | ----------------------------------- | ------- | +| 12th October 2026 | Release of [STLSoft 1.11.1-rc9](https://github.com/synesissoftware/STLSoft/releases/tag/1.11.1-rc9) | Version change only | | 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/include/stlsoft/stlsoft.h b/include/stlsoft/stlsoft.h index 51d82f0c8..ed41592ae 100644 --- a/include/stlsoft/stlsoft.h +++ b/include/stlsoft/stlsoft.h @@ -423,6 +423,7 @@ # 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 (12th October 2026) */ #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ #define _STLSOFT_VER_MAJOR 1 From e30a2af1c9a47928051c6290db72a9e6cd7db691 Mon Sep 17 00:00:00 2001 From: Matt Wilson Date: Thu, 15 Oct 2026 14:27:06 +1100 Subject: [PATCH 02/23] test(stlsoft): unit-test resizeable_buffer_resize helper Add test.unit.stlsoft.util.resizeable_buffer_helpers covering stlsoft::resizeable_buffer_resize for auto_buffer, std::vector, and bool-/void-returning stubs (including failure propagation). --- test/unit/stlsoft/util/CMakeLists.txt | 1 + .../resizeable_buffer_helpers/CMakeLists.txt | 2 + .../util/resizeable_buffer_helpers/entry.cpp | 251 ++++++++++++++++++ 3 files changed, 254 insertions(+) create mode 100644 test/unit/stlsoft/util/resizeable_buffer_helpers/CMakeLists.txt create mode 100644 test/unit/stlsoft/util/resizeable_buffer_helpers/entry.cpp diff --git a/test/unit/stlsoft/util/CMakeLists.txt b/test/unit/stlsoft/util/CMakeLists.txt index aff0fe68b..957bcb461 100644 --- a/test/unit/stlsoft/util/CMakeLists.txt +++ b/test/unit/stlsoft/util/CMakeLists.txt @@ -1,6 +1,7 @@ add_subdirectory(bit_functions) add_subdirectory(count_decimal_digits) add_subdirectory(count_hexadecimal_digits) +add_subdirectory(resizeable_buffer_helpers) if(X_CMAKE_CXX_FULLSTANDARD GREATER_EQUAL 2011) add_subdirectory(string_insertion) diff --git a/test/unit/stlsoft/util/resizeable_buffer_helpers/CMakeLists.txt b/test/unit/stlsoft/util/resizeable_buffer_helpers/CMakeLists.txt new file mode 100644 index 000000000..cc8b70aa2 --- /dev/null +++ b/test/unit/stlsoft/util/resizeable_buffer_helpers/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.stlsoft.util.resizeable_buffer_helpers entry.cpp) diff --git a/test/unit/stlsoft/util/resizeable_buffer_helpers/entry.cpp b/test/unit/stlsoft/util/resizeable_buffer_helpers/entry.cpp new file mode 100644 index 000000000..44d62c789 --- /dev/null +++ b/test/unit/stlsoft/util/resizeable_buffer_helpers/entry.cpp @@ -0,0 +1,251 @@ +/* ///////////////////////////////////////////////////////////////////////// + * File: test/unit/stlsoft/util/resizeable_buffer_helpers/entry.cpp + * + * Purpose: Unit-tests for `stlsoft::resizeable_buffer_resize`. + * + * 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 + +/* Standard C++ header files */ +#include + +/* Standard C header files */ +#include +#include + + +/* ///////////////////////////////////////////////////////////////////////// + * forward declarations + */ + +namespace { + + static void TEST_WITH_auto_buffer_GROW(); + static void TEST_WITH_auto_buffer_SHRINK(); + static void TEST_WITH_auto_buffer_TO_ZERO(); + static void TEST_WITH_bool_returning_stub_FAILURE(); + static void TEST_WITH_bool_returning_stub_SUCCESS(); + static void TEST_WITH_vector_GROW(); + static void TEST_WITH_vector_SHRINK(); + static void TEST_WITH_vector_TO_ZERO(); + static void TEST_WITH_void_returning_stub_SUCCESS(); +} // 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.stlsoft.util.resizeable_buffer_helpers", verbosity)) + { + XTESTS_RUN_CASE(TEST_WITH_auto_buffer_GROW); + XTESTS_RUN_CASE(TEST_WITH_auto_buffer_SHRINK); + XTESTS_RUN_CASE(TEST_WITH_auto_buffer_TO_ZERO); + XTESTS_RUN_CASE(TEST_WITH_bool_returning_stub_FAILURE); + XTESTS_RUN_CASE(TEST_WITH_bool_returning_stub_SUCCESS); + XTESTS_RUN_CASE(TEST_WITH_vector_GROW); + XTESTS_RUN_CASE(TEST_WITH_vector_SHRINK); + XTESTS_RUN_CASE(TEST_WITH_vector_TO_ZERO); + XTESTS_RUN_CASE(TEST_WITH_void_returning_stub_SUCCESS); + + XTESTS_PRINT_RESULTS(); + + XTESTS_END_RUNNER_UPDATE_EXITCODE(&retCode); + } + + return retCode; +} + + +/* ///////////////////////////////////////////////////////////////////////// + * test function implementations + */ + +namespace { + +/** Minimal resizeable-buffer stub whose resize() returns + * bool, optionally failing. + */ +class bool_returning_stub +{ +public: // types + typedef char value_type; + typedef size_t size_type; + +public: // construction + bool_returning_stub() + : m_size(0) + , m_fail(false) + {} + +public: // accessors + size_type size() const + { + return m_size; + } + +public: // operations + void set_fail(bool fail) + { + m_fail = fail; + } + + bool resize(size_type newSize) + { + if (m_fail) + { + return false; + } + + m_size = newSize; + + return true; + } + +private: // fields + size_type m_size; + bool m_fail; +}; + +/** Minimal resizeable-buffer stub whose resize() returns + * void. + */ +class void_returning_stub +{ +public: // types + typedef char value_type; + typedef size_t size_type; + +public: // construction + void_returning_stub() + : m_size(0) + {} + +public: // accessors + size_type size() const + { + return m_size; + } + +public: // operations + void resize(size_type newSize) + { + m_size = newSize; + } + +private: // fields + size_type m_size; +}; + + +static void TEST_WITH_auto_buffer_GROW() +{ + stlsoft::auto_buffer rb(1); + + TEST_BOOLEAN_TRUE(stlsoft::resizeable_buffer_resize(rb, 32)); + TEST_INT_EQ(32, rb.size()); +} + +static void TEST_WITH_auto_buffer_SHRINK() +{ + stlsoft::auto_buffer rb(64); + + TEST_BOOLEAN_TRUE(stlsoft::resizeable_buffer_resize(rb, 8)); + TEST_INT_EQ(8, rb.size()); +} + +static void TEST_WITH_auto_buffer_TO_ZERO() +{ + stlsoft::auto_buffer rb(16); + + TEST_BOOLEAN_TRUE(stlsoft::resizeable_buffer_resize(rb, 0)); + TEST_INT_EQ(0, rb.size()); +} + +static void TEST_WITH_vector_GROW() +{ + std::vector rb(1, 'x'); + + TEST_BOOLEAN_TRUE(stlsoft::resizeable_buffer_resize(rb, 32)); + TEST_INT_EQ(32, rb.size()); +} + +static void TEST_WITH_vector_SHRINK() +{ + std::vector rb(64, 'x'); + + TEST_BOOLEAN_TRUE(stlsoft::resizeable_buffer_resize(rb, 8)); + TEST_INT_EQ(8, rb.size()); +} + +static void TEST_WITH_vector_TO_ZERO() +{ + std::vector rb(16, 'x'); + + TEST_BOOLEAN_TRUE(stlsoft::resizeable_buffer_resize(rb, 0)); + TEST_INT_EQ(0, rb.size()); +} + +static void TEST_WITH_bool_returning_stub_SUCCESS() +{ + bool_returning_stub rb; + + TEST_BOOLEAN_TRUE(stlsoft::resizeable_buffer_resize(rb, 10)); + TEST_INT_EQ(10, rb.size()); +} + +static void TEST_WITH_bool_returning_stub_FAILURE() +{ + bool_returning_stub rb; + + rb.set_fail(true); + + TEST_BOOLEAN_FALSE(stlsoft::resizeable_buffer_resize(rb, 10)); + TEST_INT_EQ(0, rb.size()); +} + +static void TEST_WITH_void_returning_stub_SUCCESS() +{ + void_returning_stub rb; + + TEST_BOOLEAN_TRUE(stlsoft::resizeable_buffer_resize(rb, 10)); + TEST_INT_EQ(10, rb.size()); +} + +} // anonymous namespace + + +/* ///////////////////////////// end of file //////////////////////////// */ + From 498a6bb3db09c711d498a511836f986d8de395ef Mon Sep 17 00:00:00 2001 From: Matt Wilson Date: Thu, 15 Oct 2026 14:30:43 +1100 Subject: [PATCH 03/23] TODO.md --- TODO.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/TODO.md b/TODO.md index fae197b5e..94a495299 100644 --- a/TODO.md +++ b/TODO.md @@ -34,6 +34,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; +* [ ] Bring in 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 From e7cd3e74c5fd1b3d3715fe1557f66d3bae58c478 Mon Sep 17 00:00:00 2001 From: Matt Wilson Date: Thu, 15 Oct 2026 14:39:15 +1100 Subject: [PATCH 04/23] docs(stlsoft): capture Resizeable Buffer concept in CONCEPTS.md Add top-level CONCEPTS.md covering classic buffer-and-length OS API pitfalls, the probe-then-fill gold standard (null buffer + zero capacity), Resizeable Buffer requirements/models, and the traits rb overload contract; link from README and resizeable_buffer_helpers.hpp. --- CONCEPTS.md | 190 ++++++++++++++++++ README.md | 2 +- .../util/resizeable_buffer_helpers.hpp | 7 +- 3 files changed, 196 insertions(+), 3 deletions(-) create mode 100644 CONCEPTS.md diff --git a/CONCEPTS.md b/CONCEPTS.md new file mode 100644 index 000000000..030f04f07 --- /dev/null +++ b/CONCEPTS.md @@ -0,0 +1,190 @@ +# STLSoft - Concepts + + +## Table of Contents + +- [Introduction](#introduction) +- [Classic buffer-and-length OS APIs](#classic-buffer-and-length-os-apis) + - [What goes wrong](#what-goes-wrong) + - [Gold standard: probe, then fill](#gold-standard-probe-then-fill) +- [The Resizeable Buffer concept](#the-resizeable-buffer-concept) + - [Motivation](#motivation) + - [Requirements](#requirements) + - [Models and non-models](#models-and-non-models) + - [Helper: `resizeable_buffer_resize`](#helper-resizeable_buffer_resize) + - [Contract for traits overloads that take an `rb`](#contract-for-traits-overloads-that-take-an-rb) +- [See also](#see-also) + + +## Introduction + +This document records **concepts** used across **STLSoft** — structural +requirements that are not (necessarily) reified as language-level concepts +or base classes, but that several APIs assume. The first entry is the +**Resizeable Buffer** concept used by **UnixSTL** / **WinSTL** +`system_traits` and `filesystem_traits` overloads that accept a generic +buffer rather than a raw pointer and length. + + +## Classic buffer-and-length OS APIs + +A large class of operating-system and C library functions take a +**destination buffer** and a **capacity** (in characters or bytes), and +return either a written length or a failure code. Familiar examples +include `getcwd` / `_getcwd`, `GetCurrentDirectory`, +`GetEnvironmentVariable`, `ExpandEnvironmentStrings`, and +`GetModuleFileName`. + +Callers typically need either: + +* to **fill** a buffer they already own; or +* to **discover** how large a buffer is required before allocating; + + +### What goes wrong + +Historical APIs do not share one contract. Common failure modes include: + +* **Fixed ceilings** — e.g. relying solely on `_MAX_PATH` / `PATH_MAX`, + which is wrong for long paths and for systems without a compile-time + maximum; +* **Truncation without a true demand** — e.g. raw Windows' + [`GetModuleFileName`](https://learn.microsoft.com/en-us/windows/win32/api/libloaderapi/nf-libloaderapi-getmodulefilenamew) + may truncate into the supplied buffer and return a value equal to the + capacity, without reporting the size that would have been sufficient + (callers then grow-and-retry, or wrap the API); +* **Ambiguous “empty destination”** — passing a **non-null** buffer with + **capacity 0** is *not* a reliable size probe on many APIs: it often + means “write nothing into this empty buffer” and returns `0` or fails, + rather than returning the required length; +* **Inconsistent NUL character accounting** — some returns count the + terminating `NUL`, some do not, and some change meaning between the + “too small” and “success” cases; + + +### Gold standard: probe, then fill + +The normative, unambiguous pattern preferred in **STLSoft** facades is a +**two-phase** protocol: + +1. **Probe** — call with a **null** buffer and a **zero** capacity + (`buff == nullptr` and `cch == 0`). The function returns a **demand**: + a character count of *at least* the full result length **plus one** for + the terminating `NUL` (it may return more than that minimum); +2. **Allocate** — obtain storage of at least that demand (stack, heap, + `auto_buffer`, `vector`, …); +3. **Fill** — call again with a non-null buffer and that capacity. On + success the return is the **length of the string excluding the + `NUL`**; + +Preconditions on the raw overloads take the form: + +```text +0 == cch || nullptr != buff +``` + +so that a zero capacity is allowed **only** when the buffer pointer is +null (the probe), and a non-null buffer always has a positive capacity +for a fill. + +**Do not** probe by passing a non-null buffer with length zero. That +conflates “empty destination” with “size query” and is not portable +across OS APIs. Prefer **null buffer + zero length** for the probe; +wrappers that must paper over defective native APIs (such as +`GetModuleFileName`) should still *present* this gold contract to their +callers. + +This probe-vs-fill convention is the gold standard summarised in the +discussion of required-length probing +([Ask Brave — probe with 0 length vs null buffer](https://search.brave.com/ask?q=What+about+when+wanting+to+probe+the+actual+required+length.+Should+the+caller+pass+0+length%2C+or+NUL...&source=quick-answer-followup&conversation=09aef0cd1c6f4bfdcbbb5fc05969c1dbd832)). + + +## The Resizeable Buffer concept + +### Motivation + +Repeating probe / allocate / fill at every call site is verbose and +easy to get wrong (especially NUL accounting and failure paths). +**STLSoft** therefore offers overloads that take a **resizeable +buffer** — any contiguous, resizable character sequence that can grow +to the demanded size — and perform the two-phase protocol internally. + + +### Requirements + +A type `T` models **Resizeable Buffer** for an element type `CharT` when +it provides at least: + +| Member | Meaning | +| --- | --- | +| `value_type` | Element type (typically `char` or `wchar_t`); | +| `size_type` | Unsigned size type; | +| `size() const` | Number of elements currently managed **including** the trailing `NUL` when the buffer is used as a C-string; | +| `empty() const` | Equivalent to `0 == size()`; | +| `operator[](size_type)` | Mutable access; contiguous storage so that `&rb[0]` addresses the first element when `size() > 0`; | +| `operator[](size_type) const` | Const access (needed by read-only helpers such as `has_dir_end`); | +| `resize(size_type)` | Change the number of managed elements. May return `bool` (`true` on success) or `void` (failure via exception or as documented for that type); | + +**Invariants** assumed by path-oriented APIs: + +* when `!empty()`, `rb[size() - 1] == CharT(0)` (trailing `NUL`); +* `resize` **preserves** existing elements up to the new size when + shrinking or growing (so helpers such as `ensure_dir_end` may append + in place); +* storage is **contiguous**; + + +### Models and non-models + +| Type | Models? | Notes | +| --- | --- | --- | +| `stlsoft::auto_buffer` | ✅ | Preferred; `resize` returns `bool`; | +| `std::vector` | ✅ | `resize` returns `void`; use `resizeable_buffer_resize`; | +| `stlsoft::basic_path_buffer<…>` | ❌ | `size()` **excludes** the `NUL`; off-by-one if passed as an `rb`; | +| `winstl::basic_file_path_buffer<…>` | ❌ | `resize` is a no-op in some specialisations; | + + +### Helper: `resizeable_buffer_resize` + +Declared in +[`stlsoft/util/resizeable_buffer_helpers.hpp`](./include/stlsoft/util/resizeable_buffer_helpers.hpp). + +`stlsoft::resizeable_buffer_resize(rb, newSize)` invokes `rb.resize(newSize)` +whether that member returns `bool` or `void`, and always returns `bool` +(`true` on success). Prefer it over calling `rb.resize` directly in +generic code. + + +### Contract for traits overloads that take an `rb` + +Overloads of the form `get_*(…, T_resizeableBuffer& rb)` (and similar) +should follow this gold sequence: + +1. **Probe** via the raw overload with a null buffer and zero capacity; +2. If the probe returns `0` (failure) — **leave `rb` unchanged**, do + **not** take `&rb[0]`, return `0`; +3. If `rb.size() < cchRequired` — call `resizeable_buffer_resize(rb, + cchRequired)`; on failure set an appropriate out-of-memory status + (`ENOMEM` / `ERROR_OUTOFMEMORY`) and return `0` without taking + `&rb[0]` on an empty buffer; +4. **Fill** via the raw overload into `&rb[0]` with capacity `rb.size()`; +5. Optional out-parameters that point into the result (e.g. a basename + separator pointer) are computed **only after** the final fill — never + across a resize; + +On success, the return value matches the raw fill overload (typically +the string length **excluding** the `NUL`). The buffer’s `size()` remains +the allocated demand (typically at least length + 1). + + +## See also + +* Pseudo-struct documentation in + `unixstl::filesystem_traits` / `winstl::filesystem_traits` + (`struct resizeable_buffer` under `\name concepts`); +* Unit tests: + [`test/unit/stlsoft/util/resizeable_buffer_helpers/`](./test/unit/stlsoft/util/resizeable_buffer_helpers/); +* [FAQ.md](./FAQ.md), [INSTALL.md](./INSTALL.md); + + + diff --git a/README.md b/README.md index 5bd14781c..cdfaa79e5 100644 --- a/README.md +++ b/README.md @@ -44,7 +44,7 @@ The overarching characteristic of **STLSoft** is that it is *lightweight*. Speci **NOTE**: **STLSoft** is *not* a framework. Each library component is as thin as possible for its given function. The intent is that **STLSoft** components are used as building blocks for higher-level software — applications, classes, libraries, servers. **STLSoft** has been used extensively in all these guises. -Further reading: [FAQ.md](./FAQ.md), [INSTALL.md](./INSTALL.md), [http://www.stlsoft.org/](http://www.stlsoft.org/). +Further reading: [CONCEPTS.md](./CONCEPTS.md), [FAQ.md](./FAQ.md), [INSTALL.md](./INSTALL.md), [http://www.stlsoft.org/](http://www.stlsoft.org/). ## Installation diff --git a/include/stlsoft/util/resizeable_buffer_helpers.hpp b/include/stlsoft/util/resizeable_buffer_helpers.hpp index 079fef90b..9c5ffe72f 100644 --- a/include/stlsoft/util/resizeable_buffer_helpers.hpp +++ b/include/stlsoft/util/resizeable_buffer_helpers.hpp @@ -4,11 +4,11 @@ * Purpose: Utility functions for working with resizeable-buffers. * * Created: 24th December 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 @@ -45,6 +45,9 @@ * \brief [C++] Utility functions for working with resizeable-buffers * templates * (\ref group__library__Utility "Utility" Library). + * + * \see CONCEPTS.md in the project root — *The Resizeable Buffer concept* + * (probe-then-fill gold standard and overload contract). */ #ifndef STLSOFT_INCL_STLSOFT_UTIL_HPP_RESIZEABLE_BUFFER_HELPERS From ac0c13d6951258add54d1ebdf606bc86ded09960 Mon Sep 17 00:00:00 2001 From: Matt Wilson Date: Thu, 15 Oct 2026 14:46:13 +1100 Subject: [PATCH 05/23] fix(unixstl): harden home/env resizeable-buffer overloads and cover them Align get_home_directory(rb) and get_environment_variable(rb) with the probe-then-fill contract (unchanged rb on probe failure; resizeable_buffer_resize with ENOMEM; env demand includes NUL); add component suite test.component.unixstl.system.system_traits. --- include/unixstl/system/system_traits.hpp | 73 +++++- test/component/unixstl/system/CMakeLists.txt | 1 + .../system/system_traits/CMakeLists.txt | 2 + .../unixstl/system/system_traits/entry.cpp | 227 ++++++++++++++++++ 4 files changed, 291 insertions(+), 12 deletions(-) create mode 100644 test/component/unixstl/system/system_traits/CMakeLists.txt create mode 100644 test/component/unixstl/system/system_traits/entry.cpp diff --git a/include/unixstl/system/system_traits.hpp b/include/unixstl/system/system_traits.hpp index 3be241776..352508d83 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/ * @@ -270,9 +270,17 @@ struct system_traits , size_type cchBuffer ); - /// Gets the full path name of the current user's home directory + /// Gets the full path name of the current user's home directory into a + /// resizeable buffer (probe-then-fill; see CONCEPTS.md) + /// + /// \param rb Reference to a resizeable buffer that will be resized as + /// required to hold the path and a terminating NUL character; /// - /// \param rb Reference to a resizeable buffer + /// \return The length of the path (excluding the NUL character) on + /// success; 0 on failure. 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; template< ss_typename_param_k T_resizeableBuffer > @@ -345,11 +353,19 @@ struct system_traits , size_type cchBuffer ); - /// Gets an environment variable into the given buffer + /// Gets an environment variable into a resizeable buffer + /// (probe-then-fill; see CONCEPTS.md) /// - /// \param name The name of the variable to find + /// \param name The name of the variable to find; /// \param rb Reference to a resizeable buffer into which the - /// environment variable value is to be written + /// environment variable value is to be written. Resized to the + /// probed value length plus one for the terminating NUL (the raw + /// null-buffer probe returns the length excluding the NUL); + /// + /// \return The length of the value (excluding the NUL character) on + /// success; 0 on failure (missing variable, or resize failure). On + /// query failure \c rb is left unchanged; on resize failure + /// ENOMEM is set and \c rb is left unchanged; template< ss_typename_param_k T_resizeableBuffer > @@ -602,9 +618,25 @@ struct system_traits T_resizeableBuffer& rb ) { - size_type const cchRequired = get_home_directory(static_cast(NULL), 0); + size_type const cchRequired = get_home_directory( + static_cast(NULL) + , 0 + ); + + if (0 == cchRequired) + { + return 0; + } - rb.resize(cchRequired); + if (rb.size() < cchRequired) + { + if (!STLSOFT_NS_QUAL(resizeable_buffer_resize)(rb, cchRequired)) + { + set_last_error(ENOMEM); + + return 0; + } + } return get_home_directory(&rb[0], rb.size()); } @@ -705,14 +737,31 @@ struct system_traits , T_resizeableBuffer& rb ) { - size_type const cchRequired = get_environment_variable(name, static_cast(NULL), 0); - - if (0 == cchRequired) + /* The raw null-buffer probe returns the value length excluding the + * NUL; the resizeable-buffer overload needs demand including NUL. + */ + size_type const cchValue = get_environment_variable( + name + , static_cast(NULL) + , 0 + ); + + if (0 == cchValue) { return 0; } - rb.resize(cchRequired); + size_type const cchRequired = cchValue + 1; + + if (rb.size() < cchRequired) + { + if (!STLSOFT_NS_QUAL(resizeable_buffer_resize)(rb, cchRequired)) + { + set_last_error(ENOMEM); + + return 0; + } + } return get_environment_variable(name, &rb[0], rb.size()); } diff --git a/test/component/unixstl/system/CMakeLists.txt b/test/component/unixstl/system/CMakeLists.txt index eefe07f3a..82b193abc 100644 --- a/test/component/unixstl/system/CMakeLists.txt +++ b/test/component/unixstl/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(environment_variable) +add_subdirectory(system_traits) 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 000000000..abafd1939 --- /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 000000000..8b427a0ef --- /dev/null +++ b/test/component/unixstl/system/system_traits/entry.cpp @@ -0,0 +1,227 @@ +/* ///////////////////////////////////////////////////////////////////////// + * File: test/component/unixstl/system/system_traits/entry.cpp + * + * Purpose: Component-tests for resizeable-buffer overloads of + * `unixstl::system_traits` (`get_home_directory`, + * `get_environment_variable`). + * + * 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 + + +/* ///////////////////////////////////////////////////////////////////////// + * 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_home_directory_RESIZEABLE_auto_buffer(); + static void TEST_get_home_directory_RESIZEABLE_vector(); +} // 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_home_directory_RESIZEABLE_auto_buffer); + XTESTS_RUN_CASE(TEST_get_home_directory_RESIZEABLE_vector); + + XTESTS_PRINT_RESULTS(); + + XTESTS_END_RUNNER_UPDATE_EXITCODE(&retCode); + } + + return retCode; +} + + +/* ///////////////////////////////////////////////////////////////////////// + * test function implementations + */ + +namespace { + + typedef unixstl::system_traits traits_m_t; + typedef stlsoft::auto_buffer ab_m_t; + typedef std::vector vec_m_t; + + static char const s_missing_name[] = + "STLSOFT_TEST_ENV_ABSENT_9F3C2B1A_7E4D_4A6F_9C08_1D2E3F4A5B6C"; + + static char const s_present_name[] = + "STLSOFT_TEST_ENV_PRESENT_9F3C2B1A_7E4D_4A6F_9C08_1D2E3F4A5B6C"; + + static char const s_present_value[] = "resizeable-buffer-value"; + + +static void TEST_get_environment_variable_MISSING() +{ + { + ab_m_t rb(0); + size_t const n = traits_m_t::get_environment_variable(s_missing_name, rb); + + TEST_INT_EQ(0, n); + TEST_INT_EQ(0, rb.size()); + } + + { + vec_m_t rb; + size_t const n = traits_m_t::get_environment_variable(s_missing_name, rb); + + TEST_INT_EQ(0, n); + TEST_INT_EQ(0, rb.size()); + } + + { + ab_m_t rb(3); + rb[0] = 'a'; + rb[1] = 'b'; + rb[2] = 'c'; + + size_t const n = traits_m_t::get_environment_variable(s_missing_name, rb); + + TEST_INT_EQ(0, n); + TEST_INT_EQ(3, rb.size()); + TEST_CHAR_EQ('a', rb[0]); + TEST_CHAR_EQ('b', rb[1]); + TEST_CHAR_EQ('c', rb[2]); + } +} + +static void TEST_get_environment_variable_RESIZEABLE_auto_buffer() +{ + platformstl::environment_variable_scope const scope( + s_present_name + , s_present_value + ); + + size_t const expected_len = ::strlen(s_present_value); + ab_m_t rb(0); + size_t const n = traits_m_t::get_environment_variable(s_present_name, rb); + + TEST_INT_EQ(expected_len, n); + TEST_INT_EQ(expected_len + 1, rb.size()); + TEST_CHAR_EQ('\0', rb[n]); + TEST_MS_EQ(s_present_value, rb.data()); +} + +static void TEST_get_environment_variable_RESIZEABLE_vector() +{ + platformstl::environment_variable_scope const scope( + s_present_name + , s_present_value + ); + + size_t const expected_len = ::strlen(s_present_value); + vec_m_t rb; + size_t const n = traits_m_t::get_environment_variable(s_present_name, rb); + + TEST_INT_EQ(expected_len, n); + TEST_INT_EQ(expected_len + 1, rb.size()); + TEST_CHAR_EQ('\0', rb[n]); + TEST_MS_EQ(s_present_value, &rb[0]); +} + +static void TEST_get_home_directory_RESIZEABLE_auto_buffer() +{ + char const* const home = ::getenv("HOME"); + + if (NULL == home) + { + ab_m_t rb(0); + size_t const n = traits_m_t::get_home_directory(rb); + + TEST_INT_EQ(0, n); + TEST_INT_EQ(0, rb.size()); + + return; + } + + size_t const expected_len = ::strlen(home); + ab_m_t rb(0); + size_t const n = traits_m_t::get_home_directory(rb); + + TEST_INT_EQ(expected_len, n); + TEST_INT_EQ(expected_len + 1, rb.size()); + TEST_CHAR_EQ('\0', rb[n]); + TEST_MS_EQ(home, rb.data()); +} + +static void TEST_get_home_directory_RESIZEABLE_vector() +{ + char const* const home = ::getenv("HOME"); + + if (NULL == home) + { + vec_m_t rb; + size_t const n = traits_m_t::get_home_directory(rb); + + TEST_INT_EQ(0, n); + TEST_INT_EQ(0, rb.size()); + + return; + } + + size_t const expected_len = ::strlen(home); + vec_m_t rb; + size_t const n = traits_m_t::get_home_directory(rb); + + TEST_INT_EQ(expected_len, n); + TEST_INT_EQ(expected_len + 1, rb.size()); + TEST_CHAR_EQ('\0', rb[n]); + TEST_MS_EQ(home, &rb[0]); +} + +} // anonymous namespace + + +/* ///////////////////////////// end of file //////////////////////////// */ From 9c8378f71112551cbe80b7251be80b521543544b Mon Sep 17 00:00:00 2001 From: Matt Wilson Date: Thu, 15 Oct 2026 14:52:28 +1100 Subject: [PATCH 06/23] test(stlsoft): cover filesystem_traits path rb overloads Lock the C4 gold path for get_current_directory, get_full_path_name, and get_short_path_name resizeable-buffer overloads: empty auto_buffer and vector callers on unixstl (new paths component suite) and winstl (extended filesystem_traits component suite). --- .../unixstl/filesystem/filesystem_traits.hpp | 37 ++- include/unixstl/system/system_traits.hpp | 8 +- .../winstl/filesystem/filesystem_traits.hpp | 110 +++++++- .../filesystem_traits/CMakeLists.txt | 1 + .../filesystem_traits/paths/CMakeLists.txt | 2 + .../filesystem_traits/paths/entry.cpp | 250 ++++++++++++++++++ .../filesystem/filesystem_traits/entry.cpp | 157 ++++++++++- 7 files changed, 539 insertions(+), 26 deletions(-) create mode 100644 test/component/unixstl/filesystem/filesystem_traits/paths/CMakeLists.txt create mode 100644 test/component/unixstl/filesystem/filesystem_traits/paths/entry.cpp diff --git a/include/unixstl/filesystem/filesystem_traits.hpp b/include/unixstl/filesystem/filesystem_traits.hpp index c392cdd08..e41ec7682 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 @@ -2123,13 +2123,27 @@ return 0; , T_resizeableBuffer& rb ) { - size_type const cchRequired = get_full_path_name(fileName, static_cast(NULL), 0); + size_type const cchRequired = get_full_path_name( + fileName + , static_cast(NULL) + , 0 + ); - if (!resizeable_buffer_resize(rb, cchRequired)) + if (0 == cchRequired) { return 0; } + if (rb.size() < cchRequired) + { + if (!resizeable_buffer_resize(rb, cchRequired)) + { + set_last_error(ENOMEM); + + return 0; + } + } + return get_full_path_name(fileName, &rb[0], rb.size()); } @@ -2239,13 +2253,26 @@ return 0; T_resizeableBuffer& rb ) { - size_type const cchRequired = get_current_directory(static_cast(NULL), 0); + size_type const cchRequired = get_current_directory( + static_cast(NULL) + , 0 + ); - if (!resizeable_buffer_resize(rb, cchRequired)) + if (0 == cchRequired) { return 0; } + if (rb.size() < cchRequired) + { + if (!resizeable_buffer_resize(rb, cchRequired)) + { + set_last_error(ENOMEM); + + return 0; + } + } + return get_current_directory(&rb[0], rb.size()); } diff --git a/include/unixstl/system/system_traits.hpp b/include/unixstl/system/system_traits.hpp index 352508d83..f4e677367 100644 --- a/include/unixstl/system/system_traits.hpp +++ b/include/unixstl/system/system_traits.hpp @@ -271,7 +271,7 @@ struct system_traits ); /// Gets the full path name of the current user's home directory into a - /// resizeable buffer (probe-then-fill; see CONCEPTS.md) + /// resizeable buffer (probe-then-fill; see CONCEPTS.md). /// /// \param rb Reference to a resizeable buffer that will be resized as /// required to hold the path and a terminating NUL character; @@ -280,7 +280,7 @@ struct system_traits /// success; 0 on failure. 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; + /// on an empty buffer. template< ss_typename_param_k T_resizeableBuffer > @@ -354,7 +354,7 @@ struct system_traits ); /// Gets an environment variable into a resizeable buffer - /// (probe-then-fill; see CONCEPTS.md) + /// (probe-then-fill; see CONCEPTS.md). /// /// \param name The name of the variable to find; /// \param rb Reference to a resizeable buffer into which the @@ -365,7 +365,7 @@ struct system_traits /// \return The length of the value (excluding the NUL character) on /// success; 0 on failure (missing variable, or resize failure). On /// query failure \c rb is left unchanged; on resize failure - /// ENOMEM is set and \c rb is left unchanged; + /// ENOMEM is set and \c rb is left unchanged. template< ss_typename_param_k T_resizeableBuffer > diff --git a/include/winstl/filesystem/filesystem_traits.hpp b/include/winstl/filesystem/filesystem_traits.hpp index fe194b8ae..272b36843 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. * @@ -2015,13 +2015,27 @@ struct filesystem_traits , T_resizeableBuffer& rb ) { - size_type const cchRequired = get_full_path_name(fileName, static_cast(NULL), 0); + size_type const cchRequired = get_full_path_name( + fileName + , static_cast(NULL) + , 0 + ); - if (!resizeable_buffer_resize(rb, cchRequired)) + if (0 == cchRequired) { return 0; } + if (rb.size() < cchRequired) + { + if (!resizeable_buffer_resize(rb, cchRequired)) + { + set_last_error(ERROR_OUTOFMEMORY); + + return 0; + } + } + return get_full_path_name(fileName, &rb[0], rb.size()); } @@ -2067,13 +2081,27 @@ struct filesystem_traits , T_resizeableBuffer& rb ) { - size_type const cchRequired = get_short_path_name(fileName, static_cast(NULL), 0); + size_type const cchRequired = get_short_path_name( + fileName + , static_cast(NULL) + , 0 + ); - if (!resizeable_buffer_resize(rb, cchRequired)) + if (0 == cchRequired) { return 0; } + if (rb.size() < cchRequired) + { + if (!resizeable_buffer_resize(rb, cchRequired)) + { + set_last_error(ERROR_OUTOFMEMORY); + + return 0; + } + } + return get_short_path_name(fileName, &rb[0], rb.size()); } @@ -2151,13 +2179,26 @@ struct filesystem_traits T_resizeableBuffer& rb ) { - size_type const cchRequired = get_current_directory(static_cast(NULL), 0); + size_type const cchRequired = get_current_directory( + static_cast(NULL) + , 0 + ); - if (!resizeable_buffer_resize(rb, cchRequired)) + if (0 == cchRequired) { return 0; } + if (rb.size() < cchRequired) + { + if (!resizeable_buffer_resize(rb, cchRequired)) + { + set_last_error(ERROR_OUTOFMEMORY); + + return 0; + } + } + return get_current_directory(&rb[0], rb.size()); } @@ -3374,13 +3415,27 @@ struct filesystem_traits , T_resizeableBuffer& rb ) { - size_type const cchRequired = get_full_path_name(fileName, static_cast(NULL), 0); + size_type const cchRequired = get_full_path_name( + fileName + , static_cast(NULL) + , 0 + ); - if (!resizeable_buffer_resize(rb, cchRequired)) + if (0 == cchRequired) { return 0; } + if (rb.size() < cchRequired) + { + if (!resizeable_buffer_resize(rb, cchRequired)) + { + set_last_error(ERROR_OUTOFMEMORY); + + return 0; + } + } + return get_full_path_name(fileName, &rb[0], rb.size()); } @@ -3426,13 +3481,27 @@ struct filesystem_traits , T_resizeableBuffer& rb ) { - size_type const cchRequired = get_short_path_name(fileName, static_cast(NULL), 0); + size_type const cchRequired = get_short_path_name( + fileName + , static_cast(NULL) + , 0 + ); - if (!resizeable_buffer_resize(rb, cchRequired)) + if (0 == cchRequired) { return 0; } + if (rb.size() < cchRequired) + { + if (!resizeable_buffer_resize(rb, cchRequired)) + { + set_last_error(ERROR_OUTOFMEMORY); + + return 0; + } + } + return get_short_path_name(fileName, &rb[0], rb.size()); } @@ -3511,13 +3580,26 @@ struct filesystem_traits T_resizeableBuffer& rb ) { - size_type const cchRequired = get_current_directory(static_cast(NULL), 0); + size_type const cchRequired = get_current_directory( + static_cast(NULL) + , 0 + ); - if (!resizeable_buffer_resize(rb, cchRequired)) + if (0 == cchRequired) { return 0; } + if (rb.size() < cchRequired) + { + if (!resizeable_buffer_resize(rb, cchRequired)) + { + set_last_error(ERROR_OUTOFMEMORY); + + return 0; + } + } + return get_current_directory(&rb[0], rb.size()); } diff --git a/test/component/unixstl/filesystem/filesystem_traits/CMakeLists.txt b/test/component/unixstl/filesystem/filesystem_traits/CMakeLists.txt index 8460ebf33..7c3363b5e 100644 --- a/test/component/unixstl/filesystem/filesystem_traits/CMakeLists.txt +++ b/test/component/unixstl/filesystem/filesystem_traits/CMakeLists.txt @@ -1,2 +1,3 @@ # SIS:AUTO_GENERATED: Remove this line if you edit the file, otherwise it will be overwritten add_subdirectory(opendir) +add_subdirectory(paths) diff --git a/test/component/unixstl/filesystem/filesystem_traits/paths/CMakeLists.txt b/test/component/unixstl/filesystem/filesystem_traits/paths/CMakeLists.txt new file mode 100644 index 000000000..c9319f9fd --- /dev/null +++ b/test/component/unixstl/filesystem/filesystem_traits/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.filesystem.filesystem_traits.paths entry.cpp) diff --git a/test/component/unixstl/filesystem/filesystem_traits/paths/entry.cpp b/test/component/unixstl/filesystem/filesystem_traits/paths/entry.cpp new file mode 100644 index 000000000..9940643f7 --- /dev/null +++ b/test/component/unixstl/filesystem/filesystem_traits/paths/entry.cpp @@ -0,0 +1,250 @@ +/* ///////////////////////////////////////////////////////////////////////// + * File: test/component/unixstl/filesystem/filesystem_traits/paths/entry.cpp + * + * Purpose: Component-tests for resizeable-buffer overloads of + * `unixstl::filesystem_traits` (`get_current_directory`, + * `get_full_path_name`, `get_short_path_name`). + * + * 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 + +/* Standard C++ header files */ +#include + +/* Standard C header files */ +#include +#include + + +/* ///////////////////////////////////////////////////////////////////////// + * forward declarations + */ + +namespace { + + static void TEST_get_current_directory_RESIZEABLE_auto_buffer(); + static void TEST_get_current_directory_RESIZEABLE_vector(); + static void TEST_get_full_path_name_RESIZEABLE_auto_buffer(); + static void TEST_get_full_path_name_RESIZEABLE_vector(); + static void TEST_get_short_path_name_RESIZEABLE_auto_buffer(); + static void TEST_get_short_path_name_RESIZEABLE_vector(); +} // 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.filesystem.filesystem_traits.paths", verbosity)) + { + XTESTS_RUN_CASE(TEST_get_current_directory_RESIZEABLE_auto_buffer); + XTESTS_RUN_CASE(TEST_get_current_directory_RESIZEABLE_vector); + XTESTS_RUN_CASE(TEST_get_full_path_name_RESIZEABLE_auto_buffer); + XTESTS_RUN_CASE(TEST_get_full_path_name_RESIZEABLE_vector); + XTESTS_RUN_CASE(TEST_get_short_path_name_RESIZEABLE_auto_buffer); + XTESTS_RUN_CASE(TEST_get_short_path_name_RESIZEABLE_vector); + + XTESTS_PRINT_RESULTS(); + + XTESTS_END_RUNNER_UPDATE_EXITCODE(&retCode); + } + + return retCode; +} + + +/* ///////////////////////////////////////////////////////////////////////// + * test function implementations + */ + +namespace { + + typedef unixstl::filesystem_traits traits_m_t; + typedef stlsoft::auto_buffer ab_m_t; + typedef std::vector vec_m_t; + + + static + size_t + capture_fixed( + size_t (*fn)(char*, size_t) + , vec_m_t& expected + ) + { + expected.resize(1 + traits_m_t::path_max()); + + size_t const n = fn(&expected[0], expected.size()); + + if (0 != n && + n < expected.size()) + { + expected.resize(n + 1); + expected[n] = '\0'; + } + + return n; + } + + static + size_t + capture_cwd( + char* buffer + , size_t cchBuffer + ) + { + return traits_m_t::get_current_directory(buffer, cchBuffer); + } + + static + size_t + capture_full_dot( + char* buffer + , size_t cchBuffer + ) + { + return traits_m_t::get_full_path_name(".", buffer, cchBuffer); + } + + static + size_t + capture_short_dot( + char* buffer + , size_t cchBuffer + ) + { + return traits_m_t::get_short_path_name(".", buffer, cchBuffer); + } + + +static void TEST_get_current_directory_RESIZEABLE_auto_buffer() +{ + vec_m_t expected; + size_t const expected_len = capture_fixed(capture_cwd, expected); + + TEST_INT_NE(0, expected_len); + + ab_m_t rb(0); + size_t const n = traits_m_t::get_current_directory(rb); + + TEST_INT_EQ(expected_len, n); + TEST_INT_EQ(expected_len + 1, rb.size()); + TEST_CHAR_EQ('\0', rb[n]); + TEST_MS_EQ(&expected[0], rb.data()); +} + +static void TEST_get_current_directory_RESIZEABLE_vector() +{ + vec_m_t expected; + size_t const expected_len = capture_fixed(capture_cwd, expected); + + TEST_INT_NE(0, expected_len); + + vec_m_t rb; + size_t const n = traits_m_t::get_current_directory(rb); + + TEST_INT_EQ(expected_len, n); + TEST_INT_EQ(expected_len + 1, rb.size()); + TEST_CHAR_EQ('\0', rb[n]); + TEST_MS_EQ(&expected[0], &rb[0]); +} + +static void TEST_get_full_path_name_RESIZEABLE_auto_buffer() +{ + vec_m_t expected; + size_t const expected_len = capture_fixed(capture_full_dot, expected); + + TEST_INT_NE(0, expected_len); + + ab_m_t rb(0); + size_t const n = traits_m_t::get_full_path_name(".", rb); + + TEST_INT_EQ(expected_len, n); + TEST_INT_EQ(expected_len + 1, rb.size()); + TEST_CHAR_EQ('\0', rb[n]); + TEST_MS_EQ(&expected[0], rb.data()); +} + +static void TEST_get_full_path_name_RESIZEABLE_vector() +{ + vec_m_t expected; + size_t const expected_len = capture_fixed(capture_full_dot, expected); + + TEST_INT_NE(0, expected_len); + + vec_m_t rb; + size_t const n = traits_m_t::get_full_path_name(".", rb); + + TEST_INT_EQ(expected_len, n); + TEST_INT_EQ(expected_len + 1, rb.size()); + TEST_CHAR_EQ('\0', rb[n]); + TEST_MS_EQ(&expected[0], &rb[0]); +} + +static void TEST_get_short_path_name_RESIZEABLE_auto_buffer() +{ + vec_m_t expected; + size_t const expected_len = capture_fixed(capture_short_dot, expected); + + TEST_INT_NE(0, expected_len); + + ab_m_t rb(0); + size_t const n = traits_m_t::get_short_path_name(".", rb); + + TEST_INT_EQ(expected_len, n); + TEST_INT_EQ(expected_len + 1, rb.size()); + TEST_CHAR_EQ('\0', rb[n]); + TEST_MS_EQ(&expected[0], rb.data()); +} + +static void TEST_get_short_path_name_RESIZEABLE_vector() +{ + vec_m_t expected; + size_t const expected_len = capture_fixed(capture_short_dot, expected); + + TEST_INT_NE(0, expected_len); + + vec_m_t rb; + size_t const n = traits_m_t::get_short_path_name(".", rb); + + TEST_INT_EQ(expected_len, n); + TEST_INT_EQ(expected_len + 1, rb.size()); + TEST_CHAR_EQ('\0', rb[n]); + TEST_MS_EQ(&expected[0], &rb[0]); +} + +} // anonymous namespace + + +/* ///////////////////////////// end of file //////////////////////////// */ diff --git a/test/component/winstl/filesystem/filesystem_traits/entry.cpp b/test/component/winstl/filesystem/filesystem_traits/entry.cpp index add202432..ace529cf8 100644 --- a/test/component/winstl/filesystem/filesystem_traits/entry.cpp +++ b/test/component/winstl/filesystem/filesystem_traits/entry.cpp @@ -1,10 +1,10 @@ /* ///////////////////////////////////////////////////////////////////////// - * File: filesystem_traits/entry.cpp + * File: test/component/winstl/filesystem/filesystem_traits/entry.cpp * * Purpose: Component-tests for `winstl::filesystem_traits`. * * Created: 31st December 2008 - * Updated: 29th September 2026 + * Updated: 15th October 2026 * * ////////////////////////////////////////////////////////////////////// */ @@ -47,6 +47,12 @@ namespace { static void TEST_FIND_FILE_1(); static void TEST_FIND_FILE_2(); + static void TEST_get_current_directory_RESIZEABLE_auto_buffer(); + static void TEST_get_current_directory_RESIZEABLE_vector(); + static void TEST_get_full_path_name_RESIZEABLE_auto_buffer(); + static void TEST_get_full_path_name_RESIZEABLE_vector(); + static void TEST_get_short_path_name_RESIZEABLE_auto_buffer(); + static void TEST_get_short_path_name_RESIZEABLE_vector(); } // anonymous namespace @@ -54,7 +60,7 @@ namespace { * main() */ -int main(int argc, char *argv[]) +int main(int argc, char* argv[]) { int retCode = EXIT_SUCCESS; int verbosity = 2; @@ -65,6 +71,12 @@ int main(int argc, char *argv[]) { XTESTS_RUN_CASE(TEST_FIND_FILE_1); XTESTS_RUN_CASE(TEST_FIND_FILE_2); + XTESTS_RUN_CASE(TEST_get_current_directory_RESIZEABLE_auto_buffer); + XTESTS_RUN_CASE(TEST_get_current_directory_RESIZEABLE_vector); + XTESTS_RUN_CASE(TEST_get_full_path_name_RESIZEABLE_auto_buffer); + XTESTS_RUN_CASE(TEST_get_full_path_name_RESIZEABLE_vector); + XTESTS_RUN_CASE(TEST_get_short_path_name_RESIZEABLE_auto_buffer); + XTESTS_RUN_CASE(TEST_get_short_path_name_RESIZEABLE_vector); XTESTS_PRINT_RESULTS(); @@ -179,6 +191,145 @@ static void TEST_FIND_FILE_2() } } } + + +static void TEST_get_current_directory_RESIZEABLE_auto_buffer() +{ + vec_m_t expected(1 + filesystem_traits_m_t::path_max()); + size_t const expected_len = filesystem_traits_m_t::get_current_directory( + &expected[0] + , expected.size() + ); + + TEST_INT_NE(0, expected_len); + + ab_m_t rb(0); + size_t const n = filesystem_traits_m_t::get_current_directory(rb); + + TEST_INT_EQ(expected_len, n); + TEST_INT_EQ(expected_len + 1, rb.size()); + TEST_CHAR_EQ('\0', rb[n]); + TEST_MS_EQ(&expected[0], rb.data()); +} + +static void TEST_get_current_directory_RESIZEABLE_vector() +{ + vec_m_t expected(1 + filesystem_traits_m_t::path_max()); + size_t const expected_len = filesystem_traits_m_t::get_current_directory( + &expected[0] + , expected.size() + ); + + TEST_INT_NE(0, expected_len); + + vec_m_t rb; + size_t const n = filesystem_traits_m_t::get_current_directory(rb); + + TEST_INT_EQ(expected_len, n); + TEST_INT_EQ(expected_len + 1, rb.size()); + TEST_CHAR_EQ('\0', rb[n]); + TEST_MS_EQ(&expected[0], &rb[0]); +} + +static void TEST_get_full_path_name_RESIZEABLE_auto_buffer() +{ + char const* const fileName = "."; + + vec_m_t expected(1 + filesystem_traits_m_t::path_max()); + size_t const expected_len = filesystem_traits_m_t::get_full_path_name( + fileName + , &expected[0] + , expected.size() + ); + + TEST_INT_NE(0, expected_len); + + ab_m_t rb(0); + size_t const n = filesystem_traits_m_t::get_full_path_name(fileName, rb); + + TEST_INT_EQ(expected_len, n); + TEST_INT_EQ(expected_len + 1, rb.size()); + TEST_CHAR_EQ('\0', rb[n]); + TEST_MS_EQ(&expected[0], rb.data()); +} + +static void TEST_get_full_path_name_RESIZEABLE_vector() +{ + char const* const fileName = "."; + + vec_m_t expected(1 + filesystem_traits_m_t::path_max()); + size_t const expected_len = filesystem_traits_m_t::get_full_path_name( + fileName + , &expected[0] + , expected.size() + ); + + TEST_INT_NE(0, expected_len); + + vec_m_t rb; + size_t const n = filesystem_traits_m_t::get_full_path_name(fileName, rb); + + TEST_INT_EQ(expected_len, n); + TEST_INT_EQ(expected_len + 1, rb.size()); + TEST_CHAR_EQ('\0', rb[n]); + TEST_MS_EQ(&expected[0], &rb[0]); +} + +static void TEST_get_short_path_name_RESIZEABLE_auto_buffer() +{ + string_m_t const windir = get_windows_directory(); + + vec_m_t expected(1 + filesystem_traits_m_t::path_max()); + size_t const expected_len = filesystem_traits_m_t::get_short_path_name( + windir.c_str() + , &expected[0] + , expected.size() + ); + + ab_m_t rb(0); + size_t const n = filesystem_traits_m_t::get_short_path_name(windir.c_str(), rb); + + TEST_INT_EQ(expected_len, n); + + if (0 == expected_len) + { + TEST_INT_EQ(0, rb.size()); + } + else + { + TEST_INT_EQ(expected_len + 1, rb.size()); + TEST_CHAR_EQ('\0', rb[n]); + TEST_MS_EQ(&expected[0], rb.data()); + } +} + +static void TEST_get_short_path_name_RESIZEABLE_vector() +{ + string_m_t const windir = get_windows_directory(); + + vec_m_t expected(1 + filesystem_traits_m_t::path_max()); + size_t const expected_len = filesystem_traits_m_t::get_short_path_name( + windir.c_str() + , &expected[0] + , expected.size() + ); + + vec_m_t rb; + size_t const n = filesystem_traits_m_t::get_short_path_name(windir.c_str(), rb); + + TEST_INT_EQ(expected_len, n); + + if (0 == expected_len) + { + TEST_INT_EQ(0, rb.size()); + } + else + { + TEST_INT_EQ(expected_len + 1, rb.size()); + TEST_CHAR_EQ('\0', rb[n]); + TEST_MS_EQ(&expected[0], &rb[0]); + } +} } /* anonymous namespace */ From 5906475072612973e3171003cb451d2f8ca0b74a Mon Sep 17 00:00:00 2001 From: Matt Wilson Date: Thu, 15 Oct 2026 14:58:23 +1100 Subject: [PATCH 07/23] fix(stlsoft): align filesystem_traits ensure/remove_dir_end rb (C2/C3) Make unixstl ensure_dir_end(rb) leave a lone-NUL "" unchanged (n > 1, matching winstl and the C-string overload). Make winstl remove_dir_end(rb) shrink size to the post-strip length so a later ensure_dir_end cannot write past the NUL. Add unixstl unit coverage and strengthen winstl size / round-trip assertions. --- .../unixstl/filesystem/filesystem_traits.hpp | 18 +- .../winstl/filesystem/filesystem_traits.hpp | 48 ++-- test/unit/unixstl/filesystem/CMakeLists.txt | 1 + .../filesystem_traits/CMakeLists.txt | 2 + .../filesystem/filesystem_traits/entry.cpp | 219 ++++++++++++++++++ .../filesystem/filesystem_traits/entry.cpp | 34 ++- 6 files changed, 305 insertions(+), 17 deletions(-) create mode 100644 test/unit/unixstl/filesystem/filesystem_traits/CMakeLists.txt create mode 100644 test/unit/unixstl/filesystem/filesystem_traits/entry.cpp diff --git a/include/unixstl/filesystem/filesystem_traits.hpp b/include/unixstl/filesystem/filesystem_traits.hpp index e41ec7682..1a3e16e21 100644 --- a/include/unixstl/filesystem/filesystem_traits.hpp +++ b/include/unixstl/filesystem/filesystem_traits.hpp @@ -1069,10 +1069,15 @@ struct filesystem_traits { size_type const n = rb.size(); - if (0 != n) + /* Require more than a lone NUL so "" stays "" (matches + * winstl and the C-string overload). + */ + if (n > 1) { if (!resizeable_buffer_resize(rb, n + 1)) { + set_last_error(ENOMEM); + return 0; } @@ -1214,6 +1219,8 @@ struct filesystem_traits if (!resizeable_buffer_resize(rb, n - 1)) { + set_last_error(ENOMEM); + return 0; } @@ -2877,10 +2884,15 @@ struct filesystem_traits { size_type const n = rb.size(); - if (0 != n) + /* Require more than a lone NUL so "" stays "" (matches + * winstl and the C-string overload). + */ + if (n > 1) { if (!resizeable_buffer_resize(rb, n + 1)) { + set_last_error(ENOMEM); + return 0; } @@ -3022,6 +3034,8 @@ struct filesystem_traits if (!resizeable_buffer_resize(rb, n - 1)) { + set_last_error(ENOMEM); + return 0; } diff --git a/include/winstl/filesystem/filesystem_traits.hpp b/include/winstl/filesystem/filesystem_traits.hpp index 272b36843..86bcdc8a2 100644 --- a/include/winstl/filesystem/filesystem_traits.hpp +++ b/include/winstl/filesystem/filesystem_traits.hpp @@ -1222,20 +1222,30 @@ struct filesystem_traits T_resizeableBuffer& rb ) { - size_type len = rb.size(); + size_type const n = rb.size(); - if (0 == len) + if (0 == n) { return 0; } - else - { - size_type lenToDecrease = len - 1; - remove_dir_end(rb.data(), len - 1, &lenToDecrease); + size_type lenToDecrease = n - 1; + + remove_dir_end(rb.data(), n - 1, &lenToDecrease); - return lenToDecrease; + size_type const cchRequired = lenToDecrease + 1; + + if (rb.size() != cchRequired) + { + if (!resizeable_buffer_resize(rb, cchRequired)) + { + set_last_error(ERROR_OUTOFMEMORY); + + return 0; + } } + + return lenToDecrease; } public: // path classification and analysis @@ -2880,20 +2890,30 @@ struct filesystem_traits T_resizeableBuffer& rb ) { - size_type len = rb.size(); + size_type const n = rb.size(); - if (0 == len) + if (0 == n) { return 0; } - else - { - size_type lenToDecrease = len - 1; - remove_dir_end(rb.data(), len - 1, &lenToDecrease); + size_type lenToDecrease = n - 1; + + remove_dir_end(rb.data(), n - 1, &lenToDecrease); - return lenToDecrease; + size_type const cchRequired = lenToDecrease + 1; + + if (rb.size() != cchRequired) + { + if (!resizeable_buffer_resize(rb, cchRequired)) + { + set_last_error(ERROR_OUTOFMEMORY); + + return 0; + } } + + return lenToDecrease; } public: // path classification and analysis diff --git a/test/unit/unixstl/filesystem/CMakeLists.txt b/test/unit/unixstl/filesystem/CMakeLists.txt index 7bfdcb84b..fb3680258 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 000000000..c5ad72a10 --- /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 000000000..cd2f37b32 --- /dev/null +++ b/test/unit/unixstl/filesystem/filesystem_traits/entry.cpp @@ -0,0 +1,219 @@ +/* ///////////////////////////////////////////////////////////////////////// + * 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). + * + * 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 + +/* Standard C++ header files */ +#include + +/* Standard C header files */ +#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(); +} // 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_PRINT_RESULTS(); + + XTESTS_END_RUNNER_UPDATE_EXITCODE(&retCode); + } + + return retCode; +} + + +/* ///////////////////////////////////////////////////////////////////////// + * test function implementations + */ + +namespace { + + typedef unixstl::filesystem_traits traits_m_t; + typedef stlsoft::auto_buffer ab_m_t; + typedef std::vector vec_m_t; + + +static void TEST_ensure_dir_end_EMPTY_stays_empty() +{ + { + char dirname[] = "\0"; + char* r = traits_m_t::ensure_dir_end(dirname); + + TEST_MS_EQ("", dirname); + TEST_PTR_EQ(dirname + 0, r); + } + +#if __cplusplus >= 201103L + + { + ab_m_t buff = { '\0' }; + size_t const r = traits_m_t::ensure_dir_end(buff); + + TEST_MS_EQ("", buff.data()); + TEST_INT_EQ(0, r); + TEST_INT_EQ(1, buff.size()); + } +#endif + + { + vec_m_t buff(0); + size_t const r = traits_m_t::ensure_dir_end(buff); + + TEST_MS_EQ("", buff.data()); + TEST_INT_EQ(0, r); + TEST_INT_EQ(0, buff.size()); + } + + { + vec_m_t buff(1, '\0'); + size_t const r = traits_m_t::ensure_dir_end(buff); + + TEST_MS_EQ("", buff.data()); + TEST_INT_EQ(0, r); + TEST_INT_EQ(1, buff.size()); + } +} + +static void TEST_ensure_dir_end_APPENDS_separator() +{ +#if __cplusplus >= 201103L + + { + ab_m_t buff = { 'a', 'b', 'c', '\0' }; + size_t const r = traits_m_t::ensure_dir_end(buff); + + TEST_MS_EQ("abc/", buff.data()); + TEST_INT_EQ(4, r); + TEST_INT_EQ(5, buff.size()); + } +#endif + + { + vec_m_t buff; + buff.push_back('a'); + buff.push_back('b'); + buff.push_back('c'); + buff.push_back('\0'); + + size_t const r = traits_m_t::ensure_dir_end(buff); + + TEST_MS_EQ("abc/", buff.data()); + TEST_INT_EQ(4, r); + TEST_INT_EQ(5, buff.size()); + } +} + +static void TEST_remove_dir_end_SHRINKS_buffer() +{ +#if __cplusplus >= 201103L + + { + ab_m_t buff = { 'a', 'b', 'c', '/', '\0' }; + size_t const r = traits_m_t::remove_dir_end(buff); + + TEST_MS_EQ("abc", buff.data()); + TEST_INT_EQ(3, r); + TEST_INT_EQ(4, buff.size()); + } +#endif + + { + vec_m_t buff; + buff.push_back('a'); + buff.push_back('b'); + buff.push_back('c'); + buff.push_back('/'); + buff.push_back('\0'); + + size_t const r = traits_m_t::remove_dir_end(buff); + + TEST_MS_EQ("abc", buff.data()); + TEST_INT_EQ(3, r); + TEST_INT_EQ(4, buff.size()); + } +} + +static void TEST_remove_then_ensure_round_trip() +{ + vec_m_t buff; + buff.push_back('a'); + buff.push_back('b'); + buff.push_back('c'); + buff.push_back('/'); + buff.push_back('\0'); + + size_t const n_remove = traits_m_t::remove_dir_end(buff); + + TEST_INT_EQ(3, n_remove); + TEST_INT_EQ(4, buff.size()); + TEST_MS_EQ("abc", buff.data()); + + size_t const n_ensure = traits_m_t::ensure_dir_end(buff); + + TEST_INT_EQ(4, n_ensure); + TEST_INT_EQ(5, buff.size()); + TEST_MS_EQ("abc/", buff.data()); +} + +} // anonymous namespace + + +/* ///////////////////////////// end of file //////////////////////////// */ diff --git a/test/unit/winstl/filesystem/filesystem_traits/entry.cpp b/test/unit/winstl/filesystem/filesystem_traits/entry.cpp index 0a9e3e6e1..db80f2639 100644 --- a/test/unit/winstl/filesystem/filesystem_traits/entry.cpp +++ b/test/unit/winstl/filesystem/filesystem_traits/entry.cpp @@ -4,7 +4,7 @@ * Purpose: Unit-tests for `winstl::filesystem_traits`. * * Created: 31st December 2008 - * Updated: 29th September 2026 + * Updated: 15th October 2026 * * ////////////////////////////////////////////////////////////////////// */ @@ -51,6 +51,7 @@ namespace { static void TEST_has_dir_end_1(); static void TEST_remove_dir_end_1(); + static void TEST_remove_then_ensure_round_trip(); static void TEST_find_last_path_name_separator(); static void TEST_find_next_path_name_separator(); @@ -98,6 +99,7 @@ int main(int argc, char *argv[]) XTESTS_RUN_CASE(TEST_has_dir_end_1); XTESTS_RUN_CASE(TEST_remove_dir_end_1); + XTESTS_RUN_CASE(TEST_remove_then_ensure_round_trip); XTESTS_RUN_CASE(TEST_path_is_absolute_1); XTESTS_RUN_CASE(TEST_path_is_absolute_2); @@ -866,6 +868,7 @@ static void TEST_remove_dir_end_1() TEST_MS_EQ("abc", buff.data()); TEST_INT_EQ(3, r); + TEST_INT_EQ(4, buff.size()); } // passing resizeable buffer (auto_buffer) @@ -875,6 +878,7 @@ static void TEST_remove_dir_end_1() TEST_WS_EQ(L"abc", buff.data()); TEST_INT_EQ(3, r); + TEST_INT_EQ(4, buff.size()); } // passing resizeable buffer (vector) @@ -884,6 +888,7 @@ static void TEST_remove_dir_end_1() TEST_MS_EQ("abc", buff.data()); TEST_INT_EQ(3, r); + TEST_INT_EQ(4, buff.size()); } // passing resizeable buffer (vector) @@ -893,6 +898,7 @@ static void TEST_remove_dir_end_1() TEST_WS_EQ(L"abc", buff.data()); TEST_INT_EQ(3, r); + TEST_INT_EQ(4, buff.size()); } #endif } @@ -926,6 +932,7 @@ static void TEST_remove_dir_end_1() TEST_MS_EQ("abc", buff.data()); TEST_INT_EQ(3, r); + TEST_INT_EQ(4, buff.size()); } // passing resizeable buffer (auto_buffer) @@ -935,6 +942,7 @@ static void TEST_remove_dir_end_1() TEST_WS_EQ(L"abc", buff.data()); TEST_INT_EQ(3, r); + TEST_INT_EQ(4, buff.size()); } // passing resizeable buffer (vector) @@ -944,6 +952,7 @@ static void TEST_remove_dir_end_1() TEST_MS_EQ("abc", buff.data()); TEST_INT_EQ(3, r); + TEST_INT_EQ(4, buff.size()); } // passing resizeable buffer (vector) @@ -953,11 +962,34 @@ static void TEST_remove_dir_end_1() TEST_WS_EQ(L"abc", buff.data()); TEST_INT_EQ(3, r); + TEST_INT_EQ(4, buff.size()); } #endif } } +static void TEST_remove_then_ensure_round_trip() +{ + vec_m_t buff; + buff.push_back('a'); + buff.push_back('b'); + buff.push_back('c'); + buff.push_back('\\'); + buff.push_back('\0'); + + ss_size_t const n_remove = filesystem_traits_m_t::remove_dir_end(buff); + + TEST_INT_EQ(3, n_remove); + TEST_INT_EQ(4, buff.size()); + TEST_MS_EQ("abc", buff.data()); + + ss_size_t const n_ensure = filesystem_traits_m_t::ensure_dir_end(buff); + + TEST_INT_EQ(4, n_ensure); + TEST_INT_EQ(5, buff.size()); + TEST_MS_EQ("abc\\", buff.data()); +} + static void TEST_path_is_absolute_1() { { From 3566ab1778258e695dbf950960a05cef8c4e9ef5 Mon Sep 17 00:00:00 2001 From: Matt Wilson Date: Thu, 15 Oct 2026 15:29:03 +1100 Subject: [PATCH 08/23] docs(stlsoft): add Resizeable Buffer concept example Add examples/by_concept/resizeable_buffer demonstrating probe-then-fill into auto_buffer and vector via platformstl traits rb overloads, plus a direct resizeable_buffer_resize use; catalogue in EXAMPLES.md and link from CONCEPTS.md. --- CONCEPTS.md | 4 +- EXAMPLES.md | 1 + examples/by_concept/CMakeLists.txt | 1 + .../resizeable_buffer/CMakeLists.txt | 1 + .../by_concept/resizeable_buffer/main.cpp | 159 ++++++++++++++++++ 5 files changed, 165 insertions(+), 1 deletion(-) create mode 100644 examples/by_concept/resizeable_buffer/CMakeLists.txt create mode 100644 examples/by_concept/resizeable_buffer/main.cpp diff --git a/CONCEPTS.md b/CONCEPTS.md index 030f04f07..7effe3bcd 100644 --- a/CONCEPTS.md +++ b/CONCEPTS.md @@ -179,12 +179,14 @@ the allocated demand (typically at least length + 1). ## See also +* Example: + [`examples/by_concept/resizeable_buffer/`](./examples/by_concept/resizeable_buffer/main.cpp); * Pseudo-struct documentation in `unixstl::filesystem_traits` / `winstl::filesystem_traits` (`struct resizeable_buffer` under `\name concepts`); * Unit tests: [`test/unit/stlsoft/util/resizeable_buffer_helpers/`](./test/unit/stlsoft/util/resizeable_buffer_helpers/); -* [FAQ.md](./FAQ.md), [INSTALL.md](./INSTALL.md); +* [FAQ.md](./FAQ.md), [INSTALL.md](./INSTALL.md), [EXAMPLES.md](./EXAMPLES.md); diff --git a/EXAMPLES.md b/EXAMPLES.md index e5104e6a9..2b29561ba 100644 --- a/EXAMPLES.md +++ b/EXAMPLES.md @@ -3,6 +3,7 @@ | Name | Source & Description | Platform | Summary | | ---- | -------------------- | -------- | ------- | | **By concept**: | | | | +| **resizeable_buffer** | [by_concept/resizeable_buffer](./examples/by_concept/resizeable_buffer/main.cpp) | * | Probe-then-fill into `auto_buffer` / `vector` via traits `rb` overloads ([CONCEPTS.md](./CONCEPTS.md)) | | **time_functions** | [by_concept/string_access_shims/time_functions](./examples/by_concept/string_access_shims/time_functions/main.cpp) | * | Format time-related types via string-access shims (e.g. `struct tm`, `std::chrono`) | | | | | | | **By project**: | | | | diff --git a/examples/by_concept/CMakeLists.txt b/examples/by_concept/CMakeLists.txt index 52b1a73c7..e0d99ef8d 100644 --- a/examples/by_concept/CMakeLists.txt +++ b/examples/by_concept/CMakeLists.txt @@ -1,2 +1,3 @@ # SIS:AUTO_GENERATED: Remove this line if you edit the file, otherwise it will be overwritten +add_subdirectory(resizeable_buffer) add_subdirectory(string_access_shims) diff --git a/examples/by_concept/resizeable_buffer/CMakeLists.txt b/examples/by_concept/resizeable_buffer/CMakeLists.txt new file mode 100644 index 000000000..454f5cdf2 --- /dev/null +++ b/examples/by_concept/resizeable_buffer/CMakeLists.txt @@ -0,0 +1 @@ +define_example_program(resizeable_buffer main.cpp) diff --git a/examples/by_concept/resizeable_buffer/main.cpp b/examples/by_concept/resizeable_buffer/main.cpp new file mode 100644 index 000000000..ffc52ea2c --- /dev/null +++ b/examples/by_concept/resizeable_buffer/main.cpp @@ -0,0 +1,159 @@ +/* ///////////////////////////////////////////////////////////////////////// + * File: by_concept/resizeable_buffer/main.cpp + * + * Purpose: C++ example program demonstrating the Resizeable Buffer + * concept: probe-then-fill into `stlsoft::auto_buffer` and + * `std::vector` via `platformstl` traits `rb` overloads (see + * CONCEPTS.md). + * + * Created: 15th October 2026 + * Updated: 15th October 2026 + * + * ////////////////////////////////////////////////////////////////////// */ + + +/* ///////////////////////////////////////////////////////////////////////// + * includes + */ + +#include +#include + +#include +#include + +#include +#include + +#include +#include + + +/* ///////////////////////////////////////////////////////////////////////// + * types + */ + +typedef platformstl::system_traits system_traits_t; +typedef platformstl::filesystem_traits filesystem_traits_t; +typedef stlsoft::auto_buffer ab_t; +typedef std::vector vec_t; + + +/* ///////////////////////////////////////////////////////////////////////// + * helpers + */ + +static +void +print_cstr_field( + char const* label +, char const* s +, size_t n +) +{ + std::cout + << label + << " (" + << n + << " chars): '" + << (NULL != s ? s : "") + << "'" + << std::endl; +} + + +/* ///////////////////////////////////////////////////////////////////////// + * main() + */ + +int main(int /* argc */, char* /* argv */[]) +{ + /* Preferred model: stlsoft::auto_buffer — empty demand, traits resize. + */ + { + ab_t home(0); + size_t const n = system_traits_t::get_home_directory(home); + + if (0 == n) + { + std::cerr << "get_home_directory failed" << std::endl; + } + else + { + print_cstr_field("home (auto_buffer)", home.data(), n); + } + } + + /* Also a model: std::vector — same rb overload contract. + */ + { + vec_t cwd; + size_t const n = filesystem_traits_t::get_current_directory(cwd); + + if (0 == n) + { + std::cerr << "get_current_directory failed" << std::endl; + } + else + { + print_cstr_field("cwd (vector)", &cwd[0], n); + } + } + + /* Environment value into an empty auto_buffer (traits resize via + * resizeable_buffer_resize internally). + */ + { + char const name[] = "PATH"; + ab_t path(0); + size_t const n = system_traits_t::get_environment_variable(name, path); + + if (0 == n) + { + std::cerr << "get_environment_variable(\"" << name << "\") failed" << std::endl; + } + else + { + print_cstr_field("PATH (auto_buffer)", path.data(), n); + } + } + + /* Direct use of the helper: grow a vector before writing into it. + */ + { + vec_t scratch; + + if (!stlsoft::resizeable_buffer_resize(scratch, 8)) + { + std::cerr << "resizeable_buffer_resize failed" << std::endl; + + return EXIT_FAILURE; + } + + scratch[0] = 'r'; + scratch[1] = 'b'; + scratch[2] = '\0'; + + print_cstr_field("helper grown vector", &scratch[0], 2); + } + + /* Path helper on an rb: append a directory separator when missing. + */ + { + vec_t dir; + size_t const n = filesystem_traits_t::get_current_directory(dir); + + if (0 != n) + { + size_t const n2 = filesystem_traits_t::ensure_dir_end(dir); + + print_cstr_field("cwd with dir-end", &dir[0], n2); + } + } + + return EXIT_SUCCESS; +} + + +/* ///////////////////////////// end of file //////////////////////////// */ + From dbb7654bc54409209d244497ffc30bb857267103 Mon Sep 17 00:00:00 2001 From: Matt Wilson Date: Thu, 15 Oct 2026 16:51:54 +1100 Subject: [PATCH 09/23] tidy --- test/unit/winstl/filesystem/filesystem_traits/entry.cpp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/test/unit/winstl/filesystem/filesystem_traits/entry.cpp b/test/unit/winstl/filesystem/filesystem_traits/entry.cpp index db80f2639..7eefb0322 100644 --- a/test/unit/winstl/filesystem/filesystem_traits/entry.cpp +++ b/test/unit/winstl/filesystem/filesystem_traits/entry.cpp @@ -1,5 +1,5 @@ /* ///////////////////////////////////////////////////////////////////////// - * File: filesystem_traits/entry.cpp + * File: test/unit/winstl/filesystem/filesystem_traits/entry.cpp * * Purpose: Unit-tests for `winstl::filesystem_traits`. * From eb4cc36ca93a69fdac6af8accd3e617533dcf776 Mon Sep 17 00:00:00 2001 From: Matt Wilson Date: Fri, 16 Oct 2026 06:39:59 +1100 Subject: [PATCH 10/23] fix(stlsoft): set OOM last-error on filesystem_traits resize failures (C5) Ensure every resizeable_buffer_resize failure in unixstl/winstl filesystem_traits reports ENOMEM / ERROR_OUTOFMEMORY, including winstl ensure_dir_end(rb) and the unixstl full-path cwd scratch grow; add unit tests with a failing-resize buffer model. --- .../unixstl/filesystem/filesystem_traits.hpp | 4 +- .../winstl/filesystem/filesystem_traits.hpp | 6 +- .../filesystem/filesystem_traits/entry.cpp | 64 ++++++++++++++++++- .../filesystem/filesystem_traits/entry.cpp | 63 +++++++++++++++++- 4 files changed, 133 insertions(+), 4 deletions(-) diff --git a/include/unixstl/filesystem/filesystem_traits.hpp b/include/unixstl/filesystem/filesystem_traits.hpp index 1a3e16e21..09568c384 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: 15th October 2026 + * Updated: 16th October 2026 * * Thanks: To Sergey Nikulov, for spotting a preprocessor typo that broke * GCC -pedantic; to Michal Makowski and Zar Eindl for reporting @@ -1827,6 +1827,8 @@ struct filesystem_traits if (!resizeable_buffer_resize(cwd, n2 + len + 1)) { + set_last_error(ENOMEM); + return 0; } diff --git a/include/winstl/filesystem/filesystem_traits.hpp b/include/winstl/filesystem/filesystem_traits.hpp index 86bcdc8a2..d6e9d849f 100644 --- a/include/winstl/filesystem/filesystem_traits.hpp +++ b/include/winstl/filesystem/filesystem_traits.hpp @@ -5,7 +5,7 @@ * Unicode specialisations thereof. * * Created: 15th November 2002 - * Updated: 15th October 2026 + * Updated: 16th October 2026 * * Home: http://stlsoft.org/ * @@ -1082,6 +1082,8 @@ struct filesystem_traits { if (!resizeable_buffer_resize(rb, n + 1)) { + set_last_error(ERROR_OUTOFMEMORY); + return 0; } @@ -2750,6 +2752,8 @@ struct filesystem_traits { if (!resizeable_buffer_resize(rb, n + 1)) { + set_last_error(ERROR_OUTOFMEMORY); + return 0; } diff --git a/test/unit/unixstl/filesystem/filesystem_traits/entry.cpp b/test/unit/unixstl/filesystem/filesystem_traits/entry.cpp index cd2f37b32..03fb50b69 100644 --- a/test/unit/unixstl/filesystem/filesystem_traits/entry.cpp +++ b/test/unit/unixstl/filesystem/filesystem_traits/entry.cpp @@ -6,7 +6,7 @@ * buffer size after remove). * * Created: 15th October 2026 - * Updated: 15th October 2026 + * Updated: 16th October 2026 * * ////////////////////////////////////////////////////////////////////// */ @@ -37,6 +37,7 @@ #include /* Standard C header files */ +#include #include @@ -48,6 +49,7 @@ namespace { static void TEST_ensure_dir_end_EMPTY_stays_empty(); static void TEST_ensure_dir_end_APPENDS_separator(); + static void TEST_ensure_dir_end_RESIZE_FAILURE_sets_ENOMEM(); static void TEST_remove_dir_end_SHRINKS_buffer(); static void TEST_remove_then_ensure_round_trip(); } // anonymous namespace @@ -68,6 +70,7 @@ int main(int argc, char* argv[]) { XTESTS_RUN_CASE(TEST_ensure_dir_end_EMPTY_stays_empty); XTESTS_RUN_CASE(TEST_ensure_dir_end_APPENDS_separator); + XTESTS_RUN_CASE(TEST_ensure_dir_end_RESIZE_FAILURE_sets_ENOMEM); XTESTS_RUN_CASE(TEST_remove_dir_end_SHRINKS_buffer); XTESTS_RUN_CASE(TEST_remove_then_ensure_round_trip); @@ -90,6 +93,47 @@ namespace { typedef stlsoft::auto_buffer ab_m_t; typedef std::vector vec_m_t; + /* Resizeable-buffer model whose resize() always fails — used to lock + * C5 OOM reporting without exhausting the process heap. + */ + struct fail_resize_buffer + { + typedef char value_type; + typedef size_t size_type; + + std::vector storage; + + size_type + size() const + { + return storage.size(); + } + + bool + empty() const + { + return storage.empty(); + } + + char& + operator [](size_type i) + { + return storage[i]; + } + + char const& + operator [](size_type i) const + { + return storage[i]; + } + + bool + resize(size_type /* n */) + { + return false; + } + }; + static void TEST_ensure_dir_end_EMPTY_stays_empty() { @@ -161,6 +205,24 @@ static void TEST_ensure_dir_end_APPENDS_separator() } } +static void TEST_ensure_dir_end_RESIZE_FAILURE_sets_ENOMEM() +{ + fail_resize_buffer rb; + + rb.storage.push_back('a'); + rb.storage.push_back('b'); + rb.storage.push_back('c'); + rb.storage.push_back('\0'); + + traits_m_t::set_last_error(0); + + size_t const n = traits_m_t::ensure_dir_end(rb); + + TEST_INT_EQ(0, n); + TEST_INT_EQ(4, rb.size()); + TEST_INT_EQ(ENOMEM, traits_m_t::get_last_error()); +} + static void TEST_remove_dir_end_SHRINKS_buffer() { #if __cplusplus >= 201103L diff --git a/test/unit/winstl/filesystem/filesystem_traits/entry.cpp b/test/unit/winstl/filesystem/filesystem_traits/entry.cpp index 7eefb0322..f40914502 100644 --- a/test/unit/winstl/filesystem/filesystem_traits/entry.cpp +++ b/test/unit/winstl/filesystem/filesystem_traits/entry.cpp @@ -4,7 +4,7 @@ * Purpose: Unit-tests for `winstl::filesystem_traits`. * * Created: 31st December 2008 - * Updated: 15th October 2026 + * Updated: 16th October 2026 * * ////////////////////////////////////////////////////////////////////// */ @@ -47,6 +47,7 @@ namespace { static void TEST_starts_with_dots(); static void TEST_ensure_dir_end_1(); // TODO: rename to `dirname_ensure_pns()` + static void TEST_ensure_dir_end_RESIZE_FAILURE_sets_ERROR_OUTOFMEMORY(); static void TEST_has_dir_end_1(); @@ -95,6 +96,7 @@ int main(int argc, char *argv[]) XTESTS_RUN_CASE(TEST_starts_with_dots); XTESTS_RUN_CASE(TEST_ensure_dir_end_1); + XTESTS_RUN_CASE(TEST_ensure_dir_end_RESIZE_FAILURE_sets_ERROR_OUTOFMEMORY); XTESTS_RUN_CASE(TEST_has_dir_end_1); @@ -148,6 +150,47 @@ namespace { typedef winstl::filesystem_traits filesystem_traits_m_t; typedef winstl::filesystem_traits filesystem_traits_w_t; + /* Resizeable-buffer model whose resize() always fails — used to lock + * C5 OOM reporting without exhausting the process heap. + */ + struct fail_resize_buffer + { + typedef char value_type; + typedef size_t size_type; + + std::vector storage; + + size_type + size() const + { + return storage.size(); + } + + bool + empty() const + { + return storage.empty(); + } + + char& + operator [](size_type i) + { + return storage[i]; + } + + char const& + operator [](size_type i) const + { + return storage[i]; + } + + bool + resize(size_type /* n */) + { + return false; + } + }; + static void TEST_basename_is_dots() { @@ -486,6 +529,24 @@ static void TEST_ensure_dir_end_1() } } +static void TEST_ensure_dir_end_RESIZE_FAILURE_sets_ERROR_OUTOFMEMORY() +{ + fail_resize_buffer rb; + + rb.storage.push_back('a'); + rb.storage.push_back('b'); + rb.storage.push_back('c'); + rb.storage.push_back('\0'); + + filesystem_traits_m_t::set_last_error(ERROR_SUCCESS); + + ss_size_t const n = filesystem_traits_m_t::ensure_dir_end(rb); + + TEST_INT_EQ(0, n); + TEST_INT_EQ(4, rb.size()); + TEST_INT_EQ(ERROR_OUTOFMEMORY, filesystem_traits_m_t::get_last_error()); +} + static void TEST_has_dir_end_1() { // empty string From 23af7a51bea83952b01a40d30ca1b48ddae5ad29 Mon Sep 17 00:00:00 2001 From: Matt Wilson Date: Fri, 16 Oct 2026 06:44:01 +1100 Subject: [PATCH 11/23] docs(stlsoft): enrich resizeable_buffer_helpers Doxygen (D2) Document the Resizeable Buffer concept at file scope and fully specify resizeable_buffer_resize (parameters, bool/void resize adaptation, retval/failure notes, caller OOM duty); cross-link CONCEPTS.md, the by_concept example, and the helper unit suite. --- CONCEPTS.md | 5 +- .../util/resizeable_buffer_helpers.hpp | 76 ++++++++++++++++--- 2 files changed, 69 insertions(+), 12 deletions(-) diff --git a/CONCEPTS.md b/CONCEPTS.md index 7effe3bcd..80afffb06 100644 --- a/CONCEPTS.md +++ b/CONCEPTS.md @@ -147,7 +147,10 @@ it provides at least: ### Helper: `resizeable_buffer_resize` Declared in -[`stlsoft/util/resizeable_buffer_helpers.hpp`](./include/stlsoft/util/resizeable_buffer_helpers.hpp). +[`stlsoft/util/resizeable_buffer_helpers.hpp`](./include/stlsoft/util/resizeable_buffer_helpers.hpp) +(Doxygen on the file and on the function documents parameters, return +values, failure policy, and the expectation that callers set +`ENOMEM` / `ERROR_OUTOFMEMORY` themselves). `stlsoft::resizeable_buffer_resize(rb, newSize)` invokes `rb.resize(newSize)` whether that member returns `bool` or `void`, and always returns `bool` diff --git a/include/stlsoft/util/resizeable_buffer_helpers.hpp b/include/stlsoft/util/resizeable_buffer_helpers.hpp index 9c5ffe72f..9a0e0afb4 100644 --- a/include/stlsoft/util/resizeable_buffer_helpers.hpp +++ b/include/stlsoft/util/resizeable_buffer_helpers.hpp @@ -4,7 +4,7 @@ * Purpose: Utility functions for working with resizeable-buffers. * * Created: 24th December 2020 - * Updated: 15th October 2026 + * Updated: 16th October 2026 * * Home: http://stlsoft.org/ * @@ -42,12 +42,26 @@ /** \file stlsoft/util/resizeable_buffer_helpers.hpp * - * \brief [C++] Utility functions for working with resizeable-buffers - * templates + * \brief [C++] Helpers for types that model the Resizeable Buffer + * concept * (\ref group__library__Utility "Utility" Library). * - * \see CONCEPTS.md in the project root — *The Resizeable Buffer concept* - * (probe-then-fill gold standard and overload contract). + * A Resizeable Buffer is a contiguous, growable character sequence + * used by UnixSTL / WinSTL system_traits and + * filesystem_traits overloads that take a generic + * rb rather than a raw pointer and length. Preferred models + * include \c stlsoft::auto_buffer and \c std::vector; see + * CONCEPTS.md in the project root for the full + * requirements table, non-models, and the probe-then-fill gold contract + * for traits overloads. + * + * This header provides \c stlsoft::resizeable_buffer_resize, which adapts + * T::resize whether that member returns \c bool or \c void + * so generic code has one failure channel (\c bool). + * + * \see CONCEPTS.md — The Resizeable Buffer concept + * \see examples/by_concept/resizeable_buffer/main.cpp + * \see test/unit/stlsoft/util/resizeable_buffer_helpers/ */ #ifndef STLSOFT_INCL_STLSOFT_UTIL_HPP_RESIZEABLE_BUFFER_HELPERS @@ -56,8 +70,8 @@ #ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION # define STLSOFT_VER_STLSOFT_UTIL_HPP_RESIZEABLE_BUFFER_HELPERS_MAJOR 1 # define STLSOFT_VER_STLSOFT_UTIL_HPP_RESIZEABLE_BUFFER_HELPERS_MINOR 0 -# define STLSOFT_VER_STLSOFT_UTIL_HPP_RESIZEABLE_BUFFER_HELPERS_REVISION 4 -# define STLSOFT_VER_STLSOFT_UTIL_HPP_RESIZEABLE_BUFFER_HELPERS_EDIT 7 +# define STLSOFT_VER_STLSOFT_UTIL_HPP_RESIZEABLE_BUFFER_HELPERS_REVISION 5 +# define STLSOFT_VER_STLSOFT_UTIL_HPP_RESIZEABLE_BUFFER_HELPERS_EDIT 8 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -195,11 +209,51 @@ STLSOFT_CLOSE_WORKER_NS_(ximpl_stlsoft_util_rb_helpers_) * functions */ -/** Invokes resize() on the given buffer, regardless of - * whether the buffer's type's method returns \c bool or \c void +/** Invokes resize() on a Resizeable Buffer, unifying + * bool- and void-returning members. + * + * Prefer this helper over calling rb.resize(newSize) + * directly in generic code (traits templates, concept examples) so that + * failure is always reported as false without caring which + * overload of resize the model provides. + * + * \tparam T_resizeableBuffer A type that models Resizeable Buffer + * for its value_type. Must declare an unambiguous + * resize(size_type) (or resize(size_t)) + * member returning either \c bool or \c void, and a nested + * value_type. + * + * \param rb Reference to the buffer instance to resize + * \param newSize The requested number of elements after the call + * (for path/string use this is typically the probed demand + * including the trailing NUL) + * + * \retval true The resize succeeded. For \c void-returning + * resize, success means the call returned without + * throwing (models such as \c std::vector typically throw + * std::bad_alloc on exhaustion). For \c bool-returning + * resize (e.g. \c stlsoft::auto_buffer), the member's + * return value is propagated. + * \retval false The resize failed. Only reachable when + * T_resizeableBuffer::resize returns \c bool and that + * call returned \c false. On failure the buffer is left unchanged + * when the model obeys the strong guarantee (as + * \c stlsoft::auto_buffer does). + * + * \note This function does not set errno / + * GetLastError. Callers that implement the traits + * rb gold contract should, on \c false, set + * ENOMEM or ERROR_OUTOFMEMORY (as + * appropriate) and return without taking &rb[0] on an + * empty buffer. + * + * \note Element preservation, contiguity, and trailing-NUL invariants + * are properties of the buffer model, not of this helper; see + * CONCEPTS.md. * - * \param rb Reference to the resizeable buffer instance - * \param newSize The new size + * \see stlsoft::auto_buffer::resize + * \see CONCEPTS.md — Helper: resizeable_buffer_resize and + * Contract for traits overloads that take an rb */ template< ss_typename_param_k T_resizeableBuffer From bb148771aa2063ad494f67142b7fd15d849f4a07 Mon Sep 17 00:00:00 2001 From: Matt Wilson Date: Fri, 16 Oct 2026 06:46:23 +1100 Subject: [PATCH 12/23] docs(stlsoft): call out Resizeable Buffer in FAQ, CHANGES, NEWS MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add FAQ Q6 linking CONCEPTS.md, resizeable_buffer_helpers, and the by_concept example; record C1–C5 and docs under CHANGES 1.11.1-rc10; add a NEWS chronology row for the concept and traits hardening (no release tag until the version bump). --- CHANGES.md | 22 ++++++++++++++++++++++ FAQ.md | 19 +++++++++++++++++++ NEWS.md | 1 + 3 files changed, 42 insertions(+) diff --git a/CHANGES.md b/CHANGES.md index 282dca153..f746c27cb 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -1,6 +1,28 @@ # STLSoft - CHANGES +## 1.11.1-rc10 - 16th October 2026 + +* additions: + * Added **CONCEPTS.md** — documents the **Resizeable Buffer** concept (requirements, models / non-models, probe-then-fill gold contract for traits `rb` overloads); + * Added example **examples/by_concept/resizeable_buffer** — probe-then-fill into `auto_buffer` / `vector` via `platformstl` traits `rb` overloads and `resizeable_buffer_resize`; +* fixes: + * **unixstl::system_traits** — `get_home_directory(rb)` and `get_environment_variable(rb)` follow the gold pattern (early-out on probe `0`, conditional resize, `ENOMEM` on failure); environment `rb` demand includes the trailing NUL (`cchValue + 1`); + * **unixstl** / **winstl** `filesystem_traits` — `get_full_path_name` / `get_short_path_name` / `get_current_directory` `rb` overloads no longer resize-then-`&rb[0]` on an empty buffer when the probe returns `0`; resize failure sets `ENOMEM` / `ERROR_OUTOFMEMORY`; + * **unixstl::filesystem_traits** — `ensure_dir_end(rb)` leaves a lone-NUL `""` unchanged (`n > 1`, matching WinSTL and the C-string overload); + * **winstl::filesystem_traits** — `remove_dir_end(rb)` shrinks `size()` to the post-strip length so a later `ensure_dir_end(rb)` cannot write past the NUL; + * **unixstl** / **winstl** `filesystem_traits` — every `resizeable_buffer_resize` failure on the `rb` / scratch paths above reports last-error (including WinSTL `ensure_dir_end(rb)` and the UnixSTL full-path cwd scratch grow); +* docs: + * Enriched Doxygen on **stlsoft/util/resizeable_buffer_helpers.hpp** (`resizeable_buffer_resize` parameters, return values, failure policy, caller OOM duty); + * **FAQ.md** — Q6 on the Resizeable Buffer concept; + * **EXAMPLES.md** — catalogues **by_concept/resizeable_buffer**; +* testing: + * Component tests for unixstl `system_traits` home / environment `rb` overloads; + * Component tests for unixstl / winstl filesystem path `rb` overloads; + * Unit tests for unixstl / winstl `ensure_dir_end` / `remove_dir_end` (including size / round-trip and failing-resize OOM reporting); + * Unit tests for `stlsoft::resizeable_buffer_resize`; + + ## 1.11.1-rc9 - 12th October 2026 * version: diff --git a/FAQ.md b/FAQ.md index bc09e57c0..b8a2e2e69 100644 --- a/FAQ.md +++ b/FAQ.md @@ -12,6 +12,7 @@ it will be used to create one. - [Q3: "How do I use STLSoft?"](#q3-how-do-i-use-stlsoft) - [Q4: "Does STLSoft have unit-tests?"](#q4-does-stlsoft-have-unit-tests) - [Q5: "Is STLSoft still relevant given the widespread support for 'Modern C++'?"](#q5-is-stlsoft-still-relevant-given-the-widespread-support-for-modern-c) +- [Q6: "What is a Resizeable Buffer?"](#q6-what-is-a-resizeable-buffer) # FAQs: @@ -65,4 +66,22 @@ This is a good question. The Synesis open-source libraries — including and more — continue to be maintained in light of contemporary C++ practice, while still supporting a wide range of compilers and platforms. That work informs the future of **STLSoft**, which may mean further investment in the existing 1.x stream or, eventually, a 2.x stream less burdened by historical compiler-feature detection. +## Q6: "What is a Resizeable Buffer?" + +A **Resizeable Buffer** is a contiguous, growable character sequence (for +example `stlsoft::auto_buffer` or `std::vector`) that UnixSTL / WinSTL +`system_traits` and `filesystem_traits` overloads accept as a generic +`rb` instead of a raw pointer and length. Those overloads follow a +**probe-then-fill** contract: query demand with a null buffer and zero +capacity, resize only when needed (via +`stlsoft::resizeable_buffer_resize`), set `ENOMEM` / +`ERROR_OUTOFMEMORY` on resize failure, and never take `&rb[0]` on an +empty buffer. + +See [**CONCEPTS.md**](./CONCEPTS.md), the helper +[`stlsoft/util/resizeable_buffer_helpers.hpp`](./include/stlsoft/util/resizeable_buffer_helpers.hpp), +and the example +[`examples/by_concept/resizeable_buffer/`](./examples/by_concept/resizeable_buffer/main.cpp). + + diff --git a/NEWS.md b/NEWS.md index 3203c8be3..dadf6f4af 100644 --- a/NEWS.md +++ b/NEWS.md @@ -3,6 +3,7 @@ | Date | News Item | Details | | ------------------- | ----------------------------------- | ------- | +| 16th October 2026 | Resizeable Buffer concept & traits `rb` hardening | **CONCEPTS.md**; `resizeable_buffer_resize` docs; example **by_concept/resizeable_buffer**; C1–C5 `rb` / `dir_end` fixes | | 12th October 2026 | Release of [STLSoft 1.11.1-rc9](https://github.com/synesissoftware/STLSoft/releases/tag/1.11.1-rc9) | Version change only | | 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** | From f2412e85bcdd464ec9dbb05781f7e45a54b23b68 Mon Sep 17 00:00:00 2001 From: Matt Wilson Date: Fri, 16 Oct 2026 07:03:47 +1100 Subject: [PATCH 13/23] fix(stlsoft): align unixstl remove_dir_end strip-all; fix readdir soft-fail Match WinSTL by stripping all trailing separators in unixstl filesystem_traits remove_dir_end (C-string and rb); replace the non-exception absolutePath failure path in readdir_sequence (broken \'0' write) with an empty-string soft-fail; extend unit tests and CHANGES/NEWS. --- CHANGES.md | 4 +- NEWS.md | 2 +- TODO.md | 3 +- .../unixstl/filesystem/filesystem_traits.hpp | 64 +++++++++++++------ .../unixstl/filesystem/readdir_sequence.hpp | 17 ++--- .../filesystem/filesystem_traits/entry.cpp | 44 ++++++++++++- 6 files changed, 101 insertions(+), 33 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index f746c27cb..465c44109 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -11,7 +11,9 @@ * **unixstl** / **winstl** `filesystem_traits` — `get_full_path_name` / `get_short_path_name` / `get_current_directory` `rb` overloads no longer resize-then-`&rb[0]` on an empty buffer when the probe returns `0`; resize failure sets `ENOMEM` / `ERROR_OUTOFMEMORY`; * **unixstl::filesystem_traits** — `ensure_dir_end(rb)` leaves a lone-NUL `""` unchanged (`n > 1`, matching WinSTL and the C-string overload); * **winstl::filesystem_traits** — `remove_dir_end(rb)` shrinks `size()` to the post-strip length so a later `ensure_dir_end(rb)` cannot write past the NUL; + * **unixstl::filesystem_traits** — `remove_dir_end` (C-string and `rb`, A+W) now strips **all** trailing path separators, matching WinSTL (was strip-one); * **unixstl** / **winstl** `filesystem_traits` — every `resizeable_buffer_resize` failure on the `rb` / scratch paths above reports last-error (including WinSTL `ensure_dir_end(rb)` and the UnixSTL full-path cwd scratch grow); + * **unixstl::readdir_sequence** — non-exception `absolutePath` failure path no longer contains a broken `\'0'` write; soft-fails with an empty string (parallel to the throw when exceptions are enabled); * docs: * Enriched Doxygen on **stlsoft/util/resizeable_buffer_helpers.hpp** (`resizeable_buffer_resize` parameters, return values, failure policy, caller OOM duty); * **FAQ.md** — Q6 on the Resizeable Buffer concept; @@ -19,7 +21,7 @@ * testing: * Component tests for unixstl `system_traits` home / environment `rb` overloads; * Component tests for unixstl / winstl filesystem path `rb` overloads; - * Unit tests for unixstl / winstl `ensure_dir_end` / `remove_dir_end` (including size / round-trip and failing-resize OOM reporting); + * Unit tests for unixstl / winstl `ensure_dir_end` / `remove_dir_end` (including size / round-trip, failing-resize OOM reporting, and unixstl strip-all trailing separators); * Unit tests for `stlsoft::resizeable_buffer_resize`; diff --git a/NEWS.md b/NEWS.md index dadf6f4af..20a64e383 100644 --- a/NEWS.md +++ b/NEWS.md @@ -3,7 +3,7 @@ | Date | News Item | Details | | ------------------- | ----------------------------------- | ------- | -| 16th October 2026 | Resizeable Buffer concept & traits `rb` hardening | **CONCEPTS.md**; `resizeable_buffer_resize` docs; example **by_concept/resizeable_buffer**; C1–C5 `rb` / `dir_end` fixes | +| 16th October 2026 | Resizeable Buffer concept & traits `rb` hardening | **CONCEPTS.md**; `resizeable_buffer_resize` docs; example **by_concept/resizeable_buffer**; C1–C5 `rb` / `dir_end` fixes; unixstl strip-all `remove_dir_end`; `readdir_sequence` no-exception soft-fail | | 12th October 2026 | Release of [STLSoft 1.11.1-rc9](https://github.com/synesissoftware/STLSoft/releases/tag/1.11.1-rc9) | Version change only | | 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** | diff --git a/TODO.md b/TODO.md index 94a495299..40e9271a6 100644 --- a/TODO.md +++ b/TODO.md @@ -75,7 +75,8 @@ Dedicated increment: **test analysis and coverage only** — no other product ch ### 1.11.6 -* [ ] Flesh out declared-but-undefined `unixstl::system_traits` methods (Linux system calls; emulations/workarounds elsewhere) — see also [**KNOWN_ISSUES.md**](./KNOWN_ISSUES.md); +* [ ] Flesh out declared-but-undefined `unixstl::system_traits` methods (Linux system calls; emulations/workarounds elsewhere) — see also [**KNOWN_ISSUES.md**](./KNOWN_ISSUES.md): + * [ ] `expand_environment_strings` (ANSI + wide; C-string and `rb` overloads) — implement or undeclare (parked Resizeable Buffer **G1**); ### 1.11.7 diff --git a/include/unixstl/filesystem/filesystem_traits.hpp b/include/unixstl/filesystem/filesystem_traits.hpp index 09568c384..8e82db14b 100644 --- a/include/unixstl/filesystem/filesystem_traits.hpp +++ b/include/unixstl/filesystem/filesystem_traits.hpp @@ -426,7 +426,7 @@ struct filesystem_traits T_resizeableBuffer const& rb ); - /// Removes the path name separator from the end of \c dir, if present + /// Removes all trailing path name separators from the end of \c dir /// /// \pre nullptr != dir /// @@ -437,12 +437,12 @@ struct filesystem_traits char_type* dir ); - /// Removes the path name separator from the end of \c dir, if present + /// Removes all trailing path name separators from the end of \c dir /// /// \param path Pointer to characters of path to be examined /// \param len Number of characters in \c path to be examined /// \param pLenToDecrease An optional pointer to a variable that will - /// be decremented if a path name separator is removed + /// be decremented once per path name separator removed /// /// \return \c dir /// @@ -458,7 +458,7 @@ struct filesystem_traits , size_type* pLenToDecrease ); - /// Removes the path name separator from the end of \c rb, if present + /// Removes all trailing path name separators from the end of \c rb /// /// \param rb a reference to a \c resizeable_buffer /// @@ -1189,7 +1189,7 @@ struct filesystem_traits pLenToDecrease = &dummy; } - if (0 != len) + for (; 0 != len; ) { char_type& last = dir[len - 1]; @@ -1198,6 +1198,11 @@ struct filesystem_traits last = char_type(0); --*pLenToDecrease; + --len; + } + else + { + break; } } @@ -1213,21 +1218,30 @@ struct filesystem_traits T_resizeableBuffer& rb ) { - if (has_dir_end(rb)) + size_type const n = rb.size(); + + if (0 == n) { - size_type const n = rb.size(); + return 0; + } - if (!resizeable_buffer_resize(rb, n - 1)) + size_type lenToDecrease = n - 1; + + remove_dir_end(rb.data(), n - 1, &lenToDecrease); + + size_type const cchRequired = lenToDecrease + 1; + + if (rb.size() != cchRequired) + { + if (!resizeable_buffer_resize(rb, cchRequired)) { set_last_error(ENOMEM); return 0; } - - rb[n - 2] = char_type(0); } - return rb.empty() ? 0 : rb.size() - 1; + return lenToDecrease; } public: // path classification and analysis @@ -3006,7 +3020,7 @@ struct filesystem_traits pLenToDecrease = &dummy; } - if (0 != len) + for (; 0 != len; ) { char_type& last = dir[len - 1]; @@ -3015,6 +3029,11 @@ struct filesystem_traits last = char_type(0); --*pLenToDecrease; + --len; + } + else + { + break; } } @@ -3030,21 +3049,30 @@ struct filesystem_traits T_resizeableBuffer& rb ) { - if (has_dir_end(rb)) + size_type const n = rb.size(); + + if (0 == n) { - size_type const n = rb.size(); + return 0; + } - if (!resizeable_buffer_resize(rb, n - 1)) + size_type lenToDecrease = n - 1; + + remove_dir_end(rb.data(), n - 1, &lenToDecrease); + + size_type const cchRequired = lenToDecrease + 1; + + if (rb.size() != cchRequired) + { + if (!resizeable_buffer_resize(rb, cchRequired)) { set_last_error(ENOMEM); return 0; } - - rb[n - 2] = char_type(0); } - return rb.empty() ? 0 : rb.size() - 1; + return lenToDecrease; } public: // path classification and analysis diff --git a/include/unixstl/filesystem/readdir_sequence.hpp b/include/unixstl/filesystem/readdir_sequence.hpp index b9b971390..9a3f55b6f 100644 --- a/include/unixstl/filesystem/readdir_sequence.hpp +++ b/include/unixstl/filesystem/readdir_sequence.hpp @@ -4,7 +4,7 @@ * Purpose: readdir_sequence class. * * Created: 15th January 2002 - * Updated: 29th May 2025 + * Updated: 16th October 2026 * * Home: http://stlsoft.org/ * @@ -53,8 +53,8 @@ #ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION # define UNIXSTL_VER_UNIXSTL_FILESYSTEM_HPP_READDIR_SEQUENCE_MAJOR 5 # define UNIXSTL_VER_UNIXSTL_FILESYSTEM_HPP_READDIR_SEQUENCE_MINOR 6 -# define UNIXSTL_VER_UNIXSTL_FILESYSTEM_HPP_READDIR_SEQUENCE_REVISION 1 -# define UNIXSTL_VER_UNIXSTL_FILESYSTEM_HPP_READDIR_SEQUENCE_EDIT 178 +# define UNIXSTL_VER_UNIXSTL_FILESYSTEM_HPP_READDIR_SEQUENCE_REVISION 2 +# define UNIXSTL_VER_UNIXSTL_FILESYSTEM_HPP_READDIR_SEQUENCE_EDIT 179 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -631,14 +631,9 @@ readdir_sequence::prepare_directory_( STLSOFT_THROW_X(readdir_sequence_exception("failed to obtain full path of search directory", e, directory)); #else /* ? STLSOFT_CF_EXCEPTION_SUPPORT */ - // "+nul" - if (!path.resize(1 + n)) - { - return string_type(); - } - - traits_type::char_copy(&path[0], directory, n); - path[n] = \'0'; + // Soft-fail parallel to the throw above (and to the + // allocation-failure return earlier in this function) + return string_type(); #endif /* STLSOFT_CF_EXCEPTION_SUPPORT */ } } diff --git a/test/unit/unixstl/filesystem/filesystem_traits/entry.cpp b/test/unit/unixstl/filesystem/filesystem_traits/entry.cpp index 03fb50b69..cd184f9e0 100644 --- a/test/unit/unixstl/filesystem/filesystem_traits/entry.cpp +++ b/test/unit/unixstl/filesystem/filesystem_traits/entry.cpp @@ -3,7 +3,7 @@ * * Purpose: Unit-tests for `unixstl::filesystem_traits` resizeable-buffer * `ensure_dir_end` / `remove_dir_end` (C2 empty-`""` behaviour; - * buffer size after remove). + * buffer size after remove; G3 strip-all trailing separators). * * Created: 15th October 2026 * Updated: 16th October 2026 @@ -51,6 +51,7 @@ namespace { static void TEST_ensure_dir_end_APPENDS_separator(); static void TEST_ensure_dir_end_RESIZE_FAILURE_sets_ENOMEM(); static void TEST_remove_dir_end_SHRINKS_buffer(); + static void TEST_remove_dir_end_STRIPS_ALL_trailing_separators(); static void TEST_remove_then_ensure_round_trip(); } // anonymous namespace @@ -72,6 +73,7 @@ int main(int argc, char* argv[]) XTESTS_RUN_CASE(TEST_ensure_dir_end_APPENDS_separator); XTESTS_RUN_CASE(TEST_ensure_dir_end_RESIZE_FAILURE_sets_ENOMEM); XTESTS_RUN_CASE(TEST_remove_dir_end_SHRINKS_buffer); + XTESTS_RUN_CASE(TEST_remove_dir_end_STRIPS_ALL_trailing_separators); XTESTS_RUN_CASE(TEST_remove_then_ensure_round_trip); XTESTS_PRINT_RESULTS(); @@ -253,6 +255,46 @@ static void TEST_remove_dir_end_SHRINKS_buffer() } } +static void TEST_remove_dir_end_STRIPS_ALL_trailing_separators() +{ + { + char dirname[] = "abc///"; + char* r = traits_m_t::remove_dir_end(dirname); + + TEST_MS_EQ("abc", dirname); + TEST_PTR_EQ(dirname + 0, r); + } + +#if __cplusplus >= 201103L + + { + ab_m_t buff = { 'a', 'b', 'c', '/', '/', '/', '\0' }; + size_t const r = traits_m_t::remove_dir_end(buff); + + TEST_MS_EQ("abc", buff.data()); + TEST_INT_EQ(3, r); + TEST_INT_EQ(4, buff.size()); + } +#endif + + { + vec_m_t buff; + buff.push_back('a'); + buff.push_back('b'); + buff.push_back('c'); + buff.push_back('/'); + buff.push_back('/'); + buff.push_back('/'); + buff.push_back('\0'); + + size_t const r = traits_m_t::remove_dir_end(buff); + + TEST_MS_EQ("abc", buff.data()); + TEST_INT_EQ(3, r); + TEST_INT_EQ(4, buff.size()); + } +} + static void TEST_remove_then_ensure_round_trip() { vec_m_t buff; From 4c234bbaefbf515931fceea66d3f75e9e9978fbb Mon Sep 17 00:00:00 2001 From: Matt Wilson Date: Fri, 16 Oct 2026 07:09:57 +1100 Subject: [PATCH 14/23] fix(stlsoft): size full-path scratch to 1+len (G6 OOB) Allocate get_full_path_name_impl's temporary with room for the trailing NUL (1 + len, not 1 + (len - 1)) on unixstl and winstl; copy then terminate so the write is in-bounds (WinSTL quoted paths exercise this branch). --- CHANGES.md | 1 + NEWS.md | 2 +- include/unixstl/filesystem/filesystem_traits.hpp | 6 ++++-- include/winstl/filesystem/filesystem_traits.hpp | 6 ++++-- 4 files changed, 10 insertions(+), 5 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index 465c44109..308985af2 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -14,6 +14,7 @@ * **unixstl::filesystem_traits** — `remove_dir_end` (C-string and `rb`, A+W) now strips **all** trailing path separators, matching WinSTL (was strip-one); * **unixstl** / **winstl** `filesystem_traits` — every `resizeable_buffer_resize` failure on the `rb` / scratch paths above reports last-error (including WinSTL `ensure_dir_end(rb)` and the UnixSTL full-path cwd scratch grow); * **unixstl::readdir_sequence** — non-exception `absolutePath` failure path no longer contains a broken `\'0'` write; soft-fails with an empty string (parallel to the throw when exceptions are enabled); + * **unixstl** / **winstl** `filesystem_traits` — `get_full_path_name_impl` scratch for a non-NUL-terminated counted slice is sized `1 + len` (was `1 + (len - 1)`), so writing the trailing NUL is in-bounds; WinSTL quoted-path handling takes this branch; * docs: * Enriched Doxygen on **stlsoft/util/resizeable_buffer_helpers.hpp** (`resizeable_buffer_resize` parameters, return values, failure policy, caller OOM duty); * **FAQ.md** — Q6 on the Resizeable Buffer concept; diff --git a/NEWS.md b/NEWS.md index 20a64e383..15c850ebc 100644 --- a/NEWS.md +++ b/NEWS.md @@ -3,7 +3,7 @@ | Date | News Item | Details | | ------------------- | ----------------------------------- | ------- | -| 16th October 2026 | Resizeable Buffer concept & traits `rb` hardening | **CONCEPTS.md**; `resizeable_buffer_resize` docs; example **by_concept/resizeable_buffer**; C1–C5 `rb` / `dir_end` fixes; unixstl strip-all `remove_dir_end`; `readdir_sequence` no-exception soft-fail | +| 16th October 2026 | Resizeable Buffer concept & traits `rb` hardening | **CONCEPTS.md**; `resizeable_buffer_resize` docs; example **by_concept/resizeable_buffer**; C1–C5 `rb` / `dir_end` fixes; unixstl strip-all `remove_dir_end`; `readdir_sequence` no-exception soft-fail; full-path OOB size fix | | 12th October 2026 | Release of [STLSoft 1.11.1-rc9](https://github.com/synesissoftware/STLSoft/releases/tag/1.11.1-rc9) | Version change only | | 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** | diff --git a/include/unixstl/filesystem/filesystem_traits.hpp b/include/unixstl/filesystem/filesystem_traits.hpp index 8e82db14b..c7fc3967e 100644 --- a/include/unixstl/filesystem/filesystem_traits.hpp +++ b/include/unixstl/filesystem/filesystem_traits.hpp @@ -2048,7 +2048,8 @@ return 0; if ('\0' != fileName[len]) { - buffer_type_ fileName_(1 + (len - 1)); + // len characters of payload + trailing NUL + buffer_type_ fileName_(1 + len); // May be being compiled absent exception support, so need to check the // file path buffers. (This _could_ be done with a compile-time #ifdef, @@ -2063,9 +2064,10 @@ return 0; } else { + char_copy(&fileName_[0], fileName, len); fileName_[len] = '\0'; - return get_full_path_name_impl2(char_copy(&fileName_[0], fileName, len) + return get_full_path_name_impl2(fileName_.data() , len , buffer , cchBuffer); diff --git a/include/winstl/filesystem/filesystem_traits.hpp b/include/winstl/filesystem/filesystem_traits.hpp index d6e9d849f..c5eb0dc8e 100644 --- a/include/winstl/filesystem/filesystem_traits.hpp +++ b/include/winstl/filesystem/filesystem_traits.hpp @@ -1846,7 +1846,8 @@ struct filesystem_traits if ('\0' != fileName[len]) { - buffer_type_ fileName_(1 + (len - 1)); + // len characters of payload + trailing NUL + buffer_type_ fileName_(1 + len); // May be being compiled absent exception support, so need to check the // file path buffers. (This _could_ be done with a compile-time #ifdef, @@ -1861,10 +1862,11 @@ struct filesystem_traits } else { + STLSOFT_API_EXTERNAL_memfns_memcpy(&fileName_[0], fileName, sizeof(char_type) * len); fileName_[len] = '\0'; return get_full_path_name_impl( - static_cast(STLSOFT_API_EXTERNAL_memfns_memcpy(&fileName_[0], fileName, sizeof(char_type) * len)) + fileName_.data() , len , buffer , cchBuffer From 4ec4d8086c0cca248b9d4c80bbebecb315856f3f Mon Sep 17 00:00:00 2001 From: Matt Wilson Date: Fri, 16 Oct 2026 07:24:51 +1100 Subject: [PATCH 15/23] fix(stlsoft): support defaulted-arg resize in resizeable_buffer_resize (G5) Invoke rb.resize(newSize) with SFINAE detection of one-argument bool/ss_bool_t resize so pre-C++11 vector-style resize(size, value=) works without forming an ambiguous &T::resize; extend the VC6 member-pointer path with a two-argument void overload; add unit stub. --- CHANGES.md | 3 +- CONCEPTS.md | 7 +- NEWS.md | 2 +- .../util/resizeable_buffer_helpers.hpp | 187 ++++++++++++------ .../util/resizeable_buffer_helpers/entry.cpp | 58 +++++- 5 files changed, 191 insertions(+), 66 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index 308985af2..58623c4ac 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -15,6 +15,7 @@ * **unixstl** / **winstl** `filesystem_traits` — every `resizeable_buffer_resize` failure on the `rb` / scratch paths above reports last-error (including WinSTL `ensure_dir_end(rb)` and the UnixSTL full-path cwd scratch grow); * **unixstl::readdir_sequence** — non-exception `absolutePath` failure path no longer contains a broken `\'0'` write; soft-fails with an empty string (parallel to the throw when exceptions are enabled); * **unixstl** / **winstl** `filesystem_traits` — `get_full_path_name_impl` scratch for a non-NUL-terminated counted slice is sized `1 + len` (was `1 + (len - 1)`), so writing the trailing NUL is in-bounds; WinSTL quoted-path handling takes this branch; + * **stlsoft::resizeable_buffer_resize** — invoke `rb.resize(newSize)` directly (with SFINAE detection of one-argument `bool` / `ss_bool_t` `resize`) so pre-C++11-style `resize(size, value = value())` models work; VC6 path adds a two-argument `void` member-pointer overload; * docs: * Enriched Doxygen on **stlsoft/util/resizeable_buffer_helpers.hpp** (`resizeable_buffer_resize` parameters, return values, failure policy, caller OOM duty); * **FAQ.md** — Q6 on the Resizeable Buffer concept; @@ -23,7 +24,7 @@ * Component tests for unixstl `system_traits` home / environment `rb` overloads; * Component tests for unixstl / winstl filesystem path `rb` overloads; * Unit tests for unixstl / winstl `ensure_dir_end` / `remove_dir_end` (including size / round-trip, failing-resize OOM reporting, and unixstl strip-all trailing separators); - * Unit tests for `stlsoft::resizeable_buffer_resize`; + * Unit tests for `stlsoft::resizeable_buffer_resize` (including a stub with defaulted fill-argument `resize`, G5); ## 1.11.1-rc9 - 12th October 2026 diff --git a/CONCEPTS.md b/CONCEPTS.md index 80afffb06..2a598770e 100644 --- a/CONCEPTS.md +++ b/CONCEPTS.md @@ -153,9 +153,10 @@ values, failure policy, and the expectation that callers set `ENOMEM` / `ERROR_OUTOFMEMORY` themselves). `stlsoft::resizeable_buffer_resize(rb, newSize)` invokes `rb.resize(newSize)` -whether that member returns `bool` or `void`, and always returns `bool` -(`true` on success). Prefer it over calling `rb.resize` directly in -generic code. +whether that member returns `bool` or `void`, and whether `resize` is a +one-argument member or a two-argument member with a defaulted fill (as on +pre-C++11 `std::vector`), and always returns `bool` (`true` on success). +Prefer it over calling `rb.resize` directly in generic code. ### Contract for traits overloads that take an `rb` diff --git a/NEWS.md b/NEWS.md index 15c850ebc..eb93ebb3a 100644 --- a/NEWS.md +++ b/NEWS.md @@ -3,7 +3,7 @@ | Date | News Item | Details | | ------------------- | ----------------------------------- | ------- | -| 16th October 2026 | Resizeable Buffer concept & traits `rb` hardening | **CONCEPTS.md**; `resizeable_buffer_resize` docs; example **by_concept/resizeable_buffer**; C1–C5 `rb` / `dir_end` fixes; unixstl strip-all `remove_dir_end`; `readdir_sequence` no-exception soft-fail; full-path OOB size fix | +| 16th October 2026 | Resizeable Buffer concept & traits `rb` hardening | **CONCEPTS.md**; `resizeable_buffer_resize` docs; example **by_concept/resizeable_buffer**; C1–C5 `rb` / `dir_end` fixes; unixstl strip-all `remove_dir_end`; `readdir_sequence` no-exception soft-fail; full-path OOB size fix; `resizeable_buffer_resize` default-arg `resize` (G5) | | 12th October 2026 | Release of [STLSoft 1.11.1-rc9](https://github.com/synesissoftware/STLSoft/releases/tag/1.11.1-rc9) | Version change only | | 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** | diff --git a/include/stlsoft/util/resizeable_buffer_helpers.hpp b/include/stlsoft/util/resizeable_buffer_helpers.hpp index 9a0e0afb4..fa2f51c38 100644 --- a/include/stlsoft/util/resizeable_buffer_helpers.hpp +++ b/include/stlsoft/util/resizeable_buffer_helpers.hpp @@ -57,7 +57,9 @@ * * This header provides \c stlsoft::resizeable_buffer_resize, which adapts * T::resize whether that member returns \c bool or \c void - * so generic code has one failure channel (\c bool). + * (and whether \c resize is a one-argument member or a two-argument member + * with a defaulted fill value, as on pre-C++11 \c std::vector) so generic + * code has one failure channel (\c bool). * * \see CONCEPTS.md — The Resizeable Buffer concept * \see examples/by_concept/resizeable_buffer/main.cpp @@ -69,9 +71,9 @@ #ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION # define STLSOFT_VER_STLSOFT_UTIL_HPP_RESIZEABLE_BUFFER_HELPERS_MAJOR 1 -# define STLSOFT_VER_STLSOFT_UTIL_HPP_RESIZEABLE_BUFFER_HELPERS_MINOR 0 -# define STLSOFT_VER_STLSOFT_UTIL_HPP_RESIZEABLE_BUFFER_HELPERS_REVISION 5 -# define STLSOFT_VER_STLSOFT_UTIL_HPP_RESIZEABLE_BUFFER_HELPERS_EDIT 8 +# define STLSOFT_VER_STLSOFT_UTIL_HPP_RESIZEABLE_BUFFER_HELPERS_MINOR 1 +# define STLSOFT_VER_STLSOFT_UTIL_HPP_RESIZEABLE_BUFFER_HELPERS_REVISION 1 +# define STLSOFT_VER_STLSOFT_UTIL_HPP_RESIZEABLE_BUFFER_HELPERS_EDIT 9 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -86,9 +88,9 @@ # pragma message(__FILE__) #endif /* STLSOFT_TRACE_INCLUDE */ -#ifndef STLSOFT_INCL_STLSOFT_META_HPP_SIZE_OF -# include -#endif /* !STLSOFT_INCL_STLSOFT_META_HPP_SIZE_OF */ +#ifndef STLSOFT_INCL_STLSOFT_META_HPP_YESNO +# include +#endif /* !STLSOFT_INCL_STLSOFT_META_HPP_YESNO */ /* ///////////////////////////////////////////////////////////////////////// @@ -108,11 +110,17 @@ namespace stlsoft #ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION STLSOFT_OPEN_WORKER_NS_(ximpl_stlsoft_util_rb_helpers_) -#if 0 -#elif defined(STLSOFT_COMPILER_IS_MSVC) && \ - _MSC_VER < 1310 +# if 0 +# elif defined(STLSOFT_COMPILER_IS_MSVC) && \ + _MSC_VER < 1310 - /* Have to muck around with state here to get the old girl to work */ + /* Have to muck around with state here to get the old girl to work. + * + * VC6 cannot use the SFINAE / direct-call path below. Keep + * pointer-to-member overload sets, and add a two-argument void + * resize (pre-C++11 vector shape) without adding a two-argument + * bool resize (that would make auto_buffer's &resize ambiguous). + */ template< ss_typename_param_k T_rb @@ -123,6 +131,8 @@ struct rb_helper_traits_vc6 T_rb* prb; public: + typedef ss_typename_type_k T_rb::value_type value_type; + ss_explicit_k rb_helper_traits_vc6( T_rb& rb @@ -133,7 +143,7 @@ struct rb_helper_traits_vc6 bool do_resize( size_t newSize - , bool (T_rb::*pfn)(size_t) + , bool (T_rb::*pfn)(size_t) ) { return (prb->*pfn)(newSize); @@ -142,13 +152,24 @@ struct rb_helper_traits_vc6 bool do_resize( size_t newSize - , void (T_rb::*pfn)(size_t) + , void (T_rb::*pfn)(size_t) ) { (prb->*pfn)(newSize); return true; } + + bool + do_resize( + size_t newSize + , void (T_rb::*pfn)(size_t, value_type) + ) + { + (prb->*pfn)(newSize, value_type()); + + return true; + } }; template< @@ -162,45 +183,86 @@ traits_for( { return rb_helper_traits_vc6(rb); } -#else +# else /* ? compiler */ + + /* Prefer a direct rb.resize(newSize) call so that: + * - one-argument resize(size) works; + * - two-argument resize(size, value = value()) works via the default + * (pre-C++11 vector); + * - C++11 vector's two overloads are not made ambiguous by forming + * &T::resize against competing member-pointer parameter types. + * + * Detect a one-argument bool / ss_bool_t-returning resize via SFINAE on + * the member-pointer type so auto_buffer's failure channel is preserved. + */ template< ss_typename_param_k T_resizeableBuffer -, ss_typename_param_k T_character > -struct rb_helper_traits +struct rb_has_bool_one_arg_resize { - typedef T_character char_type; - typedef T_resizeableBuffer buffer_type; - - typedef bool (buffer_type::*pfn_b)(size_t); - typedef void (buffer_type::*pfn_v)(size_t); - + typedef char yes_type_; + typedef char (&no_type_)[2]; + + template< + ss_typename_param_k U + , ss_bool_t (U::*)(ss_size_t) + > + struct ptm + {}; + + template< + ss_typename_param_k U + > static - bool - do_resize( - buffer_type& buffer - , size_t newSize - , pfn_b pfn - ) - { - return (buffer.*pfn)(newSize); - } - + yes_type_ + test( + ptm* + ); + + template< + ss_typename_param_k U + > static - bool - do_resize( - buffer_type& buffer - , size_t newSize - , pfn_v pfn - ) - { - (buffer.*pfn)(newSize); + no_type_ + test( + ... + ); - return true; - } + enum { value = sizeof(test(0)) == sizeof(yes_type_) }; }; -#endif + +template< + ss_typename_param_k T_resizeableBuffer +> +inline +bool +rb_invoke_resize( + T_resizeableBuffer& rb +, ss_size_t newSize +, yes_type +) +{ + return rb.resize(newSize); +} + +template< + ss_typename_param_k T_resizeableBuffer +> +inline +bool +rb_invoke_resize( + T_resizeableBuffer& rb +, ss_size_t newSize +, no_type +) +{ + rb.resize(newSize); + + return true; +} +# endif /* compiler */ + STLSOFT_CLOSE_WORKER_NS_(ximpl_stlsoft_util_rb_helpers_) #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -218,10 +280,12 @@ STLSOFT_CLOSE_WORKER_NS_(ximpl_stlsoft_util_rb_helpers_) * overload of resize the model provides. * * \tparam T_resizeableBuffer A type that models Resizeable Buffer - * for its value_type. Must declare an unambiguous - * resize(size_type) (or resize(size_t)) - * member returning either \c bool or \c void, and a nested - * value_type. + * for its value_type. Must provide a nested + * value_type and a resize member that can be + * invoked as rb.resize(newSize) — either a one-argument + * resize(size_type) returning \c bool / \c ss_bool_t or + * \c void, or a two-argument resize(size_type, value_type) + * with a defaulted fill (as on pre-C++11 \c std::vector). * * \param rb Reference to the buffer instance to resize * \param newSize The requested number of elements after the call @@ -235,9 +299,9 @@ STLSOFT_CLOSE_WORKER_NS_(ximpl_stlsoft_util_rb_helpers_) * resize (e.g. \c stlsoft::auto_buffer), the member's * return value is propagated. * \retval false The resize failed. Only reachable when - * T_resizeableBuffer::resize returns \c bool and that - * call returned \c false. On failure the buffer is left unchanged - * when the model obeys the strong guarantee (as + * T_resizeableBuffer::resize returns \c bool / \c ss_bool_t + * and that call returned \c false. On failure the buffer is left + * unchanged when the model obeys the strong guarantee (as * \c stlsoft::auto_buffer does). * * \note This function does not set errno / @@ -279,17 +343,19 @@ resizeable_buffer_resize( return traits_for(rb).do_resize(newSize, &T_resizeableBuffer::resize); #else - typedef T_resizeableBuffer buffer_t; - typedef ss_typename_type_k buffer_t::value_type value_t; - STLSOFT_WORKER_NS_USING_(ximpl_stlsoft_util_rb_helpers_, rb_helper_traits); + STLSOFT_WORKER_NS_USING_(ximpl_stlsoft_util_rb_helpers_, rb_has_bool_one_arg_resize); + STLSOFT_WORKER_NS_USING_(ximpl_stlsoft_util_rb_helpers_, rb_invoke_resize); - typedef rb_helper_traits< - buffer_t - , value_t - > traits_t; + typedef value_to_yesno_type< + rb_has_bool_one_arg_resize::value + > yesno_t; - return traits_t::do_resize(rb, newSize, &T_resizeableBuffer::resize); + return rb_invoke_resize( + rb + , newSize + , ss_typename_type_k yesno_t::type() + ); #endif #ifdef STLSOFT_COMPILER_IS_MSVC @@ -301,7 +367,9 @@ resizeable_buffer_resize( #endif /* compiler */ } -/* ////////////////////////////////////////////////////////////////////// */ +/* ///////////////////////////////////////////////////////////////////////// + * namespace + */ #ifndef STLSOFT_NO_NAMESPACE } // namespace stlsoft @@ -319,4 +387,3 @@ resizeable_buffer_resize( #endif /* !STLSOFT_INCL_STLSOFT_UTIL_HPP_RESIZEABLE_BUFFER_HELPERS */ /* ///////////////////////////// end of file //////////////////////////// */ - diff --git a/test/unit/stlsoft/util/resizeable_buffer_helpers/entry.cpp b/test/unit/stlsoft/util/resizeable_buffer_helpers/entry.cpp index 44d62c789..edb063eed 100644 --- a/test/unit/stlsoft/util/resizeable_buffer_helpers/entry.cpp +++ b/test/unit/stlsoft/util/resizeable_buffer_helpers/entry.cpp @@ -4,7 +4,7 @@ * Purpose: Unit-tests for `stlsoft::resizeable_buffer_resize`. * * Created: 15th October 2026 - * Updated: 15th October 2026 + * Updated: 16th October 2026 * * ////////////////////////////////////////////////////////////////////// */ @@ -53,6 +53,8 @@ namespace { static void TEST_WITH_vector_GROW(); static void TEST_WITH_vector_SHRINK(); static void TEST_WITH_vector_TO_ZERO(); + static void TEST_WITH_void_returning_default_arg_stub_GROW(); + static void TEST_WITH_void_returning_default_arg_stub_SHRINK(); static void TEST_WITH_void_returning_stub_SUCCESS(); } // anonymous namespace @@ -78,6 +80,8 @@ int main(int argc, char* argv[]) XTESTS_RUN_CASE(TEST_WITH_vector_GROW); XTESTS_RUN_CASE(TEST_WITH_vector_SHRINK); XTESTS_RUN_CASE(TEST_WITH_vector_TO_ZERO); + XTESTS_RUN_CASE(TEST_WITH_void_returning_default_arg_stub_GROW); + XTESTS_RUN_CASE(TEST_WITH_void_returning_default_arg_stub_SHRINK); XTESTS_RUN_CASE(TEST_WITH_void_returning_stub_SUCCESS); XTESTS_PRINT_RESULTS(); @@ -169,6 +173,41 @@ class void_returning_stub size_type m_size; }; +/** Models pre-C++11 std::vector::resize: a single member + * with a defaulted fill argument, so &T::resize has a + * two-parameter type while rb.resize(n) remains valid. + */ +class void_returning_default_arg_stub +{ +public: // types + typedef char value_type; + typedef size_t size_type; + +public: // construction + void_returning_default_arg_stub() + : m_size(0) + {} + +public: // accessors + size_type size() const + { + return m_size; + } + +public: // operations + void + resize( + size_type newSize + , value_type /* fill */ = value_type() + ) + { + m_size = newSize; + } + +private: // fields + size_type m_size; +}; + static void TEST_WITH_auto_buffer_GROW() { @@ -244,6 +283,23 @@ static void TEST_WITH_void_returning_stub_SUCCESS() TEST_INT_EQ(10, rb.size()); } +static void TEST_WITH_void_returning_default_arg_stub_GROW() +{ + void_returning_default_arg_stub rb; + + TEST_BOOLEAN_TRUE(stlsoft::resizeable_buffer_resize(rb, 32)); + TEST_INT_EQ(32, rb.size()); +} + +static void TEST_WITH_void_returning_default_arg_stub_SHRINK() +{ + void_returning_default_arg_stub rb; + + TEST_BOOLEAN_TRUE(stlsoft::resizeable_buffer_resize(rb, 8)); + TEST_BOOLEAN_TRUE(stlsoft::resizeable_buffer_resize(rb, 3)); + TEST_INT_EQ(3, rb.size()); +} + } // anonymous namespace From 4f7d0d556b338262788df60ef9e1252858a34a2b Mon Sep 17 00:00:00 2001 From: Matt Wilson Date: Sat, 17 Oct 2026 17:19:43 +1100 Subject: [PATCH 16/23] date --- CHANGES.md | 2 +- NEWS.md | 2 +- include/stlsoft/stlsoft.h | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index 282dca153..f8baaf6cf 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -1,7 +1,7 @@ # STLSoft - CHANGES -## 1.11.1-rc9 - 12th October 2026 +## 1.11.1-rc9 - 18th October 2026 * version: * Version change only; diff --git a/NEWS.md b/NEWS.md index 3203c8be3..310f12d5d 100644 --- a/NEWS.md +++ b/NEWS.md @@ -3,7 +3,7 @@ | Date | News Item | Details | | ------------------- | ----------------------------------- | ------- | -| 12th October 2026 | Release of [STLSoft 1.11.1-rc9](https://github.com/synesissoftware/STLSoft/releases/tag/1.11.1-rc9) | Version change only | +| 18th October 2026 | Release of [STLSoft 1.11.1-rc9](https://github.com/synesissoftware/STLSoft/releases/tag/1.11.1-rc9) | Version change only | | 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/include/stlsoft/stlsoft.h b/include/stlsoft/stlsoft.h index ed41592ae..027e0efc9 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/ * From 0d5000ca0bdbcd62da34d80d35e9df9932d614a4 Mon Sep 17 00:00:00 2001 From: synesissoftware Date: Sat, 17 Oct 2026 17:22:16 +1100 Subject: [PATCH 17/23] Documentation, commenting, canonicalisation (#57) * chore(documentation markup): changed Doxygen tag `\remarks` => `\note` * chore(documentation markup): ensuring "NUL character" is the phrasing --- .../acestl/reactor/custom_event_handler.hpp | 10 ++++---- .../atlstl/automation/multiple_dispatch.hpp | 18 ++++++------- .../collections/collection_sequence.hpp | 8 +++--- .../collections/enumeration_policies.hpp | 18 ++++++------- .../collections/enumerator_sequence.hpp | 8 +++--- .../exception/variant_type_exception.hpp | 8 +++--- include/comstl/util/object_functions.h | 10 ++++---- include/comstl/util/variant.hpp | 8 +++--- include/inetstl/util/uds_helpers.h | 6 ++--- .../shims/attribute/get_kernel_handle.hpp | 21 +++------------- .../shims/attribute/get_synch_handle.hpp | 12 ++++----- include/platformstl/filesystem/cwd_stack.hpp | 9 ++++--- include/platformstl/platformstl.h | 8 +++--- include/stlsoft/containers/frequency_map.hpp | 14 +++++------ .../integer_to_base32_string.hpp | 11 ++++---- .../integer_to_base36_string.hpp | 11 ++++---- .../integer_to_decimal_string.hpp | 13 +++++----- .../integer_to_hexadecimal_string.hpp | 13 +++++----- .../integer_to_lc_string.hpp | 10 ++++---- .../integer_to_octal_string.hpp | 13 +++++----- include/stlsoft/conversion/sap_cast.hpp | 8 +++--- .../diagnostics/std_chrono_hrc_stopwatch.hpp | 8 +++--- .../filesystem/io_functions/read_line.hpp | 8 +++--- include/stlsoft/filesystem/path_buffer.hpp | 8 +++--- include/stlsoft/iterator/FILE_iterator.hpp | 10 ++++---- .../stlsoft/iterators/ostream_iterator.hpp | 10 ++++---- .../limits/integral_format_width_limits.hpp | 8 +++--- include/stlsoft/memory/allocator_base.hpp | 18 ++++++------- include/stlsoft/memory/auto_buffer.hpp | 10 ++++---- include/stlsoft/meta/is_class_type.hpp | 24 +++++++++--------- include/stlsoft/obsolete/proxy_iterator.hpp | 8 +++--- .../shims/access/string/std/exception.hpp | 14 +++++------ .../shims/access/string/std/type_info.hpp | 16 ++++++------ .../scoped_handle/scoped_handle_cc.hpp | 10 ++++---- include/stlsoft/string/char_traits.hpp | 6 ++--- include/stlsoft/string/cstring_maker.hpp | 10 ++++---- include/stlsoft/string/shim_string.hpp | 16 ++++++------ include/stlsoft/string/simple_string.hpp | 8 +++--- include/stlsoft/string/static_string.hpp | 6 ++--- include/stlsoft/time/fast_strftime.hpp | 17 +++++++------ include/stlsoft/util/exception_string.hpp | 10 ++++---- .../stlsoft/util/exception_string_creator.hpp | 12 ++++----- include/stlsoft/util/must_init.hpp | 10 ++++---- include/stlsoft/util/printf_traits.hpp | 8 +++--- include/stlsoft/util/true_typedef.hpp | 10 ++++---- include/unixstl/diagnostics/stopwatch.hpp | 10 ++++---- .../unixstl/filesystem/filesystem_traits.hpp | 6 ++--- include/unixstl/filesystem/path.hpp | 10 ++++---- include/winstl/diagnostics/stopwatch.hpp | 18 ++++++------- include/winstl/filesystem/file_functions.hpp | 25 +++++++++---------- .../winstl/filesystem/filesystem_traits.hpp | 10 ++++---- include/winstl/filesystem/path.hpp | 18 ++++++------- .../winstl/filesystem/squeeze_functions.hpp | 8 +++--- include/winstl/registry/functions.hpp | 8 +++--- include/winstl/registry/reg_key.hpp | 8 +++--- include/winstl/registry/reg_value.hpp | 8 +++--- include/winstl/shell/memory/functions.h | 12 ++++----- include/winstl/shims/access/string/time.hpp | 12 ++++----- .../system/system_information_functions.h | 14 +++++------ include/winstl/winstl.h | 10 ++++---- 60 files changed, 330 insertions(+), 349 deletions(-) diff --git a/include/acestl/reactor/custom_event_handler.hpp b/include/acestl/reactor/custom_event_handler.hpp index 1777f645e..5221d7934 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 e9a3229de..836a98694 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 93b6dfebb..973b38fdc 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 b123d09d9..6c1ad92dc 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 fa223b913..956efee02 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/exception/variant_type_exception.hpp b/include/comstl/exception/variant_type_exception.hpp index b306ea411..3d5391b97 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/object_functions.h b/include/comstl/util/object_functions.h index b05e2c49e..91cf0d56f 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 */ @@ -108,7 +108,7 @@ namespace comstl_project * * \pre \c p is a \c nullptr pointer, 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 @@ -306,7 +306,7 @@ namespace comstl * * \pre \c p is a \c nullptr pointer, 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 diff --git a/include/comstl/util/variant.hpp b/include/comstl/util/variant.hpp index 58b576dae..a71facf63 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 diff --git a/include/inetstl/util/uds_helpers.h b/include/inetstl/util/uds_helpers.h index e12a5b1f4..beeacd87e 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 f030aadaf..5a924bb2d 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 174b0822e..1f7bfe1a4 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 bfd4c249c..e51c8fd39 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 d2862a2da..dba480cb6 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: 15th 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 @@ -331,7 +331,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 +353,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 5828d1a27..a5c390dc8 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 93202a46a..89e2ba919 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 71dabd477..5714a856f 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 2b4937527..6a1185451 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 49c5797c4..8e9e3b90c 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 44fa9e035..c4d505479 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 0793fcc88..a9cb1dcd4 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 74e15afad..7e2f9aac7 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 19902a846..07ffd9498 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 2cd9b0bc6..a2f8690a8 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 85eace070..196b45e07 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 */ @@ -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 13b14e12e..3b1ddb3d2 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 508013329..e063b186c 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 3debba085..0d7b1cedc 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 397510faa..81e7001b1 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.hpp b/include/stlsoft/memory/auto_buffer.hpp index b24e3a448..2c878ec6f 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. diff --git a/include/stlsoft/meta/is_class_type.hpp b/include/stlsoft/meta/is_class_type.hpp index ba328a726..8e9b40b74 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 8c2eefed1..45c5b5747 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 3444e51b3..f1e8d740e 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 2d413b539..c50627cbe 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/scoped_handle/scoped_handle_cc.hpp b/include/stlsoft/smartptr/scoped_handle/scoped_handle_cc.hpp index 4a854a558..1998494bd 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/string/char_traits.hpp b/include/stlsoft/string/char_traits.hpp index b7a81bbfe..8c645f0bd 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/cstring_maker.hpp b/include/stlsoft/string/cstring_maker.hpp index 08a2fcb28..37ca28e36 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 6e330cb14..8e5bfeb11 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 @@ -422,7 +422,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 b9c2c1323..2b688549d 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 550ec3762..51e7327f2 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/time/fast_strftime.hpp b/include/stlsoft/time/fast_strftime.hpp index c5b3e9564..2d67e1d19 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 0dbe9d215..c85a7681f 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 b7bc39838..103e220cb 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 38639f387..b2bf656f0 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 a900c81ac..56f1e90d3 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 156ce2aee..6f8ed4077 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 708ca4500..a1c5a1c9b 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 c392cdd08..e38134549 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 @@ -61,7 +61,7 @@ # 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_REVISION 1 -# define UNIXSTL_VER_UNIXSTL_FILESYSTEM_HPP_FILESYSTEM_TRAITS_EDIT 190 +# define UNIXSTL_VER_UNIXSTL_FILESYSTEM_HPP_FILESYSTEM_TRAITS_EDIT 191 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -332,7 +332,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 diff --git a/include/unixstl/filesystem/path.hpp b/include/unixstl/filesystem/path.hpp index b8b2f94fb..c8c8c89d9 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/winstl/diagnostics/stopwatch.hpp b/include/winstl/diagnostics/stopwatch.hpp index 5fa39ee2b..650946435 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 e7463a131..07a14e7b7 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/filesystem_traits.hpp b/include/winstl/filesystem/filesystem_traits.hpp index fe194b8ae..55ad3e409 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 @@ -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; diff --git a/include/winstl/filesystem/path.hpp b/include/winstl/filesystem/path.hpp index 1921d2534..e670876b1 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: 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 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_EDIT 330 #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; diff --git a/include/winstl/filesystem/squeeze_functions.hpp b/include/winstl/filesystem/squeeze_functions.hpp index 8fd99f96d..b21cd15bd 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 16b413b1a..ed41e13b3 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 881fc4426..c26df4fdd 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 c1224822e..790c4debe 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 16c02a2c9..0bf7a59d9 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 10e3c6f80..25334f45a 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/system_information_functions.h b/include/winstl/system/system_information_functions.h index 3b9f19b9a..d8dd75f8a 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,9 +148,9 @@ 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 @@ -258,9 +258,9 @@ 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 diff --git a/include/winstl/winstl.h b/include/winstl/winstl.h index 592659ec3..190b91e42 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: 15th October 2026 * * Home: http://stlsoft.org/ * @@ -51,7 +51,7 @@ # 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_EDIT 246 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ /** \file winstl/winstl.h @@ -631,7 +631,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 +653,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 +841,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 From d35f5fbb0aac67c7d27a40890efb2168b986513d Mon Sep 17 00:00:00 2001 From: synesissoftware Date: Sat, 17 Oct 2026 17:47:40 +1100 Subject: [PATCH 18/23] Preconditions (#56) * docs(STLSoft): normalise expression-form \pre lines Strip outer parentheses, trailing semicolons, and wrappers from expression-form Doxygen \pre comments so each mirrors assert(E); bump Updated, SIS copyright through 2026, and file *_EDIT on the 14 touched headers. * docs(STLSoft): prefer expression-form \pre with nullptr Convert easy prose preconditions to boolean expressions (!empty(), nullptr != p); replace remaining \pre NULL with nullptr; bump Updated, SIS copyright through 2026, and *_EDIT on each touched header. * docs(STLSoft): finish hard \pre cases where expressible Convert non-null COM and shim_string truncate preconditions to expressions; clean remaining null-or-valid COM prose; leave prior-init, unchecked array index, and exception-gated contracts as prose; bump Updated, SIS copyright, and *_EDIT on touched headers. * docs(STLSoft): put zero-length check before null in \pre Reorder optional-buffer preconditions in console_functions.h to 0 == n || nullptr != s; bump Updated, SIS copyright, and *_EDIT. * docs(STLSoft): normalise Doxygen \pre to bare nullptr expressions Standardise \pre comments as bare boolean expressions (no outer parentheses, no trailing punctuation), prefer nullptr over NULL/prose, put zero-length checks before null checks for optional buffers, and convert expressible empty/length contracts to !empty() / n <= size(); bump Updated, SIS copyright through 2026, and *_EDIT on touched headers. --- CHANGES.md | 11 ++++++- Doxyfile | 2 +- INSTALL.md | 18 +++++------ NEWS.md | 2 +- TODO.md | 2 ++ include/comstl/comstl.h | 7 +++-- include/comstl/util/CY_functions.h | 14 ++++----- include/comstl/util/DECIMAL_functions.h | 14 ++++----- include/comstl/util/VARIANT_functions.h | 14 ++++----- include/comstl/util/object_functions.h | 16 +++++----- include/comstl/util/refcount_functions.h | 10 +++---- include/comstl/util/variant.hpp | 4 +-- include/inetstl/inetstl.h | 11 +++---- include/platformstl/platformstl.h | 5 ++-- include/stlsoft/filesystem/path_buffer.hpp | 2 +- include/stlsoft/memory/auto_buffer.h | 8 ++--- include/stlsoft/memory/auto_buffer.hpp | 8 ++--- include/stlsoft/smartptr/ref_ptr.hpp | 18 +++++------ include/stlsoft/stlsoft.h | 6 ++-- include/stlsoft/string/copy_functions.h | 14 ++++----- include/stlsoft/string/shim_string.hpp | 3 +- .../stlsoft/system/environment/functions.h | 10 +++---- .../stlsoft/system/environment/functions.hpp | 6 ++-- .../unixstl/filesystem/filesystem_traits.hpp | 6 ++-- include/unixstl/unixstl.h | 11 +++---- .../winstl/filesystem/filesystem_traits.hpp | 14 ++++----- .../winstl/filesystem/memory_map_functions.h | 8 ++--- include/winstl/system/console_functions.h | 22 +++++++------- .../system/system_information_functions.h | 4 +-- include/winstl/time/conversion_functions.h | 12 ++++---- include/winstl/time/creation_functions.h | 18 +++++------ include/winstl/time/elicitation_functions.h | 30 +++++++++---------- include/winstl/time/localisation_functions.h | 26 ++++++++-------- include/winstl/time/modification_functions.h | 14 ++++----- include/winstl/winstl.h | 9 +++--- test/unit/versions/entry.cpp | 12 ++++---- 36 files changed, 201 insertions(+), 190 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index f8baaf6cf..71c0f7dd8 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -3,8 +3,17 @@ ## 1.11.1-rc9 - 18th October 2026 +* 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: - * Version change only; + * **test.unit.versions** — aligned with **1.11.1-rc9** (**_STLSOFT_VER_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**; + * **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**; + * **comstl** — **1.10.4** (**_COMSTL_VER_1_10_4**), with **STLSoft 1.11.1-rc9**; ## 1.11.1-rc8 - 10th October 2026 diff --git a/Doxyfile b/Doxyfile index 2b908973f..7ba982b98 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 13e5c0ee9..7b04011e3 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 310f12d5d..7bdefd98b 100644 --- a/NEWS.md +++ b/NEWS.md @@ -3,7 +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) | Version change only | +| 18th October 2026 | Release of [STLSoft 1.11.1-rc9](https://github.com/synesissoftware/STLSoft/releases/tag/1.11.1-rc9) | `\pre` normalised to bare exprs with `nullptr`; zero-first optional buffers; companion project 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 fae197b5e..d997851e0 100644 --- a/TODO.md +++ b/TODO.md @@ -43,6 +43,8 @@ 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; ### 1.11.3 diff --git a/include/comstl/comstl.h b/include/comstl/comstl.h index 39af63a02..fd86bbdcd 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/util/CY_functions.h b/include/comstl/util/CY_functions.h index 3f3a1e671..b8dff6232 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 e87802761..982a658c6 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 a0432d2b7..28b146cae 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 91cf0d56f..be3b045f9 100644 --- a/include/comstl/util/object_functions.h +++ b/include/comstl/util/object_functions.h @@ -106,7 +106,7 @@ 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 * * \note If the function success, the caller must release the reference * count associated with the interface pointer in \c *identity. @@ -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,7 +304,7 @@ 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 * * \note If the function success, the caller must release the reference * count associated with the interface pointer in \c *identity. @@ -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 59a6e46d4..42564831a 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 a71facf63..99a4e8a83 100644 --- a/include/comstl/util/variant.hpp +++ b/include/comstl/util/variant.hpp @@ -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 aca3309d2..7aafdef82 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/platformstl/platformstl.h b/include/platformstl/platformstl.h index dba480cb6..f58926eaf 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: 15th October 2026 + * Updated: 17th October 2026 * * Home: http://stlsoft.org/ * @@ -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\ diff --git a/include/stlsoft/filesystem/path_buffer.hpp b/include/stlsoft/filesystem/path_buffer.hpp index 196b45e07..c331b985f 100644 --- a/include/stlsoft/filesystem/path_buffer.hpp +++ b/include/stlsoft/filesystem/path_buffer.hpp @@ -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 diff --git a/include/stlsoft/memory/auto_buffer.h b/include/stlsoft/memory/auto_buffer.h index 201a4cd74..18887f9e6 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 2c878ec6f..92a66dcc9 100644 --- a/include/stlsoft/memory/auto_buffer.hpp +++ b/include/stlsoft/memory/auto_buffer.hpp @@ -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/smartptr/ref_ptr.hpp b/include/stlsoft/smartptr/ref_ptr.hpp index be1817bd5..df0d4194b 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/stlsoft.h b/include/stlsoft/stlsoft.h index 027e0efc9..da78b79ab 100644 --- a/include/stlsoft/stlsoft.h +++ b/include/stlsoft/stlsoft.h @@ -56,7 +56,7 @@ # 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_EDIT 609 #else /* ? STLSOFT_DOCUMENTATION_SKIP_SECTION */ /* # include "./internal/doxygen_defs.h" */ #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -423,13 +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 (12th 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/copy_functions.h b/include/stlsoft/string/copy_functions.h index 313a01050..a05260813 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: 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) 2016-2019, Matthew Wilson and Synesis Software * All rights reserved. * @@ -55,7 +55,7 @@ # 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_EDIT 17 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -109,8 +109,8 @@ 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 @@ -185,8 +185,8 @@ 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 diff --git a/include/stlsoft/string/shim_string.hpp b/include/stlsoft/string/shim_string.hpp index 8e5bfeb11..5b1c0bbd0 100644 --- a/include/stlsoft/string/shim_string.hpp +++ b/include/stlsoft/string/shim_string.hpp @@ -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(); diff --git a/include/stlsoft/system/environment/functions.h b/include/stlsoft/system/environment/functions.h index ce665a09d..d5207bd23 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 541830f44..b46620c46 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/unixstl/filesystem/filesystem_traits.hpp b/include/unixstl/filesystem/filesystem_traits.hpp index e38134549..338ee8255 100644 --- a/include/unixstl/filesystem/filesystem_traits.hpp +++ b/include/unixstl/filesystem/filesystem_traits.hpp @@ -61,7 +61,7 @@ # 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_REVISION 1 -# define UNIXSTL_VER_UNIXSTL_FILESYSTEM_HPP_FILESYSTEM_TRAITS_EDIT 191 +# define UNIXSTL_VER_UNIXSTL_FILESYSTEM_HPP_FILESYSTEM_TRAITS_EDIT 192 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -734,7 +734,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 +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: diff --git a/include/unixstl/unixstl.h b/include/unixstl/unixstl.h index 33335107e..33c03a2eb 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/ * @@ -51,7 +51,7 @@ # 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_EDIT 133 #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/filesystem/filesystem_traits.hpp b/include/winstl/filesystem/filesystem_traits.hpp index 55ad3e409..70c1ec21c 100644 --- a/include/winstl/filesystem/filesystem_traits.hpp +++ b/include/winstl/filesystem/filesystem_traits.hpp @@ -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: @@ -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 1288ca712..5c8b1a47a 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/system/console_functions.h b/include/winstl/system/console_functions.h index 9db95fa81..9f8aa0965 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 d8dd75f8a..4cdb3702c 100644 --- a/include/winstl/system/system_information_functions.h +++ b/include/winstl/system/system_information_functions.h @@ -157,7 +157,7 @@ winstl_C_system_information_functions_MORE_DATA_( * 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 @@ -266,7 +266,7 @@ winstl_C_get_computer_name_w( * 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/time/conversion_functions.h b/include/winstl/time/conversion_functions.h index ae58e7760..208c7a4d8 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 c5e209356..d27ee74da 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 eb75326ea..7dbbdc18b 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 03eb17cc0..d51ad80df 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 315901e15..016a9c7e6 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 190b91e42..71de67265 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: 15th October 2026 + * Updated: 17th October 2026 * * Home: http://stlsoft.org/ * @@ -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 */ diff --git a/test/unit/versions/entry.cpp b/test/unit/versions/entry.cpp index 4f1128d11..4c5c1638c 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 From 1620b64067b3d4c3aadddb1694fa192ff65fd530 Mon Sep 17 00:00:00 2001 From: Matt Wilson Date: Sat, 17 Oct 2026 18:34:34 +1100 Subject: [PATCH 19/23] merge fix: removing vestigial duplicate --- .../CMakeLists.txt | 2 - .../entry.cpp | 259 ------------------ 2 files changed, 261 deletions(-) delete mode 100644 test/component/stlsoft/system/test.component.stlsoft.system.environment_variable_exists/CMakeLists.txt delete mode 100644 test/component/stlsoft/system/test.component.stlsoft.system.environment_variable_exists/entry.cpp 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 9107eda86..000000000 --- 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 7f7bbca0a..000000000 --- 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 //////////////////////////// */ - From f14a68229ef3f7b9c5dd9c184b5754b42e54c0f8 Mon Sep 17 00:00:00 2001 From: Matt Wilson Date: Mon, 19 Oct 2026 14:11:49 +1100 Subject: [PATCH 20/23] feat(winstl): add get_module_directory resizeable-buffer overload (G2) Provide system_traits get_module_directory(hModule, rb) for ANSI and wide, matching the process-path gold probe-then-fill contract; extend unit coverage for auto_buffer/vector and document in CHANGES/NEWS. --- CHANGES.md | 4 +- Doxyfile | 2 +- INSTALL.md | 18 ++-- NEWS.md | 2 +- include/stlsoft/stlsoft.h | 3 +- include/winstl/system/system_traits.hpp | 85 ++++++++++++++++++- test/unit/versions/entry.cpp | 2 +- .../winstl/system/system_traits/entry.cpp | 80 ++++++++++++++++- 8 files changed, 180 insertions(+), 16 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index f75fa854f..c3da149e0 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -1,11 +1,12 @@ # STLSoft - CHANGES -## 1.11.1-rc10 - 16th October 2026 +## 1.11.1-rc10 - 20th October 2026 * additions: * Added **CONCEPTS.md** — documents the **Resizeable Buffer** concept (requirements, models / non-models, probe-then-fill gold contract for traits `rb` overloads); * Added example **examples/by_concept/resizeable_buffer** — probe-then-fill into `auto_buffer` / `vector` via `platformstl` traits `rb` overloads and `resizeable_buffer_resize`; + * **winstl::system_traits** — added `get_module_directory(hModule, rb)` (A+W), gold probe-then-fill companion to the raw overload and to `get_module_filename(rb)`; * fixes: * **unixstl::system_traits** — `get_home_directory(rb)` and `get_environment_variable(rb)` follow the gold pattern (early-out on probe `0`, conditional resize, `ENOMEM` on failure); environment `rb` demand includes the trailing NUL (`cchValue + 1`); * **unixstl** / **winstl** `filesystem_traits` — `get_full_path_name` / `get_short_path_name` / `get_current_directory` `rb` overloads no longer resize-then-`&rb[0]` on an empty buffer when the probe returns `0`; resize failure sets `ENOMEM` / `ERROR_OUTOFMEMORY`; @@ -25,6 +26,7 @@ * Component tests for unixstl / winstl filesystem path `rb` overloads; * Unit tests for unixstl / winstl `ensure_dir_end` / `remove_dir_end` (including size / round-trip, failing-resize OOM reporting, and unixstl strip-all trailing separators); * Unit tests for `stlsoft::resizeable_buffer_resize` (including a stub with defaulted fill-argument `resize`, G5); + * Unit tests for **winstl** `get_module_directory(rb)` (`auto_buffer` / `vector`, invalid handle, grow-from-empty, pre-sized buffer); ## 1.11.1-rc9 - 18th October 2026 diff --git a/Doxyfile b/Doxyfile index 7ba982b98..99277d457 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-rc9 +PROJECT_NUMBER = 1.11.1-rc10 # Overridden at generation time by generate_doxygen.sh (respects # SIS_CMAKE_BUILD_DIR). diff --git a/INSTALL.md b/INSTALL.md index 7b04011e3..24c9e4e0e 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-rc9.zip**](https://github.com/synesissoftware/STLSoft/archive/refs/tags/1.11.1-rc9.zip); +1. Download the latest distribution, e.g. [**STLSoft-1.11.1-rc10.zip**](https://github.com/synesissoftware/STLSoft/archive/refs/tags/1.11.1-rc10.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-rc9.zip +$ unzip STLSoft-1.11.1-rc10.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-rc9`, 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-rc10`, 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-rc9** +**/usr/local/stlsoft/STLSoft-1.11.1-rc10** then you should set the environment variable `STLSOFT` to -**/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`. +**/usr/local/stlsoft/STLSoft-1.11.1-rc10** +in which case the file `stlsoft/stlsoft.h`, for example, will be located in `/usr/local/stlsoft/STLSoft-1.11.1-rc10/include/stlsoft/stlsoft.h`. Conversely, if you're using **Windows** and you install to -**C:\3pty\STLSoft\STLSoft-1.11.1-rc9** +**C:\3pty\STLSoft\STLSoft-1.11.1-rc10** then you should set the environment variable `STLSOFT` to -**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`. +**C:\3pty\STLSoft\STLSoft-1.11.1-rc10** +in which case the file `stlsoft/stlsoft.h`, for example, will be located in `C:\3pty\STLSoft\STLSoft-1.11.1-rc10\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 050ea11e5..74f96de6c 100644 --- a/NEWS.md +++ b/NEWS.md @@ -3,7 +3,7 @@ | Date | News Item | Details | | ------------------- | ----------------------------------- | ------- | -| 20th October 2026 | Release of [STLSoft 1.11.1-rc10](https://github.com/synesissoftware/STLSoft/releases/tag/1.11.1-rc10) | Resizeable Buffer concept & traits `rb` hardening; **CONCEPTS.md**; `resizeable_buffer_resize` docs; example **by_concept/resizeable_buffer**; C1–C5 `rb` / `dir_end` fixes; unixstl strip-all `remove_dir_end`; `readdir_sequence` no-exception soft-fail; full-path OOB size fix; `resizeable_buffer_resize` default-arg `resize` (G5) | +| 20th October 2026 | Release of [STLSoft 1.11.1-rc10](https://github.com/synesissoftware/STLSoft/releases/tag/1.11.1-rc10) | Resizeable Buffer concept & traits `rb` hardening; **CONCEPTS.md**; `get_module_directory(rb)`; `resizeable_buffer_resize` docs; example **by_concept/resizeable_buffer**; C1–C5 `rb` / `dir_end` fixes; unixstl strip-all `remove_dir_end`; `readdir_sequence` no-exception soft-fail; full-path OOB size fix; `resizeable_buffer_resize` default-arg `resize` (G5) | | 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** | diff --git a/include/stlsoft/stlsoft.h b/include/stlsoft/stlsoft.h index 264b5daf8..766798625 100644 --- a/include/stlsoft/stlsoft.h +++ b/include/stlsoft/stlsoft.h @@ -424,12 +424,13 @@ # 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) */ +# define _STLSOFT_VER_1_11_1_RC10 0x010B01CA /*!< Version 1.11.1 rc 10 (20th 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 0xC9 +#define _STLSOFT_VER_ALPHABETA 0xCA #define _STLSOFT_VER \ (0\ diff --git a/include/winstl/system/system_traits.hpp b/include/winstl/system/system_traits.hpp index a2e4ecf22..bd955ceee 100644 --- a/include/winstl/system/system_traits.hpp +++ b/include/winstl/system/system_traits.hpp @@ -5,7 +5,7 @@ * Unicode specialisations thereof. * * Created: 15th November 2002 - * Updated: 15th October 2026 + * Updated: 19th October 2026 * * Thanks: Austin Ziegler for spotting the defective pre-condition * enforcement of expand_environment_strings(). @@ -401,6 +401,21 @@ struct system_traits , size_type cchBuffer ); + /// Gets the full path name of the directory of the given module + /// + /// \param hModule The module handle. If \c nullptr then obtains the + /// directory path of the executing module + /// \param rb Reference to a resizeable buffer + template< + ss_typename_param_k T_resizeableBuffer + > + static + size_type + get_module_directory( + HMODULE hModule + , T_resizeableBuffer& rb + ); + /// Gets the full path name of the system directory /// /// \param buffer Pointer to array of size \c cchBuffer. Must not be @@ -954,6 +969,40 @@ struct system_traits return cch; } + template< + ss_typename_param_k T_resizeableBuffer + > + static + size_type + get_module_directory( + HMODULE hModule + , T_resizeableBuffer& rb + ) + { + size_type const cchRequired = get_module_directory( + hModule + , static_cast(NULL) + , 0 + ); + + 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_module_directory(hModule, &rb[0], rb.size()); + } + static size_type get_system_directory( @@ -1639,6 +1688,40 @@ struct system_traits return cch; } + template< + ss_typename_param_k T_resizeableBuffer + > + static + size_type + get_module_directory( + HMODULE hModule + , T_resizeableBuffer& rb + ) + { + size_type const cchRequired = get_module_directory( + hModule + , static_cast(NULL) + , 0 + ); + + 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_module_directory(hModule, &rb[0], rb.size()); + } + static size_type get_system_directory( diff --git a/test/unit/versions/entry.cpp b/test/unit/versions/entry.cpp index 4c5c1638c..b000a3088 100644 --- a/test/unit/versions/entry.cpp +++ b/test/unit/versions/entry.cpp @@ -133,7 +133,7 @@ namespace { static void TEST__STLSOFT_VER() { - TEST_INT_EQ(_STLSOFT_VER_1_11_1_RC9, _STLSOFT_VER); + TEST_INT_EQ(_STLSOFT_VER_1_11_1_RC10, _STLSOFT_VER); } #ifdef STLSOFT_HAS_ACE diff --git a/test/unit/winstl/system/system_traits/entry.cpp b/test/unit/winstl/system/system_traits/entry.cpp index 75f2a3175..ff524f380 100644 --- a/test/unit/winstl/system/system_traits/entry.cpp +++ b/test/unit/winstl/system/system_traits/entry.cpp @@ -4,7 +4,7 @@ * Purpose: Unit-tests for `winstl::system_traits`. * * Created: 22nd May 2025 - * Updated: 29th September 2026 + * Updated: 19th October 2026 * * ////////////////////////////////////////////////////////////////////// */ @@ -842,6 +842,28 @@ static void TEST_get_module_directory() TEST_CHAR_EQ(L'~', buff[n]); TEST_CHAR_EQ(L'~', buff[STLSOFT_NUM_ELEMENTS(buff) - 1]); } + + // passing resizeable buffer (auto_buffer) + { + ::SetLastError(ERROR_SUCCESS); + + ab_m_t buff(1); + ss_size_t const n = system_traits_m_t::get_module_directory(hmInvalid, buff); + + TEST_INT_EQ(ERROR_MOD_NOT_FOUND, ::GetLastError()); + TEST_INT_EQ(0, n); + } + + // passing resizeable buffer (vector) + { + ::SetLastError(ERROR_SUCCESS); + + vec_w_t buff(0); + ss_size_t const n = system_traits_w_t::get_module_directory(hmInvalid, buff); + + TEST_INT_EQ(ERROR_MOD_NOT_FOUND, ::GetLastError()); + TEST_INT_EQ(0, n); + } } HMODULE hmKernel = ::LoadLibraryA("kernel32"); @@ -872,6 +894,34 @@ static void TEST_get_module_directory() TEST_INT_GE(4, n); TEST_CHAR_EQ(L'\0', buff[0]); } + + // passing resizeable buffer (auto_buffer) — grows then fills + { + ::SetLastError(ERROR_SUCCESS); + + ab_m_t buff(1); + ss_size_t const n = system_traits_m_t::get_module_directory(hmKernel, buff); + + TEST_INT_EQ(ERROR_SUCCESS, ::GetLastError()); + TEST_INT_GE(13, n); + TEST_INT_GT(buff.size(), n); + TEST_CHAR_EQ('\0', buff[n]); + TEST_CHAR_NE('\0', buff[n - 1]); + } + + // passing resizeable buffer (vector) — grows then fills + { + ::SetLastError(ERROR_SUCCESS); + + vec_w_t buff(0); + ss_size_t const n = system_traits_w_t::get_module_directory(hmKernel, buff); + + TEST_INT_EQ(ERROR_SUCCESS, ::GetLastError()); + TEST_INT_GE(13, n); + TEST_INT_GT(buff.size(), n); + TEST_CHAR_EQ(L'\0', buff[n]); + TEST_CHAR_NE(L'\0', buff[n - 1]); + } } // sufficient memory @@ -901,6 +951,34 @@ static void TEST_get_module_directory() TEST_CHAR_EQ(L'\0', buff[n]); TEST_CHAR_NE(L'\0', buff[n - 1]); } + + // passing resizeable buffer (auto_buffer) + { + ::SetLastError(ERROR_SUCCESS); + + ab_w_t buff(1001); + ss_size_t const n = system_traits_w_t::get_module_directory(hmKernel, buff); + + TEST_INT_EQ(ERROR_SUCCESS, ::GetLastError()); + TEST_INT_GE(13, n); + TEST_INT_GT(buff.size(), n); + TEST_CHAR_EQ(L'\0', buff[n]); + TEST_CHAR_NE(L'\0', buff[n - 1]); + } + + // passing resizeable buffer (vector) + { + ::SetLastError(ERROR_SUCCESS); + + vec_m_t buff(1001, '\0'); + ss_size_t const n = system_traits_m_t::get_module_directory(hmKernel, buff); + + TEST_INT_EQ(ERROR_SUCCESS, ::GetLastError()); + TEST_INT_GE(13, n); + TEST_INT_GT(buff.size(), n); + TEST_CHAR_EQ('\0', buff[n]); + TEST_CHAR_NE('\0', buff[n - 1]); + } } } From 74d843f94f0239398f61b5e7684cb0d329cadad1 Mon Sep 17 00:00:00 2001 From: Matt Wilson Date: Mon, 19 Oct 2026 14:16:25 +1100 Subject: [PATCH 21/23] TODO.md --- TODO.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/TODO.md b/TODO.md index 30aac0d7b..a904a7782 100644 --- a/TODO.md +++ b/TODO.md @@ -38,7 +38,7 @@ * [ ] bring in some essential unit-tests from interal repo; * [ ] Bring in the CONCEPTS documentation: * [ ] auto-buffer; - * [ ] resizeable-buffer; + * [x] ~~~resizeable-buffer~~~ - ✅; * [ ] string-access-shims; * [ ] Null Object (variable); * [ ] Externals (esp. not introducing sub-project's headers proper); @@ -48,7 +48,7 @@ ### 1.11.2 -Dedicated increment: **test analysis and coverage only** — no other product changes in this release. +Dedicated increment: **test analysis and coverage** (primary), plus **Resizeable Buffer** follow-ups deferred from the **1.11.1** lock. * [ ] Existing test consistency (deep analysis); * [ ] Complete coverage of currently tested components (improvement / completion); @@ -58,6 +58,14 @@ Dedicated increment: **test analysis and coverage only** — no other product ch * [ ] 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; +* [ ] Resizeable Buffer — follow-ups deferred from the **1.11.1** concept/implementation lock (do **not** reopen C1–C5, D1–D4, G2, G3, G5–G7 without cause; gold contract is **CONCEPTS.md** — *The Resizeable Buffer concept* and *Contract for traits overloads that take an `rb`*; helper **stlsoft/util/resizeable_buffer_helpers.hpp**; exemplar `rb` overloads include `get_current_process_path(rb)` and winstl `get_module_directory(rb)`): + * [ ] **G1** — unixstl `system_traits::expand_environment_strings` is **declare-only** (ANSI + wide; both the C-string `(src, buffer, cch)` and `rb` overloads have no definitions in **include/unixstl/system/system_traits.hpp**); WinSTL already implements both (incl. an `rb` overload); callers such as **include/platformstl/filesystem/cwd_stack.hpp** invoke it and will fail to link on UNIX if used — **either** implement (gold probe-then-fill; env/expansion demand must account for trailing NUL; resize failure → `ENOMEM`; unit/component tests) **or** undeclare/remove the stubs and fix/guard callers; same gap is noted under **1.11.6**; + * [ ] **G4** — settle **caller empty-`rb` policy**: whether traits `rb` overloads require / document that callers always pass an empty buffer (`0 == rb.size()`) versus allowing a pre-sized/`capacity`-bearing `rb` (today gold probes with a null buffer + zero capacity and only resizes when `rb.size() < cchRequired`; some older `rb` overloads still probe via `0 == rb.size() ? NULL : &rb[0]`) — record the decision in **CONCEPTS.md** and align overload docs/impls/tests to it; + * [ ] **C6** — Resizeable Buffer is **structurally typed** only: look-alike types can compile without honouring trailing-NUL / `size()`-includes-NUL invariants; **path_buffer** / **file_path_buffer** remain documented non-models in **CONCEPTS.md** — decide whether to add debug asserts (e.g. trailing NUL when `!empty()`), concept-check helpers, and/or harden docs/tests so misuse is caught; + * [ ] **C7** — gold probe-then-fill has **no retry** if the required size changes between the null probe and the fill (TOCTOU on env/cwd/path); rare in practice — either document as accepted limitation in **CONCEPTS.md** or add a bounded grow-and-retry loop with tests; + * [ ] **P1** — several winstl `system_traits` `rb` overloads (e.g. `get_module_filename`, `get_home_directory`, `expand_environment_strings`) always perform a **second** fill API call even when the first call already succeeded with `rb.size() >= cchRequired`; prefer returning the first-call result when the buffer was already large enough (no behaviour change on the normative path) — measure/guard with existing unit coverage; + * [ ] **P2** — unixstl `filesystem_traits` `rb` path helpers (notably relative `get_full_path_name(rb)`) **query twice** and/or allocate heavy scratch (`path_max()`-sized `auto_buffer`, large stack cwd) — reduce duplicate work (compute once into scratch then copy, or reuse probe data) without changing the public contract; add/extend component tests under **test/component/unixstl/filesystem/filesystem_traits/**; + * [ ] **P3** — `ensure_dir_end(rb)` grows by exactly **+1**, which forces a heap realloc when an `auto_buffer` is already on its internal array boundary; internal callers often avoid the `rb` form for this reason — consider amortized growth or document that pointer/`&sz[0]` forms remain preferred for hot paths; cover with unit tests if behaviour changes; ### 1.11.3 @@ -83,7 +91,7 @@ Dedicated increment: **test analysis and coverage only** — no other product ch ### 1.11.6 * [ ] Flesh out declared-but-undefined `unixstl::system_traits` methods (Linux system calls; emulations/workarounds elsewhere) — see also [**KNOWN_ISSUES.md**](./KNOWN_ISSUES.md): - * [ ] `expand_environment_strings` (ANSI + wide; C-string and `rb` overloads) — implement or undeclare (parked Resizeable Buffer **G1**); + * [ ] `expand_environment_strings` (ANSI + wide; C-string and `rb` overloads) — implement or undeclare; full pickup brief under **1.11.2** Resizeable Buffer **G1**; ### 1.11.7 From 03b7ada3fcb83260414841f8ea867acb965feb69 Mon Sep 17 00:00:00 2001 From: Matt Wilson Date: Mon, 19 Oct 2026 14:32:11 +1100 Subject: [PATCH 22/23] fix(stlsoft): silence ensure_dir_end GCC bounds; fix module-dir GT args Early-return from one-arg ensure_dir_end when the C-string length is zero so GCC -Warray-bounds does not treat the capacity-0 append path as writing past a tiny empty stack buffer under -Werror; apply the same guard in unixstl and winstl (A+W). Correct four TEST_INT_GT argument orders in TEST_get_module_directory to match sibling rb coverage (assert buffer size exceeds returned length). --- .../unixstl/filesystem/filesystem_traits.hpp | 24 ++++++++++++++++--- .../winstl/filesystem/filesystem_traits.hpp | 24 ++++++++++++++++--- .../winstl/system/system_traits/entry.cpp | 8 +++---- 3 files changed, 46 insertions(+), 10 deletions(-) diff --git a/include/unixstl/filesystem/filesystem_traits.hpp b/include/unixstl/filesystem/filesystem_traits.hpp index 755827b06..1d643c05d 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: 16th October 2026 + * Updated: 19th October 2026 * * Thanks: To Sergey Nikulov, for spotting a preprocessor typo that broke * GCC -pedantic; to Michal Makowski and Zar Eindl for reporting @@ -60,8 +60,8 @@ #ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION # 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 193 +# define UNIXSTL_VER_UNIXSTL_FILESYSTEM_HPP_FILESYSTEM_TRAITS_REVISION 2 +# define UNIXSTL_VER_UNIXSTL_FILESYSTEM_HPP_FILESYSTEM_TRAITS_EDIT 194 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -1003,6 +1003,15 @@ struct filesystem_traits size_type const len = str_len(dir); + /* Empty string: leave unchanged (and avoid the capacity-0 append + * path, which GCC -Warray-bounds may flag when inlined into a + * tiny stack buffer). + */ + if (0 == len) + { + return dir; + } + return ensure_dir_end(dir, len, 0, NULL); } @@ -2836,6 +2845,15 @@ struct filesystem_traits size_type const len = str_len(dir); + /* Empty string: leave unchanged (and avoid the capacity-0 append + * path, which GCC -Warray-bounds may flag when inlined into a + * tiny stack buffer). + */ + if (0 == len) + { + return dir; + } + return ensure_dir_end(dir, len, 0, NULL); } diff --git a/include/winstl/filesystem/filesystem_traits.hpp b/include/winstl/filesystem/filesystem_traits.hpp index 683269add..7b81a5595 100644 --- a/include/winstl/filesystem/filesystem_traits.hpp +++ b/include/winstl/filesystem/filesystem_traits.hpp @@ -5,7 +5,7 @@ * Unicode specialisations thereof. * * Created: 15th November 2002 - * Updated: 16th October 2026 + * Updated: 19th October 2026 * * Home: http://stlsoft.org/ * @@ -55,8 +55,8 @@ #ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION # 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 195 +# define WINSTL_VER_WINSTL_FILESYSTEM_HPP_FILESYSTEM_TRAITS_REVISION 12 +# define WINSTL_VER_WINSTL_FILESYSTEM_HPP_FILESYSTEM_TRAITS_EDIT 196 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */ @@ -1011,6 +1011,15 @@ struct filesystem_traits size_type const len = str_len(dir); + /* Empty string: leave unchanged (and avoid the capacity-0 append + * path, which GCC -Warray-bounds may flag when inlined into a + * tiny stack buffer). + */ + if (0 == len) + { + return dir; + } + return ensure_dir_end(dir, len, 0, NULL); } @@ -2683,6 +2692,15 @@ struct filesystem_traits size_type const len = str_len(dir); + /* Empty string: leave unchanged (and avoid the capacity-0 append + * path, which GCC -Warray-bounds may flag when inlined into a + * tiny stack buffer). + */ + if (0 == len) + { + return dir; + } + return ensure_dir_end(dir, len, 0, NULL); } diff --git a/test/unit/winstl/system/system_traits/entry.cpp b/test/unit/winstl/system/system_traits/entry.cpp index ff524f380..5170723cb 100644 --- a/test/unit/winstl/system/system_traits/entry.cpp +++ b/test/unit/winstl/system/system_traits/entry.cpp @@ -904,7 +904,7 @@ static void TEST_get_module_directory() TEST_INT_EQ(ERROR_SUCCESS, ::GetLastError()); TEST_INT_GE(13, n); - TEST_INT_GT(buff.size(), n); + TEST_INT_GT(n, buff.size()); TEST_CHAR_EQ('\0', buff[n]); TEST_CHAR_NE('\0', buff[n - 1]); } @@ -918,7 +918,7 @@ static void TEST_get_module_directory() TEST_INT_EQ(ERROR_SUCCESS, ::GetLastError()); TEST_INT_GE(13, n); - TEST_INT_GT(buff.size(), n); + TEST_INT_GT(n, buff.size()); TEST_CHAR_EQ(L'\0', buff[n]); TEST_CHAR_NE(L'\0', buff[n - 1]); } @@ -961,7 +961,7 @@ static void TEST_get_module_directory() TEST_INT_EQ(ERROR_SUCCESS, ::GetLastError()); TEST_INT_GE(13, n); - TEST_INT_GT(buff.size(), n); + TEST_INT_GT(n, buff.size()); TEST_CHAR_EQ(L'\0', buff[n]); TEST_CHAR_NE(L'\0', buff[n - 1]); } @@ -975,7 +975,7 @@ static void TEST_get_module_directory() TEST_INT_EQ(ERROR_SUCCESS, ::GetLastError()); TEST_INT_GE(13, n); - TEST_INT_GT(buff.size(), n); + TEST_INT_GT(n, buff.size()); TEST_CHAR_EQ('\0', buff[n]); TEST_CHAR_NE('\0', buff[n - 1]); } From 41c552b24a24ae879ece3c575347282632bc628a Mon Sep 17 00:00:00 2001 From: Matt Wilson Date: Mon, 19 Oct 2026 14:58:47 +1100 Subject: [PATCH 23/23] test(stlsoft): avoid tiny-stack empty ensure_dir_end under GCC -Werror Drive empty C-string ensure_dir_end coverage through the sized overload with an explicit capacity instead of one-arg on `char dirname[] = "\0"`, which GCC -Warray-bounds / -Wstringop-overflow still treats as an out-of-bounds capacity-0 append under -Werror even with an empty early-out; apply the same pattern in unixstl and winstl unit tests. --- .../filesystem/filesystem_traits/entry.cpp | 17 ++++++++-- .../filesystem/filesystem_traits/entry.cpp | 31 ++++++++++++++++--- 2 files changed, 41 insertions(+), 7 deletions(-) diff --git a/test/unit/unixstl/filesystem/filesystem_traits/entry.cpp b/test/unit/unixstl/filesystem/filesystem_traits/entry.cpp index 29a6d85f2..9d1eca885 100644 --- a/test/unit/unixstl/filesystem/filesystem_traits/entry.cpp +++ b/test/unit/unixstl/filesystem/filesystem_traits/entry.cpp @@ -151,11 +151,24 @@ namespace { static void TEST_ensure_dir_end_EMPTY_stays_empty() { + /* C-string empty: exercise the sized overload with an explicit + * capacity. Calling the one-arg form on a tiny stack array such as + * `char dirname[] = "\0"` makes GCC -Warray-bounds / -Wstringop- + * overflow treat the capacity-0 append path as writing past the + * object under -Werror, even when an empty early-out is present. + */ { - char dirname[] = "\0"; - char* r = traits_m_t::ensure_dir_end(dirname); + char dirname[8] = { 0 }; + size_t n = 0; + char* r = traits_m_t::ensure_dir_end( + dirname + , 0 + , STLSOFT_NUM_ELEMENTS(dirname) + , &n + ); TEST_MS_EQ("", dirname); + TEST_INT_EQ(0, n); TEST_PTR_EQ(dirname + 0, r); } diff --git a/test/unit/winstl/filesystem/filesystem_traits/entry.cpp b/test/unit/winstl/filesystem/filesystem_traits/entry.cpp index f40914502..7441049ee 100644 --- a/test/unit/winstl/filesystem/filesystem_traits/entry.cpp +++ b/test/unit/winstl/filesystem/filesystem_traits/entry.cpp @@ -4,7 +4,7 @@ * Purpose: Unit-tests for `winstl::filesystem_traits`. * * Created: 31st December 2008 - * Updated: 16th October 2026 + * Updated: 19th October 2026 * * ////////////////////////////////////////////////////////////////////// */ @@ -270,21 +270,42 @@ static void TEST_ensure_dir_end_1() { // empty string { + /* C-string empty: exercise the sized overload with an explicit + * capacity. Calling the one-arg form on a tiny stack array such as + * `char dirname[] = "\0"` makes GCC -Warray-bounds / -Wstringop- + * overflow treat the capacity-0 append path as writing past the + * object under -Werror, even when an empty early-out is present. + */ + // passing character array (char) { - char dirname[] = "\0"; - char* r = filesystem_traits_m_t::ensure_dir_end(dirname); + char dirname[8] = { 0 }; + ss_size_t n = 0; + char* r = filesystem_traits_m_t::ensure_dir_end( + dirname + , 0 + , STLSOFT_NUM_ELEMENTS(dirname) + , &n + ); TEST_MS_EQ("", dirname); + TEST_INT_EQ(0, n); TEST_PTR_EQ(dirname + 0, r); } // passing character array (wchar_t) { - wchar_t dirname[] = L"\0"; - wchar_t* r = filesystem_traits_w_t::ensure_dir_end(dirname); + wchar_t dirname[8] = { 0 }; + ss_size_t n = 0; + wchar_t* r = filesystem_traits_w_t::ensure_dir_end( + dirname + , 0 + , STLSOFT_NUM_ELEMENTS(dirname) + , &n + ); TEST_WS_EQ(L"", dirname); + TEST_INT_EQ(0, n); TEST_PTR_EQ(dirname + 0, r); }