This class is not intended to be instantiated.
+ */ public class ArrayAlgorithms{ + /** + * Private constructor to prevent instantiation of this utility class. + */ private ArrayAlgorithms(){} - //This function returns the sum of all elements in the list + + //?This function returns the sum of all elements in the list + /** + * Returns the sum of all elements in the given iterable collection of integers. + * + * @param nums the iterable collection of integers to sum + * @return the sum of all integers in the collection + */ public static int getSum(IterableThis class cannot be instantiated.
+ */ public class NumberAlgorithms{ + /** + * Private constructor to prevent instantiation + */ private NumberAlgorithms(){} + /** + * Error message used for invalid factorial inputs. + */ public static final String FACTORIAL_NEGATIVE_MESSAGE = "n! cannot be negative"; - //This function returns a list with all the prime numbers <= goalNumber + //?This function returns a list with all the prime numbers <= goalNumber + /** + * Returns a list of all prime numbers less than or equal to the specified number. + * + * @param goalNumber the upper limit for generating prime numbers + * @return a list of prime numbers less than or equal to {@code goalNumber} + * @see #getPrimes(long) + */ public static List+ * This class provides methods to start, stop, and reset a stopwatch, as well as retrieve the + * elapsed time in nanoseconds, microseconds, milliseconds, seconds, minutes, and hours. It + * also includes functionality to get the elapsed time as a formatted string in the most + * appropriate time unit. + *
+ */ public class Stopwatch{ + /** + * The start time of the stopwatch in nanoseconds. + */ private Long startTime; + /** + * The stop time of the stopwatch in nanoseconds. + */ private Long stopTime; - //Constructor makes sure all values are set to defaults + + + //?Constructor makes sure all values are set to defaults + /** + * Constructs a new Stopwatch and initializes the start and stop times to {@code null}. + * This ensures that incorrect function calling order can be detected easily. + */ public Stopwatch(){ //Make sure both values are null so it is easier to detect incorrect function calling order startTime = null; stopTime = null; } - //Returns a long with the elapsed time in nanoseconds. Used by other functions to get the time before converting it to the correct resolution + + + //?Returns a long with the elapsed time in nanoseconds. Used by other functions to get the time before converting it to the correct resolution + /** + * Returns the elapsed time in nanoseconds. + *+ * If the stopwatch has not been started, it returns {@code 0L}. If the stopwatch has + * been started but not stopped, it returns the time elapsed since it was started. + *
+ * + * @return the elapsed time in nanoseconds + */ private Long getTime(){ if(startTime == null){ return 0L; @@ -46,16 +79,37 @@ public class Stopwatch{ return stopTime - startTime; } } - //An enum that helps keep track of how many times the time has been reduced in the getStr function + + + //?An enum that helps keep track of how many times the time has been reduced in the getStr function + /** + * Enum to represent the time resolution for formatting the time string. + */ private enum TIME_RESOLUTION{ NANOSECOND, MICROSECOND, MILLISECOND, SECOND, MINUTE, HOUR, ERROR } - //Simulates starting a stopwatch by saving the time + + + //?Simulates starting a stopwatch by saving the time + /** + * Starts the stopwatch by recording the current time in nanoseconds. + *+ * If the stopwatch was already running, the previous start time is overwritten. + *
+ */ public void start(){ //Make sure the stop time is reset to 0 stopTime = null; //Get the time as close to returning from the function as possible startTime = System.nanoTime(); } - //Simulates stopping a stopwatch by saving the time + + + //?Simulates stopping a stopwatch by saving the time + /** + * Stops the stopwatch by recording the current time in nanoseconds. + *+ * If the stopwatch has not been started, this method has no effect. + *
+ */ public void stop(){ //Set the stopTime as close to call time as possible stopTime = System.nanoTime(); @@ -64,42 +118,114 @@ public class Stopwatch{ stopTime = null; } } - //Resets all variables in the stopwatch + + + //?Resets all variables in the stopwatch + /** + * Resets the stopwatch, clearing the start and stop times. + *+ * After calling this method, the stopwatch needs to be started again before measuring + * elapsed time. + *
+ */ public void reset(){ //Make sure all variables are reset correctly startTime = null; stopTime = null; } - //Returns the time in nanoseconds + + + //?Returns the time in nanoseconds + /** + * Returns the elapsed time in nanoseconds. + * + * @return the elapsed time in nanoseconds as a {@code double} + */ public double getNano(){ return getTime().doubleValue(); } - //Returns the time in microseconds + + + //?Returns the time in microseconds + /** + * Returns the elapsed time in microseconds. + * + * @return the elapsed time in microseconds as a {@code double} + */ public double getMicro(){ return getTime().doubleValue() / 1000D; } - //Returns the time in milliseconds + + + //?Returns the time in milliseconds + /** + * Returns the elapsed time in milliseconds. + * + * @return the elapsed time in milliseconds as a {@code double} + */ public double getMilli(){ return getTime().doubleValue() / 1000000D; } - //Returns the time in seconds + + + //?Returns the time in seconds + /** + * Returns the elapsed time in seconds. + * + * @return the elapsed time in seconds as a {@code double} + */ public double getSecond(){ return getTime().doubleValue() / 1000000000D; } - //Returns the time in minutes + + + //?Returns the time in minutes + /** + * Returns the elapsed time in minutes. + * + * @return the elapsed time in minutes as a {@code double} + */ public double getMinute(){ return getTime().doubleValue() / 60000000000D; } - //Returns the time in hours + + + //?Returns the time in hours + /** + * Returns the elapsed time in hours. + * + * @return the elapsed time in hours as a {@code double} + */ public double getHour(){ return getTime().doubleValue() / 3600000000000D; } - //Returns the time as a string at the 'best' resolution. (Goal is xxx.xxx) + + + //?Returns the time as a string at the 'best' resolution. (Goal is xxx.xxx) + /** + * Returns the elapsed time as a formatted string with the most appropriate resolution. + *+ * The method automatically selects the best time resolution to display the time in a + * human-readable format. + *
+ * + * @return a formatted string representing the elapsed time + * @throws InvalidResult if the time resolution is invalid + */ public String getStr() throws InvalidResult{ //Get the current duration from time return getStr(getTime().doubleValue()); } + + /** + * Returns a formatted string representing the given time in nanoseconds with the most + * appropriate resolution. + * + * @param nanoseconds the time in nanoseconds to format + * @return a formatted string representing the given time + * @throws InvalidResult if the time resolution is invalid + */ public static String getStr(double nanoseconds) throws InvalidResult{ Double duration = nanoseconds; //Reduce the number to the appropriate number of digits. (xxx.x). @@ -145,6 +271,12 @@ public class Stopwatch{ return time; } + + /** + * Returns a string representation of the elapsed time in the most appropriate resolution. + * + * @return a string representation of the elapsed time + */ @Override public String toString(){ return getStr(); diff --git a/src/main/java/com/mattrixwv/StringAlgorithms.java b/src/main/java/com/mattrixwv/StringAlgorithms.java index 89cff8c..2bec82c 100644 --- a/src/main/java/com/mattrixwv/StringAlgorithms.java +++ b/src/main/java/com/mattrixwv/StringAlgorithms.java @@ -1,10 +1,10 @@ //JavaClasses/src/main/java/mattrixwv/StringAlgorithms.java //Matthew Ellison // Created: 07-03-21 -//Modified: 04-13-23 +//Modified: 08-11-24 //This class contains algorithms for strings that I've found it useful to keep around /* - Copyright (C) 2023 Matthew Ellison + Copyright (C) 2024 Matthew Ellison This program is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by @@ -27,12 +27,38 @@ import java.util.Collections; import java.util.List; +/** + * Utility class providing algorithms for manipulating and analyzing strings. + * + *+ * This class offers methods to generate permutations of a string, count occurrences of a character, + * check if a string is a palindrome, and determine if a string is pandigital. + *
+ */ public class StringAlgorithms{ + /** + * Private constructor to prevent instantiation of this utility class. + */ private StringAlgorithms(){} - //This is a function that creates all permutations of a string and returns a vector of those permutations. + + + //?This is a function that creates all permutations of a string and returns a vector of those permutations. + /** + * Generates all permutations of the given string. + * + * @param master the input string for which permutations are to be generated + * @return a list of all permutations of the input string + */ public static List+ * This class holds three values of potentially different types and provides methods to access them. + *
+ * + * @param+ * Returns {@code true} if and only if the specified object is also a Triple, and all + * corresponding pairs of elements in the two Triples are equal. + *
+ * + * @param o the object to be compared for equality with this Triple + * @return {@code true} if the specified object is equal to this Triple, {@code false} otherwise + */ @Override public boolean equals(Object o){ if(this == o){ @@ -55,10 +108,27 @@ public class Triple+ * The string representation consists of the string representations of the three elements, + * separated by commas and enclosed in square brackets. + *
+ * + * @return a string representation of the Triple + */ @Override public String toString(){ return "[" + a.toString() + ", " + b.toString() + ", " + c.toString() + "]"; diff --git a/src/main/java/com/mattrixwv/exceptions/InvalidResult.java b/src/main/java/com/mattrixwv/exceptions/InvalidResult.java index a7ee316..1c64664 100644 --- a/src/main/java/com/mattrixwv/exceptions/InvalidResult.java +++ b/src/main/java/com/mattrixwv/exceptions/InvalidResult.java @@ -1,23 +1,59 @@ //JavaClasses/src/main/java/mattrixwv/Exceptions/InvalidResult.java //Matthew Ellison // Created: 08-24-20 -//Modified: 04-13-23 +//Modified: 08-11-24 //This is an exception for an invalid result out of one of my algorithms package com.mattrixwv.exceptions; +/** + * The {@code InvalidResult} class extends {@code RuntimeException} and is used to indicate + * that an invalid result has occurred. It provides several constructors to create exceptions + * with a custom message and/or cause. + * + *This class is a runtime exception, meaning it is unchecked and does not need to be declared + * in a method or constructor's {@code throws} clause.
+ * + * @see RuntimeException + */ public class InvalidResult extends RuntimeException{ - private static final long serialVersionUID = 1L; - + /** + * Constructs a new runtime exception with {@code null} as its detail message. + * The cause is not initialized and may subsequently be initialized by a call to {@link #initCause}. + */ public InvalidResult(){ super(); } + /** + * Constructs a new runtime exception with the specified detail message. The cause is not initialized, + * and may subsequently be initialized by a call to {@link #initCause}. + * + * @param msg the detail message. The detail message is saved for later retrieval by the {@link #getMessage()} method. + */ public InvalidResult(String msg){ super(msg); } + /** + * Constructs a new runtime exception with the specified cause and a detail message of + * {@code (cause == null ? null : cause.toString())} (which typically contains the class + * and detail message of {@code cause}). + * + * @param cause the cause (which is saved for later retrieval by the {@link #getCause()} method). + * A {@code null} value is permitted and indicates that the cause is nonexistent or unknown. + */ public InvalidResult(Throwable cause){ super(cause); } + /** + * Constructs a new runtime exception with the specified detail message and cause. + * + *Note that the detail message associated with {@code cause} is not automatically incorporated + * in this runtime exception's detail message.
+ * + * @param msg the detail message (which is saved for later retrieval by the {@link #getMessage()} method). + * @param cause the cause (which is saved for later retrieval by the {@link #getCause()} method). + * A {@code null} value is permitted and indicates that the cause is nonexistent or unknown. + */ public InvalidResult(String msg, Throwable cause){ super(msg, cause); } diff --git a/src/main/java/com/mattrixwv/generators/HexagonalNumberGenerator.java b/src/main/java/com/mattrixwv/generators/HexagonalNumberGenerator.java index 56bcb22..84a6895 100644 --- a/src/main/java/com/mattrixwv/generators/HexagonalNumberGenerator.java +++ b/src/main/java/com/mattrixwv/generators/HexagonalNumberGenerator.java @@ -1,10 +1,10 @@ //JavaClasses/src/main/java/mattrixwv/HexagonalNumberGenerator.java //Matthew Ellison // Created: 08-20-22 -//Modified: 04-13-23 +//Modified: 08-11-24 //This class generates hexagonal numbers /* -Copyright (C) 2023 Matthew Ellison +Copyright (C) 2024 Matthew Ellison This program is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by @@ -26,18 +26,48 @@ import java.util.Iterator; import java.util.NoSuchElementException; +/** + * A generator for hexagonal numbers, which implements the {@link Iterator} interface. + * + *+ * Hexagonal numbers are figurate numbers that represent hexagons. The n-th hexagonal number is given by + * the formula: H(n) = 2n^2 - n. + *
+ * + *+ * This generator allows iteration over hexagonal numbers starting from the first. + *
+ */ public class HexagonalNumberGenerator implements Iterator+ * Pentagonal numbers are figurate numbers that represent pentagons. The n-th pentagonal number is given by + * the formula: P(n) = (3n^2 - n) / 2. + *
+ * + *+ * This generator allows iteration over pentagonal numbers starting from the first. + *
+ */ public class PentagonalNumberGenerator implements Iterator+ * This implementation generates prime numbers in an incremental fashion using a modified version of the Sieve of Eratosthenes algorithm. + * The algorithm uses a map to keep track of the multiples of found prime numbers to efficiently determine the next prime. + *
+ */ public class SieveOfEratosthenes implements Iterator+ * This method always returns {@code true} as the iterator is designed to + * generate primes indefinitely. + *
+ * + * @return {@code true}, as the iterator can generate an infinite number of primes + */ @Override public boolean hasNext(){ return true; } + /** + * Returns the next prime number. + * + *+ * The method generates the next prime number by checking and updating the + * internal map of known multiples. The first prime returned is 2, and subsequent + * primes are found by incrementing the possible prime number and checking its + * primality using the map. + *
+ * + * @return the next prime number + * @throws NoSuchElementException if the next prime cannot be represented by a {@code long} + */ @Override public Long next(){ long prime; diff --git a/src/main/java/com/mattrixwv/generators/SieveOfEratosthenesBig.java b/src/main/java/com/mattrixwv/generators/SieveOfEratosthenesBig.java index 0aa9760..fb48c2f 100644 --- a/src/main/java/com/mattrixwv/generators/SieveOfEratosthenesBig.java +++ b/src/main/java/com/mattrixwv/generators/SieveOfEratosthenesBig.java @@ -1,10 +1,10 @@ //JavaClasses/src/main/java/mattrixwv/SieveOfEratosthenesBig.java //Matthew Ellison // Created: 06-30-21 -//Modified: 04-13-23 +//Modified: 08-11-24 //This class uses to Sieve of Eratosthenes to generate an infinite number of primes /* -Copyright (C) 2023 Matthew Ellison +Copyright (C) 2024 Matthew Ellison This program is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by @@ -28,23 +28,65 @@ import java.util.Arrays; import java.util.HashMap; import java.util.Iterator; import java.util.Map; +import java.util.NoSuchElementException; +/** + * A generator for prime numbers using the Sieve of Eratosthenes algorithm, which implements the {@link Iterator} interface. + * + *+ * This implementation generates prime numbers in an incremental fashion using a modified version of the Sieve of Eratosthenes algorithm. + * The algorithm uses a map to keep track of the multiples of found prime numbers to efficiently determine the next prime. + *
+ */ public class SieveOfEratosthenesBig implements Iterator+ * This method always returns {@code true} as the iterator is designed to + * generate primes indefinitely. + *
+ * + * @return {@code true}, as the iterator can generate an infinite number of primes + */ @Override public boolean hasNext(){ return true; } + /** + * Returns the next prime number. + * + *+ * The method generates the next prime number by checking and updating the + * internal map of known multiples. The first prime returned is 2, and subsequent + * primes are found by incrementing the possible prime number and checking its + * primality using the map. + *
+ * + * @return the next prime number + * @throws NoSuchElementException if the next prime cannot be represented by a {@code long} + */ @Override public BigInteger next(){ BigInteger prime; @@ -72,6 +114,10 @@ public class SieveOfEratosthenesBig implements Iterator+ * Triangular numbers are figurate numbers that represent triangles. The n-th triangular number is given by + * the formula: T(n) = n(n + 1) / 2. + *
+ * + *+ * This generator allows iteration over triangular numbers starting from the first. + *
+ */ public class TriangularNumberGenerator implements Iterator