A high‑performance, single‑file replacement for
List<T>with span‑aware APIs, fine‑grained capacity control and a battery‑included toolbox of 90+ methods. Targets .NET 6, 7, 8 and newer.
- Why DynamicArray?
- Features
- Installation
- Quick Start
- API Overview
- Complexity Analysis
- Benchmarks
- Memory & Growth Strategy
- Roadmap
- Contributing
- License
- Changelog
List<T> covers 80 % of use‑cases but leaves power‑users wanting when they need:
- Span‑friendly bulk APIs (
AddRange(ReadOnlySpan<T>), in‑place compaction, etc.) - Predictable performance measured in nanoseconds, matching raw array access
- Advanced manipulations (rotate, shuffle, flip, distinct, set ops…)
- Statistics helpers (sum, average, median, min, max)
- Full control over capacity management (trim, compact, ensure) without reflection hacks
DynamicArray delivers all that in a single, dependency‑free C# file you can drop anywhere.
| Category | Highlight |
|---|---|
| Performance | Inlined fast‑paths for Add, Insert, Remove rival raw array speed (≤ 1 ns/op) |
| Bulk operations | AddRange/InsertRange on IEnumerable<T> and ReadOnlySpan<T> |
| Math helpers | Sum, Average, Median, Min, Max for numeric types |
| Algorithms | Shuffle (Fisher‑Yates), Rotate, Flip, Reverse, Sort |
| Search | SIMD‑backed IndexOf/LastIndexOf, BinarySearch, Find/FindAll |
| Set‑like | Distinct, AddIfNotContains, SequenceEqual |
| String utils | ToUpper, ToLower, ChangeCaseRange (culture‑aware) |
| Factory | CreateRandom (numeric) & CreateRandomStrings |
| Safety | Full argument validation, XML‑docs, 100 % tests coverage |
# .NET CLI
dotnet add package DynamicArray.CoreOr copy DynamicArray.cs into your project (no external deps).
var scores = new DynamicArray<int>();
scores.AddRange(stackalloc[] { 23, 42, 7, 15 }); // span overload
scores.Insert(2, 99); // [23, 42, 99, 7, 15]
Console.WriteLine($"Median: {scores.Median()}"); // 23
scores.Shuffle();
foreach (var s in scores)
Console.WriteLine(s);90+ public methods are grouped below. See XML docs or IntelliSense for full signatures.
| Group | Key Methods |
|---|---|
| Add / Insert | Add, AddRange, Insert, InsertRange, AddIfNotContains |
| Remove | Remove, RemoveAt, RemoveLast, RemoveRange, RemoveAll, Clear |
| Transform | Sort, Reverse, Rotate, Flip, Shuffle, TrimExcess, Compact, Resize |
| Search | IndexOf, LastIndexOf, BinarySearch, Find, FindAll, Contains |
| Math / Stats | Sum, Average, Median, Min, Max |
| Conversion | ToArray, Clone, ConvertAll |
| String ext. | ToUpper, ToLower, ChangeCaseRange |
Notation: n = current size, m = added elements, k = removed/matched elements, L = avg string length.
| Operation | Time | Space | Notes |
|---|---|---|---|
Add |
O(1) amort. | O(1) | Fast‑path + doubling strategy |
AddRange(ReadOnlySpan) |
O(m) | O(n+m) amort. | Zero‑alloc copy when room fits |
Insert |
O(n) | O(1) | Tail copied once via Array.Copy |
InsertRange |
O(n+m) | O(1) | Tail shift + single materialisation |
RemoveAt |
O(n) | O(1) | Shift left tail |
RemoveRange |
O(n) | O(1) | Single pass copy |
RemoveAll |
O(n) | O(1) | Span compaction |
Clear |
O(1) / O(n) | O(1) | Value vs reference types |
Sort |
O(n log n) | O(log n) | Array.Introsort |
Median |
O(n log n) | O(n) | Uses temp copy |
IndexOf |
O(n) | O(1) | SIMD for default comparer |
BinarySearch |
O(log n) | O(1) | Requires sorted array |
Sum, Average |
O(n) | O(1) | Numeric only |
Full table »
(expanded table as provided in docs/Complexity.md)
| Scenario (int) | List<T> |
DynamicArray | Speed‑up |
|---|---|---|---|
10 M × Add |
0.90 ms | 0.98 ms | 0.9× |
| Append w/ resize (cold) | 1.2 µs | 1.3 µs | 0.9× |
Head InsertRange 100 k |
5.2 s | 0.18 s | × 28 |
Mid RemoveRange 100 k |
0.23 s | 0.09 s | × 2.5 |
RemoveAll 50 % match |
0.31 s | 0.14 s | × 2.2 |
Run on Ryzen 7 5700U • .NET 8 • Tiered PGO ON. Full BenchmarkDotNet logs in benchmarks/.
- Growth factor 2× – balances realloc cost and fragmentation (configurable).
- Shrink‑threshold 25 % – capacity halves when usage ≤ 25 % to avoid thrashing.
Compact()– forces capacity = Count for memory‑constrained scenarios.- All internal copies leverage
Array.CopyorSpan<T>.CopyTofor SIMD moves.
- 🔄 Immutable wrapper (
ReadOnlyDynamicArray<T>) - 🧵 Thread‑safe variant with striped locks
- 🗂️
GroupBy/Chunkhelpers (LINQ‑like without allocs) - 📉 Optional
IReadOnlyList<T>/IList<T>adapter for drop‑in replacement
Feel free to 👍 on issues or open PRs to influence priority.
- Fork & clone
dotnet test(all green?)dotnet benchmark(optional) – ensure no perf regression- Commit using Conventional Commits (
feat:,fix:,perf:…) - Open PR against
main
We appreciate unit tests, benchmarks and real‑world usage reports!
MIT – do whatever you want, but don’t blame us if it explodes 🧨. See LICENSE.
- ♻️ Re‑wrote
Addwith fast/slow path – now parity withList<T> - 🚀
InsertRange,RemoveRange,RemoveAllsingle‑pass implementations - 🔍
IndexOf/LastIndexOfdelegate to SIMD runtime paths - ✨ Minor API polish –
Shufflenow usesRandom.Shared - 📝 Added full Complexity Matrix & Benchmarks docs
Older entries
- 2.0 – 2025‑05‑22 – Initial public release
- 1.x – Internal iterations