feat(collections): add immutable list copy operations

Author: robertvokac

CLAUDE.md

@@ -9,7 +9,7 @@
 ## Non-negotiable rules
 
 1. **Zero errors, zero warnings** before any commit. `cmake --build build --parallel 4` must be clean.
-2. **No test-count regression.** `scripts/run_component_tests.sh build` must show no failures. The verified baseline is 12,625 tests across 36 component executables and one integration executable; this floor should be raised as new tests are added and lowered only with an explicit, documented reason.
+2. **No test-count regression.** `scripts/run_component_tests.sh build` must show no failures. The verified baseline is 12,630 tests across 36 component executables and one integration executable; this floor should be raised as new tests are added and lowered only with an explicit, documented reason.
 3. **Push only to `feature/work`.** Never push to `develop` or `master`, and never create tags, without explicit per-action user approval.
 4. **SPDX header on every project source/header** — `// SPDX-License-Identifier: MIT` + copyright + .NET attribution. Vendored sources retain their upstream headers; Markdown uses an HTML SPDX comment where one is present.
 5. **Property naming:** always `getXxxProperty()` / `setXxxProperty()`. Exception: indexers

NEXT.md

@@ -4,9 +4,9 @@
 # NEXT.md
 
 *Last verified: 2026-07-25. Branch: `feature/work`. The P0 component-boundary
-repair, three P1 parity repairs, P1 portability revalidation, and six bounded
+repair, three P1 parity repairs, P1 portability revalidation, and seven bounded
 P2 API slices are complete: 41 physical modules, 90 production dependency
-edges, and 12,625 tests across 37 executables.*
+edges, and 12,630 tests across 37 executables.*
 
 This is the cold-start handoff for the next working session. Keep it focused
 on verified facts, remaining bounded work, and commands needed to resume.
@@ -28,7 +28,7 @@ Historical session detail belongs in git history and `plan.sqlite3`.
 - The ten-job selective consumer matrix, including a direct
   `Collections.Blocking` consumer, is green. Text.Json retains its target
   absence and negative include-leakage assertions.
-- The full native baseline is a warning-free build with 12,625 passing tests
+- The full native baseline is a warning-free build with 12,630 passing tests
   across 36 component executables and one integration executable.
 - `TaskT<TResult>::ContinueWith` now supports both action and result-producing
   callbacks. It runs inline on completion; `NotOn*` and `OnlyOn*` filter the
@@ -40,6 +40,9 @@ Historical session detail belongs in git history and `plan.sqlite3`.
   work on non-seekable streams, return partial data at clean EOF, and reject
   truncated or malformed UTF-8. Seekable `PeekChar` restores both stream and
   decoder state; it deliberately throws on non-seekable streams.
+- `ImmutableList<T>` supports all three `CopyTo` overloads using a fixed-size
+  `std::vector` destination. Its bounds checks distinguish invalid source
+  ranges from an undersized destination and avoid signed-overflow-prone sums.
 - MinGW-w64 GCC 14-win32/CMake 3.31.6 and Emscripten 5.0.7/CMake 3.31.6 both
   compile the post-modular `All` graph and selective `Text.Json` libraries.
   This is compile-only evidence: cross tests were deliberately disabled.
@@ -48,15 +51,15 @@ Historical session detail belongs in git history and `plan.sqlite3`.
   ASan/LSan ownership scenarios, including 100 continuation teardowns, pass.
 
 The local `plan.sqlite3` snapshot contains 16,201 classified `task` rows and
-1,748 completed tickets. Ticket #1737 records the completed P0 split, tickets
+1,749 completed tickets. Ticket #1737 records the completed P0 split, tickets
 #1738/#1739 the MemoryStream and generic-continuation repairs, ticket #1740 the
 XML whitespace repair, #1741 the completed cross-build revalidation and
 `WebProxy` portability fix, #1742 focused sanitizer evidence, and #1743 the
 `ImmutableList<T>` predicate-query slice. Ticket #1744 records seekable
 `BinaryReader::PeekChar`, #1745 `ImmutableList<T>::Sort`/`Reverse`, and #1746
-`ImmutableList<T>::GetRange`, #1747 `ImmutableList<T>::ConvertAll`, and #1748
-the UTF-8 `BinaryReader` batch-character APIs. The database is git-ignored and
-is not part of a fresh clone.
+`ImmutableList<T>::GetRange`, #1747 `ImmutableList<T>::ConvertAll`, #1748 the
+UTF-8 `BinaryReader` batch-character APIs, and #1749 `ImmutableList<T>`
+copying. The database is git-ignored and is not part of a fresh clone.
 
 ## P0 completion: restore Collections isolation
 
