This document provides an introduction to ZLinq, a zero-allocation LINQ library for .NET. It covers the fundamental concepts, goals, and key features that distinguish ZLinq from the standard System.Linq library. For detailed information about specific features, see the following pages:
ZLinq is a high-performance, zero-allocation LINQ implementation for .NET that maintains 99% compatibility with .NET 10's LINQ operators while eliminating the memory allocations typically associated with method chaining. The library supports all .NET platforms including netstandard2.0, netstandard2.1, net8, net9, net10, Unity, and Godot.
Primary Goals:
| Goal | Description |
|---|---|
| Zero Allocation | Eliminate heap allocations during method chaining through struct-based design |
| High Performance | Leverage SIMD acceleration, span-based operations, and compile-time optimizations |
| Compatibility | Maintain 99% API compatibility with System.Linq, including .NET 10 operators |
| Cross-Platform | Support all .NET platforms from .NET Framework 4.8 to .NET 10 and game engines |
The library is validated against dotnet/runtime's System.Linq.Tests with over 9,000 passing tests, demonstrating production-ready compatibility README.md38-40
Sources: README.md1-45
ZLinq achieves zero-allocation LINQ through two core types that work together to replace the traditional IEnumerable<T> and IEnumerator<T> pattern:
ValueEnumerable<TEnumerator, T>
The ValueEnumerable<TEnumerator, T> type is a readonly ref struct wrapper that holds a struct-based enumerator README.md47-51 In .NET 9+, it uses the allows ref struct constraint to enable Span<T> integration. Key characteristics:
IEnumerable<T> in .NET 9+ due to ref struct restrictionsIValueEnumerator<T>
The IValueEnumerator<T> interface is implemented by struct types and defines the iteration protocol README.md53-61:
TryGetNext(out T current) - Combines MoveNext + Current into a single method callTryGetNonEnumeratedCount(out int count) - Returns count without enumeration (optimization)TryGetSpan(out ReadOnlySpan<T> span) - Provides direct span access when possible (enables SIMD)TryCopyTo(scoped Span<T> destination, Index offset) - Efficient bulk copy operationsDispose() - Resource cleanup (required for pooled memory)This design minimizes virtual dispatch overhead and enables the C# compiler to inline operations across method chains.
Sources: README.md44-75
Sources: README.md85-98 README.md109-114
ZLinq provides full LINQ operations on Span<T> and ReadOnlySpan<T> types, enabled by .NET 9/C# 13's allows ref struct constraint README.md33 This allows stack-allocated span types to flow through LINQ operations without any heap allocations.
The TryGetSpan method in IValueEnumerator<T> enables operations to access the underlying span directly for maximum performance README.md59
ZLinq automatically applies SIMD vectorization to supported operations when TryGetSpan returns true. In .NET 8+, the following operations are SIMD-accelerated README.md583-592:
| Operation | Supported Types |
|---|---|
| Sum/SumUnchecked | sbyte, short, int, long, byte, ushort, uint, ulong, double |
| Average | sbyte, short, int, long, byte, ushort, uint, ulong, double |
| Min/Max | byte, sbyte, short, ushort, int, uint, long, ulong, nint, nuint, Int128, UInt128 |
| Contains | byte, sbyte, short, ushort, int, uint, long, ulong, bool, char, nint, nuint |
| SequenceEqual | byte, sbyte, short, ushort, int, uint, long, ulong, bool, char, nint, nuint |
The library also provides explicit AsVectorizable() methods and VectorizedUpdate for custom SIMD operations. For details, see LINQ to SIMD.
ZLinq extends LINQ to hierarchical data structures through the ITraverser<T> interface, enabling axis-based navigation familiar from LINQ to XML README.md456-476:
| Axis Method | Description |
|---|---|
| Ancestors() | Navigate upward through parent hierarchy |
| Children() | Enumerate immediate children |
| Descendants() | Depth-first traversal of all descendants |
| BeforeSelf() | Siblings before the current node |
| AfterSelf() | Siblings after the current node |
Built-in support exists for:
DirectoryInfo/FileInfo navigation README.md481-506JsonNode querying README.md508-574GameObject/Transform and VisualElement hierarchy README.md576-778Node hierarchy README.md849-898For implementation details, see LINQ to Tree.
Sources: README.md33-36 README.md456-476 README.md580-704
Sources: README.md8 README.md31-36 README.md79-80 README.md481-898
ZLinq requires calling AsValueEnumerable() on any collection to begin using zero-allocation LINQ operations:
The AsValueEnumerable() method converts various collection types to ValueEnumerable<TEnumerator, T> with specialized enumerators for optimal performance README.md108-119:
| Source Type | Enumerator | Allocation |
|---|---|---|
| T[] | FromArray<T> | Zero |
| List<T> | FromList<T> | Zero |
| Span<T> (.NET 9+) | FromSpan<T> | Zero |
| Memory<T> | FromMemory<T> | Zero |
| Dictionary<K,V> | FromDictionary<K,V> | Zero |
| IEnumerable<T> | FromEnumerable<T> | Runtime detection* |
*FromEnumerable<T> performs runtime type detection: if the actual type is T[] or List<T>, it uses zero-allocation paths README.md112-113
For automatic application without AsValueEnumerable(), see Drop-in Replacement System.
Sources: README.md20-28 README.md85-119
Each LINQ operation returns a new ValueEnumerable<TNewEnumerator, T> with a different generic type parameter, building a nested enumerator composition at compile time:
The type system enables automatic specialization: calling Where on ValueEnumerable<FromArray<int>, int> produces a specialized ArrayWhere<int> enumerator rather than a generic Where<FromArray<int>, int>. This allows operation fusion where multiple operations are combined into a single enumerator (e.g., ArrayWhereSelect<TSource, TResult>).
All work is deferred until a materialization operation like ToArray(), ToList(), or foreach is invoked, following standard LINQ lazy evaluation semantics.
For detailed information on operation chaining and specialization patterns, see Operation Chaining and Specialization.
Sources: README.md64-74
This multi-tiered optimization strategy is enabled by the IValueEnumerator<T> interface design. Operations progressively attempt faster paths before falling back to slower methods. For example, Count() first tries TryGetNonEnumeratedCount, then TryGetSpan for length access, and only falls back to iteration if necessary.
Sources: README.md53-74
ZLinq adds several operators beyond System.Linq to enable efficient zero-allocation scenarios:
Collection Conversion:
ValueEnumerable.Range(), .Repeat(), .Empty() - Optimized factory methods README.md122-124Sequence(), InfiniteSequence() - .NET 10 operators available on all platforms, including DateTime/DateTimeOffset overloads README.md126-206Memory Management:
ToArrayPool() - Returns PooledArray<T> rented from ArrayPool<T>.Shared README.md146-164CopyTo(Span<T>), CopyTo(List<T>) - Avoid return collection allocation README.md142-144SIMD Operations:
SumUnchecked() - Unchecked overflow for maximum SIMD performance README.md134-136AsVectorizable() - Explicit SIMD operations on arrays/spans README.md603-704Extended Numeric Support:
Average(), Sum() - Support all INumber<T> types, not just primitives README.md130-136Utility:
JoinToString(separator) - String concatenation since ValueEnumerable<T> cannot be passed to String.Join README.md165-167For comprehensive operation documentation, see LINQ Operations.
Sources: README.md104-206
Understanding the differences between ZLinq and System.Linq is critical for successful adoption:
| Aspect | System.Linq | ZLinq | Implication |
|---|---|---|---|
| Base Type | IEnumerable<T> | ValueEnumerable<TEnum, T> | Cannot pass to IEnumerable<T> methods |
| Allocation | Heap per chain | Stack (ref struct in .NET 9+) | Zero GC pressure but ref struct limitations |
| Type Stability | Same type across chains | Different type per operation | Cannot reassign to same variable |
| Async Support | Full | None (ref struct in .NET 9+) | Cannot span await/yield boundaries |
| Platform | All .NET | netstandard2.0+ | Broad support but version-dependent features |
Critical Limitations:
IEnumerable<T>, cannot span async boundaries README.md210-218var seq = seq.Concat(...) patterns README.md220ToArrayPool() for temporary materialization) README.md212For migration strategies and workarounds, see Getting Started.
Sources: README.md208-222
The ZLinq.DropInGenerator package provides automatic conversion of System.Linq calls to ZLinq without code changes. It uses a Roslyn source generator to emit higher-priority extension methods that shadow System.Linq README.md224-253:
The DropInGenerateTypes flags control which types receive drop-in support:
Array, Span, Memory, List, Enumerable (IEnumerable<T>)Collection = Array | Span | Memory | ListEverything = Collection | EnumerableImportant: Using DropInGenerateTypes.Enumerable makes System.Linq inaccessible and requires careful namespace management README.md246-253
For detailed configuration including custom types via ZLinqDropInExternalExtension, see Drop-in Replacement System.
Sources: README.md224-366
Installation via NuGet:
Platform-Specific Packages:
dotnet add package ZLinq.Godot (Godot 4.0+)dotnet add package ZLinq.FileSystemdotnet add package ZLinq.JsonWhere to Go Next:
ValueEnumerable<T> and IValueEnumerator<T> in depthQuick Start Example:
Sources: README.md77-98 README.md481-898
Refresh this wiki