Zero Allocation StringBuilder for .NET Core and Unity.

• Struct StringBuilder to avoid allocation of builder itself
• Rent write buffer from ThreadStatic or ArrayPool
• All append methods are generics(Append<T>(T value)) and write to buffer directly instead of concatenate value.ToString
• T0~T15 AppendFormat(AppendFormat<T0,...,T15>(string format, T0 arg0, ..., T15 arg15) avoids boxing of struct argument
• Also T0~T15 Concat(Concat<T0,...,T15>(T0 arg0, ..., T15 arg15)) avoid boxing and value.ToString allocation
• Convinient ZString.Format/Concat/Join methods can replace instead of String.Format/Concat/Join
• Can build both Utf16(Span<char>) and Utf8(Span<byte>) directly
• Can use inner buffer to avoid allocate final string
• Integrated with Unity TextMeshPro to avoid string allocation

This graph compares following codes.

• "x:" + x + " y:" + y + " z:" + z
• ZString.Concat("x:", x, " y:", y, " z:", z)
• string.Format("x:{0} y:{1} z:{2}", x, y, z)
• ZString.Format("x:{0} y:{1} z:{2}", x, y, z)
• new StringBuilder(), Append(), .ToString()
• ZString.CreateStringBuilder(), Append(), .ToString()

"x:" + x + " y:" + y + " z:" + z is converted to String.Concat(new []{ "x:", x.ToString(), " y:", y.ToString(), " z:", z.ToString() }) by C# compiler. It has each .ToString allocation and params array allocation. string.Format calls String.Format(string, object, object, object) so each arguments causes int -> object boxing.

All ZString methods only allocate final string. Also, ZString has enabled to access inner buffer so if output target has stringless api(like Unity TextMeshPro's SetCharArray), you can achieve completely zero allocation.

For .NET Core, use NuGet.

PM> Install-Package ZString

For Unity, check the releases page, download ZString.Unity.unitypackage.

async void Example(int x, int y, int z)
{
    // same as x + y + z
    _ = ZString.Concat(x, y, z);

    // also can use numeric format strings
    _ = ZString.Format("x:{0}, y:{1:000}, z:{2:P}",x, y, z);

    _ = ZString.Join(',', x, y, z);

    // for Unity, direct write(avoid string allocation completely) to TextMeshPro
    tmp.SetTextFormat("Position: {0}, {1}, {2}", x, y, z);

    // create StringBuilder
    using(var sb = ZString.CreateStringBuilder())
    {
        sb.Append("foo");
        sb.AppendLine(42);
        sb.AppendFormat("{0} {1:.###}", "bar", 123.456789);

        // and build final string
        var str = sb.ToString();

        // for Unity, direct write to TextMeshPro
        tmp.SetText(sb);

        // write to destination buffer
        sb.TryCopyTo(dest, out var written);
    }

    // C# 8.0, Using declarations
    // create Utf8 StringBuilder that build Utf8 directly to avoid encoding
    using var sb2 = ZString.CreateUtf8StringBuilder();

    sb2.Concat("foo:", x, ", bar:", y);

    // directly write to steam or dest to avoid allocation
    await sb2.WriteToAsync(stream);
    sb2.TryCopyTo(dest, out var written);
}

static class ZString

struct Utf16ValueStringBuilder : IBufferWriter<char>, IDisposable

struct Utf8ValueStringBuilder : IBufferWriter<byte>, IDisposable

static class TextMeshProExtensions(Unity only)

ZString.CreateStringBuilder(notNested:true) is a special optimized parameter that uses ThreadStatic buffer instead of rent from ArrayPool. It is slightly faster but can not use in nested.

using(var sb = ZString.CreateStringBuilder(true))
{
    sb.Append("foo");

    using var sb2 = ZString.CreateStringBuilder(true); // NG, nested stringbuilder uses conflicted same buffer
    var str = ZString.Concat("x", 100); // NG, ZString.Concat/Join/Format uses threadstatic buffer
}

// OK, return buffer immediately.
using(var sb = ZString.CreateStringBuilder(true))
{
    sb.Append("foo");
    return sb.ToString();
}

ZString.CreateStringBuilder() is same as ZString.CreateStringBuilder(notNested:false).

In default, SByte, Int16, Int32, Int64, Byte, UInt16, UInt32, UInt64, Single, Double, TimeSpan, DateTime, DateTimeOffset, Decimal, Guid, String, Char are used there own formatter to avoid .ToString() allocation, write directly to buffer. If not exists there list type, used .ToString() and copy string data.

If you want to avoid to convert string in custom type, you can register your own formatter.

Utf16ValueStringBuilder.RegisterTryFormat((MyStruct value, Span<char> destination, out int charsWritten, ReadOnlySpan<char> format) =>
{
    // write value to destionation and set size to charsWritten.
    charsWritten = 0;
    return true;
});

Utf8ValueStringBuilder.RegisterTryFormat((MyStruct value, Span<byte> destination, out int written, StandardFormat format) =>
{
    written = 0;
    return true;
});

CreateStringBuilder and CreateUtf8StringBuilder must use with using. Because their builder rent 64K buffer from ArrayPool. If not return buffer, allocate 64K buffer when string builder is created.

Utf8ValueStringBuilder and Utf16ValueStringBuilder implements IBufferWriter so you can pass serializer(such as JsonSerializer of System.Text.Json). But be careful to boxing copy, ValueStringBuilder is mutable struct. For example,

using var sb = ZString.CreateUtf8StringBuilder();
IBufferWriter<byte> boxed = sb;
var writer = new Utf8JsonWriter(boxed);
JsonSerializer.Serialize(writer, ....);

using var unboxed = (Utf8ValueStringBuilder)boxed;
var str = unboxed.ToString();

This library is licensed under the the MIT License.

.NET Standard 2.0 and Unity version borrows dotnet/runtime conversion methods, there exists under ZString/Number directory.