feat: add PadLeft and PadRight methods for padding strings

Author: linkdotnet

CHANGELOG.md

@@ -6,6 +6,10 @@ All notable changes to **ValueStringBuilder** will be documented in this file. T
 
 ## [Unreleased]
 
+### Added
+
+- Added `PadLeft(ReadOnlySpan<char>, int, char)` and `PadRight(ReadOnlySpan<char>, int, char)` methods to append padded strings without allocating additional memory (by [@SMAH1](https://github.com/SMAH1) in #260)
+
 ## [3.0.0] - 2025-10-30
 
 This is the `v3` major release. The API is almost the same as in `v2` - there is only a slight change in the `Concat` static helper method to reflect a less-boxed API.

src/LinkDotNet.StringBuilder/ValueStringBuilder.Pad.cs

@@ -43,4 +43,54 @@ public void PadRight(int totalWidth, char paddingChar)
         buffer[bufferPosition..totalWidth].Fill(paddingChar);
         bufferPosition = totalWidth;
     }
+
+    /// <summary>
+    /// Appends the source string padded on the left with the given character to reach the specified total width.
+    /// </summary>
+    /// <param name="source">The source string to pad and append.</param>
+    /// <param name="totalWidth">Total width of the padded string.</param>
+    /// <param name="paddingChar">Character to pad the string with. Defaults to space.</param>
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public void PadLeft(ReadOnlySpan<char> source, int totalWidth, char paddingChar = ' ')
+    {
+        if (totalWidth <= source.Length)
+        {
+            Append(source);
+            return;
+        }
+
+        var padding = totalWidth - source.Length;
+        EnsureCapacity(bufferPosition + totalWidth);
+
+        buffer.Slice(bufferPosition, padding).Fill(paddingChar);
+        bufferPosition += padding;
+
+        source.CopyTo(buffer[bufferPosition..]);
+        bufferPosition += source.Length;
+    }
+
+    /// <summary>
+    /// Appends the source string padded on the right with the given character to reach the specified total width.
+    /// </summary>
+    /// <param name="source">The source string to pad and append.</param>
+    /// <param name="totalWidth">Total width of the padded string.</param>
+    /// <param name="paddingChar">Character to pad the string with. Defaults to space.</param>
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public void PadRight(ReadOnlySpan<char> source, int totalWidth, char paddingChar = ' ')
+    {
+        if (totalWidth <= source.Length)
+        {
+            Append(source);
+            return;
+        }
+
+        var padding = totalWidth - source.Length;
+        EnsureCapacity(bufferPosition + totalWidth);
+
+        source.CopyTo(buffer[bufferPosition..]);
+        bufferPosition += source.Length;
+
+        buffer.Slice(bufferPosition, padding).Fill(paddingChar);
+        bufferPosition += padding;
+    }
 }

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

@@ -41,4 +41,106 @@ public void GivenTotalWidthIsSmallerThanCurrentLength_WhenPadRight_ThenShouldNot
 
         stringBuilder.ToString().ShouldBe("Hello");
     }
+
+    [Fact]
+    public void ShouldPadLeftWithSource()
+    {
+        using var stringBuilder = new ValueStringBuilder();
+
+        stringBuilder.PadLeft("Hello".AsSpan(), 10, ' ');
+
+        stringBuilder.ToString().ShouldBe("     Hello");
+    }
+
+    [Fact]
+    public void ShouldPadRightWithSource()
+    {
+        using var stringBuilder = new ValueStringBuilder();
+
+        stringBuilder.PadRight("Hello".AsSpan(), 10, ' ');
+
+        stringBuilder.ToString().ShouldBe("Hello     ");
+    }
+
+    [Fact]
+    public void ShouldPadLeftWithSourceAndCustomChar()
+    {
+        using var stringBuilder = new ValueStringBuilder();
+
+        stringBuilder.PadLeft("42".AsSpan(), 5, '0');
+
+        stringBuilder.ToString().ShouldBe("00042");
+    }
+
+    [Fact]
+    public void ShouldPadRightWithSourceAndCustomChar()
+    {
+        using var stringBuilder = new ValueStringBuilder();
+
+        stringBuilder.PadRight("Test".AsSpan(), 8, '*');
+
+        stringBuilder.ToString().ShouldBe("Test****");
+    }
+
+    [Fact]
+    public void GivenTotalWidthIsSmallerThanSourceLength_WhenPadLeftWithSource_ThenShouldAppendSourceOnly()
+    {
+        using var stringBuilder = new ValueStringBuilder();
+
+        stringBuilder.PadLeft("Hello".AsSpan(), 3, ' ');
+
+        stringBuilder.ToString().ShouldBe("Hello");
+    }
+
+    [Fact]
+    public void GivenTotalWidthIsSmallerThanSourceLength_WhenPadRightWithSource_ThenShouldAppendSourceOnly()
+    {
+        using var stringBuilder = new ValueStringBuilder();
+
+        stringBuilder.PadRight("Hello".AsSpan(), 3, ' ');
+
+        stringBuilder.ToString().ShouldBe("Hello");
+    }
+
+    [Fact]
+    public void ShouldPadLeftWithSourceMultipleTimes()
+    {
+        using var stringBuilder = new ValueStringBuilder();
+
+        stringBuilder.PadLeft("A".AsSpan(), 3, '-');
+        stringBuilder.PadLeft("B".AsSpan(), 3, '-');
+
+        stringBuilder.ToString().ShouldBe("--A--B");
+    }
+
+    [Fact]
+    public void ShouldPadRightWithSourceMultipleTimes()
+    {
+        using var stringBuilder = new ValueStringBuilder();
+
+        stringBuilder.PadRight("A".AsSpan(), 3, '-');
+        stringBuilder.PadRight("B".AsSpan(), 3, '-');
+
+        stringBuilder.ToString().ShouldBe("A--B--");
+    }
+
+    [Fact]
+    public void ShouldPadLeftWithSourceAndExistingContent()
+    {
+        using var stringBuilder = new ValueStringBuilder("Start ");
+
+        stringBuilder.PadLeft("End".AsSpan(), 10, '.');
+
+        stringBuilder.ToString().ShouldBe("Start .......End");
+    }
+
+    [Fact]
+    public void ShouldPadRightWithSourceAndExistingContent()
+    {
+        using var stringBuilder = new ValueStringBuilder("Start ");
+
+        stringBuilder.PadRight("End".AsSpan(), 10, '.');
+
+        stringBuilder.ToString().ShouldBe("Start End.......");
+    }
 }