Add String.First/Last helpers and fix Split for multi-char separators (#135)

Fix String.Split to correctly handle multi-character separators like "<br />".
Previously, it would split on each individual character rather than the
whole string.

Add String.First and String.Last helpers to extract the first or last
element from an array/collection. These can be composed with Split:

  {{String.First (String.Split yourField "<br />")}}

Changes:
- Fix Split to use string[] overload instead of char[] for multi-char separators
- Add First(IEnumerable<object?>) returning the first element
- Add Last(IEnumerable<object?>) returning the last element
- Add unit and template tests for all changes
- Update CHANGELOG for 2.5.4

Author: ablyler

CHANGELOG.md

@@ -1,3 +1,8 @@
+# 2.5.4 (TBD)
+- Fix String.Split to correctly handle multi-character separators (e.g., `"<br />"` now splits on the whole string instead of each character) [bug]
+- Add String.First helper to get the first element from an array/collection [enhancement]
+- Add String.Last helper to get the last element from an array/collection [enhancement]
+
 # 2.5.3 (13 September 2025)
 - [#132](https://github.com/Handlebars-Net/Handlebars.Net.Helpers/pull/132) - Humanizer Truncate should always be used as &quot;Humanizer.Truncate&quot; [bug] contributed by [StefH](https://github.com/StefH)
 - [#133](https://github.com/Handlebars-Net/Handlebars.Net.Helpers/pull/133) - Fix SonarCloud [enhancement] contributed by [StefH](https://github.com/StefH)

src/Handlebars.Net.Helpers/Helpers/StringHelpers.cs

@@ -1,5 +1,6 @@
 using System;
 using System.Collections;
+using System.Collections.Generic;
 using System.Linq;
 using System.Text;
 using HandlebarsDotNet.Helpers.Attributes;
@@ -342,13 +343,35 @@ public string Reverse(string value)
         return new string(value.ToCharArray().Reverse().ToArray());
     }
 
+    [HandlebarsWriter(WriterType.Value)]
+    public object? First(IEnumerable<object?> values)
+    {
+        if (values is null)
+        {
+            throw new ArgumentNullException(nameof(values));
+        }
+
+        return values.FirstOrDefault();
+    }
+
+    [HandlebarsWriter(WriterType.Value)]
+    public object? Last(IEnumerable<object?> values)
+    {
+        if (values is null)
+        {
+            throw new ArgumentNullException(nameof(values));
+        }
+
+        return values.LastOrDefault();
+    }
+
     [HandlebarsWriter(WriterType.Value)]
     public string[] Split(string value, string separator)
     {
         Guard.NotNull(value);
         Guard.NotNull(separator);
 
-        return separator.Length == 1 ? value.Split(separator[0]) : value.Split(separator.ToCharArray(), StringSplitOptions.RemoveEmptyEntries);
+        return value.Split(new[] { separator }, StringSplitOptions.None);
     }
 
     [HandlebarsWriter(WriterType.Value)]

test/Handlebars.Net.Helpers.Tests/Helpers/StringHelpersTests.cs

@@ -598,4 +598,90 @@ public void Substring_3params_Exceptions(string value, int start, int end)
         // Assert
         action.Should().Throw<ArgumentException>();
     }
+
+    [Theory]
+    [InlineData("a;b;c", ";", new[] { "a", "b", "c" })]
+    [InlineData("a<br />b<br />c", "<br />", new[] { "a", "b", "c" })]
+    [InlineData("Honors Algebra 2<br /><br />More text", "<br />", new[] { "Honors Algebra 2", "", "More text" })]
+    [InlineData("no separator here", ";", new[] { "no separator here" })]
+    public void Split(string value, string separator, string[] expected)
+    {
+        // Act
+        var result = _sut.Split(value, separator);
+
+        // Assert
+        result.Should().BeEquivalentTo(expected);
+    }
+
+    [Fact]
+    public void First_ReturnsFirstElement()
+    {
+        // Arrange
+        var values = new object[] { "first", "second", "third" };
+
+        // Act
+        var result = _sut.First(values);
+
+        // Assert
+        result.Should().Be("first");
+    }
+
+    [Fact]
+    public void First_ReturnsNullForEmptyCollection()
+    {
+        // Arrange
+        var values = Array.Empty<object>();
+
+        // Act
+        var result = _sut.First(values);
+
+        // Assert
+        result.Should().BeNull();
+    }
+
+    [Fact]
+    public void First_ThrowsForNullCollection()
+    {
+        // Act
+        Action action = () => _sut.First(null!);
+
+        // Assert
+        action.Should().Throw<ArgumentNullException>();
+    }
+
+    [Fact]
+    public void Last_ReturnsLastElement()
+    {
+        // Arrange
+        var values = new object[] { "first", "second", "third" };
+
+        // Act
+        var result = _sut.Last(values);
+
+        // Assert
+        result.Should().Be("third");
+    }
+
+    [Fact]
+    public void Last_ReturnsNullForEmptyCollection()
+    {
+        // Arrange
+        var values = Array.Empty<object>();
+
+        // Act
+        var result = _sut.Last(values);
+
+        // Assert
+        result.Should().BeNull();
+    }
+
+    [Fact]
+    public void Last_ThrowsForNullCollection()
+    {
+        // Act
+        Action action = () => _sut.Last(null!);
+
+        // Assert
+        action.Should().Throw<ArgumentNullException>();
+    }
 }

test/Handlebars.Net.Helpers.Tests/Templates/StringHelpersTemplateTests.cs

@@ -596,4 +596,52 @@ public void FormatAsString_Template_Now()
         decodeResult.Should().BeTrue();
         decoded.Should().Be("test 2020-Apr-15 abc");
     }
+
+    [Theory]
+    [InlineData("{{String.First (String.Split \"a<br />b<br />c\" \"<br />\")}}", "a")]
+    [InlineData("{{String.First (String.Split \"Honors Algebra 2<br /><br />More text\" \"<br />\")}}", "Honors Algebra 2")]
+    [InlineData("{{String.First (String.Split \"single\" \";\")}}", "single")]
+    public void FirstWithSplit(string template, string expected)
+    {
+        // Arrange
+        var action = _handlebarsContext.Compile(template);
+
+        // Act
+        var result = action("");
+
+        // Assert
+        result.Should().Be(expected);
+    }
+
+    [Theory]
+    [InlineData("{{String.Last (String.Split \"a<br />b<br />c\" \"<br />\")}}", "c")]
+    [InlineData("{{String.Last (String.Split \"single\" \";\")}}", "single")]
+    public void LastWithSplit(string template, string expected)
+    {
+        // Arrange
+        var action = _handlebarsContext.Compile(template);
+
+        // Act
+        var result = action("");
+
+        // Assert
+        result.Should().Be(expected);
+    }
+
+    [Fact]
+    public void FirstWithSplit_FromModel()
+    {
+        // Arrange
+        var model = new
+        {
+            yourField = "Honors Algebra 2<br /><br /><span style=\"background-color: #fbeeb8;\"><strong>Textbook<br /></strong>Algebra and Trigonometry</span>"
+        };
+        var action = _handlebarsContext.Compile("{{String.First (String.Split yourField \"<br />\")}}");
+
+        // Act
+        var result = action(model);
+
+        // Assert
+        result.Should().Be("Honors Algebra 2");
+    }
 }