feat(maths): enhance Average with stream method and improved JavaDoc

src/main/java/com/thealgorithms/maths/Average.java

@@ -1,9 +1,16 @@
 package com.thealgorithms.maths;
 
+import java.util.Arrays;
+import java.util.OptionalDouble;
+
 /**
  * A utility class for computing the average of numeric arrays.
- * This class provides static methods to calculate the average of arrays
- * of both {@code double} and {@code int} values.
+ *
+ * <p>This class provides static methods to calculate the arithmetic mean
+ * of arrays of both {@code double} and {@code int} values. It also offers
+ * a Stream-based alternative for modern, declarative usage.
+ *
+ * <p>All methods guard against {@code null} or empty inputs.
  */
 public final class Average {
 
@@ -13,11 +20,14 @@ private Average() {
     }
 
     /**
-     * Computes the average of a {@code double} array.
+     * Computes the arithmetic mean of a {@code double} array.
+     *
+     * <p>The average is calculated as the sum of all elements divided
+     * by the number of elements: {@code avg = Σ(numbers[i]) / n}.
      *
-     * @param numbers an array of {@code double} values
-     * @return the average of the given numbers
-     * @throws IllegalArgumentException if the input array is {@code null} or empty
+     * @param numbers a non-null, non-empty array of {@code double} values
+     * @return the arithmetic mean of the given numbers
+     * @throws IllegalArgumentException if {@code numbers} is {@code null} or empty
      */
     public static double average(double[] numbers) {
         if (numbers == null || numbers.length == 0) {
@@ -31,11 +41,14 @@ public static double average(double[] numbers) {
     }
 
     /**
-     * Computes the average of an {@code int} array.
+     * Computes the arithmetic mean of an {@code int} array.
+     *
+     * <p>The sum is accumulated in a {@code long} to prevent integer overflow
+     * when processing large arrays or large values.
      *
-     * @param numbers an array of {@code int} values
-     * @return the average of the given numbers
-     * @throws IllegalArgumentException if the input array is {@code null} or empty
+     * @param numbers a non-null, non-empty array of {@code int} values
+     * @return the arithmetic mean as a {@code long} (truncated toward zero)
+     * @throws IllegalArgumentException if {@code numbers} is {@code null} or empty
      */
     public static long average(int[] numbers) {
         if (numbers == null || numbers.length == 0) {
@@ -47,4 +60,21 @@ public static long average(int[] numbers) {
         }
         return sum / numbers.length;
     }
+
+    /**
+     * Computes the arithmetic mean of a {@code double} array using Java Streams.
+     *
+     * <p>This method is a declarative alternative to {@link #average(double[])}.
+     * Instead of throwing on empty input, it returns an empty {@link OptionalDouble},
+     * following the convention of the Stream API.
+     *
+     * @param numbers an array of {@code double} values, may be {@code null} or empty
+     * @return an {@link OptionalDouble} with the mean, or empty if input is null/empty
+     */
+    public static OptionalDouble averageStream(double[] numbers) {
+        if (numbers == null || numbers.length == 0) {
+            return OptionalDouble.empty();
+        }
+        return Arrays.stream(numbers).average();
+    }
 }