Merge branch 'master' into refactor/ceil

Author: alxkm

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

@@ -1,30 +1,48 @@
 package com.thealgorithms.maths;
 
-/*
- * Algorithm explanation:
- * https://technotip.com/6774/c-program-to-find-generic-root-of-a-number/#:~:text=Generic%20Root%3A%20of%20a%20number,get%20a%20single%2Ddigit%20output.&text=For%20Example%3A%20If%20user%20input,%2B%204%20%2B%205%20%3D%2015.
+/**
+ * Calculates the generic root (repeated digital sum) of a non-negative integer.
+ * <p>
+ * For example, the generic root of 12345 is calculated as:
+ * 1 + 2 + 3 + 4 + 5 = 15,
+ * then 1 + 5 = 6, so the generic root is 6.
+ * <p>
+ * Reference:
+ * https://technotip.com/6774/c-program-to-find-generic-root-of-a-number/
  */
 public final class GenericRoot {
+
+    private static final int BASE = 10;
+
     private GenericRoot() {
     }
 
-    private static int base = 10;
-
+    /**
+     * Computes the sum of the digits of a non-negative integer in base 10.
+     *
+     * @param n non-negative integer
+     * @return sum of digits of {@code n}
+     */
     private static int sumOfDigits(final int n) {
         assert n >= 0;
-        if (n < base) {
+        if (n < BASE) {
             return n;
         }
-        return n % base + sumOfDigits(n / base);
+        return (n % BASE) + sumOfDigits(n / BASE);
     }
 
+    /**
+     * Computes the generic root (repeated digital sum) of an integer.
+     * For negative inputs, the absolute value is used.
+     *
+     * @param n integer input
+     * @return generic root of {@code n}
+     */
     public static int genericRoot(final int n) {
-        if (n < 0) {
-            return genericRoot(-n);
-        }
-        if (n > base) {
-            return genericRoot(sumOfDigits(n));
+        int number = Math.abs(n);
+        if (number < BASE) {
+            return number;
         }
-        return n;
+        return genericRoot(sumOfDigits(number));
     }
 }

src/main/java/com/thealgorithms/misc/RangeInSortedArray.java

@@ -1,25 +1,46 @@
 package com.thealgorithms.misc;
 
+/**
+ * Utility class for operations to find the range of occurrences of a key
+ * in a sorted (non-decreasing) array, and to count elements less than or equal to a given key.
+ */
 public final class RangeInSortedArray {
+
     private RangeInSortedArray() {
     }
 
-    // Get the 1st and last occurrence index of a number 'key' in a non-decreasing array 'nums'
-    // Gives [-1, -1] in case element doesn't exist in array
+    /**
+     * Finds the first and last occurrence indices of the key in a sorted array.
+     *
+     * @param nums sorted array of integers (non-decreasing order)
+     * @param key the target value to search for
+     * @return int array of size two where
+     *         - index 0 is the first occurrence of key,
+     *         - index 1 is the last occurrence of key,
+     *         or [-1, -1] if the key does not exist in the array.
+     */
     public static int[] sortedRange(int[] nums, int key) {
         int[] range = new int[] {-1, -1};
-        alteredBinSearchIter(nums, key, 0, nums.length - 1, range, true);
-        alteredBinSearchIter(nums, key, 0, nums.length - 1, range, false);
+        alteredBinSearchIter(nums, key, 0, nums.length - 1, range, true); // find left boundary
+        alteredBinSearchIter(nums, key, 0, nums.length - 1, range, false); // find right boundary
         return range;
     }
 
-    // Recursive altered binary search which searches for leftmost as well as rightmost occurrence
-    // of 'key'
+    /**
+     * Recursive altered binary search to find either the leftmost or rightmost occurrence of a key.
+     *
+     * @param nums the sorted array
+     * @param key the target to find
+     * @param left current left bound in search
+     * @param right current right bound in search
+     * @param range array to update with boundaries: range[0] for leftmost, range[1] for rightmost
+     * @param goLeft if true, searches for leftmost occurrence; if false, for rightmost occurrence
+     */
     public static void alteredBinSearch(int[] nums, int key, int left, int right, int[] range, boolean goLeft) {
         if (left > right) {
             return;
         }
-        int mid = (left + right) >>> 1;
+        int mid = left + ((right - left) >>> 1);
         if (nums[mid] > key) {
             alteredBinSearch(nums, key, left, mid - 1, range, goLeft);
         } else if (nums[mid] < key) {
@@ -41,11 +62,19 @@ public static void alteredBinSearch(int[] nums, int key, int left, int right, in
         }
     }
 
-    // Iterative altered binary search which searches for leftmost as well as rightmost occurrence
-    // of 'key'
+    /**
+     * Iterative altered binary search to find either the leftmost or rightmost occurrence of a key.
+     *
+     * @param nums the sorted array
+     * @param key the target to find
+     * @param left initial left bound
+     * @param right initial right bound
+     * @param range array to update with boundaries: range[0] for leftmost, range[1] for rightmost
+     * @param goLeft if true, searches for leftmost occurrence; if false, for rightmost occurrence
+     */
     public static void alteredBinSearchIter(int[] nums, int key, int left, int right, int[] range, boolean goLeft) {
         while (left <= right) {
-            final int mid = (left + right) >>> 1;
+            int mid = left + ((right - left) >>> 1);
             if (nums[mid] > key) {
                 right = mid - 1;
             } else if (nums[mid] < key) {
@@ -55,33 +84,48 @@ public static void alteredBinSearchIter(int[] nums, int key, int left, int right
                     if (mid == 0 || nums[mid - 1] != key) {
                         range[0] = mid;
                         return;
-                    } else {
-                        right = mid - 1;
                     }
+                    right = mid - 1;
                 } else {
                     if (mid == nums.length - 1 || nums[mid + 1] != key) {
                         range[1] = mid;
                         return;
-                    } else {
-                        left = mid + 1;
                     }
+                    left = mid + 1;
                 }
             }
         }
     }
 
+    /**
+     * Counts the number of elements strictly less than the given key.
+     *
+     * @param nums sorted array
+     * @param key the key to compare
+     * @return the count of elements less than the key
+     */
     public static int getCountLessThan(int[] nums, int key) {
         return getLessThan(nums, key, 0, nums.length - 1);
     }
 
+    /**
+     * Helper method using binary search to count elements less than or equal to the key.
+     *
+     * @param nums sorted array
+     * @param key the key to compare
+     * @param left current left bound
+     * @param right current right bound
+     * @return count of elements less than or equal to the key
+     */
     public static int getLessThan(int[] nums, int key, int left, int right) {
         int count = 0;
         while (left <= right) {
-            final int mid = (left + right) >>> 1;
+            int mid = left + ((right - left) >>> 1);
             if (nums[mid] > key) {
                 right = mid - 1;
-            } else if (nums[mid] <= key) {
-                count = mid + 1; // At least mid+1 elements exist which are <= key
+            } else {
+                // nums[mid] <= key
+                count = mid + 1; // all elements from 0 to mid inclusive are <= key
                 left = mid + 1;
             }
         }

src/main/java/com/thealgorithms/stacks/InfixToPostfix.java

@@ -4,54 +4,96 @@
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 
+/**
+ * Utility class for converting an infix arithmetic expression
+ * into its equivalent postfix (Reverse Polish Notation) form.
+ * <p>
+ * This class provides a static method to perform the conversion,
+ * validating balanced brackets before processing.
+ * </p>
+ */
 public final class InfixToPostfix {
+
     private InfixToPostfix() {
     }
 
-    public static String infix2PostFix(String infixExpression) throws Exception {
+    /**
+     * Converts a given infix expression string to a postfix expression string.
+     * <p>
+     * The method first checks if the brackets in the input expression are balanced
+     * by calling {@code BalancedBrackets.isBalanced} on the filtered brackets.
+     * If the brackets are not balanced, it throws an IllegalArgumentException.
+     * </p>
+     * <p>
+     * Supported operators are: {@code +, -, *, /, ^}
+     * and operands can be letters or digits.
+     * </p>
+     *
+     * @param infixExpression the arithmetic expression in infix notation
+     * @return the equivalent postfix notation expression
+     * @throws IllegalArgumentException if the brackets in the expression are unbalanced
+     */
+    public static String infix2PostFix(String infixExpression) {
         if (!BalancedBrackets.isBalanced(filterBrackets(infixExpression))) {
-            throw new Exception("invalid expression");
+            throw new IllegalArgumentException("Invalid expression: unbalanced brackets.");
         }
+
         StringBuilder output = new StringBuilder();
-        Stack<Character> stack = new Stack<>();
-        for (char element : infixExpression.toCharArray()) {
-            if (Character.isLetterOrDigit(element)) {
-                output.append(element);
-            } else if (element == '(') {
-                stack.push(element);
-            } else if (element == ')') {
-                while (!stack.isEmpty() && stack.peek() != '(') {
-                    output.append(stack.pop());
+        Stack<Character> operatorStack = new Stack<>();
+
+        for (char token : infixExpression.toCharArray()) {
+            if (Character.isLetterOrDigit(token)) {
+                // Append operands (letters or digits) directly to output
+                output.append(token);
+            } else if (token == '(') {
+                // Push '(' to stack
+                operatorStack.push(token);
+            } else if (token == ')') {
+                // Pop and append until '(' is found
+                while (!operatorStack.isEmpty() && operatorStack.peek() != '(') {
+                    output.append(operatorStack.pop());
                 }
-                stack.pop();
+                operatorStack.pop(); // Remove '(' from stack
             } else {
-                while (!stack.isEmpty() && precedence(element) <= precedence(stack.peek())) {
-                    output.append(stack.pop());
+                // Pop operators with higher or equal precedence and append them
+                while (!operatorStack.isEmpty() && precedence(token) <= precedence(operatorStack.peek())) {
+                    output.append(operatorStack.pop());
                 }
-                stack.push(element);
+                operatorStack.push(token);
             }
         }
-        while (!stack.isEmpty()) {
-            output.append(stack.pop());
+
+        // Pop any remaining operators
+        while (!operatorStack.isEmpty()) {
+            output.append(operatorStack.pop());
         }
+
         return output.toString();
     }
 
+    /**
+     * Returns the precedence level of the given operator.
+     *
+     * @param operator the operator character (e.g., '+', '-', '*', '/', '^')
+     * @return the precedence value: higher means higher precedence,
+     *         or -1 if the character is not a recognized operator
+     */
     private static int precedence(char operator) {
-        switch (operator) {
-        case '+':
-        case '-':
-            return 0;
-        case '*':
-        case '/':
-            return 1;
-        case '^':
-            return 2;
-        default:
-            return -1;
-        }
+        return switch (operator) {
+            case '+', '-' -> 0;
+            case '*', '/' -> 1;
+            case '^' -> 2;
+            default -> -1;
+        };
     }
 
+    /**
+     * Extracts only the bracket characters from the input string.
+     * Supports parentheses (), curly braces {}, square brackets [], and angle brackets &lt;&gt;.
+     *
+     * @param input the original expression string
+     * @return a string containing only bracket characters from the input
+     */
     private static String filterBrackets(String input) {
         Pattern pattern = Pattern.compile("[^(){}\\[\\]<>]");
         Matcher matcher = pattern.matcher(input);