Module com.slinky.hackmaster

Package com.slinky.hackmaster.model.cell

Class CellGrid

java.lang.Object

com.slinky.hackmaster.model.cell.CellGrid

All Implemented Interfaces:

CellManager

public class CellGrid
extends Object
implements CellManager

The CellGrid class is responsible for managing a grid of Cell objects, including their creation, clustering, and global operations.

This class provides a structured way to represent a grid of characters, where each character is encapsulated in a Cell object. The grid can contain both letters and symbols, which are automatically categorised and clustered into CellCluster objects based on the provided ClusterStrategy.

Key responsibilities of the CellGrid include:

• Cell Creation: Initialises all Cell objects based on the provided character grid. The cells are stored in a contiguous array for efficient memory usage and easy access.
• Clustering: Clusters the cells into groups of letters and symbols using the provided ClusterStrategy. These clusters are stored separately for quick access and manipulation.
• Global Operations: Provides various operations that can be performed on the entire grid, such as retrieving specific cells, accessing the list of letter or symbol clusters, and searching for and removing specific word clusters.
• Memory Efficiency: Maintains references to all Cell objects in a flat array, ensuring efficient memory usage and simplifying global operations that need to access all cells.

The CellGrid does not maintain a persistent reference to the ClusterStrategy used during initialisation; it is only used during the setup process to categorise and cluster the cells according to the specific strategy's logic.

Example use cases include:

• Creating a grid from a matrix of characters and clustering them into words and symbols.
• Retrieving the words formed by letter clusters for further processing or display.
• Performing operations on the entire grid of cells, such as clearing specific clusters or querying the grid for specific patterns.

Important Constraints:

• The character grid provided during instantiation must be rectangular; that is, all rows must have the same length.
• The ClusterStrategy provided must not be null and must be able to handle the clustering of both letter and symbol cells.

Author:

Kheagen Haskins

See Also:

• Cell
• CellCluster
• ClusterStrategy
• LetterCell
• SymbolCell

Constructor Summary

Constructors

Constructor	Description
CellGrid(String text, ClusterStrategy clusterStrategy)	Constructs a new CellGrid with the specified text grid and clustering strategy.
CellGrid(String text, ClusterStrategy clusterStrategy, int rows, int cols)	Constructs a new CellGrid with the specified text grid and clustering strategy.

Method Summary

Modifier and Type	Method	Description
Cell	getCell(int index)	Retrieves the Cell at the specified index from the internal cell array.
Cell	getCellAt(int row, int col)	Returns the Cell located at the specified row and column in the grid.
Cell[]	getCells()	Returns a flat array of all the Cell objects in the grid.
Cell[][]	getCells2D()	Returns the 2D arrangement of Cells.
int	getColumnCount()	Retrieves the number of columns in the grid.
List<CellCluster>	getLetterClusters()	Returns the list of letter clusters in the grid.
int	getRowCount()	Retrieves the number of rows in the grid.
List<CellCluster>	getSymbolClusters()	Returns the list of symbol clusters in the grid.
String[]	getWords()	Returns an array of words formed by the letter clusters in the grid.
String	removeDud(String dudText)	Searches through the letter clusters for a cluster containing the specified dudText, removes it, and returns the text of the removed cluster.

Methods inherited from class java.lang.Object

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

Constructor Details

CellGrid

public CellGrid(String text,
 ClusterStrategy clusterStrategy,
 int rows,
 int cols)

Constructs a new CellGrid with the specified text grid and clustering strategy.

This constructor initialises the grid of Cell objects and clusters them based on the provided ClusterStrategy. The grid must be rectangular, with all rows of equal length, and both the grid and strategy must be non-null.

Parameters:

text - A string of characters representing the text grid to be converted into cells.

clusterStrategy - The strategy used to cluster the cells into letter and symbol clusters.

rows - the number of rows in this grid

cols - the number of columns in this grid

Throws:

IllegalArgumentException - If the textGrid is null or does not match the size of the grid as specified by the number of rows and columns, or if the clusterStrategy is null, or if the grid is not rectangular.

