https://github.com/ktsu-dev/containers
https://github.com/ktsu-dev/containers
Last synced: 4 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/ktsu-dev/containers
- Owner: ktsu-dev
- License: mit
- Created: 2025-05-17T06:42:21.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2026-02-14T01:44:12.000Z (4 months ago)
- Last Synced: 2026-02-14T08:51:08.555Z (4 months ago)
- Language: C#
- Size: 465 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
- Authors: AUTHORS.md
- Copyright: COPYRIGHT.md
Awesome Lists containing this project
README
# ktsu.Containers
A high-performance collection library for .NET providing specialized container implementations with focus on performance, memory efficiency, and developer experience.
## 🚀 Features
- **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
## 📦 Collections
### OrderedCollection
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
### OrderedSet
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
### RingBuffer
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
## 🏆 Performance & Benchmarking
We've implemented a comprehensive benchmarking system using BenchmarkDotNet that validates our implementations against standard .NET collections.
### Benchmark Categories
#### 🎯 Container-Specific Benchmarks
- **OrderedCollection vs List + Sort vs SortedList**
- **OrderedSet vs HashSet vs SortedSet**
- **RingBuffer vs Queue vs List with size limiting**
#### 📊 Standard Collection Baselines
Performance baselines for all major .NET collections:
- List, HashSet, SortedSet
- Dictionary, SortedDictionary
- Queue, Stack
- ConcurrentDictionary, ConcurrentQueue
#### 🔄 Cross-Collection Comparisons
Direct comparisons for common scenarios:
- Building ordered collections (incremental vs bulk)
- Set operations across different implementations
- Memory efficiency patterns
- Real-world usage workflows
#### 📈 Performance Analysis
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)
### Running Benchmarks
#### Quick Start
```powershell
# 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
```
#### Available Targets
| 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 |
#### Command Line Options
```bash
# 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
```
## 📋 Installation
```xml
```
## 🔧 Usage Examples
### OrderedCollection
```csharp
// Create and populate
var collection = new OrderedCollection();
collection.Add(3);
collection.Add(1);
collection.Add(2);
// Collection automatically maintains order: [1, 2, 3]
// Efficient search
bool contains = collection.Contains(2); // O(log n) binary search
// Access by index
int first = collection[0]; // 1
```
### OrderedSet
```csharp
// Create with initial data
var set = new OrderedSet { 3, 1, 4, 1, 5 };
// Set contains unique elements in order: [1, 3, 4, 5]
// Set operations
var other = new OrderedSet { 4, 5, 6 };
set.UnionWith(other); // [1, 3, 4, 5, 6]
```
### RingBuffer
```csharp
// Create fixed-size buffer
var buffer = new RingBuffer(3);
buffer.PushBack(1);
buffer.PushBack(2);
buffer.PushBack(3);
buffer.PushBack(4); // Overwrites first element
// Buffer contains: [2, 3, 4]
// Index access
int latest = buffer[buffer.Count - 1]; // 4 (most recent)
```
## 🛠️ Development
### Building
```bash
dotnet build
```
### Testing
```bash
dotnet test
```
### Benchmarking
```bash
# Quick performance check
.\scripts\run-benchmarks.ps1 -Target Quick
# Comprehensive analysis
.\scripts\run-benchmarks.ps1 -Target All -Export Html
```
## 📊 Performance Characteristics
### OrderedCollection
- ✅ **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
### OrderedSet
- ✅ **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
### RingBuffer
- ✅ **Excellent for**: Streaming data, fixed-size caches, sliding windows
- ⚠️ **Consider alternatives for**: Dynamic growth requirements
- 🎯 **Sweet spot**: Continuous data streams with occasional random access
## 🤝 Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add comprehensive tests
5. Run benchmarks to validate performance
6. Submit a pull request
### Adding New Containers
When adding new containers:
1. Implement the container in `Containers/`
2. Add comprehensive tests in `Containers.Test/`
3. Create benchmark comparisons in `Containers.Benchmarks/`
4. Update documentation
## 📝 License
Licensed under the MIT License. See [LICENSE.md](LICENSE.md) for details.
## 🏗️ Architecture
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
## 🎯 Design Principles
1. **Performance First**: Every operation is optimized for speed and memory efficiency
2. **Standard Compliance**: Full compatibility with .NET collection interfaces
3. **Predictable Behavior**: Clear performance characteristics and edge case handling
4. **Developer Experience**: Intuitive APIs with comprehensive documentation
5. **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.