A high-performance collection library for .NET providing specialized container implementations with focus on performance, memory efficiency, and developer experience.
- OrderedCollection: Maintains elements in sorted order with efficient binary search operations
- OrderedSet: Unique elements maintained in sorted order with full ISet support
- RingBuffer: Fixed-size circular buffer optimized for streaming data scenarios
- Comprehensive Benchmarking: World-class performance validation against .NET collections
A collection that maintains elements in sorted order with efficient insertion and search operations.
Key Features:
- O(log n) insertion maintaining sort order
- O(log n) search operations via binary search
- Multiple constructors with capacity and comparer support
- Implements ICollection, IReadOnlyCollection, IReadOnlyList
Best Use Cases:
- Incremental sorted data building
- Frequent search operations on ordered data
- Scenarios requiring both order and random access
A set implementation that maintains unique elements in sorted order.
Key Features:
- O(log n) Add/Remove/Contains operations
- Full ISet interface support (Union, Intersection, Except, etc.)
- Sorted enumeration without additional sorting cost
- Memory-efficient list-based implementation
Best Use Cases:
- Unique sorted collections
- Set operations with maintained order
- Mathematical set operations with sorted results
A fixed-size circular buffer optimized for continuous data streams.
Key Features:
- O(1) insertion and access operations
- Automatic wrapping when capacity is reached
- Index-based access to buffer elements
- Resizing and resampling capabilities
- Power-of-two sizing for optimal performance
Best Use Cases:
- Streaming data processing
- Fixed-size caches
- Sliding window algorithms
- Audio/signal processing buffers
We've implemented a comprehensive benchmarking system using BenchmarkDotNet that validates our implementations against standard .NET collections.
- OrderedCollection vs List + Sort vs SortedList
- OrderedSet vs HashSet vs SortedSet
- RingBuffer vs Queue vs List with size limiting
Performance baselines for all major .NET collections:
- List, HashSet, SortedSet
- Dictionary<TKey,TValue>, SortedDictionary<TKey,TValue>
- Queue, Stack
- ConcurrentDictionary<TKey,TValue>, ConcurrentQueue
Direct comparisons for common scenarios:
- Building ordered collections (incremental vs bulk)
- Set operations across different implementations
- Memory efficiency patterns
- Real-world usage workflows
Advanced scenarios including:
- Scalability testing (1K to 100K+ elements)
- Edge cases and worst-case scenarios
- Memory pressure analysis
- Specialized use cases (sliding windows, priority queues)
# Fast development feedback
.\scripts\run-benchmarks.ps1 -Target Quick
# Compare specific containers
.\scripts\run-benchmarks.ps1 -Target OrderedSet -Export Html
# Cross-collection analysis
.\scripts\run-benchmarks.ps1 -Target CrossComparison -Export All
# Full benchmark suite
.\scripts\run-benchmarks.ps1 -Target All -Export Html| Target | Description |
|---|---|
Quick | Fast subset for development feedback |
OrderedCollection | OrderedCollection vs alternatives |
OrderedSet | OrderedSet vs alternatives |
RingBuffer | RingBuffer vs alternatives |
Standard | Built-in .NET collection baselines |
CrossComparison | Direct cross-collection comparisons |
PerformanceAnalysis | Scalability and edge case analysis |
All | Complete benchmark suite |
# Manual benchmark execution
dotnet run --project Containers.Benchmarks --configuration Release
# Filtered benchmarks
dotnet run --project Containers.Benchmarks --configuration Release -- --filter "*Add*"# Export results
dotnet run --project Containers.Benchmarks --configuration Release -- --exporters html,csv,json<PackageReferenceInclude="ktsu.Containers"Version="1.0.0" />// Create and populatevarcollection=newOrderedCollection<int>();collection.Add(3);collection.Add(1);collection.Add(2);// Collection automatically maintains order: [1, 2, 3]// Efficient searchboolcontains=collection.Contains(2);// O(log n) binary search// Access by indexintfirst=collection[0];// 1// Create with initial datavarset=newOrderedSet<int>{3,1,4,1,5};// Set contains unique elements in order: [1, 3, 4, 5]// Set operationsvarother=newOrderedSet<int>{4,5,6};set.UnionWith(other);// [1, 3, 4, 5, 6]// Create fixed-size buffervarbuffer=newRingBuffer<int>(3);buffer.PushBack(1);buffer.PushBack(2);buffer.PushBack(3);buffer.PushBack(4);// Overwrites first element// Buffer contains: [2, 3, 4]// Index accessintlatest=buffer[buffer.Count-1];// 4 (most recent)dotnet builddotnet test# Quick performance check
.\scripts\run-benchmarks.ps1 -Target Quick
# Comprehensive analysis
.\scripts\run-benchmarks.ps1 -Target All -Export Html- ✅ Excellent for: Incremental sorted insertions, frequent searches
⚠️ Consider alternatives for: Large bulk operations (List + Sort may be faster)- 🎯 Sweet spot: 100-10,000 elements with mixed insert/search operations
- ✅ Excellent for: Unique sorted collections, set operations with order
⚠️ Consider alternatives for: Pure membership testing (HashSet is faster)- 🎯 Sweet spot: Mathematical set operations requiring sorted results
- ✅ Excellent for: Streaming data, fixed-size caches, sliding windows
⚠️ Consider alternatives for: Dynamic growth requirements- 🎯 Sweet spot: Continuous data streams with occasional random access
- Fork the repository
- Create a feature branch
- Make your changes
- Add comprehensive tests
- Run benchmarks to validate performance
- Submit a pull request
When adding new containers:
- Implement the container in
Containers/ - Add comprehensive tests in
Containers.Test/ - Create benchmark comparisons in
Containers.Benchmarks/ - Update documentation
Licensed under the MIT License. See LICENSE.md for details.
The library is built with performance and reliability in mind:
- Zero-allocation operations where possible
- Power-of-two sizing for optimal memory access patterns
- Binary search algorithms for O(log n) performance
- Comprehensive test coverage ensuring reliability
- Benchmark-driven development validating performance claims
- Performance First: Every operation is optimized for speed and memory efficiency
- Standard Compliance: Full compatibility with .NET collection interfaces
- Predictable Behavior: Clear performance characteristics and edge case handling
- Developer Experience: Intuitive APIs with comprehensive documentation
- Validation: Extensive testing and benchmarking ensures reliability
This library provides high-performance alternatives to standard .NET collections while maintaining familiar APIs and adding specialized functionality for common use cases.