feat: add AppendInterpolatedStringHandler

Author: linkdotnet

CHANGELOG.md

@@ -6,6 +6,10 @@ All notable changes to **ValueStringBuilder** will be documented in this file. T
 
 ## [Unreleased]
 
+### Added
+
+- Added `AppendInterpolatedStringHandler` to support zero-allocation string interpolation in `Append` and `AppendLine` methods.
+
 ## [3.2.0] - 2025-10-31
 
 ### Changed

src/LinkDotNet.StringBuilder/ValueStringBuilder.InterpolatedStringHandler.cs

@@ -0,0 +1,109 @@
+using System.Runtime.CompilerServices;
+
+namespace LinkDotNet.StringBuilder;
+
+public ref partial struct ValueStringBuilder
+{
+    /// <summary>
+    /// Appends an interpolated string to the builder.
+    /// </summary>
+    /// <param name="handler">The interpolated string handler.</param>
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public void Append([InterpolatedStringHandlerArgument("")] ref AppendInterpolatedStringHandler handler)
+    {
+        this = handler.Builder;
+    }
+
+    /// <summary>
+    /// Appends an interpolated string followed by a new line to the builder.
+    /// </summary>
+    /// <param name="handler">The interpolated string handler.</param>
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public void AppendLine([InterpolatedStringHandlerArgument("")] ref AppendInterpolatedStringHandler handler)
+    {
+        this = handler.Builder;
+        Append(Environment.NewLine);
+    }
+
+    /// <summary>
+    /// Nested struct which handles interpolated strings for <see cref="ValueStringBuilder"/>.
+    /// </summary>
+    [InterpolatedStringHandler]
+    public ref struct AppendInterpolatedStringHandler
+    {
+        internal ValueStringBuilder Builder;
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="AppendInterpolatedStringHandler"/> struct.
+        /// </summary>
+        /// <param name="literalLength">The length of the literal part of the interpolated string.</param>
+        /// <param name="formattedCount">The number of formatted segments in the interpolated string.</param>
+        /// <param name="builder">The builder to append to.</param>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public AppendInterpolatedStringHandler(int literalLength, int formattedCount, ValueStringBuilder builder)
+        {
+            this.Builder = builder;
+
+            // A conservative guess for the capacity.
+            this.Builder.EnsureCapacity(this.Builder.Length + literalLength + (formattedCount * 11));
+        }
+
+        /// <summary>
+        /// Appends a literal string to the handler.
+        /// </summary>
+        /// <param name="value">The literal string.</param>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public void AppendLiteral(string value) => Builder.Append(value);
+
+        /// <summary>
+        /// Appends a formatted value to the handler.
+        /// </summary>
+        /// <param name="value">The value to format.</param>
+        /// <typeparam name="T">The type of the value.</typeparam>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public void AppendFormatted<T>(T value)
+        {
+            if (value is ISpanFormattable formattable)
+            {
+                Builder.Append(formattable);
+            }
+            else
+            {
+                Builder.Append(value?.ToString());
+            }
+        }
+
+        /// <summary>
+        /// Appends a formatted value with a given format.
+        /// </summary>
+        /// <param name="value">The value to format.</param>
+        /// <param name="format">The format string.</param>
+        /// <typeparam name="T">The type of the value.</typeparam>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public void AppendFormatted<T>(T value, string? format)
+        {
+            if (value is ISpanFormattable formattable)
+            {
+                Builder.Append(formattable, format);
+            }
+            else
+            {
+                Builder.Append(value?.ToString());
+            }
+        }
+
+        /// <summary>
+        /// Appends a character span to the handler.
+        /// </summary>
+        /// <param name="value">The character span.</param>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public void AppendFormatted(ReadOnlySpan<char> value) => Builder.Append(value);
+
+        /// <summary>
+        /// Appends a string to the handler.
+        /// </summary>
+        /// <param name="value">The string value.</param>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public void AppendFormatted(string? value) => Builder.Append(value);
+    }
+}

tests/LinkDotNet.StringBuilder.UnitTests/ValueStringBuilder.InterpolatedString.Tests.cs

@@ -0,0 +1,99 @@
+namespace LinkDotNet.StringBuilder.UnitTests;
+
+public class ValueStringBuilderInterpolatedStringTests
+{
+    [Fact]
+    public void ShouldAppendInterpolatedString()
+    {
+        using var builder = new ValueStringBuilder();
+        var name = "World";
+        var version = 1.0;
+
+        builder.Append($"Hello {name}, version {version}");
+
+        builder.ToString().ShouldBe("Hello World, version 1");
+    }
+
+    [Fact]
+    public void ShouldAppendInterpolatedStringWithFormat()
+    {
+        using var builder = new ValueStringBuilder();
+        var price = 1.2345;
+
+        builder.Append($"Price: {price:N2}");
+
+        builder.ToString().ShouldBe("Price: 1.23");
+    }
+
+    [Fact]
+    public void ShouldAppendLineInterpolatedString()
+    {
+        using var builder = new ValueStringBuilder();
+        var name = "World";
+
+        builder.AppendLine($"Hello {name}");
+
+        builder.ToString().ShouldBe($"Hello World{Environment.NewLine}");
+    }
+
+    [Fact]
+    public void ShouldHandleSpanInInterpolatedString()
+    {
+        using var builder = new ValueStringBuilder();
+        ReadOnlySpan<char> span = "from span";
+
+        builder.Append($"Value {span}");
+
+        builder.ToString().ShouldBe("Value from span");
+    }
+
+    [Fact]
+    public void ShouldHandleCustomType()
+    {
+        using var builder = new ValueStringBuilder();
+        var custom = new CustomType { Value = "Test" };
+
+        builder.Append($"Custom: {custom}");
+
+        builder.ToString().ShouldBe("Custom: Test");
+    }
+
+    [Fact]
+    public void ShouldAppendToExistingContent()
+    {
+        using var builder = new ValueStringBuilder("Initial ");
+
+        builder.Append($"Appended {123}");
+
+        builder.ToString().ShouldBe("Initial Appended 123");
+    }
+
+    [Fact]
+    public void ShouldAppendMultipleInterpolatedStrings()
+    {
+        using var builder = new ValueStringBuilder();
+
+        builder.Append($"First {1} ");
+        builder.Append($"Second {2}");
+
+        builder.ToString().ShouldBe("First 1 Second 2");
+    }
+
+    [Fact]
+    public void ShouldClearAndThenAppendInterpolatedString()
+    {
+        using var builder = new ValueStringBuilder("Initial");
+        builder.Clear();
+
+        builder.Append($"New {1}");
+
+        builder.ToString().ShouldBe("New 1");
+    }
+
+    private class CustomType
+    {
+        public string Value { get; set; } = string.Empty;
+
+        public override string ToString() => Value;
+    }
+}