Improved accuracy and reliability of BoardCell conversions with comprehensive testing

[teogor]

This pull request addresses an issue with the BoardCell encoding and decoding functions where digits containing 0 were not handled correctly.

Specifically, the fix addresses:
- toInt(): Ensures that the 'J' character is correctly decoded as 0.
- toBoardCell(): Handles cases where the integer is composed of digits containing 0 (e.g., 10, 20, etc.).

Additionally, this PR introduces unit tests to verify the corrected behavior and ensure future changes maintain the expected functionality.

Using the fixed functions:

Once you've implemented the fixes in toBoardCell() and toInt(), you can use them directly in your code like this:

// Convert an integer to its BoardCell representation:
val cellValue = 20
val cellRepresentation = cellValue.toBoardCell() // Expected output: "Bj"

// Convert a BoardCell string back to an integer:
val cellString = "Aj"
val intValue = cellString.toInt() // Expected output: 10

// Check if an integer matches its BoardCell representation:
val number = 10
if (number == cellString.toInt()) {
  println("Number $number matches its BoardCell representation: $cellString")
}

[teogor]

Algorithm J-Encoding For Sudoku Cells

Encoding:

1. Split: Convert the integer representing the cell value into a string.
2. Map: Iterate through each character (digit) in the string:
   • For digits 1-9, assign the corresponding letter 'a' to 'i' (a = 1, b = 2, etc.).
   • For digit 0, assign the letter 'j'.
3. Format: Uppercase the first character in the resulting string.

Decoding:

1. Map: Process each character (letter) in the BoardCell string:
   • For letters 'a' to 'i', convert them to their corresponding digits (a = 1, b = 2, etc.).
   • For letter 'j', convert it to 0.
2. Combine: Join the converted digits into a single integer, representing the decoded cell value.

Example:

Encoding:

• Input: Integer 230
• Steps:
  1. Convert to string: '2', '3', '0'
  2. Map digits: 'b', 'c', 'j'
  3. Uppercase first: 'B', 'c', 'j'
• Output: String "Bcj"

Decoding:

• Input: String "Bcj"
• Steps:
  1. Split into characters: ## Algorithm Explanation: BoardCell Encoding and Decoding

Encoding:

1. Split: Convert the integer representing the cell value into a string.
2. Map: Iterate through each character (digit) in the string:
   • For digits 1-9, assign the corresponding letter 'a' to 'i' (a = 1, b = 2, etc.).
   • For digit 0, assign the letter 'j'.
3. Format: Uppercase the first character in the resulting string.

Decoding:

1. Map: Process each character (letter) in the BoardCell string:
   • For letters 'a' to 'i', convert them to their corresponding digits (a = 1, b = 2, etc.).
   • For letter 'j', convert it to 0.
2. Combine: Join the converted digits into a single integer, representing the decoded cell value.

Example:

Encoding:

• Input: Integer 230
• Steps:
  1. Convert to string: '2', '3', '0'
  2. Map digits: 'b', 'c', 'j'
  3. Uppercase first: 'B', 'c', 'j'
• Output: String "Bcj"

Decoding:

• Input: String "Bcj"
• Steps:
  1. Split into characters: 'B', 'c', 'j'
  2. Map letters: 2, 3, 0
  3. Join digits: 230
• Output: Integer 230

View the J-Encoding algorithm documentation: source.teogor.dev/sudoklify/j-encoding-for-sudoku-cells