{"id":25009102,"url":"https://github.com/mrdav30/swiftcollections","last_synced_at":"2026-05-07T17:02:10.505Z","repository":{"id":275857133,"uuid":"911261401","full_name":"mrdav30/SwiftCollections","owner":"mrdav30","description":"A high-performance, memory-efficient library of collections designed for game development, simulations, and other performance-critical applications.","archived":false,"fork":false,"pushed_at":"2025-02-21T04:15:37.000Z","size":279,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-23T17:13:09.882Z","etag":null,"topics":["collections","csharp","data-structures","dotnet","game-development","memory-management","object-pooling","observables","performance","unity"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mrdav30.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-01-02T15:54:54.000Z","updated_at":"2025-02-21T04:08:00.000Z","dependencies_parsed_at":"2025-02-05T00:29:26.012Z","dependency_job_id":null,"html_url":"https://github.com/mrdav30/SwiftCollections","commit_stats":null,"previous_names":["mrdav30/swiftcollections"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrdav30%2FSwiftCollections","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrdav30%2FSwiftCollections/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrdav30%2FSwiftCollections/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrdav30%2FSwiftCollections/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mrdav30","download_url":"https://codeload.github.com/mrdav30/SwiftCollections/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250477810,"owners_count":21437049,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["collections","csharp","data-structures","dotnet","game-development","memory-management","object-pooling","observables","performance","unity"],"created_at":"2025-02-05T04:12:28.556Z","updated_at":"2026-05-07T17:02:10.499Z","avatar_url":"https://github.com/mrdav30.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SwiftCollections\n\n![SwiftCollections Icon](https://raw.githubusercontent.com/mrdav30/SwiftCollections/main/icon.png)\n\n[![.NET CI](https://github.com/mrdav30/SwiftCollections/actions/workflows/dotnet.yml/badge.svg)](https://github.com/mrdav30/SwiftCollections/actions/workflows/dotnet.yml)\n[![Coverage](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fmrdav30.github.io%2FSwiftCollections%2FSummary.json\u0026query=%24.summary.linecoverage\u0026suffix=%25\u0026label=coverage\u0026color=brightgreen)](https://mrdav30.github.io/SwiftCollections/)\n[![NuGet](https://img.shields.io/nuget/v/SwiftCollections.svg)](https://www.nuget.org/packages/SwiftCollections)\n[![NuGet Downloads](https://img.shields.io/nuget/dt/SwiftCollections.svg)](https://www.nuget.org/packages/SwiftCollections)\n[![License](https://img.shields.io/github/license/mrdav30/SwiftCollections.svg)](https://github.com/mrdav30/SwiftCollections/blob/main/LICENSE)\n[![Frameworks](https://img.shields.io/badge/frameworks-netstandard2.1%20%7C%20net8.0-512BD4.svg)](https://github.com/mrdav30/SwiftCollections)\n\n**SwiftCollections** is a high-performance collection library for performance-sensitive .NET workloads, including game systems, simulations, and spatial queries.\n\n---\n\n## 🛠️ Key Features\n\n- **Optimized for Performance**: Designed for low time complexity and minimal memory allocations.\n- **Framework Agnostic** : Works with .NET, Unity, and other game engines.\n- **Full Serialization Support**: Out-of-the-box round-trip serialization via MemoryPack across most core collections, with System.Text.Json constructor support on .NET 8+. A Lean (no MemoryPack) variant is available for projects that manage serialization independently.\n- **Fast core collections**: `SwiftDictionary`, `SwiftHashSet`, `SwiftList`, `SwiftQueue`, `SwiftStack`, `SwiftSortedList`\n- **Specialized containers**: `SwiftBucket`, `SwiftGenerationalBucket`, `SwiftPackedSet`, `SwiftSparseMap`, `SwiftBiDictionary`\n- **Flat 2D/3D storage**: `SwiftArray2D`, `SwiftArray3D`, `SwiftBoolArray2D`, `SwiftShortArray2D`\n- **Pools**: `SwiftObjectPool`, `SwiftArrayPool`, `SwiftCollectionPool`, and typed pool helpers\n- **Observable collections** for change-tracking scenarios\n- **Spatial queries** via typed `SwiftBVH\u003cTKey, TVolume\u003e`, `SwiftSpatialHash\u003cTKey, TVolume\u003e`, and `SwiftOctree\u003cTKey, TVolume\u003e` plus default numerics wrappers\n- **Lightweight diagnostics** via `SwiftCollections.Diagnostics` for opt-in low-level log/event routing\n\n---\n\n## 🚀 Installation\n\n### Non-Unity Projects\n\n1. **Choose the package that fits your runtime**:\n   - Use `SwiftCollections` if you want the standard package with built-in `MemoryPack` support.\n   - Use `SwiftCollections.Lean` if you want the same collections without the `MemoryPack` dependency, such as when integrating with toolchains that do better without MemoryPack-generated code.\n   - Use `SwiftCollections.FixedMathSharp` if you need fixed-point spatial query volumes backed by `FixedMathSharp`, with `MemoryPack` support included.\n   - Use `SwiftCollections.FixedMathSharp.Lean` if you need the fixed-point companion without the `MemoryPack` dependency.\n\n2. **Install via NuGet**:\n   - Standard package:\n\n     ```bash\n     dotnet add package SwiftCollections\n     ```\n\n   - Lean (no MemoryPack) package:\n\n     ```bash\n     dotnet add package SwiftCollections.Lean\n     ```\n\n   - Fixed-point companion (with MemoryPack):\n\n     ```bash\n     dotnet add package SwiftCollections.FixedMathSharp\n     ```\n\n   - Fixed-point companion, Lean (no MemoryPack):\n\n     ```bash\n     dotnet add package SwiftCollections.FixedMathSharp.Lean\n     ```\n\n3. **Or Download/Clone**:\n\n   ```bash\n   git clone https://github.com/mrdav30/SwiftCollections.git\n   ```\n\n   Then reference `src/SwiftCollections/SwiftCollections.csproj` or build the package locally.\n\n### Package Variants\n\nSwiftCollections is published in two build variants per package so you can choose between convenience and maximum compatibility:\n\n- `SwiftCollections` / `SwiftCollections.FixedMathSharp`\n  Includes `MemoryPack` and its generated serialization support. This is the best default choice for most .NET applications.\n- `SwiftCollections.Lean` / `SwiftCollections.FixedMathSharp.Lean`\n  Excludes the `MemoryPack` package and uses internal shim attributes so the same source compiles without the dependency. Choose this when you do not need built-in MemoryPack serialization, when you prefer to use a different serializer, or when your target environment is sensitive to MemoryPack-generated code paths.\n\nBoth standard and lean variants expose the same core collections API. The main difference is whether `MemoryPack` is part of the package and serialization surface.\n\nIf you use Unity Burst AOT, prefer the Lean variants. `MemoryPack`'s Unity support is centered on IL2CPP via its .NET Source Generator path, so the Lean variants are the safer choice for Burst AOT scenarios.\n\n### Unity\n\nUnity support is maintained separately:\n\n[SwiftCollections-Unity](https://github.com/mrdav30/SwiftCollections-Unity)\n\n---\n\n## 🧩 Dependencies\n\n- Core package dependency: [MemoryPack](https://github.com/Cysharp/MemoryPack) *(standard variants only)*\n- Optional fixed-point companion: [FixedMathSharp](https://github.com/mrdav30/FixedMathSharp) via `SwiftCollections.FixedMathSharp` or `SwiftCollections.FixedMathSharp.Lean`\n\n---\n\n## 📦 Library Overview\n\n### Core Data Structures\n\n- **SwiftDictionary**: A high-performance dictionary optimized for O(1) operations and minimal memory usage.\n- **SwiftBiDictionary**: A bidirectional dictionary for efficient forward and reverse lookups in O(1).\n- **SwiftHashSet**: An optimized set for unique values with fast operations.\n- **SwiftBucket**: High-performance collection for O(1) addition and removal with stable indexing.\n- **SwiftGenerationalBucket**: A bucket variant that tracks generations to prevent stale references.\n- **SwiftPackedSet**: A compact set implementation for dense integer keys.\n- **SwiftSparseMap**: A memory-efficient map for sparse key distributions.\n- **SwiftQueue**: Circular-buffer-based queue for ultra-low-latency operations.\n- **SwiftList**: A dynamic list optimized for speed-critical applications.\n- **SwiftSortedList**: Dynamically sorted collection with O(log n) operations.\n- **SwiftStack**: Fast array-based stack with O(1) operations.\n- **SwiftArray2D / SwiftArray3D**: Efficient, flat-mapped arrays for 2D and 3D data.\n- **SwiftBVH**: Bounding Volume Hierarchy for broad-phase spatial queries.\n- **SwiftSpatialHash**: Spatial hash for high-churn, uniform-size, and sparse huge-world scenes.\n- **SwiftOctree**: Hierarchical octree for dynamic scenes with uneven density.\n\n`SwiftDictionary\u003cTKey, TValue\u003e` and `SwiftHashSet\u003cT\u003e` use deterministic default comparers for `string` keys when no comparer is supplied. `object` keys also get a SwiftCollections default comparer that hashes strings deterministically, but non-string object-key determinism still depends on the underlying key type. Custom comparers are still supported.\n\n### Pools\n\n- **SwiftObjectPool**: Thread-safe generic object pooling for improved memory usage and performance.\n- **SwiftArrayPool**: Array-specific pool for efficient reuse of arrays.\n- **SwiftCollectionPool**: Pool for reusable collection instances (e.g., List, HashSet).\n- **Default Collection Pools**: Ready-to-use pools are available for `SwiftList`, `SwiftQueue`, `SwiftHashSet`, `SwiftDictionary`, `SwiftStack`, `SwiftPackedSet`, and `SwiftSparseMap`.\n\n### Spatial Data Structures\n\n- **SwiftBVH**: Bounding Volume Hierarchy for broad-phase queries with mixed or extreme object-size variance.\n- **SwiftSpatialHash**: Spatial hash for sparse huge-world needle queries and uniform-size high-churn workloads.\n- **SwiftOctree**: Hierarchical octree for dynamic scenes, uneven density, and repeated region queries.\n\nUse them by workload:\n\n- **SwiftBVH** is the best fit for scenes with mixed or extreme object-size variance (e.g. tiny units alongside large terrain pieces), large churning objects, and general broad-phase intersection queries over heterogeneous populations. It is not thread-safe; synchronize access externally if needed. Avoid it for dense same-size clustered scenes and for sparse huge-world needle (tiny query window) lookups.\n- **SwiftSpatialHash** is the best fit for sparse, huge-world scenes where small query windows rarely overlap many cells (O(1) bucket lookup dominates), and for high-frequency updates with mostly uniform-size objects. Performance degrades when object sizes vary widely, since a fixed cell size becomes either too coarse or too fine.\n- **SwiftOctree** is the strongest all-around performer for dynamic scenes with uniform or small objects, mixed broad-phase, and repeated regional queries over uneven distributions. Prefer it when most objects are similar in size or when queries target specific spatial sub-regions repeatedly.\n\n### Observable Collections\n\n- **SwiftObservableArray / SwiftObservableList / SwiftObservableDictionary**: Reactive, observable collections with property and collection change notifications.\n\n### Diagnostics\n\n- **DiagnosticChannel / DiagnosticEvent / DiagnosticLevel**: Lightweight diagnostics primitives for routing informational, warning, or error events without coupling the library to a higher-level logging framework.\n- **No-work disabled interpolated diagnostics**: `DiagnosticChannel.Write` supports interpolated messages without evaluating formatted expressions when the requested level is disabled.\n- **SwiftCollectionDiagnostics.Shared**: Ready-to-use shared channel for library-wide diagnostics.\n\nDiagnostics are opt-in and disabled by default until you configure a minimum level and sink.\n\n## 📖 Usage Examples\n\n### SwiftBVH for Spatial Queries\n\n```csharp\nvar bvh = new SwiftBVH\u003cint\u003e(100);\nvar volume = new BoundVolume(new Vector3(0, 0, 0), new Vector3(1, 1, 1));\nbvh.Insert(1, volume);\n\nvar results = new SwiftList\u003cint\u003e();\nbvh.Query(new BoundVolume(new Vector3(0, 0, 0), new Vector3(2, 2, 2)), results);\nConsole.WriteLine(results.Count); // Output: 1\n```\n\n### SwiftBVH with Custom Typed Volumes\n\n```csharp\nvar typedBvh = new SwiftBVH\u003cint, BoundVolume\u003e(100);\ntypedBvh.Insert(1, new BoundVolume(new Vector3(0, 0, 0), new Vector3(1, 1, 1)));\n```\n\n### SwiftSpatialHash for Broad-Phase Cell Queries\n\n```csharp\nvar spatialHash = new SwiftSpatialHash\u003cint\u003e(64, 2f);\nspatialHash.Insert(1, new BoundVolume(new Vector3(0, 0, 0), new Vector3(1, 1, 1)));\n\nvar nearby = new List\u003cint\u003e();\nspatialHash.QueryNeighborhood(\n    new BoundVolume(new Vector3(0, 0, 0), new Vector3(1, 1, 1)),\n    nearby);\n```\n\n### SwiftOctree for Hierarchical Region Queries\n\n```csharp\nvar worldBounds = new BoundVolume(new Vector3(0, 0, 0), new Vector3(64, 64, 64));\nvar octree = new SwiftOctree\u003cint\u003e(\n    worldBounds,\n    new SwiftOctreeOptions(maxDepth: 6, nodeCapacity: 8),\n    minNodeSize: 1f);\n\noctree.Insert(1, new BoundVolume(new Vector3(2, 2, 2), new Vector3(4, 4, 4)));\n\nvar visible = new List\u003cint\u003e();\noctree.Query(new BoundVolume(new Vector3(0, 0, 0), new Vector3(8, 8, 8)), visible);\n```\n\n### Fixed-Point SwiftBVH (Companion Package)\n\n```csharp\nvar fixedBvh = new SwiftFixedBVH\u003cint\u003e(100);\nfixedBvh.Insert(1, new FixedBoundVolume(new Vector3d(0, 0, 0), new Vector3d(1, 1, 1)));\n```\n\n### SwiftArray2D\n\n```csharp\nvar array2D = new SwiftArray2D\u003cint\u003e(10, 10);\narray2D[3, 4] = 42;\nConsole.WriteLine(array2D[3, 4]); // Output: 42\n```\n\n### SwiftQueue\n\n```csharp\nvar queue = new SwiftQueue\u003cint\u003e(10);\nqueue.Enqueue(5);\nConsole.WriteLine(queue.Dequeue()); // Output: 5\n```\n\n### Populating Arrays\n\n```csharp\nvar array = new int[10].Populate(() =\u003e new Random().Next(1, 100));\n```\n\n### Diagnostic Example\n\n```csharp\nusing System;\nusing SwiftCollections.Diagnostics;\n\nDiagnosticChannel diagnostics = SwiftCollectionDiagnostics.Shared;\ndiagnostics.MinimumLevel = DiagnosticLevel.Warning;\ndiagnostics.Sink = static (in DiagnosticEvent diagnostic) =\u003e\n{\n    Console.WriteLine($\"[{diagnostic.Channel}] {diagnostic.Level}: {diagnostic.Message} ({diagnostic.Source})\");\n};\n\ndiagnostics.Write(DiagnosticLevel.Info, \"Skipped because the minimum level is Warning.\", \"Bootstrap\");\ndiagnostics.Write(DiagnosticLevel.Error, \"Pool allocation failed.\", \"Bootstrap\");\ndiagnostics.Write(DiagnosticLevel.Warning, $\"Pool usage is {0.42:P0}.\", \"Bootstrap\");\n```\n\n## 🧪 Development\n\nBuild the solution:\n\n```bash\ndotnet build SwiftCollections.slnx -c Debug\n```\n\nRun the unit tests:\n\n```bash\ndotnet test tests/SwiftCollections.Tests/SwiftCollections.Tests.csproj -c Debug --no-build\n```\n\nRun benchmarks:\n\n```bash\ndotnet run --project tests/SwiftCollections.Benchmarks/SwiftCollections.Benchmarks.csproj -c Release -f net8\n```\n\nUseful benchmark runner commands:\n\n```bash\ndotnet run --project tests/SwiftCollections.Benchmarks/SwiftCollections.Benchmarks.csproj -c Release -f net8 -- list\ndotnet run --project tests/SwiftCollections.Benchmarks/SwiftCollections.Benchmarks.csproj -c Release -f net8 -- dictionary\ndotnet run --project tests/SwiftCollections.Benchmarks/SwiftCollections.Benchmarks.csproj -c Release -f net8 -- query --list flat\ndotnet run --project tests/SwiftCollections.Benchmarks/SwiftCollections.Benchmarks.csproj -c Release -f net8 -- hashset --filter \"*Contains*\"\ndotnet run --project tests/SwiftCollections.Benchmarks/SwiftCollections.Benchmarks.csproj -c Release -f net8 -- all --list flat\n```\n\nWith no extra arguments, BenchmarkDotNet's default switcher behavior is used. Leading non-option arguments are treated as benchmark selection aliases, and any remaining arguments are forwarded to BenchmarkDotNet.\n\n## 🛠️ Compatibility\n\n- `netstandard2.1`\n- `net8.0`\n- Windows, Linux, and macOS\n\nFixed-point BVH support is provided by the separate `SwiftCollections.FixedMathSharp` companion package.\n\n---\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [CONTRIBUTING](https://github.com/mrdav30/SwiftCollections/blob/main/CONTRIBUTING.md) guide for details on how to propose changes, report issues, and interact with the community.\n\n---\n\n## 👥 Contributors\n\n- **mrdav30** - Lead Developer\n- Contributions are welcome! Feel free to submit pull requests or report issues.\n\n---\n\n## 💬 Community \u0026 Support\n\nFor questions, discussions, or general support, join the official Discord community:\n\n👉 **[Join the Discord Server](https://discord.gg/mhwK2QFNBA)**\n\nFor bug reports or feature requests, please open an issue in this repository.\n\nWe welcome feedback, contributors, and community discussion across all projects.\n\n---\n\n## 📄 License\n\nThis project is licensed under the MIT License.\n\nSee the following files for details:\n\n- LICENSE – standard MIT license\n- NOTICE – additional terms regarding project branding and redistribution\n- COPYRIGHT – authorship information\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmrdav30%2Fswiftcollections","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmrdav30%2Fswiftcollections","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmrdav30%2Fswiftcollections/lists"}