FixedStrings 1.0.0

FixedStrings

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

FixedStrings provides a zero allocation valuetype based fixed string implementation with the following size 8/16/32/64.

// Zero allocation!
FixedString16 str = $"HelloWorld {DateTime.Now.Year}";
// Prints "HelloWorld 2023"
Console.Out.WriteLine(str.AsSpan());

Features

• Zero allocation via FixedString8, FixedString16, FixedString32 and FixedString64 structs.
• Supporting alignment and format for interpolated values

  byte value = 10; 
  FixedString16 str = $"Test 0x{value:X2}";
  

• Compatible with net7.0+

User Guide

Why FixedStrings?

Many modern applications are suffering from lots of allocations on the heap, and it is very frequent to see dozen of thousands of strings allocated on the managed heap. Having all these managed objects around is creating a lot more pressure on the GC, they can be more scattered in memory.

In many scenarios, you might be able to co-locate such strings closer to the class that are using them, but you might be able also to refine the memory requirement/usage for these strings.

For instance, on a 64 bit system, a single allocation of an empty managed string on the heap will take 24 bytes + 8 bytes for the reference to it. That's 32 bytes for an empty string! See details on sharplab.io.

With a fixed string, like FixedString8, you get 7 characters and it takes only 16 bytes or a FixedString16 would give similarly 15 characters while taking only 32 bytes!

As you can see in the benchmarks below, by avoiding an allocation to the heap, FixedStrings can be 2x as fast as creating them on the heap.

How does it work?

FixedStrings is relying on the C# 10 interpolated string handlers feature.

But unlike classical usage of interpolated string handlers, a FixedString is in fact itself an interpolation handler, using a fixed size buffer to store the string.

Each fixed string contains a short value for the length.

For example FixedString8 is declared like this:

[InterpolatedStringHandler]
public struct FixedString8 : IFixedString<FixedString8>
{
    private short _length;
    private short _c0;
    private short _c1;
    private short _c2;
    private short _c3;
    private short _c4;
    private short _c5;
    private short _c6;

    // ...
}

It is using a short for the internal representation of each characters to avoid marshalling issues - so that each character is passed as a plain short (UTF-16) value to the native side.

You can then copy around by value this string very easily and you can have a better control of the layout in memory.

Usage and restrictions

FixedStrings are not meant to replace all strings in your application. They are meant to be used for strings that are known to be short and that are used in a very hot path of your application.

• If you try to add more characters than the size of the fixed string, it will be truncated. For practical reasons, It won't throw an exception!

• FixedStrings support interpolation:

  FixedString8 str = $"Hello {name}";
  

  For performance reasons, supported types for values are: string and any types implementing ISpanFormattable (e.g int, float...etc.). A fixed string is itself ISpanFormattable and can be used as a value - and nested in string interpolations.

  Note that if a non string interpolated value cannot fit within the fixed string, it won't be emitted and the string will be truncated (in case of using a string). For example

  FixedString8 str = $"{"Hello"}{"World"}";
  

  will result in str containing "HelloWo" (7 characters). but the following interpolation:

  FixedString8 str = $"Hello{int.MaxValue}";
  

  will result in str containing "Hello", with the int value being discarded as it cannot fit within the fixed string.

• FixedStrings support assigning from a regular string:

  FixedString8 str = "Hello";
  

• You can get a ReadOnlySpan<char> directly from a FixedString:

  FixedString8 str = "Hello";
  ReadOnlySpan<char> span = str.AsSpan();
  

• FixedStrings can be copied by value:

  FixedString8 str = "Hello";
  FixedString8 str2 = str;
  

  str2 will be a copy of str.

• FixedStrings implement IFixedString<T> and can be used as a generic constraint:

  public ReadOnlySpan<char> Foo<T>(T value) where T : IFixedString<T>
  {
      // ...
      return value.AsSpan();
  }
  

Benchmarks

TestFixed is using a FixedString and TestDynamic is using a regular string.

• For FixedString8, the performance gain is 2.5x faster than using a regular string.
• For FixedString16, the performance gain is 2x faster than using a regular string.
• For FixedString32 / FixedString64, the performance gain is 30% faster than using a regular string.

Building FixedStrings

In order to build FixedStrings, you need:

• Install the .NET 8 SDK
• Install the .NET 7 SDK (For the benchmarks)

dotnet build -c Release src/FixedStrings.sln

License

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

Author

Alexandre Mutel aka xoofx.