feat: function to filter a text on a list of chars (#224)

* feat: function to filter a text on a list of chars
* Update the automatically generated documentation related to the list of functions and predicates

---------

Co-authored-by: AppVeyor bot <no-reply@nbiguity.io>

Expressif.Testing/Functions/Text/CharFunctionsTest.cs

@@ -32,4 +32,27 @@ public void RemoveChars_Valid(string value, char charToRemove, string expected)
     public void ReplaceChars_Valid(string value, char charToReplace, char replacingChar, string expected)
         => Assert.That(new ReplaceChars(() => charToReplace, () => replacingChar).Evaluate(value)
             , Is.EqualTo(expected));
+
+
+    [Test]
+    [TestCase("12345678", new[] { '2', '8', '4' }, "248")]
+    [TestCase("12314561789", new[] { '2', '1', '4' }, "12141")]
+    [TestCase("(null)", new[] { '2', '1', '4' }, "(null)")]
+    [TestCase("(empty)", new[] { '2', '1', '4' }, "(empty)")]
+    [TestCase("(blank)", new[] { '2', '1', '4' }, "(blank)")]
+    [TestCase("(blank)", new[] { '2', '1', '4' }, "(blank)")]
+    public void FilterChars_Chars_Valid(string value, char[] filter, string expected)
+        => Assert.That(new FilterChars(() => filter).Evaluate(value)
+            , Is.EqualTo(expected));
+
+    [Test]
+    [TestCase("12345678", "284", "248")]
+    [TestCase("12314561789", "214", "12141")]
+    [TestCase("(null)", "214", "(null)")]
+    [TestCase("(empty)", "214", "(empty)")]
+    [TestCase("(blank)", "214", "(blank)")]
+    [TestCase("(blank)", "214", "(blank)")]
+    public void FilterChars_String_Valid(string value, string filter, string expected)
+        => Assert.That(new FilterChars(() => filter).Evaluate(value)
+            , Is.EqualTo(expected));
 }

Expressif/Functions/Text/CharFunctions.cs

@@ -66,3 +66,37 @@ protected override object EvaluateString(string value)
     protected override object EvaluateBlank()
         => new Whitespace().Keyword;
 }
+
+
+/// <summary>
+/// Returns only those characters specified in the parameter, in the order, they were originally entered in the input value.
+/// </summary>
+public class FilterChars : BaseTextFunction
+{
+    public Func<char[]> Filter { get; }
+
+    /// <param name="filter">The chars to filter from the argument string.</param>
+    public FilterChars(Func<char[]> filter)
+        => (Filter) = (filter);
+
+    /// <param name="filter">The string containing the chars to filter from the argument string.</param>
+    public FilterChars(Func<string> filter)
+    {
+        static Func<char[]> toCharArray(string str) => str.ToCharArray;
+        Filter = toCharArray(filter.Invoke());
+    }
+
+    protected override object EvaluateString(string value)
+    {
+        var filter = Filter.Invoke();
+
+        var stringBuilder = new StringBuilder();
+        foreach (var c in value)
+            if (filter.Contains(c))
+                stringBuilder.Append(c);
+        return stringBuilder.ToString();
+    }
+
+    protected override object EvaluateBlank()
+        => new Whitespace().Keyword;
+}

README.md

@@ -292,6 +292,7 @@ Install-Package Expressif
 |Text     | count-distinct-chars       | text-to-count-distinct-chars                                                     |
 |Text     | count-substring            | text-to-count-substring                                                          |
 |Text     | empty-to-null              |                                                                                  |
+|Text     | filter-chars               | text-to-filter-chars                                                             |
 |Text     | first-chars                | text-to-first-chars                                                              |
 |Text     | html-to-text               |                                                                                  |
 |Text     | last-chars                 | text-to-last-chars                                                               |