From 47fe1a7d472071550ceb531cf75751a9ff6f3cfe Mon Sep 17 00:00:00 2001 From: Hugo Dimitrijevic Date: Wed, 3 Apr 2024 20:54:46 +0200 Subject: [PATCH] ajout doc modele --- .../main/java/fr/iutfbleau/sae/GameModel.java | 214 +++++++++++++++--- 1 file changed, 183 insertions(+), 31 deletions(-) diff --git a/app/src/main/java/fr/iutfbleau/sae/GameModel.java b/app/src/main/java/fr/iutfbleau/sae/GameModel.java index b007479..4d53876 100644 --- a/app/src/main/java/fr/iutfbleau/sae/GameModel.java +++ b/app/src/main/java/fr/iutfbleau/sae/GameModel.java @@ -7,30 +7,62 @@ import java.util.HashSet; import java.util.Map; import java.util.Set; - +/** + * {@code GameModel} is a class that represents the state of the game. + * + * @autor Alexeï Kadir, Lyanis Souidi, Hugo Dimitrijevic + * @version 1.0 + */ public class GameModel { - + /** + * The {@code Map} of {@code Cell}s to the {@code Set} of {@code Line}s that + * intersect them. + */ private final Map> cells; - + /** + * The {@code Set} of {@code Line}s that have been drawn. + */ private final Set lines; - + /** + * The size of the initial cross. + */ private int size; - + /** + * Whether the game is in hard mode. In hard mode, {@code Line}s cannot extend + * each other. + */ private boolean hardMode; - + /** + * The number of unique valid {@code Line}s that can be drawn. + */ private int validLineCount; - + /** + * The start of the {@code Line} being drawn. If this is {@code null}, no + * {@code Line} is + * being drawn. + */ private Cell inputLineStart; - + /** + * The end of the {@code Line} being drawn. If this is {@code null}, no + * {@code Line} is + * being drawn. + */ private Cell inputLineEnd; - + /** + * Constructs a new {@code GameModel} with the specified size, and whether the + * game is in + * hard mode. + * + * @param size The size of the initial cross. + * @param hardMode Whether the game is in hard mode. + */ public GameModel(int size, boolean hardMode) { this.cells = new HashMap>(); this.lines = new HashSet(); @@ -40,7 +72,14 @@ public class GameModel { this.hardMode = hardMode; } - + /** + * Resets the grid, and initializes a new game with a cross of the specified + * size. This call does not recount the number of valid {@code Line}s that can + * be + * drawn. + * + * @param size The size of the initial cross. + */ private void resetGrid(int size) { if ((size + 2) % 3 != 0) throw new IllegalArgumentException("Invalid size."); @@ -66,7 +105,14 @@ public class GameModel { this.fillCells(side * 2 - 2, side * 2 - 2, 1, side); } - + /** + * Recounts the number of valid {@code Line}s that can be drawn. This call + * iterates over all + * {@code Cell}s in the grid, and finds all unique valid {@code Line}s that + * intersect them. This call is expensive, and should be used sparingly. The + * line count is updated when lines are added by the user, so this call is only + * necessary when the grid is reset. + */ private void recountValidLines() { this.validLineCount = 0; @@ -78,29 +124,55 @@ public class GameModel { this.validLineCount = validLines.size(); } - + /** + * Returns the number of unique valid {@code Line}s that can be drawn. + * + * @return The number of unique valid {@code Line}s that can be drawn. + */ public int getValidLineCount() { return this.validLineCount; } - + /** + * Returns whether the game is finished. The game is finished when all valid + * {@code Line}s have been drawn. + * + * @return {@code true} if the game is finished, {@code false} otherwise. + */ public boolean isGameFinished() { return this.validLineCount == 0; } - + /** + * Returns the score of the game. The score is the number of {@code Line}s that + * have been drawn. + * + * @return The score of the game. + */ public int getScore() { return this.lines.size(); } - + /** + * Resets the grid, and initializes a new game with a cross of the specified + * size. + * + * @param size The size of the initial cross. + */ public void reset(int size) { this.resetGrid(size); this.recountValidLines(); } - + /** + * Resets the grid, and initializes a new game with a cross of the specified + * size, and the specified set of {@code Line}s. These {@code Line}s are added + * without checking for validity. + * + * @param size The size of the initial cross. + * @param lines The set of {@code Line}s to add to the grid. + */ public void reset(int size, Set lines) { this.resetGrid(size); @@ -119,12 +191,20 @@ public class GameModel { this.recountValidLines(); } - + /** + * Returns the size of the cross. + * + * @return The size of the cross. + */ public int getSize() { return this.size; } - + /** + * Returns a copy of the {@code Set} of {@code Cell}s in the grid. + * + * @return A copy of the {@code Set} of {@code Cell}s in the grid. + */ public Set getCells() { Set cells = new HashSet(); @@ -134,7 +214,11 @@ public class GameModel { return cells; } - + /** + * Returns a copy of the {@code Set} of {@code Line}s that have been drawn. + * + * @return A copy of the {@code Set} of {@code Line}s that have been drawn. + */ public Set getLines() { Set lines = new HashSet(); @@ -144,13 +228,23 @@ public class GameModel { return lines; } - + /** + * Starts drawing a {@code Line} at the specified {@code Cell}. + * + * @param start The {@code Cell} where the {@code Line} starts. + */ public void startInputLine(Cell start) { this.inputLineStart = new Cell(start); this.inputLineEnd = new Cell(start); } - + /** + * Moves the end of the {@code Line} being drawn to the specified {@code Cell}. + * + * @param end The {@code Cell} where the {@code Line} ends. + * @return {@code true} if the end of the {@code Line} was moved, {@code false} + * otherwise. + */ public boolean moveInputLineEnd(Cell end) { if (this.inputLineStart == null) return false; @@ -162,7 +256,15 @@ public class GameModel { return changed; } - + /** + * Ends drawing a {@code Line} at the specified {@code Cell}. If the + * {@code Line} + * is valid, it is added to the grid, and the {@code Cell}s it intersects are + * updated. If the {@code Line} is not valid, it is discarded. The number of + * unique valid {@code Line}s that can be drawn is updated as well. + * + * @param end The {@code Cell} where the {@code Line} ends. + */ public void endInputLine(Cell end) { if (this.inputLineStart == null) return; @@ -205,27 +307,54 @@ public class GameModel { this.inputLineEnd = null; } - + /** + * Returns whether a {@code Line} is being drawn. + * + * @return {@code true} if a {@code Line} is being drawn, {@code false} + * otherwise. + */ public boolean hasInputLine() { return this.inputLineStart != null; } - + /** + * Returns whether the {@code Line} being drawn is valid. + * + * @return {@code true} if the {@code Line} being drawn is valid, {@code false} + * otherwise. + */ public boolean isInputLineValid() { return this.isLineValid(this.inputLineStart, this.inputLineEnd); } - + /** + * Returns the {@code Cell} where the {@code Line} being drawn starts. + * + * @return The {@code Cell} where the {@code Line} being drawn starts. + */ public Cell getInputLineStart() { return new Cell(this.inputLineStart); } - + /** + * Returns the {@code Cell} where the {@code Line} being drawn ends. + * + * @return The {@code Cell} where the {@code Line} being drawn ends. + */ public Cell getInputLineEnd() { return new Cell(this.inputLineEnd); } - + /** + * Returns whether the {@code Line} between the specified {@code Cell}s is + * valid. A {@code Line} is valid if it is horizontal, vertical, or diagonal, + * and intersects exactly four {@code Cell}s. In hard mode, {@code Line}s + * cannot extend each other. + * + * @param start The {@code Cell} where the {@code Line} starts. + * @param end The {@code Cell} where the {@code Line} ends. + * @return {@code true} if the {@code Line} is valid, {@code false} otherwise. + */ public boolean isLineValid(Cell start, Cell end) { if (!Line.isValid(start, end)) return false; @@ -266,7 +395,14 @@ public class GameModel { return true; } - + /** + * Finds all unique valid {@code Line}s that intersect the specified + * {@code Cell}, + * and adds them to the specified {@code Set}. + * + * @param cell The {@code Cell} to check for intersections. + * @param lines The {@code Set} to add the valid {@code Line}s to. + */ private void findValidLines(Cell cell, Set lines) { for (int i = 0; i < 5; i++) { Cell start = new Cell(cell.x - 4 + i, cell.y); @@ -295,19 +431,35 @@ public class GameModel { } } - + /** + * Fills the specified rectangle of {@code Cell}s. + * + * @param x The x-coordinate of the top-left corner of the rectangle. + * @param y The y-coordinate of the top-left corner of the rectangle. + * @param w The width of the rectangle. + * @param h The height of the rectangle. + */ private void fillCells(int x, int y, int w, int h) { for (int dx = 0; dx < w; dx++) for (int dy = 0; dy < h; dy++) this.placeCell(x + dx, y + dy); } - + /** + * Places a {@code Cell} in the grid. + * + * @param x The x-coordinate of the {@code Cell}. + * @param y The y-coordinate of the {@code Cell}. + */ private void placeCell(int x, int y) { this.placeCell(new Cell(x, y)); } - + /** + * Places a {@code Cell} in the grid. + * + * @param cell The {@code Cell} to place. + */ private void placeCell(Cell cell) { if (this.cells.containsKey(cell)) return;