right = doRecursion(p, up.substring(1));
-
- left.addAll(right);
-
- return left;
- }
-}
diff --git a/src/main/java/com/thealgorithms/audiofilters/EMAFilter.java b/src/main/java/com/thealgorithms/audiofilters/EMAFilter.java
new file mode 100644
index 000000000000..0dd23e937953
--- /dev/null
+++ b/src/main/java/com/thealgorithms/audiofilters/EMAFilter.java
@@ -0,0 +1,48 @@
+package com.thealgorithms.audiofilters;
+
+/**
+ * Exponential Moving Average (EMA) Filter for smoothing audio signals.
+ *
+ * This filter applies an exponential moving average to a sequence of audio
+ * signal values, making it useful for smoothing out rapid fluctuations.
+ * The smoothing factor (alpha) controls the degree of smoothing.
+ *
+ *
Based on the definition from
+ * Wikipedia link.
+ */
+public class EMAFilter {
+ private final double alpha;
+ private double emaValue;
+ /**
+ * Constructs an EMA filter with a given smoothing factor.
+ *
+ * @param alpha Smoothing factor (0 < alpha <= 1)
+ * @throws IllegalArgumentException if alpha is not in (0, 1]
+ */
+ public EMAFilter(double alpha) {
+ if (alpha <= 0 || alpha > 1) {
+ throw new IllegalArgumentException("Alpha must be between 0 and 1.");
+ }
+ this.alpha = alpha;
+ this.emaValue = 0.0;
+ }
+ /**
+ * Applies the EMA filter to an audio signal array.
+ *
+ * @param audioSignal Array of audio samples to process
+ * @return Array of processed (smoothed) samples
+ */
+ public double[] apply(double[] audioSignal) {
+ if (audioSignal.length == 0) {
+ return new double[0];
+ }
+ double[] emaSignal = new double[audioSignal.length];
+ emaValue = audioSignal[0];
+ emaSignal[0] = emaValue;
+ for (int i = 1; i < audioSignal.length; i++) {
+ emaValue = alpha * audioSignal[i] + (1 - alpha) * emaValue;
+ emaSignal[i] = emaValue;
+ }
+ return emaSignal;
+ }
+}
diff --git a/src/main/java/com/thealgorithms/audiofilters/IIRFilter.java b/src/main/java/com/thealgorithms/audiofilters/IIRFilter.java
index c211cd08a501..fbc095909541 100644
--- a/src/main/java/com/thealgorithms/audiofilters/IIRFilter.java
+++ b/src/main/java/com/thealgorithms/audiofilters/IIRFilter.java
@@ -58,7 +58,7 @@ public void setCoeffs(double[] aCoeffs, double[] bCoeffs) throws IllegalArgument
throw new IllegalArgumentException("bCoeffs must be of size " + order + ", got " + bCoeffs.length);
}
- for (int i = 0; i <= order; i++) {
+ for (int i = 0; i < order; i++) {
coeffsA[i] = aCoeffs[i];
coeffsB[i] = bCoeffs[i];
}
diff --git a/src/main/java/com/thealgorithms/backtracking/AllPathsFromSourceToTarget.java b/src/main/java/com/thealgorithms/backtracking/AllPathsFromSourceToTarget.java
index 6f93b704ffb2..c35a36d97a57 100644
--- a/src/main/java/com/thealgorithms/backtracking/AllPathsFromSourceToTarget.java
+++ b/src/main/java/com/thealgorithms/backtracking/AllPathsFromSourceToTarget.java
@@ -9,6 +9,7 @@
*
* @author Siddhant Swarup Mallick
*/
+@SuppressWarnings({"rawtypes", "unchecked"})
public class AllPathsFromSourceToTarget {
// No. of vertices in graph
diff --git a/src/main/java/com/thealgorithms/backtracking/ArrayCombination.java b/src/main/java/com/thealgorithms/backtracking/ArrayCombination.java
index a064decc0eb7..f8cd0c40c20e 100644
--- a/src/main/java/com/thealgorithms/backtracking/ArrayCombination.java
+++ b/src/main/java/com/thealgorithms/backtracking/ArrayCombination.java
@@ -4,22 +4,24 @@
import java.util.List;
/**
- * Finds all combinations of 0...n-1 of length k
+ * This class provides methods to find all combinations of integers from 0 to n-1
+ * of a specified length k using backtracking.
*/
public final class ArrayCombination {
private ArrayCombination() {
}
/**
- * Finds all combinations of length k of 0..n-1 using backtracking.
+ * Generates all possible combinations of length k from the integers 0 to n-1.
*
- * @param n Number of the elements.
- * @param k Length of the combination.
- * @return A list of all combinations of length k.
+ * @param n The total number of elements (0 to n-1).
+ * @param k The desired length of each combination.
+ * @return A list containing all combinations of length k.
+ * @throws IllegalArgumentException if n or k are negative, or if k is greater than n.
*/
public static List> combination(int n, int k) {
if (n < 0 || k < 0 || k > n) {
- throw new IllegalArgumentException("Wrong input.");
+ throw new IllegalArgumentException("Invalid input: n must be non-negative, k must be non-negative and less than or equal to n.");
}
List> combinations = new ArrayList<>();
@@ -27,16 +29,26 @@ public static List> combination(int n, int k) {
return combinations;
}
+ /**
+ * A helper method that uses backtracking to find combinations.
+ *
+ * @param combinations The list to store all valid combinations found.
+ * @param current The current combination being built.
+ * @param start The starting index for the current recursion.
+ * @param n The total number of elements (0 to n-1).
+ * @param k The desired length of each combination.
+ */
private static void combine(List> combinations, List current, int start, int n, int k) {
- if (current.size() == k) { // Base case: combination found
- combinations.add(new ArrayList<>(current)); // Copy to avoid modification
+ // Base case: combination found
+ if (current.size() == k) {
+ combinations.add(new ArrayList<>(current));
return;
}
for (int i = start; i < n; i++) {
current.add(i);
combine(combinations, current, i + 1, n, k);
- current.removeLast(); // Backtrack
+ current.remove(current.size() - 1); // Backtrack
}
}
}
diff --git a/src/main/java/com/thealgorithms/backtracking/Combination.java b/src/main/java/com/thealgorithms/backtracking/Combination.java
index bf2a672a0ef8..ecaf7428f986 100644
--- a/src/main/java/com/thealgorithms/backtracking/Combination.java
+++ b/src/main/java/com/thealgorithms/backtracking/Combination.java
@@ -1,6 +1,7 @@
package com.thealgorithms.backtracking;
import java.util.Arrays;
+import java.util.Collections;
import java.util.LinkedList;
import java.util.List;
import java.util.TreeSet;
@@ -13,8 +14,6 @@ public final class Combination {
private Combination() {
}
- private static int length;
-
/**
* Find all combinations of given array using backtracking
* @param arr the array.
@@ -23,39 +22,45 @@ private Combination() {
* @return a list of all combinations of length n. If n == 0, return null.
*/
public static List> combination(T[] arr, int n) {
+ if (n < 0) {
+ throw new IllegalArgumentException("The combination length cannot be negative.");
+ }
+
if (n == 0) {
- return null;
+ return Collections.emptyList();
}
- length = n;
T[] array = arr.clone();
Arrays.sort(array);
+
List> result = new LinkedList<>();
- backtracking(array, 0, new TreeSet(), result);
+ backtracking(array, n, 0, new TreeSet(), result);
return result;
}
/**
* Backtrack all possible combinations of a given array
* @param arr the array.
+ * @param n length of the combination
* @param index the starting index.
* @param currSet set that tracks current combination
* @param result the list contains all combination.
* @param the type of elements in the array.
*/
- private static void backtracking(T[] arr, int index, TreeSet currSet, List> result) {
- if (index + length - currSet.size() > arr.length) {
+ private static void backtracking(T[] arr, int n, int index, TreeSet currSet, List> result) {
+ if (index + n - currSet.size() > arr.length) {
return;
}
- if (length - 1 == currSet.size()) {
+ if (currSet.size() == n - 1) {
for (int i = index; i < arr.length; i++) {
currSet.add(arr[i]);
- result.add((TreeSet) currSet.clone());
+ result.add(new TreeSet<>(currSet));
currSet.remove(arr[i]);
}
+ return;
}
for (int i = index; i < arr.length; i++) {
currSet.add(arr[i]);
- backtracking(arr, i + 1, currSet, result);
+ backtracking(arr, n, i + 1, currSet, result);
currSet.remove(arr[i]);
}
}
diff --git a/src/main/java/com/thealgorithms/backtracking/CrosswordSolver.java b/src/main/java/com/thealgorithms/backtracking/CrosswordSolver.java
new file mode 100644
index 000000000000..6bfb026c7de9
--- /dev/null
+++ b/src/main/java/com/thealgorithms/backtracking/CrosswordSolver.java
@@ -0,0 +1,125 @@
+package com.thealgorithms.backtracking;
+
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.List;
+
+/**
+ * A class to solve a crossword puzzle using backtracking.
+ * Example:
+ * Input:
+ * puzzle = {
+ * {' ', ' ', ' '},
+ * {' ', ' ', ' '},
+ * {' ', ' ', ' '}
+ * }
+ * words = List.of("cat", "dog")
+ *
+ * Output:
+ * {
+ * {'c', 'a', 't'},
+ * {' ', ' ', ' '},
+ * {'d', 'o', 'g'}
+ * }
+ */
+public final class CrosswordSolver {
+ private CrosswordSolver() {
+ }
+
+ /**
+ * Checks if a word can be placed at the specified position in the crossword.
+ *
+ * @param puzzle The crossword puzzle represented as a 2D char array.
+ * @param word The word to be placed.
+ * @param row The row index where the word might be placed.
+ * @param col The column index where the word might be placed.
+ * @param vertical If true, the word is placed vertically; otherwise, horizontally.
+ * @return true if the word can be placed, false otherwise.
+ */
+ public static boolean isValid(char[][] puzzle, String word, int row, int col, boolean vertical) {
+ for (int i = 0; i < word.length(); i++) {
+ if (vertical) {
+ if (row + i >= puzzle.length || puzzle[row + i][col] != ' ') {
+ return false;
+ }
+ } else {
+ if (col + i >= puzzle[0].length || puzzle[row][col + i] != ' ') {
+ return false;
+ }
+ }
+ }
+ return true;
+ }
+
+ /**
+ * Places a word at the specified position in the crossword.
+ *
+ * @param puzzle The crossword puzzle represented as a 2D char array.
+ * @param word The word to be placed.
+ * @param row The row index where the word will be placed.
+ * @param col The column index where the word will be placed.
+ * @param vertical If true, the word is placed vertically; otherwise, horizontally.
+ */
+ public static void placeWord(char[][] puzzle, String word, int row, int col, boolean vertical) {
+ for (int i = 0; i < word.length(); i++) {
+ if (vertical) {
+ puzzle[row + i][col] = word.charAt(i);
+ } else {
+ puzzle[row][col + i] = word.charAt(i);
+ }
+ }
+ }
+
+ /**
+ * Removes a word from the specified position in the crossword.
+ *
+ * @param puzzle The crossword puzzle represented as a 2D char array.
+ * @param word The word to be removed.
+ * @param row The row index where the word is placed.
+ * @param col The column index where the word is placed.
+ * @param vertical If true, the word was placed vertically; otherwise, horizontally.
+ */
+ public static void removeWord(char[][] puzzle, String word, int row, int col, boolean vertical) {
+ for (int i = 0; i < word.length(); i++) {
+ if (vertical) {
+ puzzle[row + i][col] = ' ';
+ } else {
+ puzzle[row][col + i] = ' ';
+ }
+ }
+ }
+
+ /**
+ * Solves the crossword puzzle using backtracking.
+ *
+ * @param puzzle The crossword puzzle represented as a 2D char array.
+ * @param words The list of words to be placed.
+ * @return true if the crossword is solved, false otherwise.
+ */
+ public static boolean solveCrossword(char[][] puzzle, Collection words) {
+ // Create a mutable copy of the words list
+ List remainingWords = new ArrayList<>(words);
+
+ for (int row = 0; row < puzzle.length; row++) {
+ for (int col = 0; col < puzzle[0].length; col++) {
+ if (puzzle[row][col] == ' ') {
+ for (String word : new ArrayList<>(remainingWords)) {
+ for (boolean vertical : new boolean[] {true, false}) {
+ if (isValid(puzzle, word, row, col, vertical)) {
+ placeWord(puzzle, word, row, col, vertical);
+ remainingWords.remove(word);
+ if (solveCrossword(puzzle, remainingWords)) {
+ return true;
+ }
+ remainingWords.add(word);
+ removeWord(puzzle, word, row, col, vertical);
+ }
+ }
+ }
+ return false;
+ }
+ }
+ }
+ return true;
+ }
+}
diff --git a/src/main/java/com/thealgorithms/backtracking/KnightsTour.java b/src/main/java/com/thealgorithms/backtracking/KnightsTour.java
index 2287b39da385..2c2da659f3aa 100644
--- a/src/main/java/com/thealgorithms/backtracking/KnightsTour.java
+++ b/src/main/java/com/thealgorithms/backtracking/KnightsTour.java
@@ -4,33 +4,26 @@
import java.util.Comparator;
import java.util.List;
-/*
- * Problem Statement: -
-
- Given a N*N board with the Knight placed on the first block of an empty board. Moving according
- to the rules of chess knight must visit each square exactly once. Print the order of each cell in
- which they are visited.
-
- Example: -
-
- Input : N = 8
-
- Output:
- 0 59 38 33 30 17 8 63
- 37 34 31 60 9 62 29 16
- 58 1 36 39 32 27 18 7
- 35 48 41 26 61 10 15 28
- 42 57 2 49 40 23 6 19
- 47 50 45 54 25 20 11 14
- 56 43 52 3 22 13 24 5
- 51 46 55 44 53 4 21 12
-
+/**
+ * The KnightsTour class solves the Knight's Tour problem using backtracking.
+ *
+ * Problem Statement:
+ * Given an N*N board with a knight placed on the first block, the knight must
+ * move according to chess rules and visit each square on the board exactly once.
+ * The class outputs the sequence of moves for the knight.
+ *
+ * Example:
+ * Input: N = 8 (8x8 chess board)
+ * Output: The sequence of numbers representing the order in which the knight visits each square.
*/
public final class KnightsTour {
private KnightsTour() {
}
+ // The size of the chess board (12x12 grid, with 2 extra rows/columns as a buffer around a 8x8 area)
private static final int BASE = 12;
+
+ // Possible moves for a knight in chess
private static final int[][] MOVES = {
{1, -2},
{2, -1},
@@ -40,36 +33,40 @@ private KnightsTour() {
{-2, 1},
{-2, -1},
{-1, -2},
- }; // Possible moves by knight on chess
- private static int[][] grid; // chess grid
- private static int total; // total squares in chess
+ };
+
+ // Chess grid representing the board
+ static int[][] grid;
+
+ // Total number of cells the knight needs to visit
+ static int total;
- public static void main(String[] args) {
+ /**
+ * Resets the chess board to its initial state.
+ * Initializes the grid with boundary cells marked as -1 and internal cells as 0.
+ * Sets the total number of cells the knight needs to visit.
+ */
+ public static void resetBoard() {
grid = new int[BASE][BASE];
total = (BASE - 4) * (BASE - 4);
-
for (int r = 0; r < BASE; r++) {
for (int c = 0; c < BASE; c++) {
if (r < 2 || r > BASE - 3 || c < 2 || c > BASE - 3) {
- grid[r][c] = -1;
+ grid[r][c] = -1; // Mark boundary cells
}
}
}
-
- int row = 2 + (int) (Math.random() * (BASE - 4));
- int col = 2 + (int) (Math.random() * (BASE - 4));
-
- grid[row][col] = 1;
-
- if (solve(row, col, 2)) {
- printResult();
- } else {
- System.out.println("no result");
- }
}
- // Return True when solvable
- private static boolean solve(int row, int column, int count) {
+ /**
+ * Recursive method to solve the Knight's Tour problem.
+ *
+ * @param row The current row of the knight
+ * @param column The current column of the knight
+ * @param count The current move number
+ * @return True if a solution is found, False otherwise
+ */
+ static boolean solve(int row, int column, int count) {
if (count > total) {
return true;
}
@@ -80,29 +77,37 @@ private static boolean solve(int row, int column, int count) {
return false;
}
+ // Sort neighbors by Warnsdorff's rule (fewest onward moves)
neighbor.sort(Comparator.comparingInt(a -> a[2]));
for (int[] nb : neighbor) {
- row = nb[0];
- column = nb[1];
- grid[row][column] = count;
- if (!orphanDetected(count, row, column) && solve(row, column, count + 1)) {
+ int nextRow = nb[0];
+ int nextCol = nb[1];
+ grid[nextRow][nextCol] = count;
+ if (!orphanDetected(count, nextRow, nextCol) && solve(nextRow, nextCol, count + 1)) {
return true;
}
- grid[row][column] = 0;
+ grid[nextRow][nextCol] = 0; // Backtrack
}
return false;
}
- // Returns List of neighbours
- private static List neighbors(int row, int column) {
+ /**
+ * Returns a list of valid neighboring cells where the knight can move.
+ *
+ * @param row The current row of the knight
+ * @param column The current column of the knight
+ * @return A list of arrays representing valid moves, where each array contains:
+ * {nextRow, nextCol, numberOfPossibleNextMoves}
+ */
+ static List neighbors(int row, int column) {
List neighbour = new ArrayList<>();
for (int[] m : MOVES) {
int x = m[0];
int y = m[1];
- if (grid[row + y][column + x] == 0) {
+ if (row + y >= 0 && row + y < BASE && column + x >= 0 && column + x < BASE && grid[row + y][column + x] == 0) {
int num = countNeighbors(row + y, column + x);
neighbour.add(new int[] {row + y, column + x, num});
}
@@ -110,19 +115,34 @@ private static List neighbors(int row, int column) {
return neighbour;
}
- // Returns the total count of neighbors
- private static int countNeighbors(int row, int column) {
+ /**
+ * Counts the number of possible valid moves for a knight from a given position.
+ *
+ * @param row The row of the current position
+ * @param column The column of the current position
+ * @return The number of valid neighboring moves
+ */
+ static int countNeighbors(int row, int column) {
int num = 0;
for (int[] m : MOVES) {
- if (grid[row + m[1]][column + m[0]] == 0) {
+ int x = m[0];
+ int y = m[1];
+ if (row + y >= 0 && row + y < BASE && column + x >= 0 && column + x < BASE && grid[row + y][column + x] == 0) {
num++;
}
}
return num;
}
- // Returns true if it is orphan
- private static boolean orphanDetected(int count, int row, int column) {
+ /**
+ * Detects if moving to a given position will create an orphan (a position with no further valid moves).
+ *
+ * @param count The current move number
+ * @param row The row of the current position
+ * @param column The column of the current position
+ * @return True if an orphan is detected, False otherwise
+ */
+ static boolean orphanDetected(int count, int row, int column) {
if (count < total - 1) {
List neighbor = neighbors(row, column);
for (int[] nb : neighbor) {
@@ -133,17 +153,4 @@ private static boolean orphanDetected(int count, int row, int column) {
}
return false;
}
-
- // Prints the result grid
- private static void printResult() {
- for (int[] row : grid) {
- for (int i : row) {
- if (i == -1) {
- continue;
- }
- System.out.printf("%2d ", i);
- }
- System.out.println();
- }
- }
}
diff --git a/src/main/java/com/thealgorithms/backtracking/MazeRecursion.java b/src/main/java/com/thealgorithms/backtracking/MazeRecursion.java
index f7eae01e449a..8247172e7ee0 100644
--- a/src/main/java/com/thealgorithms/backtracking/MazeRecursion.java
+++ b/src/main/java/com/thealgorithms/backtracking/MazeRecursion.java
@@ -1,152 +1,125 @@
package com.thealgorithms.backtracking;
+/**
+ * This class contains methods to solve a maze using recursive backtracking.
+ * The maze is represented as a 2D array where walls, paths, and visited/dead
+ * ends are marked with different integers.
+ *
+ * The goal is to find a path from a starting position to the target position
+ * (map[6][5]) while navigating through the maze.
+ */
public final class MazeRecursion {
+
private MazeRecursion() {
}
- public static void mazeRecursion() {
- // First create a 2 dimensions array to mimic a maze map
- int[][] map = new int[8][7];
- int[][] map2 = new int[8][7];
-
- // We use 1 to indicate wall
- // Set the ceiling and floor to 1
- for (int i = 0; i < 7; i++) {
- map[0][i] = 1;
- map[7][i] = 1;
- }
-
- // Then we set the left and right wall to 1
- for (int i = 0; i < 8; i++) {
- map[i][0] = 1;
- map[i][6] = 1;
- }
-
- // Now we have created a maze with its wall initialized
-
- // Here we set the obstacle
- map[3][1] = 1;
- map[3][2] = 1;
-
- // Print the current map
- System.out.println("The condition of the map： ");
- for (int i = 0; i < 8; i++) {
- for (int j = 0; j < 7; j++) {
- System.out.print(map[i][j] + " ");
- }
- System.out.println();
- }
-
- // clone another map for setWay2 method
- for (int i = 0; i < map.length; i++) {
- System.arraycopy(map[i], 0, map2[i], 0, map[i].length);
- }
-
- // By using recursive backtracking to let your ball(target) find its way in the
- // maze
- // The first parameter is the map
- // Second parameter is x coordinate of your target
- // Third parameter is the y coordinate of your target
- setWay(map, 1, 1);
- setWay2(map2, 1, 1);
-
- // Print out the new map1, with the ball footprint
- System.out.println("After the ball goes through the map1，show the current map1 condition");
- for (int i = 0; i < 8; i++) {
- for (int j = 0; j < 7; j++) {
- System.out.print(map[i][j] + " ");
- }
- System.out.println();
+ /**
+ * This method solves the maze using the "down -> right -> up -> left"
+ * movement strategy.
+ *
+ * @param map The 2D array representing the maze (walls, paths, etc.)
+ * @return The solved maze with paths marked, or null if no solution exists.
+ */
+ public static int[][] solveMazeUsingFirstStrategy(int[][] map) {
+ if (setWay(map, 1, 1)) {
+ return map;
}
+ return null;
+ }
- // Print out the new map2, with the ball footprint
- System.out.println("After the ball goes through the map2，show the current map2 condition");
- for (int i = 0; i < 8; i++) {
- for (int j = 0; j < 7; j++) {
- System.out.print(map2[i][j] + " ");
- }
- System.out.println();
+ /**
+ * This method solves the maze using the "up -> right -> down -> left"
+ * movement strategy.
+ *
+ * @param map The 2D array representing the maze (walls, paths, etc.)
+ * @return The solved maze with paths marked, or null if no solution exists.
+ */
+ public static int[][] solveMazeUsingSecondStrategy(int[][] map) {
+ if (setWay2(map, 1, 1)) {
+ return map;
}
+ return null;
}
/**
- * Using recursive path finding to help the ball find its way in the maze
- * Description：
- * 1. map (means the maze)
- * 2. i, j (means the initial coordinate of the ball in the maze)
- * 3. if the ball can reach the end of maze, that is position of map[6][5],
- * means the we have found a path for the ball
- * 4. Additional Information： 0 in the map[i][j] means the ball has not gone
- * through this position, 1 means the wall, 2 means the path is feasible, 3
- * means the ball has gone through the path but this path is dead end
- * 5. We will need strategy for the ball to pass through the maze for example:
- * Down -> Right -> Up -> Left, if the path doesn't work, then backtrack
+ * Attempts to find a path through the maze using a "down -> right -> up -> left"
+ * movement strategy. The path is marked with '2' for valid paths and '3' for dead ends.
*
- * @author OngLipWei
- * @version Jun 23, 2021 11:36:14 AM
- * @param map The maze
- * @param i x coordinate of your ball(target)
- * @param j y coordinate of your ball(target)
- * @return If we did find a path for the ball，return true，else false
+ * @param map The 2D array representing the maze (walls, paths, etc.)
+ * @param i The current x-coordinate of the ball (row index)
+ * @param j The current y-coordinate of the ball (column index)
+ * @return True if a path is found to (6,5), otherwise false
*/
- public static boolean setWay(int[][] map, int i, int j) {
- if (map[6][5] == 2) { // means the ball find its path, ending condition
+ private static boolean setWay(int[][] map, int i, int j) {
+ if (map[6][5] == 2) {
return true;
}
- if (map[i][j] == 0) { // if the ball haven't gone through this point
- // then the ball follows the move strategy : down -> right -> up -> left
- map[i][j] = 2; // we assume that this path is feasible first, set the current point to 2
- // first。
- if (setWay(map, i + 1, j)) { // go down
+
+ // If the current position is unvisited (0), explore it
+ if (map[i][j] == 0) {
+ // Mark the current position as '2'
+ map[i][j] = 2;
+
+ // Move down
+ if (setWay(map, i + 1, j)) {
return true;
- } else if (setWay(map, i, j + 1)) { // go right
+ }
+ // Move right
+ else if (setWay(map, i, j + 1)) {
return true;
- } else if (setWay(map, i - 1, j)) { // go up
+ }
+ // Move up
+ else if (setWay(map, i - 1, j)) {
return true;
- } else if (setWay(map, i, j - 1)) { // go left
+ }
+ // Move left
+ else if (setWay(map, i, j - 1)) {
return true;
- } else {
- // means that the current point is the dead end, the ball cannot proceed, set
- // the current point to 3 and return false, the backtracking will start, it will
- // go to the previous step and check for feasible path again
- map[i][j] = 3;
- return false;
}
- } else { // if the map[i][j] != 0 , it will probably be 1,2,3, return false because the
- // ball cannot hit the wall, cannot go to the path that has gone though before,
- // and cannot head to deadened.
+
+ map[i][j] = 3; // Mark as dead end (3) if no direction worked
return false;
}
+ return false;
}
- // Here is another move strategy for the ball: up->right->down->left
- public static boolean setWay2(int[][] map, int i, int j) {
- if (map[6][5] == 2) { // means the ball find its path, ending condition
+ /**
+ * Attempts to find a path through the maze using an alternative movement
+ * strategy "up -> right -> down -> left".
+ *
+ * @param map The 2D array representing the maze (walls, paths, etc.)
+ * @param i The current x-coordinate of the ball (row index)
+ * @param j The current y-coordinate of the ball (column index)
+ * @return True if a path is found to (6,5), otherwise false
+ */
+ private static boolean setWay2(int[][] map, int i, int j) {
+ if (map[6][5] == 2) {
return true;
}
- if (map[i][j] == 0) { // if the ball haven't gone through this point
- // then the ball follows the move strategy : up->right->down->left
- map[i][j] = 2; // we assume that this path is feasible first, set the current point to 2
- // first。
- if (setWay2(map, i - 1, j)) { // go up
+
+ if (map[i][j] == 0) {
+ map[i][j] = 2;
+
+ // Move up
+ if (setWay2(map, i - 1, j)) {
return true;
- } else if (setWay2(map, i, j + 1)) { // go right
+ }
+ // Move right
+ else if (setWay2(map, i, j + 1)) {
return true;
- } else if (setWay2(map, i + 1, j)) { // go down
+ }
+ // Move down
+ else if (setWay2(map, i + 1, j)) {
return true;
- } else if (setWay2(map, i, j - 1)) { // go left
+ }
+ // Move left
+ else if (setWay2(map, i, j - 1)) {
return true;
- } else {
- // means that the current point is the dead end, the ball cannot proceed, set
- // the current point to 3 and return false, the backtracking will start, it will
- // go to the previous step and check for feasible path again
- map[i][j] = 3;
- return false;
}
- } else { // if the map[i][j] != 0 , it will probably be 1,2,3, return false because the
- // ball cannot hit the wall, cannot go to the path that has gone through before,
- // and cannot head to deadend.
+
+ map[i][j] = 3; // Mark as dead end (3) if no direction worked
return false;
}
+ return false;
}
}
diff --git a/src/main/java/com/thealgorithms/backtracking/PowerSum.java b/src/main/java/com/thealgorithms/backtracking/PowerSum.java
index 6617ea326a1c..b34ba660ebd7 100644
--- a/src/main/java/com/thealgorithms/backtracking/PowerSum.java
+++ b/src/main/java/com/thealgorithms/backtracking/PowerSum.java
@@ -1,45 +1,51 @@
package com.thealgorithms.backtracking;
-/*
- * Problem Statement :
- * Find the number of ways that a given integer, N , can be expressed as the sum of the Xth powers
- * of unique, natural numbers. For example, if N=100 and X=3, we have to find all combinations of
- * unique cubes adding up to 100. The only solution is 1^3+2^3+3^3+4^3. Therefore output will be 1.
+/**
+ * Problem Statement:
+ * Find the number of ways that a given integer, N, can be expressed as the sum of the Xth powers
+ * of unique, natural numbers.
+ * For example, if N=100 and X=3, we have to find all combinations of unique cubes adding up to 100.
+ * The only solution is 1^3 + 2^3 + 3^3 + 4^3. Therefore, the output will be 1.
+ *
+ * N is represented by the parameter 'targetSum' in the code.
+ * X is represented by the parameter 'power' in the code.
*/
public class PowerSum {
- private int count = 0;
- private int sum = 0;
-
- public int powSum(int n, int x) {
- sum(n, x, 1);
- return count;
+ /**
+ * Calculates the number of ways to express the target sum as a sum of Xth powers of unique natural numbers.
+ *
+ * @param targetSum The target sum to achieve (N in the problem statement)
+ * @param power The power to raise natural numbers to (X in the problem statement)
+ * @return The number of ways to express the target sum
+ */
+ public int powSum(int targetSum, int power) {
+ // Special case: when both targetSum and power are zero
+ if (targetSum == 0 && power == 0) {
+ return 1; // by convention, one way to sum to zero: use nothing
+ }
+ return sumRecursive(targetSum, power, 1, 0);
}
- // here i is the natural number which will be raised by X and added in sum.
- public void sum(int n, int x, int i) {
- // if sum is equal to N that is one of our answer and count is increased.
- if (sum == n) {
- count++;
- return;
- } // we will be adding next natural number raised to X only if on adding it in sum the
- // result is less than N.
- else if (sum + power(i, x) <= n) {
- sum += power(i, x);
- sum(n, x, i + 1);
- // backtracking and removing the number added last since no possible combination is
- // there with it.
- sum -= power(i, x);
+ /**
+ * Recursively calculates the number of ways to express the remaining sum as a sum of Xth powers.
+ *
+ * @param remainingSum The remaining sum to achieve
+ * @param power The power to raise natural numbers to (X in the problem statement)
+ * @param currentNumber The current natural number being considered
+ * @param currentSum The current sum of powered numbers
+ * @return The number of valid combinations
+ */
+ private int sumRecursive(int remainingSum, int power, int currentNumber, int currentSum) {
+ int newSum = currentSum + (int) Math.pow(currentNumber, power);
+
+ if (newSum == remainingSum) {
+ return 1;
}
- if (power(i, x) < n) {
- // calling the sum function with next natural number after backtracking if when it is
- // raised to X is still less than X.
- sum(n, x, i + 1);
+ if (newSum > remainingSum) {
+ return 0;
}
- }
- // creating a separate power function so that it can be used again and again when required.
- private int power(int a, int b) {
- return (int) Math.pow(a, b);
+ return sumRecursive(remainingSum, power, currentNumber + 1, newSum) + sumRecursive(remainingSum, power, currentNumber + 1, currentSum);
}
}
diff --git a/src/main/java/com/thealgorithms/backtracking/WordPatternMatcher.java b/src/main/java/com/thealgorithms/backtracking/WordPatternMatcher.java
new file mode 100644
index 000000000000..1854cab20a7f
--- /dev/null
+++ b/src/main/java/com/thealgorithms/backtracking/WordPatternMatcher.java
@@ -0,0 +1,86 @@
+package com.thealgorithms.backtracking;
+
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * Class to determine if a pattern matches a string using backtracking.
+ *
+ * Example:
+ * Pattern: "abab"
+ * Input String: "JavaPythonJavaPython"
+ * Output: true
+ *
+ * Pattern: "aaaa"
+ * Input String: "JavaJavaJavaJava"
+ * Output: true
+ *
+ * Pattern: "aabb"
+ * Input String: "JavaPythonPythonJava"
+ * Output: false
+ */
+public final class WordPatternMatcher {
+ private WordPatternMatcher() {
+ }
+
+ /**
+ * Determines if the given pattern matches the input string using backtracking.
+ *
+ * @param pattern The pattern to match.
+ * @param inputString The string to match against the pattern.
+ * @return True if the pattern matches the string, False otherwise.
+ */
+ public static boolean matchWordPattern(String pattern, String inputString) {
+ Map patternMap = new HashMap<>();
+ Map strMap = new HashMap<>();
+ return backtrack(pattern, inputString, 0, 0, patternMap, strMap);
+ }
+
+ /**
+ * Backtracking helper function to check if the pattern matches the string.
+ *
+ * @param pattern The pattern string.
+ * @param inputString The string to match against the pattern.
+ * @param patternIndex Current index in the pattern.
+ * @param strIndex Current index in the input string.
+ * @param patternMap Map to store pattern characters to string mappings.
+ * @param strMap Map to store string to pattern character mappings.
+ * @return True if the pattern matches, False otherwise.
+ */
+ private static boolean backtrack(String pattern, String inputString, int patternIndex, int strIndex, Map patternMap, Map strMap) {
+ if (patternIndex == pattern.length() && strIndex == inputString.length()) {
+ return true;
+ }
+ if (patternIndex == pattern.length() || strIndex == inputString.length()) {
+ return false;
+ }
+
+ char currentChar = pattern.charAt(patternIndex);
+ if (patternMap.containsKey(currentChar)) {
+ String mappedStr = patternMap.get(currentChar);
+ if (inputString.startsWith(mappedStr, strIndex)) {
+ return backtrack(pattern, inputString, patternIndex + 1, strIndex + mappedStr.length(), patternMap, strMap);
+ } else {
+ return false;
+ }
+ }
+
+ for (int end = strIndex + 1; end <= inputString.length(); end++) {
+ String substring = inputString.substring(strIndex, end);
+ if (strMap.containsKey(substring)) {
+ continue;
+ }
+
+ patternMap.put(currentChar, substring);
+ strMap.put(substring, currentChar);
+ if (backtrack(pattern, inputString, patternIndex + 1, end, patternMap, strMap)) {
+ return true;
+ }
+
+ patternMap.remove(currentChar);
+ strMap.remove(substring);
+ }
+
+ return false;
+ }
+}
diff --git a/src/main/java/com/thealgorithms/backtracking/WordSearch.java b/src/main/java/com/thealgorithms/backtracking/WordSearch.java
index f3a5b0433727..174ca90ccaab 100644
--- a/src/main/java/com/thealgorithms/backtracking/WordSearch.java
+++ b/src/main/java/com/thealgorithms/backtracking/WordSearch.java
@@ -1,35 +1,39 @@
package com.thealgorithms.backtracking;
-/*
-Word Search Problem (https://en.wikipedia.org/wiki/Word_search)
-
-Given an m x n grid of characters board and a string word, return true if word exists in the grid.
-
-The word can be constructed from letters of sequentially adjacent cell, where "adjacent" cells are
-those horizontally or vertically neighboring. The same letter cell may not be used more than once.
-
-For example,
-Given board =
-
-[
- ['A','B','C','E'],
- ['S','F','C','S'],
- ['A','D','E','E']
-]
-word = "ABCCED", -> returns true,
-word = "SEE", -> returns true,
-word = "ABCB", -> returns false.
-*/
-
-/*
- Solution
- Depth First Search in matrix (as multiple sources possible) with backtracking
- like finding cycle in a directed graph. Maintain a record of path
-
- Tx = O(m * n * 3^L): for each cell, we look at 3 options (not 4 as that one will be visited), we
- do it L times Sx = O(L) : stack size is max L
-*/
-
+/**
+ * Word Search Problem
+ *
+ * This class solves the word search problem where given an m x n grid of characters (board)
+ * and a target word, the task is to check if the word exists in the grid.
+ * The word can be constructed from sequentially adjacent cells (horizontally or vertically),
+ * and the same cell may not be used more than once in constructing the word.
+ *
+ * Example:
+ * - For board =
+ * [
+ * ['A','B','C','E'],
+ * ['S','F','C','S'],
+ * ['A','D','E','E']
+ * ]
+ * and word = "ABCCED", -> returns true
+ * and word = "SEE", -> returns true
+ * and word = "ABCB", -> returns false
+ *
+ * Solution:
+ * - Depth First Search (DFS) with backtracking is used to explore possible paths from any cell
+ * matching the first letter of the word. DFS ensures that we search all valid paths, while
+ * backtracking helps in reverting decisions when a path fails to lead to a solution.
+ *
+ * Time Complexity: O(m * n * 3^L)
+ * - m = number of rows in the board
+ * - n = number of columns in the board
+ * - L = length of the word
+ * - For each cell, we look at 3 possible directions (since we exclude the previously visited direction),
+ * and we do this for L letters.
+ *
+ * Space Complexity: O(L)
+ * - Stack space for the recursive DFS function, where L is the maximum depth of recursion (length of the word).
+ */
public class WordSearch {
private final int[] dx = {0, 0, 1, -1};
private final int[] dy = {1, -1, 0, 0};
@@ -37,15 +41,32 @@ public class WordSearch {
private char[][] board;
private String word;
+ /**
+ * Checks if the given (x, y) coordinates are valid positions in the board.
+ *
+ * @param x The row index.
+ * @param y The column index.
+ * @return True if the coordinates are within the bounds of the board; false otherwise.
+ */
private boolean isValid(int x, int y) {
return x >= 0 && x < board.length && y >= 0 && y < board[0].length;
}
+ /**
+ * Performs Depth First Search (DFS) from the cell (x, y)
+ * to search for the next character in the word.
+ *
+ * @param x The current row index.
+ * @param y The current column index.
+ * @param nextIdx The index of the next character in the word to be matched.
+ * @return True if a valid path is found to match the remaining characters of the word; false otherwise.
+ */
private boolean doDFS(int x, int y, int nextIdx) {
visited[x][y] = true;
if (nextIdx == word.length()) {
return true;
}
+
for (int i = 0; i < 4; ++i) {
int xi = x + dx[i];
int yi = y + dy[i];
@@ -56,10 +77,19 @@ private boolean doDFS(int x, int y, int nextIdx) {
}
}
}
- visited[x][y] = false;
+
+ visited[x][y] = false; // Backtrack
return false;
}
+ /**
+ * Main function to check if the word exists in the board. It initiates DFS from any
+ * cell that matches the first character of the word.
+ *
+ * @param board The 2D grid of characters (the board).
+ * @param word The target word to search for in the board.
+ * @return True if the word exists in the board; false otherwise.
+ */
public boolean exist(char[][] board, String word) {
this.board = board;
this.word = word;
diff --git a/src/main/java/com/thealgorithms/bitmanipulation/BcdConversion.java b/src/main/java/com/thealgorithms/bitmanipulation/BcdConversion.java
new file mode 100644
index 000000000000..e6bd35720d9f
--- /dev/null
+++ b/src/main/java/com/thealgorithms/bitmanipulation/BcdConversion.java
@@ -0,0 +1,82 @@
+package com.thealgorithms.bitmanipulation;
+
+/**
+ * This class provides methods to convert between BCD (Binary-Coded Decimal) and decimal numbers.
+ *
+ * BCD is a class of binary encodings of decimal numbers where each decimal digit is represented by a fixed number of binary digits, usually four or eight.
+ *
+ * For more information, refer to the
+ * Binary-Coded Decimal Wikipedia page.
+ *
+ * Example usage:
+ *
+ * int decimal = BcdConversion.bcdToDecimal(0x1234);
+ * System.out.println("BCD 0x1234 to decimal: " + decimal); // Output: 1234
+ *
+ * int bcd = BcdConversion.decimalToBcd(1234);
+ * System.out.println("Decimal 1234 to BCD: " + Integer.toHexString(bcd)); // Output: 0x1234
+ *
+ */
+public final class BcdConversion {
+ private BcdConversion() {
+ }
+
+ /**
+ * Converts a BCD (Binary-Coded Decimal) number to a decimal number.
+ * Steps:
+ *
1. Validate the BCD number to ensure all digits are between 0 and 9.
+ *
2. Extract the last 4 bits (one BCD digit) from the BCD number.
+ *
3. Multiply the extracted digit by the corresponding power of 10 and add it to the decimal number.
+ *
4. Shift the BCD number right by 4 bits to process the next BCD digit.
+ *
5. Repeat steps 1-4 until the BCD number is zero.
+ *
+ * @param bcd The BCD number.
+ * @return The corresponding decimal number.
+ * @throws IllegalArgumentException if the BCD number contains invalid digits.
+ */
+ public static int bcdToDecimal(int bcd) {
+ int decimal = 0;
+ int multiplier = 1;
+
+ // Validate BCD digits
+ while (bcd > 0) {
+ int digit = bcd & 0xF;
+ if (digit > 9) {
+ throw new IllegalArgumentException("Invalid BCD digit: " + digit);
+ }
+ decimal += digit * multiplier;
+ multiplier *= 10;
+ bcd >>= 4;
+ }
+ return decimal;
+ }
+
+ /**
+ * Converts a decimal number to BCD (Binary-Coded Decimal).
+ *
Steps:
+ *
1. Check if the decimal number is within the valid range for BCD (0 to 9999).
+ *
2. Extract the last decimal digit from the decimal number.
+ *
3. Shift the digit to the correct BCD position and add it to the BCD number.
+ *
4. Remove the last decimal digit from the decimal number.
+ *
5. Repeat steps 2-4 until the decimal number is zero.
+ *
+ * @param decimal The decimal number.
+ * @return The corresponding BCD number.
+ * @throws IllegalArgumentException if the decimal number is greater than 9999.
+ */
+ public static int decimalToBcd(int decimal) {
+ if (decimal < 0 || decimal > 9999) {
+ throw new IllegalArgumentException("Value out of bounds for BCD representation: " + decimal);
+ }
+
+ int bcd = 0;
+ int shift = 0;
+ while (decimal > 0) {
+ int digit = decimal % 10;
+ bcd |= (digit << (shift * 4));
+ decimal /= 10;
+ shift++;
+ }
+ return bcd;
+ }
+}
diff --git a/src/main/java/com/thealgorithms/bitmanipulation/BinaryPalindromeCheck.java b/src/main/java/com/thealgorithms/bitmanipulation/BinaryPalindromeCheck.java
new file mode 100644
index 000000000000..0d6fd140c720
--- /dev/null
+++ b/src/main/java/com/thealgorithms/bitmanipulation/BinaryPalindromeCheck.java
@@ -0,0 +1,43 @@
+package com.thealgorithms.bitmanipulation;
+
+/**
+ * This class contains a method to check if the binary representation of a number is a palindrome.
+ *
+ * A binary palindrome is a number whose binary representation is the same when read from left to right and right to left.
+ * For example, the number 9 has a binary representation of 1001, which is a palindrome.
+ * The number 10 has a binary representation of 1010, which is not a palindrome.
+ *
+ *
+ * @author Hardvan
+ */
+public final class BinaryPalindromeCheck {
+ private BinaryPalindromeCheck() {
+ }
+
+ /**
+ * Checks if the binary representation of a number is a palindrome.
+ *
+ * @param x The number to check.
+ * @return True if the binary representation is a palindrome, otherwise false.
+ */
+ public static boolean isBinaryPalindrome(int x) {
+ int reversed = reverseBits(x);
+ return x == reversed;
+ }
+
+ /**
+ * Helper function to reverse all the bits of an integer.
+ *
+ * @param x The number to reverse the bits of.
+ * @return The number with reversed bits.
+ */
+ private static int reverseBits(int x) {
+ int result = 0;
+ while (x > 0) {
+ result <<= 1;
+ result |= (x & 1);
+ x >>= 1;
+ }
+ return result;
+ }
+}
diff --git a/src/main/java/com/thealgorithms/bitmanipulation/BitSwap.java b/src/main/java/com/thealgorithms/bitmanipulation/BitSwap.java
index 40b3097b1276..634c9e7b3b44 100644
--- a/src/main/java/com/thealgorithms/bitmanipulation/BitSwap.java
+++ b/src/main/java/com/thealgorithms/bitmanipulation/BitSwap.java
@@ -1,13 +1,31 @@
package com.thealgorithms.bitmanipulation;
+/**
+ * Utility class for performing bit-swapping operations on integers.
+ * This class cannot be instantiated.
+ */
public final class BitSwap {
private BitSwap() {
}
- /*
- * @brief Swaps the bits at the position posA and posB from data
+
+ /**
+ * Swaps two bits at specified positions in an integer.
+ *
+ * @param data The input integer whose bits need to be swapped
+ * @param posA The position of the first bit (0-based, from least significant)
+ * @param posB The position of the second bit (0-based, from least significant)
+ * @return The modified value with swapped bits
+ * @throws IllegalArgumentException if either position is negative or ≥ 32
*/
+
public static int bitSwap(int data, final int posA, final int posB) {
- if (SingleBitOperations.getBit(data, posA) != SingleBitOperations.getBit(data, posB)) {
+ if (posA < 0 || posA >= Integer.SIZE || posB < 0 || posB >= Integer.SIZE) {
+ throw new IllegalArgumentException("Bit positions must be between 0 and 31");
+ }
+
+ boolean bitA = ((data >> posA) & 1) != 0;
+ boolean bitB = ((data >> posB) & 1) != 0;
+ if (bitA != bitB) {
data ^= (1 << posA) ^ (1 << posB);
}
return data;
diff --git a/src/main/java/com/thealgorithms/bitmanipulation/BitwiseGCD.java b/src/main/java/com/thealgorithms/bitmanipulation/BitwiseGCD.java
new file mode 100644
index 000000000000..516563459256
--- /dev/null
+++ b/src/main/java/com/thealgorithms/bitmanipulation/BitwiseGCD.java
@@ -0,0 +1,147 @@
+package com.thealgorithms.bitmanipulation;
+
+import java.math.BigInteger;
+
+/**
+ * Bitwise GCD implementation with full-range support utilities.
+ *
+ * This class provides a fast binary (Stein's) GCD implementation for {@code long}
+ * inputs and a BigInteger-backed API for full 2's-complement range support (including
+ * {@code Long.MIN_VALUE}). The {@code long} implementation is efficient and avoids
+ * division/modulo operations. For edge-cases that overflow signed-64-bit ranges
+ * (e.g., gcd(Long.MIN_VALUE, 0) = 2^63), use the BigInteger API {@code gcdBig}.
+ *
+ *
Behaviour:
+ *
+ * - {@code gcd(long,long)} : returns non-negative {@code long} gcd for inputs whose
+ * absolute values fit in signed {@code long} (i.e., not causing an unsigned 2^63 result).
+ * If the true gcd does not fit in a signed {@code long} (for example gcd(Long.MIN_VALUE,0) = 2^63)
+ * this method will delegate to BigInteger and throw {@link ArithmeticException} if the
+ * BigInteger result does not fit into a signed {@code long}.
+ * - {@code gcdBig(BigInteger, BigInteger)} : returns the exact gcd as a {@link BigInteger}
+ * and works for the full signed-64-bit range and beyond.
+ *
+ */
+public final class BitwiseGCD {
+
+ private BitwiseGCD() {
+ }
+
+ /**
+ * Computes GCD of two long values using Stein's algorithm (binary GCD).
+ * Handles negative inputs. If either input is {@code Long.MIN_VALUE} the
+ * method delegates to the BigInteger implementation and will throw {@link ArithmeticException}
+ * if the result cannot be represented as a signed {@code long}.
+ *
+ * @param a first value (may be negative)
+ * @param b second value (may be negative)
+ * @return non-negative gcd as a {@code long}
+ * @throws ArithmeticException when the exact gcd does not fit into a signed {@code long}
+ */
+ public static long gcd(long a, long b) {
+ // Trivial cases
+ if (a == 0L) {
+ return absOrThrowIfOverflow(b);
+ }
+ if (b == 0L) {
+ return absOrThrowIfOverflow(a);
+ }
+
+ // If either is Long.MIN_VALUE, absolute value doesn't fit into signed long.
+ if (a == Long.MIN_VALUE || b == Long.MIN_VALUE) {
+ // Delegate to BigInteger and try to return a long if it fits
+ BigInteger g = gcdBig(BigInteger.valueOf(a), BigInteger.valueOf(b));
+ return g.longValueExact();
+ }
+
+ // Work with non-negative long values now (safe because we excluded Long.MIN_VALUE)
+ a = (a < 0) ? -a : a;
+ b = (b < 0) ? -b : b;
+
+ // Count common factors of 2
+ int commonTwos = Long.numberOfTrailingZeros(a | b);
+
+ // Remove all factors of 2 from a
+ a >>= Long.numberOfTrailingZeros(a);
+
+ while (b != 0L) {
+ // Remove all factors of 2 from b
+ b >>= Long.numberOfTrailingZeros(b);
+
+ // Now both a and b are odd. Ensure a <= b
+ if (a > b) {
+ long tmp = a;
+ a = b;
+ b = tmp;
+ }
+
+ // b >= a; subtract a from b (result is even)
+ b = b - a;
+ }
+
+ // Restore common powers of two
+ return a << commonTwos;
+ }
+
+ /**
+ * Helper to return absolute value of x unless x == Long.MIN_VALUE, in which
+ * case we delegate to BigInteger and throw to indicate overflow.
+ */
+ private static long absOrThrowIfOverflow(long x) {
+ if (x == Long.MIN_VALUE) {
+ // |Long.MIN_VALUE| = 2^63 which does not fit into signed long
+ throw new ArithmeticException("Absolute value of Long.MIN_VALUE does not fit into signed long. Use gcdBig() for full-range support.");
+ }
+ return (x < 0) ? -x : x;
+ }
+
+ /**
+ * Computes GCD for an array of {@code long} values. Returns 0 for empty/null arrays.
+ * If any intermediate gcd cannot be represented in signed long (rare), an ArithmeticException
+ * will be thrown.
+ */
+ public static long gcd(long... values) {
+
+ if (values == null || values.length == 0) {
+ return 0L;
+ }
+ long result = values[0];
+ for (int i = 1; i < values.length; i++) {
+ result = gcd(result, values[i]);
+ if (result == 1L) {
+ return 1L; // early exit
+ }
+ }
+ return result;
+ }
+
+ /**
+ * BigInteger-backed gcd that works for the full integer range (and beyond).
+ * This is the recommended method when inputs may be Long.MIN_VALUE or when you
+ * need an exact result even if it is greater than Long.MAX_VALUE.
+ * @param a first value (may be negative)
+ * @param b second value (may be negative)
+ * @return non-negative gcd as a {@link BigInteger}
+ */
+ public static BigInteger gcdBig(BigInteger a, BigInteger b) {
+
+ if (a == null || b == null) {
+ throw new NullPointerException("Arguments must not be null");
+ }
+ return a.abs().gcd(b.abs());
+ }
+
+ /**
+ * Convenience overload that accepts signed-64 inputs and returns BigInteger gcd.
+ */
+ public static BigInteger gcdBig(long a, long b) {
+ return gcdBig(BigInteger.valueOf(a), BigInteger.valueOf(b));
+ }
+
+ /**
+ * int overload for convenience.
+ */
+ public static int gcd(int a, int b) {
+ return (int) gcd((long) a, (long) b);
+ }
+}
diff --git a/src/main/java/com/thealgorithms/bitmanipulation/BooleanAlgebraGates.java b/src/main/java/com/thealgorithms/bitmanipulation/BooleanAlgebraGates.java
new file mode 100644
index 000000000000..869466320831
--- /dev/null
+++ b/src/main/java/com/thealgorithms/bitmanipulation/BooleanAlgebraGates.java
@@ -0,0 +1,111 @@
+package com.thealgorithms.bitmanipulation;
+
+import java.util.List;
+
+/**
+ * Implements various Boolean algebra gates (AND, OR, NOT, XOR, NAND, NOR)
+ */
+public final class BooleanAlgebraGates {
+
+ private BooleanAlgebraGates() {
+ // Prevent instantiation
+ }
+
+ /**
+ * Represents a Boolean gate that takes multiple inputs and returns a result.
+ */
+ interface BooleanGate {
+ /**
+ * Evaluates the gate with the given inputs.
+ *
+ * @param inputs The input values for the gate.
+ * @return The result of the evaluation.
+ */
+ boolean evaluate(List inputs);
+ }
+
+ /**
+ * AND Gate implementation.
+ * Returns true if all inputs are true; otherwise, false.
+ */
+ static class ANDGate implements BooleanGate {
+ @Override
+ public boolean evaluate(List inputs) {
+ for (boolean input : inputs) {
+ if (!input) {
+ return false;
+ }
+ }
+ return true;
+ }
+ }
+
+ /**
+ * OR Gate implementation.
+ * Returns true if at least one input is true; otherwise, false.
+ */
+ static class ORGate implements BooleanGate {
+ @Override
+ public boolean evaluate(List inputs) {
+ for (boolean input : inputs) {
+ if (input) {
+ return true;
+ }
+ }
+ return false;
+ }
+ }
+
+ /**
+ * NOT Gate implementation (Unary operation).
+ * Negates a single input value.
+ */
+ static class NOTGate {
+ /**
+ * Evaluates the negation of the input.
+ *
+ * @param input The input value to be negated.
+ * @return The negated value.
+ */
+ public boolean evaluate(boolean input) {
+ return !input;
+ }
+ }
+
+ /**
+ * XOR Gate implementation.
+ * Returns true if an odd number of inputs are true; otherwise, false.
+ */
+ static class XORGate implements BooleanGate {
+ @Override
+ public boolean evaluate(List inputs) {
+ boolean result = false;
+ for (boolean input : inputs) {
+ result ^= input;
+ }
+ return result;
+ }
+ }
+
+ /**
+ * NAND Gate implementation.
+ * Returns true if at least one input is false; otherwise, false.
+ */
+ static class NANDGate implements BooleanGate {
+ @Override
+ public boolean evaluate(List inputs) {
+ return !new ANDGate().evaluate(inputs); // Equivalent to negation of AND
+ }
+ }
+
+ /**
+ * NOR Gate implementation.
+ * Returns true if all inputs are false; otherwise, false.
+ */
+ static class NORGate implements BooleanGate {
+ @Override
+ public boolean evaluate(List inputs) {
+ return !new ORGate().evaluate(inputs); // Equivalent to negation of OR
+ }
+ }
+}
diff --git a/src/main/java/com/thealgorithms/bitmanipulation/ClearLeftmostSetBit.java b/src/main/java/com/thealgorithms/bitmanipulation/ClearLeftmostSetBit.java
new file mode 100644
index 000000000000..3e9a4a21183f
--- /dev/null
+++ b/src/main/java/com/thealgorithms/bitmanipulation/ClearLeftmostSetBit.java
@@ -0,0 +1,39 @@
+package com.thealgorithms.bitmanipulation;
+
+/**
+ * ClearLeftmostSetBit class contains a method to clear the leftmost set bit of a number.
+ * The leftmost set bit is the leftmost bit that is set to 1 in the binary representation of a number.
+ *
+ * Example:
+ * 26 (11010) -> 10 (01010)
+ * 1 (1) -> 0 (0)
+ * 7 (111) -> 3 (011)
+ * 6 (0110) -> 2 (0010)
+ *
+ * @author Hardvan
+ */
+public final class ClearLeftmostSetBit {
+ private ClearLeftmostSetBit() {
+ }
+
+ /**
+ * Clears the leftmost set bit (1) of a given number.
+ * Step 1: Find the position of the leftmost set bit
+ * Step 2: Create a mask with all bits set except for the leftmost set bit
+ * Step 3: Clear the leftmost set bit using AND with the mask
+ *
+ * @param num The input number.
+ * @return The number after clearing the leftmost set bit.
+ */
+ public static int clearLeftmostSetBit(int num) {
+ int pos = 0;
+ int temp = num;
+ while (temp > 0) {
+ temp >>= 1;
+ pos++;
+ }
+
+ int mask = ~(1 << (pos - 1));
+ return num & mask;
+ }
+}
diff --git a/src/main/java/com/thealgorithms/bitmanipulation/CountBitsFlip.java b/src/main/java/com/thealgorithms/bitmanipulation/CountBitsFlip.java
new file mode 100644
index 000000000000..8d2c757e5e0a
--- /dev/null
+++ b/src/main/java/com/thealgorithms/bitmanipulation/CountBitsFlip.java
@@ -0,0 +1,63 @@
+package com.thealgorithms.bitmanipulation;
+
+/**
+ * Implementation to count number of bits to be flipped to convert A to B
+ *
+ * Problem: Given two numbers A and B, count the number of bits needed to be
+ * flipped to convert A to B.
+ *
+ * Example:
+ * A = 10 (01010 in binary)
+ * B = 20 (10100 in binary)
+ * XOR = 30 (11110 in binary) - positions where bits differ
+ * Answer: 4 bits need to be flipped
+ *
+ * Time Complexity: O(log n) - where n is the number of set bits
+ * Space Complexity: O(1)
+ *
+ *@author [Yash Rajput](https://github.com/the-yash-rajput)
+ */
+public final class CountBitsFlip {
+
+ private CountBitsFlip() {
+ throw new AssertionError("No instances.");
+ }
+
+ /**
+ * Counts the number of bits that need to be flipped to convert a to b
+ *
+ * Algorithm:
+ * 1. XOR a and b to get positions where bits differ
+ * 2. Count the number of set bits in the XOR result
+ * 3. Use Brian Kernighan's algorithm: n & (n-1) removes rightmost set bit
+ *
+ * @param a the source number
+ * @param b the target number
+ * @return the number of bits to flip to convert A to B
+ */
+ public static long countBitsFlip(long a, long b) {
+ int count = 0;
+
+ // XOR gives us positions where bits differ
+ long xorResult = a ^ b;
+
+ // Count set bits using Brian Kernighan's algorithm
+ while (xorResult != 0) {
+ xorResult = xorResult & (xorResult - 1); // Remove rightmost set bit
+ count++;
+ }
+
+ return count;
+ }
+
+ /**
+ * Alternative implementation using Long.bitCount().
+ *
+ * @param a the source number
+ * @param b the target number
+ * @return the number of bits to flip to convert a to b
+ */
+ public static long countBitsFlipAlternative(long a, long b) {
+ return Long.bitCount(a ^ b);
+ }
+}
diff --git a/src/main/java/com/thealgorithms/bitmanipulation/CountLeadingZeros.java b/src/main/java/com/thealgorithms/bitmanipulation/CountLeadingZeros.java
new file mode 100644
index 000000000000..318334f0b951
--- /dev/null
+++ b/src/main/java/com/thealgorithms/bitmanipulation/CountLeadingZeros.java
@@ -0,0 +1,39 @@
+package com.thealgorithms.bitmanipulation;
+
+/**
+ * CountLeadingZeros class contains a method to count the number of leading zeros in the binary representation of a number.
+ * The number of leading zeros is the number of zeros before the leftmost 1 bit.
+ * For example, the number 5 has 29 leading zeros in its 32-bit binary representation.
+ * The number 0 has 32 leading zeros.
+ * The number 1 has 31 leading zeros.
+ * The number -1 has no leading zeros.
+ *
+ * @author Hardvan
+ */
+public final class CountLeadingZeros {
+ private CountLeadingZeros() {
+ }
+
+ /**
+ * Counts the number of leading zeros in the binary representation of a number.
+ * Method: Keep shifting the mask to the right until the leftmost bit is 1.
+ * The number of shifts is the number of leading zeros.
+ *
+ * @param num The input number.
+ * @return The number of leading zeros.
+ */
+ public static int countLeadingZeros(int num) {
+ if (num == 0) {
+ return 32;
+ }
+
+ int count = 0;
+ int mask = 1 << 31;
+ while ((mask & num) == 0) {
+ count++;
+ mask >>>= 1;
+ }
+
+ return count;
+ }
+}
diff --git a/src/main/java/com/thealgorithms/bitmanipulation/CountSetBits.java b/src/main/java/com/thealgorithms/bitmanipulation/CountSetBits.java
index eb0886e30292..242f35fc35f2 100644
--- a/src/main/java/com/thealgorithms/bitmanipulation/CountSetBits.java
+++ b/src/main/java/com/thealgorithms/bitmanipulation/CountSetBits.java
@@ -48,4 +48,32 @@ public long countSetBits(long num) {
}
return cnt;
}
+
+ /**
+ * This approach takes O(1) running time to count the set bits, but requires a pre-processing.
+ *
+ * So, we divide our 32-bit input into 8-bit chunks, with four chunks. We have 8 bits in each chunk.
+ *
+ * Then the range is from 0-255 (0 to 2^7).
+ * So, we may need to count set bits from 0 to 255 in individual chunks.
+ *
+ * @param num takes a long number
+ * @return the count of set bits in the binary equivalent
+ */
+ public int lookupApproach(int num) {
+ int[] table = new int[256];
+ table[0] = 0;
+
+ for (int i = 1; i < 256; i++) {
+ table[i] = (i & 1) + table[i >> 1]; // i >> 1 equals to i/2
+ }
+
+ int res = 0;
+ for (int i = 0; i < 4; i++) {
+ res += table[num & 0xff];
+ num >>= 8;
+ }
+
+ return res;
+ }
}
diff --git a/src/main/java/com/thealgorithms/bitmanipulation/FindNthBit.java b/src/main/java/com/thealgorithms/bitmanipulation/FindNthBit.java
new file mode 100644
index 000000000000..7a35fc3feebf
--- /dev/null
+++ b/src/main/java/com/thealgorithms/bitmanipulation/FindNthBit.java
@@ -0,0 +1,46 @@
+package com.thealgorithms.bitmanipulation;
+
+/**
+ * A utility class to find the Nth bit of a given number.
+ *
+ * This class provides a method to extract the value of the Nth bit (either 0 or 1)
+ * from the binary representation of a given integer.
+ *
+ *
Example:
+ *
{@code
+ * int result = FindNthBit.findNthBit(5, 2); // returns 0 as the 2nd bit of 5 (binary 101) is 0.
+ * }
+ *
+ * Author: Tuhinm2002
+ */
+public final class FindNthBit {
+
+ /**
+ * Private constructor to prevent instantiation.
+ *
+ *
This is a utility class, and it should not be instantiated.
+ * Attempting to instantiate this class will throw an UnsupportedOperationException.
+ */
+ private FindNthBit() {
+ throw new UnsupportedOperationException("Utility class");
+ }
+
+ /**
+ * Finds the value of the Nth bit of the given number.
+ *
+ *
This method uses bitwise operations to extract the Nth bit from the
+ * binary representation of the given integer.
+ *
+ * @param num the integer number whose Nth bit is to be found
+ * @param n the bit position (1-based) to retrieve
+ * @return the value of the Nth bit (0 or 1)
+ * @throws IllegalArgumentException if the bit position is less than 1
+ */
+ public static int findNthBit(int num, int n) {
+ if (n < 1) {
+ throw new IllegalArgumentException("Bit position must be greater than or equal to 1.");
+ }
+ // Shifting the number to the right by (n - 1) positions and checking the last bit
+ return (num & (1 << (n - 1))) >> (n - 1);
+ }
+}
diff --git a/src/main/java/com/thealgorithms/bitmanipulation/FirstDifferentBit.java b/src/main/java/com/thealgorithms/bitmanipulation/FirstDifferentBit.java
new file mode 100644
index 000000000000..9a761c572e2c
--- /dev/null
+++ b/src/main/java/com/thealgorithms/bitmanipulation/FirstDifferentBit.java
@@ -0,0 +1,33 @@
+package com.thealgorithms.bitmanipulation;
+
+/**
+ * This class provides a method to find the first differing bit
+ * between two integers.
+ *
+ * Example:
+ * x = 10 (1010 in binary)
+ * y = 12 (1100 in binary)
+ * The first differing bit is at index 1 (0-based)
+ * So, the output will be 1
+ *
+ * @author Hardvan
+ */
+public final class FirstDifferentBit {
+ private FirstDifferentBit() {
+ }
+
+ /**
+ * Identifies the index of the first differing bit between two integers.
+ * Steps:
+ * 1. XOR the two integers to get the differing bits
+ * 2. Find the index of the first set bit in XOR result
+ *
+ * @param x the first integer
+ * @param y the second integer
+ * @return the index of the first differing bit (0-based)
+ */
+ public static int firstDifferentBit(int x, int y) {
+ int diff = x ^ y;
+ return Integer.numberOfTrailingZeros(diff);
+ }
+}
diff --git a/src/main/java/com/thealgorithms/bitmanipulation/GenerateSubsets.java b/src/main/java/com/thealgorithms/bitmanipulation/GenerateSubsets.java
new file mode 100644
index 000000000000..f1b812495c1b
--- /dev/null
+++ b/src/main/java/com/thealgorithms/bitmanipulation/GenerateSubsets.java
@@ -0,0 +1,44 @@
+package com.thealgorithms.bitmanipulation;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * This class provides a method to generate all subsets (power set)
+ * of a given set using bit manipulation.
+ *
+ * @author Hardvan
+ */
+public final class GenerateSubsets {
+ private GenerateSubsets() {
+ }
+
+ /**
+ * Generates all subsets of a given set using bit manipulation.
+ * Steps:
+ * 1. Iterate over all numbers from 0 to 2^n - 1.
+ * 2. For each number, iterate over all bits from 0 to n - 1.
+ * 3. If the i-th bit of the number is set, add the i-th element of the set to the current subset.
+ * 4. Add the current subset to the list of subsets.
+ * 5. Return the list of subsets.
+ *
+ * @param set the input set of integers
+ * @return a list of all subsets represented as lists of integers
+ */
+ public static List> generateSubsets(int[] set) {
+ int n = set.length;
+ List> subsets = new ArrayList<>();
+
+ for (int mask = 0; mask < (1 << n); mask++) {
+ List subset = new ArrayList<>();
+ for (int i = 0; i < n; i++) {
+ if ((mask & (1 << i)) != 0) {
+ subset.add(set[i]);
+ }
+ }
+ subsets.add(subset);
+ }
+
+ return subsets;
+ }
+}
diff --git a/src/main/java/com/thealgorithms/bitmanipulation/GrayCodeConversion.java b/src/main/java/com/thealgorithms/bitmanipulation/GrayCodeConversion.java
new file mode 100644
index 000000000000..83cd30c7d50a
--- /dev/null
+++ b/src/main/java/com/thealgorithms/bitmanipulation/GrayCodeConversion.java
@@ -0,0 +1,44 @@
+package com.thealgorithms.bitmanipulation;
+
+/**
+ * Gray code is a binary numeral system where two successive values differ in only one bit.
+ * This is a simple conversion between binary and Gray code.
+ * Example:
+ * 7 -> 0111 -> 0100 -> 4
+ * 4 -> 0100 -> 0111 -> 7
+ * 0 -> 0000 -> 0000 -> 0
+ * 1 -> 0001 -> 0000 -> 0
+ * 2 -> 0010 -> 0011 -> 3
+ * 3 -> 0011 -> 0010 -> 2
+ *
+ * @author Hardvan
+ */
+public final class GrayCodeConversion {
+ private GrayCodeConversion() {
+ }
+
+ /**
+ * Converts a binary number to Gray code.
+ *
+ * @param num The binary number.
+ * @return The corresponding Gray code.
+ */
+ public static int binaryToGray(int num) {
+ return num ^ (num >> 1);
+ }
+
+ /**
+ * Converts a Gray code number back to binary.
+ *
+ * @param gray The Gray code number.
+ * @return The corresponding binary number.
+ */
+ public static int grayToBinary(int gray) {
+ int binary = gray;
+ while (gray > 0) {
+ gray >>= 1;
+ binary ^= gray;
+ }
+ return binary;
+ }
+}
diff --git a/src/main/java/com/thealgorithms/bitmanipulation/HammingDistance.java b/src/main/java/com/thealgorithms/bitmanipulation/HammingDistance.java
new file mode 100644
index 000000000000..4c24909ef234
--- /dev/null
+++ b/src/main/java/com/thealgorithms/bitmanipulation/HammingDistance.java
@@ -0,0 +1,29 @@
+package com.thealgorithms.bitmanipulation;
+
+/**
+ * The Hamming distance between two integers is the number of positions at which the corresponding bits are different.
+ * Given two integers x and y, calculate the Hamming distance.
+ * Example:
+ * Input: x = 1, y = 4
+ * Output: 2
+ * Explanation: 1 (0001) and 4 (0100) have 2 differing bits.
+ *
+ * @author Hardvan
+ */
+public final class HammingDistance {
+ private HammingDistance() {
+ }
+
+ /**
+ * Calculates the Hamming distance between two integers.
+ * The Hamming distance is the number of differing bits between the two integers.
+ *
+ * @param x The first integer.
+ * @param y The second integer.
+ * @return The Hamming distance (number of differing bits).
+ */
+ public static int hammingDistance(int x, int y) {
+ int xor = x ^ y;
+ return Integer.bitCount(xor);
+ }
+}
diff --git a/src/main/java/com/thealgorithms/bitmanipulation/HigherLowerPowerOfTwo.java b/src/main/java/com/thealgorithms/bitmanipulation/HigherLowerPowerOfTwo.java
new file mode 100644
index 000000000000..0fb058b2b8a3
--- /dev/null
+++ b/src/main/java/com/thealgorithms/bitmanipulation/HigherLowerPowerOfTwo.java
@@ -0,0 +1,54 @@
+package com.thealgorithms.bitmanipulation;
+
+/**
+ * HigherLowerPowerOfTwo class has two methods to find the next higher and lower power of two.
+ *
+ * nextHigherPowerOfTwo method finds the next higher power of two.
+ * nextLowerPowerOfTwo method finds the next lower power of two.
+ * Both methods take an integer as input and return the next higher or lower power of two.
+ * If the input is less than 1, the next higher power of two is 1.
+ * If the input is less than or equal to 1, the next lower power of two is 0.
+ * nextHigherPowerOfTwo method uses bitwise operations to find the next higher power of two.
+ * nextLowerPowerOfTwo method uses Integer.highestOneBit method to find the next lower power of two.
+ * The time complexity of both methods is O(1).
+ * The space complexity of both methods is O(1).
+ *
+ *
+ * @author Hardvan
+ */
+public final class HigherLowerPowerOfTwo {
+ private HigherLowerPowerOfTwo() {
+ }
+
+ /**
+ * Finds the next higher power of two.
+ *
+ * @param x The given number.
+ * @return The next higher power of two.
+ */
+ public static int nextHigherPowerOfTwo(int x) {
+ if (x < 1) {
+ return 1;
+ }
+ x--;
+ x |= x >> 1;
+ x |= x >> 2;
+ x |= x >> 4;
+ x |= x >> 8;
+ x |= x >> 16;
+ return x + 1;
+ }
+
+ /**
+ * Finds the next lower power of two.
+ *
+ * @param x The given number.
+ * @return The next lower power of two.
+ */
+ public static int nextLowerPowerOfTwo(int x) {
+ if (x < 1) {
+ return 0;
+ }
+ return Integer.highestOneBit(x);
+ }
+}
diff --git a/src/main/java/com/thealgorithms/bitmanipulation/HighestSetBit.java b/src/main/java/com/thealgorithms/bitmanipulation/HighestSetBit.java
index 6b53b1aa182b..2398b8214371 100644
--- a/src/main/java/com/thealgorithms/bitmanipulation/HighestSetBit.java
+++ b/src/main/java/com/thealgorithms/bitmanipulation/HighestSetBit.java
@@ -1,17 +1,39 @@
package com.thealgorithms.bitmanipulation;
+
import java.util.Optional;
/**
* Find Highest Set Bit
- * This class provides a function calculating the position (or index)
- * of the most significant bit being set to 1 in a given integer.
- * @author Bama Charan Chhandogi (https://github.com/BamaCharanChhandogi)
+ *
+ * This class provides a utility method to calculate the position of the highest
+ * (most significant) bit that is set to 1 in a given non-negative integer.
+ * It is often used in bit manipulation tasks to find the left-most set bit in binary
+ * representation of a number.
+ *
+ * Example:
+ * - For input 18 (binary 10010), the highest set bit is at position 4 (zero-based index).
+ *
+ * @author Bama Charan Chhandogi
+ * @version 1.0
+ * @since 2021-06-23
*/
-
public final class HighestSetBit {
+
private HighestSetBit() {
}
+ /**
+ * Finds the highest (most significant) set bit in the given integer.
+ * The method returns the position (index) of the highest set bit as an {@link Optional}.
+ *
+ * - If the number is 0, no bits are set, and the method returns {@link Optional#empty()}.
+ * - If the number is negative, the method throws {@link IllegalArgumentException}.
+ *
+ * @param num The input integer for which the highest set bit is to be found. It must be non-negative.
+ * @return An {@link Optional} containing the index of the highest set bit (zero-based).
+ * Returns {@link Optional#empty()} if the number is 0.
+ * @throws IllegalArgumentException if the input number is negative.
+ */
public static Optional findHighestSetBit(int num) {
if (num < 0) {
throw new IllegalArgumentException("Input cannot be negative");
@@ -27,6 +49,6 @@ public static Optional findHighestSetBit(int num) {
position++;
}
- return Optional.of(position - 1);
+ return Optional.of(position - 1); // Subtract 1 to convert to zero-based index
}
}
diff --git a/src/main/java/com/thealgorithms/bitmanipulation/IndexOfRightMostSetBit.java b/src/main/java/com/thealgorithms/bitmanipulation/IndexOfRightMostSetBit.java
index b825916a8674..1b8962344ea7 100644
--- a/src/main/java/com/thealgorithms/bitmanipulation/IndexOfRightMostSetBit.java
+++ b/src/main/java/com/thealgorithms/bitmanipulation/IndexOfRightMostSetBit.java
@@ -1,13 +1,27 @@
package com.thealgorithms.bitmanipulation;
/**
- * Find The Index Of Right Most SetBit
- * @author Bama Charan Chhandogi (https://github.com/BamaCharanChhandogi)
+ * Utility class for bit manipulation operations.
+ * This class provides methods to work with bitwise operations.
+ * Specifically, it includes a method to find the index of the rightmost set bit
+ * in an integer.
+ * This class is not meant to be instantiated.
+ *
+ * Author: Bama Charan Chhandogi (https://github.com/BamaCharanChhandogi)
*/
-
public final class IndexOfRightMostSetBit {
+
private IndexOfRightMostSetBit() {
}
+
+ /**
+ * Finds the index of the rightmost set bit in the given integer.
+ * The index is zero-based, meaning the rightmost bit has an index of 0.
+ *
+ * @param n the integer to check for the rightmost set bit
+ * @return the index of the rightmost set bit; -1 if there are no set bits
+ * (i.e., the input integer is 0)
+ */
public static int indexOfRightMostSetBit(int n) {
if (n == 0) {
return -1; // No set bits
@@ -16,7 +30,7 @@ public static int indexOfRightMostSetBit(int n) {
// Handle negative numbers by finding the two's complement
if (n < 0) {
n = -n;
- n = n & (~n + 1); // Get the rightmost set bit in positive form
+ n = n & (~n + 1); // Isolate the rightmost set bit
}
int index = 0;
diff --git a/src/main/java/com/thealgorithms/bitmanipulation/IsPowerTwo.java b/src/main/java/com/thealgorithms/bitmanipulation/IsPowerTwo.java
index 54d28d4d22cc..4cdf3c6faa3e 100644
--- a/src/main/java/com/thealgorithms/bitmanipulation/IsPowerTwo.java
+++ b/src/main/java/com/thealgorithms/bitmanipulation/IsPowerTwo.java
@@ -1,13 +1,27 @@
package com.thealgorithms.bitmanipulation;
/**
- * Is number power of 2
+ * Utility class for checking if a number is a power of two.
+ * A power of two is a number that can be expressed as 2^n where n is a non-negative integer.
+ * This class provides a method to determine if a given integer is a power of two using bit manipulation.
+ *
* @author Bama Charan Chhandogi (https://github.com/BamaCharanChhandogi)
*/
-
public final class IsPowerTwo {
private IsPowerTwo() {
}
+
+ /**
+ * Checks if the given integer is a power of two.
+ *
+ * A number is considered a power of two if it is greater than zero and
+ * has exactly one '1' bit in its binary representation. This method
+ * uses the property that for any power of two (n), the expression
+ * (n & (n - 1)) will be zero.
+ *
+ * @param number the integer to check
+ * @return true if the number is a power of two, false otherwise
+ */
public static boolean isPowerTwo(int number) {
if (number <= 0) {
return false;
diff --git a/src/main/java/com/thealgorithms/bitmanipulation/LowestSetBit.java b/src/main/java/com/thealgorithms/bitmanipulation/LowestSetBit.java
new file mode 100644
index 000000000000..127b6fa2c0b1
--- /dev/null
+++ b/src/main/java/com/thealgorithms/bitmanipulation/LowestSetBit.java
@@ -0,0 +1,34 @@
+package com.thealgorithms.bitmanipulation;
+
+/**
+ * Lowest Set Bit
+ * @author Prayas Kumar (https://github.com/prayas7102)
+ */
+
+public final class LowestSetBit {
+ // Private constructor to hide the default public one
+ private LowestSetBit() {
+ }
+ /**
+ * Isolates the lowest set bit of the given number. For example, if n = 18
+ * (binary: 10010), the result will be 2 (binary: 00010).
+ *
+ * @param n the number whose lowest set bit will be isolated
+ * @return the isolated lowest set bit of n
+ */
+ public static int isolateLowestSetBit(int n) {
+ // Isolate the lowest set bit using n & -n
+ return n & -n;
+ }
+ /**
+ * Clears the lowest set bit of the given number.
+ * For example, if n = 18 (binary: 10010), the result will be 16 (binary: 10000).
+ *
+ * @param n the number whose lowest set bit will be cleared
+ * @return the number after clearing its lowest set bit
+ */
+ public static int clearLowestSetBit(int n) {
+ // Clear the lowest set bit using n & (n - 1)
+ return n & (n - 1);
+ }
+}
diff --git a/src/main/java/com/thealgorithms/bitmanipulation/ModuloPowerOfTwo.java b/src/main/java/com/thealgorithms/bitmanipulation/ModuloPowerOfTwo.java
new file mode 100644
index 000000000000..537a046f77e4
--- /dev/null
+++ b/src/main/java/com/thealgorithms/bitmanipulation/ModuloPowerOfTwo.java
@@ -0,0 +1,28 @@
+package com.thealgorithms.bitmanipulation;
+
+/**
+ * This class provides a method to compute the remainder
+ * of a number when divided by a power of two (2^n)
+ * without using division or modulo operations.
+ *
+ * @author Hardvan
+ */
+public final class ModuloPowerOfTwo {
+ private ModuloPowerOfTwo() {
+ }
+
+ /**
+ * Computes the remainder of a given integer when divided by 2^n.
+ *
+ * @param x the input number
+ * @param n the exponent (power of two)
+ * @return the remainder of x divided by 2^n
+ */
+ public static int moduloPowerOfTwo(int x, int n) {
+ if (n <= 0) {
+ throw new IllegalArgumentException("The exponent must be positive");
+ }
+
+ return x & ((1 << n) - 1);
+ }
+}
diff --git a/src/main/java/com/thealgorithms/bitmanipulation/NextHigherSameBitCount.java b/src/main/java/com/thealgorithms/bitmanipulation/NextHigherSameBitCount.java
new file mode 100644
index 000000000000..6a764d806279
--- /dev/null
+++ b/src/main/java/com/thealgorithms/bitmanipulation/NextHigherSameBitCount.java
@@ -0,0 +1,30 @@
+package com.thealgorithms.bitmanipulation;
+
+/**
+ * This class provides a method to find the next higher number
+ * with the same number of set bits as the given number.
+ *
+ * @author Hardvan
+ */
+public final class NextHigherSameBitCount {
+ private NextHigherSameBitCount() {
+ }
+
+ /**
+ * Finds the next higher integer with the same number of set bits.
+ * Steps:
+ * 1. Find {@code c}, the rightmost set bit of {@code n}.
+ * 2. Find {@code r}, the rightmost set bit of {@code n + c}.
+ * 3. Swap the bits of {@code r} and {@code n} to the right of {@code c}.
+ * 4. Shift the bits of {@code r} and {@code n} to the right of {@code c} to the rightmost.
+ * 5. Combine the results of steps 3 and 4.
+ *
+ * @param n the input number
+ * @return the next higher integer with the same set bit count
+ */
+ public static int nextHigherSameBitCount(int n) {
+ int c = n & -n;
+ int r = n + c;
+ return (((r ^ n) >> 2) / c) | r;
+ }
+}
diff --git a/src/main/java/com/thealgorithms/bitmanipulation/NonRepeatingNumberFinder.java b/src/main/java/com/thealgorithms/bitmanipulation/NonRepeatingNumberFinder.java
index 07476a8b9476..17e1a73ec062 100644
--- a/src/main/java/com/thealgorithms/bitmanipulation/NonRepeatingNumberFinder.java
+++ b/src/main/java/com/thealgorithms/bitmanipulation/NonRepeatingNumberFinder.java
@@ -1,14 +1,30 @@
package com.thealgorithms.bitmanipulation;
/**
- * Find Non Repeating Number
+ * A utility class to find the non-repeating number in an array where every other number repeats.
+ * This class contains a method to identify the single unique number using bit manipulation.
+ *
+ * The solution leverages the properties of the XOR operation, which states that:
+ * - x ^ x = 0 for any integer x (a number XORed with itself is zero)
+ * - x ^ 0 = x for any integer x (a number XORed with zero is the number itself)
+ *
+ * Using these properties, we can find the non-repeating number in linear time with constant space.
+ *
+ * Example:
+ * Given the input array [2, 3, 5, 2, 3], the output will be 5 since it does not repeat.
+ *
* @author Bama Charan Chhandogi (https://github.com/BamaCharanChhandogi)
*/
-
public final class NonRepeatingNumberFinder {
private NonRepeatingNumberFinder() {
}
+ /**
+ * Finds the non-repeating number in the given array.
+ *
+ * @param arr an array of integers where every number except one appears twice
+ * @return the integer that appears only once in the array or 0 if the array is empty
+ */
public static int findNonRepeatingNumber(int[] arr) {
int result = 0;
for (int num : arr) {
diff --git a/src/main/java/com/thealgorithms/bitmanipulation/NumberAppearingOddTimes.java b/src/main/java/com/thealgorithms/bitmanipulation/NumberAppearingOddTimes.java
new file mode 100644
index 000000000000..bd4868d4dbd5
--- /dev/null
+++ b/src/main/java/com/thealgorithms/bitmanipulation/NumberAppearingOddTimes.java
@@ -0,0 +1,41 @@
+package com.thealgorithms.bitmanipulation;
+
+/**
+ * This class provides a method to find the element that appears an
+ * odd number of times in an array. All other elements in the array
+ * must appear an even number of times for the logic to work.
+ *
+ * The solution uses the XOR operation, which has the following properties:
+ * - a ^ a = 0 (XOR-ing the same numbers cancels them out)
+ * - a ^ 0 = a
+ * - XOR is commutative and associative.
+ *
+ * Time Complexity: O(n), where n is the size of the array.
+ * Space Complexity: O(1), as no extra space is used.
+ *
+ * Usage Example:
+ * int result = NumberAppearingOddTimes.findOddOccurrence(new int[]{1, 2, 1, 2, 3});
+ * // result will be 3
+ *
+ * @author Lakshyajeet Singh Goyal (https://github.com/DarkMatter-999)
+ */
+
+public final class NumberAppearingOddTimes {
+ private NumberAppearingOddTimes() {
+ }
+
+ /**
+ * Finds the element in the array that appears an odd number of times.
+ *
+ * @param arr the input array containing integers, where all elements
+ * except one appear an even number of times.
+ * @return the integer that appears an odd number of times.
+ */
+ public static int findOddOccurrence(int[] arr) {
+ int result = 0;
+ for (int num : arr) {
+ result ^= num;
+ }
+ return result;
+ }
+}
diff --git a/src/main/java/com/thealgorithms/bitmanipulation/NumbersDifferentSigns.java b/src/main/java/com/thealgorithms/bitmanipulation/NumbersDifferentSigns.java
index 8e0946f0eb23..a2da37aa81ee 100644
--- a/src/main/java/com/thealgorithms/bitmanipulation/NumbersDifferentSigns.java
+++ b/src/main/java/com/thealgorithms/bitmanipulation/NumbersDifferentSigns.java
@@ -1,14 +1,29 @@
package com.thealgorithms.bitmanipulation;
/**
- * Numbers Different Signs
+ * This class provides a method to determine whether two integers have
+ * different signs. It utilizes the XOR operation on the two numbers:
+ *
+ * - If two numbers have different signs, their most significant bits
+ * (sign bits) will differ, resulting in a negative XOR result.
+ * - If two numbers have the same sign, the XOR result will be non-negative.
+ *
+ * Time Complexity: O(1) - Constant time operation.
+ * Space Complexity: O(1) - No extra space used.
+ *
* @author Bama Charan Chhandogi
*/
-
public final class NumbersDifferentSigns {
private NumbersDifferentSigns() {
}
+ /**
+ * Determines if two integers have different signs using bitwise XOR.
+ *
+ * @param num1 the first integer
+ * @param num2 the second integer
+ * @return true if the two numbers have different signs, false otherwise
+ */
public static boolean differentSigns(int num1, int num2) {
return (num1 ^ num2) < 0;
}
diff --git a/src/main/java/com/thealgorithms/bitmanipulation/OneBitDifference.java b/src/main/java/com/thealgorithms/bitmanipulation/OneBitDifference.java
new file mode 100644
index 000000000000..afec0188e299
--- /dev/null
+++ b/src/main/java/com/thealgorithms/bitmanipulation/OneBitDifference.java
@@ -0,0 +1,32 @@
+package com.thealgorithms.bitmanipulation;
+
+/**
+ * This class provides a method to detect if two integers
+ * differ by exactly one bit flip.
+ *
+ * Example:
+ * 1 (0001) and 2 (0010) differ by exactly one bit flip.
+ * 7 (0111) and 3 (0011) differ by exactly one bit flip.
+ *
+ * @author Hardvan
+ */
+public final class OneBitDifference {
+ private OneBitDifference() {
+ }
+
+ /**
+ * Checks if two integers differ by exactly one bit.
+ *
+ * @param x the first integer
+ * @param y the second integer
+ * @return true if x and y differ by exactly one bit, false otherwise
+ */
+ public static boolean differByOneBit(int x, int y) {
+ if (x == y) {
+ return false;
+ }
+
+ int xor = x ^ y;
+ return (xor & (xor - 1)) == 0;
+ }
+}
diff --git a/src/main/java/com/thealgorithms/bitmanipulation/OnesComplement.java b/src/main/java/com/thealgorithms/bitmanipulation/OnesComplement.java
new file mode 100644
index 000000000000..aae3a996e49d
--- /dev/null
+++ b/src/main/java/com/thealgorithms/bitmanipulation/OnesComplement.java
@@ -0,0 +1,37 @@
+package com.thealgorithms.bitmanipulation;
+
+/**
+ * @author - https://github.com/Monk-AbhinayVerma
+ * @Wikipedia - https://en.wikipedia.org/wiki/Ones%27_complement
+ * The class OnesComplement computes the complement of binary number
+ * and returns
+ * the complemented binary string.
+ * @return the complimented binary string
+ */
+public final class OnesComplement {
+ private OnesComplement() {
+ }
+
+ /**
+ * Returns the 1's complement of a binary string.
+ *
+ * @param binary A string representing a binary number (e.g., "1010").
+ * @return A string representing the 1's complement.
+ * @throws IllegalArgumentException if the input is null or contains characters other than '0' or '1'.
+ */
+ public static String onesComplement(String binary) {
+ if (binary == null || binary.isEmpty()) {
+ throw new IllegalArgumentException("Input must be a non-empty binary string.");
+ }
+
+ StringBuilder complement = new StringBuilder(binary.length());
+ for (char bit : binary.toCharArray()) {
+ switch (bit) {
+ case '0' -> complement.append('1');
+ case '1' -> complement.append('0');
+ default -> throw new IllegalArgumentException("Input must contain only '0' and '1'. Found: " + bit);
+ }
+ }
+ return complement.toString();
+ }
+}
diff --git a/src/main/java/com/thealgorithms/bitmanipulation/ParityCheck.java b/src/main/java/com/thealgorithms/bitmanipulation/ParityCheck.java
new file mode 100644
index 000000000000..5acab4d4a362
--- /dev/null
+++ b/src/main/java/com/thealgorithms/bitmanipulation/ParityCheck.java
@@ -0,0 +1,34 @@
+package com.thealgorithms.bitmanipulation;
+
+/**
+ * The ParityCheck class provides a method to check the parity of a given number.
+ *
+ * Parity is a mathematical term that describes the property of an integer's binary representation.
+ * The parity of a binary number is the number of 1s in its binary representation.
+ * If the number of 1s is even, the parity is even; otherwise, it is odd.
+ *
+ * For example, the binary representation of 5 is 101, which has two 1s, so the parity of 5 is even.
+ * The binary representation of 6 is 110, which has two 1s, so the parity of 6 is even.
+ * The binary representation of 7 is 111, which has three 1s, so the parity of 7 is odd.
+ *
+ * @author Hardvan
+ */
+public final class ParityCheck {
+ private ParityCheck() {
+ }
+
+ /**
+ * This method checks the parity of the given number.
+ *
+ * @param n the number to check the parity of
+ * @return true if the number has even parity, false otherwise
+ */
+ public static boolean checkParity(int n) {
+ int count = 0;
+ while (n > 0) {
+ count += n & 1;
+ n >>= 1;
+ }
+ return count % 2 == 0;
+ }
+}
diff --git a/src/main/java/com/thealgorithms/bitmanipulation/ReverseBits.java b/src/main/java/com/thealgorithms/bitmanipulation/ReverseBits.java
index e8f2930d3afe..12c269d9be48 100644
--- a/src/main/java/com/thealgorithms/bitmanipulation/ReverseBits.java
+++ b/src/main/java/com/thealgorithms/bitmanipulation/ReverseBits.java
@@ -1,14 +1,33 @@
package com.thealgorithms.bitmanipulation;
/**
- * Converts any Octal Number to a Binary Number
+ * This class provides a method to reverse the bits of a 32-bit integer.
+ * Reversing the bits means that the least significant bit (LSB) becomes
+ * the most significant bit (MSB) and vice versa.
+ *
+ * Example:
+ * Input (binary): 00000010100101000001111010011100 (43261596)
+ * Output (binary): 00111001011110000010100101000000 (964176192)
+ *
+ * Time Complexity: O(32) - A fixed number of 32 iterations
+ * Space Complexity: O(1) - No extra space used
+ *
+ * Note:
+ * - If the input is negative, Java handles it using two’s complement representation.
+ * - This function works on 32-bit integers by default.
+ *
* @author Bama Charan Chhandogi
*/
-
public final class ReverseBits {
private ReverseBits() {
}
+ /**
+ * Reverses the bits of a 32-bit integer.
+ *
+ * @param n the integer whose bits are to be reversed
+ * @return the integer obtained by reversing the bits of the input
+ */
public static int reverseBits(int n) {
int result = 0;
int bitCount = 32;
diff --git a/src/main/java/com/thealgorithms/bitmanipulation/SingleBitOperations.java b/src/main/java/com/thealgorithms/bitmanipulation/SingleBitOperations.java
index b41aeca19af6..624a4e2b858a 100644
--- a/src/main/java/com/thealgorithms/bitmanipulation/SingleBitOperations.java
+++ b/src/main/java/com/thealgorithms/bitmanipulation/SingleBitOperations.java
@@ -1,34 +1,68 @@
package com.thealgorithms.bitmanipulation;
-/*
+/**
+ * A utility class for performing single-bit operations on integers.
+ * These operations include flipping, setting, clearing, and getting
+ * individual bits at specified positions.
+ *
+ * Bit positions are zero-indexed (i.e., the least significant bit is at position 0).
+ * These methods leverage bitwise operations for optimal performance.
+ *
+ * Examples:
+ * - `flipBit(3, 1)` flips the bit at index 1 in binary `11` (result: `1`).
+ * - `setBit(4, 0)` sets the bit at index 0 in `100` (result: `101` or 5).
+ * - `clearBit(7, 1)` clears the bit at index 1 in `111` (result: `101` or 5).
+ * - `getBit(6, 0)` checks if the least significant bit is set (result: `0`).
+ *
+ * Time Complexity: O(1) for all operations.
+ *
* Author: lukasb1b (https://github.com/lukasb1b)
*/
-
public final class SingleBitOperations {
private SingleBitOperations() {
}
+
/**
- * Flip the bit at position 'bit' in 'num'
+ * Flips (toggles) the bit at the specified position.
+ *
+ * @param num the input number
+ * @param bit the position of the bit to flip (0-indexed)
+ * @return the new number after flipping the specified bit
*/
public static int flipBit(final int num, final int bit) {
return num ^ (1 << bit);
}
+
/**
- * Set the bit at position 'bit' to 1 in the 'num' variable
+ * Sets the bit at the specified position to 1.
+ *
+ * @param num the input number
+ * @param bit the position of the bit to set (0-indexed)
+ * @return the new number after setting the specified bit to 1
*/
public static int setBit(final int num, final int bit) {
return num | (1 << bit);
}
+
/**
- * Clears the bit located at 'bit' from 'num'
+ * Clears the bit at the specified position (sets it to 0).
+ *
+ * @param num the input number
+ * @param bit the position of the bit to clear (0-indexed)
+ * @return the new number after clearing the specified bit
*/
public static int clearBit(final int num, final int bit) {
return num & ~(1 << bit);
}
+
/**
- * Get the bit located at 'bit' from 'num'
+ * Gets the bit value (0 or 1) at the specified position.
+ *
+ * @param num the input number
+ * @param bit the position of the bit to retrieve (0-indexed)
+ * @return 1 if the bit is set, 0 otherwise
*/
public static int getBit(final int num, final int bit) {
- return ((num >> bit) & 1);
+ return (num >> bit) & 1;
}
}
diff --git a/src/main/java/com/thealgorithms/bitmanipulation/SingleElement.java b/src/main/java/com/thealgorithms/bitmanipulation/SingleElement.java
new file mode 100644
index 000000000000..85ebdf02db25
--- /dev/null
+++ b/src/main/java/com/thealgorithms/bitmanipulation/SingleElement.java
@@ -0,0 +1,39 @@
+package com.thealgorithms.bitmanipulation;
+
+/**
+ * Utility class to find the single non-duplicate element from an array
+ * where all other elements appear twice.
+ *
+ * The algorithm runs in O(n) time complexity and O(1) space complexity
+ * using bitwise XOR.
+ *
+ *
+ * @author Tuhin M
+ */
+public final class SingleElement {
+
+ /**
+ * Private constructor to prevent instantiation of this utility class.
+ * Throws an UnsupportedOperationException if attempted.
+ */
+ private SingleElement() {
+ throw new UnsupportedOperationException("Utility Class");
+ }
+
+ /**
+ * Finds the single non-duplicate element in an array where every other
+ * element appears exactly twice. Uses bitwise XOR to achieve O(n) time
+ * complexity and O(1) space complexity.
+ *
+ * @param arr the input array containing integers where every element
+ * except one appears exactly twice
+ * @return the single non-duplicate element
+ */
+ public static int findSingleElement(int[] arr) {
+ int ele = 0;
+ for (int i = 0; i < arr.length; i++) {
+ ele ^= arr[i];
+ }
+ return ele;
+ }
+}
diff --git a/src/main/java/com/thealgorithms/bitmanipulation/SwapAdjacentBits.java b/src/main/java/com/thealgorithms/bitmanipulation/SwapAdjacentBits.java
new file mode 100644
index 000000000000..98a7de8bdf1a
--- /dev/null
+++ b/src/main/java/com/thealgorithms/bitmanipulation/SwapAdjacentBits.java
@@ -0,0 +1,57 @@
+package com.thealgorithms.bitmanipulation;
+
+/**
+ * A utility class to swap every pair of adjacent bits in a given integer.
+ * This operation shifts the even-positioned bits to odd positions and vice versa.
+ *
+ * Example:
+ * - Input: 2 (binary: `10`) → Output: 1 (binary: `01`)
+ * - Input: 43 (binary: `101011`) → Output: 23 (binary: `010111`)
+ *
+ * **Explanation of the Algorithm:**
+ * 1. Mask even-positioned bits: Using `0xAAAAAAAA` (binary: `101010...`),
+ * which selects bits in even positions.
+ * 2. Mask odd-positioned bits: Using `0x55555555` (binary: `010101...`),
+ * which selects bits in odd positions.
+ * 3. Shift bits:
+ * - Right-shift even-positioned bits by 1 to move them to odd positions.
+ * - Left-shift odd-positioned bits by 1 to move them to even positions.
+ * 4. Combine both shifted results using bitwise OR (`|`) to produce the final result.
+ *
+ * Use Case: This algorithm can be useful in applications involving low-level bit manipulation,
+ * such as encoding, data compression, or cryptographic transformations.
+ *
+ * Time Complexity: O(1) (constant time, since operations are bitwise).
+ *
+ * Author: Lakshyajeet Singh Goyal (https://github.com/DarkMatter-999)
+ */
+public final class SwapAdjacentBits {
+ private SwapAdjacentBits() {
+ }
+
+ /**
+ * Swaps every pair of adjacent bits of a given integer.
+ * Steps:
+ * 1. Mask the even-positioned bits.
+ * 2. Mask the odd-positioned bits.
+ * 3. Shift the even bits to the right and the odd bits to the left.
+ * 4. Combine the shifted bits.
+ *
+ * @param num the integer whose bits are to be swapped
+ * @return the integer after swapping every pair of adjacent bits
+ */
+ public static int swapAdjacentBits(int num) {
+ // mask the even bits (0xAAAAAAAA => 10101010...)
+ int evenBits = num & 0xAAAAAAAA;
+
+ // mask the odd bits (0x55555555 => 01010101...)
+ int oddBits = num & 0x55555555;
+
+ // right shift even bits and left shift odd bits
+ evenBits >>= 1;
+ oddBits <<= 1;
+
+ // combine shifted bits
+ return evenBits | oddBits;
+ }
+}
diff --git a/src/main/java/com/thealgorithms/bitmanipulation/TwosComplement.java b/src/main/java/com/thealgorithms/bitmanipulation/TwosComplement.java
new file mode 100644
index 000000000000..9b8cecd791a6
--- /dev/null
+++ b/src/main/java/com/thealgorithms/bitmanipulation/TwosComplement.java
@@ -0,0 +1,62 @@
+package com.thealgorithms.bitmanipulation;
+
+/**
+ * This class provides a method to compute the Two's Complement of a given binary number.
+ *
+ * In two's complement representation, a binary number's negative value is obtained
+ * by taking the one's complement (inverting all bits) and then adding 1 to the result.
+ * This method handles both small and large binary strings and ensures the output is
+ * correct for all binary inputs, including edge cases like all zeroes and all ones.
+ *
+ *
For more information on Two's Complement:
+ * @see Wikipedia - Two's Complement
+ *
+ *
Algorithm originally suggested by Jon von Neumann.
+ *
+ * @author Abhinay Verma (https://github.com/Monk-AbhinayVerma)
+ */
+public final class TwosComplement {
+ private TwosComplement() {
+ }
+
+ /**
+ * Computes the Two's Complement of the given binary string.
+ * Steps:
+ * 1. Compute the One's Complement (invert all bits).
+ * 2. Add 1 to the One's Complement to get the Two's Complement.
+ * 3. Iterate from the rightmost bit to the left, adding 1 and carrying over as needed.
+ * 4. If a carry is still present after the leftmost bit, prepend '1' to handle overflow.
+ *
+ * @param binary The binary number as a string (only '0' and '1' characters allowed).
+ * @return The two's complement of the input binary string as a new binary string.
+ * @throws IllegalArgumentException If the input contains non-binary characters.
+ */
+ public static String twosComplement(String binary) {
+ if (!binary.matches("[01]+")) {
+ throw new IllegalArgumentException("Input must contain only '0' and '1'.");
+ }
+
+ StringBuilder onesComplement = new StringBuilder();
+ for (char bit : binary.toCharArray()) {
+ onesComplement.append(bit == '0' ? '1' : '0');
+ }
+
+ StringBuilder twosComplement = new StringBuilder(onesComplement);
+ boolean carry = true;
+
+ for (int i = onesComplement.length() - 1; i >= 0 && carry; i--) {
+ if (onesComplement.charAt(i) == '1') {
+ twosComplement.setCharAt(i, '0');
+ } else {
+ twosComplement.setCharAt(i, '1');
+ carry = false;
+ }
+ }
+
+ if (carry) {
+ twosComplement.insert(0, '1');
+ }
+
+ return twosComplement.toString();
+ }
+}
diff --git a/src/main/java/com/thealgorithms/bitmanipulation/Xs3Conversion.java b/src/main/java/com/thealgorithms/bitmanipulation/Xs3Conversion.java
new file mode 100644
index 000000000000..b22abc0c04ff
--- /dev/null
+++ b/src/main/java/com/thealgorithms/bitmanipulation/Xs3Conversion.java
@@ -0,0 +1,58 @@
+package com.thealgorithms.bitmanipulation;
+
+/**
+ * This class provides methods to convert between XS-3 (Excess-3) and binary.
+ *
+ * Excess-3, also called XS-3, is a binary-coded decimal (BCD) code in which each decimal digit is represented by its corresponding 4-bit binary value plus 3.
+ *
+ * For more information, refer to the
+ * Excess-3 Wikipedia page.
+ *
+ * Example usage:
+ *
+ * int binary = Xs3Conversion.xs3ToBinary(0x4567);
+ * System.out.println("XS-3 0x4567 to binary: " + binary); // Output: 1234
+ *
+ * int xs3 = Xs3Conversion.binaryToXs3(1234);
+ * System.out.println("Binary 1234 to XS-3: " + Integer.toHexString(xs3)); // Output: 0x4567
+ *
+ */
+public final class Xs3Conversion {
+ private Xs3Conversion() {
+ }
+ /**
+ * Converts an XS-3 (Excess-3) number to binary.
+ *
+ * @param xs3 The XS-3 number.
+ * @return The corresponding binary number.
+ */
+ public static int xs3ToBinary(int xs3) {
+ int binary = 0;
+ int multiplier = 1;
+ while (xs3 > 0) {
+ int digit = (xs3 & 0xF) - 3; // Extract the last 4 bits (one XS-3 digit) and subtract 3
+ binary += digit * multiplier;
+ multiplier *= 10;
+ xs3 >>= 4; // Shift right by 4 bits to process the next XS-3 digit
+ }
+ return binary;
+ }
+
+ /**
+ * Converts a binary number to XS-3 (Excess-3).
+ *
+ * @param binary The binary number.
+ * @return The corresponding XS-3 number.
+ */
+ public static int binaryToXs3(int binary) {
+ int xs3 = 0;
+ int shift = 0;
+ while (binary > 0) {
+ int digit = (binary % 10) + 3; // Extract the last decimal digit and add 3
+ xs3 |= (digit << (shift * 4)); // Shift the digit to the correct XS-3 position
+ binary /= 10; // Remove the last decimal digit
+ shift++;
+ }
+ return xs3;
+ }
+}
diff --git a/src/main/java/com/thealgorithms/ciphers/ADFGVXCipher.java b/src/main/java/com/thealgorithms/ciphers/ADFGVXCipher.java
new file mode 100644
index 000000000000..d915858f9e6f
--- /dev/null
+++ b/src/main/java/com/thealgorithms/ciphers/ADFGVXCipher.java
@@ -0,0 +1,167 @@
+package com.thealgorithms.ciphers;
+
+import java.util.Arrays;
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * The ADFGVX cipher is a fractionating transposition cipher that was used by
+ * the German Army during World War I. It combines a **Polybius square substitution**
+ * with a **columnar transposition** to enhance encryption strength.
+ *
+ * The name "ADFGVX" refers to the six letters (A, D, F, G, V, X) used as row and
+ * column labels in the Polybius square. This cipher was designed to secure
+ * communication and create complex, hard-to-break ciphertexts.
+ *
+ * Learn more: ADFGVX Cipher - Wikipedia.
+ *
+ * Example usage:
+ *
+ * ADFGVXCipher cipher = new ADFGVXCipher();
+ * String encrypted = cipher.encrypt("attack at 1200am", "PRIVACY");
+ * String decrypted = cipher.decrypt(encrypted, "PRIVACY");
+ *
+ *
+ * @author bennybebo
+ */
+public class ADFGVXCipher {
+
+ // Constants used in the Polybius square
+ private static final char[] POLYBIUS_LETTERS = {'A', 'D', 'F', 'G', 'V', 'X'};
+ private static final char[][] POLYBIUS_SQUARE = {{'N', 'A', '1', 'C', '3', 'H'}, {'8', 'T', 'B', '2', 'O', 'M'}, {'E', '5', 'W', 'R', 'P', 'D'}, {'4', 'F', '6', 'G', '7', 'I'}, {'9', 'J', '0', 'K', 'L', 'Q'}, {'S', 'U', 'V', 'X', 'Y', 'Z'}};
+
+ // Maps for fast substitution lookups
+ private static final Map POLYBIUS_MAP = new HashMap<>();
+ private static final Map REVERSE_POLYBIUS_MAP = new HashMap<>();
+
+ // Static block to initialize the lookup tables from the Polybius square
+ static {
+ for (int i = 0; i < POLYBIUS_SQUARE.length; i++) {
+ for (int j = 0; j < POLYBIUS_SQUARE[i].length; j++) {
+ String key = "" + POLYBIUS_LETTERS[i] + POLYBIUS_LETTERS[j];
+ POLYBIUS_MAP.put(key, POLYBIUS_SQUARE[i][j]);
+ REVERSE_POLYBIUS_MAP.put(POLYBIUS_SQUARE[i][j], key);
+ }
+ }
+ }
+
+ /**
+ * Encrypts a given plaintext using the ADFGVX cipher with the provided keyword.
+ * Steps:
+ * 1. Substitute each letter in the plaintext with a pair of ADFGVX letters.
+ * 2. Perform a columnar transposition on the fractionated text using the keyword.
+ *
+ * @param plaintext The message to be encrypted (can contain letters and digits).
+ * @param key The keyword for columnar transposition.
+ * @return The encrypted message as ciphertext.
+ */
+ public String encrypt(String plaintext, String key) {
+ plaintext = plaintext.toUpperCase().replaceAll("[^A-Z0-9]", ""); // Sanitize input
+ StringBuilder fractionatedText = new StringBuilder();
+
+ for (char c : plaintext.toCharArray()) {
+ fractionatedText.append(REVERSE_POLYBIUS_MAP.get(c));
+ }
+
+ return columnarTransposition(fractionatedText.toString(), key);
+ }
+
+ /**
+ * Decrypts a given ciphertext using the ADFGVX cipher with the provided keyword.
+ * Steps:
+ * 1. Reverse the columnar transposition performed during encryption.
+ * 2. Substitute each pair of ADFGVX letters with the corresponding plaintext letter.
+ * The resulting text is the decrypted message.
+ *
+ * @param ciphertext The encrypted message.
+ * @param key The keyword used during encryption.
+ * @return The decrypted plaintext message.
+ */
+ public String decrypt(String ciphertext, String key) {
+ String fractionatedText = reverseColumnarTransposition(ciphertext, key);
+
+ StringBuilder plaintext = new StringBuilder();
+ for (int i = 0; i < fractionatedText.length(); i += 2) {
+ String pair = fractionatedText.substring(i, i + 2);
+ plaintext.append(POLYBIUS_MAP.get(pair));
+ }
+
+ return plaintext.toString();
+ }
+
+ /**
+ * Helper method: Performs columnar transposition during encryption
+ *
+ * @param text The fractionated text to be transposed
+ * @param key The keyword for columnar transposition
+ * @return The transposed text
+ */
+ private String columnarTransposition(String text, String key) {
+ int numRows = (int) Math.ceil((double) text.length() / key.length());
+ char[][] table = new char[numRows][key.length()];
+ for (char[] row : table) { // Fill empty cells with underscores
+ Arrays.fill(row, '_');
+ }
+
+ // Populate the table row by row
+ for (int i = 0; i < text.length(); i++) {
+ table[i / key.length()][i % key.length()] = text.charAt(i);
+ }
+
+ // Read columns based on the alphabetical order of the key
+ StringBuilder ciphertext = new StringBuilder();
+ char[] sortedKey = key.toCharArray();
+ Arrays.sort(sortedKey);
+
+ for (char keyChar : sortedKey) {
+ int column = key.indexOf(keyChar);
+ for (char[] row : table) {
+ if (row[column] != '_') {
+ ciphertext.append(row[column]);
+ }
+ }
+ }
+
+ return ciphertext.toString();
+ }
+
+ /**
+ * Helper method: Reverses the columnar transposition during decryption
+ *
+ * @param ciphertext The transposed text to be reversed
+ * @param key The keyword used during encryption
+ * @return The reversed text
+ */
+ private String reverseColumnarTransposition(String ciphertext, String key) {
+ int numRows = (int) Math.ceil((double) ciphertext.length() / key.length());
+ char[][] table = new char[numRows][key.length()];
+
+ char[] sortedKey = key.toCharArray();
+ Arrays.sort(sortedKey);
+
+ int index = 0;
+ // Populate the table column by column according to the sorted key
+ for (char keyChar : sortedKey) {
+ int column = key.indexOf(keyChar);
+ for (int row = 0; row < numRows; row++) {
+ if (index < ciphertext.length()) {
+ table[row][column] = ciphertext.charAt(index++);
+ } else {
+ table[row][column] = '_';
+ }
+ }
+ }
+
+ // Read the table row by row to reconstruct the fractionated text
+ StringBuilder fractionatedText = new StringBuilder();
+ for (char[] row : table) {
+ for (char cell : row) {
+ if (cell != '_') {
+ fractionatedText.append(cell);
+ }
+ }
+ }
+
+ return fractionatedText.toString();
+ }
+}
diff --git a/src/main/java/com/thealgorithms/ciphers/AES.java b/src/main/java/com/thealgorithms/ciphers/AES.java
index 5d614afbe584..1c283f6b7655 100644
--- a/src/main/java/com/thealgorithms/ciphers/AES.java
+++ b/src/main/java/com/thealgorithms/ciphers/AES.java
@@ -2418,8 +2418,6 @@ public static BigInteger scheduleCore(BigInteger t, int rconCounter) {
rBytes = new StringBuilder(rBytes.substring(0, i * 2) + currentByteBits + rBytes.substring((i + 1) * 2));
}
- // t = new BigInteger(rBytes, 16);
- // return t;
return new BigInteger(rBytes.toString(), 16);
}
diff --git a/src/main/java/com/thealgorithms/ciphers/AffineCipher.java b/src/main/java/com/thealgorithms/ciphers/AffineCipher.java
index bcf3a5b0167b..979f18532eaa 100644
--- a/src/main/java/com/thealgorithms/ciphers/AffineCipher.java
+++ b/src/main/java/com/thealgorithms/ciphers/AffineCipher.java
@@ -1,5 +1,23 @@
package com.thealgorithms.ciphers;
+/**
+ * The AffineCipher class implements the Affine cipher, a type of monoalphabetic substitution cipher.
+ * It encrypts and decrypts messages using a linear transformation defined by the formula:
+ *
+ * E(x) = (a * x + b) mod m
+ * D(y) = a^-1 * (y - b) mod m
+ *
+ * where:
+ * - E(x) is the encrypted character,
+ * - D(y) is the decrypted character,
+ * - a is the multiplicative key (must be coprime to m),
+ * - b is the additive key,
+ * - x is the index of the plaintext character,
+ * - y is the index of the ciphertext character,
+ * - m is the size of the alphabet (26 for the English alphabet).
+ *
+ * The class provides methods for encrypting and decrypting messages, as well as a main method to demonstrate its usage.
+ */
final class AffineCipher {
private AffineCipher() {
}
@@ -8,62 +26,62 @@ private AffineCipher() {
static int a = 17;
static int b = 20;
+ /**
+ * Encrypts a message using the Affine cipher.
+ *
+ * @param msg the plaintext message as a character array
+ * @return the encrypted ciphertext
+ */
static String encryptMessage(char[] msg) {
- /// Cipher Text initially empty
- String cipher = "";
+ // Cipher Text initially empty
+ StringBuilder cipher = new StringBuilder();
for (int i = 0; i < msg.length; i++) {
// Avoid space to be encrypted
- /* applying encryption formula ( a x + b ) mod m
+ /* applying encryption formula ( a * x + b ) mod m
{here x is msg[i] and m is 26} and added 'A' to
- bring it in range of ascii alphabet[ 65-90 | A-Z ] */
+ bring it in the range of ASCII alphabet [65-90 | A-Z] */
if (msg[i] != ' ') {
- cipher = cipher + (char) ((((a * (msg[i] - 'A')) + b) % 26) + 'A');
+ cipher.append((char) ((((a * (msg[i] - 'A')) + b) % 26) + 'A'));
} else { // else simply append space character
- cipher += msg[i];
+ cipher.append(msg[i]);
}
}
- return cipher;
+ return cipher.toString();
}
+ /**
+ * Decrypts a ciphertext using the Affine cipher.
+ *
+ * @param cipher the ciphertext to decrypt
+ * @return the decrypted plaintext message
+ */
static String decryptCipher(String cipher) {
- String msg = "";
+ StringBuilder msg = new StringBuilder();
int aInv = 0;
- int flag = 0;
+ int flag;
- // Find a^-1 (the multiplicative inverse of a
- // in the group of integers modulo m.)
+ // Find a^-1 (the multiplicative inverse of a in the group of integers modulo m.)
for (int i = 0; i < 26; i++) {
flag = (a * i) % 26;
- // Check if (a*i)%26 == 1,
+ // Check if (a * i) % 26 == 1,
// then i will be the multiplicative inverse of a
if (flag == 1) {
aInv = i;
+ break;
}
}
for (int i = 0; i < cipher.length(); i++) {
- /*Applying decryption formula a^-1 ( x - b ) mod m
+ /* Applying decryption formula a^-1 * (x - b) mod m
{here x is cipher[i] and m is 26} and added 'A'
- to bring it in range of ASCII alphabet[ 65-90 | A-Z ] */
+ to bring it in the range of ASCII alphabet [65-90 | A-Z] */
if (cipher.charAt(i) != ' ') {
- msg = msg + (char) (((aInv * ((cipher.charAt(i) + 'A' - b)) % 26)) + 'A');
+ msg.append((char) (((aInv * ((cipher.charAt(i) - 'A') - b + 26)) % 26) + 'A'));
} else { // else simply append space character
- msg += cipher.charAt(i);
+ msg.append(cipher.charAt(i));
}
}
- return msg;
- }
-
- // Driver code
- public static void main(String[] args) {
- String msg = "AFFINE CIPHER";
-
- // Calling encryption function
- String cipherText = encryptMessage(msg.toCharArray());
- System.out.println("Encrypted Message is : " + cipherText);
-
- // Calling Decryption function
- System.out.println("Decrypted Message is: " + decryptCipher(cipherText));
+ return msg.toString();
}
}
diff --git a/src/main/java/com/thealgorithms/ciphers/AtbashCipher.java b/src/main/java/com/thealgorithms/ciphers/AtbashCipher.java
new file mode 100644
index 000000000000..9169aa82bd75
--- /dev/null
+++ b/src/main/java/com/thealgorithms/ciphers/AtbashCipher.java
@@ -0,0 +1,101 @@
+package com.thealgorithms.ciphers;
+
+/**
+ * The Atbash cipher is a classic substitution cipher that substitutes each letter
+ * with its opposite letter in the alphabet.
+ *
+ * For example:
+ * - 'A' becomes 'Z', 'B' becomes 'Y', 'C' becomes 'X', and so on.
+ * - Similarly, 'a' becomes 'z', 'b' becomes 'y', and so on.
+ *
+ * The cipher works identically for both uppercase and lowercase letters.
+ * Non-alphabetical characters remain unchanged in the output.
+ *
+ * This cipher is symmetric, meaning that applying the cipher twice will return
+ * the original text. Therefore, the same function is used for both encryption and decryption.
+ *
+ * Usage Example:
+ *
+ * AtbashCipher cipher = new AtbashCipher("Hello World!");
+ * String encrypted = cipher.convert(); // Output: "Svool Dliow!"
+ *
+ *
+ * @author Krounosity
+ * @see Atbash Cipher (Wikipedia)
+ */
+public class AtbashCipher {
+
+ private String toConvert;
+
+ public AtbashCipher() {
+ }
+
+ /**
+ * Constructor with a string parameter.
+ *
+ * @param str The string to be converted using the Atbash cipher
+ */
+ public AtbashCipher(String str) {
+ this.toConvert = str;
+ }
+
+ /**
+ * Returns the current string set for conversion.
+ *
+ * @return The string to be converted
+ */
+ public String getString() {
+ return toConvert;
+ }
+
+ /**
+ * Sets the string to be converted using the Atbash cipher.
+ *
+ * @param str The new string to convert
+ */
+ public void setString(String str) {
+ this.toConvert = str;
+ }
+
+ /**
+ * Checks if a character is uppercase.
+ *
+ * @param ch The character to check
+ * @return {@code true} if the character is uppercase, {@code false} otherwise
+ */
+ private boolean isCapital(char ch) {
+ return ch >= 'A' && ch <= 'Z';
+ }
+
+ /**
+ * Checks if a character is lowercase.
+ *
+ * @param ch The character to check
+ * @return {@code true} if the character is lowercase, {@code false} otherwise
+ */
+ private boolean isSmall(char ch) {
+ return ch >= 'a' && ch <= 'z';
+ }
+
+ /**
+ * Converts the input string using the Atbash cipher.
+ * Alphabetic characters are substituted with their opposite in the alphabet,
+ * while non-alphabetic characters remain unchanged.
+ *
+ * @return The converted string after applying the Atbash cipher
+ */
+ public String convert() {
+ StringBuilder convertedString = new StringBuilder();
+
+ for (char ch : toConvert.toCharArray()) {
+ if (isSmall(ch)) {
+ convertedString.append((char) ('z' - (ch - 'a')));
+ } else if (isCapital(ch)) {
+ convertedString.append((char) ('Z' - (ch - 'A')));
+ } else {
+ convertedString.append(ch);
+ }
+ }
+ return convertedString.toString();
+ }
+}
diff --git a/src/main/java/com/thealgorithms/ciphers/Autokey.java b/src/main/java/com/thealgorithms/ciphers/Autokey.java
new file mode 100644
index 000000000000..bb67f512accf
--- /dev/null
+++ b/src/main/java/com/thealgorithms/ciphers/Autokey.java
@@ -0,0 +1,55 @@
+package com.thealgorithms.ciphers;
+
+/**
+ * The Autokey Cipher is an interesting and historically significant encryption method,
+ * as it improves upon the classic Vigenère Cipher by using the plaintext itself to
+ * extend the key. This makes it harder to break using frequency analysis, as it
+ * doesn’t rely solely on a repeated key.
+ * https://en.wikipedia.org/wiki/Autokey_cipher
+ *
+ * @author bennybebo
+ */
+public class Autokey {
+
+ // Encrypts the plaintext using the Autokey cipher
+ public String encrypt(String plaintext, String keyword) {
+ plaintext = plaintext.toUpperCase().replaceAll("[^A-Z]", ""); // Sanitize input
+ keyword = keyword.toUpperCase();
+
+ StringBuilder extendedKey = new StringBuilder(keyword);
+ extendedKey.append(plaintext); // Extend key with plaintext
+
+ StringBuilder ciphertext = new StringBuilder();
+
+ for (int i = 0; i < plaintext.length(); i++) {
+ char plainChar = plaintext.charAt(i);
+ char keyChar = extendedKey.charAt(i);
+
+ int encryptedChar = (plainChar - 'A' + keyChar - 'A') % 26 + 'A';
+ ciphertext.append((char) encryptedChar);
+ }
+
+ return ciphertext.toString();
+ }
+
+ // Decrypts the ciphertext using the Autokey cipher
+ public String decrypt(String ciphertext, String keyword) {
+ ciphertext = ciphertext.toUpperCase().replaceAll("[^A-Z]", ""); // Sanitize input
+ keyword = keyword.toUpperCase();
+
+ StringBuilder plaintext = new StringBuilder();
+ StringBuilder extendedKey = new StringBuilder(keyword);
+
+ for (int i = 0; i < ciphertext.length(); i++) {
+ char cipherChar = ciphertext.charAt(i);
+ char keyChar = extendedKey.charAt(i);
+
+ int decryptedChar = (cipherChar - 'A' - (keyChar - 'A') + 26) % 26 + 'A';
+ plaintext.append((char) decryptedChar);
+
+ extendedKey.append((char) decryptedChar); // Extend key with each decrypted char
+ }
+
+ return plaintext.toString();
+ }
+}
diff --git a/src/main/java/com/thealgorithms/ciphers/BaconianCipher.java b/src/main/java/com/thealgorithms/ciphers/BaconianCipher.java
new file mode 100644
index 000000000000..16dfd6e674af
--- /dev/null
+++ b/src/main/java/com/thealgorithms/ciphers/BaconianCipher.java
@@ -0,0 +1,71 @@
+package com.thealgorithms.ciphers;
+
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * The Baconian Cipher is a substitution cipher where each letter is represented
+ * by a group of five binary digits (A's and B's). It can also be used to hide
+ * messages within other texts, making it a simple form of steganography.
+ * https://en.wikipedia.org/wiki/Bacon%27s_cipher
+ *
+ * @author Bennybebo
+ */
+public class BaconianCipher {
+
+ private static final Map BACONIAN_MAP = new HashMap<>();
+ private static final Map REVERSE_BACONIAN_MAP = new HashMap<>();
+
+ static {
+ // Initialize the Baconian cipher mappings
+ String[] baconianAlphabet = {"AAAAA", "AAAAB", "AAABA", "AAABB", "AABAA", "AABAB", "AABBA", "AABBB", "ABAAA", "ABAAB", "ABABA", "ABABB", "ABBAA", "ABBAB", "ABBBA", "ABBBB", "BAAAA", "BAAAB", "BAABA", "BAABB", "BABAA", "BABAB", "BABBA", "BABBB", "BBAAA", "BBAAB"};
+ char letter = 'A';
+ for (String code : baconianAlphabet) {
+ BACONIAN_MAP.put(letter, code);
+ REVERSE_BACONIAN_MAP.put(code, letter);
+ letter++;
+ }
+
+ // Handle I/J as the same letter
+ BACONIAN_MAP.put('I', BACONIAN_MAP.get('J'));
+ REVERSE_BACONIAN_MAP.put(BACONIAN_MAP.get('I'), 'I');
+ }
+
+ /**
+ * Encrypts the given plaintext using the Baconian cipher.
+ *
+ * @param plaintext The plaintext message to encrypt.
+ * @return The ciphertext as a binary (A/B) sequence.
+ */
+ public String encrypt(String plaintext) {
+ StringBuilder ciphertext = new StringBuilder();
+ plaintext = plaintext.toUpperCase().replaceAll("[^A-Z]", ""); // Remove non-letter characters
+
+ for (char letter : plaintext.toCharArray()) {
+ ciphertext.append(BACONIAN_MAP.get(letter));
+ }
+
+ return ciphertext.toString();
+ }
+
+ /**
+ * Decrypts the given ciphertext encoded in binary (A/B) format using the Baconian cipher.
+ *
+ * @param ciphertext The ciphertext to decrypt.
+ * @return The decrypted plaintext message.
+ */
+ public String decrypt(String ciphertext) {
+ StringBuilder plaintext = new StringBuilder();
+
+ for (int i = 0; i < ciphertext.length(); i += 5) {
+ String code = ciphertext.substring(i, i + 5);
+ if (REVERSE_BACONIAN_MAP.containsKey(code)) {
+ plaintext.append(REVERSE_BACONIAN_MAP.get(code));
+ } else {
+ throw new IllegalArgumentException("Invalid Baconian code: " + code);
+ }
+ }
+
+ return plaintext.toString();
+ }
+}
diff --git a/src/main/java/com/thealgorithms/ciphers/Blowfish.java b/src/main/java/com/thealgorithms/ciphers/Blowfish.java
index f6a0a3753e9b..ea1807e62710 100644
--- a/src/main/java/com/thealgorithms/ciphers/Blowfish.java
+++ b/src/main/java/com/thealgorithms/ciphers/Blowfish.java
@@ -1078,7 +1078,7 @@ public class Blowfish {
* @return String object which is a binary representation of the hex number passed as parameter
*/
private String hexToBin(String hex) {
- String binary = "";
+ StringBuilder binary = new StringBuilder();
long num;
String binary4B;
int n = hex.length();
@@ -1089,9 +1089,9 @@ private String hexToBin(String hex) {
binary4B = "0000" + binary4B;
binary4B = binary4B.substring(binary4B.length() - 4);
- binary += binary4B;
+ binary.append(binary4B);
}
- return binary;
+ return binary.toString();
}
/**
@@ -1103,12 +1103,12 @@ private String hexToBin(String hex) {
*/
private String binToHex(String binary) {
long num = Long.parseUnsignedLong(binary, 2);
- String hex = Long.toHexString(num);
+ StringBuilder hex = new StringBuilder(Long.toHexString(num));
while (hex.length() < (binary.length() / 4)) {
- hex = "0" + hex;
+ hex.insert(0, "0");
}
- return hex;
+ return hex.toString();
}
/**
@@ -1121,12 +1121,12 @@ private String binToHex(String binary) {
private String xor(String a, String b) {
a = hexToBin(a);
b = hexToBin(b);
- String ans = "";
+ StringBuilder ans = new StringBuilder();
for (int i = 0; i < a.length(); i++) {
- ans += (char) (((a.charAt(i) - '0') ^ (b.charAt(i) - '0')) + '0');
+ ans.append((char) (((a.charAt(i) - '0') ^ (b.charAt(i) - '0')) + '0'));
}
- ans = binToHex(ans);
- return ans;
+ ans = new StringBuilder(binToHex(ans.toString()));
+ return ans.toString();
}
/**
diff --git a/src/main/java/com/thealgorithms/ciphers/Caesar.java b/src/main/java/com/thealgorithms/ciphers/Caesar.java
index 61c444cf6463..23535bc2b5d2 100644
--- a/src/main/java/com/thealgorithms/ciphers/Caesar.java
+++ b/src/main/java/com/thealgorithms/ciphers/Caesar.java
@@ -9,6 +9,9 @@
* @author khalil2535
*/
public class Caesar {
+ private static char normalizeShift(final int shift) {
+ return (char) (shift % 26);
+ }
/**
* Encrypt text by shifting every Latin char by add number shift for ASCII
@@ -19,7 +22,7 @@ public class Caesar {
public String encode(String message, int shift) {
StringBuilder encoded = new StringBuilder();
- shift %= 26;
+ final char shiftChar = normalizeShift(shift);
final int length = message.length();
for (int i = 0; i < length; i++) {
@@ -29,10 +32,10 @@ public String encode(String message, int shift) {
char current = message.charAt(i); // Java law : char + int = char
if (isCapitalLatinLetter(current)) {
- current += shift;
+ current += shiftChar;
encoded.append((char) (current > 'Z' ? current - 26 : current)); // 26 = number of latin letters
} else if (isSmallLatinLetter(current)) {
- current += shift;
+ current += shiftChar;
encoded.append((char) (current > 'z' ? current - 26 : current)); // 26 = number of latin letters
} else {
encoded.append(current);
@@ -50,16 +53,16 @@ public String encode(String message, int shift) {
public String decode(String encryptedMessage, int shift) {
StringBuilder decoded = new StringBuilder();
- shift %= 26;
+ final char shiftChar = normalizeShift(shift);
final int length = encryptedMessage.length();
for (int i = 0; i < length; i++) {
char current = encryptedMessage.charAt(i);
if (isCapitalLatinLetter(current)) {
- current -= shift;
+ current -= shiftChar;
decoded.append((char) (current < 'A' ? current + 26 : current)); // 26 = number of latin letters
} else if (isSmallLatinLetter(current)) {
- current -= shift;
+ current -= shiftChar;
decoded.append((char) (current < 'a' ? current + 26 : current)); // 26 = number of latin letters
} else {
decoded.append(current);
diff --git a/src/main/java/com/thealgorithms/ciphers/ColumnarTranspositionCipher.java b/src/main/java/com/thealgorithms/ciphers/ColumnarTranspositionCipher.java
index e59cfb12d816..b6b889b079ca 100644
--- a/src/main/java/com/thealgorithms/ciphers/ColumnarTranspositionCipher.java
+++ b/src/main/java/com/thealgorithms/ciphers/ColumnarTranspositionCipher.java
@@ -27,13 +27,13 @@ private ColumnarTranspositionCipher() {
* @return a String with the word encrypted by the Columnar Transposition
* Cipher Rule
*/
- public static String encrpyter(String word, String keyword) {
+ public static String encrypt(final String word, final String keyword) {
ColumnarTranspositionCipher.keyword = keyword;
- abecedariumBuilder(500);
+ abecedariumBuilder();
table = tableBuilder(word);
Object[][] sortedTable = sortTable(table);
StringBuilder wordEncrypted = new StringBuilder();
- for (int i = 0; i < sortedTable[i].length; i++) {
+ for (int i = 0; i < sortedTable[0].length; i++) {
for (int j = 1; j < sortedTable.length; j++) {
wordEncrypted.append(sortedTable[j][i]);
}
@@ -51,11 +51,12 @@ public static String encrpyter(String word, String keyword) {
* @return a String with the word encrypted by the Columnar Transposition
* Cipher Rule
*/
- public static String encrpyter(String word, String keyword, String abecedarium) {
+ public static String encrypt(String word, String keyword, String abecedarium) {
ColumnarTranspositionCipher.keyword = keyword;
ColumnarTranspositionCipher.abecedarium = Objects.requireNonNullElse(abecedarium, ABECEDARIUM);
table = tableBuilder(word);
Object[][] sortedTable = sortTable(table);
+
StringBuilder wordEncrypted = new StringBuilder();
for (int i = 0; i < sortedTable[0].length; i++) {
for (int j = 1; j < sortedTable.length; j++) {
@@ -72,7 +73,7 @@ public static String encrpyter(String word, String keyword, String abecedarium)
* @return a String decrypted with the word encrypted by the Columnar
* Transposition Cipher Rule
*/
- public static String decrypter() {
+ public static String decrypt() {
StringBuilder wordDecrypted = new StringBuilder();
for (int i = 1; i < table.length; i++) {
for (Object item : table[i]) {
@@ -91,14 +92,14 @@ public static String decrypter() {
*/
private static Object[][] tableBuilder(String word) {
Object[][] table = new Object[numberOfRows(word) + 1][keyword.length()];
- char[] wordInChards = word.toCharArray();
- // Fils in the respective numbers
+ char[] wordInChars = word.toCharArray();
+ // Fills in the respective numbers for the column
table[0] = findElements();
int charElement = 0;
for (int i = 1; i < table.length; i++) {
for (int j = 0; j < table[i].length; j++) {
- if (charElement < wordInChards.length) {
- table[i][j] = wordInChards[charElement];
+ if (charElement < wordInChars.length) {
+ table[i][j] = wordInChars[charElement];
charElement++;
} else {
table[i][j] = ENCRYPTION_FIELD_CHAR;
@@ -116,7 +117,7 @@ private static Object[][] tableBuilder(String word) {
* order to respect the Columnar Transposition Cipher Rule.
*/
private static int numberOfRows(String word) {
- if (word.length() / keyword.length() > word.length() / keyword.length()) {
+ if (word.length() % keyword.length() != 0) {
return (word.length() / keyword.length()) + 1;
} else {
return word.length() / keyword.length();
@@ -173,35 +174,13 @@ private static void switchColumns(Object[][] table, int firstColumnIndex, int se
}
/**
- * Creates an abecedarium with a specified ascii inded
- *
- * @param value Number of characters being used based on the ASCII Table
+ * Creates an abecedarium with all available ascii values.
*/
- private static void abecedariumBuilder(int value) {
+ private static void abecedariumBuilder() {
StringBuilder t = new StringBuilder();
- for (int i = 0; i < value; i++) {
+ for (int i = 0; i < 256; i++) {
t.append((char) i);
}
abecedarium = t.toString();
}
-
- private static void showTable() {
- for (Object[] table1 : table) {
- for (Object item : table1) {
- System.out.print(item + " ");
- }
- System.out.println();
- }
- }
-
- public static void main(String[] args) {
- String keywordForExample = "asd215";
- String wordBeingEncrypted = "This is a test of the Columnar Transposition Cipher";
- System.out.println("### Example of Columnar Transposition Cipher ###\n");
- System.out.println("Word being encryped ->>> " + wordBeingEncrypted);
- System.out.println("Word encrypted ->>> " + ColumnarTranspositionCipher.encrpyter(wordBeingEncrypted, keywordForExample));
- System.out.println("Word decryped ->>> " + ColumnarTranspositionCipher.decrypter());
- System.out.println("\n### Encrypted Table ###");
- showTable();
- }
}
diff --git a/src/main/java/com/thealgorithms/ciphers/DiffieHellman.java b/src/main/java/com/thealgorithms/ciphers/DiffieHellman.java
new file mode 100644
index 000000000000..7470b40e001a
--- /dev/null
+++ b/src/main/java/com/thealgorithms/ciphers/DiffieHellman.java
@@ -0,0 +1,36 @@
+package com.thealgorithms.ciphers;
+
+import java.math.BigInteger;
+
+public final class DiffieHellman {
+
+ private final BigInteger base;
+ private final BigInteger secret;
+ private final BigInteger prime;
+
+ // Constructor to initialize base, secret, and prime
+ public DiffieHellman(BigInteger base, BigInteger secret, BigInteger prime) {
+ // Check for non-null and positive values
+ if (base == null || secret == null || prime == null || base.signum() <= 0 || secret.signum() <= 0 || prime.signum() <= 0) {
+ throw new IllegalArgumentException("Base, secret, and prime must be non-null and positive values.");
+ }
+ this.base = base;
+ this.secret = secret;
+ this.prime = prime;
+ }
+
+ // Method to calculate public value (g^x mod p)
+ public BigInteger calculatePublicValue() {
+ // Returns g^x mod p
+ return base.modPow(secret, prime);
+ }
+
+ // Method to calculate the shared secret key (otherPublic^secret mod p)
+ public BigInteger calculateSharedSecret(BigInteger otherPublicValue) {
+ if (otherPublicValue == null || otherPublicValue.signum() <= 0) {
+ throw new IllegalArgumentException("Other public value must be non-null and positive.");
+ }
+ // Returns b^x mod p or a^y mod p
+ return otherPublicValue.modPow(secret, prime);
+ }
+}
diff --git a/src/main/java/com/thealgorithms/ciphers/ECC.java b/src/main/java/com/thealgorithms/ciphers/ECC.java
new file mode 100644
index 000000000000..7b1e37f0e1e1
--- /dev/null
+++ b/src/main/java/com/thealgorithms/ciphers/ECC.java
@@ -0,0 +1,236 @@
+package com.thealgorithms.ciphers;
+
+import java.math.BigInteger;
+import java.security.SecureRandom;
+
+/**
+ * ECC - Elliptic Curve Cryptography
+ * Elliptic Curve Cryptography is a public-key cryptography method that uses the algebraic structure of
+ * elliptic curves over finite fields. ECC provides a higher level of security with smaller key sizes compared
+ * to other public-key methods like RSA, making it particularly suitable for environments where computational
+ * resources are limited, such as mobile devices and embedded systems.
+ *
+ * This class implements elliptic curve cryptography, providing encryption and decryption
+ * functionalities based on public and private key pairs.
+ *
+ * @author xuyang
+ */
+public class ECC {
+
+ private BigInteger privateKey; // Private key used for decryption
+ private ECPoint publicKey; // Public key used for encryption
+ private EllipticCurve curve; // Elliptic curve used in cryptography
+ private ECPoint basePoint; // Base point G on the elliptic curve
+
+ public ECC(int bits) {
+ generateKeys(bits); // Generates public-private key pair
+ }
+
+ public EllipticCurve getCurve() {
+ return curve; // Returns the elliptic curve
+ }
+
+ public void setCurve(EllipticCurve curve) {
+ this.curve = curve;
+ }
+
+ // Getter and Setter for private key
+ public BigInteger getPrivateKey() {
+ return privateKey;
+ }
+
+ public void setPrivateKey(BigInteger privateKey) {
+ this.privateKey = privateKey;
+ }
+
+ /**
+ * Encrypts the message using the public key.
+ * The message is transformed into an ECPoint and encrypted with elliptic curve operations.
+ *
+ * @param message The plain message to be encrypted
+ * @return The encrypted message as an array of ECPoints (R, S)
+ */
+ public ECPoint[] encrypt(String message) {
+ BigInteger m = new BigInteger(message.getBytes()); // Convert message to BigInteger
+ SecureRandom r = new SecureRandom(); // Generate random value for k
+ BigInteger k = new BigInteger(curve.getFieldSize(), r); // Generate random scalar k
+
+ // Calculate point r = k * G, where G is the base point
+ ECPoint rPoint = basePoint.multiply(k, curve.getP(), curve.getA());
+
+ // Calculate point s = k * publicKey + encodedMessage
+ ECPoint sPoint = publicKey.multiply(k, curve.getP(), curve.getA()).add(curve.encodeMessage(m), curve.getP(), curve.getA());
+
+ return new ECPoint[] {rPoint, sPoint}; // Return encrypted message as two ECPoints
+ }
+
+ /**
+ * Decrypts the encrypted message using the private key.
+ * The decryption process is the reverse of encryption, recovering the original message.
+ *
+ * @param encryptedMessage The encrypted message as an array of ECPoints (R, S)
+ * @return The decrypted plain message as a String
+ */
+ public String decrypt(ECPoint[] encryptedMessage) {
+ ECPoint rPoint = encryptedMessage[0]; // First part of ciphertext
+ ECPoint sPoint = encryptedMessage[1]; // Second part of ciphertext
+
+ // Perform decryption: s - r * privateKey
+ ECPoint decodedMessage = sPoint.subtract(rPoint.multiply(privateKey, curve.getP(), curve.getA()), curve.getP(), curve.getA());
+
+ BigInteger m = curve.decodeMessage(decodedMessage); // Decode the message from ECPoint
+
+ return new String(m.toByteArray()); // Convert BigInteger back to String
+ }
+
+ /**
+ * Generates a new public-private key pair for encryption and decryption.
+ *
+ * @param bits The size (in bits) of the keys to generate
+ */
+ public final void generateKeys(int bits) {
+ SecureRandom r = new SecureRandom();
+ curve = new EllipticCurve(bits); // Initialize a new elliptic curve
+ basePoint = curve.getBasePoint(); // Set the base point G
+
+ // Generate private key as a random BigInteger
+ privateKey = new BigInteger(bits, r);
+
+ // Generate public key as the point publicKey = privateKey * G
+ publicKey = basePoint.multiply(privateKey, curve.getP(), curve.getA());
+ }
+
+ /**
+ * Class representing an elliptic curve with the form y^2 = x^3 + ax + b.
+ */
+ public static class EllipticCurve {
+ private final BigInteger a; // Coefficient a in the curve equation
+ private final BigInteger b; // Coefficient b in the curve equation
+ private final BigInteger p; // Prime number p, defining the finite field
+ private final ECPoint basePoint; // Base point G on the curve
+
+ // Constructor with explicit parameters for a, b, p, and base point
+ public EllipticCurve(BigInteger a, BigInteger b, BigInteger p, ECPoint basePoint) {
+ this.a = a;
+ this.b = b;
+ this.p = p;
+ this.basePoint = basePoint;
+ }
+
+ // Constructor that randomly generates the curve parameters
+ public EllipticCurve(int bits) {
+ SecureRandom r = new SecureRandom();
+ this.p = BigInteger.probablePrime(bits, r); // Random prime p
+ this.a = new BigInteger(bits, r); // Random coefficient a
+ this.b = new BigInteger(bits, r); // Random coefficient b
+ this.basePoint = new ECPoint(BigInteger.valueOf(4), BigInteger.valueOf(8)); // Fixed base point G
+ }
+
+ public ECPoint getBasePoint() {
+ return basePoint;
+ }
+
+ public BigInteger getP() {
+ return p;
+ }
+
+ public BigInteger getA() {
+ return a;
+ }
+
+ public BigInteger getB() {
+ return b;
+ }
+
+ public int getFieldSize() {
+ return p.bitLength();
+ }
+
+ public ECPoint encodeMessage(BigInteger message) {
+ // Simple encoding of a message as an ECPoint (this is a simplified example)
+ return new ECPoint(message, message);
+ }
+
+ public BigInteger decodeMessage(ECPoint point) {
+ return point.getX(); // Decode the message from ECPoint (simplified)
+ }
+ }
+
+ /**
+ * Class representing a point on the elliptic curve.
+ */
+ public static class ECPoint {
+ private final BigInteger x; // X-coordinate of the point
+ private final BigInteger y; // Y-coordinate of the point
+
+ public ECPoint(BigInteger x, BigInteger y) {
+ this.x = x;
+ this.y = y;
+ }
+
+ public BigInteger getX() {
+ return x;
+ }
+
+ public BigInteger getY() {
+ return y;
+ }
+
+ @Override
+ public String toString() {
+ return "ECPoint(x=" + x.toString() + ", y=" + y.toString() + ")";
+ }
+
+ /**
+ * Add two points on the elliptic curve.
+ */
+ public ECPoint add(ECPoint other, BigInteger p, BigInteger a) {
+ if (this.x.equals(BigInteger.ZERO) && this.y.equals(BigInteger.ZERO)) {
+ return other; // If this point is the identity, return the other point
+ }
+ if (other.x.equals(BigInteger.ZERO) && other.y.equals(BigInteger.ZERO)) {
+ return this; // If the other point is the identity, return this point
+ }
+
+ BigInteger lambda;
+ if (this.equals(other)) {
+ // Special case: point doubling
+ lambda = this.x.pow(2).multiply(BigInteger.valueOf(3)).add(a).multiply(this.y.multiply(BigInteger.valueOf(2)).modInverse(p)).mod(p);
+ } else {
+ // General case: adding two different points
+ lambda = other.y.subtract(this.y).multiply(other.x.subtract(this.x).modInverse(p)).mod(p);
+ }
+
+ BigInteger xr = lambda.pow(2).subtract(this.x).subtract(other.x).mod(p);
+ BigInteger yr = lambda.multiply(this.x.subtract(xr)).subtract(this.y).mod(p);
+
+ return new ECPoint(xr, yr);
+ }
+
+ /**
+ * Subtract two points on the elliptic curve.
+ */
+ public ECPoint subtract(ECPoint other, BigInteger p, BigInteger a) {
+ ECPoint negOther = new ECPoint(other.x, p.subtract(other.y)); // Negate the Y coordinate
+ return this.add(negOther, p, a); // Add the negated point
+ }
+
+ /**
+ * Multiply a point by a scalar (repeated addition).
+ */
+ public ECPoint multiply(BigInteger k, BigInteger p, BigInteger a) {
+ ECPoint result = new ECPoint(BigInteger.ZERO, BigInteger.ZERO); // Identity point
+ ECPoint addend = this;
+
+ while (k.signum() > 0) {
+ if (k.testBit(0)) {
+ result = result.add(addend, p, a); // Add the current point
+ }
+ addend = addend.add(addend, p, a); // Double the point
+ k = k.shiftRight(1); // Divide k by 2
+ }
+
+ return result;
+ }
+ }
+}
diff --git a/src/main/java/com/thealgorithms/ciphers/MonoAlphabetic.java b/src/main/java/com/thealgorithms/ciphers/MonoAlphabetic.java
new file mode 100644
index 000000000000..1d5b7110a6f3
--- /dev/null
+++ b/src/main/java/com/thealgorithms/ciphers/MonoAlphabetic.java
@@ -0,0 +1,48 @@
+package com.thealgorithms.ciphers;
+
+public final class MonoAlphabetic {
+
+ private MonoAlphabetic() {
+ throw new UnsupportedOperationException("Utility class");
+ }
+
+ // Encryption method
+ public static String encrypt(String data, String key) {
+ if (!data.matches("[A-Z]+")) {
+ throw new IllegalArgumentException("Input data contains invalid characters. Only uppercase A-Z are allowed.");
+ }
+ StringBuilder sb = new StringBuilder();
+
+ // Encrypt each character
+ for (char c : data.toCharArray()) {
+ int idx = charToPos(c); // Get the index of the character
+ sb.append(key.charAt(idx)); // Map to the corresponding character in the key
+ }
+ return sb.toString();
+ }
+
+ // Decryption method
+ public static String decrypt(String data, String key) {
+ StringBuilder sb = new StringBuilder();
+
+ // Decrypt each character
+ for (char c : data.toCharArray()) {
+ int idx = key.indexOf(c); // Find the index of the character in the key
+ if (idx == -1) {
+ throw new IllegalArgumentException("Input data contains invalid characters.");
+ }
+ sb.append(posToChar(idx)); // Convert the index back to the original character
+ }
+ return sb.toString();
+ }
+
+ // Helper method: Convert a character to its position in the alphabet
+ private static int charToPos(char c) {
+ return c - 'A'; // Subtract 'A' to get position (0 for A, 1 for B, etc.)
+ }
+
+ // Helper method: Convert a position in the alphabet to a character
+ private static char posToChar(int pos) {
+ return (char) (pos + 'A'); // Add 'A' to convert position back to character
+ }
+}
diff --git a/src/main/java/com/thealgorithms/ciphers/PermutationCipher.java b/src/main/java/com/thealgorithms/ciphers/PermutationCipher.java
new file mode 100644
index 000000000000..ce443545db1d
--- /dev/null
+++ b/src/main/java/com/thealgorithms/ciphers/PermutationCipher.java
@@ -0,0 +1,194 @@
+package com.thealgorithms.ciphers;
+
+import java.util.HashSet;
+import java.util.Set;
+
+/**
+ * A Java implementation of Permutation Cipher.
+ * It is a type of transposition cipher in which the plaintext is divided into blocks
+ * and the characters within each block are rearranged according to a fixed permutation key.
+ *
+ * For example, with key {3, 1, 2} and plaintext "HELLO", the text is divided into blocks
+ * of 3 characters: "HEL" and "LO" (with padding). The characters are then rearranged
+ * according to the key positions.
+ *
+ * @author GitHub Copilot
+ */
+public class PermutationCipher {
+
+ private static final char PADDING_CHAR = 'X';
+
+ /**
+ * Encrypts the given plaintext using the permutation cipher with the specified key.
+ *
+ * @param plaintext the text to encrypt
+ * @param key the permutation key (array of integers representing positions)
+ * @return the encrypted text
+ * @throws IllegalArgumentException if the key is invalid
+ */
+ public String encrypt(String plaintext, int[] key) {
+ validateKey(key);
+
+ if (plaintext == null || plaintext.isEmpty()) {
+ return plaintext;
+ }
+
+ // Remove spaces and convert to uppercase for consistent processing
+ String cleanText = plaintext.replaceAll("\\s+", "").toUpperCase();
+
+ // Pad the text to make it divisible by key length
+ String paddedText = padText(cleanText, key.length);
+
+ StringBuilder encrypted = new StringBuilder();
+
+ // Process text in blocks of key length
+ for (int i = 0; i < paddedText.length(); i += key.length) {
+ String block = paddedText.substring(i, Math.min(i + key.length, paddedText.length()));
+ encrypted.append(permuteBlock(block, key));
+ }
+
+ return encrypted.toString();
+ }
+
+ /**
+ * Decrypts the given ciphertext using the permutation cipher with the specified key.
+ *
+ * @param ciphertext the text to decrypt
+ * @param key the permutation key (array of integers representing positions)
+ * @return the decrypted text
+ * @throws IllegalArgumentException if the key is invalid
+ */
+ public String decrypt(String ciphertext, int[] key) {
+ validateKey(key);
+
+ if (ciphertext == null || ciphertext.isEmpty()) {
+ return ciphertext;
+ }
+
+ // Create the inverse permutation
+ int[] inverseKey = createInverseKey(key);
+
+ StringBuilder decrypted = new StringBuilder();
+
+ // Process text in blocks of key length
+ for (int i = 0; i < ciphertext.length(); i += key.length) {
+ String block = ciphertext.substring(i, Math.min(i + key.length, ciphertext.length()));
+ decrypted.append(permuteBlock(block, inverseKey));
+ }
+
+ // Remove padding characters from the end
+ return removePadding(decrypted.toString());
+ }
+ /**
+ * Validates that the permutation key is valid.
+ * A valid key must contain all integers from 1 to n exactly once, where n is the key length.
+ *
+ * @param key the permutation key to validate
+ * @throws IllegalArgumentException if the key is invalid
+ */
+ private void validateKey(int[] key) {
+ if (key == null || key.length == 0) {
+ throw new IllegalArgumentException("Key cannot be null or empty");
+ }
+
+ Set keySet = new HashSet<>();
+ for (int position : key) {
+ if (position < 1 || position > key.length) {
+ throw new IllegalArgumentException("Key must contain integers from 1 to " + key.length);
+ }
+ if (!keySet.add(position)) {
+ throw new IllegalArgumentException("Key must contain each position exactly once");
+ }
+ }
+ }
+
+ /**
+ * Pads the text with padding characters to make its length divisible by the block size.
+ *
+ * @param text the text to pad
+ * @param blockSize the size of each block
+ * @return the padded text
+ */
+ private String padText(String text, int blockSize) {
+ int remainder = text.length() % blockSize;
+ if (remainder == 0) {
+ return text;
+ }
+
+ int paddingNeeded = blockSize - remainder;
+ StringBuilder padded = new StringBuilder(text);
+ for (int i = 0; i < paddingNeeded; i++) {
+ padded.append(PADDING_CHAR);
+ }
+
+ return padded.toString();
+ }
+ /**
+ * Applies the permutation to a single block of text.
+ *
+ * @param block the block to permute
+ * @param key the permutation key
+ * @return the permuted block
+ */
+ private String permuteBlock(String block, int[] key) {
+ if (block.length() != key.length) {
+ // Handle case where block is shorter than key (shouldn't happen with proper padding)
+ block = padText(block, key.length);
+ }
+
+ char[] result = new char[key.length];
+ char[] blockChars = block.toCharArray();
+
+ for (int i = 0; i < key.length; i++) {
+ // Key positions are 1-based, so subtract 1 for 0-based array indexing
+ result[i] = blockChars[key[i] - 1];
+ }
+
+ return new String(result);
+ }
+
+ /**
+ * Creates the inverse permutation key for decryption.
+ *
+ * @param key the original permutation key
+ * @return the inverse key
+ */
+ private int[] createInverseKey(int[] key) {
+ int[] inverse = new int[key.length];
+
+ for (int i = 0; i < key.length; i++) {
+ // The inverse key maps each position to where it should go
+ inverse[key[i] - 1] = i + 1;
+ }
+
+ return inverse;
+ }
+
+ /**
+ * Removes padding characters from the end of the decrypted text.
+ *
+ * @param text the text to remove padding from
+ * @return the text without padding
+ */
+ private String removePadding(String text) {
+ if (text.isEmpty()) {
+ return text;
+ }
+
+ int i = text.length() - 1;
+ while (i >= 0 && text.charAt(i) == PADDING_CHAR) {
+ i--;
+ }
+
+ return text.substring(0, i + 1);
+ }
+
+ /**
+ * Gets the padding character used by this cipher.
+ *
+ * @return the padding character
+ */
+ public char getPaddingChar() {
+ return PADDING_CHAR;
+ }
+}
diff --git a/src/main/java/com/thealgorithms/ciphers/RSA.java b/src/main/java/com/thealgorithms/ciphers/RSA.java
index f50e501e68c8..28af1a62032a 100644
--- a/src/main/java/com/thealgorithms/ciphers/RSA.java
+++ b/src/main/java/com/thealgorithms/ciphers/RSA.java
@@ -4,7 +4,27 @@
import java.security.SecureRandom;
/**
- * @author Nguyen Duy Tiep on 23-Oct-17.
+ * RSA is an asymmetric cryptographic algorithm used for secure data encryption and decryption.
+ * It relies on a pair of keys: a public key (used for encryption) and a private key
+ * (used for decryption). The algorithm is based on the difficulty of factoring large prime numbers.
+ *
+ * This implementation includes key generation, encryption, and decryption methods that can handle both
+ * text-based messages and BigInteger inputs. For more details on RSA:
+ * RSA Cryptosystem - Wikipedia.
+ *
+ * Example Usage:
+ *
+ * RSA rsa = new RSA(1024);
+ * String encryptedMessage = rsa.encrypt("Hello RSA!");
+ * String decryptedMessage = rsa.decrypt(encryptedMessage);
+ * System.out.println(decryptedMessage); // Output: Hello RSA!
+ *
+ *
+ * Note: The key size directly affects the security and performance of the RSA algorithm.
+ * Larger keys are more secure but slower to compute.
+ *
+ * @author Nguyen Duy Tiep
+ * @version 23-Oct-17
*/
public class RSA {
@@ -12,55 +32,88 @@ public class RSA {
private BigInteger privateKey;
private BigInteger publicKey;
+ /**
+ * Constructor that generates RSA keys with the specified number of bits.
+ *
+ * @param bits The bit length of the keys to be generated. Common sizes include 512, 1024, 2048, etc.
+ */
public RSA(int bits) {
generateKeys(bits);
}
/**
- * @return encrypted message
+ * Encrypts a text message using the RSA public key.
+ *
+ * @param message The plaintext message to be encrypted.
+ * @throws IllegalArgumentException If the message is empty.
+ * @return The encrypted message represented as a String.
*/
public synchronized String encrypt(String message) {
+ if (message.isEmpty()) {
+ throw new IllegalArgumentException("Message is empty");
+ }
return (new BigInteger(message.getBytes())).modPow(publicKey, modulus).toString();
}
/**
- * @return encrypted message as big integer
+ * Encrypts a BigInteger message using the RSA public key.
+ *
+ * @param message The plaintext message as a BigInteger.
+ * @return The encrypted message as a BigInteger.
*/
public synchronized BigInteger encrypt(BigInteger message) {
return message.modPow(publicKey, modulus);
}
/**
- * @return plain message
+ * Decrypts an encrypted message (as String) using the RSA private key.
+ *
+ * @param encryptedMessage The encrypted message to be decrypted, represented as a String.
+ * @throws IllegalArgumentException If the message is empty.
+ * @return The decrypted plaintext message as a String.
*/
public synchronized String decrypt(String encryptedMessage) {
+ if (encryptedMessage.isEmpty()) {
+ throw new IllegalArgumentException("Message is empty");
+ }
return new String((new BigInteger(encryptedMessage)).modPow(privateKey, modulus).toByteArray());
}
/**
- * @return plain message as big integer
+ * Decrypts an encrypted BigInteger message using the RSA private key.
+ *
+ * @param encryptedMessage The encrypted message as a BigInteger.
+ * @return The decrypted plaintext message as a BigInteger.
*/
public synchronized BigInteger decrypt(BigInteger encryptedMessage) {
return encryptedMessage.modPow(privateKey, modulus);
}
/**
- * Generate a new public and private key set.
+ * Generates a new RSA key pair (public and private keys) with the specified bit length.
+ * Steps:
+ * 1. Generate two large prime numbers p and q.
+ * 2. Compute the modulus n = p * q.
+ * 3. Compute Euler's totient function: φ(n) = (p-1) * (q-1).
+ * 4. Choose a public key e (starting from 3) that is coprime with φ(n).
+ * 5. Compute the private key d as the modular inverse of e mod φ(n).
+ * The public key is (e, n) and the private key is (d, n).
+ *
+ * @param bits The bit length of the keys to be generated.
*/
public final synchronized void generateKeys(int bits) {
- SecureRandom r = new SecureRandom();
- BigInteger p = new BigInteger(bits / 2, 100, r);
- BigInteger q = new BigInteger(bits / 2, 100, r);
+ SecureRandom random = new SecureRandom();
+ BigInteger p = new BigInteger(bits / 2, 100, random);
+ BigInteger q = new BigInteger(bits / 2, 100, random);
modulus = p.multiply(q);
- BigInteger m = (p.subtract(BigInteger.ONE)).multiply(q.subtract(BigInteger.ONE));
+ BigInteger phi = (p.subtract(BigInteger.ONE)).multiply(q.subtract(BigInteger.ONE));
publicKey = BigInteger.valueOf(3L);
-
- while (m.gcd(publicKey).intValue() > 1) {
+ while (phi.gcd(publicKey).intValue() > 1) {
publicKey = publicKey.add(BigInteger.TWO);
}
- privateKey = publicKey.modInverse(m);
+ privateKey = publicKey.modInverse(phi);
}
}
diff --git a/src/main/java/com/thealgorithms/ciphers/RailFenceCipher.java b/src/main/java/com/thealgorithms/ciphers/RailFenceCipher.java
new file mode 100644
index 000000000000..f81252980468
--- /dev/null
+++ b/src/main/java/com/thealgorithms/ciphers/RailFenceCipher.java
@@ -0,0 +1,147 @@
+package com.thealgorithms.ciphers;
+
+import java.util.Arrays;
+
+/**
+ * The rail fence cipher (also called a zigzag cipher) is a classical type of transposition cipher.
+ * It derives its name from the manner in which encryption is performed, in analogy to a fence built with horizontal rails.
+ * https://en.wikipedia.org/wiki/Rail_fence_cipher
+ * @author https://github.com/Krounosity
+ */
+
+public class RailFenceCipher {
+
+ // Encrypts the input string using the rail fence cipher method with the given number of rails.
+ public String encrypt(String str, int rails) {
+
+ // Base case of single rail or rails are more than the number of characters in the string
+ if (rails == 1 || rails >= str.length()) {
+ return str;
+ }
+
+ // Boolean flag to determine if the movement is downward or upward in the rail matrix.
+ boolean down = true;
+ // Create a 2D array to represent the rails (rows) and the length of the string (columns).
+ char[][] strRail = new char[rails][str.length()];
+
+ // Initialize all positions in the rail matrix with a placeholder character ('\n').
+ for (int i = 0; i < rails; i++) {
+ Arrays.fill(strRail[i], '\n');
+ }
+
+ int row = 0; // Start at the first row
+ int col = 0; // Start at the first column
+
+ int i = 0;
+
+ // Fill the rail matrix with characters from the string based on the rail pattern.
+ while (col < str.length()) {
+ // Change direction to down when at the first row.
+ if (row == 0) {
+ down = true;
+ }
+ // Change direction to up when at the last row.
+ else if (row == rails - 1) {
+ down = false;
+ }
+
+ // Place the character in the current position of the rail matrix.
+ strRail[row][col] = str.charAt(i);
+ col++; // Move to the next column.
+ // Move to the next row based on the direction.
+ if (down) {
+ row++;
+ } else {
+ row--;
+ }
+
+ i++;
+ }
+
+ // Construct the encrypted string by reading characters row by row.
+ StringBuilder encryptedString = new StringBuilder();
+ for (char[] chRow : strRail) {
+ for (char ch : chRow) {
+ if (ch != '\n') {
+ encryptedString.append(ch);
+ }
+ }
+ }
+ return encryptedString.toString();
+ }
+ // Decrypts the input string using the rail fence cipher method with the given number of rails.
+ public String decrypt(String str, int rails) {
+
+ // Base case of single rail or rails are more than the number of characters in the string
+ if (rails == 1 || rails >= str.length()) {
+ return str;
+ }
+ // Boolean flag to determine if the movement is downward or upward in the rail matrix.
+ boolean down = true;
+
+ // Create a 2D array to represent the rails (rows) and the length of the string (columns).
+ char[][] strRail = new char[rails][str.length()];
+
+ int row = 0; // Start at the first row
+ int col = 0; // Start at the first column
+
+ // Mark the pattern on the rail matrix using '*'.
+ while (col < str.length()) {
+ // Change direction to down when at the first row.
+ if (row == 0) {
+ down = true;
+ }
+ // Change direction to up when at the last row.
+ else if (row == rails - 1) {
+ down = false;
+ }
+
+ // Mark the current position in the rail matrix.
+ strRail[row][col] = '*';
+ col++; // Move to the next column.
+ // Move to the next row based on the direction.
+ if (down) {
+ row++;
+ } else {
+ row--;
+ }
+ }
+
+ int index = 0; // Index to track characters from the input string.
+ // Fill the rail matrix with characters from the input string based on the marked pattern.
+ for (int i = 0; i < rails; i++) {
+ for (int j = 0; j < str.length(); j++) {
+ if (strRail[i][j] == '*') {
+ strRail[i][j] = str.charAt(index++);
+ }
+ }
+ }
+
+ // Construct the decrypted string by following the zigzag pattern.
+ StringBuilder decryptedString = new StringBuilder();
+ row = 0; // Reset to the first row
+ col = 0; // Reset to the first column
+
+ while (col < str.length()) {
+ // Change direction to down when at the first row.
+ if (row == 0) {
+ down = true;
+ }
+ // Change direction to up when at the last row.
+ else if (row == rails - 1) {
+ down = false;
+ }
+ // Append the character from the rail matrix to the decrypted string.
+ decryptedString.append(strRail[row][col]);
+ col++; // Move to the next column.
+ // Move to the next row based on the direction.
+ if (down) {
+ row++;
+ } else {
+ row--;
+ }
+ }
+
+ return decryptedString.toString();
+ }
+}
diff --git a/src/main/java/com/thealgorithms/ciphers/Vigenere.java b/src/main/java/com/thealgorithms/ciphers/Vigenere.java
index 1702f1abb94c..0f117853bb85 100644
--- a/src/main/java/com/thealgorithms/ciphers/Vigenere.java
+++ b/src/main/java/com/thealgorithms/ciphers/Vigenere.java
@@ -1,16 +1,54 @@
package com.thealgorithms.ciphers;
/**
- * A Java implementation of Vigenere Cipher.
+ * A Java implementation of the Vigenère Cipher.
+ *
+ * The Vigenère Cipher is a polyalphabetic substitution cipher that uses a
+ * keyword to shift letters in the plaintext by different amounts, depending
+ * on the corresponding character in the keyword. It wraps around the alphabet,
+ * ensuring the shifts are within 'A'-'Z' or 'a'-'z'.
+ *
+ * Non-alphabetic characters (like spaces, punctuation) are kept unchanged.
+ *
+ * Encryption Example:
+ * - Plaintext: "Hello World!"
+ * - Key: "suchsecret"
+ * - Encrypted Text: "Zynsg Yfvev!"
+ *
+ * Decryption Example:
+ * - Ciphertext: "Zynsg Yfvev!"
+ * - Key: "suchsecret"
+ * - Decrypted Text: "Hello World!"
+ *
+ * Wikipedia Reference:
+ * Vigenère Cipher - Wikipedia
*
* @author straiffix
* @author beingmartinbmc
*/
public class Vigenere {
+ /**
+ * Encrypts a given message using the Vigenère Cipher with the specified key.
+ * Steps:
+ * 1. Iterate over each character in the message.
+ * 2. If the character is a letter, shift it by the corresponding character in the key.
+ * 3. Preserve the case of the letter.
+ * 4. Preserve non-alphabetic characters.
+ * 5. Move to the next character in the key (cyclic).
+ * 6. Return the encrypted message.
+ *
+ * @param message The plaintext message to encrypt.
+ * @param key The keyword used for encryption.
+ * @throws IllegalArgumentException if the key is empty.
+ * @return The encrypted message.
+ */
public String encrypt(final String message, final String key) {
- StringBuilder result = new StringBuilder();
+ if (key.isEmpty()) {
+ throw new IllegalArgumentException("Key cannot be empty.");
+ }
+ StringBuilder result = new StringBuilder();
int j = 0;
for (int i = 0; i < message.length(); i++) {
char c = message.charAt(i);
@@ -20,17 +58,35 @@ public String encrypt(final String message, final String key) {
} else {
result.append((char) ((c + key.toLowerCase().charAt(j) - 2 * 'a') % 26 + 'a'));
}
+ j = ++j % key.length();
} else {
result.append(c);
}
- j = ++j % key.length();
}
return result.toString();
}
+ /**
+ * Decrypts a given message encrypted with the Vigenère Cipher using the specified key.
+ * Steps:
+ * 1. Iterate over each character in the message.
+ * 2. If the character is a letter, shift it back by the corresponding character in the key.
+ * 3. Preserve the case of the letter.
+ * 4. Preserve non-alphabetic characters.
+ * 5. Move to the next character in the key (cyclic).
+ * 6. Return the decrypted message.
+ *
+ * @param message The encrypted message to decrypt.
+ * @param key The keyword used for decryption.
+ * @throws IllegalArgumentException if the key is empty.
+ * @return The decrypted plaintext message.
+ */
public String decrypt(final String message, final String key) {
- StringBuilder result = new StringBuilder();
+ if (key.isEmpty()) {
+ throw new IllegalArgumentException("Key cannot be empty.");
+ }
+ StringBuilder result = new StringBuilder();
int j = 0;
for (int i = 0; i < message.length(); i++) {
char c = message.charAt(i);
@@ -40,11 +96,10 @@ public String decrypt(final String message, final String key) {
} else {
result.append((char) ('z' - (25 - (c - key.toLowerCase().charAt(j))) % 26));
}
+ j = ++j % key.length();
} else {
result.append(c);
}
-
- j = ++j % key.length();
}
return result.toString();
}
diff --git a/src/main/java/com/thealgorithms/ciphers/XORCipher.java b/src/main/java/com/thealgorithms/ciphers/XORCipher.java
index c4410d8c77ba..a612ccfbcdef 100644
--- a/src/main/java/com/thealgorithms/ciphers/XORCipher.java
+++ b/src/main/java/com/thealgorithms/ciphers/XORCipher.java
@@ -5,18 +5,46 @@
import java.util.HexFormat;
/**
- * A simple implementation of XOR cipher that, given a key, allows to encrypt and decrypt a plaintext.
+ * A simple implementation of the XOR cipher that allows both encryption and decryption
+ * using a given key. This cipher works by applying the XOR bitwise operation between
+ * the bytes of the input text and the corresponding bytes of the key (repeating the key
+ * if necessary).
*
- * @author lcsjunior
+ * Usage:
+ * - Encryption: Converts plaintext into a hexadecimal-encoded ciphertext.
+ * - Decryption: Converts the hexadecimal ciphertext back into plaintext.
+ *
+ * Characteristics:
+ * - Symmetric: The same key is used for both encryption and decryption.
+ * - Simple but vulnerable: XOR encryption is insecure for real-world cryptography,
+ * especially when the same key is reused.
+ *
+ * Example:
+ * Plaintext: "Hello!"
+ * Key: "key"
+ * Encrypted: "27090c03120b"
+ * Decrypted: "Hello!"
*
+ * Reference: XOR Cipher - Wikipedia
+ *
+ * @author lcsjunior
*/
public final class XORCipher {
+ // Default character encoding for string conversion
private static final Charset CS_DEFAULT = StandardCharsets.UTF_8;
private XORCipher() {
}
+ /**
+ * Applies the XOR operation between the input bytes and the key bytes.
+ * If the key is shorter than the input, it wraps around (cyclically).
+ *
+ * @param inputBytes The input byte array (plaintext or ciphertext).
+ * @param keyBytes The key byte array used for XOR operation.
+ * @return A new byte array containing the XOR result.
+ */
public static byte[] xor(final byte[] inputBytes, final byte[] keyBytes) {
byte[] outputBytes = new byte[inputBytes.length];
for (int i = 0; i < inputBytes.length; ++i) {
@@ -25,14 +53,40 @@ public static byte[] xor(final byte[] inputBytes, final byte[] keyBytes) {
return outputBytes;
}
+ /**
+ * Encrypts the given plaintext using the XOR cipher with the specified key.
+ * The result is a hexadecimal-encoded string representing the ciphertext.
+ *
+ * @param plainText The input plaintext to encrypt.
+ * @param key The encryption key.
+ * @throws IllegalArgumentException if the key is empty.
+ * @return A hexadecimal string representing the encrypted text.
+ */
public static String encrypt(final String plainText, final String key) {
+ if (key.isEmpty()) {
+ throw new IllegalArgumentException("Key must not be empty");
+ }
+
byte[] plainTextBytes = plainText.getBytes(CS_DEFAULT);
byte[] keyBytes = key.getBytes(CS_DEFAULT);
byte[] xorResult = xor(plainTextBytes, keyBytes);
return HexFormat.of().formatHex(xorResult);
}
+ /**
+ * Decrypts the given ciphertext (in hexadecimal format) using the XOR cipher
+ * with the specified key. The result is the original plaintext.
+ *
+ * @param cipherText The hexadecimal string representing the encrypted text.
+ * @param key The decryption key (must be the same as the encryption key).
+ * @throws IllegalArgumentException if the key is empty.
+ * @return The decrypted plaintext.
+ */
public static String decrypt(final String cipherText, final String key) {
+ if (key.isEmpty()) {
+ throw new IllegalArgumentException("Key must not be empty");
+ }
+
byte[] cipherBytes = HexFormat.of().parseHex(cipherText);
byte[] keyBytes = key.getBytes(CS_DEFAULT);
byte[] xorResult = xor(cipherBytes, keyBytes);
diff --git a/src/main/java/com/thealgorithms/ciphers/a5/A5Cipher.java b/src/main/java/com/thealgorithms/ciphers/a5/A5Cipher.java
index b7d36db5c809..cc2e9105229a 100644
--- a/src/main/java/com/thealgorithms/ciphers/a5/A5Cipher.java
+++ b/src/main/java/com/thealgorithms/ciphers/a5/A5Cipher.java
@@ -2,17 +2,43 @@
import java.util.BitSet;
-// https://en.wikipedia.org/wiki/A5/1
+/**
+ * The A5Cipher class implements the A5/1 stream cipher, which is a widely used
+ * encryption algorithm, particularly in mobile communications.
+ *
+ * This implementation uses a key stream generator to produce a stream of bits
+ * that are XORed with the plaintext bits to produce the ciphertext.
+ *
+ *
+ * For more details about the A5/1 algorithm, refer to
+ * Wikipedia.
+ *
+ */
public class A5Cipher {
private final A5KeyStreamGenerator keyStreamGenerator;
- private static final int KEY_STREAM_LENGTH = 228; // 28.5 bytes so we need to pad bytes or something
-
+ private static final int KEY_STREAM_LENGTH = 228; // Length of the key stream in bits (28.5 bytes)
+
+ /**
+ * Constructs an A5Cipher instance with the specified session key and frame counter.
+ *
+ * @param sessionKey a BitSet representing the session key used for encryption.
+ * @param frameCounter a BitSet representing the frame counter that helps in key stream generation.
+ */
public A5Cipher(BitSet sessionKey, BitSet frameCounter) {
keyStreamGenerator = new A5KeyStreamGenerator();
keyStreamGenerator.initialize(sessionKey, frameCounter);
}
+ /**
+ * Encrypts the given plaintext bits using the A5/1 cipher algorithm.
+ *
+ * This method generates a key stream and XORs it with the provided plaintext
+ * bits to produce the ciphertext.
+ *
+ * @param plainTextBits a BitSet representing the plaintext bits to be encrypted.
+ * @return a BitSet containing the encrypted ciphertext bits.
+ */
public BitSet encrypt(BitSet plainTextBits) {
// create a copy
var result = new BitSet(KEY_STREAM_LENGTH);
@@ -24,6 +50,13 @@ public BitSet encrypt(BitSet plainTextBits) {
return result;
}
+ /**
+ * Resets the internal counter of the key stream generator.
+ *
+ * This method can be called to re-initialize the state of the key stream
+ * generator, allowing for new key streams to be generated for subsequent
+ * encryptions.
+ */
public void resetCounter() {
keyStreamGenerator.reInitialize();
}
diff --git a/src/main/java/com/thealgorithms/ciphers/a5/A5KeyStreamGenerator.java b/src/main/java/com/thealgorithms/ciphers/a5/A5KeyStreamGenerator.java
index 0b17a685bc57..ee837ef4241a 100644
--- a/src/main/java/com/thealgorithms/ciphers/a5/A5KeyStreamGenerator.java
+++ b/src/main/java/com/thealgorithms/ciphers/a5/A5KeyStreamGenerator.java
@@ -2,15 +2,39 @@
import java.util.BitSet;
-// TODO: raise exceptions for improper use
+/**
+ * The A5KeyStreamGenerator class is responsible for generating key streams
+ * for the A5/1 encryption algorithm using a combination of Linear Feedback Shift Registers (LFSRs).
+ *
+ *
+ * This class extends the CompositeLFSR and initializes a set of LFSRs with
+ * a session key and a frame counter to produce a pseudo-random key stream.
+ *
+ *
+ *
+ * Note: Proper exception handling for invalid usage is to be implemented.
+ *
+ */
public class A5KeyStreamGenerator extends CompositeLFSR {
private BitSet initialFrameCounter;
private BitSet frameCounter;
private BitSet sessionKey;
private static final int INITIAL_CLOCKING_CYCLES = 100;
- private static final int KEY_STREAM_LENGTH = 228; // 28.5 bytes so we need to pad bytes or something
+ private static final int KEY_STREAM_LENGTH = 228;
+ /**
+ * Initializes the A5KeyStreamGenerator with the specified session key and frame counter.
+ *
+ *
+ * This method sets up the internal state of the LFSRs using the provided
+ * session key and frame counter. It creates three LFSRs with specific
+ * configurations and initializes them.
+ *
+ *
+ * @param sessionKey a BitSet representing the session key used for key stream generation.
+ * @param frameCounter a BitSet representing the frame counter that influences the key stream.
+ */
@Override
public void initialize(BitSet sessionKey, BitSet frameCounter) {
this.sessionKey = sessionKey;
@@ -26,10 +50,26 @@ public void initialize(BitSet sessionKey, BitSet frameCounter) {
registers.forEach(lfsr -> lfsr.initialize(sessionKey, frameCounter));
}
+ /**
+ * Re-initializes the key stream generator with the original session key
+ * and frame counter. This method restores the generator to its initial
+ * state.
+ */
public void reInitialize() {
this.initialize(sessionKey, initialFrameCounter);
}
+ /**
+ * Generates the next key stream of bits.
+ *
+ *
+ * This method performs an initial set of clocking cycles and then retrieves
+ * a key stream of the specified length. After generation, it re-initializes
+ * the internal registers.
+ *
+ *
+ * @return a BitSet containing the generated key stream bits.
+ */
public BitSet getNextKeyStream() {
for (int cycle = 1; cycle <= INITIAL_CLOCKING_CYCLES; ++cycle) {
this.clock();
@@ -45,12 +85,37 @@ public BitSet getNextKeyStream() {
return result;
}
+ /**
+ * Re-initializes the registers for the LFSRs.
+ *
+ *
+ * This method increments the frame counter and re-initializes each LFSR
+ * with the current session key and frame counter.
+ *
+ */
private void reInitializeRegisters() {
incrementFrameCounter();
registers.forEach(lfsr -> lfsr.initialize(sessionKey, frameCounter));
}
+ /**
+ * Increments the current frame counter.
+ *
+ *
+ * This method uses a utility function to increment the frame counter,
+ * which influences the key stream generation process.
+ *
+ */
private void incrementFrameCounter() {
Utils.increment(frameCounter, FRAME_COUNTER_LENGTH);
}
+
+ /**
+ * Retrieves the current frame counter.
+ *
+ * @return a BitSet representing the current state of the frame counter.
+ */
+ public BitSet getFrameCounter() {
+ return frameCounter;
+ }
}
diff --git a/src/main/java/com/thealgorithms/ciphers/a5/CompositeLFSR.java b/src/main/java/com/thealgorithms/ciphers/a5/CompositeLFSR.java
index f96946c39490..029a93848c28 100644
--- a/src/main/java/com/thealgorithms/ciphers/a5/CompositeLFSR.java
+++ b/src/main/java/com/thealgorithms/ciphers/a5/CompositeLFSR.java
@@ -5,13 +5,33 @@
import java.util.Map;
import java.util.TreeMap;
+/**
+ * The CompositeLFSR class represents a composite implementation of
+ * Linear Feedback Shift Registers (LFSRs) for cryptographic purposes.
+ *
+ *
+ * This abstract class manages a collection of LFSR instances and
+ * provides a mechanism for irregular clocking based on the
+ * majority bit among the registers. It implements the BaseLFSR
+ * interface, requiring subclasses to define specific LFSR behaviors.
+ *
+ */
public abstract class CompositeLFSR implements BaseLFSR {
protected final List registers = new ArrayList<>();
/**
- * Implements irregular clocking using the clock bit for each register
- * @return the registers discarded bit xored value
+ * Performs a clocking operation on the composite LFSR.
+ *
+ *
+ * This method determines the majority bit across all registers and
+ * clocks each register based on its clock bit. If a register's
+ * clock bit matches the majority bit, it is clocked (shifted).
+ * The method also computes and returns the XOR of the last bits
+ * of all registers.
+ *
+ *
+ * @return the XOR value of the last bits of all registers.
*/
@Override
public boolean clock() {
@@ -26,6 +46,18 @@ public boolean clock() {
return result;
}
+ /**
+ * Calculates the majority bit among all registers.
+ *
+ *
+ * This private method counts the number of true and false clock bits
+ * across all LFSR registers. It returns true if the count of true
+ * bits is greater than or equal to the count of false bits; otherwise,
+ * it returns false.
+ *
+ *
+ * @return true if the majority clock bits are true; false otherwise.
+ */
private boolean getMajorityBit() {
Map bitCount = new TreeMap<>();
bitCount.put(Boolean.FALSE, 0);
diff --git a/src/main/java/com/thealgorithms/compression/ArithmeticCoding.java b/src/main/java/com/thealgorithms/compression/ArithmeticCoding.java
new file mode 100644
index 000000000000..b5ccf359d1be
--- /dev/null
+++ b/src/main/java/com/thealgorithms/compression/ArithmeticCoding.java
@@ -0,0 +1,157 @@
+package com.thealgorithms.compression;
+
+import java.math.BigDecimal;
+import java.math.MathContext;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * An implementation of the Arithmetic Coding algorithm.
+ *
+ *
+ * Arithmetic coding is a form of entropy encoding used in lossless data
+ * compression. It encodes an entire message into a single number, a fraction n
+ * where (0.0 <= n < 1.0). Unlike Huffman coding, which assigns a specific
+ * bit sequence to each symbol, arithmetic coding represents the message as a
+ * sub-interval of the [0, 1) interval.
+ *
+ *
+ *
+ * This implementation uses BigDecimal for precision to handle the shrinking
+ * intervals, making it suitable for educational purposes to demonstrate the
+ * core logic.
+ *
+ *
+ *
+ * Time Complexity: O(n*m) for compression and decompression where n is the
+ * length of the input and m is the number of unique symbols, due to the need
+ * to calculate symbol probabilities.
+ *
+ *
+ *
+ * References:
+ *
+ *
+ */
+public final class ArithmeticCoding {
+
+ private ArithmeticCoding() {
+ }
+
+ /**
+ * Compresses a string using the Arithmetic Coding algorithm.
+ *
+ * @param uncompressed The string to be compressed.
+ * @return The compressed representation as a BigDecimal number.
+ * @throws IllegalArgumentException if the input string is null or empty.
+ */
+ public static BigDecimal compress(String uncompressed) {
+ if (uncompressed == null || uncompressed.isEmpty()) {
+ throw new IllegalArgumentException("Input string cannot be null or empty.");
+ }
+
+ Map probabilityTable = calculateProbabilities(uncompressed);
+
+ BigDecimal low = BigDecimal.ZERO;
+ BigDecimal high = BigDecimal.ONE;
+
+ for (char symbol : uncompressed.toCharArray()) {
+ BigDecimal range = high.subtract(low);
+ Symbol sym = probabilityTable.get(symbol);
+
+ high = low.add(range.multiply(sym.high()));
+ low = low.add(range.multiply(sym.low()));
+ }
+
+ return low; // Return the lower bound of the final interval
+ }
+
+ /**
+ * Decompresses a BigDecimal number back into the original string.
+ *
+ * @param compressed The compressed BigDecimal number.
+ * @param length The length of the original uncompressed string.
+ * @param probabilityTable The probability table used during compression.
+ * @return The original, uncompressed string.
+ */
+ public static String decompress(BigDecimal compressed, int length, Map probabilityTable) {
+ StringBuilder decompressed = new StringBuilder();
+
+ // Create a sorted list of symbols for deterministic decompression, matching the
+ // order used in calculateProbabilities
+ List> sortedSymbols = new ArrayList<>(probabilityTable.entrySet());
+ sortedSymbols.sort(Map.Entry.comparingByKey());
+
+ BigDecimal low = BigDecimal.ZERO;
+ BigDecimal high = BigDecimal.ONE;
+
+ for (int i = 0; i < length; i++) {
+ BigDecimal range = high.subtract(low);
+
+ // Find which symbol the compressed value falls into
+ for (Map.Entry entry : sortedSymbols) {
+ Symbol sym = entry.getValue();
+
+ // Calculate the actual range for this symbol in the current interval
+ BigDecimal symLow = low.add(range.multiply(sym.low()));
+ BigDecimal symHigh = low.add(range.multiply(sym.high()));
+
+ // Check if the compressed value falls within this symbol's range
+ if (compressed.compareTo(symLow) >= 0 && compressed.compareTo(symHigh) < 0) {
+ decompressed.append(entry.getKey());
+
+ // Update the interval for the next iteration
+ low = symLow;
+ high = symHigh;
+ break;
+ }
+ }
+ }
+
+ return decompressed.toString();
+ }
+
+ /**
+ * Calculates the frequency and probability range for each character in the
+ * input string in a deterministic order.
+ *
+ * @param text The input string.
+ * @return A map from each character to a Symbol object containing its
+ * probability range.
+ */
+ public static Map calculateProbabilities(String text) {
+ Map frequencies = new HashMap<>();
+ for (char c : text.toCharArray()) {
+ frequencies.put(c, frequencies.getOrDefault(c, 0) + 1);
+ }
+
+ // Sort the characters to ensure a deterministic order for the probability table
+ List sortedKeys = new ArrayList<>(frequencies.keySet());
+ Collections.sort(sortedKeys);
+
+ Map probabilityTable = new HashMap<>();
+ BigDecimal currentLow = BigDecimal.ZERO;
+ int total = text.length();
+
+ for (char symbol : sortedKeys) {
+ BigDecimal probability = BigDecimal.valueOf(frequencies.get(symbol)).divide(BigDecimal.valueOf(total), MathContext.DECIMAL128);
+ BigDecimal high = currentLow.add(probability);
+ probabilityTable.put(symbol, new Symbol(currentLow, high));
+ currentLow = high;
+ }
+
+ return probabilityTable;
+ }
+
+ /**
+ * Helper class to store the probability range [low, high) for a symbol.
+ */
+ public record Symbol(BigDecimal low, BigDecimal high) {
+ }
+}
diff --git a/src/main/java/com/thealgorithms/compression/BurrowsWheelerTransform.java b/src/main/java/com/thealgorithms/compression/BurrowsWheelerTransform.java
new file mode 100644
index 000000000000..a148517e5b55
--- /dev/null
+++ b/src/main/java/com/thealgorithms/compression/BurrowsWheelerTransform.java
@@ -0,0 +1,220 @@
+package com.thealgorithms.compression;
+
+import java.util.Arrays;
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * Implementation of the Burrows-Wheeler Transform (BWT) and its inverse.
+ *
+ * BWT is a reversible data transformation algorithm that rearranges a string into runs of
+ * similar characters. While not a compression algorithm itself, it significantly improves
+ * the compressibility of data for subsequent algorithms like Move-to-Front encoding and
+ * Run-Length Encoding.
+ *
+ *
+ * The transform works by:
+ *
+ * - Generating all rotations of the input string
+ * - Sorting these rotations lexicographically
+ * - Taking the last column of the sorted matrix as output
+ * - Recording the index of the original string in the sorted matrix
+ *
+ *
+ *
+ * Important: The input string should end with a unique end-of-string marker
+ * (typically '$') that:
+ *
+ * - Does not appear anywhere else in the text
+ * - Is lexicographically smaller than all other characters
+ * - Ensures unique rotations and enables correct inverse transformation
+ *
+ * Without this marker, the inverse transform may not correctly reconstruct the original string.
+ *
+ *
+ * Time Complexity:
+ *
+ * - Forward transform: O(n² log n) where n is the string length
+ * - Inverse transform: O(n) using the LF-mapping technique
+ *
+ *
+ *
+ * Example:
+ *
+ * Input: "banana$"
+ * Output: BWTResult("annb$aa", 4)
+ * - "annb$aa" is the transformed string (groups similar characters)
+ * - 4 is the index of the original string in the sorted rotations
+ *
+ *
+ * @see Burrows–Wheeler transform (Wikipedia)
+ */
+public final class BurrowsWheelerTransform {
+
+ private BurrowsWheelerTransform() {
+ }
+
+ /**
+ * A container for the result of the forward BWT.
+ *
+ * Contains the transformed string and the index of the original string
+ * in the sorted rotations matrix, both of which are required for the
+ * inverse transformation.
+ *
+ */
+ public static class BWTResult {
+ /** The transformed string (last column of the sorted rotation matrix) */
+ public final String transformed;
+
+ /** The index of the original string in the sorted rotations matrix */
+ public final int originalIndex;
+
+ /**
+ * Constructs a BWTResult with the transformed string and original index.
+ *
+ * @param transformed the transformed string (L-column)
+ * @param originalIndex the index of the original string in sorted rotations
+ */
+ public BWTResult(String transformed, int originalIndex) {
+ this.transformed = transformed;
+ this.originalIndex = originalIndex;
+ }
+
+ @Override
+ public boolean equals(Object obj) {
+ if (this == obj) {
+ return true;
+ }
+ if (obj == null || getClass() != obj.getClass()) {
+ return false;
+ }
+ BWTResult bwtResult = (BWTResult) obj;
+ return originalIndex == bwtResult.originalIndex && transformed.equals(bwtResult.transformed);
+ }
+
+ @Override
+ public int hashCode() {
+ return 31 * transformed.hashCode() + originalIndex;
+ }
+
+ @Override
+ public String toString() {
+ return "BWTResult[transformed=" + transformed + ", originalIndex=" + originalIndex + "]";
+ }
+ }
+
+ /**
+ * Performs the forward Burrows-Wheeler Transform on the input string.
+ *
+ * The algorithm generates all cyclic rotations of the input, sorts them
+ * lexicographically, and returns the last column of this sorted matrix
+ * along with the position of the original string.
+ *
+ *
+ * Note: It is strongly recommended that the input string ends with
+ * a unique end-of-string marker (e.g., '$') that is lexicographically smaller
+ * than any other character in the string. This ensures correct inversion.
+ *
+ * @param text the input string to transform; must not be {@code null}
+ * @return a {@link BWTResult} object containing the transformed string (L-column)
+ * and the index of the original string in the sorted rotations matrix;
+ * returns {@code BWTResult("", -1)} for empty input
+ * @throws NullPointerException if {@code text} is {@code null}
+ */
+ public static BWTResult transform(String text) {
+ if (text == null || text.isEmpty()) {
+ return new BWTResult("", -1);
+ }
+
+ int n = text.length();
+
+ // Generate all rotations of the input string
+ String[] rotations = new String[n];
+ for (int i = 0; i < n; i++) {
+ rotations[i] = text.substring(i) + text.substring(0, i);
+ }
+
+ // Sort rotations lexicographically
+ Arrays.sort(rotations);
+ int originalIndex = Arrays.binarySearch(rotations, text);
+ StringBuilder lastColumn = new StringBuilder(n);
+ for (int i = 0; i < n; i++) {
+ lastColumn.append(rotations[i].charAt(n - 1));
+ }
+
+ return new BWTResult(lastColumn.toString(), originalIndex);
+ }
+
+ /**
+ * Performs the inverse Burrows-Wheeler Transform using the LF-mapping technique.
+ *
+ * The LF-mapping (Last-First mapping) is an efficient method to reconstruct
+ * the original string from the BWT output without explicitly reconstructing
+ * the entire sorted rotations matrix.
+ *
+ *
+ * The algorithm works by:
+ *
+ * - Creating the first column by sorting the BWT string
+ * - Building a mapping from first column indices to last column indices
+ * - Following this mapping starting from the original index to reconstruct the string
+ *
+ *
+ *
+ * @param bwtString the transformed string (L-column) from the forward transform; must not be {@code null}
+ * @param originalIndex the index of the original string row from the forward transform;
+ * use -1 for empty strings
+ * @return the original, untransformed string; returns empty string if input is empty or {@code originalIndex} is -1
+ * @throws NullPointerException if {@code bwtString} is {@code null}
+ * @throws IllegalArgumentException if {@code originalIndex} is out of valid range (except -1)
+ */
+ public static String inverseTransform(String bwtString, int originalIndex) {
+ if (bwtString == null || bwtString.isEmpty() || originalIndex == -1) {
+ return "";
+ }
+
+ int n = bwtString.length();
+ if (originalIndex < 0 || originalIndex >= n) {
+ throw new IllegalArgumentException("Original index must be between 0 and " + (n - 1) + ", got: " + originalIndex);
+ }
+
+ char[] lastColumn = bwtString.toCharArray();
+ char[] firstColumn = bwtString.toCharArray();
+ Arrays.sort(firstColumn);
+
+ // Create the "next" array for LF-mapping.
+ // next[i] stores the row index in the last column that corresponds to firstColumn[i]
+ int[] next = new int[n];
+
+ // Track the count of each character seen so far in the last column
+ Map countMap = new HashMap<>();
+
+ // Store the first occurrence index of each character in the first column
+ Map firstOccurrence = new HashMap<>();
+
+ for (int i = 0; i < n; i++) {
+ if (!firstOccurrence.containsKey(firstColumn[i])) {
+ firstOccurrence.put(firstColumn[i], i);
+ }
+ }
+
+ // Build the LF-mapping
+ for (int i = 0; i < n; i++) {
+ char c = lastColumn[i];
+ int count = countMap.getOrDefault(c, 0);
+ int firstIndex = firstOccurrence.get(c);
+ next[firstIndex + count] = i;
+ countMap.put(c, count + 1);
+ }
+
+ // Reconstruct the original string by following the LF-mapping
+ StringBuilder originalString = new StringBuilder(n);
+ int currentRow = originalIndex;
+ for (int i = 0; i < n; i++) {
+ originalString.append(firstColumn[currentRow]);
+ currentRow = next[currentRow];
+ }
+
+ return originalString.toString();
+ }
+}
diff --git a/src/main/java/com/thealgorithms/compression/LZ77.java b/src/main/java/com/thealgorithms/compression/LZ77.java
new file mode 100644
index 000000000000..d02307aa57b5
--- /dev/null
+++ b/src/main/java/com/thealgorithms/compression/LZ77.java
@@ -0,0 +1,168 @@
+package com.thealgorithms.compression;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * An implementation of the Lempel-Ziv 77 (LZ77) compression algorithm.
+ *
+ * LZ77 is a lossless data compression algorithm that works by finding repeated
+ * occurrences of data in a sliding window. It replaces subsequent occurrences
+ * with references (offset, length) to the first occurrence within the window.
+ *
+ *
+ * This implementation uses a simple sliding window and lookahead buffer approach.
+ * Output format is a sequence of tuples (offset, length, next_character).
+ *
+ *
+ * Time Complexity: O(n*W) in this naive implementation, where n is the input length
+ * and W is the window size, due to the search for the longest match. More advanced
+ * data structures (like suffix trees) can improve this.
+ *
+ *
+ * References:
+ *
+ *
+ */
+public final class LZ77 {
+
+ private static final int DEFAULT_WINDOW_SIZE = 4096;
+ private static final int DEFAULT_LOOKAHEAD_BUFFER_SIZE = 16;
+ private static final char END_OF_STREAM = '\u0000';
+ private LZ77() {
+ }
+
+ /**
+ * Represents a token in the LZ77 compressed output.
+ * Stores the offset back into the window, the length of the match,
+ * and the next character after the match (or END_OF_STREAM if at end).
+ */
+ public record Token(int offset, int length, char nextChar) {
+ }
+
+ /**
+ * Compresses the input text using the LZ77 algorithm.
+ *
+ * @param text The input string to compress. Must not be null.
+ * @param windowSize The size of the sliding window (search buffer). Must be positive.
+ * @param lookaheadBufferSize The size of the lookahead buffer. Must be positive.
+ * @return A list of {@link Token} objects representing the compressed data.
+ * @throws IllegalArgumentException if windowSize or lookaheadBufferSize are not positive.
+ */
+ public static List compress(String text, int windowSize, int lookaheadBufferSize) {
+ if (text == null) {
+ return new ArrayList<>();
+ }
+ if (windowSize <= 0 || lookaheadBufferSize <= 0) {
+ throw new IllegalArgumentException("Window size and lookahead buffer size must be positive.");
+ }
+
+ List compressedOutput = new ArrayList<>();
+ int currentPosition = 0;
+
+ while (currentPosition < text.length()) {
+ int bestMatchDistance = 0;
+ int bestMatchLength = 0;
+
+ // Define the start of the search window
+ int searchBufferStart = Math.max(0, currentPosition - windowSize);
+ // Define the end of the lookahead buffer (don't go past text length)
+ int lookaheadEnd = Math.min(currentPosition + lookaheadBufferSize, text.length());
+
+ // Search for the longest match in the window
+ for (int i = searchBufferStart; i < currentPosition; i++) {
+ int currentMatchLength = 0;
+
+ // Check how far the match extends into the lookahead buffer
+ // This allows for overlapping matches (e.g., "aaa" can match with offset 1)
+ while (currentPosition + currentMatchLength < lookaheadEnd) {
+ int sourceIndex = i + currentMatchLength;
+
+ // Handle overlapping matches (run-length encoding within LZ77)
+ // When we've matched beyond our starting position, wrap around using modulo
+ if (sourceIndex >= currentPosition) {
+ int offset = currentPosition - i;
+ sourceIndex = i + (currentMatchLength % offset);
+ }
+
+ if (text.charAt(sourceIndex) == text.charAt(currentPosition + currentMatchLength)) {
+ currentMatchLength++;
+ } else {
+ break;
+ }
+ }
+
+ // If this match is longer than the best found so far
+ if (currentMatchLength > bestMatchLength) {
+ bestMatchLength = currentMatchLength;
+ bestMatchDistance = currentPosition - i; // Calculate offset from current position
+ }
+ }
+
+ char nextChar;
+ if (currentPosition + bestMatchLength < text.length()) {
+ nextChar = text.charAt(currentPosition + bestMatchLength);
+ } else {
+ nextChar = END_OF_STREAM;
+ }
+
+ // Add the token to the output
+ compressedOutput.add(new Token(bestMatchDistance, bestMatchLength, nextChar));
+
+ // Move the current position forward
+ // If we're at the end and had a match, just move by the match length
+ if (nextChar == END_OF_STREAM) {
+ currentPosition += bestMatchLength;
+ } else {
+ currentPosition += bestMatchLength + 1;
+ }
+ }
+
+ return compressedOutput;
+ }
+
+ /**
+ * Compresses the input text using the LZ77 algorithm with default buffer sizes.
+ *
+ * @param text The input string to compress. Must not be null.
+ * @return A list of {@link Token} objects representing the compressed data.
+ */
+ public static List compress(String text) {
+ return compress(text, DEFAULT_WINDOW_SIZE, DEFAULT_LOOKAHEAD_BUFFER_SIZE);
+ }
+
+ /**
+ * Decompresses a list of LZ77 tokens back into the original string.
+ *
+ * @param compressedData The list of {@link Token} objects. Must not be null.
+ * @return The original, uncompressed string.
+ */
+ public static String decompress(List compressedData) {
+ if (compressedData == null) {
+ return "";
+ }
+
+ StringBuilder decompressedText = new StringBuilder();
+
+ for (Token token : compressedData) {
+ // Copy matched characters from the sliding window
+ if (token.length > 0) {
+ int startIndex = decompressedText.length() - token.offset;
+
+ // Handle overlapping matches (e.g., when length > offset)
+ for (int i = 0; i < token.length; i++) {
+ decompressedText.append(decompressedText.charAt(startIndex + i));
+ }
+ }
+
+ // Append the next character (if not END_OF_STREAM)
+ if (token.nextChar != END_OF_STREAM) {
+ decompressedText.append(token.nextChar);
+ }
+ }
+
+ return decompressedText.toString();
+ }
+}
diff --git a/src/main/java/com/thealgorithms/compression/LZ78.java b/src/main/java/com/thealgorithms/compression/LZ78.java
new file mode 100644
index 000000000000..904c379cc2a2
--- /dev/null
+++ b/src/main/java/com/thealgorithms/compression/LZ78.java
@@ -0,0 +1,136 @@
+package com.thealgorithms.compression;
+
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * An implementation of the Lempel-Ziv 78 (LZ78) compression algorithm.
+ *
+ * LZ78 is a dictionary-based lossless data compression algorithm. It processes
+ * input data sequentially, building a dictionary of phrases encountered so far.
+ * It outputs pairs (dictionary_index, next_character), representing
+ * the longest match found in the dictionary plus the character that follows it.
+ *
+ *
+ * This implementation builds the dictionary dynamically during compression.
+ * The dictionary index 0 represents the empty string (no prefix).
+ *
+ *
+ * Time Complexity: O(n) on average for compression and decompression, assuming
+ * efficient dictionary lookups (using a HashMap), where n is the
+ * length of the input string.
+ *
+ *
+ * References:
+ *
+ *
+ */
+public final class LZ78 {
+
+ /**
+ * Special character used to mark end of stream when needed.
+ */
+ private static final char END_OF_STREAM = '\u0000';
+
+ /**
+ * Private constructor to prevent instantiation of this utility class.
+ */
+ private LZ78() {
+ }
+
+ /**
+ * Represents a token in the LZ78 compressed output.
+ * Stores the index of the matching prefix in the dictionary and the next character.
+ * Index 0 represents the empty string (no prefix).
+ */
+ public record Token(int index, char nextChar) {
+ }
+
+ /**
+ * A node in the dictionary trie structure.
+ * Each node represents a phrase and can have child nodes for extended phrases.
+ */
+ private static final class TrieNode {
+ Map children = new HashMap<>();
+ int index = -1; // -1 means not assigned yet
+ }
+
+ /**
+ * Compresses the input text using the LZ78 algorithm.
+ *
+ * @param text The input string to compress. Must not be null.
+ * @return A list of {@link Token} objects representing the compressed data.
+ */
+ public static List compress(String text) {
+ if (text == null || text.isEmpty()) {
+ return new ArrayList<>();
+ }
+
+ List compressedOutput = new ArrayList<>();
+ TrieNode root = new TrieNode();
+ int nextDictionaryIndex = 1;
+
+ TrieNode currentNode = root;
+ int lastMatchedIndex = 0;
+
+ for (int i = 0; i < text.length(); i++) {
+ char currentChar = text.charAt(i);
+
+ if (currentNode.children.containsKey(currentChar)) {
+ currentNode = currentNode.children.get(currentChar);
+ lastMatchedIndex = currentNode.index;
+ } else {
+ // Output: (index of longest matching prefix, current character)
+ compressedOutput.add(new Token(lastMatchedIndex, currentChar));
+
+ TrieNode newNode = new TrieNode();
+ newNode.index = nextDictionaryIndex++;
+ currentNode.children.put(currentChar, newNode);
+
+ currentNode = root;
+ lastMatchedIndex = 0;
+ }
+ }
+
+ // Handle remaining phrase at end of input
+ if (currentNode != root) {
+ compressedOutput.add(new Token(lastMatchedIndex, END_OF_STREAM));
+ }
+
+ return compressedOutput;
+ }
+
+ /**
+ * Decompresses a list of LZ78 tokens back into the original string.
+ *
+ * @param compressedData The list of {@link Token} objects. Must not be null.
+ * @return The original, uncompressed string.
+ */
+ public static String decompress(List compressedData) {
+ if (compressedData == null || compressedData.isEmpty()) {
+ return "";
+ }
+
+ StringBuilder decompressedText = new StringBuilder();
+ Map dictionary = new HashMap<>();
+ int nextDictionaryIndex = 1;
+
+ for (Token token : compressedData) {
+ String prefix = (token.index == 0) ? "" : dictionary.get(token.index);
+
+ if (token.nextChar == END_OF_STREAM) {
+ decompressedText.append(prefix);
+ } else {
+ String currentPhrase = prefix + token.nextChar;
+ decompressedText.append(currentPhrase);
+ dictionary.put(nextDictionaryIndex++, currentPhrase);
+ }
+ }
+
+ return decompressedText.toString();
+ }
+}
diff --git a/src/main/java/com/thealgorithms/compression/LZW.java b/src/main/java/com/thealgorithms/compression/LZW.java
new file mode 100644
index 000000000000..c8383815ad4f
--- /dev/null
+++ b/src/main/java/com/thealgorithms/compression/LZW.java
@@ -0,0 +1,136 @@
+package com.thealgorithms.compression;
+
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * An implementation of the Lempel-Ziv-Welch (LZW) algorithm.
+ *
+ *
+ * LZW is a universal lossless data compression algorithm created by Abraham
+ * Lempel, Jacob Ziv, and Terry Welch. It works by building a dictionary of
+ * strings encountered during compression and replacing occurrences of those
+ * strings with a shorter code.
+ *
+ *
+ *
+ * This implementation handles standard ASCII characters and provides methods for
+ * both compression and decompression.
+ *
+ * - Compressing "TOBEORNOTTOBEORTOBEORNOT" results in a list of integer
+ * codes.
+ * - Decompressing that list of codes results back in the original
+ * string.
+ *
+ *
+ *
+ *
+ * Time Complexity: O(n) for both compression and decompression, where n is the
+ * length of the input string.
+ *
+ *
+ *
+ * References:
+ *
+ *
+ */
+public final class LZW {
+
+ /**
+ * Private constructor to prevent instantiation of this utility class.
+ */
+ private LZW() {
+ }
+
+ /**
+ * Compresses a string using the LZW algorithm.
+ *
+ * @param uncompressed The string to be compressed. Can be null.
+ * @return A list of integers representing the compressed data. Returns an empty
+ * list if the input is null or empty.
+ */
+ public static List compress(String uncompressed) {
+ if (uncompressed == null || uncompressed.isEmpty()) {
+ return new ArrayList<>();
+ }
+
+ // Initialize dictionary with single characters (ASCII 0-255)
+ int dictSize = 256;
+ Map dictionary = new HashMap<>();
+ for (int i = 0; i < dictSize; i++) {
+ dictionary.put("" + (char) i, i);
+ }
+
+ String w = "";
+ List result = new ArrayList<>();
+ for (char c : uncompressed.toCharArray()) {
+ String wc = w + c;
+ if (dictionary.containsKey(wc)) {
+ // If the new string is in the dictionary, extend the current string
+ w = wc;
+ } else {
+ // Otherwise, output the code for the current string
+ result.add(dictionary.get(w));
+ // Add the new string to the dictionary
+ dictionary.put(wc, dictSize++);
+ // Start a new current string
+ w = "" + c;
+ }
+ }
+
+ // Output the code for the last remaining string
+ result.add(dictionary.get(w));
+ return result;
+ }
+
+ /**
+ * Decompresses a list of integers back into a string using the LZW algorithm.
+ *
+ * @param compressed A list of integers representing the compressed data. Can be
+ * null.
+ * @return The original, uncompressed string. Returns an empty string if the
+ * input is null or empty.
+ */
+ public static String decompress(List compressed) {
+ if (compressed == null || compressed.isEmpty()) {
+ return "";
+ }
+
+ // Initialize dictionary with single characters (ASCII 0-255)
+ int dictSize = 256;
+ Map dictionary = new HashMap<>();
+ for (int i = 0; i < dictSize; i++) {
+ dictionary.put(i, "" + (char) i);
+ }
+
+ // Decompress the first code
+ String w = "" + (char) (int) compressed.removeFirst();
+ StringBuilder result = new StringBuilder(w);
+
+ for (int k : compressed) {
+ String entry;
+ if (dictionary.containsKey(k)) {
+ // The code is in the dictionary
+ entry = dictionary.get(k);
+ } else if (k == dictSize) {
+ // Special case for sequences like "ababab"
+ entry = w + w.charAt(0);
+ } else {
+ throw new IllegalArgumentException("Bad compressed k: " + k);
+ }
+
+ result.append(entry);
+
+ // Add new sequence to the dictionary
+ dictionary.put(dictSize++, w + entry.charAt(0));
+
+ w = entry;
+ }
+ return result.toString();
+ }
+}
diff --git a/src/main/java/com/thealgorithms/compression/MoveToFront.java b/src/main/java/com/thealgorithms/compression/MoveToFront.java
new file mode 100644
index 000000000000..fa8976df8262
--- /dev/null
+++ b/src/main/java/com/thealgorithms/compression/MoveToFront.java
@@ -0,0 +1,164 @@
+package com.thealgorithms.compression;
+
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.LinkedList;
+import java.util.List;
+import java.util.stream.Collectors;
+
+/**
+ * Implementation of the Move-to-Front (MTF) transform and its inverse.
+ *
+ * MTF is a data transformation algorithm that encodes each symbol in the input
+ * as its current position in a dynamically-maintained list, then moves that symbol
+ * to the front of the list. This transformation is particularly effective when used
+ * after the Burrows-Wheeler Transform (BWT), as BWT groups similar characters together.
+ *
+ *
+ * The transform converts runs of repeated characters into sequences of small integers
+ * (often zeros), which are highly compressible by subsequent entropy encoding algorithms
+ * like Run-Length Encoding (RLE) or Huffman coding. This technique is used in the
+ * bzip2 compression algorithm.
+ *
+ *
+ * How it works:
+ *
+ * - Maintain a list of symbols (the alphabet), initially in a fixed order
+ * - For each input symbol:
+ *
+ * - Output its current index in the list
+ * - Move that symbol to the front of the list
+ *
+ *
+ *
+ * This means frequently occurring symbols quickly move to the front and are encoded
+ * with small indices (often 0), while rare symbols remain near the back.
+ *
+ *
+ * Time Complexity:
+ *
+ * - Forward transform: O(n × m) where n is input length and m is alphabet size
+ * - Inverse transform: O(n × m)
+ *
+ * Note: Using {@link LinkedList} for O(1) insertions and O(m) search operations.
+ *
+ *
+ * Example:
+ *
+ * Input: "annb$aa"
+ * Alphabet: "$abn" (initial order)
+ * Output: [1, 3, 0, 3, 3, 3, 0]
+ *
+ * Step-by-step:
+ * - 'a': index 1 in [$,a,b,n] → output 1, list becomes [a,$,b,n]
+ * - 'n': index 3 in [a,$,b,n] → output 3, list becomes [n,a,$,b]
+ * - 'n': index 0 in [n,a,$,b] → output 0, list stays [n,a,$,b]
+ * - 'b': index 3 in [n,a,$,b] → output 3, list becomes [b,n,a,$]
+ * - etc.
+ *
+ * Notice how repeated 'n' characters produce zeros after the first occurrence!
+ *
+ *
+ * @see Move-to-front transform (Wikipedia)
+ */
+public final class MoveToFront {
+
+ private MoveToFront() {
+ }
+
+ /**
+ * Performs the forward Move-to-Front transform.
+ *
+ * Converts the input string into a list of integers, where each integer represents
+ * the position of the corresponding character in a dynamically-maintained alphabet list.
+ *
+ *
+ * Note: All characters in the input text must exist in the provided alphabet,
+ * otherwise an {@link IllegalArgumentException} is thrown. The alphabet should contain
+ * all unique characters that may appear in the input.
+ *
+ * @param text the input string to transform; if empty, returns an empty list
+ * @param initialAlphabet a string containing the initial ordered set of symbols
+ * (e.g., "$abn" or the full ASCII set); must not be empty
+ * when {@code text} is non-empty
+ * @return a list of integers representing the transformed data, where each integer
+ * is the index of the corresponding input character in the current alphabet state
+ * @throws IllegalArgumentException if {@code text} is non-empty and {@code initialAlphabet}
+ * is {@code null} or empty
+ * @throws IllegalArgumentException if any character in {@code text} is not found in
+ * {@code initialAlphabet}
+ */
+ public static List transform(String text, String initialAlphabet) {
+ if (text == null || text.isEmpty()) {
+ return new ArrayList<>();
+ }
+ if (initialAlphabet == null || initialAlphabet.isEmpty()) {
+ throw new IllegalArgumentException("Alphabet cannot be null or empty when text is not empty.");
+ }
+
+ List output = new ArrayList<>(text.length());
+
+ // Use LinkedList for O(1) add-to-front and O(n) remove operations
+ // This is more efficient than ArrayList for the move-to-front pattern
+ List alphabet = initialAlphabet.chars().mapToObj(c -> (char) c).collect(Collectors.toCollection(LinkedList::new));
+
+ for (char c : text.toCharArray()) {
+ int index = alphabet.indexOf(c);
+ if (index == -1) {
+ throw new IllegalArgumentException("Symbol '" + c + "' not found in the initial alphabet.");
+ }
+
+ output.add(index);
+
+ // Move the character to the front
+ Character symbol = alphabet.remove(index);
+ alphabet.addFirst(symbol);
+ }
+ return output;
+ }
+
+ /**
+ * Performs the inverse Move-to-Front transform.
+ *
+ * Reconstructs the original string from the list of indices produced by the
+ * forward transform. This requires the exact same initial alphabet that was
+ * used in the forward transform.
+ *
+ *
+ * Important: The {@code initialAlphabet} parameter must be identical
+ * to the one used in the forward transform, including character order, or the
+ * output will be incorrect.
+ *
+ * @param indices The list of integers from the forward transform.
+ * @param initialAlphabet the exact same initial alphabet string used for the forward transform;
+ * if {@code null} or empty, returns an empty string
+ * @return the original, untransformed string
+ * @throws IllegalArgumentException if any index in {@code indices} is negative or
+ * exceeds the current alphabet size
+ */
+ public static String inverseTransform(Collection indices, String initialAlphabet) {
+ if (indices == null || indices.isEmpty() || initialAlphabet == null || initialAlphabet.isEmpty()) {
+ return "";
+ }
+
+ StringBuilder output = new StringBuilder(indices.size());
+
+ // Use LinkedList for O(1) add-to-front and O(n) remove operations
+ List alphabet = initialAlphabet.chars().mapToObj(c -> (char) c).collect(Collectors.toCollection(LinkedList::new));
+
+ for (int index : indices) {
+ if (index < 0 || index >= alphabet.size()) {
+ throw new IllegalArgumentException("Index " + index + " is out of bounds for the current alphabet of size " + alphabet.size() + ".");
+ }
+
+ // Get the symbol at the index
+ char symbol = alphabet.get(index);
+ output.append(symbol);
+
+ // Move the symbol to the front (mirroring the forward transform)
+ alphabet.remove(index);
+ alphabet.addFirst(symbol);
+ }
+ return output.toString();
+ }
+}
diff --git a/src/main/java/com/thealgorithms/compression/RunLengthEncoding.java b/src/main/java/com/thealgorithms/compression/RunLengthEncoding.java
new file mode 100644
index 000000000000..8d065f4648df
--- /dev/null
+++ b/src/main/java/com/thealgorithms/compression/RunLengthEncoding.java
@@ -0,0 +1,87 @@
+package com.thealgorithms.compression;
+
+/**
+ * An implementation of the Run-Length Encoding (RLE) algorithm.
+ *
+ * Run-Length Encoding is a simple form of lossless data compression in which
+ * runs of data (sequences in which the same data value occurs in many
+ * consecutive data elements) are stored as a single data value and count,
+ * rather than as the original run.
+ *
+ *
This implementation provides methods for both compressing and decompressing
+ * a string. For example:
+ *
+ * - Compressing "AAAABBBCCDAA" results in "4A3B2C1D2A".
+ * - Decompressing "4A3B2C1D2A" results in "AAAABBBCCDAA".
+ *
+ *
+ * Time Complexity: O(n) for both compression and decompression, where n is the
+ * length of the input string.
+ *
+ *
References:
+ *
+ */
+public final class RunLengthEncoding {
+
+ /**
+ * Private constructor to prevent instantiation of this utility class.
+ */
+ private RunLengthEncoding() {
+ }
+
+ /**
+ * Compresses a string using the Run-Length Encoding algorithm.
+ *
+ * @param text The string to be compressed. Must not be null.
+ * @return The compressed string. Returns an empty string if the input is empty.
+ */
+ public static String compress(String text) {
+ if (text == null || text.isEmpty()) {
+ return "";
+ }
+
+ StringBuilder compressed = new StringBuilder();
+ int count = 1;
+
+ for (int i = 0; i < text.length(); i++) {
+ // Check if it's the last character or if the next character is different
+ if (i == text.length() - 1 || text.charAt(i) != text.charAt(i + 1)) {
+ compressed.append(count);
+ compressed.append(text.charAt(i));
+ count = 1; // Reset count for the new character
+ } else {
+ count++;
+ }
+ }
+ return compressed.toString();
+ }
+
+ /**
+ * Decompresses a string that was compressed using the Run-Length Encoding algorithm.
+ *
+ * @param compressedText The compressed string. Must not be null.
+ * @return The original, uncompressed string.
+ */
+ public static String decompress(String compressedText) {
+ if (compressedText == null || compressedText.isEmpty()) {
+ return "";
+ }
+
+ StringBuilder decompressed = new StringBuilder();
+ int count = 0;
+
+ for (char ch : compressedText.toCharArray()) {
+ if (Character.isDigit(ch)) {
+ // Build the number for runs of 10 or more (e.g., "12A")
+ count = count * 10 + ch - '0';
+ } else {
+ // Append the character 'count' times
+ decompressed.append(String.valueOf(ch).repeat(Math.max(0, count)));
+ count = 0; // Reset count for the next sequence
+ }
+ }
+ return decompressed.toString();
+ }
+}
diff --git a/src/main/java/com/thealgorithms/compression/ShannonFano.java b/src/main/java/com/thealgorithms/compression/ShannonFano.java
new file mode 100644
index 000000000000..aa5d7ad91b2f
--- /dev/null
+++ b/src/main/java/com/thealgorithms/compression/ShannonFano.java
@@ -0,0 +1,159 @@
+package com.thealgorithms.compression;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.stream.Collectors;
+
+/**
+ * An implementation of the Shannon-Fano algorithm for generating prefix codes.
+ *
+ * Shannon-Fano coding is an entropy encoding technique for lossless data
+ * compression. It assigns variable-length codes to symbols based on their
+ * frequencies of occurrence. It is a precursor to Huffman coding and works by
+ * recursively partitioning a sorted list of symbols into two sub-lists with
+ * nearly equal total frequencies.
+ *
+ *
The algorithm works as follows:
+ *
+ * - Count the frequency of each symbol in the input data.
+ * - Sort the symbols in descending order of their frequencies.
+ * - Recursively divide the list of symbols into two parts with sums of
+ * frequencies as close as possible to each other.
+ * - Assign a '0' bit to the codes in the first part and a '1' bit to the codes
+ * in the second part.
+ * - Repeat the process for each part until a part contains only one symbol.
+ *
+ *
+ * Time Complexity: O(n^2) in this implementation due to the partitioning logic,
+ * or O(n log n) if a more optimized partitioning strategy is used.
+ * Sorting takes O(n log n), where n is the number of unique symbols.
+ *
+ *
References:
+ *
+ */
+public final class ShannonFano {
+
+ /**
+ * Private constructor to prevent instantiation of this utility class.
+ */
+ private ShannonFano() {
+ }
+
+ /**
+ * A private inner class to represent a symbol and its frequency.
+ * Implements Comparable to allow sorting based on frequency.
+ */
+ private static class Symbol implements Comparable {
+ final char character;
+ final int frequency;
+ String code = "";
+
+ Symbol(char character, int frequency) {
+ this.character = character;
+ this.frequency = frequency;
+ }
+
+ @Override
+ public int compareTo(Symbol other) {
+ return Integer.compare(other.frequency, this.frequency); // Sort descending
+ }
+ }
+
+ /**
+ * Generates Shannon-Fano codes for the symbols in a given text.
+ *
+ * @param text The input string for which to generate codes. Must not be null.
+ * @return A map where keys are characters and values are their corresponding Shannon-Fano codes.
+ */
+ public static Map generateCodes(String text) {
+ if (text == null || text.isEmpty()) {
+ return Collections.emptyMap();
+ }
+
+ Map frequencyMap = new HashMap<>();
+ for (char c : text.toCharArray()) {
+ frequencyMap.put(c, frequencyMap.getOrDefault(c, 0) + 1);
+ }
+
+ List symbols = new ArrayList<>();
+ for (Map.Entry entry : frequencyMap.entrySet()) {
+ symbols.add(new Symbol(entry.getKey(), entry.getValue()));
+ }
+
+ Collections.sort(symbols);
+
+ // Special case: only one unique symbol
+ if (symbols.size() == 1) {
+ symbols.getFirst().code = "0";
+ } else {
+ buildCodeTree(symbols, 0, symbols.size() - 1, "");
+ }
+
+ return symbols.stream().collect(Collectors.toMap(s -> s.character, s -> s.code));
+ }
+
+ /**
+ * Recursively builds the Shannon-Fano code tree by partitioning the list of symbols.
+ * Uses index-based approach to avoid sublist creation issues.
+ *
+ * @param symbols The sorted list of symbols to be processed.
+ * @param start The start index of the current partition.
+ * @param end The end index of the current partition (inclusive).
+ * @param prefix The current prefix code being built for the symbols in this partition.
+ */
+ private static void buildCodeTree(List symbols, int start, int end, String prefix) {
+ // The initial check in generateCodes ensures start <= end is always true here.
+ // The base case is when a partition has only one symbol.
+ if (start == end) {
+ symbols.get(start).code = prefix;
+ return;
+ }
+
+ // Find the optimal split point
+ int splitIndex = findSplitIndex(symbols, start, end);
+
+ // Recursively process left and right partitions with updated prefixes
+ buildCodeTree(symbols, start, splitIndex, prefix + "0");
+ buildCodeTree(symbols, splitIndex + 1, end, prefix + "1");
+ }
+
+ /**
+ * Finds the index that splits the range into two parts with the most balanced frequency sums.
+ * This method tries every possible split point and returns the index that minimizes the
+ * absolute difference between the two partition sums.
+ *
+ * @param symbols The sorted list of symbols.
+ * @param start The start index of the range.
+ * @param end The end index of the range (inclusive).
+ * @return The index of the last element in the first partition.
+ */
+ private static int findSplitIndex(List symbols, int start, int end) {
+ // Calculate total frequency for the entire range
+ long totalFrequency = 0;
+ for (int i = start; i <= end; i++) {
+ totalFrequency += symbols.get(i).frequency;
+ }
+
+ long leftSum = 0;
+ long minDifference = Long.MAX_VALUE;
+ int splitIndex = start;
+
+ // Try every possible split point and find the one with minimum difference
+ for (int i = start; i < end; i++) {
+ leftSum += symbols.get(i).frequency;
+ long rightSum = totalFrequency - leftSum;
+ long difference = Math.abs(leftSum - rightSum);
+
+ if (difference < minDifference) {
+ minDifference = difference;
+ splitIndex = i;
+ }
+ }
+ return splitIndex;
+ }
+}
diff --git a/src/main/java/com/thealgorithms/conversions/AffineConverter.java b/src/main/java/com/thealgorithms/conversions/AffineConverter.java
index a580b23f90f9..199a6dd517d5 100644
--- a/src/main/java/com/thealgorithms/conversions/AffineConverter.java
+++ b/src/main/java/com/thealgorithms/conversions/AffineConverter.java
@@ -1,23 +1,64 @@
package com.thealgorithms.conversions;
+/**
+ * A utility class to perform affine transformations of the form:
+ * y = slope * x + intercept.
+ *
+ * This class supports inversion and composition of affine transformations.
+ * It is immutable, meaning each instance represents a fixed transformation.
+ */
public final class AffineConverter {
private final double slope;
private final double intercept;
+
+ /**
+ * Constructs an AffineConverter with the given slope and intercept.
+ *
+ * @param inSlope The slope of the affine transformation.
+ * @param inIntercept The intercept (constant term) of the affine transformation.
+ * @throws IllegalArgumentException if either parameter is NaN.
+ */
public AffineConverter(final double inSlope, final double inIntercept) {
+ if (Double.isNaN(inSlope) || Double.isNaN(inIntercept)) {
+ throw new IllegalArgumentException("Slope and intercept must be valid numbers.");
+ }
slope = inSlope;
intercept = inIntercept;
}
+ /**
+ * Converts the given input value using the affine transformation:
+ * result = slope * inValue + intercept.
+ *
+ * @param inValue The input value to convert.
+ * @return The transformed value.
+ */
public double convert(final double inValue) {
return slope * inValue + intercept;
}
+ /**
+ * Returns a new AffineConverter representing the inverse of the current transformation.
+ * The inverse of y = slope * x + intercept is x = (y - intercept) / slope.
+ *
+ * @return A new AffineConverter representing the inverse transformation.
+ * @throws AssertionError if the slope is zero, as the inverse would be undefined.
+ */
public AffineConverter invert() {
- assert slope != 0.0;
+ assert slope != 0.0 : "Slope cannot be zero for inversion.";
return new AffineConverter(1.0 / slope, -intercept / slope);
}
+ /**
+ * Composes this affine transformation with another, returning a new AffineConverter.
+ * If this transformation is f(x) and the other is g(x), the result is f(g(x)).
+ *
+ * @param other Another AffineConverter to compose with.
+ * @return A new AffineConverter representing the composition of the two transformations.
+ */
public AffineConverter compose(final AffineConverter other) {
- return new AffineConverter(slope * other.slope, slope * other.intercept + intercept);
+ double newSlope = slope * other.slope;
+ double newIntercept = slope * other.intercept + intercept;
+ return new AffineConverter(newSlope, newIntercept);
}
}
diff --git a/src/main/java/com/thealgorithms/conversions/AnyBaseToAnyBase.java b/src/main/java/com/thealgorithms/conversions/AnyBaseToAnyBase.java
index 4bd9c74a1751..7a9448fd8fe7 100644
--- a/src/main/java/com/thealgorithms/conversions/AnyBaseToAnyBase.java
+++ b/src/main/java/com/thealgorithms/conversions/AnyBaseToAnyBase.java
@@ -136,7 +136,7 @@ public static String base2base(String n, int b1, int b2) {
int decimalValue = 0;
int charB2;
char charB1;
- String output = "";
+ StringBuilder output = new StringBuilder();
// Go through every character of n
for (int i = 0; i < n.length(); i++) {
// store the character in charB1
@@ -167,15 +167,15 @@ public static String base2base(String n, int b1, int b2) {
// If the remainder is a digit < 10, simply add it to
// the left side of the new number.
if (decimalValue % b2 < 10) {
- output = decimalValue % b2 + output;
+ output.insert(0, decimalValue % b2);
} // If the remainder is >= 10, add a character with the
// corresponding value to the new number. (A = 10, B = 11, C = 12, ...)
else {
- output = (char) ((decimalValue % b2) + 55) + output;
+ output.insert(0, (char) ((decimalValue % b2) + 55));
}
// Divide by the new base again
decimalValue /= b2;
}
- return output;
+ return output.toString();
}
}
diff --git a/src/main/java/com/thealgorithms/conversions/AnytoAny.java b/src/main/java/com/thealgorithms/conversions/AnytoAny.java
index 801e493032e0..e7bdbc2b79c4 100644
--- a/src/main/java/com/thealgorithms/conversions/AnytoAny.java
+++ b/src/main/java/com/thealgorithms/conversions/AnytoAny.java
@@ -1,35 +1,68 @@
package com.thealgorithms.conversions;
-import java.util.Scanner;
-
-// given a source number , source base, destination base, this code can give you the destination
-// number.
-// sn ,sb,db ---> ()dn . this is what we have to do .
-
+/**
+ * A utility class for converting numbers from any base to any other base.
+ *
+ * This class provides a method to convert a source number from a given base
+ * to a destination number in another base. Valid bases range from 2 to 10.
+ */
public final class AnytoAny {
private AnytoAny() {
}
- public static void main(String[] args) {
- Scanner scn = new Scanner(System.in);
- int sn = scn.nextInt();
- int sb = scn.nextInt();
- int db = scn.nextInt();
- int m = 1;
- int dec = 0;
- int dn = 0;
- while (sn != 0) {
- dec = dec + (sn % 10) * m;
- m *= sb;
- sn /= 10;
+ /**
+ * Converts a number from a source base to a destination base.
+ *
+ * @param sourceNumber The number in the source base (as an integer).
+ * @param sourceBase The base of the source number (between 2 and 10).
+ * @param destBase The base to which the number should be converted (between 2 and 10).
+ * @throws IllegalArgumentException if the bases are not between 2 and 10.
+ * @return The converted number in the destination base (as an integer).
+ */
+ public static int convertBase(int sourceNumber, int sourceBase, int destBase) {
+ if (sourceBase < 2 || sourceBase > 10 || destBase < 2 || destBase > 10) {
+ throw new IllegalArgumentException("Bases must be between 2 and 10.");
+ }
+
+ int decimalValue = toDecimal(sourceNumber, sourceBase);
+ return fromDecimal(decimalValue, destBase);
+ }
+
+ /**
+ * Converts a number from a given base to its decimal representation (base 10).
+ *
+ * @param number The number in the original base.
+ * @param base The base of the given number.
+ * @return The decimal representation of the number.
+ */
+ private static int toDecimal(int number, int base) {
+ int decimalValue = 0;
+ int multiplier = 1;
+
+ while (number != 0) {
+ decimalValue += (number % 10) * multiplier;
+ multiplier *= base;
+ number /= 10;
}
- m = 1;
- while (dec != 0) {
- dn = dn + (dec % db) * m;
- m *= 10;
- dec /= db;
+ return decimalValue;
+ }
+
+ /**
+ * Converts a decimal (base 10) number to a specified base.
+ *
+ * @param decimal The decimal number to convert.
+ * @param base The destination base for conversion.
+ * @return The number in the specified base.
+ */
+ private static int fromDecimal(int decimal, int base) {
+ int result = 0;
+ int multiplier = 1;
+
+ while (decimal != 0) {
+ result += (decimal % base) * multiplier;
+ multiplier *= 10;
+ decimal /= base;
}
- System.out.println(dn);
- scn.close();
+ return result;
}
}
diff --git a/src/main/java/com/thealgorithms/conversions/Base64.java b/src/main/java/com/thealgorithms/conversions/Base64.java
new file mode 100644
index 000000000000..5219c4ba7f4e
--- /dev/null
+++ b/src/main/java/com/thealgorithms/conversions/Base64.java
@@ -0,0 +1,196 @@
+package com.thealgorithms.conversions;
+
+import java.nio.charset.StandardCharsets;
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * Base64 is a group of binary-to-text encoding schemes that represent binary data
+ * in an ASCII string format by translating it into a radix-64 representation.
+ * Each base64 digit represents exactly 6 bits of data.
+ *
+ * Base64 encoding is commonly used when there is a need to encode binary data
+ * that needs to be stored and transferred over media that are designed to deal
+ * with textual data.
+ *
+ * Wikipedia Reference: https://en.wikipedia.org/wiki/Base64
+ * Author: Nithin U.
+ * Github: https://github.com/NithinU2802
+ */
+
+public final class Base64 {
+
+ // Base64 character set
+ private static final String BASE64_CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+ private static final char PADDING_CHAR = '=';
+
+ private Base64() {
+ }
+
+ /**
+ * Encodes the given byte array to a Base64 encoded string.
+ *
+ * @param input the byte array to encode
+ * @return the Base64 encoded string
+ * @throws IllegalArgumentException if input is null
+ */
+ public static String encode(byte[] input) {
+ if (input == null) {
+ throw new IllegalArgumentException("Input cannot be null");
+ }
+
+ if (input.length == 0) {
+ return "";
+ }
+
+ StringBuilder result = new StringBuilder();
+ int padding = 0;
+
+ // Process input in groups of 3 bytes
+ for (int i = 0; i < input.length; i += 3) {
+ // Get up to 3 bytes
+ int byte1 = input[i] & 0xFF;
+ int byte2 = (i + 1 < input.length) ? (input[i + 1] & 0xFF) : 0;
+ int byte3 = (i + 2 < input.length) ? (input[i + 2] & 0xFF) : 0;
+
+ // Calculate padding needed
+ if (i + 1 >= input.length) {
+ padding = 2;
+ } else if (i + 2 >= input.length) {
+ padding = 1;
+ }
+
+ // Combine 3 bytes into a 24-bit number
+ int combined = (byte1 << 16) | (byte2 << 8) | byte3;
+
+ // Extract four 6-bit groups
+ result.append(BASE64_CHARS.charAt((combined >> 18) & 0x3F));
+ result.append(BASE64_CHARS.charAt((combined >> 12) & 0x3F));
+ result.append(BASE64_CHARS.charAt((combined >> 6) & 0x3F));
+ result.append(BASE64_CHARS.charAt(combined & 0x3F));
+ }
+
+ // Replace padding characters
+ if (padding > 0) {
+ result.setLength(result.length() - padding);
+ for (int i = 0; i < padding; i++) {
+ result.append(PADDING_CHAR);
+ }
+ }
+
+ return result.toString();
+ }
+
+ /**
+ * Encodes the given string to a Base64 encoded string using UTF-8 encoding.
+ *
+ * @param input the string to encode
+ * @return the Base64 encoded string
+ * @throws IllegalArgumentException if input is null
+ */
+ public static String encode(String input) {
+ if (input == null) {
+ throw new IllegalArgumentException("Input cannot be null");
+ }
+
+ return encode(input.getBytes(StandardCharsets.UTF_8));
+ }
+
+ /**
+ * Decodes the given Base64 encoded string to a byte array.
+ *
+ * @param input the Base64 encoded string to decode
+ * @return the decoded byte array
+ * @throws IllegalArgumentException if input is null or contains invalid Base64 characters
+ */
+ public static byte[] decode(String input) {
+ if (input == null) {
+ throw new IllegalArgumentException("Input cannot be null");
+ }
+
+ if (input.isEmpty()) {
+ return new byte[0];
+ }
+
+ // Strict RFC 4648 compliance: length must be a multiple of 4
+ if (input.length() % 4 != 0) {
+ throw new IllegalArgumentException("Invalid Base64 input length; must be multiple of 4");
+ }
+
+ // Validate padding: '=' can only appear at the end (last 1 or 2 chars)
+ int firstPadding = input.indexOf('=');
+ if (firstPadding != -1 && firstPadding < input.length() - 2) {
+ throw new IllegalArgumentException("Padding '=' can only appear at the end (last 1 or 2 characters)");
+ }
+
+ List result = new ArrayList<>();
+
+ // Process input in groups of 4 characters
+ for (int i = 0; i < input.length(); i += 4) {
+ // Get up to 4 characters
+ int char1 = getBase64Value(input.charAt(i));
+ int char2 = getBase64Value(input.charAt(i + 1));
+ int char3 = input.charAt(i + 2) == '=' ? 0 : getBase64Value(input.charAt(i + 2));
+ int char4 = input.charAt(i + 3) == '=' ? 0 : getBase64Value(input.charAt(i + 3));
+
+ // Combine four 6-bit groups into a 24-bit number
+ int combined = (char1 << 18) | (char2 << 12) | (char3 << 6) | char4;
+
+ // Extract three 8-bit bytes
+ result.add((byte) ((combined >> 16) & 0xFF));
+ if (input.charAt(i + 2) != '=') {
+ result.add((byte) ((combined >> 8) & 0xFF));
+ }
+ if (input.charAt(i + 3) != '=') {
+ result.add((byte) (combined & 0xFF));
+ }
+ }
+
+ // Convert List to byte[]
+ byte[] resultArray = new byte[result.size()];
+ for (int i = 0; i < result.size(); i++) {
+ resultArray[i] = result.get(i);
+ }
+
+ return resultArray;
+ }
+
+ /**
+ * Decodes the given Base64 encoded string to a string using UTF-8 encoding.
+ *
+ * @param input the Base64 encoded string to decode
+ * @return the decoded string
+ * @throws IllegalArgumentException if input is null or contains invalid Base64 characters
+ */
+ public static String decodeToString(String input) {
+ if (input == null) {
+ throw new IllegalArgumentException("Input cannot be null");
+ }
+
+ byte[] decodedBytes = decode(input);
+ return new String(decodedBytes, StandardCharsets.UTF_8);
+ }
+
+ /**
+ * Gets the numeric value of a Base64 character.
+ *
+ * @param c the Base64 character
+ * @return the numeric value (0-63)
+ * @throws IllegalArgumentException if character is not a valid Base64 character
+ */
+ private static int getBase64Value(char c) {
+ if (c >= 'A' && c <= 'Z') {
+ return c - 'A';
+ } else if (c >= 'a' && c <= 'z') {
+ return c - 'a' + 26;
+ } else if (c >= '0' && c <= '9') {
+ return c - '0' + 52;
+ } else if (c == '+') {
+ return 62;
+ } else if (c == '/') {
+ return 63;
+ } else {
+ throw new IllegalArgumentException("Invalid Base64 character: " + c);
+ }
+ }
+}
diff --git a/src/main/java/com/thealgorithms/conversions/CoordinateConverter.java b/src/main/java/com/thealgorithms/conversions/CoordinateConverter.java
new file mode 100644
index 000000000000..2766a3a1cf89
--- /dev/null
+++ b/src/main/java/com/thealgorithms/conversions/CoordinateConverter.java
@@ -0,0 +1,57 @@
+package com.thealgorithms.conversions;
+
+/**
+ * A utility class to convert between Cartesian and Polar coordinate systems.
+ *
+ * This class provides methods to perform the following conversions:
+ *
+ * - Cartesian to Polar coordinates
+ * - Polar to Cartesian coordinates
+ *
+ *
+ * The class is final and cannot be instantiated.
+ */
+public final class CoordinateConverter {
+
+ private CoordinateConverter() {
+ // Prevent instantiation
+ }
+
+ /**
+ * Converts Cartesian coordinates to Polar coordinates.
+ *
+ * @param x the x-coordinate in the Cartesian system; must be a finite number
+ * @param y the y-coordinate in the Cartesian system; must be a finite number
+ * @return an array where the first element is the radius (r) and the second element is the angle (theta) in degrees
+ * @throws IllegalArgumentException if x or y is not a finite number
+ */
+ public static double[] cartesianToPolar(double x, double y) {
+ if (!Double.isFinite(x) || !Double.isFinite(y)) {
+ throw new IllegalArgumentException("x and y must be finite numbers.");
+ }
+ double r = Math.sqrt(x * x + y * y);
+ double theta = Math.toDegrees(Math.atan2(y, x));
+ return new double[] {r, theta};
+ }
+
+ /**
+ * Converts Polar coordinates to Cartesian coordinates.
+ *
+ * @param r the radius in the Polar system; must be non-negative
+ * @param thetaDegrees the angle (theta) in degrees in the Polar system; must be a finite number
+ * @return an array where the first element is the x-coordinate and the second element is the y-coordinate in the Cartesian system
+ * @throws IllegalArgumentException if r is negative or thetaDegrees is not a finite number
+ */
+ public static double[] polarToCartesian(double r, double thetaDegrees) {
+ if (r < 0) {
+ throw new IllegalArgumentException("Radius (r) must be non-negative.");
+ }
+ if (!Double.isFinite(thetaDegrees)) {
+ throw new IllegalArgumentException("Theta (angle) must be a finite number.");
+ }
+ double theta = Math.toRadians(thetaDegrees);
+ double x = r * Math.cos(theta);
+ double y = r * Math.sin(theta);
+ return new double[] {x, y};
+ }
+}
diff --git a/src/main/java/com/thealgorithms/conversions/EndianConverter.java b/src/main/java/com/thealgorithms/conversions/EndianConverter.java
new file mode 100644
index 000000000000..0d69098e8255
--- /dev/null
+++ b/src/main/java/com/thealgorithms/conversions/EndianConverter.java
@@ -0,0 +1,47 @@
+package com.thealgorithms.conversions;
+
+/**
+ * Utility class for converting integers between big-endian and little-endian formats.
+ *
+ * Endianness defines how byte sequences represent multi-byte data types:
+ *
+ * - Big-endian: The most significant byte (MSB) comes first.
+ * - Little-endian: The least significant byte (LSB) comes first.
+ *
+ *
+ * Example conversion:
+ *
+ * - Big-endian to little-endian: {@code 0x12345678} → {@code 0x78563412}
+ * - Little-endian to big-endian: {@code 0x78563412} → {@code 0x12345678}
+ *
+ *
+ * Note: Both conversions in this utility are equivalent since reversing the bytes is symmetric.
+ *
+ * This class only supports 32-bit integers.
+ *
+ * @author Hardvan
+ */
+public final class EndianConverter {
+ private EndianConverter() {
+ }
+
+ /**
+ * Converts a 32-bit integer from big-endian to little-endian.
+ *
+ * @param value the integer in big-endian format
+ * @return the integer in little-endian format
+ */
+ public static int bigToLittleEndian(int value) {
+ return Integer.reverseBytes(value);
+ }
+
+ /**
+ * Converts a 32-bit integer from little-endian to big-endian.
+ *
+ * @param value the integer in little-endian format
+ * @return the integer in big-endian format
+ */
+ public static int littleToBigEndian(int value) {
+ return Integer.reverseBytes(value);
+ }
+}
diff --git a/src/main/java/com/thealgorithms/conversions/HexaDecimalToBinary.java b/src/main/java/com/thealgorithms/conversions/HexaDecimalToBinary.java
index b6228488dc76..c0eb9a01ba17 100644
--- a/src/main/java/com/thealgorithms/conversions/HexaDecimalToBinary.java
+++ b/src/main/java/com/thealgorithms/conversions/HexaDecimalToBinary.java
@@ -1,43 +1,62 @@
package com.thealgorithms.conversions;
-// Hex [0-9],[A-F] -> Binary [0,1]
+/**
+ * Utility class for converting hexadecimal numbers to binary representation.
+ *
+ * A hexadecimal number consists of digits from {@code [0-9]} and {@code [A-F]} (case-insensitive),
+ * while binary representation uses only {@code [0, 1]}.
+ *
+ * This class provides methods to:
+ *
+ * - Convert a hexadecimal string to its binary string equivalent.
+ * - Ensure the binary output is padded to 8 bits (1 byte).
+ *
+ *
+ * Example:
+ *
+ * - {@code "A1"} → {@code "10100001"}
+ * - {@code "1"} → {@code "00000001"}
+ *
+ *
+ * This class assumes that the input hexadecimal string is valid.
+ */
public class HexaDecimalToBinary {
+
+ /**
+ * Converts a hexadecimal string to its binary string equivalent.
+ * The binary output is padded to a minimum of 8 bits (1 byte).
+ * Steps:
+ *
+ * - Convert the hexadecimal string to an integer.
+ * - Convert the integer to a binary string.
+ * - Pad the binary string to ensure it is at least 8 bits long.
+ * - Return the padded binary string.
+ *
+ *
+ * @param numHex the hexadecimal string (e.g., "A1", "7F")
+ * @throws NumberFormatException if the input string is not a valid hexadecimal number
+ * @return the binary string representation, padded to 8 bits (e.g., "10100001")
+ */
public String convert(String numHex) {
- // String a HexaDecimal:
int conHex = Integer.parseInt(numHex, 16);
- // Hex a Binary:
String binary = Integer.toBinaryString(conHex);
- // Output:
return completeDigits(binary);
}
+ /**
+ * Pads the binary string to ensure it is at least 8 bits long.
+ * If the binary string is shorter than 8 bits, it adds leading zeros.
+ *
+ * @param binNum the binary string to pad
+ * @return the padded binary string with a minimum length of 8
+ */
public String completeDigits(String binNum) {
- final int longBits = 8;
- for (int i = binNum.length(); i < longBits; i++) {
- binNum = "0" + binNum;
+ final int byteSize = 8;
+ StringBuilder binNumBuilder = new StringBuilder(binNum);
+ while (binNumBuilder.length() < byteSize) {
+ binNumBuilder.insert(0, "0");
}
+ binNum = binNumBuilder.toString();
return binNum;
}
-
- public static void main(String[] args) {
- // Testing Numbers:
- String[] hexNums = {
- "1",
- "A1",
- "ef",
- "BA",
- "AA",
- "BB",
- "19",
- "01",
- "02",
- "03",
- "04",
- };
- HexaDecimalToBinary objConvert = new HexaDecimalToBinary();
-
- for (String num : hexNums) {
- System.out.println(num + " = " + objConvert.convert(num));
- }
- }
}
diff --git a/src/main/java/com/thealgorithms/conversions/HexaDecimalToDecimal.java b/src/main/java/com/thealgorithms/conversions/HexaDecimalToDecimal.java
index 003781da9d5e..2cf6024d90a3 100644
--- a/src/main/java/com/thealgorithms/conversions/HexaDecimalToDecimal.java
+++ b/src/main/java/com/thealgorithms/conversions/HexaDecimalToDecimal.java
@@ -1,39 +1,45 @@
package com.thealgorithms.conversions;
-import java.util.Scanner;
-
+/**
+ * Utility class for converting a hexadecimal string to its decimal representation.
+ *
+ * A hexadecimal number uses the base-16 numeral system, with the following characters:
+ *
+ * - Digits: 0-9
+ * - Letters: A-F (case-insensitive)
+ *
+ * Each character represents a power of 16. For example:
+ *
+ * Hexadecimal "A1" = 10*16^1 + 1*16^0 = 161 (decimal)
+ *
+ *
+ * This class provides a method to perform the conversion without using built-in Java utilities.
+ */
public final class HexaDecimalToDecimal {
private HexaDecimalToDecimal() {
}
- // convert hexadecimal to decimal
+ /**
+ * Converts a hexadecimal string to its decimal integer equivalent.
+ * The input string is case-insensitive, and must contain valid hexadecimal characters [0-9, A-F].
+ *
+ * @param hex the hexadecimal string to convert
+ * @return the decimal integer representation of the input hexadecimal string
+ * @throws IllegalArgumentException if the input string contains invalid characters
+ */
public static int getHexaToDec(String hex) {
String digits = "0123456789ABCDEF";
hex = hex.toUpperCase();
int val = 0;
+
for (int i = 0; i < hex.length(); i++) {
int d = digits.indexOf(hex.charAt(i));
+ if (d == -1) {
+ throw new IllegalArgumentException("Invalid hexadecimal character: " + hex.charAt(i));
+ }
val = 16 * val + d;
}
- return val;
- }
- // Main method gets the hexadecimal input from user and converts it into Decimal output.
- public static void main(String[] args) {
- String hexaInput;
- int decOutput;
- Scanner scan = new Scanner(System.in);
-
- System.out.print("Enter Hexadecimal Number : ");
- hexaInput = scan.nextLine();
-
- // convert hexadecimal to decimal
- decOutput = getHexaToDec(hexaInput);
- /*
- Pass the string to the getHexaToDec function
- and it returns the decimal form in the variable decOutput.
- */
- System.out.println("Number in Decimal: " + decOutput);
- scan.close();
+ return val;
}
}
diff --git a/src/main/java/com/thealgorithms/conversions/IPConverter.java b/src/main/java/com/thealgorithms/conversions/IPConverter.java
new file mode 100644
index 000000000000..765cb0201dd5
--- /dev/null
+++ b/src/main/java/com/thealgorithms/conversions/IPConverter.java
@@ -0,0 +1,58 @@
+package com.thealgorithms.conversions;
+
+/**
+ * Converts an IPv4 address to its binary equivalent and vice-versa.
+ * IP to Binary: Converts an IPv4 address to its binary equivalent.
+ * Example: 127.3.4.5 -> 01111111.00000011.00000100.00000101
+ *
+ * Binary to IP: Converts a binary equivalent to an IPv4 address.
+ * Example: 01111111.00000011.00000100.00000101 -> 127.3.4.5
+ *
+ * @author Hardvan
+ */
+public final class IPConverter {
+ private IPConverter() {
+ }
+
+ /**
+ * Converts an IPv4 address to its binary equivalent.
+ * @param ip The IPv4 address to convert.
+ * @return The binary equivalent of the IPv4 address.
+ */
+ public static String ipToBinary(String ip) {
+ StringBuilder binary = new StringBuilder();
+ for (String octet : ip.split("\\.")) {
+ binary.append(octetToBinary(Integer.parseInt(octet))).append(".");
+ }
+ return binary.substring(0, binary.length() - 1);
+ }
+
+ /**
+ * Converts a single octet to its 8-bit binary representation.
+ * @param octet The octet to convert (0-255).
+ * @return The 8-bit binary representation as a String.
+ */
+ private static String octetToBinary(int octet) {
+ char[] binary = {'0', '0', '0', '0', '0', '0', '0', '0'};
+ for (int i = 7; i >= 0; i--) {
+ if ((octet & 1) == 1) {
+ binary[i] = '1';
+ }
+ octet >>>= 1;
+ }
+ return new String(binary);
+ }
+
+ /**
+ * Converts a binary equivalent to an IPv4 address.
+ * @param binary The binary equivalent to convert.
+ * @return The IPv4 address of the binary equivalent.
+ */
+ public static String binaryToIP(String binary) {
+ StringBuilder ip = new StringBuilder();
+ for (String octet : binary.split("\\.")) {
+ ip.append(Integer.parseInt(octet, 2)).append(".");
+ }
+ return ip.substring(0, ip.length() - 1);
+ }
+}
diff --git a/src/main/java/com/thealgorithms/conversions/IPv6Converter.java b/src/main/java/com/thealgorithms/conversions/IPv6Converter.java
new file mode 100644
index 000000000000..d42ffd027514
--- /dev/null
+++ b/src/main/java/com/thealgorithms/conversions/IPv6Converter.java
@@ -0,0 +1,98 @@
+package com.thealgorithms.conversions;
+
+import java.net.InetAddress;
+import java.net.UnknownHostException;
+import java.util.Arrays;
+
+/**
+ * A utility class for converting between IPv6 and IPv4 addresses.
+ *
+ * - Converts IPv4 to IPv6-mapped IPv6 address.
+ * - Extracts IPv4 address from IPv6-mapped IPv6.
+ * - Handles exceptions for invalid inputs.
+ *
+ * @author Hardvan
+ */
+public final class IPv6Converter {
+ private IPv6Converter() {
+ }
+
+ /**
+ * Converts an IPv4 address (e.g., "192.0.2.128") to an IPv6-mapped IPv6 address.
+ * Example: IPv4 "192.0.2.128" -> IPv6 "::ffff:192.0.2.128"
+ *
+ * @param ipv4Address The IPv4 address in string format.
+ * @return The corresponding IPv6-mapped IPv6 address.
+ * @throws UnknownHostException If the IPv4 address is invalid.
+ * @throws IllegalArgumentException If the IPv6 address is not a mapped IPv4 address.
+ */
+ public static String ipv4ToIpv6(String ipv4Address) throws UnknownHostException {
+ if (ipv4Address == null || ipv4Address.isEmpty()) {
+ throw new UnknownHostException("IPv4 address is empty.");
+ }
+
+ InetAddress ipv4 = InetAddress.getByName(ipv4Address);
+ byte[] ipv4Bytes = ipv4.getAddress();
+
+ // Create IPv6-mapped IPv6 address (starts with ::ffff:)
+ byte[] ipv6Bytes = new byte[16];
+ ipv6Bytes[10] = (byte) 0xff;
+ ipv6Bytes[11] = (byte) 0xff;
+ System.arraycopy(ipv4Bytes, 0, ipv6Bytes, 12, 4);
+
+ // Manually format to "::ffff:x.x.x.x" format
+ StringBuilder ipv6String = new StringBuilder("::ffff:");
+ for (int i = 12; i < 16; i++) {
+ ipv6String.append(ipv6Bytes[i] & 0xFF);
+ if (i < 15) {
+ ipv6String.append('.');
+ }
+ }
+ return ipv6String.toString();
+ }
+
+ /**
+ * Extracts the IPv4 address from an IPv6-mapped IPv6 address.
+ * Example: IPv6 "::ffff:192.0.2.128" -> IPv4 "192.0.2.128"
+ *
+ * @param ipv6Address The IPv6 address in string format.
+ * @return The extracted IPv4 address.
+ * @throws UnknownHostException If the IPv6 address is invalid or not a mapped IPv4 address.
+ */
+ public static String ipv6ToIpv4(String ipv6Address) throws UnknownHostException {
+ InetAddress ipv6 = InetAddress.getByName(ipv6Address);
+ byte[] ipv6Bytes = ipv6.getAddress();
+
+ // Check if the address is an IPv6-mapped IPv4 address
+ if (isValidIpv6MappedIpv4(ipv6Bytes)) {
+ byte[] ipv4Bytes = Arrays.copyOfRange(ipv6Bytes, 12, 16);
+ InetAddress ipv4 = InetAddress.getByAddress(ipv4Bytes);
+ return ipv4.getHostAddress();
+ } else {
+ throw new IllegalArgumentException("Not a valid IPv6-mapped IPv4 address.");
+ }
+ }
+
+ /**
+ * Helper function to check if the given byte array represents
+ * an IPv6-mapped IPv4 address (prefix 0:0:0:0:0:ffff).
+ *
+ * @param ipv6Bytes Byte array representation of the IPv6 address.
+ * @return True if the address is IPv6-mapped IPv4, otherwise false.
+ */
+ private static boolean isValidIpv6MappedIpv4(byte[] ipv6Bytes) {
+ // IPv6-mapped IPv4 addresses are 16 bytes long, with the first 10 bytes set to 0,
+ // followed by 0xff, 0xff, and the last 4 bytes representing the IPv4 address.
+ if (ipv6Bytes.length != 16) {
+ return false;
+ }
+
+ for (int i = 0; i < 10; i++) {
+ if (ipv6Bytes[i] != 0) {
+ return false;
+ }
+ }
+
+ return ipv6Bytes[10] == (byte) 0xff && ipv6Bytes[11] == (byte) 0xff;
+ }
+}
diff --git a/src/main/java/com/thealgorithms/conversions/IntegerToEnglish.java b/src/main/java/com/thealgorithms/conversions/IntegerToEnglish.java
index d3b938bf492d..e85c608af5d0 100644
--- a/src/main/java/com/thealgorithms/conversions/IntegerToEnglish.java
+++ b/src/main/java/com/thealgorithms/conversions/IntegerToEnglish.java
@@ -2,7 +2,28 @@
import java.util.Map;
+/**
+ * A utility class to convert integers to their English word representation.
+ *
+ * The class supports conversion of numbers from 0 to 2,147,483,647
+ * (the maximum value of a 32-bit signed integer). It divides the number
+ * into groups of three digits (thousands, millions, billions, etc.) and
+ * translates each group into words.
+ *
+ * Example Usage
+ *
+ * IntegerToEnglish.integerToEnglishWords(12345);
+ * // Output: "Twelve Thousand Three Hundred Forty Five"
+ *
+ *
+ * This class uses two maps:
+ *
+ * - BASE_NUMBERS_MAP: Holds English words for numbers 0-20, multiples of 10 up to 90, and 100.
+ * - THOUSAND_POWER_MAP: Maps powers of 1000 (e.g., Thousand, Million, Billion).
+ *
+ */
public final class IntegerToEnglish {
+
private static final Map BASE_NUMBERS_MAP = Map.ofEntries(Map.entry(0, ""), Map.entry(1, "One"), Map.entry(2, "Two"), Map.entry(3, "Three"), Map.entry(4, "Four"), Map.entry(5, "Five"), Map.entry(6, "Six"), Map.entry(7, "Seven"), Map.entry(8, "Eight"), Map.entry(9, "Nine"),
Map.entry(10, "Ten"), Map.entry(11, "Eleven"), Map.entry(12, "Twelve"), Map.entry(13, "Thirteen"), Map.entry(14, "Fourteen"), Map.entry(15, "Fifteen"), Map.entry(16, "Sixteen"), Map.entry(17, "Seventeen"), Map.entry(18, "Eighteen"), Map.entry(19, "Nineteen"), Map.entry(20, "Twenty"),
Map.entry(30, "Thirty"), Map.entry(40, "Forty"), Map.entry(50, "Fifty"), Map.entry(60, "Sixty"), Map.entry(70, "Seventy"), Map.entry(80, "Eighty"), Map.entry(90, "Ninety"), Map.entry(100, "Hundred"));
@@ -13,35 +34,46 @@ private IntegerToEnglish() {
}
/**
- converts numbers < 1000 to english words
+ * Converts numbers less than 1000 into English words.
+ *
+ * @param number the integer value (0-999) to convert
+ * @return the English word representation of the input number
*/
private static String convertToWords(int number) {
int remainder = number % 100;
-
- String result;
+ StringBuilder result = new StringBuilder();
if (remainder <= 20) {
- result = BASE_NUMBERS_MAP.get(remainder);
+ result.append(BASE_NUMBERS_MAP.get(remainder));
} else if (BASE_NUMBERS_MAP.containsKey(remainder)) {
- result = BASE_NUMBERS_MAP.get(remainder);
+ result.append(BASE_NUMBERS_MAP.get(remainder));
} else {
int tensDigit = remainder / 10;
int onesDigit = remainder % 10;
-
- result = String.format("%s %s", BASE_NUMBERS_MAP.get(tensDigit * 10), BASE_NUMBERS_MAP.get(onesDigit));
+ String tens = BASE_NUMBERS_MAP.getOrDefault(tensDigit * 10, "");
+ String ones = BASE_NUMBERS_MAP.getOrDefault(onesDigit, "");
+ result.append(tens);
+ if (ones != null && !ones.isEmpty()) {
+ result.append(" ").append(ones);
+ }
}
int hundredsDigit = number / 100;
-
if (hundredsDigit > 0) {
- result = String.format("%s %s%s", BASE_NUMBERS_MAP.get(hundredsDigit), BASE_NUMBERS_MAP.get(100), result.isEmpty() ? "" : " " + result);
+ if (result.length() > 0) {
+ result.insert(0, " ");
+ }
+ result.insert(0, String.format("%s Hundred", BASE_NUMBERS_MAP.get(hundredsDigit)));
}
- return result;
+ return result.toString().trim();
}
/**
- Only convert groups of three digit if they are non-zero
+ * Converts a non-negative integer to its English word representation.
+ *
+ * @param number the integer to convert (0-2,147,483,647)
+ * @return the English word representation of the input number
*/
public static String integerToEnglishWords(int number) {
if (number == 0) {
@@ -49,7 +81,6 @@ public static String integerToEnglishWords(int number) {
}
StringBuilder result = new StringBuilder();
-
int index = 0;
while (number > 0) {
@@ -58,23 +89,20 @@ public static String integerToEnglishWords(int number) {
if (remainder > 0) {
String subResult = convertToWords(remainder);
-
if (!subResult.isEmpty()) {
- if (!result.isEmpty()) {
- result.insert(0, subResult + " " + THOUSAND_POWER_MAP.get(index) + " ");
- } else {
- if (index > 0) {
- result = new StringBuilder(subResult + " " + THOUSAND_POWER_MAP.get(index));
- } else {
- result = new StringBuilder(subResult);
- }
+ if (index > 0) {
+ subResult += " " + THOUSAND_POWER_MAP.get(index);
+ }
+ if (result.length() > 0) {
+ result.insert(0, " ");
}
+ result.insert(0, subResult);
}
}
index++;
}
- return result.toString();
+ return result.toString().trim();
}
}
diff --git a/src/main/java/com/thealgorithms/conversions/IntegerToRoman.java b/src/main/java/com/thealgorithms/conversions/IntegerToRoman.java
index 9c031df9504d..fec437668fe6 100644
--- a/src/main/java/com/thealgorithms/conversions/IntegerToRoman.java
+++ b/src/main/java/com/thealgorithms/conversions/IntegerToRoman.java
@@ -1,68 +1,68 @@
package com.thealgorithms.conversions;
/**
- * Converting Integers into Roman Numerals
+ * A utility class to convert integers into Roman numerals.
*
- *
- * ('I', 1); ('IV',4); ('V', 5); ('IX',9); ('X', 10); ('XL',40); ('L', 50);
- * ('XC',90); ('C', 100); ('D', 500); ('M', 1000);
+ *
Roman numerals follow these rules:
+ *
+ * - I = 1
+ * - IV = 4
+ * - V = 5
+ * - IX = 9
+ * - X = 10
+ * - XL = 40
+ * - L = 50
+ * - XC = 90
+ * - C = 100
+ * - D = 500
+ * - M = 1000
+ *
+ *
+ * Conversion is based on repeatedly subtracting the largest possible Roman numeral value
+ * from the input number until it reaches zero. For example, 1994 is converted as:
+ *
+ * 1994 -> MCMXCIV (1000 + 900 + 90 + 4)
+ *
*/
public final class IntegerToRoman {
+
+ // Array of Roman numeral values in descending order
+ private static final int[] ALL_ROMAN_NUMBERS_IN_ARABIC = {1000, 900, 500, 400, 100, 90, 50, 40, 10, 9, 5, 4, 1};
+
+ // Corresponding Roman numeral symbols
+ private static final String[] ALL_ROMAN_NUMBERS = {"M", "CM", "D", "CD", "C", "XC", "L", "XL", "X", "IX", "V", "IV", "I"};
+
private IntegerToRoman() {
}
- private static final int[] ALL_ROMAN_NUMBERS_IN_ARABIC = new int[] {
- 1000,
- 900,
- 500,
- 400,
- 100,
- 90,
- 50,
- 40,
- 10,
- 9,
- 5,
- 4,
- 1,
- };
- private static final String[] ALL_ROMAN_NUMBERS = new String[] {
- "M",
- "CM",
- "D",
- "CD",
- "C",
- "XC",
- "L",
- "XL",
- "X",
- "IX",
- "V",
- "IV",
- "I",
- };
-
- // Value must be > 0
+ /**
+ * Converts an integer to its Roman numeral representation.
+ * Steps:
+ *
+ * - Iterate over the Roman numeral values in descending order
+ * - Calculate how many times a numeral fits
+ * - Append the corresponding symbol
+ * - Subtract the value from the number
+ * - Repeat until the number is zero
+ * - Return the Roman numeral representation
+ *
+ *
+ * @param num the integer value to convert (must be greater than 0)
+ * @return the Roman numeral representation of the input integer
+ * or an empty string if the input is non-positive
+ */
public static String integerToRoman(int num) {
if (num <= 0) {
return "";
}
StringBuilder builder = new StringBuilder();
-
- for (int a = 0; a < ALL_ROMAN_NUMBERS_IN_ARABIC.length; a++) {
- int times = num / ALL_ROMAN_NUMBERS_IN_ARABIC[a];
- for (int b = 0; b < times; b++) {
- builder.append(ALL_ROMAN_NUMBERS[a]);
- }
-
- num -= times * ALL_ROMAN_NUMBERS_IN_ARABIC[a];
+ for (int i = 0; i < ALL_ROMAN_NUMBERS_IN_ARABIC.length; i++) {
+ int times = num / ALL_ROMAN_NUMBERS_IN_ARABIC[i];
+ builder.append(ALL_ROMAN_NUMBERS[i].repeat(Math.max(0, times)));
+ num -= times * ALL_ROMAN_NUMBERS_IN_ARABIC[i];
}
return builder.toString();
}
-
- public static void main(String[] args) {
- System.out.println(IntegerToRoman.integerToRoman(2131));
- }
}
diff --git a/src/main/java/com/thealgorithms/conversions/MorseCodeConverter.java b/src/main/java/com/thealgorithms/conversions/MorseCodeConverter.java
new file mode 100644
index 000000000000..a3973da0c586
--- /dev/null
+++ b/src/main/java/com/thealgorithms/conversions/MorseCodeConverter.java
@@ -0,0 +1,98 @@
+package com.thealgorithms.conversions;
+
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * Converts text to Morse code and vice-versa.
+ * Text to Morse code: Each letter is separated by a space and each word is separated by a pipe (|).
+ * Example: "HELLO WORLD" -> ".... . .-.. .-.. --- | .-- --- .-. .-.. -.."
+ *
+ * Morse code to text: Each letter is separated by a space and each word is separated by a pipe (|).
+ * Example: ".... . .-.. .-.. --- | .-- --- .-. .-.. -.." -> "HELLO WORLD"
+ *
+ * Applications: Used in radio communications and algorithmic challenges.
+ *
+ * @author Hardvan
+ */
+public final class MorseCodeConverter {
+ private MorseCodeConverter() {
+ }
+
+ private static final Map MORSE_MAP = new HashMap<>();
+ private static final Map REVERSE_MAP = new HashMap<>();
+
+ static {
+ MORSE_MAP.put('A', ".-");
+ MORSE_MAP.put('B', "-...");
+ MORSE_MAP.put('C', "-.-.");
+ MORSE_MAP.put('D', "-..");
+ MORSE_MAP.put('E', ".");
+ MORSE_MAP.put('F', "..-.");
+ MORSE_MAP.put('G', "--.");
+ MORSE_MAP.put('H', "....");
+ MORSE_MAP.put('I', "..");
+ MORSE_MAP.put('J', ".---");
+ MORSE_MAP.put('K', "-.-");
+ MORSE_MAP.put('L', ".-..");
+ MORSE_MAP.put('M', "--");
+ MORSE_MAP.put('N', "-.");
+ MORSE_MAP.put('O', "---");
+ MORSE_MAP.put('P', ".--.");
+ MORSE_MAP.put('Q', "--.-");
+ MORSE_MAP.put('R', ".-.");
+ MORSE_MAP.put('S', "...");
+ MORSE_MAP.put('T', "-");
+ MORSE_MAP.put('U', "..-");
+ MORSE_MAP.put('V', "...-");
+ MORSE_MAP.put('W', ".--");
+ MORSE_MAP.put('X', "-..-");
+ MORSE_MAP.put('Y', "-.--");
+ MORSE_MAP.put('Z', "--..");
+
+ // Build reverse map for decoding
+ MORSE_MAP.forEach((k, v) -> REVERSE_MAP.put(v, k));
+ }
+
+ /**
+ * Converts text to Morse code.
+ * Each letter is separated by a space and each word is separated by a pipe (|).
+ *
+ * @param text The text to convert to Morse code.
+ * @return The Morse code representation of the text.
+ */
+ public static String textToMorse(String text) {
+ StringBuilder morse = new StringBuilder();
+ String[] words = text.toUpperCase().split(" ");
+ for (int i = 0; i < words.length; i++) {
+ for (char c : words[i].toCharArray()) {
+ morse.append(MORSE_MAP.getOrDefault(c, "")).append(" ");
+ }
+ if (i < words.length - 1) {
+ morse.append("| ");
+ }
+ }
+ return morse.toString().trim();
+ }
+
+ /**
+ * Converts Morse code to text.
+ * Each letter is separated by a space and each word is separated by a pipe (|).
+ *
+ * @param morse The Morse code to convert to text.
+ * @return The text representation of the Morse code.
+ */
+ public static String morseToText(String morse) {
+ StringBuilder text = new StringBuilder();
+ String[] words = morse.split(" \\| ");
+ for (int i = 0; i < words.length; i++) {
+ for (String code : words[i].split(" ")) {
+ text.append(REVERSE_MAP.getOrDefault(code, '?'));
+ }
+ if (i < words.length - 1) {
+ text.append(" ");
+ }
+ }
+ return text.toString();
+ }
+}
diff --git a/src/main/java/com/thealgorithms/conversions/NumberToWords.java b/src/main/java/com/thealgorithms/conversions/NumberToWords.java
new file mode 100644
index 000000000000..e39c5b2dea86
--- /dev/null
+++ b/src/main/java/com/thealgorithms/conversions/NumberToWords.java
@@ -0,0 +1,100 @@
+package com.thealgorithms.conversions;
+
+import java.math.BigDecimal;
+
+/**
+ A Java-based utility for converting numeric values into their English word
+ representations. Whether you need to convert a small number, a large number
+ with millions and billions, or even a number with decimal places, this utility
+ has you covered.
+ *
+ */
+public final class NumberToWords {
+
+ private NumberToWords() {
+ }
+
+ private static final String[] UNITS = {"", "One", "Two", "Three", "Four", "Five", "Six", "Seven", "Eight", "Nine", "Ten", "Eleven", "Twelve", "Thirteen", "Fourteen", "Fifteen", "Sixteen", "Seventeen", "Eighteen", "Nineteen"};
+
+ private static final String[] TENS = {"", "", "Twenty", "Thirty", "Forty", "Fifty", "Sixty", "Seventy", "Eighty", "Ninety"};
+
+ private static final String[] POWERS = {"", "Thousand", "Million", "Billion", "Trillion"};
+
+ private static final String ZERO = "Zero";
+ private static final String POINT = " Point";
+ private static final String NEGATIVE = "Negative ";
+
+ public static String convert(BigDecimal number) {
+ if (number == null) {
+ return "Invalid Input";
+ }
+
+ // Check for negative sign
+ boolean isNegative = number.signum() < 0;
+
+ // Split the number into whole and fractional parts
+ BigDecimal[] parts = number.abs().divideAndRemainder(BigDecimal.ONE);
+ BigDecimal wholePart = parts[0]; // Keep whole part as BigDecimal
+ String fractionalPartStr = parts[1].compareTo(BigDecimal.ZERO) > 0 ? parts[1].toPlainString().substring(2) : ""; // Get fractional part only if it exists
+
+ // Convert whole part to words
+ StringBuilder result = new StringBuilder();
+ if (isNegative) {
+ result.append(NEGATIVE);
+ }
+ result.append(convertWholeNumberToWords(wholePart));
+
+ // Convert fractional part to words
+ if (!fractionalPartStr.isEmpty()) {
+ result.append(POINT);
+ for (char digit : fractionalPartStr.toCharArray()) {
+ int digitValue = Character.getNumericValue(digit);
+ result.append(" ").append(digitValue == 0 ? ZERO : UNITS[digitValue]);
+ }
+ }
+
+ return result.toString().trim();
+ }
+
+ private static String convertWholeNumberToWords(BigDecimal number) {
+ if (number.compareTo(BigDecimal.ZERO) == 0) {
+ return ZERO;
+ }
+
+ StringBuilder words = new StringBuilder();
+ int power = 0;
+
+ while (number.compareTo(BigDecimal.ZERO) > 0) {
+ // Get the last three digits
+ BigDecimal[] divisionResult = number.divideAndRemainder(BigDecimal.valueOf(1000));
+ int chunk = divisionResult[1].intValue();
+
+ if (chunk > 0) {
+ String chunkWords = convertChunk(chunk);
+ if (power > 0) {
+ words.insert(0, POWERS[power] + " ");
+ }
+ words.insert(0, chunkWords + " ");
+ }
+
+ number = divisionResult[0]; // Continue with the remaining part
+ power++;
+ }
+
+ return words.toString().trim();
+ }
+
+ private static String convertChunk(int number) {
+ String chunkWords;
+
+ if (number < 20) {
+ chunkWords = UNITS[number];
+ } else if (number < 100) {
+ chunkWords = TENS[number / 10] + (number % 10 > 0 ? " " + UNITS[number % 10] : "");
+ } else {
+ chunkWords = UNITS[number / 100] + " Hundred" + (number % 100 > 0 ? " " + convertChunk(number % 100) : "");
+ }
+
+ return chunkWords;
+ }
+}
diff --git a/src/main/java/com/thealgorithms/conversions/OctalToBinary.java b/src/main/java/com/thealgorithms/conversions/OctalToBinary.java
index 6b01c2f65cfe..a66db97633b4 100644
--- a/src/main/java/com/thealgorithms/conversions/OctalToBinary.java
+++ b/src/main/java/com/thealgorithms/conversions/OctalToBinary.java
@@ -1,14 +1,40 @@
package com.thealgorithms.conversions;
/**
- * Converts any Octal Number to a Binary Number
+ * A utility class to convert an octal (base-8) number into its binary (base-2) representation.
+ *
+ * This class provides methods to:
+ *
+ * - Convert an octal number to its binary equivalent
+ * - Convert individual octal digits to binary
+ *
+ *
+ * Octal to Binary Conversion:
+ * An octal number is converted to binary by converting each octal digit to its 3-bit binary equivalent.
+ * The result is a long representing the full binary equivalent of the octal number.
+ *
+ * Example Usage
+ *
+ * long binary = OctalToBinary.convertOctalToBinary(52); // Output: 101010 (52 in octal is 101010 in binary)
+ *
*
* @author Bama Charan Chhandogi
+ * @see Octal Number System
+ * @see Binary Number System
*/
-
public final class OctalToBinary {
private OctalToBinary() {
}
+
+ /**
+ * Converts an octal number to its binary representation.
+ *
+ * Each octal digit is individually converted to its 3-bit binary equivalent, and the binary
+ * digits are concatenated to form the final binary number.
+ *
+ * @param octalNumber the octal number to convert (non-negative integer)
+ * @return the binary equivalent as a long
+ */
public static long convertOctalToBinary(int octalNumber) {
long binaryNumber = 0;
int digitPosition = 1;
@@ -20,12 +46,25 @@ public static long convertOctalToBinary(int octalNumber) {
binaryNumber += binaryDigit * digitPosition;
octalNumber /= 10;
- digitPosition *= 1000; // Move to the next group of 3 binary digits
+ digitPosition *= 1000;
}
return binaryNumber;
}
+ /**
+ * Converts a single octal digit (0-7) to its binary equivalent.
+ *
+ * For example:
+ *
+ * - Octal digit 7 is converted to binary 111
+ * - Octal digit 3 is converted to binary 011
+ *
+ *
+ *
+ * @param octalDigit a single octal digit (0-7)
+ * @return the binary equivalent as a long
+ */
public static long convertOctalDigitToBinary(int octalDigit) {
long binaryDigit = 0;
int binaryMultiplier = 1;
diff --git a/src/main/java/com/thealgorithms/conversions/PhoneticAlphabetConverter.java b/src/main/java/com/thealgorithms/conversions/PhoneticAlphabetConverter.java
new file mode 100644
index 000000000000..730ce2214e2d
--- /dev/null
+++ b/src/main/java/com/thealgorithms/conversions/PhoneticAlphabetConverter.java
@@ -0,0 +1,84 @@
+package com.thealgorithms.conversions;
+
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * Converts text to the NATO phonetic alphabet.
+ * Examples:
+ * "ABC" -> "Alpha Bravo Charlie"
+ * "Hello" -> "Hotel Echo Lima Lima Oscar"
+ * "123" -> "One Two Three"
+ * "A1B2C3" -> "Alpha One Bravo Two Charlie Three"
+ *
+ * @author Hardvan
+ */
+public final class PhoneticAlphabetConverter {
+ private PhoneticAlphabetConverter() {
+ }
+
+ private static final Map PHONETIC_MAP = new HashMap<>();
+
+ static {
+ PHONETIC_MAP.put('A', "Alpha");
+ PHONETIC_MAP.put('B', "Bravo");
+ PHONETIC_MAP.put('C', "Charlie");
+ PHONETIC_MAP.put('D', "Delta");
+ PHONETIC_MAP.put('E', "Echo");
+ PHONETIC_MAP.put('F', "Foxtrot");
+ PHONETIC_MAP.put('G', "Golf");
+ PHONETIC_MAP.put('H', "Hotel");
+ PHONETIC_MAP.put('I', "India");
+ PHONETIC_MAP.put('J', "Juliett");
+ PHONETIC_MAP.put('K', "Kilo");
+ PHONETIC_MAP.put('L', "Lima");
+ PHONETIC_MAP.put('M', "Mike");
+ PHONETIC_MAP.put('N', "November");
+ PHONETIC_MAP.put('O', "Oscar");
+ PHONETIC_MAP.put('P', "Papa");
+ PHONETIC_MAP.put('Q', "Quebec");
+ PHONETIC_MAP.put('R', "Romeo");
+ PHONETIC_MAP.put('S', "Sierra");
+ PHONETIC_MAP.put('T', "Tango");
+ PHONETIC_MAP.put('U', "Uniform");
+ PHONETIC_MAP.put('V', "Victor");
+ PHONETIC_MAP.put('W', "Whiskey");
+ PHONETIC_MAP.put('X', "X-ray");
+ PHONETIC_MAP.put('Y', "Yankee");
+ PHONETIC_MAP.put('Z', "Zulu");
+ PHONETIC_MAP.put('0', "Zero");
+ PHONETIC_MAP.put('1', "One");
+ PHONETIC_MAP.put('2', "Two");
+ PHONETIC_MAP.put('3', "Three");
+ PHONETIC_MAP.put('4', "Four");
+ PHONETIC_MAP.put('5', "Five");
+ PHONETIC_MAP.put('6', "Six");
+ PHONETIC_MAP.put('7', "Seven");
+ PHONETIC_MAP.put('8', "Eight");
+ PHONETIC_MAP.put('9', "Nine");
+ }
+
+ /**
+ * Converts text to the NATO phonetic alphabet.
+ * Steps:
+ * 1. Convert the text to uppercase.
+ * 2. Iterate over each character in the text.
+ * 3. Get the phonetic equivalent of the character from the map.
+ * 4. Append the phonetic equivalent to the result.
+ * 5. Append a space to separate the phonetic equivalents.
+ * 6. Return the result.
+ *
+ * @param text the text to convert
+ * @return the NATO phonetic alphabet
+ */
+ public static String textToPhonetic(String text) {
+ StringBuilder phonetic = new StringBuilder();
+ for (char c : text.toUpperCase().toCharArray()) {
+ if (Character.isWhitespace(c)) {
+ continue;
+ }
+ phonetic.append(PHONETIC_MAP.getOrDefault(c, String.valueOf(c))).append(" ");
+ }
+ return phonetic.toString().trim();
+ }
+}
diff --git a/src/main/java/com/thealgorithms/conversions/RomanToInteger.java b/src/main/java/com/thealgorithms/conversions/RomanToInteger.java
index 1934e9b264c9..a634c720326f 100644
--- a/src/main/java/com/thealgorithms/conversions/RomanToInteger.java
+++ b/src/main/java/com/thealgorithms/conversions/RomanToInteger.java
@@ -3,9 +3,27 @@
import java.util.HashMap;
import java.util.Map;
+/**
+ * A utility class to convert Roman numerals into integers.
+ *
+ * Roman numerals are based on seven symbols given below:
+ *
+ * - I = 1
+ * - V = 5
+ * - X = 10
+ * - L = 50
+ * - C = 100
+ * - D = 500
+ * - M = 1000
+ *
+ *
+ * If a smaller numeral appears before a larger numeral, it is subtracted.
+ * Otherwise, it is added. For example:
+ *
+ * MCMXCIV = 1000 + (1000 - 100) + (100 - 10) + (5 - 1) = 1994
+ *
+ */
public final class RomanToInteger {
- private RomanToInteger() {
- }
private static final Map ROMAN_TO_INT = new HashMap<>() {
{
@@ -19,44 +37,53 @@ private RomanToInteger() {
}
};
+ private RomanToInteger() {
+ }
+
+ /**
+ * Converts a single Roman numeral character to its integer value.
+ *
+ * @param symbol the Roman numeral character
+ * @return the corresponding integer value
+ * @throws IllegalArgumentException if the symbol is not a valid Roman numeral
+ */
private static int romanSymbolToInt(final char symbol) {
return ROMAN_TO_INT.computeIfAbsent(symbol, c -> { throw new IllegalArgumentException("Unknown Roman symbol: " + c); });
}
- // Roman Number = Roman Numerals
-
/**
- * This function convert Roman number into Integer
+ * Converts a Roman numeral string to its integer equivalent.
+ * Steps:
+ *
+ * - Iterate over the string from right to left.
+ * - For each character, convert it to an integer value.
+ * - If the current value is greater than or equal to the max previous value, add it.
+ * - Otherwise, subtract it from the sum.
+ * - Update the max previous value.
+ * - Return the sum.
+ *
*
- * @param a Roman number string
- * @return integer
+ * @param roman the Roman numeral string
+ * @return the integer value of the Roman numeral
+ * @throws IllegalArgumentException if the input contains invalid Roman characters
+ * @throws NullPointerException if the input is {@code null}
*/
- public static int romanToInt(String a) {
- a = a.toUpperCase();
- char prev = ' ';
+ public static int romanToInt(String roman) {
+ if (roman == null) {
+ throw new NullPointerException("Input cannot be null");
+ }
+ roman = roman.toUpperCase();
int sum = 0;
-
- int newPrev = 0;
- for (int i = a.length() - 1; i >= 0; i--) {
- char c = a.charAt(i);
-
- if (prev != ' ') {
- // checking current Number greater than previous or not
- newPrev = romanSymbolToInt(prev) > newPrev ? romanSymbolToInt(prev) : newPrev;
- }
-
- int currentNum = romanSymbolToInt(c);
-
- // if current number greater than prev max previous then add
- if (currentNum >= newPrev) {
- sum += currentNum;
+ int maxPrevValue = 0;
+ for (int i = roman.length() - 1; i >= 0; i--) {
+ int currentValue = romanSymbolToInt(roman.charAt(i));
+ if (currentValue >= maxPrevValue) {
+ sum += currentValue;
+ maxPrevValue = currentValue;
} else {
- // subtract upcoming number until upcoming number not greater than prev max
- sum -= currentNum;
+ sum -= currentValue;
}
-
- prev = c;
}
return sum;
diff --git a/src/main/java/com/thealgorithms/conversions/TimeConverter.java b/src/main/java/com/thealgorithms/conversions/TimeConverter.java
new file mode 100644
index 000000000000..41cae37d7ad1
--- /dev/null
+++ b/src/main/java/com/thealgorithms/conversions/TimeConverter.java
@@ -0,0 +1,97 @@
+package com.thealgorithms.conversions;
+
+import java.util.Locale;
+import java.util.Map;
+
+/**
+ * A utility class to convert between different units of time.
+ *
+ * This class supports conversions between the following units:
+ *
+ * - seconds
+ * - minutes
+ * - hours
+ * - days
+ * - weeks
+ * - months (approximated as 30.44 days)
+ * - years (approximated as 365.25 days)
+ *
+ *
+ * The conversion is based on predefined constants in seconds.
+ * Results are rounded to three decimal places for consistency.
+ *
+ *
This class is final and cannot be instantiated.
+ *
+ * @see Wikipedia: Unit of time
+ */
+public final class TimeConverter {
+
+ private TimeConverter() {
+ // Prevent instantiation
+ }
+
+ /**
+ * Supported time units with their equivalent in seconds.
+ */
+ private enum TimeUnit {
+ SECONDS(1.0),
+ MINUTES(60.0),
+ HOURS(3600.0),
+ DAYS(86400.0),
+ WEEKS(604800.0),
+ MONTHS(2629800.0), // 30.44 days
+ YEARS(31557600.0); // 365.25 days
+
+ private final double seconds;
+
+ TimeUnit(double seconds) {
+ this.seconds = seconds;
+ }
+
+ public double toSeconds(double value) {
+ return value * seconds;
+ }
+
+ public double fromSeconds(double secondsValue) {
+ return secondsValue / seconds;
+ }
+ }
+
+ private static final Map UNIT_LOOKUP
+ = Map.ofEntries(Map.entry("seconds", TimeUnit.SECONDS), Map.entry("minutes", TimeUnit.MINUTES), Map.entry("hours", TimeUnit.HOURS), Map.entry("days", TimeUnit.DAYS), Map.entry("weeks", TimeUnit.WEEKS), Map.entry("months", TimeUnit.MONTHS), Map.entry("years", TimeUnit.YEARS));
+
+ /**
+ * Converts a time value from one unit to another.
+ *
+ * @param timeValue the numeric value of time to convert; must be non-negative
+ * @param unitFrom the unit of the input value (e.g., "minutes", "hours")
+ * @param unitTo the unit to convert into (e.g., "seconds", "days")
+ * @return the converted value in the target unit, rounded to three decimals
+ * @throws IllegalArgumentException if {@code timeValue} is negative
+ * @throws IllegalArgumentException if either {@code unitFrom} or {@code unitTo} is not supported
+ */
+ public static double convertTime(double timeValue, String unitFrom, String unitTo) {
+ if (timeValue < 0) {
+ throw new IllegalArgumentException("timeValue must be a non-negative number.");
+ }
+
+ TimeUnit from = resolveUnit(unitFrom);
+ TimeUnit to = resolveUnit(unitTo);
+
+ double secondsValue = from.toSeconds(timeValue);
+ double converted = to.fromSeconds(secondsValue);
+
+ return Math.round(converted * 1000.0) / 1000.0;
+ }
+
+ private static TimeUnit resolveUnit(String unit) {
+ if (unit == null) {
+ throw new IllegalArgumentException("Unit cannot be null.");
+ }
+ TimeUnit resolved = UNIT_LOOKUP.get(unit.toLowerCase(Locale.ROOT));
+ if (resolved == null) {
+ throw new IllegalArgumentException("Invalid unit '" + unit + "'. Supported units are: " + UNIT_LOOKUP.keySet());
+ }
+ return resolved;
+ }
+}
diff --git a/src/main/java/com/thealgorithms/conversions/TurkishToLatinConversion.java b/src/main/java/com/thealgorithms/conversions/TurkishToLatinConversion.java
index 4d13b8b7fd55..30030de6c1bd 100644
--- a/src/main/java/com/thealgorithms/conversions/TurkishToLatinConversion.java
+++ b/src/main/java/com/thealgorithms/conversions/TurkishToLatinConversion.java
@@ -1,7 +1,5 @@
package com.thealgorithms.conversions;
-import java.util.Scanner;
-
/**
* Converts turkish character to latin character
*
@@ -11,21 +9,12 @@ public final class TurkishToLatinConversion {
private TurkishToLatinConversion() {
}
- /**
- * Main method
- *
- * @param args Command line arguments
- */
- public static void main(String[] args) {
- Scanner sc = new Scanner(System.in);
- System.out.println("Input the string: ");
- String b = sc.next();
- System.out.println("Converted: " + convertTurkishToLatin(b));
- sc.close();
- }
-
/**
* This method converts a turkish character to latin character.
+ * Steps:
+ * 1. Define turkish characters and their corresponding latin characters
+ * 2. Replace all turkish characters with their corresponding latin characters
+ * 3. Return the converted string
*
* @param param String paramter
* @return String
diff --git a/src/main/java/com/thealgorithms/conversions/UnitConversions.java b/src/main/java/com/thealgorithms/conversions/UnitConversions.java
index abc06a0f8863..15f74a21a17e 100644
--- a/src/main/java/com/thealgorithms/conversions/UnitConversions.java
+++ b/src/main/java/com/thealgorithms/conversions/UnitConversions.java
@@ -5,10 +5,47 @@
import java.util.Map;
import org.apache.commons.lang3.tuple.Pair;
+/**
+ * A utility class to perform unit conversions between different measurement systems.
+ *
+ * Currently, the class supports temperature conversions between several scales:
+ * Celsius, Fahrenheit, Kelvin, Réaumur, Delisle, and Rankine.
+ *
+ *
Example Usage
+ *
+ * double result = UnitConversions.TEMPERATURE.convert("Celsius", "Fahrenheit", 100.0);
+ * // Output: 212.0 (Celsius to Fahrenheit conversion of 100°C)
+ *
+ *
+ * This class makes use of an {@link UnitsConverter} that handles the conversion logic
+ * based on predefined affine transformations. These transformations include scaling factors
+ * and offsets for temperature conversions.
+ *
+ *
Temperature Scales Supported
+ *
+ * - Celsius
+ * - Fahrenheit
+ * - Kelvin
+ * - Réaumur
+ * - Delisle
+ * - Rankine
+ *
+ */
public final class UnitConversions {
private UnitConversions() {
}
+ /**
+ * A preconfigured instance of {@link UnitsConverter} for temperature conversions.
+ * The converter handles conversions between the following temperature units:
+ *
+ * - Kelvin to Celsius
+ * - Celsius to Fahrenheit
+ * - Réaumur to Celsius
+ * - Delisle to Celsius
+ * - Rankine to Kelvin
+ *
+ */
public static final UnitsConverter TEMPERATURE = new UnitsConverter(Map.ofEntries(entry(Pair.of("Kelvin", "Celsius"), new AffineConverter(1.0, -273.15)), entry(Pair.of("Celsius", "Fahrenheit"), new AffineConverter(9.0 / 5.0, 32.0)),
entry(Pair.of("Réaumur", "Celsius"), new AffineConverter(5.0 / 4.0, 0.0)), entry(Pair.of("Delisle", "Celsius"), new AffineConverter(-2.0 / 3.0, 100.0)), entry(Pair.of("Rankine", "Kelvin"), new AffineConverter(5.0 / 9.0, 0.0))));
}
diff --git a/src/main/java/com/thealgorithms/conversions/UnitsConverter.java b/src/main/java/com/thealgorithms/conversions/UnitsConverter.java
index 81c4d4562070..00690b2c0f9b 100644
--- a/src/main/java/com/thealgorithms/conversions/UnitsConverter.java
+++ b/src/main/java/com/thealgorithms/conversions/UnitsConverter.java
@@ -7,6 +7,43 @@
import java.util.Set;
import org.apache.commons.lang3.tuple.Pair;
+/**
+ * A class that handles unit conversions using affine transformations.
+ *
+ * The {@code UnitsConverter} allows converting values between different units using
+ * pre-defined affine conversion formulas. Each conversion is represented by an
+ * {@link AffineConverter} that defines the scaling and offset for the conversion.
+ *
+ *
For each unit, both direct conversions (e.g., Celsius to Fahrenheit) and inverse
+ * conversions (e.g., Fahrenheit to Celsius) are generated automatically. It also computes
+ * transitive conversions (e.g., Celsius to Kelvin via Fahrenheit if both conversions exist).
+ *
+ *
Key features include:
+ *
+ * - Automatic handling of inverse conversions (e.g., Fahrenheit to Celsius).
+ * - Compositional conversions, meaning if conversions between A -> B and B -> C exist,
+ * it can automatically generate A -> C conversion.
+ * - Supports multiple unit systems as long as conversions are provided in pairs.
+ *
+ *
+ * Example Usage
+ *
+ * Map<Pair<String, String>, AffineConverter> basicConversions = Map.ofEntries(
+ * entry(Pair.of("Celsius", "Fahrenheit"), new AffineConverter(9.0 / 5.0, 32.0)),
+ * entry(Pair.of("Kelvin", "Celsius"), new AffineConverter(1.0, -273.15))
+ * );
+ *
+ * UnitsConverter converter = new UnitsConverter(basicConversions);
+ * double result = converter.convert("Celsius", "Fahrenheit", 100.0);
+ * // Output: 212.0 (Celsius to Fahrenheit conversion of 100°C)
+ *
+ *
+ * Exception Handling
+ *
+ * - If the input unit and output unit are the same, an {@link IllegalArgumentException} is thrown.
+ * - If a conversion between the requested units does not exist, a {@link NoSuchElementException} is thrown.
+ *
+ */
public final class UnitsConverter {
private final Map, AffineConverter> conversions;
private final Set units;
@@ -68,11 +105,29 @@ private static Set extractUnits(final Map, AffineCo
return res;
}
+ /**
+ * Constructor for {@code UnitsConverter}.
+ *
+ * Accepts a map of basic conversions and automatically generates inverse and
+ * transitive conversions.
+ *
+ * @param basicConversions the initial set of unit conversions to add.
+ */
public UnitsConverter(final Map, AffineConverter> basicConversions) {
conversions = computeAllConversions(basicConversions);
units = extractUnits(conversions);
}
+ /**
+ * Converts a value from one unit to another.
+ *
+ * @param inputUnit the unit of the input value.
+ * @param outputUnit the unit to convert the value into.
+ * @param value the value to convert.
+ * @return the converted value in the target unit.
+ * @throws IllegalArgumentException if inputUnit equals outputUnit.
+ * @throws NoSuchElementException if no conversion exists between the units.
+ */
public double convert(final String inputUnit, final String outputUnit, final double value) {
if (inputUnit.equals(outputUnit)) {
throw new IllegalArgumentException("inputUnit must be different from outputUnit.");
@@ -81,6 +136,11 @@ public double convert(final String inputUnit, final String outputUnit, final dou
return conversions.computeIfAbsent(conversionKey, k -> { throw new NoSuchElementException("No converter for: " + k); }).convert(value);
}
+ /**
+ * Retrieves the set of all units supported by this converter.
+ *
+ * @return a set of available units.
+ */
public Set availableUnits() {
return units;
}
diff --git a/src/main/java/com/thealgorithms/conversions/WordsToNumber.java b/src/main/java/com/thealgorithms/conversions/WordsToNumber.java
new file mode 100644
index 000000000000..e2b81a0f4b47
--- /dev/null
+++ b/src/main/java/com/thealgorithms/conversions/WordsToNumber.java
@@ -0,0 +1,343 @@
+package com.thealgorithms.conversions;
+
+import java.io.Serial;
+import java.math.BigDecimal;
+import java.util.ArrayDeque;
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.List;
+
+/**
+ A Java-based utility for converting English word representations of numbers
+ into their numeric form. This utility supports whole numbers, decimals,
+ large values up to trillions, and even scientific notation where applicable.
+ It ensures accurate parsing while handling edge cases like negative numbers,
+ improper word placements, and ambiguous inputs.
+ *
+ */
+
+public final class WordsToNumber {
+
+ private WordsToNumber() {
+ }
+
+ private enum NumberWord {
+ ZERO("zero", 0),
+ ONE("one", 1),
+ TWO("two", 2),
+ THREE("three", 3),
+ FOUR("four", 4),
+ FIVE("five", 5),
+ SIX("six", 6),
+ SEVEN("seven", 7),
+ EIGHT("eight", 8),
+ NINE("nine", 9),
+ TEN("ten", 10),
+ ELEVEN("eleven", 11),
+ TWELVE("twelve", 12),
+ THIRTEEN("thirteen", 13),
+ FOURTEEN("fourteen", 14),
+ FIFTEEN("fifteen", 15),
+ SIXTEEN("sixteen", 16),
+ SEVENTEEN("seventeen", 17),
+ EIGHTEEN("eighteen", 18),
+ NINETEEN("nineteen", 19),
+ TWENTY("twenty", 20),
+ THIRTY("thirty", 30),
+ FORTY("forty", 40),
+ FIFTY("fifty", 50),
+ SIXTY("sixty", 60),
+ SEVENTY("seventy", 70),
+ EIGHTY("eighty", 80),
+ NINETY("ninety", 90);
+
+ private final String word;
+ private final int value;
+
+ NumberWord(String word, int value) {
+ this.word = word;
+ this.value = value;
+ }
+
+ public static Integer getValue(String word) {
+ for (NumberWord num : values()) {
+ if (word.equals(num.word)) {
+ return num.value;
+ }
+ }
+ return null;
+ }
+ }
+
+ private enum PowerOfTen {
+ THOUSAND("thousand", new BigDecimal("1000")),
+ MILLION("million", new BigDecimal("1000000")),
+ BILLION("billion", new BigDecimal("1000000000")),
+ TRILLION("trillion", new BigDecimal("1000000000000"));
+
+ private final String word;
+ private final BigDecimal value;
+
+ PowerOfTen(String word, BigDecimal value) {
+ this.word = word;
+ this.value = value;
+ }
+
+ public static BigDecimal getValue(String word) {
+ for (PowerOfTen power : values()) {
+ if (word.equals(power.word)) {
+ return power.value;
+ }
+ }
+ return null;
+ }
+ }
+
+ public static String convert(String numberInWords) {
+ if (numberInWords == null) {
+ throw new WordsToNumberException(WordsToNumberException.ErrorType.NULL_INPUT, "");
+ }
+
+ ArrayDeque wordDeque = preprocessWords(numberInWords);
+ BigDecimal completeNumber = convertWordQueueToBigDecimal(wordDeque);
+
+ return completeNumber.toString();
+ }
+
+ public static BigDecimal convertToBigDecimal(String numberInWords) {
+ String conversionResult = convert(numberInWords);
+ return new BigDecimal(conversionResult);
+ }
+
+ private static ArrayDeque preprocessWords(String numberInWords) {
+ String[] wordSplitArray = numberInWords.trim().split("[ ,-]");
+ ArrayDeque wordDeque = new ArrayDeque<>();
+ for (String word : wordSplitArray) {
+ if (word.isEmpty()) {
+ continue;
+ }
+ wordDeque.add(word.toLowerCase());
+ }
+ if (wordDeque.isEmpty()) {
+ throw new WordsToNumberException(WordsToNumberException.ErrorType.NULL_INPUT, "");
+ }
+ return wordDeque;
+ }
+
+ private static void handleConjunction(boolean prevNumWasHundred, boolean prevNumWasPowerOfTen, ArrayDeque wordDeque) {
+ if (wordDeque.isEmpty()) {
+ throw new WordsToNumberException(WordsToNumberException.ErrorType.INVALID_CONJUNCTION, "");
+ }
+
+ String nextWord = wordDeque.pollFirst();
+ String afterNextWord = wordDeque.peekFirst();
+
+ wordDeque.addFirst(nextWord);
+
+ Integer number = NumberWord.getValue(nextWord);
+
+ boolean isPrevWordValid = prevNumWasHundred || prevNumWasPowerOfTen;
+ boolean isNextWordValid = number != null && (number >= 10 || afterNextWord == null || "point".equals(afterNextWord));
+
+ if (!isPrevWordValid || !isNextWordValid) {
+ throw new WordsToNumberException(WordsToNumberException.ErrorType.INVALID_CONJUNCTION, "");
+ }
+ }
+
+ private static BigDecimal handleHundred(BigDecimal currentChunk, String word, boolean prevNumWasPowerOfTen) {
+ boolean currentChunkIsZero = currentChunk.compareTo(BigDecimal.ZERO) == 0;
+ if (currentChunk.compareTo(BigDecimal.TEN) >= 0 || prevNumWasPowerOfTen) {
+ throw new WordsToNumberException(WordsToNumberException.ErrorType.UNEXPECTED_WORD, word);
+ }
+ if (currentChunkIsZero) {
+ currentChunk = currentChunk.add(BigDecimal.ONE);
+ }
+ return currentChunk.multiply(BigDecimal.valueOf(100));
+ }
+
+ private static void handlePowerOfTen(List chunks, BigDecimal currentChunk, BigDecimal powerOfTen, String word, boolean prevNumWasPowerOfTen) {
+ boolean currentChunkIsZero = currentChunk.compareTo(BigDecimal.ZERO) == 0;
+ if (currentChunkIsZero || prevNumWasPowerOfTen) {
+ throw new WordsToNumberException(WordsToNumberException.ErrorType.UNEXPECTED_WORD, word);
+ }
+ BigDecimal nextChunk = currentChunk.multiply(powerOfTen);
+
+ if (!(chunks.isEmpty() || isAdditionSafe(chunks.getLast(), nextChunk))) {
+ throw new WordsToNumberException(WordsToNumberException.ErrorType.UNEXPECTED_WORD, word);
+ }
+ chunks.add(nextChunk);
+ }
+
+ private static BigDecimal handleNumber(Collection chunks, BigDecimal currentChunk, String word, Integer number) {
+ boolean currentChunkIsZero = currentChunk.compareTo(BigDecimal.ZERO) == 0;
+ if (number == 0 && !(currentChunkIsZero && chunks.isEmpty())) {
+ throw new WordsToNumberException(WordsToNumberException.ErrorType.UNEXPECTED_WORD, word);
+ }
+ BigDecimal bigDecimalNumber = BigDecimal.valueOf(number);
+
+ if (!currentChunkIsZero && !isAdditionSafe(currentChunk, bigDecimalNumber)) {
+ throw new WordsToNumberException(WordsToNumberException.ErrorType.UNEXPECTED_WORD, word);
+ }
+ return currentChunk.add(bigDecimalNumber);
+ }
+
+ private static void handlePoint(Collection chunks, BigDecimal currentChunk, ArrayDeque wordDeque) {
+ boolean currentChunkIsZero = currentChunk.compareTo(BigDecimal.ZERO) == 0;
+ if (!currentChunkIsZero) {
+ chunks.add(currentChunk);
+ }
+
+ String decimalPart = convertDecimalPart(wordDeque);
+ chunks.add(new BigDecimal(decimalPart));
+ }
+
+ private static void handleNegative(boolean isNegative) {
+ if (isNegative) {
+ throw new WordsToNumberException(WordsToNumberException.ErrorType.MULTIPLE_NEGATIVES, "");
+ }
+ throw new WordsToNumberException(WordsToNumberException.ErrorType.INVALID_NEGATIVE, "");
+ }
+
+ private static BigDecimal convertWordQueueToBigDecimal(ArrayDeque wordDeque) {
+ BigDecimal currentChunk = BigDecimal.ZERO;
+ List chunks = new ArrayList<>();
+
+ boolean isNegative = "negative".equals(wordDeque.peek());
+ if (isNegative) {
+ wordDeque.poll();
+ }
+
+ boolean prevNumWasHundred = false;
+ boolean prevNumWasPowerOfTen = false;
+
+ while (!wordDeque.isEmpty()) {
+ String word = wordDeque.poll();
+
+ switch (word) {
+ case "and" -> {
+ handleConjunction(prevNumWasHundred, prevNumWasPowerOfTen, wordDeque);
+ continue;
+ }
+ case "hundred" -> {
+ currentChunk = handleHundred(currentChunk, word, prevNumWasPowerOfTen);
+ prevNumWasHundred = true;
+ continue;
+ }
+ default -> {
+
+ }
+ }
+ prevNumWasHundred = false;
+
+ BigDecimal powerOfTen = PowerOfTen.getValue(word);
+ if (powerOfTen != null) {
+ handlePowerOfTen(chunks, currentChunk, powerOfTen, word, prevNumWasPowerOfTen);
+ currentChunk = BigDecimal.ZERO;
+ prevNumWasPowerOfTen = true;
+ continue;
+ }
+ prevNumWasPowerOfTen = false;
+
+ Integer number = NumberWord.getValue(word);
+ if (number != null) {
+ currentChunk = handleNumber(chunks, currentChunk, word, number);
+ continue;
+ }
+
+ switch (word) {
+ case "point" -> {
+ handlePoint(chunks, currentChunk, wordDeque);
+ currentChunk = BigDecimal.ZERO;
+ continue;
+ }
+ case "negative" -> {
+ handleNegative(isNegative);
+ }
+ default -> {
+
+ }
+ }
+
+ throw new WordsToNumberException(WordsToNumberException.ErrorType.UNKNOWN_WORD, word);
+ }
+
+ if (currentChunk.compareTo(BigDecimal.ZERO) != 0) {
+ chunks.add(currentChunk);
+ }
+
+ BigDecimal completeNumber = combineChunks(chunks);
+ return isNegative ? completeNumber.multiply(BigDecimal.valueOf(-1))
+ :
+ completeNumber;
+ }
+
+ private static boolean isAdditionSafe(BigDecimal currentChunk, BigDecimal number) {
+ int chunkDigitCount = currentChunk.toString().length();
+ int numberDigitCount = number.toString().length();
+ return chunkDigitCount > numberDigitCount;
+ }
+
+ private static String convertDecimalPart(ArrayDeque wordDeque) {
+ StringBuilder decimalPart = new StringBuilder(".");
+
+ while (!wordDeque.isEmpty()) {
+ String word = wordDeque.poll();
+ Integer number = NumberWord.getValue(word);
+ if (number == null) {
+ throw new WordsToNumberException(WordsToNumberException.ErrorType.UNEXPECTED_WORD_AFTER_POINT, word);
+ }
+ decimalPart.append(number);
+ }
+
+ boolean missingNumbers = decimalPart.length() == 1;
+ if (missingNumbers) {
+ throw new WordsToNumberException(WordsToNumberException.ErrorType.MISSING_DECIMAL_NUMBERS, "");
+ }
+ return decimalPart.toString();
+ }
+
+ private static BigDecimal combineChunks(List chunks) {
+ BigDecimal completeNumber = BigDecimal.ZERO;
+ for (BigDecimal chunk : chunks) {
+ completeNumber = completeNumber.add(chunk);
+ }
+ return completeNumber;
+ }
+ }
+
+ class WordsToNumberException extends RuntimeException {
+
+ @Serial private static final long serialVersionUID = 1L;
+
+ enum ErrorType {
+ NULL_INPUT("'null' or empty input provided"),
+ UNKNOWN_WORD("Unknown Word: "),
+ UNEXPECTED_WORD("Unexpected Word: "),
+ UNEXPECTED_WORD_AFTER_POINT("Unexpected Word (after Point): "),
+ MISSING_DECIMAL_NUMBERS("Decimal part is missing numbers."),
+ MULTIPLE_NEGATIVES("Multiple 'Negative's detected."),
+ INVALID_NEGATIVE("Incorrect 'negative' placement"),
+ INVALID_CONJUNCTION("Incorrect 'and' placement");
+
+ private final String message;
+
+ ErrorType(String message) {
+ this.message = message;
+ }
+
+ public String formatMessage(String details) {
+ return "Invalid Input. " + message + (details.isEmpty() ? "" : details);
+ }
+ }
+
+ public final ErrorType errorType;
+
+ WordsToNumberException(ErrorType errorType, String details) {
+ super(errorType.formatMessage(details));
+ this.errorType = errorType;
+ }
+
+ public ErrorType getErrorType() {
+ return errorType;
+ }
+ }
diff --git a/src/main/java/com/thealgorithms/datastructures/bags/Bag.java b/src/main/java/com/thealgorithms/datastructures/bags/Bag.java
index 1bb143fabda1..afc3bbe40cce 100644
--- a/src/main/java/com/thealgorithms/datastructures/bags/Bag.java
+++ b/src/main/java/com/thealgorithms/datastructures/bags/Bag.java
@@ -4,14 +4,18 @@
import java.util.NoSuchElementException;
/**
- * A collection that allows adding and iterating over elements but does not support element removal.
+ * A generic collection that allows adding and iterating over elements but does not support
+ * element removal. This class implements a simple bag data structure, which can hold duplicate
+ * elements and provides operations to check for membership and the size of the collection.
+ *
+ * Bag is not thread-safe and should not be accessed by multiple threads concurrently.
*
* @param the type of elements in this bag
*/
public class Bag implements Iterable {
- private Node firstElement; // First element in the bag
- private int size; // Number of elements in the bag
+ private Node firstElement; // Reference to the first element in the bag
+ private int size; // Count of elements in the bag
// Node class representing each element in the bag
private static final class Node {
@@ -21,6 +25,7 @@ private static final class Node {
/**
* Constructs an empty bag.
+ * This initializes the bag with zero elements.
*/
public Bag() {
firstElement = null;
@@ -30,7 +35,7 @@ public Bag() {
/**
* Checks if the bag is empty.
*
- * @return true if the bag is empty, false otherwise
+ * @return {@code true} if the bag contains no elements; {@code false} otherwise
*/
public boolean isEmpty() {
return size == 0;
@@ -39,7 +44,7 @@ public boolean isEmpty() {
/**
* Returns the number of elements in the bag.
*
- * @return the number of elements
+ * @return the number of elements currently in the bag
*/
public int size() {
return size;
@@ -48,7 +53,10 @@ public int size() {
/**
* Adds an element to the bag.
*
- * @param element the element to add
+ *
This method adds the specified element to the bag. Duplicates are allowed, and the
+ * bag will maintain the order in which elements are added.
+ *
+ * @param element the element to add; must not be {@code null}
*/
public void add(E element) {
Node newNode = new Node<>();
@@ -61,8 +69,10 @@ public void add(E element) {
/**
* Checks if the bag contains a specific element.
*
- * @param element the element to check for
- * @return true if the bag contains the element, false otherwise
+ * This method uses the {@code equals} method of the element to determine membership.
+ *
+ * @param element the element to check for; must not be {@code null}
+ * @return {@code true} if the bag contains the specified element; {@code false} otherwise
*/
public boolean contains(E element) {
for (E value : this) {
@@ -76,6 +86,8 @@ public boolean contains(E element) {
/**
* Returns an iterator over the elements in this bag.
*
+ *
The iterator provides a way to traverse the elements in the order they were added.
+ *
* @return an iterator that iterates over the elements in the bag
*/
@Override
@@ -88,19 +100,35 @@ private static class ListIterator implements Iterator {
private Node currentElement;
+ /**
+ * Constructs a ListIterator starting from the given first element.
+ *
+ * @param firstElement the first element of the bag to iterate over
+ */
ListIterator(Node firstElement) {
this.currentElement = firstElement;
}
+ /**
+ * Checks if there are more elements to iterate over.
+ *
+ * @return {@code true} if there are more elements; {@code false} otherwise
+ */
@Override
public boolean hasNext() {
return currentElement != null;
}
+ /**
+ * Returns the next element in the iteration.
+ *
+ * @return the next element in the bag
+ * @throws NoSuchElementException if there are no more elements to return
+ */
@Override
public E next() {
if (!hasNext()) {
- throw new NoSuchElementException();
+ throw new NoSuchElementException("No more elements in the bag.");
}
E element = currentElement.content;
currentElement = currentElement.nextElement;
diff --git a/src/main/java/com/thealgorithms/datastructures/bloomfilter/BloomFilter.java b/src/main/java/com/thealgorithms/datastructures/bloomfilter/BloomFilter.java
index 33ea22c3d271..90625ad1c902 100644
--- a/src/main/java/com/thealgorithms/datastructures/bloomfilter/BloomFilter.java
+++ b/src/main/java/com/thealgorithms/datastructures/bloomfilter/BloomFilter.java
@@ -1,12 +1,21 @@
package com.thealgorithms.datastructures.bloomfilter;
+import java.util.Arrays;
import java.util.BitSet;
/**
* A generic BloomFilter implementation for probabilistic membership checking.
+ *
+ * Bloom filters are space-efficient data structures that provide a fast way to
+ * test whether an
+ * element is a member of a set. They may produce false positives, indicating an
+ * element is
+ * in the set when it is not, but they will never produce false negatives.
+ *
*
* @param The type of elements to be stored in the Bloom filter.
*/
+@SuppressWarnings("rawtypes")
public class BloomFilter {
private final int numberOfHashFunctions;
@@ -14,13 +23,20 @@ public class BloomFilter {
private final Hash[] hashFunctions;
/**
- * Constructs a BloomFilter with a specified number of hash functions and bit array size.
+ * Constructs a BloomFilter with a specified number of hash functions and bit
+ * array size.
*
* @param numberOfHashFunctions the number of hash functions to use
- * @param bitArraySize the size of the bit array
+ * @param bitArraySize the size of the bit array, which determines the
+ * capacity of the filter
+ * @throws IllegalArgumentException if numberOfHashFunctions or bitArraySize is
+ * less than 1
*/
@SuppressWarnings("unchecked")
public BloomFilter(int numberOfHashFunctions, int bitArraySize) {
+ if (numberOfHashFunctions < 1 || bitArraySize < 1) {
+ throw new IllegalArgumentException("Number of hash functions and bit array size must be greater than 0");
+ }
this.numberOfHashFunctions = numberOfHashFunctions;
this.bitArray = new BitSet(bitArraySize);
this.hashFunctions = new Hash[numberOfHashFunctions];
@@ -28,7 +44,8 @@ public BloomFilter(int numberOfHashFunctions, int bitArraySize) {
}
/**
- * Initializes the hash functions with unique indices.
+ * Initializes the hash functions with unique indices to ensure different
+ * hashing.
*/
private void initializeHashFunctions() {
for (int i = 0; i < numberOfHashFunctions; i++) {
@@ -38,8 +55,13 @@ private void initializeHashFunctions() {
/**
* Inserts an element into the Bloom filter.
+ *
+ * This method hashes the element using all defined hash functions and sets the
+ * corresponding
+ * bits in the bit array.
+ *
*
- * @param key the element to insert
+ * @param key the element to insert into the Bloom filter
*/
public void insert(T key) {
for (Hash hash : hashFunctions) {
@@ -50,9 +72,17 @@ public void insert(T key) {
/**
* Checks if an element might be in the Bloom filter.
+ *
+ * This method checks the bits at the positions computed by each hash function.
+ * If any of these
+ * bits are not set, the element is definitely not in the filter. If all bits
+ * are set, the element
+ * might be in the filter.
+ *
*
- * @param key the element to check
- * @return {@code true} if the element might be in the Bloom filter, {@code false} if it is definitely not
+ * @param key the element to check for membership in the Bloom filter
+ * @return {@code true} if the element might be in the Bloom filter,
+ * {@code false} if it is definitely not
*/
public boolean contains(T key) {
for (Hash hash : hashFunctions) {
@@ -66,6 +96,10 @@ public boolean contains(T key) {
/**
* Inner class representing a hash function used by the Bloom filter.
+ *
+ * Each instance of this class represents a different hash function based on its
+ * index.
+ *
*
* @param The type of elements to be hashed.
*/
@@ -76,7 +110,7 @@ private static class Hash {
/**
* Constructs a Hash function with a specified index.
*
- * @param index the index of this hash function
+ * @param index the index of this hash function, used to create a unique hash
*/
Hash(int index) {
this.index = index;
@@ -84,19 +118,27 @@ private static class Hash {
/**
* Computes the hash of the given key.
+ *
+ * The hash value is calculated by multiplying the index of the hash function
+ * with the ASCII sum of the string representation of the key.
+ *
*
* @param key the element to hash
- * @return the hash value
+ * @return the computed hash value
*/
public int compute(T key) {
- return index * asciiString(String.valueOf(key));
+ return index * contentHash(key);
}
/**
* Computes the ASCII value sum of the characters in a string.
+ *
+ * This method iterates through each character of the string and accumulates
+ * their ASCII values to produce a single integer value.
+ *
*
* @param word the string to compute
- * @return the sum of ASCII values of the characters
+ * @return the sum of ASCII values of the characters in the string
*/
private int asciiString(String word) {
int sum = 0;
@@ -105,5 +147,31 @@ private int asciiString(String word) {
}
return sum;
}
+
+ /**
+ * Computes a content-based hash for arrays; falls back to ASCII-sum of String value otherwise.
+ */
+ private int contentHash(Object key) {
+ if (key instanceof int[]) {
+ return Arrays.hashCode((int[]) key);
+ } else if (key instanceof long[]) {
+ return Arrays.hashCode((long[]) key);
+ } else if (key instanceof byte[]) {
+ return Arrays.hashCode((byte[]) key);
+ } else if (key instanceof short[]) {
+ return Arrays.hashCode((short[]) key);
+ } else if (key instanceof char[]) {
+ return Arrays.hashCode((char[]) key);
+ } else if (key instanceof boolean[]) {
+ return Arrays.hashCode((boolean[]) key);
+ } else if (key instanceof float[]) {
+ return Arrays.hashCode((float[]) key);
+ } else if (key instanceof double[]) {
+ return Arrays.hashCode((double[]) key);
+ } else if (key instanceof Object[]) {
+ return Arrays.deepHashCode((Object[]) key);
+ }
+ return asciiString(String.valueOf(key));
+ }
}
}
diff --git a/src/main/java/com/thealgorithms/datastructures/buffers/CircularBuffer.java b/src/main/java/com/thealgorithms/datastructures/buffers/CircularBuffer.java
index 15e9a0956226..3b89c2119ae0 100644
--- a/src/main/java/com/thealgorithms/datastructures/buffers/CircularBuffer.java
+++ b/src/main/java/com/thealgorithms/datastructures/buffers/CircularBuffer.java
@@ -2,27 +2,63 @@
import java.util.concurrent.atomic.AtomicInteger;
+/**
+ * The {@code CircularBuffer} class implements a generic circular (or ring) buffer.
+ * A circular buffer is a fixed-size data structure that operates in a FIFO (First In, First Out) manner.
+ * The buffer allows you to overwrite old data when the buffer is full and efficiently use limited memory.
+ * When the buffer is full, adding a new item will overwrite the oldest data.
+ *
+ * @param - The type of elements stored in the circular buffer.
+ */
+@SuppressWarnings("unchecked")
public class CircularBuffer
- {
private final Item[] buffer;
private final CircularPointer putPointer;
private final CircularPointer getPointer;
private final AtomicInteger size = new AtomicInteger(0);
+ /**
+ * Constructor to initialize the circular buffer with a specified size.
+ *
+ * @param size The size of the circular buffer.
+ * @throws IllegalArgumentException if the size is zero or negative.
+ */
public CircularBuffer(int size) {
+ if (size <= 0) {
+ throw new IllegalArgumentException("Buffer size must be positive");
+ }
// noinspection unchecked
this.buffer = (Item[]) new Object[size];
this.putPointer = new CircularPointer(0, size);
this.getPointer = new CircularPointer(0, size);
}
+ /**
+ * Checks if the circular buffer is empty.
+ * This method is based on the current size of the buffer.
+ *
+ * @return {@code true} if the buffer is empty, {@code false} otherwise.
+ */
public boolean isEmpty() {
return size.get() == 0;
}
+ /**
+ * Checks if the circular buffer is full.
+ * The buffer is considered full when its size equals its capacity.
+ *
+ * @return {@code true} if the buffer is full, {@code false} otherwise.
+ */
public boolean isFull() {
return size.get() == buffer.length;
}
+ /**
+ * Retrieves and removes the item at the front of the buffer (FIFO).
+ * This operation will move the {@code getPointer} forward.
+ *
+ * @return The item at the front of the buffer, or {@code null} if the buffer is empty.
+ */
public Item get() {
if (isEmpty()) {
return null;
@@ -33,31 +69,64 @@ public Item get() {
return item;
}
+ /**
+ * Adds an item to the end of the buffer (FIFO).
+ * If the buffer is full, this operation will overwrite the oldest data.
+ *
+ * @param item The item to be added.
+ * @throws IllegalArgumentException if the item is null.
+ * @return {@code true} if the item was successfully added, {@code false} if the buffer was full and the item overwrote existing data.
+ */
public boolean put(Item item) {
+ if (item == null) {
+ throw new IllegalArgumentException("Null items are not allowed");
+ }
+
+ boolean wasEmpty = isEmpty();
if (isFull()) {
- return false;
+ getPointer.getAndIncrement(); // Move get pointer to discard oldest item
+ } else {
+ size.incrementAndGet();
}
buffer[putPointer.getAndIncrement()] = item;
- size.incrementAndGet();
- return true;
+ return wasEmpty;
}
+ /**
+ * The {@code CircularPointer} class is a helper class used to track the current index (pointer)
+ * in the circular buffer.
+ * The max value represents the capacity of the buffer.
+ * The `CircularPointer` class ensures that the pointer automatically wraps around to 0
+ * when it reaches the maximum index.
+ * This is achieved in the `getAndIncrement` method, where the pointer
+ * is incremented and then taken modulo the maximum value (`max`).
+ * This operation ensures that the pointer always stays within the bounds of the buffer.
+ */
private static class CircularPointer {
private int pointer;
private final int max;
+ /**
+ * Constructor to initialize the circular pointer.
+ *
+ * @param pointer The initial position of the pointer.
+ * @param max The maximum size (capacity) of the circular buffer.
+ */
CircularPointer(int pointer, int max) {
this.pointer = pointer;
this.max = max;
}
+ /**
+ * Increments the pointer by 1 and wraps it around to 0 if it reaches the maximum value.
+ * This ensures the pointer always stays within the buffer's bounds.
+ *
+ * @return The current pointer value before incrementing.
+ */
public int getAndIncrement() {
- if (pointer == max) {
- pointer = 0;
- }
int tmp = pointer;
- pointer++;
+ pointer = (pointer + 1) % max;
return tmp;
}
}
diff --git a/src/main/java/com/thealgorithms/datastructures/caches/FIFOCache.java b/src/main/java/com/thealgorithms/datastructures/caches/FIFOCache.java
new file mode 100644
index 000000000000..fa048434a187
--- /dev/null
+++ b/src/main/java/com/thealgorithms/datastructures/caches/FIFOCache.java
@@ -0,0 +1,549 @@
+package com.thealgorithms.datastructures.caches;
+
+import java.util.Iterator;
+import java.util.LinkedHashMap;
+import java.util.LinkedHashSet;
+import java.util.Map;
+import java.util.Set;
+import java.util.concurrent.atomic.AtomicInteger;
+import java.util.concurrent.locks.Lock;
+import java.util.concurrent.locks.ReentrantLock;
+import java.util.function.BiConsumer;
+
+/**
+ * A thread-safe generic cache implementation using the First-In-First-Out eviction policy.
+ *
+ * The cache holds a fixed number of entries, defined by its capacity. When the cache is full and a
+ * new entry is added, the oldest entry in the cache is selected and evicted to make space.
+ *
+ * Optionally, entries can have a time-to-live (TTL) in milliseconds. If a TTL is set, entries will
+ * automatically expire and be removed upon access or insertion attempts.
+ *
+ * Features:
+ *
+ * - Removes oldest entry when capacity is exceeded
+ * - Optional TTL (time-to-live in milliseconds) per entry or default TTL for all entries
+ * - Thread-safe access using locking
+ * - Hit and miss counters for cache statistics
+ * - Eviction listener callback support
+ *
+ *
+ * @param the type of keys maintained by this cache
+ * @param the type of mapped values
+ * See FIFO
+ * @author Kevin Babu (GitHub)
+ */
+public final class FIFOCache {
+
+ private final int capacity;
+ private final long defaultTTL;
+ private final Map> cache;
+ private final Lock lock;
+
+ private long hits = 0;
+ private long misses = 0;
+ private final BiConsumer evictionListener;
+ private final EvictionStrategy evictionStrategy;
+
+ /**
+ * Internal structure to store value + expiry timestamp.
+ *
+ * @param the type of the value being cached
+ */
+ private static class CacheEntry {
+ V value;
+ long expiryTime;
+
+ /**
+ * Constructs a new {@code CacheEntry} with the specified value and time-to-live (TTL).
+ * If TTL is 0, the entry is kept indefinitely, that is, unless it is the first value,
+ * then it will be removed according to the FIFO principle
+ *
+ * @param value the value to cache
+ * @param ttlMillis the time-to-live in milliseconds
+ */
+ CacheEntry(V value, long ttlMillis) {
+ this.value = value;
+ if (ttlMillis == 0) {
+ this.expiryTime = Long.MAX_VALUE;
+ } else {
+ this.expiryTime = System.currentTimeMillis() + ttlMillis;
+ }
+ }
+
+ /**
+ * Checks if the cache entry has expired.
+ *
+ * @return {@code true} if the current time is past the expiration time; {@code false} otherwise
+ */
+ boolean isExpired() {
+ return System.currentTimeMillis() > expiryTime;
+ }
+ }
+
+ /**
+ * Constructs a new {@code FIFOCache} instance using the provided {@link Builder}.
+ *
+ * This constructor initializes the cache with the specified capacity and default TTL,
+ * sets up internal data structures (a {@code LinkedHashMap} for cache entries and configures eviction.
+ *
+ * @param builder the {@code Builder} object containing configuration parameters
+ */
+ private FIFOCache(Builder builder) {
+ this.capacity = builder.capacity;
+ this.defaultTTL = builder.defaultTTL;
+ this.cache = new LinkedHashMap<>();
+ this.lock = new ReentrantLock();
+ this.evictionListener = builder.evictionListener;
+ this.evictionStrategy = builder.evictionStrategy;
+ }
+
+ /**
+ * Retrieves the value associated with the specified key from the cache.
+ *
+ * If the key is not present or the corresponding entry has expired, this method
+ * returns {@code null}. If an expired entry is found, it will be removed and the
+ * eviction listener (if any) will be notified. Cache hit-and-miss statistics are
+ * also updated accordingly.
+ *
+ * @param key the key whose associated value is to be returned; must not be {@code null}
+ * @return the cached value associated with the key, or {@code null} if not present or expired
+ * @throws IllegalArgumentException if {@code key} is {@code null}
+ */
+ public V get(K key) {
+ if (key == null) {
+ throw new IllegalArgumentException("Key must not be null");
+ }
+
+ lock.lock();
+ try {
+ evictionStrategy.onAccess(this);
+
+ CacheEntry entry = cache.get(key);
+ if (entry == null || entry.isExpired()) {
+ if (entry != null) {
+ cache.remove(key);
+ notifyEviction(key, entry.value);
+ }
+ misses++;
+ return null;
+ }
+ hits++;
+ return entry.value;
+ } finally {
+ lock.unlock();
+ }
+ }
+
+ /**
+ * Adds a key-value pair to the cache using the default time-to-live (TTL).
+ *
+ * The key may overwrite an existing entry. The actual insertion is delegated
+ * to the overloaded {@link #put(K, V, long)} method.
+ *
+ * @param key the key to cache the value under
+ * @param value the value to be cached
+ */
+ public void put(K key, V value) {
+ put(key, value, defaultTTL);
+ }
+
+ /**
+ * Adds a key-value pair to the cache with a specified time-to-live (TTL).
+ *
+ *
If the key already exists, its value is removed, re-inserted at tail and its TTL is reset.
+ * If the key does not exist and the cache is full, the oldest entry is evicted to make space.
+ * Expired entries are also cleaned up prior to any eviction. The eviction listener
+ * is notified when an entry gets evicted.
+ *
+ * @param key the key to associate with the cached value; must not be {@code null}
+ * @param value the value to be cached; must not be {@code null}
+ * @param ttlMillis the time-to-live for this entry in milliseconds; must be >= 0
+ * @throws IllegalArgumentException if {@code key} or {@code value} is {@code null}, or if {@code ttlMillis} is negative
+ */
+ public void put(K key, V value, long ttlMillis) {
+ if (key == null || value == null) {
+ throw new IllegalArgumentException("Key and value must not be null");
+ }
+ if (ttlMillis < 0) {
+ throw new IllegalArgumentException("TTL must be >= 0");
+ }
+
+ lock.lock();
+ try {
+ // If key already exists, remove it
+ CacheEntry oldEntry = cache.remove(key);
+ if (oldEntry != null && !oldEntry.isExpired()) {
+ notifyEviction(key, oldEntry.value);
+ }
+
+ // Evict expired entries to make space for new entry
+ evictExpired();
+
+ // If no expired entry was removed, remove the oldest
+ if (cache.size() >= capacity) {
+ Iterator>> it = cache.entrySet().iterator();
+ if (it.hasNext()) {
+ Map.Entry> eldest = it.next();
+ it.remove();
+ notifyEviction(eldest.getKey(), eldest.getValue().value);
+ }
+ }
+
+ // Insert new entry at tail
+ cache.put(key, new CacheEntry<>(value, ttlMillis));
+ } finally {
+ lock.unlock();
+ }
+ }
+
+ /**
+ * Removes all expired entries from the cache.
+ *
+ * This method iterates through the list of cached keys and checks each associated
+ * entry for expiration. Expired entries are removed the cache map. For each eviction,
+ * the eviction listener is notified.
+ */
+ private int evictExpired() {
+ int count = 0;
+ Iterator>> it = cache.entrySet().iterator();
+
+ while (it.hasNext()) {
+ Map.Entry> entry = it.next();
+ if (entry != null && entry.getValue().isExpired()) {
+ it.remove();
+ notifyEviction(entry.getKey(), entry.getValue().value);
+ count++;
+ }
+ }
+
+ return count;
+ }
+
+ /**
+ * Removes the specified key and its associated entry from the cache.
+ *
+ * @param key the key to remove from the cache;
+ * @return the value associated with the key; or {@code null} if no such key exists
+ */
+ public V removeKey(K key) {
+ if (key == null) {
+ throw new IllegalArgumentException("Key cannot be null");
+ }
+ CacheEntry entry = cache.remove(key);
+
+ // No such key in cache
+ if (entry == null) {
+ return null;
+ }
+
+ notifyEviction(key, entry.value);
+ return entry.value;
+ }
+
+ /**
+ * Notifies the eviction listener, if one is registered, that a key-value pair has been evicted.
+ *
+ * If the {@code evictionListener} is not {@code null}, it is invoked with the provided key
+ * and value. Any exceptions thrown by the listener are caught and logged to standard error,
+ * preventing them from disrupting cache operations.
+ *
+ * @param key the key that was evicted
+ * @param value the value that was associated with the evicted key
+ */
+ private void notifyEviction(K key, V value) {
+ if (evictionListener != null) {
+ try {
+ evictionListener.accept(key, value);
+ } catch (Exception e) {
+ System.err.println("Eviction listener failed: " + e.getMessage());
+ }
+ }
+ }
+
+ /**
+ * Returns the number of successful cache lookups (hits).
+ *
+ * @return the number of cache hits
+ */
+ public long getHits() {
+ lock.lock();
+ try {
+ return hits;
+ } finally {
+ lock.unlock();
+ }
+ }
+
+ /**
+ * Returns the number of failed cache lookups (misses), including expired entries.
+ *
+ * @return the number of cache misses
+ */
+ public long getMisses() {
+ lock.lock();
+ try {
+ return misses;
+ } finally {
+ lock.unlock();
+ }
+ }
+
+ /**
+ * Returns the current number of entries in the cache, excluding expired ones.
+ *
+ * @return the current cache size
+ */
+ public int size() {
+ lock.lock();
+ try {
+ evictionStrategy.onAccess(this);
+
+ int count = 0;
+ for (CacheEntry entry : cache.values()) {
+ if (!entry.isExpired()) {
+ ++count;
+ }
+ }
+ return count;
+ } finally {
+ lock.unlock();
+ }
+ }
+
+ /**
+ * Removes all entries from the cache, regardless of their expiration status.
+ *
+ * This method clears the internal cache map entirely, resets the hit-and-miss counters,
+ * and notifies the eviction listener (if any) for each removed entry.
+ * Note that expired entries are treated the same as active ones for the purpose of clearing.
+ *
+ *
This operation acquires the internal lock to ensure thread safety.
+ */
+ public void clear() {
+ lock.lock();
+ try {
+ for (Map.Entry> entry : cache.entrySet()) {
+ notifyEviction(entry.getKey(), entry.getValue().value);
+ }
+ cache.clear();
+ hits = 0;
+ misses = 0;
+ } finally {
+ lock.unlock();
+ }
+ }
+
+ /**
+ * Returns a set of all keys currently stored in the cache that have not expired.
+ *
+ * This method iterates through the cache and collects the keys of all non-expired entries.
+ * Expired entries are ignored but not removed. If you want to ensure expired entries are cleaned up,
+ * consider invoking {@link EvictionStrategy#onAccess(FIFOCache)} or calling {@link #evictExpired()} manually.
+ *
+ *
This operation acquires the internal lock to ensure thread safety.
+ *
+ * @return a set containing all non-expired keys currently in the cache
+ */
+ public Set getAllKeys() {
+ lock.lock();
+ try {
+ Set keys = new LinkedHashSet<>();
+
+ for (Map.Entry> entry : cache.entrySet()) {
+ if (!entry.getValue().isExpired()) {
+ keys.add(entry.getKey());
+ }
+ }
+
+ return keys;
+ } finally {
+ lock.unlock();
+ }
+ }
+
+ /**
+ * Returns the current {@link EvictionStrategy} used by this cache instance.
+
+ * @return the eviction strategy currently assigned to this cache
+ */
+ public EvictionStrategy getEvictionStrategy() {
+ return evictionStrategy;
+ }
+
+ /**
+ * Returns a string representation of the cache, including metadata and current non-expired entries.
+ *
+ * The returned string includes the cache's capacity, current size (excluding expired entries),
+ * hit-and-miss counts, and a map of all non-expired key-value pairs. This method acquires a lock
+ * to ensure thread-safe access.
+ *
+ * @return a string summarizing the state of the cache
+ */
+ @Override
+ public String toString() {
+ lock.lock();
+ try {
+ Map visible = new LinkedHashMap<>();
+ for (Map.Entry> entry : cache.entrySet()) {
+ if (!entry.getValue().isExpired()) {
+ visible.put(entry.getKey(), entry.getValue().value);
+ }
+ }
+ return String.format("Cache(capacity=%d, size=%d, hits=%d, misses=%d, entries=%s)", capacity, visible.size(), hits, misses, visible);
+ } finally {
+ lock.unlock();
+ }
+ }
+
+ /**
+ * A strategy interface for controlling when expired entries are evicted from the cache.
+ *
+ * Implementations decide whether and when to trigger {@link FIFOCache#evictExpired()} based
+ * on cache usage patterns. This allows for flexible eviction behaviour such as periodic cleanup,
+ * or no automatic cleanup.
+ *
+ * @param the type of keys maintained by the cache
+ * @param the type of cached values
+ */
+ public interface EvictionStrategy {
+ /**
+ * Called on each cache access (e.g., {@link FIFOCache#get(Object)}) to optionally trigger eviction.
+ *
+ * @param cache the cache instance on which this strategy is applied
+ * @return the number of expired entries evicted during this access
+ */
+ int onAccess(FIFOCache cache);
+ }
+
+ /**
+ * An eviction strategy that performs eviction of expired entries on each call.
+ *
+ * @param the type of keys
+ * @param the type of values
+ */
+ public static class ImmediateEvictionStrategy implements EvictionStrategy {
+ @Override
+ public int onAccess(FIFOCache cache) {
+ return cache.evictExpired();
+ }
+ }
+
+ /**
+ * An eviction strategy that triggers eviction on every fixed number of accesses.
+ *
+ * This deterministic strategy ensures cleanup occurs at predictable intervals,
+ * ideal for moderately active caches where memory usage is a concern.
+ *
+ * @param the type of keys
+ * @param the type of values
+ */
+ public static class PeriodicEvictionStrategy implements EvictionStrategy {
+ private final int interval;
+ private final AtomicInteger counter = new AtomicInteger();
+
+ /**
+ * Constructs a periodic eviction strategy.
+ *
+ * @param interval the number of accesses between evictions; must be > 0
+ * @throws IllegalArgumentException if {@code interval} is less than or equal to 0
+ */
+ public PeriodicEvictionStrategy(int interval) {
+ if (interval <= 0) {
+ throw new IllegalArgumentException("Interval must be > 0");
+ }
+ this.interval = interval;
+ }
+
+ @Override
+ public int onAccess(FIFOCache cache) {
+ if (counter.incrementAndGet() % interval == 0) {
+ return cache.evictExpired();
+ }
+
+ return 0;
+ }
+ }
+
+ /**
+ * A builder for constructing a {@link FIFOCache} instance with customizable settings.
+ *
+ * Allows configuring capacity, default TTL, eviction listener, and a pluggable eviction
+ * strategy. Call {@link #build()} to create the configured cache instance.
+ *
+ * @param the type of keys maintained by the cache
+ * @param the type of values stored in the cache
+ */
+ public static class Builder {
+ private final int capacity;
+ private long defaultTTL = 0;
+ private BiConsumer evictionListener;
+ private EvictionStrategy evictionStrategy = new FIFOCache.ImmediateEvictionStrategy<>();
+ /**
+ * Creates a new {@code Builder} with the specified cache capacity.
+ *
+ * @param capacity the maximum number of entries the cache can hold; must be > 0
+ * @throws IllegalArgumentException if {@code capacity} is less than or equal to 0
+ */
+ public Builder(int capacity) {
+ if (capacity <= 0) {
+ throw new IllegalArgumentException("Capacity must be > 0");
+ }
+ this.capacity = capacity;
+ }
+
+ /**
+ * Sets the default time-to-live (TTL) in milliseconds for cache entries.
+ *
+ * @param ttlMillis the TTL duration in milliseconds; must be >= 0
+ * @return this builder instance for chaining
+ * @throws IllegalArgumentException if {@code ttlMillis} is negative
+ */
+ public Builder defaultTTL(long ttlMillis) {
+ if (ttlMillis < 0) {
+ throw new IllegalArgumentException("Default TTL must be >= 0");
+ }
+ this.defaultTTL = ttlMillis;
+ return this;
+ }
+
+ /**
+ * Sets an eviction listener to be notified when entries are evicted from the cache.
+ *
+ * @param listener a {@link BiConsumer} that accepts evicted keys and values; must not be {@code null}
+ * @return this builder instance for chaining
+ * @throws IllegalArgumentException if {@code listener} is {@code null}
+ */
+ public Builder evictionListener(BiConsumer listener) {
+ if (listener == null) {
+ throw new IllegalArgumentException("Listener must not be null");
+ }
+ this.evictionListener = listener;
+ return this;
+ }
+
+ /**
+ * Builds and returns a new {@link FIFOCache} instance with the configured parameters.
+ *
+ * @return a fully configured {@code FIFOCache} instance
+ */
+ public FIFOCache build() {
+ return new FIFOCache<>(this);
+ }
+
+ /**
+ * Sets the eviction strategy used to determine when to clean up expired entries.
+ *
+ * @param strategy an {@link EvictionStrategy} implementation; must not be {@code null}
+ * @return this builder instance
+ * @throws IllegalArgumentException if {@code strategy} is {@code null}
+ */
+ public Builder evictionStrategy(EvictionStrategy strategy) {
+ if (strategy == null) {
+ throw new IllegalArgumentException("Eviction strategy must not be null");
+ }
+ this.evictionStrategy = strategy;
+ return this;
+ }
+ }
+}
diff --git a/src/main/java/com/thealgorithms/datastructures/caches/LFUCache.java b/src/main/java/com/thealgorithms/datastructures/caches/LFUCache.java
index a5b83af14551..bf2b928ec33c 100644
--- a/src/main/java/com/thealgorithms/datastructures/caches/LFUCache.java
+++ b/src/main/java/com/thealgorithms/datastructures/caches/LFUCache.java
@@ -4,11 +4,32 @@
import java.util.Map;
/**
- * Java program for LFU Cache (https://en.wikipedia.org/wiki/Least_frequently_used)
+ * The {@code LFUCache} class implements a Least Frequently Used (LFU) cache.
+ * An LFU cache evicts the least frequently used item when the cache reaches its capacity.
+ * It maintains a mapping of keys to nodes, where each node contains the key, its associated value,
+ * and a frequency count that tracks how many times the item has been accessed. A doubly linked list
+ * is used to efficiently manage the ordering of items based on their usage frequency.
+ *
+ * This implementation is designed to provide O(1) time complexity for both the {@code get} and
+ * {@code put} operations, which is achieved through the use of a hashmap for quick access and a
+ * doubly linked list for maintaining the order of item frequencies.
+ *
+ *
+ * Reference: LFU Cache - Wikipedia
+ *
+ *
+ * @param The type of keys maintained by this cache.
+ * @param The type of mapped values.
+ *
* @author Akshay Dubey (https://github.com/itsAkshayDubey)
*/
public class LFUCache {
+ /**
+ * The {@code Node} class represents an element in the LFU cache.
+ * Each node contains a key, a value, and a frequency count.
+ * It also has pointers to the previous and next nodes in the doubly linked list.
+ */
private class Node {
private final K key;
private V value;
@@ -16,6 +37,13 @@ private class Node {
private Node previous;
private Node next;
+ /**
+ * Constructs a new {@code Node} with the specified key, value, and frequency.
+ *
+ * @param key The key associated with this node.
+ * @param value The value stored in this node.
+ * @param frequency The frequency of usage of this node.
+ */
Node(K key, V value, int frequency) {
this.key = key;
this.value = value;
@@ -29,10 +57,19 @@ private class Node {
private final int capacity;
private static final int DEFAULT_CAPACITY = 100;
+ /**
+ * Constructs an LFU cache with the default capacity.
+ */
public LFUCache() {
this(DEFAULT_CAPACITY);
}
+ /**
+ * Constructs an LFU cache with the specified capacity.
+ *
+ * @param capacity The maximum number of items that the cache can hold.
+ * @throws IllegalArgumentException if the specified capacity is less than or equal to zero.
+ */
public LFUCache(int capacity) {
if (capacity <= 0) {
throw new IllegalArgumentException("Capacity must be greater than zero.");
@@ -42,10 +79,12 @@ public LFUCache(int capacity) {
}
/**
- * Retrieves the value for the given key from the cache. Increases the frequency of the node.
+ * Retrieves the value associated with the given key from the cache.
+ * If the key exists, the node's frequency is incremented, and the node is repositioned
+ * in the linked list based on its updated frequency.
*
- * @param key The key to look up.
- * @return The value associated with the key, or null if the key is not present.
+ * @param key The key whose associated value is to be returned.
+ * @return The value associated with the key, or {@code null} if the key is not present in the cache.
*/
public V get(K key) {
Node node = cache.get(key);
@@ -59,10 +98,12 @@ public V get(K key) {
}
/**
- * Adds or updates a key-value pair in the cache. If the cache is full, the least frequently used item is evicted.
+ * Inserts or updates a key-value pair in the cache.
+ * If the key already exists, the value is updated and its frequency is incremented.
+ * If the cache is full, the least frequently used item is removed before inserting the new item.
*
- * @param key The key to insert or update.
- * @param value The value to insert or update.
+ * @param key The key associated with the value to be inserted or updated.
+ * @param value The value to be inserted or updated.
*/
public void put(K key, V value) {
if (cache.containsKey(key)) {
@@ -73,7 +114,7 @@ public void put(K key, V value) {
addNodeWithUpdatedFrequency(node);
} else {
if (cache.size() >= capacity) {
- cache.remove(this.head.key);
+ cache.remove(this.head.key); // Evict least frequently used item
removeNode(head);
}
Node node = new Node(key, value, 1);
@@ -84,13 +125,14 @@ public void put(K key, V value) {
/**
* Adds a node to the linked list in the correct position based on its frequency.
+ * The linked list is ordered by frequency, with the least frequently used node at the head.
*
- * @param node The node to add.
+ * @param node The node to be inserted into the list.
*/
private void addNodeWithUpdatedFrequency(Node node) {
if (tail != null && head != null) {
Node temp = this.head;
- while (temp != null) {
+ while (true) {
if (temp.frequency > node.frequency) {
if (temp == head) {
node.next = temp;
@@ -122,9 +164,10 @@ private void addNodeWithUpdatedFrequency(Node node) {
}
/**
- * Removes a node from the linked list.
+ * Removes a node from the doubly linked list.
+ * This method ensures that the pointers of neighboring nodes are properly updated.
*
- * @param node The node to remove.
+ * @param node The node to be removed from the list.
*/
private void removeNode(Node node) {
if (node.previous != null) {
diff --git a/src/main/java/com/thealgorithms/datastructures/caches/LIFOCache.java b/src/main/java/com/thealgorithms/datastructures/caches/LIFOCache.java
new file mode 100644
index 000000000000..df3d4da912fe
--- /dev/null
+++ b/src/main/java/com/thealgorithms/datastructures/caches/LIFOCache.java
@@ -0,0 +1,563 @@
+package com.thealgorithms.datastructures.caches;
+
+import java.util.ArrayDeque;
+import java.util.Deque;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.Iterator;
+import java.util.LinkedHashMap;
+import java.util.Map;
+import java.util.Set;
+import java.util.concurrent.atomic.AtomicInteger;
+import java.util.concurrent.locks.Lock;
+import java.util.concurrent.locks.ReentrantLock;
+import java.util.function.BiConsumer;
+
+/**
+ * A thread-safe generic cache implementation using the Last-In-First-Out eviction policy.
+ *
+ * The cache holds a fixed number of entries, defined by its capacity. When the cache is full and a
+ * new entry is added, the youngest entry in the cache is selected and evicted to make space.
+ *
+ * Optionally, entries can have a time-to-live (TTL) in milliseconds. If a TTL is set, entries will
+ * automatically expire and be removed upon access or insertion attempts.
+ *
+ * Features:
+ *
+ * - Removes youngest entry when capacity is exceeded
+ * - Optional TTL (time-to-live in milliseconds) per entry or default TTL for all entries
+ * - Thread-safe access using locking
+ * - Hit and miss counters for cache statistics
+ * - Eviction listener callback support
+ *
+ *
+ * @param the type of keys maintained by this cache
+ * @param the type of mapped values
+ * See LIFO
+ * @author Kevin Babu (GitHub)
+ */
+public final class LIFOCache {
+
+ private final int capacity;
+ private final long defaultTTL;
+ private final Map> cache;
+ private final Lock lock;
+ private final Deque keys;
+ private long hits = 0;
+ private long misses = 0;
+ private final BiConsumer evictionListener;
+ private final EvictionStrategy evictionStrategy;
+
+ /**
+ * Internal structure to store value + expiry timestamp.
+ *
+ * @param the type of the value being cached
+ */
+ private static class CacheEntry {
+ V value;
+ long expiryTime;
+
+ /**
+ * Constructs a new {@code CacheEntry} with the specified value and time-to-live (TTL).
+ * If TTL is 0, the entry is kept indefinitely, that is, unless it is the first value,
+ * then it will be removed according to the LIFO principle
+ *
+ * @param value the value to cache
+ * @param ttlMillis the time-to-live in milliseconds
+ */
+ CacheEntry(V value, long ttlMillis) {
+ this.value = value;
+ if (ttlMillis == 0) {
+ this.expiryTime = Long.MAX_VALUE;
+ } else {
+ this.expiryTime = System.currentTimeMillis() + ttlMillis;
+ }
+ }
+
+ /**
+ * Checks if the cache entry has expired.
+ *
+ * @return {@code true} if the current time is past the expiration time; {@code false} otherwise
+ */
+ boolean isExpired() {
+ return System.currentTimeMillis() > expiryTime;
+ }
+ }
+
+ /**
+ * Constructs a new {@code LIFOCache} instance using the provided {@link Builder}.
+ *
+ * This constructor initializes the cache with the specified capacity and default TTL,
+ * sets up internal data structures (a {@code HashMap} for cache entries,
+ * {an @code ArrayDeque}, for key storage, and configures eviction.
+ *
+ * @param builder the {@code Builder} object containing configuration parameters
+ */
+ private LIFOCache(Builder builder) {
+ this.capacity = builder.capacity;
+ this.defaultTTL = builder.defaultTTL;
+ this.cache = new HashMap<>(builder.capacity);
+ this.keys = new ArrayDeque<>(builder.capacity);
+ this.lock = new ReentrantLock();
+ this.evictionListener = builder.evictionListener;
+ this.evictionStrategy = builder.evictionStrategy;
+ }
+
+ /**
+ * Retrieves the value associated with the specified key from the cache.
+ *
+ * If the key is not present or the corresponding entry has expired, this method
+ * returns {@code null}. If an expired entry is found, it will be removed and the
+ * eviction listener (if any) will be notified. Cache hit-and-miss statistics are
+ * also updated accordingly.
+ *
+ * @param key the key whose associated value is to be returned; must not be {@code null}
+ * @return the cached value associated with the key, or {@code null} if not present or expired
+ * @throws IllegalArgumentException if {@code key} is {@code null}
+ */
+ public V get(K key) {
+ if (key == null) {
+ throw new IllegalArgumentException("Key must not be null");
+ }
+
+ lock.lock();
+ try {
+ evictionStrategy.onAccess(this);
+
+ final CacheEntry entry = cache.get(key);
+ if (entry == null || entry.isExpired()) {
+ if (entry != null) {
+ cache.remove(key);
+ keys.remove(key);
+ notifyEviction(key, entry.value);
+ }
+ misses++;
+ return null;
+ }
+ hits++;
+ return entry.value;
+ } finally {
+ lock.unlock();
+ }
+ }
+
+ /**
+ * Adds a key-value pair to the cache using the default time-to-live (TTL).
+ *
+ * The key may overwrite an existing entry. The actual insertion is delegated
+ * to the overloaded {@link #put(K, V, long)} method.
+ *
+ * @param key the key to cache the value under
+ * @param value the value to be cached
+ */
+ public void put(K key, V value) {
+ put(key, value, defaultTTL);
+ }
+
+ /**
+ * Adds a key-value pair to the cache with a specified time-to-live (TTL).
+ *
+ *
If the key already exists, its value is removed, re-inserted at tail and its TTL is reset.
+ * If the key does not exist and the cache is full, the youngest entry is evicted to make space.
+ * Expired entries are also cleaned up prior to any eviction. The eviction listener
+ * is notified when an entry gets evicted.
+ *
+ * @param key the key to associate with the cached value; must not be {@code null}
+ * @param value the value to be cached; must not be {@code null}
+ * @param ttlMillis the time-to-live for this entry in milliseconds; must be >= 0
+ * @throws IllegalArgumentException if {@code key} or {@code value} is {@code null}, or if {@code ttlMillis} is negative
+ */
+ public void put(K key, V value, long ttlMillis) {
+ if (key == null || value == null) {
+ throw new IllegalArgumentException("Key and value must not be null");
+ }
+ if (ttlMillis < 0) {
+ throw new IllegalArgumentException("TTL must be >= 0");
+ }
+
+ lock.lock();
+ try {
+ // If key already exists, remove it. It will later be re-inserted at top of stack
+ keys.remove(key);
+ final CacheEntry oldEntry = cache.remove(key);
+ if (oldEntry != null && !oldEntry.isExpired()) {
+ notifyEviction(key, oldEntry.value);
+ }
+
+ // Evict expired entries to make space for new entry
+ evictExpired();
+
+ // If no expired entry was removed, remove the youngest
+ if (cache.size() >= capacity) {
+ final K youngestKey = keys.pollLast();
+ final CacheEntry youngestEntry = cache.remove(youngestKey);
+ notifyEviction(youngestKey, youngestEntry.value);
+ }
+
+ // Insert new entry at tail
+ keys.add(key);
+ cache.put(key, new CacheEntry<>(value, ttlMillis));
+ } finally {
+ lock.unlock();
+ }
+ }
+
+ /**
+ * Removes all expired entries from the cache.
+ *
+ * This method iterates through the list of cached keys and checks each associated
+ * entry for expiration. Expired entries are removed the cache map. For each eviction,
+ * the eviction listener is notified.
+ */
+ private int evictExpired() {
+ int count = 0;
+ final Iterator it = keys.iterator();
+
+ while (it.hasNext()) {
+ final K k = it.next();
+ final CacheEntry entry = cache.get(k);
+ if (entry != null && entry.isExpired()) {
+ it.remove();
+ cache.remove(k);
+ notifyEviction(k, entry.value);
+ count++;
+ }
+ }
+
+ return count;
+ }
+
+ /**
+ * Removes the specified key and its associated entry from the cache.
+ *
+ * @param key the key to remove from the cache;
+ * @return the value associated with the key; or {@code null} if no such key exists
+ */
+ public V removeKey(K key) {
+ if (key == null) {
+ throw new IllegalArgumentException("Key cannot be null");
+ }
+ lock.lock();
+ try {
+ final CacheEntry entry = cache.remove(key);
+ keys.remove(key);
+
+ // No such key in cache
+ if (entry == null) {
+ return null;
+ }
+
+ notifyEviction(key, entry.value);
+ return entry.value;
+ } finally {
+ lock.unlock();
+ }
+ }
+
+ /**
+ * Notifies the eviction listener, if one is registered, that a key-value pair has been evicted.
+ *
+ * If the {@code evictionListener} is not {@code null}, it is invoked with the provided key
+ * and value. Any exceptions thrown by the listener are caught and logged to standard error,
+ * preventing them from disrupting cache operations.
+ *
+ * @param key the key that was evicted
+ * @param value the value that was associated with the evicted key
+ */
+ private void notifyEviction(K key, V value) {
+ if (evictionListener != null) {
+ try {
+ evictionListener.accept(key, value);
+ } catch (Exception e) {
+ System.err.println("Eviction listener failed: " + e.getMessage());
+ }
+ }
+ }
+
+ /**
+ * Returns the number of successful cache lookups (hits).
+ *
+ * @return the number of cache hits
+ */
+ public long getHits() {
+ lock.lock();
+ try {
+ return hits;
+ } finally {
+ lock.unlock();
+ }
+ }
+
+ /**
+ * Returns the number of failed cache lookups (misses), including expired entries.
+ *
+ * @return the number of cache misses
+ */
+ public long getMisses() {
+ lock.lock();
+ try {
+ return misses;
+ } finally {
+ lock.unlock();
+ }
+ }
+
+ /**
+ * Returns the current number of entries in the cache, excluding expired ones.
+ *
+ * @return the current cache size
+ */
+ public int size() {
+ lock.lock();
+ try {
+ evictionStrategy.onAccess(this);
+
+ int count = 0;
+ for (CacheEntry entry : cache.values()) {
+ if (!entry.isExpired()) {
+ ++count;
+ }
+ }
+ return count;
+ } finally {
+ lock.unlock();
+ }
+ }
+
+ /**
+ * Removes all entries from the cache, regardless of their expiration status.
+ *
+ * This method clears the internal cache map entirely, resets the hit-and-miss counters,
+ * and notifies the eviction listener (if any) for each removed entry.
+ * Note that expired entries are treated the same as active ones for the purpose of clearing.
+ *
+ *
This operation acquires the internal lock to ensure thread safety.
+ */
+ public void clear() {
+ lock.lock();
+ try {
+ for (Map.Entry> entry : cache.entrySet()) {
+ notifyEviction(entry.getKey(), entry.getValue().value);
+ }
+ keys.clear();
+ cache.clear();
+ hits = 0;
+ misses = 0;
+ } finally {
+ lock.unlock();
+ }
+ }
+
+ /**
+ * Returns a set of all keys currently stored in the cache that have not expired.
+ *
+ * This method iterates through the cache and collects the keys of all non-expired entries.
+ * Expired entries are ignored but not removed. If you want to ensure expired entries are cleaned up,
+ * consider invoking {@link EvictionStrategy#onAccess(LIFOCache)} or calling {@link #evictExpired()} manually.
+ *
+ *
This operation acquires the internal lock to ensure thread safety.
+ *
+ * @return a set containing all non-expired keys currently in the cache
+ */
+ public Set getAllKeys() {
+ lock.lock();
+ try {
+ final Set result = new HashSet<>();
+
+ for (Map.Entry> entry : cache.entrySet()) {
+ if (!entry.getValue().isExpired()) {
+ result.add(entry.getKey());
+ }
+ }
+
+ return result;
+ } finally {
+ lock.unlock();
+ }
+ }
+
+ /**
+ * Returns the current {@link EvictionStrategy} used by this cache instance.
+
+ * @return the eviction strategy currently assigned to this cache
+ */
+ public EvictionStrategy getEvictionStrategy() {
+ return evictionStrategy;
+ }
+
+ /**
+ * Returns a string representation of the cache, including metadata and current non-expired entries.
+ *
+ * The returned string includes the cache's capacity, current size (excluding expired entries),
+ * hit-and-miss counts, and a map of all non-expired key-value pairs. This method acquires a lock
+ * to ensure thread-safe access.
+ *
+ * @return a string summarizing the state of the cache
+ */
+ @Override
+ public String toString() {
+ lock.lock();
+ try {
+ final Map visible = new LinkedHashMap<>();
+ for (Map.Entry> entry : cache.entrySet()) {
+ if (!entry.getValue().isExpired()) {
+ visible.put(entry.getKey(), entry.getValue().value);
+ }
+ }
+ return String.format("Cache(capacity=%d, size=%d, hits=%d, misses=%d, entries=%s)", capacity, visible.size(), hits, misses, visible);
+ } finally {
+ lock.unlock();
+ }
+ }
+
+ /**
+ * A strategy interface for controlling when expired entries are evicted from the cache.
+ *
+ * Implementations decide whether and when to trigger {@link LIFOCache#evictExpired()} based
+ * on cache usage patterns. This allows for flexible eviction behaviour such as periodic cleanup,
+ * or no automatic cleanup.
+ *
+ * @param the type of keys maintained by the cache
+ * @param the type of cached values
+ */
+ public interface EvictionStrategy {
+ /**
+ * Called on each cache access (e.g., {@link LIFOCache#get(Object)}) to optionally trigger eviction.
+ *
+ * @param cache the cache instance on which this strategy is applied
+ * @return the number of expired entries evicted during this access
+ */
+ int onAccess(LIFOCache cache);
+ }
+
+ /**
+ * An eviction strategy that performs eviction of expired entries on each call.
+ *
+ * @param the type of keys
+ * @param the type of values
+ */
+ public static class ImmediateEvictionStrategy implements EvictionStrategy {
+ @Override
+ public int onAccess(LIFOCache cache) {
+ return cache.evictExpired();
+ }
+ }
+
+ /**
+ * An eviction strategy that triggers eviction on every fixed number of accesses.
+ *
+ * This deterministic strategy ensures cleanup occurs at predictable intervals,
+ * ideal for moderately active caches where memory usage is a concern.
+ *
+ * @param the type of keys
+ * @param the type of values
+ */
+ public static class PeriodicEvictionStrategy implements EvictionStrategy {
+ private final int interval;
+ private final AtomicInteger counter = new AtomicInteger();
+
+ /**
+ * Constructs a periodic eviction strategy.
+ *
+ * @param interval the number of accesses between evictions; must be > 0
+ * @throws IllegalArgumentException if {@code interval} is less than or equal to 0
+ */
+ public PeriodicEvictionStrategy(int interval) {
+ if (interval <= 0) {
+ throw new IllegalArgumentException("Interval must be > 0");
+ }
+ this.interval = interval;
+ }
+
+ @Override
+ public int onAccess(LIFOCache cache) {
+ if (counter.incrementAndGet() % interval == 0) {
+ return cache.evictExpired();
+ }
+
+ return 0;
+ }
+ }
+
+ /**
+ * A builder for constructing a {@link LIFOCache} instance with customizable settings.
+ *
+ * Allows configuring capacity, default TTL, eviction listener, and a pluggable eviction
+ * strategy. Call {@link #build()} to create the configured cache instance.
+ *
+ * @param the type of keys maintained by the cache
+ * @param the type of values stored in the cache
+ */
+ public static class Builder {
+ private final int capacity;
+ private long defaultTTL = 0;
+ private BiConsumer evictionListener;
+ private EvictionStrategy evictionStrategy = new LIFOCache.ImmediateEvictionStrategy<>();
+ /**
+ * Creates a new {@code Builder} with the specified cache capacity.
+ *
+ * @param capacity the maximum number of entries the cache can hold; must be > 0
+ * @throws IllegalArgumentException if {@code capacity} is less than or equal to 0
+ */
+ public Builder(int capacity) {
+ if (capacity <= 0) {
+ throw new IllegalArgumentException("Capacity must be > 0");
+ }
+ this.capacity = capacity;
+ }
+
+ /**
+ * Sets the default time-to-live (TTL) in milliseconds for cache entries.
+ *
+ * @param ttlMillis the TTL duration in milliseconds; must be >= 0
+ * @return this builder instance for chaining
+ * @throws IllegalArgumentException if {@code ttlMillis} is negative
+ */
+ public Builder defaultTTL(long ttlMillis) {
+ if (ttlMillis < 0) {
+ throw new IllegalArgumentException("Default TTL must be >= 0");
+ }
+ this.defaultTTL = ttlMillis;
+ return this;
+ }
+
+ /**
+ * Sets an eviction listener to be notified when entries are evicted from the cache.
+ *
+ * @param listener a {@link BiConsumer} that accepts evicted keys and values; must not be {@code null}
+ * @return this builder instance for chaining
+ * @throws IllegalArgumentException if {@code listener} is {@code null}
+ */
+ public Builder evictionListener(BiConsumer listener) {
+ if (listener == null) {
+ throw new IllegalArgumentException("Listener must not be null");
+ }
+ this.evictionListener = listener;
+ return this;
+ }
+
+ /**
+ * Builds and returns a new {@link LIFOCache} instance with the configured parameters.
+ *
+ * @return a fully configured {@code LIFOCache} instance
+ */
+ public LIFOCache build() {
+ return new LIFOCache<>(this);
+ }
+
+ /**
+ * Sets the eviction strategy used to determine when to clean up expired entries.
+ *
+ * @param strategy an {@link EvictionStrategy} implementation; must not be {@code null}
+ * @return this builder instance
+ * @throws IllegalArgumentException if {@code strategy} is {@code null}
+ */
+ public Builder evictionStrategy(EvictionStrategy strategy) {
+ if (strategy == null) {
+ throw new IllegalArgumentException("Eviction strategy must not be null");
+ }
+ this.evictionStrategy = strategy;
+ return this;
+ }
+ }
+}
diff --git a/src/main/java/com/thealgorithms/datastructures/caches/LRUCache.java b/src/main/java/com/thealgorithms/datastructures/caches/LRUCache.java
index 97818ff83351..ec39d2a6ed28 100644
--- a/src/main/java/com/thealgorithms/datastructures/caches/LRUCache.java
+++ b/src/main/java/com/thealgorithms/datastructures/caches/LRUCache.java
@@ -4,15 +4,40 @@
import java.util.Map;
/**
- * Least recently used (LRU)
- *
- * Discards the least recently used items first. This algorithm requires keeping
- * track of what was used when, which is expensive if one wants to make sure the
- * algorithm always discards the least recently used item.
- * https://en.wikipedia.org/wiki/Cache_replacement_policies#Least_recently_used_(LRU)
+ * A Least Recently Used (LRU) Cache implementation.
*
- * @param key type
- * @param value type
+ * An LRU cache is a fixed-size cache that maintains items in order of use. When the cache reaches
+ * its capacity and a new item needs to be added, it removes the least recently used item first.
+ * This implementation provides O(1) time complexity for both get and put operations.
+ *
+ * Features:
+ *
+ * - Fixed-size cache with configurable capacity
+ * - Constant time O(1) operations for get and put
+ * - Thread-unsafe - should be externally synchronized if used in concurrent environments
+ * - Supports null values but not null keys
+ *
+ *
+ * Implementation Details:
+ *
+ * - Uses a HashMap for O(1) key-value lookups
+ * - Maintains a doubly-linked list for tracking access order
+ * - The head of the list contains the least recently used item
+ * - The tail of the list contains the most recently used item
+ *
+ *
+ * Example usage:
+ *
+ * LRUCache cache = new LRUCache<>(3); // Create cache with capacity 3
+ * cache.put("A", 1); // Cache: A=1
+ * cache.put("B", 2); // Cache: A=1, B=2
+ * cache.put("C", 3); // Cache: A=1, B=2, C=3
+ * cache.get("A"); // Cache: B=2, C=3, A=1 (A moved to end)
+ * cache.put("D", 4); // Cache: C=3, A=1, D=4 (B evicted)
+ *
+ *
+ * @param the type of keys maintained by this cache
+ * @param the type of mapped values
*/
public class LRUCache {
@@ -30,6 +55,11 @@ public LRUCache(int cap) {
setCapacity(cap);
}
+ /**
+ * Returns the current capacity of the cache.
+ *
+ * @param newCapacity the new capacity of the cache
+ */
private void setCapacity(int newCapacity) {
checkCapacity(newCapacity);
for (int i = data.size(); i > newCapacity; i--) {
@@ -39,6 +69,11 @@ private void setCapacity(int newCapacity) {
this.cap = newCapacity;
}
+ /**
+ * Evicts the least recently used item from the cache.
+ *
+ * @return the evicted entry
+ */
private Entry evict() {
if (head == null) {
throw new RuntimeException("cache cannot be empty!");
@@ -50,12 +85,25 @@ private Entry evict() {
return evicted;
}
+ /**
+ * Checks if the capacity is valid.
+ *
+ * @param capacity the capacity to check
+ */
private void checkCapacity(int capacity) {
if (capacity <= 0) {
throw new RuntimeException("capacity must greater than 0!");
}
}
+ /**
+ * Returns the value to which the specified key is mapped, or null if this cache contains no
+ * mapping for the key.
+ *
+ * @param key the key whose associated value is to be returned
+ * @return the value to which the specified key is mapped, or null if this cache contains no
+ * mapping for the key
+ */
public V get(K key) {
if (!data.containsKey(key)) {
return null;
@@ -65,6 +113,11 @@ public V get(K key) {
return entry.getValue();
}
+ /**
+ * Moves the specified entry to the end of the list.
+ *
+ * @param entry the entry to move
+ */
private void moveNodeToLast(Entry entry) {
if (tail == entry) {
return;
@@ -86,6 +139,12 @@ private void moveNodeToLast(Entry entry) {
tail = entry;
}
+ /**
+ * Associates the specified value with the specified key in this cache.
+ *
+ * @param key the key with which the specified value is to be associated
+ * @param value the value to be associated with the specified key
+ */
public void put(K key, V value) {
if (data.containsKey(key)) {
final Entry existingEntry = data.get(key);
@@ -107,6 +166,11 @@ public void put(K key, V value) {
data.put(key, newEntry);
}
+ /**
+ * Adds a new entry to the end of the list.
+ *
+ * @param newEntry the entry to add
+ */
private void addNewEntry(Entry newEntry) {
if (data.isEmpty()) {
head = newEntry;
diff --git a/src/main/java/com/thealgorithms/datastructures/caches/MRUCache.java b/src/main/java/com/thealgorithms/datastructures/caches/MRUCache.java
index 9c155be8b195..93b13e6ad654 100644
--- a/src/main/java/com/thealgorithms/datastructures/caches/MRUCache.java
+++ b/src/main/java/com/thealgorithms/datastructures/caches/MRUCache.java
@@ -4,14 +4,17 @@
import java.util.Map;
/**
- * Most recently used (MRU)
+ * Represents a Most Recently Used (MRU) Cache.
*
- * In contrast to Least Recently Used (LRU), MRU discards the most recently used
- * items first.
- * https://en.wikipedia.org/wiki/Cache_replacement_policies#Most_recently_used_(MRU)
+ * In contrast to the Least Recently Used (LRU) strategy, the MRU caching policy
+ * evicts the most recently accessed items first. This class provides methods to
+ * store key-value pairs and manage cache eviction based on this policy.
*
- * @param key type
- * @param value type
+ * For more information, refer to:
+ * MRU on Wikipedia.
+ *
+ * @param the type of keys maintained by this cache
+ * @param the type of values associated with the keys
*/
public class MRUCache {
@@ -21,40 +24,74 @@ public class MRUCache {
private int cap;
private static final int DEFAULT_CAP = 100;
+ /**
+ * Creates an MRUCache with the default capacity.
+ */
public MRUCache() {
setCapacity(DEFAULT_CAP);
}
+ /**
+ * Creates an MRUCache with a specified capacity.
+ *
+ * @param cap the maximum number of items the cache can hold
+ */
+ public MRUCache(int cap) {
+ setCapacity(cap);
+ }
+
+ /**
+ * Sets the capacity of the cache and evicts items if the new capacity
+ * is less than the current number of items.
+ *
+ * @param newCapacity the new capacity to set
+ */
private void setCapacity(int newCapacity) {
checkCapacity(newCapacity);
- for (int i = data.size(); i > newCapacity; i--) {
+ while (data.size() > newCapacity) {
Entry evicted = evict();
data.remove(evicted.getKey());
}
this.cap = newCapacity;
}
+ /**
+ * Checks if the specified capacity is valid.
+ *
+ * @param capacity the capacity to check
+ * @throws IllegalArgumentException if the capacity is less than or equal to zero
+ */
private void checkCapacity(int capacity) {
if (capacity <= 0) {
- throw new RuntimeException("capacity must greater than 0!");
+ throw new IllegalArgumentException("Capacity must be greater than 0!");
}
}
+ /**
+ * Evicts the most recently used entry from the cache.
+ *
+ * @return the evicted entry
+ * @throws RuntimeException if the cache is empty
+ */
private Entry evict() {
if (head == null) {
- throw new RuntimeException("cache cannot be empty!");
+ throw new RuntimeException("Cache cannot be empty!");
}
final Entry evicted = this.tail;
tail = evicted.getPreEntry();
- tail.setNextEntry(null);
+ if (tail != null) {
+ tail.setNextEntry(null);
+ }
evicted.setNextEntry(null);
return evicted;
}
- public MRUCache(int cap) {
- setCapacity(cap);
- }
-
+ /**
+ * Retrieves the value associated with the specified key.
+ *
+ * @param key the key whose associated value is to be returned
+ * @return the value associated with the specified key, or null if the key does not exist
+ */
public V get(K key) {
if (!data.containsKey(key)) {
return null;
@@ -64,11 +101,19 @@ public V get(K key) {
return entry.getValue();
}
+ /**
+ * Associates the specified value with the specified key in the cache.
+ * If the key already exists, its value is updated and the entry is moved to the most recently used position.
+ * If the cache is full, the most recently used entry is evicted before adding the new entry.
+ *
+ * @param key the key with which the specified value is to be associated
+ * @param value the value to be associated with the specified key
+ */
public void put(K key, V value) {
if (data.containsKey(key)) {
- final Entry exitingEntry = data.get(key);
- exitingEntry.setValue(value);
- moveEntryToLast(exitingEntry);
+ final Entry existingEntry = data.get(key);
+ existingEntry.setValue(value);
+ moveEntryToLast(existingEntry);
return;
}
Entry newEntry;
@@ -84,6 +129,11 @@ public void put(K key, V value) {
data.put(key, newEntry);
}
+ /**
+ * Adds a new entry to the cache and updates the head and tail pointers accordingly.
+ *
+ * @param newEntry the new entry to be added
+ */
private void addNewEntry(Entry newEntry) {
if (data.isEmpty()) {
head = newEntry;
@@ -96,6 +146,11 @@ private void addNewEntry(Entry newEntry) {
tail = newEntry;
}
+ /**
+ * Moves the specified entry to the most recently used position in the cache.
+ *
+ * @param entry the entry to be moved
+ */
private void moveEntryToLast(Entry entry) {
if (tail == entry) {
return;
@@ -117,8 +172,14 @@ private void moveEntryToLast(Entry entry) {
tail = entry;
}
+ /**
+ * A nested class representing an entry in the cache, which holds a key-value pair
+ * and references to the previous and next entries in the linked list structure.
+ *
+ * @param the type of the key
+ * @param the type of the value
+ */
static final class Entry {
-
private Entry preEntry;
private Entry nextEntry;
private I key;
diff --git a/src/main/java/com/thealgorithms/datastructures/caches/RRCache.java b/src/main/java/com/thealgorithms/datastructures/caches/RRCache.java
new file mode 100644
index 000000000000..1821872be9cd
--- /dev/null
+++ b/src/main/java/com/thealgorithms/datastructures/caches/RRCache.java
@@ -0,0 +1,505 @@
+package com.thealgorithms.datastructures.caches;
+
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.Iterator;
+import java.util.List;
+import java.util.Map;
+import java.util.Random;
+import java.util.concurrent.locks.Lock;
+import java.util.concurrent.locks.ReentrantLock;
+import java.util.function.BiConsumer;
+
+/**
+ * A thread-safe generic cache implementation using the Random Replacement (RR) eviction policy.
+ *
+ * The cache holds a fixed number of entries, defined by its capacity. When the cache is full and a
+ * new entry is added, one of the existing entries is selected at random and evicted to make space.
+ *
+ * Optionally, entries can have a time-to-live (TTL) in milliseconds. If a TTL is set, entries will
+ * automatically expire and be removed upon access or insertion attempts.
+ *
+ * Features:
+ *
+ * - Random eviction when capacity is exceeded
+ * - Optional TTL (time-to-live in milliseconds) per entry or default TTL for all entries
+ * - Thread-safe access using locking
+ * - Hit and miss counters for cache statistics
+ * - Eviction listener callback support
+ *
+ *
+ * @param the type of keys maintained by this cache
+ * @param the type of mapped values
+ * See Random Replacement
+ * @author Kevin Babu (GitHub)
+ */
+public final class RRCache {
+
+ private final int capacity;
+ private final long defaultTTL;
+ private final Map> cache;
+ private final List keys;
+ private final Random random;
+ private final Lock lock;
+
+ private long hits = 0;
+ private long misses = 0;
+ private final BiConsumer evictionListener;
+ private final EvictionStrategy