From 6d3da377d61314b27cf948592b1c6f7e63bd2819 Mon Sep 17 00:00:00 2001 From: Papichardog Date: Thu, 9 Apr 2026 20:20:14 -0600 Subject: [PATCH 1/5] docs(maths): improve JavaDoc for Average utility class --- .../java/com/thealgorithms/maths/Average.java | 30 ++++++++++++------- 1 file changed, 20 insertions(+), 10 deletions(-) diff --git a/src/main/java/com/thealgorithms/maths/Average.java b/src/main/java/com/thealgorithms/maths/Average.java index a550a7f6504d..5ca2b6ab173d 100644 --- a/src/main/java/com/thealgorithms/maths/Average.java +++ b/src/main/java/com/thealgorithms/maths/Average.java @@ -2,8 +2,12 @@ /** * 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 +17,14 @@ private Average() { } /** - * Computes the average of a {@code double} array. + * Computes the arithmetic mean of a {@code double} array. * - * @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 + *

The average is calculated as the sum of all elements divided + * by the number of elements: {@code avg = Σ(numbers[i]) / n}. + * + * @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 +38,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) { From 28468364568f9fa642e2c798974d7439113c38b4 Mon Sep 17 00:00:00 2001 From: Papichardog Date: Thu, 9 Apr 2026 20:30:13 -0600 Subject: [PATCH 2/5] feat(maths): add stream-based averageStream method and validations --- .../java/com/thealgorithms/maths/Average.java | 31 ++++++++++++++++--- 1 file changed, 27 insertions(+), 4 deletions(-) diff --git a/src/main/java/com/thealgorithms/maths/Average.java b/src/main/java/com/thealgorithms/maths/Average.java index 5ca2b6ab173d..5ee95a544cd2 100644 --- a/src/main/java/com/thealgorithms/maths/Average.java +++ b/src/main/java/com/thealgorithms/maths/Average.java @@ -1,5 +1,8 @@ package com.thealgorithms.maths; +import java.util.Arrays; +import java.util.OptionalDouble; + /** * A utility class for computing the average of numeric arrays. * @@ -13,7 +16,8 @@ public final class Average { // Prevent instantiation of this utility class private Average() { - throw new UnsupportedOperationException("This is a utility class and cannot be instantiated."); + throw new UnsupportedOperationException( + "This is a utility class and cannot be instantiated."); } /** @@ -28,7 +32,8 @@ private Average() { */ public static double average(double[] numbers) { if (numbers == null || numbers.length == 0) { - throw new IllegalArgumentException("Numbers array cannot be empty or null"); + throw new IllegalArgumentException( + "Numbers array cannot be empty or null"); } double sum = 0; for (double number : numbers) { @@ -49,7 +54,8 @@ public static double average(double[] numbers) { */ public static long average(int[] numbers) { if (numbers == null || numbers.length == 0) { - throw new IllegalArgumentException("Numbers array cannot be empty or null"); + throw new IllegalArgumentException( + "Numbers array cannot be empty or null"); } long sum = 0; for (int number : numbers) { @@ -57,4 +63,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(); + } +} \ No newline at end of file From 14b90573f86f86744be69727e13410dec372d5ca Mon Sep 17 00:00:00 2001 From: Papichardog Date: Thu, 9 Apr 2026 21:09:03 -0600 Subject: [PATCH 3/5] style: fix formatting --- src/main/java/com/thealgorithms/maths/Average.java | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/src/main/java/com/thealgorithms/maths/Average.java b/src/main/java/com/thealgorithms/maths/Average.java index 5ee95a544cd2..9495330fd827 100644 --- a/src/main/java/com/thealgorithms/maths/Average.java +++ b/src/main/java/com/thealgorithms/maths/Average.java @@ -16,8 +16,7 @@ public final class Average { // Prevent instantiation of this utility class private Average() { - throw new UnsupportedOperationException( - "This is a utility class and cannot be instantiated."); + throw new UnsupportedOperationException("This is a utility class and cannot be instantiated."); } /** @@ -32,8 +31,7 @@ private Average() { */ public static double average(double[] numbers) { if (numbers == null || numbers.length == 0) { - throw new IllegalArgumentException( - "Numbers array cannot be empty or null"); + throw new IllegalArgumentException("Numbers array cannot be empty or null"); } double sum = 0; for (double number : numbers) { @@ -54,8 +52,7 @@ public static double average(double[] numbers) { */ public static long average(int[] numbers) { if (numbers == null || numbers.length == 0) { - throw new IllegalArgumentException( - "Numbers array cannot be empty or null"); + throw new IllegalArgumentException("Numbers array cannot be empty or null"); } long sum = 0; for (int number : numbers) { From 149e07bfbffa64d2ef37dff4763c7883dfc80e5d Mon Sep 17 00:00:00 2001 From: Papichardog Date: Thu, 9 Apr 2026 21:40:12 -0600 Subject: [PATCH 4/5] style: final formatting fix for CI checks --- src/main/java/com/thealgorithms/maths/Average.java | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/main/java/com/thealgorithms/maths/Average.java b/src/main/java/com/thealgorithms/maths/Average.java index 9495330fd827..914814a92507 100644 --- a/src/main/java/com/thealgorithms/maths/Average.java +++ b/src/main/java/com/thealgorithms/maths/Average.java @@ -30,7 +30,7 @@ private Average() { * @throws IllegalArgumentException if {@code numbers} is {@code null} or empty */ public static double average(double[] numbers) { - if (numbers == null || numbers.length == 0) { + if (numbers==null || numbers.length==0) { throw new IllegalArgumentException("Numbers array cannot be empty or null"); } double sum = 0; @@ -51,7 +51,7 @@ public static double average(double[] numbers) { * @throws IllegalArgumentException if {@code numbers} is {@code null} or empty */ public static long average(int[] numbers) { - if (numbers == null || numbers.length == 0) { + if (numbers==null || numbers.length==0) { throw new IllegalArgumentException("Numbers array cannot be empty or null"); } long sum = 0; @@ -72,7 +72,7 @@ public static long average(int[] numbers) { * @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) { + if (numbers==null || numbers.length==0) { return OptionalDouble.empty(); } return Arrays.stream(numbers).average(); From a93fca01e8a9322a3989148ebd5a9e062d2ae170 Mon Sep 17 00:00:00 2001 From: Papichardog Date: Fri, 10 Apr 2026 00:18:44 -0600 Subject: [PATCH 5/5] style: apply official clang-format to Average.java --- src/main/java/com/thealgorithms/maths/Average.java | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/main/java/com/thealgorithms/maths/Average.java b/src/main/java/com/thealgorithms/maths/Average.java index 914814a92507..cf55af509ccc 100644 --- a/src/main/java/com/thealgorithms/maths/Average.java +++ b/src/main/java/com/thealgorithms/maths/Average.java @@ -30,7 +30,7 @@ private Average() { * @throws IllegalArgumentException if {@code numbers} is {@code null} or empty */ public static double average(double[] numbers) { - if (numbers==null || numbers.length==0) { + if (numbers == null || numbers.length == 0) { throw new IllegalArgumentException("Numbers array cannot be empty or null"); } double sum = 0; @@ -51,7 +51,7 @@ public static double average(double[] numbers) { * @throws IllegalArgumentException if {@code numbers} is {@code null} or empty */ public static long average(int[] numbers) { - if (numbers==null || numbers.length==0) { + if (numbers == null || numbers.length == 0) { throw new IllegalArgumentException("Numbers array cannot be empty or null"); } long sum = 0; @@ -72,9 +72,9 @@ public static long average(int[] numbers) { * @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) { + if (numbers == null || numbers.length == 0) { return OptionalDouble.empty(); } return Arrays.stream(numbers).average(); } -} \ No newline at end of file +}