Adds new function AVERAGE (#468)

docs/references/functions.md

@@ -14,6 +14,7 @@ Available through the _ExpressionConfiguration.StandardFunctionsDictionary_ cons
 | Name                                       | Description                                                                                                                |
 |--------------------------------------------|----------------------------------------------------------------------------------------------------------------------------|
 | ABS(value)                                 | Absolute (non-negative) value                                                                                              |
+| AVERAGE(value, ...)                        | Returns the average (arithmetic mean) of all parameters.                                                                   |
 | CEILING(value)                             | Rounds the given value an integer using the rounding mode CEILING                                                          |
 | COALESCE(value, ...)                       | Returns the first non-null parameter, or NULL if all parameters are null                                                   |
 | FACT(base)                                 | Calculates the factorial of a base value                                                                                   |

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

@@ -129,6 +129,7 @@ public class ExpressionConfiguration {
       MapBasedFunctionDictionary.ofFunctions(
           // basic functions
           Map.entry("ABS", new AbsFunction()),
+          Map.entry("AVERAGE", new AverageFunction()),
           Map.entry("CEILING", new CeilingFunction()),
           Map.entry("COALESCE", new CoalesceFunction()),
           Map.entry("FACT", new FactFunction()),

src/main/java/com/ezylang/evalex/functions/basic/AverageFunction.java

@@ -0,0 +1,46 @@
+/*
+  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.basic;
+
+import com.ezylang.evalex.Expression;
+import com.ezylang.evalex.data.EvaluationValue;
+import com.ezylang.evalex.functions.FunctionParameter;
+import com.ezylang.evalex.parser.Token;
+import java.math.BigDecimal;
+import java.math.MathContext;
+import java.util.Arrays;
+
+/**
+ * Returns the average (arithmetic mean) of the numeric arguments.
+ *
+ * @author oswaldo.bapvic.jr
+ */
+@FunctionParameter(name = "firstValue")
+@FunctionParameter(name = "additionalValues", isVarArg = true)
+public class AverageFunction extends AbstractMinMaxFunction {
+  @Override
+  public EvaluationValue evaluate(
+      Expression expression, Token functionToken, EvaluationValue... parameterValues) {
+    MathContext mathContext = expression.getConfiguration().getMathContext();
+    BigDecimal sum =
+        Arrays.stream(parameterValues)
+            .map(EvaluationValue::getNumberValue)
+            .reduce(BigDecimal.ZERO, BigDecimal::add);
+    BigDecimal count = BigDecimal.valueOf(parameterValues.length);
+    BigDecimal average = sum.divide(count, mathContext);
+    return expression.convertValue(average);
+  }
+}

src/test/java/com/ezylang/evalex/functions/basic/BasicFunctionsTest.java

@@ -362,4 +362,30 @@ void testCoalesce(String expression, String expectedResult)
       assertThat(evaluationValue.getStringValue()).isEqualTo(expectedResult);
     }
   }
+
+  @ParameterizedTest
+  @CsvSource(
+      delimiter = ':',
+      value = {
+        "AVERAGE(99) : 99",
+        "AVERAGE(1,2) : 1.5",
+        "AVERAGE(1,3) : 2",
+        "AVERAGE(1.999,2) : 1.9995",
+        "AVERAGE(-5,0,5) : 0",
+        "AVERAGE(10,15,32) : 19",
+        "AVERAGE(7,9,27,2) : 11.25",
+        "AVERAGE(7,9,27,2,5) : 10",
+        "AVERAGE(-7,-9,-27,-2,-5) : -10"
+      })
+  void testAverage(String expression, String expectedResult)
+      throws EvaluationException, ParseException {
+    assertExpressionHasExpectedResult(expression, expectedResult);
+  }
+
+  @Test
+  void testAverageThrowsException() {
+    assertThatThrownBy(() -> new Expression("AVERAGE()").evaluate())
+        .isInstanceOf(ParseException.class)
+        .hasMessage("Not enough parameters for function");
+  }
 }