@@ -165,13 +168,21 @@ cover slice content, source immutability, boundary empties, and invalid ranges.
 backed immutable list. It preserves an empty source and rejects an empty
 converter with `ArgumentNullException`; three regressions cover those cases.
 
+## P2 completion: `ImmutableList<T>::CopyTo`
+
+All three `CopyTo` overloads now copy to a fixed-size `std::vector<T>`
+destination: full list, destination offset, and source/destination range.
+They preserve order and source immutability, allow valid empty end ranges,
+and distinguish invalid indices/ranges from an undersized destination. Five
+regressions cover each overload, boundary behavior, and validation.
+
 ## Recommended next bounded tasks
 
 All currently planned P1 work is complete. Choose one consumer-driven P2
 slice, create a ticket, and keep the changes isolated:
 
 1. **`ImmutableList<T>` breadth.** Select one real consumer-needed group from
-   copying, builder support, or comparer overloads.
+   builder support or comparer overloads.
 2. **Other documented partial surfaces.** Examples include `BigInteger`
    bitwise operations, fuller UTF-7 behavior, and wider debugger/process/XML
    surfaces.

README.md

@@ -7,7 +7,7 @@ collector, or the complete .NET platform.
 
 The repository currently builds as 41 independently selectable CMake
 components. The verified Linux baseline on 2026-07-25 is a warning-free build
-with **12,625 passing tests across 37 test executables**.
+with **12,630 passing tests across 37 test executables**.
 
 ## What is included
 
@@ -181,7 +181,7 @@ Other platform evidence is narrower:
 
 | Platform/toolchain | Verified scope |
 |---|---|
-| Linux/GCC | Current full component build and all 12,625 tests. |
+| Linux/GCC | Current full component build and all 12,630 tests. |
 | Windows/MinGW | MinGW-w64 GCC 14-win32/CMake 3.31.6 compiled the post-component `All` and selective `Text.Json` library graphs under ticket #1741. GoogleTest was not cross-built and repository CI remains Ubuntu-only. |
 | Emscripten | Emscripten 5.0.7/CMake 3.31.6 compiled the post-component `All` and selective `Text.Json` library graphs under ticket #1741. Tests were not cross-built or run, and some runtime APIs deliberately throw `PlatformNotSupportedException`. |
 | macOS/Apple Clang | Real downstream Xcode 15.4 builds drove portability fixes on 2026-07-20; this repository has no macOS job or recorded full standalone test baseline. |

docs/CMakeComponents.md

@@ -131,7 +131,7 @@ are named `SharpRuntimeTests_<Component>`; genuinely cross-module scenarios
 are in `SharpRuntimeIntegrationTests`. CTest also discovers every individual
 GoogleTest case.
 
-The verified 2026-07-25 `All` baseline contains 12,625 tests across 36
+The verified 2026-07-25 `All` baseline contains 12,630 tests across 36
 component executables and one integration executable.
 
 ## Boundary validation and CI

modules/collections/include/System/Collections/Immutable/ImmutableList.hpp

@@ -26,8 +26,8 @@ using SharpRuntime::intcs;
  * Remove/RemoveAll/RemoveAt/RemoveRange(int,int)/Sort/Reverse/Contains/IndexOf/LastIndexOf/
  * BinarySearch).
  * Deliberately deferred relative to real .NET's ImmutableList<T> (a much larger surface backed
- * by an AVL tree, not a flat vector): range and custom-comparer Sort/Reverse overloads, the 3
- * CopyTo overloads, ToBuilder/Builder,
+ * by an AVL tree, not a flat vector): range and custom-comparer Sort/Reverse overloads,
+ * ToBuilder/Builder,
  * RemoveRange(IEnumerable<T>), and every
  * IEqualityComparer<T>/IComparer<T>-taking overload of Remove/RemoveRange/Replace/IndexOf/
  * LastIndexOf/BinarySearch (this port always uses T::operator== / operator< instead). These are
@@ -314,6 +314,62 @@ class ImmutableList {
         return ImmutableList<TOutput>::Create(values);
     }
 
