feat: Add AppendIf methods to ZaSpanStringBuilder for conditional appending

Author: CorentinGS

src/ZaString/Extensions/ZaSpanStringBuilderExtensions.cs

@@ -133,6 +133,72 @@ public static ref ZaSpanStringBuilder AppendLine(ref this ZaSpanStringBuilder bu
         return ref builder.AppendLine();
     }
 
+    /// <summary>
+    ///     Conditionally appends a string to the builder if the condition is true.
+    /// </summary>
+    /// <param name="builder">The builder instance.</param>
+    /// <param name="condition">The condition to evaluate.</param>
+    /// <param name="value">The string to append if the condition is true. If null, the operation is a no-op.</param>
+    /// <returns>A reference to the builder to allow for method chaining.</returns>
+    public static ref ZaSpanStringBuilder AppendIf(ref this ZaSpanStringBuilder builder, bool condition, string? value)
+    {
+        if (condition)
+        {
+            builder.Append(value);
+        }
+        return ref builder;
+    }
+
+    /// <summary>
+    ///     Conditionally appends a read-only span of characters to the builder if the condition is true.
+    /// </summary>
+    /// <param name="builder">The builder instance.</param>
+    /// <param name="condition">The condition to evaluate.</param>
+    /// <param name="value">The span of characters to append if the condition is true.</param>
+    /// <returns>A reference to the builder to allow for method chaining.</returns>
+    public static ref ZaSpanStringBuilder AppendIf(ref this ZaSpanStringBuilder builder, bool condition, ReadOnlySpan<char> value)
+    {
+        if (condition)
+        {
+            builder.Append(value);
+        }
+        return ref builder;
+    }
+
+    /// <summary>
+    ///     Conditionally appends a single character to the builder if the condition is true.
+    /// </summary>
+    /// <param name="builder">The builder instance.</param>
+    /// <param name="condition">The condition to evaluate.</param>
+    /// <param name="value">The character to append if the condition is true.</param>
+    /// <returns>A reference to the builder to allow for method chaining.</returns>
+    public static ref ZaSpanStringBuilder AppendIf(ref this ZaSpanStringBuilder builder, bool condition, char value)
+    {
+        if (condition)
+        {
+            builder.Append(value);
+        }
+        return ref builder;
+    }
+
+    /// <summary>
+    ///     Conditionally appends a formatted value to the builder if the condition is true.
+    /// </summary>
+    /// <typeparam name="T">The type of the value, which must implement ISpanFormattable.</typeparam>
+    /// <param name="builder">The builder instance.</param>
+    /// <param name="condition">The condition to evaluate.</param>
+    /// <param name="value">The value to format and append if the condition is true.</param>
+    /// <param name="format">An optional format string for the value.</param>
+    /// <returns>A reference to the builder to allow for method chaining.</returns>
+    public static ref ZaSpanStringBuilder AppendIf<T>(ref this ZaSpanStringBuilder builder, bool condition, T value, ReadOnlySpan<char> format = default) where T : ISpanFormattable
+    {
+        if (condition)
+        {
+            builder.Append(value, format);
+        }
+        return ref builder;
+    }
+
     /// <summary>
     ///     Throws a standardized exception for out-of-range errors.
     /// </summary>

tests/ZaString.Tests/ZaSpanStringBuilderBasicTests.cs

@@ -613,4 +613,175 @@ public void Clear_PreservesCapacity()
         Assert.Equal(originalCapacity, builder.Capacity);
         Assert.Equal(50, builder.Capacity);
     }
