Merge branch 'master' into master

Author: gopaljilab

pom.xml

@@ -42,7 +42,7 @@
         <dependency>
             <groupId>org.mockito</groupId>
             <artifactId>mockito-core</artifactId>
-            <version>5.20.0</version>
+            <version>5.21.0</version>
             <scope>test</scope>
         </dependency>
         <dependency>
@@ -127,7 +127,7 @@
                         <plugin>
                             <groupId>com.mebigfatguy.fb-contrib</groupId>
                             <artifactId>fb-contrib</artifactId>
-                            <version>7.7.1</version>
+                            <version>7.7.2</version>
                         </plugin>
                         <plugin>
                             <groupId>com.h3xstream.findsecbugs</groupId>

src/main/java/com/thealgorithms/physics/SnellLaw.java

@@ -0,0 +1,33 @@
+package com.thealgorithms.physics;
+
+/**
+ * Calculates refraction angle using Snell's Law:
+ * n1 * sin(theta1) = n2 * sin(theta2)
+ * @see <a href="https://en.wikipedia.org/wiki/Snell%27s_law">Snell's Law</a>
+ */
+public final class SnellLaw {
+
+    private SnellLaw() {
+        throw new AssertionError("No instances.");
+    }
+
+    /**
+     * Computes the refracted angle (theta2) in radians.
+     *
+     * @param n1 index of refraction of medium 1
+     * @param n2 index of refraction of medium 2
+     * @param theta1 incident angle in radians
+     * @return refracted angle (theta2) in radians
+     * @throws IllegalArgumentException if total internal reflection occurs
+     */
+    public static double refractedAngle(double n1, double n2, double theta1) {
+        double ratio = n1 / n2;
+        double sinTheta2 = ratio * Math.sin(theta1);
+
+        if (Math.abs(sinTheta2) > 1.0) {
+            throw new IllegalArgumentException("Total internal reflection: no refraction possible.");
+        }
+
+        return Math.asin(sinTheta2);
+    }
+}

src/main/java/com/thealgorithms/sorts/BubbleSort.java

