feat: functions to retain specific set of chars into a text (#280)

* feat: functions to retain specific set of chars into a text
* 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/RetainFunctionsTest.cs

@@ -0,0 +1,59 @@
+using Expressif.Functions.Text;
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Text;
+using System.Threading.Tasks;
+
+namespace Expressif.Testing.Functions.Text;
+
+public class RetainFunctionsTest
+{
+    [Test]
+    [TestCase("abc12345abc6789", "123456789")]
+    [TestCase("abc12345abc, 6789", "123456789")]
+    [TestCase("12345", "12345")]
+    [TestCase("-12,345.6", "123456")]
+    [TestCase("abc", "(empty)")]
+    [TestCase("(null)", "(null)")]
+    [TestCase("(empty)", "(empty)")]
+    [TestCase("(blank)", "(empty)")]
+    public void RetainNumeric_Valid(string value, string expected)
+       => Assert.That(new RetainNumeric().Evaluate(value), Is.EqualTo(expected));
+
+    [Test]
+    [TestCase("abc12345abc6789", "123456789")]
+    [TestCase("abc12345abc, 6789", "12345,6789")]
+    [TestCase("12345", "12345")]
+    [TestCase("-12,345.6", "-12,345.6")]
+    [TestCase("abc", "(empty)")]
+    [TestCase("(null)", "(null)")]
+    [TestCase("(empty)", "(empty)")]
+    [TestCase("(blank)", "(empty)")]
+    public void RetainNumericSymbol_Valid(string value, string expected)
+        => Assert.That(new RetainNumericSymbol().Evaluate(value), Is.EqualTo(expected));
+
+    [Test]
+    [TestCase("abc12345abc6789", "abcabc")]
+    [TestCase("abc12345abc, 6789", "abcabc")]
+    [TestCase("12345", "(empty)")]
+    [TestCase("-12,345.6", "(empty)")]
+    [TestCase("abc", "abc")]
+    [TestCase("(null)", "(null)")]
+    [TestCase("(empty)", "(empty)")]
+    [TestCase("(blank)", "(empty)")]
+    public void RetainAlpha_Valid(string value, string expected)
+        => Assert.That(new RetainAlpha().Evaluate(value), Is.EqualTo(expected));
+
+    [Test]
+    [TestCase("abc12345abc6789", "abc12345abc6789")]
+    [TestCase("abc12345abc, 6789", "abc12345abc6789")]
+    [TestCase("12345", "12345")]
+    [TestCase("-12,345.6", "123456")]
+    [TestCase("abc", "abc")]
+    [TestCase("(null)", "(null)")]
+    [TestCase("(empty)", "(empty)")]
+    [TestCase("(blank)", "(empty)")]
+    public void RetainAlphaNumeric_Valid(string value, string expected)
+        => Assert.That(new RetainAlphaNumeric().Evaluate(value), Is.EqualTo(expected));
+}

Expressif/Functions/Text/RetainFunctions.cs

@@ -0,0 +1,70 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Reflection;
+using System.Text;
+using System.Threading.Tasks;
+using Expressif.Values.Special;
+using Sprache;
+
+namespace Expressif.Functions.Text;
+public abstract class BaseTextRetain : BaseTextFunction
+{
+    protected override object? EvaluateBlank() => new Empty().Keyword;
+
+    protected override object? EvaluateString(string value)
+
+    {
+        Span<char> span = value.ToCharArray();
+        Span<char> result = stackalloc char[value.Length];
+        int index = 0;
+
+        foreach (var c in span)
+            if (IsRetainable(c))
+                result[index++] = c;
+
+        if (index == 0)
+            return new Empty().Keyword;
+
+        return new string(result.Slice(0, index));
+    }
+
+    protected abstract bool IsRetainable(char c);
+}
+
+/// <summary>
+/// Returns the input string with all non-numeric characters removed, leaving only digits (0-9).. If the argument is `null`, it returns `null`.
+/// </summary>
+public class RetainNumeric : BaseTextRetain
+{
+    protected override bool IsRetainable(char c)
+        => char.IsDigit(c);
+}
+
+/// <summary>
+/// Returns the input string with all characters removed except for digits (0-9) and the symbols `+`, `-`, `,` and `.` If the argument is `null`, it returns `null`.
+/// </summary>
+public class RetainNumericSymbol : RetainNumeric
+{
+    protected override bool IsRetainable(char c)
+        => base.IsRetainable(c) || c.Equals('+') || c.Equals('-') || c.Equals('.') || c.Equals(',');
+}
+
+/// <summary>
+/// Returns the input string with all characters removed except for letters (A-Z, a-z). If the argument is `null`, it returns `null`.
+/// </summary>
+public class RetainAlpha : BaseTextRetain
+{
+    protected override bool IsRetainable(char c)
+        => char.IsLetter(c);
+}
+
+
+/// <summary>
+/// Returns the input string with all characters removed except for letters (A-Z, a-z) and digits (0-9). If the argument is `null`, it returns `null`.
+/// </summary>
+public class RetainAlphaNumeric : BaseTextRetain
+{
+    protected override bool IsRetainable(char c)
+        => char.IsLetterOrDigit(c);
+}

README.md

@@ -314,6 +314,10 @@ Install-Package Expressif
 |Text     | remove-chars               | text-to-remove-chars                                                             |
 |Text     | replace-chars              | text-to-replace-chars                                                            |
 |Text     | replace-slice              | text-to-replace-slice                                                            |
+|Text     | retain-alpha               | text-to-retain-alpha                                                             |
+|Text     | retain-alpha-numeric       | text-to-retain-alpha-numeric                                                     |
+|Text     | retain-numeric             | text-to-retain-numeric                                                           |
+|Text     | retain-numeric-symbol      | text-to-retain-numeric-symbol                                                    |
 |Text     | skip-first-chars           | text-to-skip-first-chars                                                         |
 |Text     | skip-last-chars            | text-to-skip-last-chars                                                          |
 |Text     | suffix                     | text-to-suffix                                                                   |