+    /**
+     * @brief Copies every element to a compatible destination vector.
+     *
+     * C++ counterpart of .NET ImmutableList<T>.CopyTo(T[]). The vector is not
+     * resized: callers retain the same fixed-destination-array contract as .NET.
+     * @throws System::ArgumentException if @p destination is too small.
+     */
+    void CopyTo(std::vector<T>& destination) const {
+        CopyTo(0, destination, 0, getCountProperty());
+    }
+
+    /**
+     * @brief Copies every element to @p destination starting at @p arrayIndex.
+     *
+     * C++ counterpart of .NET ImmutableList<T>.CopyTo(T[], int).
+     * @throws System::ArgumentOutOfRangeException if @p arrayIndex is negative.
+     * @throws System::ArgumentException if @p destination cannot hold all elements.
+     */
+    void CopyTo(std::vector<T>& destination, intcs arrayIndex) const {
+        CopyTo(0, destination, arrayIndex, getCountProperty());
+    }
+
+    /**
+     * @brief Copies a source range to a compatible destination vector.
+     *
+     * C++ counterpart of .NET ImmutableList<T>.CopyTo(int, T[], int, int).
+     * @param index The zero-based source index.
+     * @param destination The fixed-size destination vector.
+     * @param arrayIndex The zero-based destination index.
+     * @param count The number of elements to copy.
+     * @throws System::ArgumentOutOfRangeException if a source index, destination index, or
+     *         count is negative, or the source range is invalid.
+     * @throws System::ArgumentException if @p destination is too small.
+     */
+    void CopyTo(intcs index, std::vector<T>& destination, intcs arrayIndex, intcs count) const {
+        const intcs sourceCount = getCountProperty();
+        if (index < 0 || index > sourceCount) {
+            throw System::ArgumentOutOfRangeException("index", "Index was out of range. Must be non-negative and within the collection.");
+        }
+        if (count < 0 || count > sourceCount - index) {
+            throw System::ArgumentOutOfRangeException("count", "Count must refer to a location within the collection.");
+        }
+        if (arrayIndex < 0) {
+            throw System::ArgumentOutOfRangeException("arrayIndex", "Non-negative number required.");
+        }
+        // Use subtraction after validating the non-negative destination index. This avoids the
+        // signed-overflow hazard in an `arrayIndex + count > destination.size()` check.
+        if (static_cast<intcs>(destination.size()) - arrayIndex < count) {
+            throw System::ArgumentException(
+                "Destination array was not long enough. Check the destination index, length, and the array's lower bounds.");
+        }
+
+        std::copy(data_->begin() + index, data_->begin() + index + count,
+                  destination.begin() + arrayIndex);
+    }
+
     /**
      * @brief Returns a new list with all elements sorted using T::operator<.
      *

modules/collections/tests/System/Collections/ImmutableListCopyTests.cpp

@@ -0,0 +1,64 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) Robert Vokac and contributors
+// Portions based on .NET runtime API (MIT License, Copyright .NET Foundation and Contributors)
+#include <gtest/gtest.h>
+
+#include <vector>
+
+#include "System/ArgumentException.hpp"
+#include "System/ArgumentOutOfRangeException.hpp"
+#include "System/Collections/Immutable/ImmutableList.hpp"
+
+using System::Collections::Immutable::ImmutableList;
+
+TEST(ImmutableListCopyTests, CopyToCopiesEntireListWithoutResizingDestination) {
+    const auto source = ImmutableList<int>::Create({10, 20, 30});
+    std::vector<int> destination{0, 0, 0};
+
+    source.CopyTo(destination);
+
+    EXPECT_EQ(destination, (std::vector<int>{10, 20, 30}));
+    EXPECT_EQ(source.getCountProperty(), 3);
+    EXPECT_EQ(source[0], 10);
+}
+
+TEST(ImmutableListCopyTests, CopyToWithDestinationOffsetPreservesSurroundingElements) {
+    const auto source = ImmutableList<int>::Create({10, 20, 30});
+    std::vector<int> destination{-1, -1, -1, -1, -1};
+
+    source.CopyTo(destination, 1);
+
+    EXPECT_EQ(destination, (std::vector<int>{-1, 10, 20, 30, -1}));
+}
+
+TEST(ImmutableListCopyTests, CopyToRangeCopiesOnlyRequestedSourceRange) {
+    const auto source = ImmutableList<int>::Create({10, 20, 30, 40, 50});
+    std::vector<int> destination{-1, -1, -1, -1, -1, -1};
+
+    source.CopyTo(1, destination, 2, 3);
+
+    EXPECT_EQ(destination, (std::vector<int>{-1, -1, 20, 30, 40, -1}));
+}
+
+TEST(ImmutableListCopyTests, CopyToRangeAllowsEmptyRangeAtEndOfSourceAndDestination) {
+    const auto source = ImmutableList<int>::Create({10, 20});
+    std::vector<int> destination{7, 8};
+
+    source.CopyTo(2, destination, 2, 0);
+
+    EXPECT_EQ(destination, (std::vector<int>{7, 8}));
+}
+
+TEST(ImmutableListCopyTests, CopyToValidatesSourceRangeAndDestinationCapacity) {
+    const auto source = ImmutableList<int>::Create({10, 20, 30});
+    std::vector<int> destination(3);
+    std::vector<int> tooSmall(2);
+
+    EXPECT_THROW(source.CopyTo(destination, -1), System::ArgumentOutOfRangeException);
+    EXPECT_THROW(source.CopyTo(-1, destination, 0, 1), System::ArgumentOutOfRangeException);
+    EXPECT_THROW(source.CopyTo(1, destination, 0, -1), System::ArgumentOutOfRangeException);
+    EXPECT_THROW(source.CopyTo(2, destination, 0, 2), System::ArgumentOutOfRangeException);
+    EXPECT_THROW(source.CopyTo(0, destination, -1, 1), System::ArgumentOutOfRangeException);
+    EXPECT_THROW(source.CopyTo(0, tooSmall, 0, 3), System::ArgumentException);
+    EXPECT_THROW(source.CopyTo(destination, 1), System::ArgumentException);
+}

plan.md

@@ -1,7 +1,7 @@
 # Sharp Runtime plan
 
 *Last verified: 2026-07-25 — 41 physical components, 90 direct production
-dependency edges, a clean native build, 12,625 passing tests across 37
+dependency edges, a clean native build, 12,630 passing tests across 37
 executables, and a green ten-job selective matrix.*
 
 Sharp Runtime is in a consumer-driven expansion phase. The original type
@@ -32,7 +32,7 @@ was never created. Neither file should be linked as current documentation.
 ### Code and validation
 
 - Native Linux/GCC build: zero errors and zero warnings.
-- Tests: 12,625 passing across 36 component binaries plus one integration
+- Tests: 12,630 passing across 36 component binaries plus one integration
   binary.
 - Component graph: 41 physical modules and 90 direct production edges.
 - Boundary validator: no cycles, duplicate public include paths, orphan
@@ -52,7 +52,7 @@ The 2026-07-25 local snapshot contains:
 | Table | State |
 |---|---|
 | `task` | 16,201 rows: 1,082 `ported`, 140 `ignore`, 14,979 legacy `ignored`; no unclassified or `tobedecided` rows |
-| `ticket` | 1,748 rows, all `done`; no `todo`, `doing`, `blocked`, or `needs_user` rows |
+| `ticket` | 1,749 rows, all `done`; no `todo`, `doing`, `blocked`, or `needs_user` rows |
 
 Because `plan.sqlite3` is git-ignored, these counts describe the maintainer
 snapshot, not data shipped in a fresh clone.
@@ -104,6 +104,9 @@ assertion without an explicit architecture decision.
   preserve UTF-8 decoder output across calls, return a partial result at clean
   EOF, propagate truncated input, and expose supplementary scalars as UTF-16
   surrogate pairs.
+- Added all three `ImmutableList<T>::CopyTo` overloads under ticket #1749,
+  using checked fixed-size `std::vector` destinations, including source range
+  and destination offset handling without signed-overflow-prone bounds checks.
 - Added consumer-driven coverage across core, collections, IO, networking,
   threading/tasks, text/JSON, XML, numerics, globalization, and cryptographic
   hashing/random APIs.
@@ -164,7 +167,7 @@ The first consumer-driven ports after modularization added:
 - XML schema exception types.
 
 The verified test baseline grew from 12,494 at the modularization checkpoint
-to 12,625.
+to 12,630.
 
 ## Candidate roadmap
 
@@ -174,9 +177,9 @@ acceptance criteria and a validation command before changing code.
 ### P2 — Consumer-driven API breadth
 
 1. **Continue a bounded `ImmutableList<T>` slice.**
-   Its documented omissions include copying, builder support, and comparer
-   overloads. Do not attempt the entire surface in one change; select methods
-   required by a real consumer and port them against the .NET reference.
+   Its documented omissions include builder support and comparer overloads.
+   Do not attempt the entire surface in one change; select methods required by
+   a real consumer and port them against the .NET reference.
 
 2. **Extend `BinaryReader` only from a concrete consumer need.**
    `ReadChar`, `ReadChars`, `Read(char[])`, `ReadDecimal`, and seekable