diff --git a/src/main/java/com/thealgorithms/maths/Average.java b/src/main/java/com/thealgorithms/maths/Average.java index a550a7f6504d..cf55af509ccc 100644 --- a/src/main/java/com/thealgorithms/maths/Average.java +++ b/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. + * + *
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. + * + *
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. + * + *
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. + * + *
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. + * + *
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(); + } }