From 1eb627b45d437baa35e15d01c3d0f2b917dc2ca0 Mon Sep 17 00:00:00 2001 From: Dorian HAMDANI Date: Tue, 6 May 2025 19:27:16 +0200 Subject: [PATCH] Document GomokuCell class file --- src/GomokuCell.java | 287 +++++++++++++++++++++++++++++--------------- 1 file changed, 187 insertions(+), 100 deletions(-) diff --git a/src/GomokuCell.java b/src/GomokuCell.java index ba144c3..5e1a292 100644 --- a/src/GomokuCell.java +++ b/src/GomokuCell.java @@ -1,160 +1,247 @@ import java.util.EnumMap; -import java.util.HashMap; import java.util.Map; /** - * This class is cell of the board of the Gomoku game. + * A cell of a Gomoku board. + * + * This class represents a cell of a Gomoku board. + * It contains the state of the cell (empty, black or white) and its neighbours, + * as well as various methods to manipulate the cell. */ -public class GomokuCell{ +public class GomokuCell { - public static final String RESET = "\u001B[0m"; - public static final String ROUGE = "\u001B[31m"; - public static final String VERT = "\u001B[32m"; - /** Enumerate neighbor with key in Cardinal direction and key representing the cell in that direction. */ - private EnumMap neighbour; - /** The state of the cell represented by the enumerate Color, Nil is empty, white and black for the color of a token */ - private Color state; + /** The neighbours of the cell. + * + * Each neighbour of the cell is stored in the EnumMap with the direction to + * that neighbour as the key. + */ + private EnumMap neighbours; - //------------------Constructors-------------------------- + /** The state of the cell. + * + * Represented by the enumerate Color where NIL is empty and + * BLACK and WHITE are the two players. + */ + private Color state; + + // - Constructors ------------------------------------- /** * The constructor of the cell. - * @param state The state by default of the cell. + * + * This constructor creates a cell with the given state + * and an empty list of neighbours. + * + * @param state The initial state of the cell. */ - public GomokuCell(Color state){ - this.neighbour = new EnumMap<>(Cardinal.class); + public GomokuCell(Color state) { + this.neighbours = new EnumMap<>(Cardinal.class); this.state = state; } - //------------------Gets-------------------------- + // - Getters ------------------------------------------ /** - * Return one neighbour. - * @param car The Cardinal direction. - * @return The GomokuCell at the direction. + * Return the state of the cell. + * + * This method returns the state of the cell. + * + * @return The state of the current cell. */ - public GomokuCell getNeighbour(Cardinal car){ - return this.neighbour.get(car); - } - - /** - * Return neighbours. - * @return The EnumMap of neighbours. - */ - public EnumMap getAllNeighbour(){ - return neighbour; - } - - /** - * Return the number of same colored neighbours in all direction. - * @return The Map of neighbours. - */ - public Map getSameColorNeighbour(){ - - Map map = new HashMap<>(); - map.put(Cardinal.N, 0); - map.put(Cardinal.W,0); - map.put(Cardinal.NW, 0); - map.put(Cardinal.SW, 0); - map.put(Cardinal.S, 0); - map.put(Cardinal.SE, 0); - map.put(Cardinal.E, 0); - map.put(Cardinal.NE, 0); - - for (Map.Entry entry : map.entrySet()) { - - GomokuCell actualcell = this; - while(this.getState() == actualcell.getNeighbour(entry.getKey()).getState()) - { - entry.setValue(entry.getValue()+1); - actualcell=actualcell.getNeighbour(entry.getKey()); - } - } - return map; - } - - /** - * Return the state. - * @return The state of the current cell with one Color. - */ - public Color getState(){ + public Color getState() { return this.state; } - //------------------Sets-------------------------- - /** - * Change state of the current cell. - * @param c The color of the token played. - * @throws IllegalStateException If the cell is not playable. + * Return the neighbour in specified direction. + * + * This method returns the neighbour of the cell in the specified direction. + * If the neighbour does not exist, it returns null. + * + * @param dir The Cardinal direction. + * @return The GomokuCell in the specified the direction, or null if it + * does not exist. */ - public void setState(Color c){ + public GomokuCell getNeighbour(Cardinal dir) { + return this.neighbours.get(dir); + } + + /** + * Return all neighbours of the cell. + * + * This method returns all the neighbours of the cell in an EnumMap. + * The keys of the map are the Cardinal directions and the values are the + * GomokuCells in that direction, or null if the neighbour does not exist. + * + * @return The EnumMap of neighbours. + */ + public EnumMap getAllNeighbours() { + return neighbours; + } + + /** + * Return the number of same colored neighbours in each direction. + * + * This method returns the number of same colored neighbours in each + * direction in a Map. The keys of the map are the Cardinal directions and + * the values are the number of same colored neighbours in that direction. + * The method iterates through each neighbour and counts the number of + * same colored neighbours in that direction until it reaches a neighbour + * that is not the same color as the current cell. + * + * @return The Map indicating the number of same colored neighbours in each + * direction. + */ + public Map getSameColorNeighbours() { + + Map map = new EnumMap<>(Cardinal.class); + int count; + + // Iterate through each direction + for (Cardinal direction : Cardinal.values()) { + count = 0; + // Get the neighbour in the specified direction + GomokuCell neighbour = this.getNeighbour(direction); + + // While the neighbour is not null and has the same state as the current cell + while (neighbour != null && neighbour.getState() == this.getState()) { + count++; + // Move to the next neighbour in the same direction + neighbour = neighbour.getNeighbour(direction); + } + + // Store the count in the map + map.put(direction, count); + } + + return map; + } + + // - Setters ------------------------------------------ + + /** + * Set the state of the cell. + * + * This method sets the state of the cell to the given color. + * + * @param c The color to set the cell to. + */ + public void setState(Color c) { this.state = c; } - - //------------------Booleans-------------------------- + // - Cell State Methods --------------------------- /** - * This method returns if the current cell is empty - * @return True if is empty, False if is not. + * Return true if the cell is empty. + * + * This method checks if the cell is empty and returns true if it is, + * false if it contains a color (and thus has been played). + * @return true if the cell is empty, false otherwise. + * @see #isPlayed() */ - public boolean isEmpty(){ + public boolean isEmpty() { return this.state == Color.NIL; } - + /** - * This method returns if the cell has already played. - * @return True if the cell is already played, False if is not. + * Return true if the cell has been played. + * + * This method returns true if the cell has been played + * (i.e. it is not empty), false otherwise. + * @return true if the cell has been played, false otherwise. + * @see #isEmpty() */ - public boolean isPlayed(){ + public boolean isPlayed() { return !this.isEmpty(); } /** - * Return if the cell is playable. - * @return True if the current cell can be played with the condition of the gomoku. + * Return true if the cell can be played. + * + * This method checks if the cell can be played with the condition of the + * Gomoku game. A cell can be played if it is empty and at least one of its + * neighbours has been played. This is to ensure that the player is not + * playing in an empty area of the board. + * + * @return true if the cell can be played, false otherwise. + * @see #isEmpty() + * @see #isPlayed() */ - public boolean isPlayable(){ - if (!this.isEmpty()) return false; + public boolean isPlayable() { + // Check if the cell has been played, if so, it cannot be played + if (this.isPlayed()) return false; + + // Check if at least one neighbour has been played for (Cardinal c : Cardinal.values()) { GomokuCell current = this.getNeighbour(c); if (current != null && current.isPlayed()) return true; } + + // If no neighbours have been played, the cell cannot be played return false; } - - //------------------Methods-------------------------- + // - Methods ------------------------------------------ /** - * This method link the cell at the Cardinal position on the current cell. - * @param car The Cardinal direction of the cell to link. - * @param cell The GomokuCell to link. + * Link the current cell to the given cell, in the specified direction. + * + * This method adds a mapping between the current cell and the given cell in + * the specified direction in the neighbours map. This is used to create a + * link between the two cells, allowing for easy access to the neighbours of + * each cell. + * + * @param dir The Cardinal direction of the cell to link. + * @param cell The cell to link to. + * @see #getNeighbour(Cardinal) + * @see #link(GomokuCell, GomokuCell, Cardinal) */ - public void linkCell(Cardinal car, GomokuCell cell){ - this.neighbour.put(car, cell); + public void linkCell(Cardinal dir, GomokuCell cell) { + this.neighbours.put(dir, cell); } - - //------------------Statics-------------------------- + // - Static Methods ----------------------------------- - public static void link(GomokuCell c1, GomokuCell c2, Cardinal c1Toc2){ - if (c1 == null || c2 == null) return ; + /** + * Link two cells together in the specified direction. + * + * This method links two cells together in the specified direction. It + * creates a bidirectional link between the two cells. The first cell is + * linked to the second cell in the specified direction, and the second cell + * is linked to the first cell in the inverse direction. + * + * If either of the cells is null, the method does nothing. + * + * @param c1 The first cell to link. + * @param c2 The second cell to link. + * @param c1Toc2 The Cardinal direction from the first cell + * to the second cell. + */ + public static void link(GomokuCell c1, GomokuCell c2, Cardinal c1Toc2) { + if (c1 == null || c2 == null) return; + // Link the first cell to the second cell in the specified direction c1.linkCell(c1Toc2, c2); + // Link the second cell to the first cell in the inverse direction c2.linkCell(c1Toc2.inverse(), c1); } - //------------------Overides-------------------------- + // - Override Methods --------------------------------- + + /** + * Return a string representation of the cell. + * + * This method returns a string representation of the cell. The string + * representation is based on the state of the cell. + * + * @return The string representation of the cell. + */ @Override public String toString() { switch (this.getState()) { - case Color.NIL: - return "."; - case Color.BLACK: - return "X"; - case Color.WHITE: - return "O"; + case Color.NIL: return "."; + case Color.BLACK: return "X"; + case Color.WHITE: return "O"; default: throw new IllegalStateException("Unexpected value: " + this.getState()); }