feat(collections): add immutable list ranges

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,613 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,616 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 three bounded
+repair, three P1 parity repairs, P1 portability revalidation, and four bounded
 P2 API slices are complete: 41 physical modules, 90 production dependency
-edges, and 12,613 tests across 37 executables.*
+edges, and 12,616 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,613 passing tests
+- The full native baseline is a warning-free build with 12,616 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
@@ -46,13 +46,14 @@ 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,745 completed tickets. Ticket #1737 records the completed P0 split, tickets
+1,746 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`, and #1745 `ImmutableList<T>::Sort`/`Reverse`. The
-database is git-ignored and is not part of a fresh clone.
+`BinaryReader::PeekChar`, #1745 `ImmutableList<T>::Sort`/`Reverse`, and #1746
+`ImmutableList<T>::GetRange`. The database is git-ignored and is not part of a
+fresh clone.
 
 ## P0 completion: restore Collections isolation
 
@@ -139,6 +140,13 @@ leave the source unchanged; range and custom-comparer overloads remain
 deferred. Three regressions cover ordering, immutability, and empty/singleton
 lists.
 
+## P2 completion: `ImmutableList<T>::GetRange`
+
+`GetRange(index, count)` returns an independently backed, ordered immutable
+slice. It accepts zero-length ranges at either valid boundary and reuses the
+same `ArgumentOutOfRangeException` checks as `RemoveRange`. Three regressions
+cover slice content, source immutability, boundary empties, and invalid ranges.
+
 ## Recommended next bounded tasks
 
 All currently planned P1 work is complete. Choose one consumer-driven P2
@@ -148,7 +156,7 @@ slice, create a ticket, and keep the changes isolated:
    `Read(char[])` behavior while preserving decoder state and truncated-input
    semantics, including supplementary UTF-8 characters.
 2. **`ImmutableList<T>` breadth.** Select one real consumer-needed group from
-   copy/range/conversion, builder support, or comparer overloads.
+   copying/conversion, builder support, or comparer overloads.
 3. **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,613 passing tests across 37 test executables**.
+with **12,616 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,613 tests. |
+| Linux/GCC | Current full component build and all 12,616 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,613 tests across 36
+The verified 2026-07-25 `All` baseline contains 12,616 tests across 36
 component executables and one integration executable.
 
 ## Boundary validation and CI

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

@@ -27,7 +27,7 @@ using SharpRuntime::intcs;
  * 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, GetRange, ConvertAll<TOutput>, ToBuilder/Builder,
+ * CopyTo overloads, ConvertAll<TOutput>, 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
@@ -274,6 +274,22 @@ class ImmutableList {
         return ImmutableList<T>(std::move(v));
     }
 
+    /**
+     * @brief Returns a new list containing the contiguous range at @p index.
+     *
+     * C++ counterpart of .NET ImmutableList<T>.GetRange(int, int).
+     * @param index The zero-based first element in the range.
+     * @param count The number of elements to copy into the result.
+     * @return An immutable list containing the requested range.
+     * @throws System::ArgumentOutOfRangeException if the range is outside this list.
+     */
+    [[nodiscard]] ImmutableList<T> GetRange(intcs index, intcs count) const {
+        requireValidRange(index, count);
+        auto values = std::make_shared<std::vector<T>>(
+            data_->begin() + index, data_->begin() + index + count);
+        return ImmutableList<T>(std::move(values));
+    }
+
     /**
      * @brief Returns a new list with all elements sorted using T::operator<.
      *

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

@@ -0,0 +1,38 @@
+// 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 "System/ArgumentOutOfRangeException.hpp"
+#include "System/Collections/Immutable/ImmutableList.hpp"
+
+using System::Collections::Immutable::ImmutableList;
+
+TEST(ImmutableListRangeTests, GetRangeReturnsOrderedIndependentSlice) {
+    const auto source = ImmutableList<int>::Create({10, 20, 30, 40, 50});
+    const auto range = source.GetRange(1, 3);
+
+    ASSERT_EQ(range.getCountProperty(), 3);
+    EXPECT_EQ(range[0], 20);
+    EXPECT_EQ(range[1], 30);
+    EXPECT_EQ(range[2], 40);
+    EXPECT_EQ(source.getCountProperty(), 5);
+    EXPECT_EQ(source[1], 20);
+    EXPECT_EQ(source[3], 40);
+}
+
+TEST(ImmutableListRangeTests, GetRangeAllowsEmptyRangeAtBothBoundaries) {
+    const auto source = ImmutableList<int>::Create({10, 20});
+
+    EXPECT_TRUE(source.GetRange(0, 0).getIsEmptyProperty());
+    EXPECT_TRUE(source.GetRange(2, 0).getIsEmptyProperty());
+}
+
+TEST(ImmutableListRangeTests, GetRangeInvalidRangesThrowArgumentOutOfRangeException) {
+    const auto source = ImmutableList<int>::Create({10, 20});
+
+    EXPECT_THROW(source.GetRange(-1, 0), System::ArgumentOutOfRangeException);
+    EXPECT_THROW(source.GetRange(3, 0), System::ArgumentOutOfRangeException);
+    EXPECT_THROW(source.GetRange(1, -1), System::ArgumentOutOfRangeException);
+    EXPECT_THROW(source.GetRange(1, 2), System::ArgumentOutOfRangeException);
+}

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,613 passing tests across 37
+dependency edges, a clean native build, 12,616 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,613 passing across 36 component binaries plus one integration
+- Tests: 12,616 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,745 rows, all `done`; no `todo`, `doing`, `blocked`, or `needs_user` rows |
+| `ticket` | 1,746 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.
@@ -92,6 +92,8 @@ assertion without an explicit architecture decision.
   empty-list, ordering, and immutability regression coverage.
 - Added default full-list `ImmutableList<T>::Sort` and `Reverse` under ticket
   #1745, leaving range and custom-comparer overloads explicitly deferred.
+- Added `ImmutableList<T>::GetRange` under ticket #1746, including exact
+  boundary and invalid-range regression coverage.
 - Added seekable `BinaryReader::PeekChar` under ticket #1744. It returns the
   next UTF-8 character or EOF without advancing, restores the position after
   decode failure, and explicitly rejects non-seekable streams rather than
@@ -156,7 +158,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,613.
+to 12,616.
 
 ## Candidate roadmap
 
@@ -166,10 +168,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 copy/range/conversion, 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 copying/conversion, 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. **Complete only demanded `BinaryReader` character APIs.**
    `ReadChar`, `ReadDecimal`, and seekable `PeekChar` are implemented, while