diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..cc1f0b1 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,7 @@ +All documentation, branch names, variable and method names, and comments must use American English. Pull request titles and commit messages must also be in English. +Do not create additional AGENTS.md files. +Do not use the `--no-build` parameter when running the application or tests, as it leads to missing libraries. +All tests should use xUnit with the FluentAssertions package. +Information about available classes and methods from the standard List and List operations is documented in README.md. Additional compatibility methods are distributed across NuGet packages. +Before adding, modifying, or removing methods or classes, review the README files from related repositories (links will be added later). +Projects and tests must target .NET 8 by default and also support .NET 9, .NET 7, and .NET 6. Use the latest available C# language features when possible. diff --git a/README.md b/README.md index 9b3e070..151691a 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,181 @@ -# Recyclable.Collections.Compatibility.List -`Recyclable.Collections.Compatibility.List` project is an open source add-on for [Recyclable.Collections](https://github.com/mlemanczyk/Recyclable.Collections) providing `List` compatibility features to the recyclable collections framework. +# Recyclable.Collections.Compatibility.List +`Recyclable.Collections.Compatibility.List` is an open source add-on for [Recyclable.Collections](https://github.com/mlemanczyk/Recyclable.Collections). It provides compatibility APIs that mirror `List` and larger list implementations while reusing memory through recyclable pools. ## Included compatibility packs -* `RecyclableList` +- `RecyclableList` -# Milestones +## Milestones 1. 👉 Implement compatibility pack - 1. ✅ `RecyclableList` - 1. 👉 `RecyclableLongList` - 1. 🅿️ `RecyclableQueue` - 1. 🅿️ `RecyclableSortedList` - 1. 🅿️ `RecyclableStack` - 1. 🅿️ `RecyclableUnorderedList` + 1. ✅ `RecyclableList` + 1. 👉 `RecyclableLongList` + 1. 🅿️ `RecyclableQueue` + 1. 🅿️ `RecyclableSortedList` + 1. 🅿️ `RecyclableStack` + 1. 🅿️ `RecyclableUnorderedList` 1. 🅿️ Review performance 1. 🅿️ Optimize performance -# Characteristics of the classes -The package +## Characteristics of the classes +All classes use [Recyclable.Collections](https://github.com/mlemanczyk/Recyclable.Collections) internally to minimize memory allocations. -## Common -* All classes will internally or externally utilize [Recyclable.Collections](https://github.com/mlemanczyk/Recyclable.Collections) to benefit from recyclable memory pools. +### Current collections +- `RecyclableList` – drop-in replacement for `List`. +- `RecyclableLongList` – supports capacities greater than `int.MaxValue`; currently partially implemented. + +### Planned collections +The following types are planned but not yet implemented. Method signatures are subject to change and will mirror their .NET equivalents. +- `RecyclableQueue` – equivalent to `Queue`. +- `RecyclableSortedList` – equivalent to `SortedList`. +- `RecyclableStack` – equivalent to `Stack`. +- `RecyclableUnorderedList` – unordered list similar to `HashSet`. + +### Standard .NET collections not provided here +This repository does not currently include recyclable versions of: +- `LinkedList` +- `Dictionary` +- `HashSet` +- `ObservableCollection` + +## Extension classes and methods +The compatibility API is implemented through a set of extension classes. The lists below show the available and planned methods. + +### `zzzRecyclableListCompatibilityList` +File: `RecyclableList.Compatibility.List.cs` +```csharp +ReadOnlyCollection AsReadOnly(this RecyclableList list) +int BinarySearch(this RecyclableList list, T item) +int BinarySearch(this RecyclableList list, T item, IComparer? comparer) +int BinarySearch(this RecyclableList list, int index, int count, T item, IComparer? comparer) +RecyclableList ConvertAll(this RecyclableList list, Converter converter) +void CopyTo(this RecyclableList list, T[] array) +void CopyTo(this RecyclableList list, int index, T[] array, int arrayIndex, int count) +void ForEach(this RecyclableList list, Action action) +RecyclableList GetRange(this RecyclableList list, int index, int count) +int RemoveAll(this RecyclableList list, Predicate match) +void RemoveRange(this RecyclableList list, int index, int count) +void Reverse(this RecyclableList list) +void Reverse(this RecyclableList list, int index, int count) +void Sort(this RecyclableList list) +void Sort(this RecyclableList list, Comparison comparison) +void Sort(this RecyclableList list, IComparer? comparer) +void Sort(this RecyclableList list, int index, int count, IComparer? comparer) +T[] ToArray(this RecyclableList list) +void TrimExcess(this RecyclableList list) +bool TrueForAll(this RecyclableList list, Predicate match) +``` + +### `zzzRecyclableListCompatibilityListInsertRange` +File: `RecyclableList.Compatibility.List.InsertRange.cs` +```csharp +void InsertRange(this RecyclableList list, int index, in Array items) +void InsertRange(this RecyclableList list, int index, in T[] items) +void InsertRange(this RecyclableList list, int index, ReadOnlySpan items) +void InsertRange(this RecyclableList list, int index, Span items) +void InsertRange(this RecyclableList list, int index, List items) +void InsertRange(this RecyclableList list, int index, ICollection items) +void InsertRange(this RecyclableList list, int index, ICollection items) +void InsertRange(this RecyclableList list, int index, RecyclableList items) +void InsertRange(this RecyclableList list, int index, RecyclableLongList items) +void InsertRange(this RecyclableList list, int index, IEnumerable items, int growByCount = RecyclableDefaults.MinPooledArrayLength) +void InsertRange(this RecyclableList list, int index, IReadOnlyList items) +void InsertRange(this RecyclableList list, int index, IEnumerable items, int growByCount = RecyclableDefaults.MinPooledArrayLength) +``` + +### `zzzRecyclableListCompatibilityListIndexOf` +File: `RecyclableList.Compatibility.List.IndexOf.cs` +```csharp +int LastIndexOf(this RecyclableList list, T item) +int LastIndexOf(this RecyclableList list, T item, int index) +int LastIndexOf(this RecyclableList list, T item, int index, int count) +``` + +### `zzzRecyclableListCompatibilityListFind` +File: `RecyclableList.Compatibility.List.Find.cs` +```csharp +bool Exists(this RecyclableList list, Predicate match) +T? Find(this RecyclableList list, Predicate match) +RecyclableList FindAll(this RecyclableList list, Predicate match) +RecyclableList FindAllIndexes(this RecyclableList list, Predicate match) +int FindIndex(this RecyclableList list, int startIndex, int count, Predicate match) +int FindIndex(this RecyclableList list, int startIndex, Predicate match) +int FindIndex(this RecyclableList list, Predicate match) +T? FindLast(this RecyclableList list, Predicate match) +int FindLastIndex(this RecyclableList list, int startIndex, int count, Predicate match) +int FindLastIndex(this RecyclableList list, int startIndex, Predicate match) +int FindLastIndex(this RecyclableList list, Predicate match) +``` + +### `zzzRecyclableLongListCompatibilityList` +File: `RecyclableLongList.Compatibility.List.cs` +```csharp +ReadOnlyCollection AsReadOnly(this RecyclableLongList list) +int BinarySearch(this RecyclableLongList list, T item) +int BinarySearch(this RecyclableLongList list, T item, IComparer? comparer) +int BinarySearch(this RecyclableLongList list, int index, int count, T item, IComparer? comparer) +RecyclableLongList ConvertAll(this RecyclableLongList list, Converter converter) +void CopyTo(this RecyclableLongList list, T[] array) +void CopyTo(this RecyclableLongList list, int index, T[] array, int arrayIndex) +void CopyTo(this RecyclableLongList list, int index, T[] array, int arrayIndex, int count) +void ForEach(this RecyclableLongList list, Action action) +RecyclableLongList GetRange(this RecyclableLongList list, int startIndex, int count) +``` +Internal methods still to be implemented: +```csharp +int RemoveAll(this RecyclableLongList list, Predicate match) +void RemoveRange(this RecyclableLongList list, int index, int count) +void Reverse(this RecyclableLongList list) +void Reverse(this RecyclableLongList list, int index, int count) +void Sort(this RecyclableLongList list) +void Sort(this RecyclableLongList list, Comparison comparison) +void Sort(this RecyclableLongList list, IComparer? comparer) +void Sort(this RecyclableLongList list, int index, int count, IComparer? comparer) +T[] ToArray(this RecyclableLongList list) +void TrimExcess(this RecyclableLongList list) +bool TrueForAll(this RecyclableLongList list, Predicate match) +``` + +### `zzzRecyclableLongListCompatibilityListFind` +File: `RecyclableLongList.Compatibility.List.Find.cs` +```csharp +bool Exists(this RecyclableLongList list, Predicate match) +T? Find(this RecyclableLongList list, Predicate match) +RecyclableLongList FindAll(this RecyclableLongList list, Predicate match) +RecyclableLongList FindAllIndexes(this RecyclableLongList list, Predicate match) +int FindIndex(this RecyclableLongList list, int startIndex, int count, Predicate match) +int FindIndex(this RecyclableLongList list, int startIndex, Predicate match) +int FindIndex(this RecyclableLongList list, Predicate match) +T? FindLast(this RecyclableLongList list, Predicate match) +int FindLastIndex(this RecyclableLongList list, int startIndex, int count, Predicate match) +int FindLastIndex(this RecyclableLongList list, int startIndex, Predicate match) +int FindLastIndex(this RecyclableLongList list, Predicate match) +``` + +### `zzzRecyclableLongListCompatibilityListIndexOf` +File: `RecyclableLongList.Compatibility.List.IndexOf.cs` +Internal methods planned: +```csharp +int LastIndexOf(this RecyclableLongList list, T item) +int LastIndexOf(this RecyclableLongList list, T item, int index) +int LastIndexOf(this RecyclableLongList list, T item, int index, int count) +``` + +### `zzzRecyclableLongListCompatibilityListInsertRange` +File: `RecyclableLongList.Compatibility.List.InsertRange.cs` +All methods are internal placeholders and currently throw `NotImplementedException`: +```csharp +void InsertRange(this RecyclableLongList list, int index, in Array items) +void InsertRange(this RecyclableLongList list, int index, in T[] items) +void InsertRange(this RecyclableLongList list, int index, ReadOnlySpan items) +void InsertRange(this RecyclableLongList list, int index, Span items) +void InsertRange(this RecyclableLongList list, int index, List items) +void InsertRange(this RecyclableLongList list, int index, ICollection items) +void InsertRange(this RecyclableLongList list, int index, ICollection items) +void InsertRange(this RecyclableLongList list, int index, RecyclableList items) +void InsertRange(this RecyclableLongList list, int index, RecyclableLongList items) +void InsertRange(this RecyclableLongList list, int index, IEnumerable items, int growByCount = RecyclableDefaults.MinPooledArrayLength) +void InsertRange(this RecyclableLongList list, int index, IReadOnlyList items) +void InsertRange(this RecyclableLongList list, int index, IEnumerable items, int growByCount = RecyclableDefaults.MinPooledArrayLength) +``` + +## Testing +The unit tests are written with **xUnit** and **FluentAssertions**. Projects and tests target **.NET 8** by default and also support **.NET 9**, **.NET 7**, and **.NET 6**. diff --git a/Recyclable.Collections.Compatibility.List.Benchmarks/Recyclable.Collections.Compatibility.List.Benchmarks.csproj b/Recyclable.Collections.Compatibility.List.Benchmarks/Recyclable.Collections.Compatibility.List.Benchmarks.csproj index 028a0c0..aa9cfd3 100644 --- a/Recyclable.Collections.Compatibility.List.Benchmarks/Recyclable.Collections.Compatibility.List.Benchmarks.csproj +++ b/Recyclable.Collections.Compatibility.List.Benchmarks/Recyclable.Collections.Compatibility.List.Benchmarks.csproj @@ -2,7 +2,7 @@ Exe - net6.0;net7.0 + net8.0;net9.0;net7.0;net6.0 enable enable diff --git a/Recyclable.Collections.Compatibility.List.Tests/Recyclable.Collections.Compatibility.List.Tests.csproj b/Recyclable.Collections.Compatibility.List.Tests/Recyclable.Collections.Compatibility.List.Tests.csproj index ab07c6c..0371962 100644 --- a/Recyclable.Collections.Compatibility.List.Tests/Recyclable.Collections.Compatibility.List.Tests.csproj +++ b/Recyclable.Collections.Compatibility.List.Tests/Recyclable.Collections.Compatibility.List.Tests.csproj @@ -1,7 +1,7 @@  - net6.0;net7.0 + net8.0;net9.0;net7.0;net6.0 enable enable diff --git a/Recyclable.Collections.Compatibility.List/Recyclable.Collections.Compatibility.List.csproj b/Recyclable.Collections.Compatibility.List/Recyclable.Collections.Compatibility.List.csproj index 8e1cf8a..8b3c1a0 100644 --- a/Recyclable.Collections.Compatibility.List/Recyclable.Collections.Compatibility.List.csproj +++ b/Recyclable.Collections.Compatibility.List/Recyclable.Collections.Compatibility.List.csproj @@ -1,7 +1,7 @@ - net6.0;net7.0 + net8.0;net9.0;net7.0;net6.0 enable enable true