Module com.slinky.hackmaster
Package com.slinky.hackmaster.util

Class GridUtil

java.lang.Object
com.slinky.hackmaster.util.GridUtil
public final class GridUtil extends Object
A comprehensive utility class designed for performing various operations on 2D arrays in Java.

The GridUtil class serves as a central repository for a variety of utility methods that facilitate the manipulation and validation of two-dimensional arrays, commonly used in grid-based applications. The utility functions include verifying if a 2D array is rectangular, converting one-dimensional arrays into two-dimensional arrays, and finding the closest factor pair for a given integer, among others.

Design and Usage

This class is declared as final to prevent inheritance, which is appropriate for utility classes where all methods are static and there is no need for instance-specific behavior. To enforce this design, the constructor is private, ensuring that no instances of the class can be created.

Thread Safety

Since all methods in this class are stateless and static, GridUtil is inherently thread-safe. This makes it suitable for use in multi-threaded environments without the need for additional synchronization.

Performance Considerations

The methods provided are optimized for performance in typical use cases involving 2D arrays. For example, the isRectangular method ensures that the array structure is checked in an efficient manner, iterating over the minimum necessary elements. The conversion methods are designed to handle large datasets with minimal overhead.

Common Use Cases

  • Validating the structure of a 2D array, ensuring all rows have the same length.
  • Converting flat, one-dimensional arrays into two-dimensional arrays for grid-based algorithms.
  • Finding optimal dimensions for splitting a dataset into rows and columns based on its size.

Extensibility

Although this class cannot be subclassed due to its final modifier, it is designed with extensibility in mind by providing general-purpose methods that can be combined and reused in various contexts. Users can build more complex functionality on top of these basic utilities in their own applications.

Examples

 // Example: Check if a 2D array is rectangular
 String[][] grid = {{"A", "B", "C"}, {"D", "E", "F"}, {"G", "H", "I"}};
 boolean isRect = GridUtil.isRectangular(grid);
 System.out.println("Is grid rectangular? " + isRect); // Output: true

 // Example: Convert a 1D array to a 2D array
 Integer[] numbers = {1, 2, 3, 4, 5, 6};
 Integer[][] grid = GridUtil.turnTo2DArray(numbers, 2, 3);
 // grid is now {{1, 2, 3}, {4, 5, 6}}

Versioning

This version of GridUtil is intended for use in applications that require basic grid manipulation functionalities. Future versions may include additional methods for handling more advanced grid operations.

Since:
2024-08-20
Version:
1.0
Author:
Kheagen Haskins

  • Method Summary

    Modifier and Type
    Method
    Description
    static Dimension
    getClosestRowColPair(int x)
    Computes and returns the closest pair of factors for a given integer x.
    static <T> boolean
    isRectangular(T[][] arr)
    Checks if the provided 2D array is rectangular (i.e., all rows have the same length).
    static <T> T[][]
    turnTo2DArray(T[] arr)
    Converts a one-dimensional array into a two-dimensional array with an automatically determined number of rows and columns.
    static <T> T[][]
    turnTo2DArray(T[] arr, int rows, int cols)
    Converts a one-dimensional array into a two-dimensional array with the specified number of rows and columns.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • isRectangular

      public static <T> boolean isRectangular(T[][] arr)
      Checks if the provided 2D array is rectangular (i.e., all rows have the same length).

      This method verifies that the 2D array provided for the grid is properly rectangular by ensuring that all rows have the same number of columns.

      Type Parameters:
      T - The object type
      Parameters:
      arr - The 2D array to check.
      Returns:
      true if the array is rectangular, false otherwise.

    • turnTo2DArray

      public static <T> T[][] turnTo2DArray(T[] arr, int rows, int cols)
      Converts a one-dimensional array into a two-dimensional array with the specified number of rows and columns.

      This method transforms the given one-dimensional array into a 2D array of the same type, ensuring that the total number of elements in the original array matches the product of the specified rows and columns. If the number of elements does not match, an IllegalArgumentException is thrown.

      Type Parameters:
      T - the type of the array elements
      Parameters:
      arr - the one-dimensional array to be converted into a two-dimensional array
      rows - the number of rows for the resulting 2D array
      cols - the number of columns for the resulting 2D array
      Returns:
      a two-dimensional array containing the elements of the input array arranged in the specified number of rows and columns
      Throws:
      IllegalArgumentException - if the length of the input array does not match rows * cols

    • turnTo2DArray

      public static <T> T[][] turnTo2DArray(T[] arr)
      Converts a one-dimensional array into a two-dimensional array with an automatically determined number of rows and columns.

      This method calculates the number of rows and columns based on the length of the input array. The calculated dimensions are then used to transform the one-dimensional array into a two-dimensional array. The dimensions are determined by the getClosestRowColPair method, which splits the array length into two factors.

      The method assumes that the input array length can be perfectly divided into rows and columns. If not, it relies on the turnTo2DArray(T[] arr, int rows, int cols) method to handle the conversion, which will throw an IllegalArgumentException if the length is incompatible with the determined dimensions.

      Type Parameters:
      T - the type of the array elements
      Parameters:
      arr - the one-dimensional array to be converted into a two-dimensional array
      Returns:
      a two-dimensional array containing the elements of the input array arranged in the automatically determined number of rows and columns
      Throws:
      IllegalArgumentException - if the calculated dimensions do not match the length of the input array

    • getClosestRowColPair

      public static Dimension getClosestRowColPair(int x)
      Computes and returns the closest pair of factors for a given integer x. The method identifies the two factors of x that are closest to each other in value. The search begins from the square root of x and moves downwards to find the closest pair. If no factors are found close to the square root, the method returns x and 1, indicating that x is likely a prime number.
      Parameters:
      x - the integer for which the closest factor pair is to be found. Must be a positive non-zero integer.
      Returns:
      a Dimension object where the width is the larger factor and the height is the smaller factor of the closest pair. If x is a prime number, returns x and 1.
      Throws:
      IllegalArgumentException - if x is less than 1, as the input must be positive and non-zero.