@@ -10,6 +10,13 @@ class BubbleSort implements SortAlgorithm {
     /**
      * Implements generic bubble sort algorithm.
      *
+     * Time Complexity:
+     * - Best case: O(n) – array is already sorted.
+     * - Average case: O(n^2)
+     * - Worst case: O(n^2)
+     *
+     * Space Complexity: O(1) – in-place sorting.
+     *
      * @param array the array to be sorted.
      * @param <T> the type of elements in the array.
      * @return the sorted array.

src/main/java/com/thealgorithms/sorts/HeapSort.java

@@ -1,9 +1,20 @@
 package com.thealgorithms.sorts;
 
 /**
- * Heap Sort Algorithm Implementation
+ * Heap Sort algorithm implementation.
+ *
+ * Heap sort converts the array into a max-heap and repeatedly extracts the maximum
+ * element to sort the array in increasing order.
+ *
+ * Time Complexity:
+ * - Best case: O(n log n)
+ * - Average case: O(n log n)
+ * - Worst case: O(n log n)
+ *
+ * Space Complexity: O(1) – in-place sorting
  *
  * @see <a href="https://en.wikipedia.org/wiki/Heapsort">Heap Sort Algorithm</a>
+ * @see SortAlgorithm
  */
 public class HeapSort implements SortAlgorithm {
 

src/main/java/com/thealgorithms/sorts/InsertionSort.java

@@ -1,5 +1,23 @@
 package com.thealgorithms.sorts;
 
+/**
+ * Generic Insertion Sort algorithm.
+ *
+ * Standard insertion sort iterates through the array and inserts each element into its
+ * correct position in the sorted portion of the array.
+ *
+ * Sentinel sort is a variation that first places the minimum element at index 0 to
+ * avoid redundant comparisons in subsequent passes.
+ *
+ * Time Complexity:
+ * - Best case: O(n) – array is already sorted (sentinel sort can improve slightly)
+ * - Average case: O(n^2)
+ * - Worst case: O(n^2) – array is reverse sorted
+ *
+ * Space Complexity: O(1) – in-place sorting
+ *
+ * @see SortAlgorithm
+ */
 class InsertionSort implements SortAlgorithm {
 
     /**

src/main/java/com/thealgorithms/sorts/MergeSort.java

@@ -13,11 +13,16 @@ class MergeSort implements SortAlgorithm {
     private Comparable[] aux;
 
     /**
-     * Generic merge sort algorithm implements.
+     * Generic merge sort algorithm.
      *
-     * @param unsorted the array which should be sorted.
-     * @param <T> Comparable class.
-     * @return sorted array.
+     * Time Complexity:
+     * - Best case: O(n log n)
+     * - Average case: O(n log n)
+     * - Worst case: O(n log n)
+     *
+     * Space Complexity: O(n) – requires auxiliary array for merging.
+     *
+     * @see SortAlgorithm
      */
     @Override
     public <T extends Comparable<T>> T[] sort(T[] unsorted) {

src/main/java/com/thealgorithms/sorts/QuickSort.java

@@ -8,9 +8,16 @@
 class QuickSort implements SortAlgorithm {
 
     /**
-     * This method implements the Generic Quick Sort
+     * Generic Quick Sort algorithm.
      *
-     * @param array The array to be sorted Sorts the array in increasing order
+     * Time Complexity:
+     * - Best case: O(n log n) – pivot splits array roughly in half each time.
+     * - Average case: O(n log n)
+     * - Worst case: O(n^2) – occurs when pivot consistently produces unbalanced splits.
+     *
+     * Space Complexity: O(log n) – recursion stack, in-place sorting.
+     *
+     * @see SortAlgorithm
      */
     @Override
     public <T extends Comparable<T>> T[] sort(T[] array) {

src/main/java/com/thealgorithms/sorts/SelectionSort.java

@@ -2,11 +2,16 @@
 
 public class SelectionSort implements SortAlgorithm {
     /**
-     * Sorts an array of comparable elements in increasing order using the selection sort algorithm.
+     * Generic Selection Sort algorithm.
      *
-     * @param array the array to be sorted
-     * @param <T> the class of array elements
-     * @return the sorted array
+     * Time Complexity:
+     * - Best case: O(n^2)
+     * - Average case: O(n^2)
+     * - Worst case: O(n^2)
+     *
+     * Space Complexity: O(1) – in-place sorting.
+     *
+     * @see SortAlgorithm
      */
     @Override
     public <T extends Comparable<T>> T[] sort(T[] array) {

src/main/java/com/thealgorithms/sorts/TopologicalSort.java

@@ -11,9 +11,16 @@
  * a linked list. A Directed Graph is proven to be acyclic when a DFS or Depth First Search is
  * performed, yielding no back-edges.
  *
- * https://en.wikipedia.org/wiki/Topological_sorting
+ * Time Complexity: O(V + E)
+ *   - V: number of vertices
+ *   - E: number of edges
  *
- * @author Jonathan Taylor (https://github.com/Jtmonument)
+ * Space Complexity: O(V + E)
+ *   - adjacency list and recursion stack in DFS
+ *
+ * Reference: https://en.wikipedia.org/wiki/Topological_sorting
+ *
+ * Author: Jonathan Taylor (https://github.com/Jtmonument)
  * Based on Introduction to Algorithms 3rd Edition
  */
 public final class TopologicalSort {

src/main/java/com/thealgorithms/strings/Upper.java

@@ -15,23 +15,27 @@ public static void main(String[] args) {
     }
 
     /**
-     * Converts all the characters in this {@code String} to upper case
+     * Converts all the characters in this {@code String} to upper case.
      *
      * @param s the string to convert
      * @return the {@code String}, converted to uppercase.
      */
     public static String toUpperCase(String s) {
         if (s == null) {
-            throw new IllegalArgumentException("Input string connot be null");
+            throw new IllegalArgumentException("Input string cannot be null");
         }
         if (s.isEmpty()) {
             return s;
         }
-        StringBuilder result = new StringBuilder(s);
-        for (int i = 0; i < result.length(); ++i) {
-            char currentChar = result.charAt(i);
-            if (Character.isLetter(currentChar) && Character.isLowerCase(currentChar)) {
-                result.setCharAt(i, Character.toUpperCase(currentChar));
+
+        StringBuilder result = new StringBuilder(s.length());
+
+        for (int i = 0; i < s.length(); ++i) {
+            char currentChar = s.charAt(i);
+            if (Character.isLowerCase(currentChar)) {
+                result.append(Character.toUpperCase(currentChar));
+            } else {
+                result.append(currentChar);
             }
         }
         return result.toString();