Merge pull request #59 from teogor/bug-fix/cell-terminology

Improve Variable Naming for Clarity: `uniqueDigitsCount` & `totalCells`

sudoklify-common/api/sudoklify-common.api

@@ -220,6 +220,8 @@ public abstract class dev/teogor/sudoklify/common/types/SudokuType {
 	public final fun getGridSize ()Ldev/teogor/sudoklify/common/types/SudokuType$GridSize;
 	public final fun getHeight ()I
 	public final fun getName ()Ljava/lang/String;
+	public final fun getTotalCells ()I
+	public final fun getUniqueDigitsCount ()I
 	public final fun getWidth ()I
 	public final fun isSquare ()Z
 	public final fun toString ()Ljava/lang/String;

sudoklify-common/src/main/kotlin/dev/teogor/sudoklify/common/types/SudokuType.kt

@@ -21,8 +21,8 @@ package dev.teogor.sudoklify.common.types
  *
  * @property gridSize The size of the Sudoku grid (width and height).
  *
- * @property digits The total number of digits used in the Sudoku (width * height).
- * @property cells The total number of cells in the Sudoku (digits squared).
+ * @property uniqueDigitsCount The total number of digits used in the Sudoku (width * height).
+ * @property totalCells The total number of cells in the Sudoku (digits squared).
  * @property isSquare Whether the grid size is square (width == height).
  * @property width The width of the Sudoku grid.
  * @property height The height of the Sudoku grid.
@@ -34,14 +34,34 @@ sealed class SudokuType(
   val gridSize: GridSize,
 ) {
   /**
-   * The total number of digits used in the Sudoku (width * height).
+   * The number of distinct digits used in the Sudoku grid. This represents the total
+   * number of unique symbols that can be placed within a single cell of the Sudoku.
+   * It is calculated as the product of the grid width and height.
    */
-  val digits: Int = gridSize.width * gridSize.height
+  val uniqueDigitsCount: Int = gridSize.width * gridSize.height
+
+  @Deprecated(
+    message = """Consider using 'uniqueDigitsCount' for better clarity. This variable provides
+      |the same information but emphasizes the distinct nature of the digits used in the Sudoku
+      |grid.""",
+    replaceWith = ReplaceWith("uniqueDigitsCount"),
+  )
+  val digits: Int = uniqueDigitsCount
 
   /**
-   * The total number of cells in the Sudoku (digits squared).
+   * The total number of cells in the Sudoku grid. This is calculated by squaring the
+   * [uniqueDigitsCount]. Each cell within the grid can hold one of the [uniqueDigitsCount]
+   * distinct digits (or symbols).
    */
-  val cells: Int = digits * digits
+  val totalCells: Int = uniqueDigitsCount * uniqueDigitsCount
+
+  @Deprecated(
+    message = """Consider using 'totalCells' for better clarity. This variable represents the
+      |same information but emphasizes the total number of individual squares or cells within
+      |the Sudoku grid.""",
+    replaceWith = ReplaceWith("totalCells"),
+  )
+  val cells = totalCells
 
   /**
    * Whether the grid size is square (width == height).
@@ -51,12 +71,12 @@ sealed class SudokuType(
   /**
    * The width of the Sudoku grid.
    */
-  val width: Int = digits
+  val width: Int = uniqueDigitsCount
 
   /**
    * The height of the Sudoku grid.
    */
-  val height: Int = digits
+  val height: Int = uniqueDigitsCount
 
   /**
    * The width of a single box in the grid.
@@ -76,7 +96,7 @@ sealed class SudokuType(
   /**
    * Returns a string representation of the Sudoku type.
    */
-  final override fun toString(): String = "$width x $height ($digits digits)"
+  final override fun toString(): String = "$width x $height ($uniqueDigitsCount digits)"
 
   /**
    * Data class representing the size of a Sudoku grid.

sudoklify-core/src/main/kotlin/dev/teogor/sudoklify/core/generation/SudokuGenerator.kt

@@ -20,7 +20,6 @@ import dev.teogor.sudoklify.common.model.Sudoku
 import dev.teogor.sudoklify.common.model.SudokuBlueprint
 import dev.teogor.sudoklify.common.model.SudokuParams
 import dev.teogor.sudoklify.common.model.SudokuPuzzle
-import dev.teogor.sudoklify.common.types.Board
 import dev.teogor.sudoklify.common.types.Difficulty
 import dev.teogor.sudoklify.common.types.Layout
 import dev.teogor.sudoklify.common.types.Seed
@@ -44,13 +43,13 @@ internal class SudokuGenerator internal constructor(
   private val difficulty: Difficulty,
 ) {
   private val random: Random = seed.toRandom()
-  private val boxDigits = sudokuType.digits
+  private val boxDigits = sudokuType.uniqueDigitsCount
   private val baseLayout: Layout = generateBaseLayout()
   private val tokenizer: Tokenizer = Tokenizer.create(boxDigits)
 
   @Deprecated(
     message =
-      """
+    """
     This constructor is deprecated. Use the primary constructor
     `SudokuGenerator(seeds, seed, sudokuType, difficulty)` instead.
     """,
@@ -71,7 +70,7 @@ internal class SudokuGenerator internal constructor(
 
   @Deprecated(
     message =
-      """
+    """
     The composeSudokuPuzzle() method is deprecated. To create a Sudoku puzzle, use the more
     versatile and efficient createPuzzle() method, which returns a SudokuPuzzle object with
     additional features and utility methods. For compatibility with existing code,
@@ -122,7 +121,7 @@ internal class SudokuGenerator internal constructor(
     layout: Layout,
     seedSequence: String,
     tokenMap: TokenMap,
-  ): Board = tokenizer.populateLayout(layout, seedSequence, tokenMap)
+  ): Array<Array<String>> = tokenizer.populateLayout(layout, seedSequence, tokenMap)
 
   private fun getLayout(baseLayout: Layout): Layout = shuffleLayout(rotateLayout(baseLayout))
 
@@ -202,7 +201,7 @@ internal class SudokuGenerator internal constructor(
     size: Int,
   ): Array<SudokuBlueprint> =
     seeds.filter { seed ->
-      seed.sudokuType.digits == size
+      seed.sudokuType.uniqueDigitsCount == size
     }.toTypedArray()
 
   private fun getRandomItem(items: Array<SudokuBlueprint>): SudokuBlueprint =

sudoklify-core/src/main/kotlin/dev/teogor/sudoklify/core/io/SudokuParser.kt

@@ -34,7 +34,7 @@ class SudokuParser(
   sudokuType: SudokuType,
 ) {
   private val puzzleBoard = puzzle.toBoard(sudokuType)
-  private val boxDigits = sudokuType.cells
+  private val boxDigits = sudokuType.uniqueDigitsCount
 
   /**
    * Converts the Sudoku puzzle string into a numerical representation.

sudoklify-core/src/main/kotlin/dev/teogor/sudoklify/core/solver/SudokuSolver.kt

@@ -69,7 +69,7 @@ class SudokuSolver(
     for (row in grid.indices) {
       for (col in grid[row].indices) {
         if (grid[row][col] == 0) {
-          for (num in 1..sudokuType.cells) {
+          for (num in 1..sudokuType.uniqueDigitsCount) {
             if (isValid(grid, row, col, num)) {
               grid[row][col] = num
               steps.add(Pair(row, col))
@@ -95,7 +95,7 @@ class SudokuSolver(
     col: Int,
     num: Int,
   ): Boolean {
-    for (i in 0 until sudokuType.cells) {
+    for (i in 0 until sudokuType.totalCells) {
       if (grid[row][i] == num || grid[i][col] == num) return false
     }
 

sudoklify-core/src/main/kotlin/dev/teogor/sudoklify/core/util/BoardConversions.kt

@@ -61,7 +61,7 @@ fun SudokuString.toBoard(sudokuType: SudokuType): Board {
   val matchedTokens = ArrayList<String>()
   matches.forEach { matchedTokens.add(it.value) }
   return matchedTokens
-    .chunked(sudokuType.digits)
+    .chunked(sudokuType.uniqueDigitsCount)
     .map { row -> row.map { it }.toTypedArray() }
     .toTypedArray()
 }

sudoklify-ktx/src/main/kotlin/dev/teogor/sudoklify/ktx/SudokuBoardExtensions.kt

@@ -66,7 +66,7 @@ inline fun <T> List<List<T>>.mapToSudokuString(crossinline valueMapper: T.() ->
 @OptIn(InternalSudoklifyApi::class)
 fun String.mapToSudokuBoard(sudokuType: SudokuType): List<List<Int>> {
   return getCells()
-    .chunked(sudokuType.cells)
+    .chunked(sudokuType.uniqueDigitsCount)
     .map { row -> row.map { it.toInt() } }
 }
 
@@ -88,7 +88,7 @@ inline fun <T> String.mapToSudokuBoard(
   crossinline valueMapper: Int.() -> T,
 ): List<List<T>> {
   return getCells()
-    .chunked(sudokuType.cells)
+    .chunked(sudokuType.uniqueDigitsCount)
     .map { row -> row.map { valueMapper(it.toInt()) } }
 }
 
@@ -110,7 +110,7 @@ inline fun <T> String.mapIndexedToSudokuBoard(
   crossinline valueMapper: (value: Int, row: Int, column: Int) -> T,
 ): List<List<T>> {
   return getCells()
-    .chunked(sudokuType.cells)
+    .chunked(sudokuType.uniqueDigitsCount)
     .mapIndexed { row, rowElements ->
       rowElements.mapIndexed { column, value ->
         valueMapper(value.toInt(), row, column)

sudoklify-ktx/src/main/kotlin/dev/teogor/sudoklify/ktx/SudokuTypeExtensions.kt

@@ -23,13 +23,13 @@ import dev.teogor.sudoklify.common.types.SudokuType
  * Returns a list containing all valid digits (1 to [SudokuType.digits]) for the
  * Sudoku.
  */
-fun SudokuType.getAllDigits(): List<Int> = (1..digits).toList()
+fun SudokuType.getAllDigits(): List<Int> = (1..uniqueDigitsCount).toList()
 
 /**
  * Checks if a given digit is valid within the range of allowed digits for this Sudoku
  * (1 to [SudokuType.digits]).
  */
-fun SudokuType.isDigitValid(digit: Int): Boolean = digit in 1..digits
+fun SudokuType.isDigitValid(digit: Int): Boolean = digit in 1..uniqueDigitsCount
 
 /**
  * Returns the box index (within the range 0 to [SudokuType.boxes - 1]) for a given cell
@@ -265,7 +265,7 @@ private fun SudokuType.requireValidCellIndex(
   cellIndex: Int,
   message: String = "Invalid cell index",
 ) {
-  require(cellIndex in 0..<cells) {
+  require(cellIndex in 0..<totalCells) {
     "Invalid index ($cellIndex): $message"
   }
 }