add STR_SUBSTRING

docs/references/functions.md

@@ -33,17 +33,18 @@ Available through the _ExpressionConfiguration.StandardFunctionsDictionary_ cons
 
 ### String Functions
 
-| Name                                | Description                                                                                             |
-|-------------------------------------|---------------------------------------------------------------------------------------------------------|
-| STR_CONTAINS(string, substring)     | Returns true if the string contains the substring (case-insensitive)                                    |
-| STR_ENDS_WITH(string, substring)    | Returns true if the string ends with the substring (case-sensitive)                                     |
-| STR_FORMAT(format [,argument, ...]) | Returns a formatted string using the specified format string and arguments, using the configured locale |
-| STR_LOWER(value)                    | Converts the given value to lower case                                                                  |
-| STR_STARTS_WITH(string, substring)  | Returns true if the string starts with the substring (case-sensitive)                                   |
-| STR_TRIM(string)                    | Returns the given string with all leading and trailing space removed.                                   |
-| STR_UPPER(value)                    | Converts the given value to upper case                                                                  |
-| STR_LENGTH(string)                  | Returns the length of the string                                                                        |
-| STR_MATCHES(string, pattern)        | Returns true if the string matches the RegEx pattern                                                    |
+| Name                                | Description                                                                                                                                   |
+|-------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------|
+| STR_CONTAINS(string, substring)     | Returns true if the string contains the substring (case-insensitive)                                                                          |
+| STR_ENDS_WITH(string, substring)    | Returns true if the string ends with the substring (case-sensitive)                                                                           |
+| STR_FORMAT(format [,argument, ...]) | Returns a formatted string using the specified format string and arguments, using the configured locale                                       |
+| STR_LOWER(value)                    | Converts the given value to lower case                                                                                                        |
+| STR_STARTS_WITH(string, substring)  | Returns true if the string starts with the substring (case-sensitive)                                                                         |
+| STR_TRIM(string)                    | Returns the given string with all leading and trailing space removed.                                                                         |
+| STR_UPPER(value)                    | Converts the given value to upper case                                                                                                        |
+| STR_LENGTH(string)                  | Returns the length of the string                                                                                                              |
+| STR_MATCHES(string, pattern)        | Returns true if the string matches the RegEx pattern                                                                                          |
+| STR_SUBSTRING(string, start[, end]) | Returns a substring of the given string, starting at the _start_ index and ending at the _end_ index (the end of the string if not specified) |
 
 ### Trigonometric Functions
 

src/main/java/com/ezylang/evalex/config/ExpressionConfiguration.java

@@ -189,6 +189,7 @@ public class ExpressionConfiguration {
           Map.entry("STR_UPPER", new StringUpperFunction()),
           Map.entry("STR_LENGTH", new StringLengthFunction()),
           Map.entry("STR_MATCHES", new StringMatchesFunction()),
+          Map.entry("STR_SUBSTRING", new StringSubstringFunction()),
           // date time functions
           Map.entry("DT_DATE_NEW", new DateTimeNewFunction()),
           Map.entry("DT_DATE_PARSE", new DateTimeParseFunction()),

src/main/java/com/ezylang/evalex/functions/string/StringSubstringFunction.java

@@ -0,0 +1,64 @@
+/*
+  Copyright 2012-2024 Udo Klimaschewski
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+package com.ezylang.evalex.functions.string;
+
+import com.ezylang.evalex.EvaluationException;
+import com.ezylang.evalex.Expression;
+import com.ezylang.evalex.data.EvaluationValue;
+import com.ezylang.evalex.functions.AbstractFunction;
+import com.ezylang.evalex.functions.FunctionParameter;
+import com.ezylang.evalex.parser.Token;
+
+/**
+ * Returns a substring of a string.
+ *
+ * @author HSGamer
+ */
+@FunctionParameter(name = "string")
+@FunctionParameter(name = "start", nonNegative = true)
+@FunctionParameter(name = "end", isVarArg = true, nonNegative = true)
+public class StringSubstringFunction extends AbstractFunction {
+  @Override
+  public void validatePreEvaluation(Token token, EvaluationValue... parameterValues)
+      throws EvaluationException {
+    super.validatePreEvaluation(token, parameterValues);
+    if (parameterValues.length > 2) {
+      if (parameterValues[2].getNumberValue().intValue()
+          < parameterValues[1].getNumberValue().intValue()) {
+        throw new EvaluationException(
+            token, "End index must be greater than or equal to start index");
+      }
+    }
+  }
+
+  @Override
+  public EvaluationValue evaluate(
+      Expression expression, Token functionToken, EvaluationValue... parameterValues)
+      throws EvaluationException {
+    String string = parameterValues[0].getStringValue();
+    int start = parameterValues[1].getNumberValue().intValue();
+    String result;
+    if (parameterValues.length > 2) {
+      int end = parameterValues[2].getNumberValue().intValue();
+      int length = string.length();
+      int finalEnd = Math.min(end, length);
+      result = string.substring(start, finalEnd);
+    } else {
+      result = string.substring(start);
+    }
+    return expression.convertValue(result);
+  }
+}

src/test/java/com/ezylang/evalex/functions/string/StringFunctionsTest.java

@@ -15,10 +15,13 @@
 */
 package com.ezylang.evalex.functions.string;
 
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
 import com.ezylang.evalex.BaseEvaluationTest;
 import com.ezylang.evalex.EvaluationException;
 import com.ezylang.evalex.config.TestConfigurationProvider;
 import com.ezylang.evalex.parser.ParseException;
+import org.junit.jupiter.api.Test;
 import org.junit.jupiter.params.ParameterizedTest;
 import org.junit.jupiter.params.provider.CsvSource;
 
@@ -198,4 +201,29 @@ void testMatches(String expression, String expectedResult)
       throws EvaluationException, ParseException {
     assertExpressionHasExpectedResult(expression, expectedResult);
   }
+
+  @ParameterizedTest
+  @CsvSource(
+      delimiter = ':',
+      value = {
+        "STR_SUBSTRING(\"\", 0, 0) : ''",
+        "STR_SUBSTRING(\"Hello World\", 0) : Hello World",
+        "STR_SUBSTRING(\"Hello World\", 6) : World",
+        "STR_SUBSTRING(\"Hello World\", 0, 5) : Hello",
+        "STR_SUBSTRING(\"Hello World\", 6, 11) : World",
+        "STR_SUBSTRING(\"Hello World\", 6, 6) : ''",
+        "STR_SUBSTRING(\"Hello World\", 0, 11) : Hello World",
+        "STR_SUBSTRING(\"Hello World\", 0, 12) : Hello World",
+      })
+  void testSubstring(String expression, String expectedResult)
+      throws EvaluationException, ParseException {
+    assertExpressionHasExpectedResult(expression, expectedResult);
+  }
+
+  @Test
+  void testSubstringEndLessThanStart() {
+    assertThatThrownBy(() -> evaluate("STR_SUBSTRING(\"Hello World\", 6, 5)"))
+        .isInstanceOf(EvaluationException.class)
+        .hasMessage("End index must be greater than or equal to start index");
+  }
 }