feat: add string.ConcatIf

CHANGELOG.md

@@ -23,6 +23,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - X10D: Added `TextWriter.WriteLineNoAlloc(uint[, ReadOnlySpan<char>[, IFormatProvider]])`.
 - X10D: Added `TextWriter.WriteLineNoAlloc(long[, ReadOnlySpan<char>[, IFormatProvider]])`.
 - X10D: Added `TextWriter.WriteLineNoAlloc(ulong[, ReadOnlySpan<char>[, IFormatProvider]])`.
+- X10D: Added `string.ConcatIf`.
 - X10D.Unity: Added `RaycastHit.GetComponent` and `RaycastHit.TryGetComponent`.
 - X10D.Unity: Added `DebugUtility.DrawFunction`, and `DebugUtility.DrawUnjoinedPolyhedron` on which it relies.
 

X10D.Tests/src/Text/StringTests.cs

@@ -105,6 +105,44 @@ public class StringTests
         Assert.Throws<ArgumentNullException>(() => _ = "Hello World".ChangeEncoding(Encoding.UTF8, null!));
     }
 
+    [Test]
+    public void ConcatIf_ShouldConcatenateString_GivenTrueCondition()
+    {
+        Assert.Multiple(() =>
+        {
+            Assert.That("Hello".ConcatIf(true, " World"), Is.EqualTo("Hello World"));
+            Assert.That("Hello".ConcatIf(true, () => " World"), Is.EqualTo("Hello World"));
+            Assert.That("Hello".ConcatIf(() => true, " World"), Is.EqualTo("Hello World"));
+            Assert.That("Hello".ConcatIf(() => true, () => " World"), Is.EqualTo("Hello World"));
+        });
+    }
+
+    [Test]
+    public void ConcatIf_ShouldNotConcatenateString_GivenFalseCondition()
+    {
+        Assert.Multiple(() =>
+        {
+            Assert.That("Hello".ConcatIf(false, " World"), Is.EqualTo("Hello"));
+            Assert.That("Hello".ConcatIf(false, () => " World"), Is.EqualTo("Hello"));
+            Assert.That("Hello".ConcatIf(() => false, " World"), Is.EqualTo("Hello"));
+            Assert.That("Hello".ConcatIf(() => false, () => " World"), Is.EqualTo("Hello"));
+        });
+    }
+
+    [Test]
+    public void ConcatIf_ShouldThrowArgumentNullException_GivenNullConditionFactory()
+    {
+        Assert.Throws<ArgumentNullException>(() => _ = "".ConcatIf(null!, "Hello World"));
+        Assert.Throws<ArgumentNullException>(() => _ = "".ConcatIf(null!, () => "Hello World"));
+    }
+
+    [Test]
+    public void ConcatIf_ShouldThrowArgumentNullException_GivenNullValueFactory()
+    {
+        Assert.Throws<ArgumentNullException>(() => _ = "".ConcatIf(true, (Func<string>?)null!));
+        Assert.Throws<ArgumentNullException>(() => _ = "".ConcatIf(() => true, (Func<string>?)null!));
+    }
+
     [Test]
     public void CountSubstring_ShouldHonor_StringComparison()
     {

X10D/src/Text/StringExtensions.cs

@@ -125,6 +125,80 @@ public static class StringExtensions
         return value.GetBytes(sourceEncoding).ToString(destinationEncoding);
     }
 
+    /// <summary>
+    ///     Appends a string to the current string if the specified condition evaluates to <see langword="true" />.
+    /// </summary>
+    /// <param name="value">The current string.</param>
+    /// <param name="condition">The condition to evaluate.</param>
+    /// <param name="appendValue">The string to append if the condition is true.</param>
+    /// <returns>The concatenated string.</returns>
+    [Pure]
+    public static string? ConcatIf(this string? value, bool condition, string? appendValue)
+    {
+        return condition ? value + appendValue : value;
+    }
+
+    /// <summary>
+    ///     Appends a string to the current string if the specified condition evaluates to <see langword="true" />.
+    /// </summary>
+    /// <param name="value">The current string.</param>
+    /// <param name="conditionFactory">The function that returns the condition to evaluate.</param>
+    /// <param name="appendValue">The string to append if the condition is true.</param>
+    /// <returns>The concatenated string.</returns>
+    /// <exception cref="ArgumentNullException"><paramref name="conditionFactory" /> is <see langword="null" />.</exception>
+    [Pure]
+    public static string? ConcatIf(this string? value, Func<bool> conditionFactory, string? appendValue)
+    {
+        if (conditionFactory is null)
+        {
+            throw new ArgumentNullException(nameof(conditionFactory));
+        }
+
+        return conditionFactory() ? value + appendValue : value;
+    }
+
+    /// <summary>
+    ///     Appends a string to the current string if the specified condition evaluates to <see langword="true" />.
+    /// </summary>
+    /// <param name="value">The current string.</param>
+    /// <param name="condition">The condition to evaluate.</param>
+    /// <param name="valueFactory">The function that returns the string to append if the condition is true.</param>
+    /// <returns>The concatenated string.</returns>
+    [Pure]
+    public static string? ConcatIf(this string? value, bool condition, Func<string?> valueFactory)
+    {
+        if (valueFactory is null)
+        {
+            throw new ArgumentNullException(nameof(valueFactory));
+        }
+
+        return condition ? value + valueFactory() : value;
+    }
+
+    /// <summary>
+    ///     Appends a string to the current string if the specified condition evaluates to <see langword="true" />.
+    /// </summary>
+    /// <param name="value">The current string.</param>
+    /// <param name="conditionFactory">The function that returns the condition to evaluate.</param>
+    /// <param name="valueFactory">The function that returns the string to append if the condition is true.</param>
+    /// <returns>The concatenated string.</returns>
+    /// <exception cref="ArgumentNullException"><paramref name="conditionFactory" /> is <see langword="null" />.</exception>
+    [Pure]
+    public static string? ConcatIf(this string? value, Func<bool> conditionFactory, Func<string?> valueFactory)
+    {
+        if (conditionFactory is null)
+        {
+            throw new ArgumentNullException(nameof(conditionFactory));
+        }
+
+        if (valueFactory is null)
+        {
+            throw new ArgumentNullException(nameof(valueFactory));
+        }
+
+        return conditionFactory() ? value + valueFactory() : value;
+    }
+
     /// <summary>
     ///     Counts the occurrences of a character within the current character span.
     /// </summary>