CellGrid

public CellGrid(String text,
 ClusterStrategy clusterStrategy)

Constructs a new CellGrid with the specified text grid and clustering strategy.

This constructor initialises the grid of Cell objects and clusters them based on the provided ClusterStrategy. The grid must be rectangular, with all rows of equal length, and both the grid and strategy must be non-null.

Parameters:

text - A string of characters representing the text grid to be converted into cells.

clusterStrategy - The strategy used to cluster the cells into letter and symbol clusters.

Throws:

IllegalArgumentException - If the textGrid is null or if the clusterStrategy is null, or if the grid is not rectangular.

Method Details

getCells

public Cell[] getCells()

Returns a flat array of all the Cell objects in the grid.

This method provides access to the entire grid of cells as a single array, which is useful for performing uniform operations across all cells.

Specified by:

getCells in interface CellManager

Returns:

An array of Cell objects representing the entire grid.

getCells2D

public Cell[][] getCells2D()

Returns the 2D arrangement of Cells.

Specified by:

getCells2D in interface CellManager

Returns:

getCell

public Cell getCell(int index)

Retrieves the Cell at the specified index from the internal cell array.

This method calculates the total number of cells based on the dimensions of rows and columns. It then checks if the provided index is within the valid range of indices. If the index is out of bounds, an ArrayIndexOutOfBoundsException is thrown.

Specified by:

getCell in interface CellManager

Parameters:

index - the index of the Cell to retrieve.

Returns:

the Cell at the specified index.

Throws:

ArrayIndexOutOfBoundsException - if the index is less than 0 or greater than or equal to the total number of cells.

getCellAt

public Cell getCellAt(int row,
 int col)

Returns the Cell located at the specified row and column in the grid.

This method retrieves a specific Cell based on its position in the grid. If the provided row or column index is out of bounds, an IllegalArgumentException is thrown.

Specified by:

getCellAt in interface CellManager

Parameters:

row - The row index of the cell to retrieve.

col - The column index of the cell to retrieve.

Returns:

The Cell located at the specified row and column.

Throws:

IllegalArgumentException - If the row or column index is out of bounds.

getRowCount

public int getRowCount()

Retrieves the number of rows in the grid. This method provides access to the private field storing the number of rows, allowing external classes to understand the grid's vertical dimensions without modifying the data.

Returns:

the number of rows in the grid

getColumnCount

public int getColumnCount()

Retrieves the number of columns in the grid. This method provides access to the private field storing the number of columns, enabling external classes to understand the grid's horizontal dimensions without altering the underlying structure.

Returns:

the number of columns in the grid

getLetterClusters

public List<CellCluster> getLetterClusters()

Returns the list of letter clusters in the grid.

This method provides access to all clusters of letter cells that have been identified in the grid.

Specified by:

getLetterClusters in interface CellManager

Returns:

A list of CellCluster objects containing letter cells.

getSymbolClusters

public List<CellCluster> getSymbolClusters()

Returns the list of symbol clusters in the grid.

This method provides access to all clusters of symbol cells that have been identified in the grid.

Specified by:

getSymbolClusters in interface CellManager

Returns:

A list of CellCluster objects containing symbol cells.

getWords

public String[] getWords()

Returns an array of words formed by the letter clusters in the grid.

This method retrieves the text content of each letter cluster and returns them as an array of strings, effectively representing the words in the grid.

Specified by:

getWords in interface CellManager

Returns:

An array of String objects, each representing a word formed by a letter cluster.

removeDud

public String removeDud(String dudText)

Searches through the letter clusters for a cluster containing the specified dudText, removes it, and returns the text of the removed cluster.

This method iterates through all remaining letter clusters to find one that matches the provided dudText. If a matching cluster is found, it is cleared and removed from the list of clusters, and its text is returned. If no matching cluster is found, the method returns null.

Specified by:

removeDud in interface CellManager

Parameters:

dudText - The text of the cluster to be removed.

Returns:

The text of the removed cluster, or null if no matching cluster is found.