+
+    [Fact]
+    public void AppendIf_String_TrueCondition_AppendsValue()
+    {
+        Span<char> buffer = stackalloc char[100];
+        var builder = ZaSpanStringBuilder.Create(buffer);
+
+        builder.AppendIf(true, "Hello");
+
+        Assert.Equal("Hello", builder.AsSpan());
+        Assert.Equal(5, builder.Length);
+    }
+
+    [Fact]
+    public void AppendIf_String_FalseCondition_AppendsNothing()
+    {
+        Span<char> buffer = stackalloc char[100];
+        var builder = ZaSpanStringBuilder.Create(buffer);
+
+        builder.AppendIf(false, "Hello");
+
+        Assert.Equal("", builder.AsSpan());
+        Assert.Equal(0, builder.Length);
+    }
+
+    [Fact]
+    public void AppendIf_String_NullValue_TrueCondition_AppendsNothing()
+    {
+        Span<char> buffer = stackalloc char[100];
+        var builder = ZaSpanStringBuilder.Create(buffer);
+
+        builder.AppendIf(true, null);
+
+        Assert.Equal("", builder.AsSpan());
+        Assert.Equal(0, builder.Length);
+    }
+
+    [Fact]
+    public void AppendIf_ReadOnlySpan_TrueCondition_AppendsValue()
+    {
+        Span<char> buffer = stackalloc char[100];
+        var builder = ZaSpanStringBuilder.Create(buffer);
+        var span = "World".AsSpan();
+
+        builder.AppendIf(true, span);
+
+        Assert.Equal("World", builder.AsSpan());
+        Assert.Equal(5, builder.Length);
+    }
+
+    [Fact]
+    public void AppendIf_ReadOnlySpan_FalseCondition_AppendsNothing()
+    {
+        Span<char> buffer = stackalloc char[100];
+        var builder = ZaSpanStringBuilder.Create(buffer);
+        var span = "World".AsSpan();
+
+        builder.AppendIf(false, span);
+
+        Assert.Equal("", builder.AsSpan());
+        Assert.Equal(0, builder.Length);
+    }
+
+    [Fact]
+    public void AppendIf_Char_TrueCondition_AppendsValue()
+    {
+        Span<char> buffer = stackalloc char[100];
+        var builder = ZaSpanStringBuilder.Create(buffer);
+
+        builder.AppendIf(true, 'A');
+
+        Assert.Equal("A", builder.AsSpan());
+        Assert.Equal(1, builder.Length);
+    }
+
+    [Fact]
+    public void AppendIf_Char_FalseCondition_AppendsNothing()
+    {
+        Span<char> buffer = stackalloc char[100];
+        var builder = ZaSpanStringBuilder.Create(buffer);
+
+        builder.AppendIf(false, 'A');
+
+        Assert.Equal("", builder.AsSpan());
+        Assert.Equal(0, builder.Length);
+    }
+
+    [Fact]
+    public void AppendIf_FormattedValue_TrueCondition_AppendsValue()
+    {
+        Span<char> buffer = stackalloc char[100];
+        var builder = ZaSpanStringBuilder.Create(buffer);
+
+        builder.AppendIf(true, 42);
+
+        Assert.Equal("42", builder.AsSpan());
+        Assert.Equal(2, builder.Length);
+    }
+
+    [Fact]
+    public void AppendIf_FormattedValue_FalseCondition_AppendsNothing()
+    {
+        Span<char> buffer = stackalloc char[100];
+        var builder = ZaSpanStringBuilder.Create(buffer);
+
+        builder.AppendIf(false, 42);
+
+        Assert.Equal("", builder.AsSpan());
+        Assert.Equal(0, builder.Length);
+    }
+
+    [Fact]
+    public void AppendIf_FormattedValueWithFormat_TrueCondition_AppendsFormattedValue()
+    {
+        Span<char> buffer = stackalloc char[100];
+        var builder = ZaSpanStringBuilder.Create(buffer);
+
+        builder.AppendIf(true, 42, "X4");
+
+        Assert.Equal("002A", builder.AsSpan());
+        Assert.Equal(4, builder.Length);
+    }
+
+    [Fact]
+    public void AppendIf_ChainedCalls_WorksCorrectly()
+    {
+        Span<char> buffer = stackalloc char[100];
+        var builder = ZaSpanStringBuilder.Create(buffer);
+        var isAdmin = true;
+        var hasPermission = false;
+
+        builder.Append("Status: ")
+            .AppendIf(isAdmin, "[Admin]")
+            .AppendIf(hasPermission, "[Permission]")
+            .Append(" User");
+
+        Assert.Equal("Status: [Admin] User", builder.AsSpan());
+        Assert.Equal(20, builder.Length);
+    }
+
+    [Fact]
+    public void AppendIf_MixedWithRegularAppends_WorksCorrectly()
+    {
+        Span<char> buffer = stackalloc char[100];
+        var builder = ZaSpanStringBuilder.Create(buffer);
+        var showId = true;
+        var showAge = false;
+
+        builder.Append("User: John")
+            .AppendIf(showId, " (ID: 123)")
+            .AppendIf(showAge, " Age: 25")
+            .Append(" - Active");
+
+        Assert.Equal("User: John (ID: 123) - Active", builder.AsSpan());
+        Assert.Equal(29, builder.Length);
+    }
+
+    [Fact]
+    public void AppendIf_AllTypesWithFalseCondition_ProducesEmptyString()
+    {
+        Span<char> buffer = stackalloc char[100];
+        var builder = ZaSpanStringBuilder.Create(buffer);
+
+        builder.AppendIf(false, "string")
+            .AppendIf(false, "span".AsSpan())
+            .AppendIf(false, 'c')
+            .AppendIf(false, 42);
+
+        Assert.Equal("", builder.AsSpan());
+        Assert.Equal(0, builder.Length);
+    }
 }