XenoAtom.Collections 1.1.1

XenoAtom.Collections

<img align="right" width="160px" height="160px" src="https://raw.githubusercontent.com/XenoAtom/XenoAtom.Collections/main/img/XenoAtom.Collections.png">

This .NET library offers structure-based collections optimized for high performance and minimal memory usage. It features UnsafeList<T>, UnsafeDictionary<TKey, TValue>, and UnsafeHashSet<T>. These collections are implemented as value types backed by a managed array (except for fixed capacity list UnsafeList<T>.N2 ... UnsafeList<T>.N1024), specifically designed for performance-critical scenarios where avoiding additional memory allocations for container objects is essential.

The code has been derived from the .NET Core runtime released under the MIT license.

These collections contains unsafe methods (prefixed by Unsafe) and should be used with caution.

✨ Features

• Three main collections: UnsafeList<T>, UnsafeDictionary<TKey, TValue> and UnsafeHashSet<T>
  • Plus fixed capacity list for efficient stack allocation:
    • UnsafeList<T>.N2
    • UnsafeList<T>.N4
    • UnsafeList<T>.N8
    • UnsafeList<T>.N16
    • UnsafeList<T>.N32
    • UnsafeList<T>.N64
    • UnsafeList<T>.N128
    • UnsafeList<T>.N256
    • UnsafeList<T>.N512
    • UnsafeList<T>.N1024
• Faster access for Dictionary and HashSet by requiring the key to be IEquatable<TKey>
• Struct based collections to avoid an allocation for the container and improve locality
• Proper debugger support for collections with custom DebuggerDisplay
• A few advanced unsafe methods to avoid checks
  • e.g Unsafe<T>.UnsafeSetCount, Unsafe<T>.UnsafeGetRefAt...
• A fast sort by ref via Span<T>.SortByRef that can inline the comparer and avoid the copy to the stack of the value being compared.
• • NativeAOT compatible
• net8.0+ support

📖 Usage

In general, the API is similar to the standard collections.

It is recommended to not expose in public APIs these unsafe collections but instead use them internally for performance-critical scenarios.

Here are some examples

• UnsafeList<T>

  // UnsafeList is a struct, but the underlying array is a managed array
  var list = new UnsafeList<int>();
  list.Add(1);
  list.Add(2);
  list.Add(3);
  list.Add(4);
  var span = list.AsSpan();
  foreach(var value in span)
  {
      Console.WriteLine(value);
  }
  

• UnsafeList<T>.N4

  // UnsafeList is a struct, and the underlying array is a fixed size array (on the stack)
  var list = new UnsafeList<int>.N4();
  list.Add(1);
  list.Add(2);
  list.Add(3);
  list.Add(4);
  var span = list.AsSpan();
  foreach(var value in span)
  {
      Console.WriteLine(value);
  }
  

• UnsafeDictionary<TKey, TValue>

  // UnsafeDictionary is a struct, but the underlying array is a managed array
  var dictionary = new UnsafeDictionary<int, string>();
  dictionary.Add(1, "One");
  dictionary.Add(2, "Two");
  dictionary.Add(3, "Three");
  dictionary.Add(4, "Four");
  foreach(var pair in dictionary)
  {
      Console.WriteLine($"{pair.Key} = {pair.Value}");
  }
  

• UnsafeHashSet<T>

  // UnsafeDictionary is a struct, but the underlying array is a managed array
  var hashSet = new UnsafeHashSet<int>();
  hashSet.Add(1);
  hashSet.Add(2);
  hashSet.Add(3);
  hashSet.Add(4);
  foreach(var value in hashSet)
  {
      Console.WriteLine(value);
  }
  

📊 Benchmarks

Some benchmarks are available in the src\XenoAtom.Collections.Bench folder. Here are some results:

• UnsafeList<T> and UnsafeDictionary<TKey, TValue> can be up to 20% faster than the standard List<T> and Dictionary<TKey, TValue> for some scenarios.
• UnsafeList<T>.N16 can be up to 50% faster than the standard List<T> for adding elements.
• Span<T>.SortByRef can be up to 50% faster than Array.Sort/Span.Sort for some scenarios.

🪪 License

This software is released under the BSD-2-Clause license.

🤗 Author

Alexandre Mutel aka XenoAtom.