Improve documentation

Author: cau777

README.md

@@ -10,6 +10,22 @@ step-by-step.
 * Algorithm made in Rust to solve puzzles in milliseconds
 * Step-by-step visualization of the solution with explanations
 
+## How the [algorithm](https://github.com/cau777/sudoku_solver/blob/master/wasm/src/sudoku_solver.rs) works
+It was inspired by some real-world Sudoku solving techniques, and aims to minimize guesses. The algorithm has a recursive 
+idea, but is actually implemented iteratively using a Stack, It also uses bitwise operations
+whenever possible to improve performance massively.
+1) Load the board from a string representation
+2) Search for cell whose value can be inferred. This is done in 2 ways:
+   * Sole candidate: when a cell can only contain one number, because all the other ones are already taken in the row/column/block.
+   * Unique candidate: when, in a row/column/block, a number can only be put in one cell. Because every number must appear
+once in every row/column/block, if only one cell can fit a determined number, it's definitely there.
+3) If the step 2 had success, complete that cell and do it again.
+4) Check if the board is complete, if so, return.
+5) Now, only guesses remain, so we have to find the cell with the least number of candidates.
+6) Guess a number on that cell and execute step 2 in the modified board.
+
+This [website](https://www.conceptispuzzles.com/index.aspx?uri=puzzle/sudoku/techniques) explains some of the logic.
+
 ## Screenshots
 * ![Empty board](https://github.com/cau777/sudoku_solver/blob/master/screenshots/empty_board.png)
 * ![Solution step](https://github.com/cau777/sudoku_solver/blob/master/screenshots/solution_step.png)

src/App.css

@@ -127,4 +127,9 @@ hr {
     border: none;
     outline: solid #4b9fd5 2px;
     background-color: #1F78B4;
+}
+
+.subtitle {
+    text-align: center;
+    font-weight: 500;
 }

src/App.tsx

@@ -12,6 +12,7 @@ function App() {
     let {t} = useTranslation();
 
     useEffect(() => {
+        // Translate the window title when the translation is loaded
         document.title = t("title");
     }, [t])
 

src/Message.ts

@@ -1,3 +1,4 @@
+// All the observations that the Wasm code can make about a cell
 export type Message =
     { t: "found", ms: number } |
     { t: "tried", num: number, row: number, col: number } |

src/SudokuBoard.tsx

@@ -27,6 +27,7 @@ export const SudokuBoard: React.FC<Props> = (props) => {
     ];
 
     for (let s = 0; s < size; s++) {
+        // Column number indicator
         firstRow.push(
             <td key={s} className={" block-row-start " + (s % blockSize === 0 ? " block-col-start " : "")}>
                 <CellBase highlighted={s === props.highlightCol}>
@@ -43,6 +44,7 @@ export const SudokuBoard: React.FC<Props> = (props) => {
         let blockRow = Math.floor(r / blockSize);
 
         let cells = [
+            // Row number indicator
             <td key={"row nums " + r} className={" block-col-start " +
                 (r % blockSize === 0 ? " block-row-start " : "")}>
                 <CellBase highlighted={props.highlightRow === r}>

src/SudokuController.tsx

@@ -96,11 +96,14 @@ export const SudokuController: React.FC<Props> = (props) => {
 
     function changeCurrentStep(index: number, steps: Step[]) {
         if (index < 0 || index >= steps.length) return;
+        // Translates the message using its key and other values as params
         let message = t(steps[index].message.t, {...steps[index].message});
 
         if (steps.length !== 1)
+            // If there are multiple messages, display the step number and then the message
             props.setLog(t("step", {num: index+1, message}));
         else
+            // If there's only one message, just display it
             props.setLog(message);
         setState(s => ({...s, currentStep: index, steps}));
     }
@@ -141,13 +144,15 @@ export const SudokuController: React.FC<Props> = (props) => {
                 <div>
                     <hr/>
                 </div>
+                <div className={"subtitle"}>{t("generate")}</div>
                 <button onClick={() => randomBoard(0.75)}>{t("generateRandomButton", {perc: 75})}</button>
                 <button onClick={() => randomBoard(0.50)}>{t("generateRandomButton", {perc: 50})}</button>
                 <button onClick={() => randomBoard(0.25)}>{t("generateRandomButton", {perc: 25})}</button>
                 <button onClick={() => randomBoard(0.1)}>{t("generateRandomButton", {perc: 10})}</button>
                 <div>
                     <hr/>
                 </div>
+                <div className={"subtitle"}>{t("solve")}</div>
 
                 {state.steps === null ?
                     <>

src/board.ts

@@ -1,12 +1,3 @@
-// export type Board = (number | null)[];
-//
-// export function defaultBoard(size: number) {
-//     return new Array(size).fill(null);
-// }
-//
-// export function setCell(board: Board, row: number, col: number, size: number, value: number | undefined) {
-//     board[row + "-" + col] =
-// }
 
 export class Board {
     readonly size: number;
@@ -16,10 +7,13 @@ export class Board {
         this.size = blockSize * blockSize;
     }
 
+    // Create an empty board
     public static default(blockSize: number) {
         return new Board(blockSize, new Array(blockSize * blockSize * blockSize * blockSize).fill(null))
     }
 
+    // A literal a continuous string representation of the board, in the format "1 2 3 _ _ 6 7 8 _"
+    // that can contain new lines
     public static fromLiteral(literal: string, blockSize: number) {
         let array = literal
             .replace("\n", " ")
@@ -40,10 +34,12 @@ export class Board {
         return this;
     }
 
+    // Deep copy of the object
     public copy() {
         return new Board(this.blockSize, [...this.cells]);
     }
 
+    // Converts the board to the format "1 2 3 _ _ 6 7 8 _"
     public toLiteral() {
         return this.cells.reduce((acc, value) => acc + (value ?? "_") + " ", "");
     }

src/i18n.ts

@@ -2,21 +2,23 @@ import i18next from "i18next";
 import {initReactI18next} from "react-i18next";
 import LanguageDetector from "i18next-browser-languagedetector";
 
+// Update the html lang attribute
 i18next.on("languageChanged", (lng) => document.documentElement.setAttribute("lang", lng));
 
 i18next
     .use(initReactI18next)
-    .use(LanguageDetector)
+    .use(LanguageDetector) // Uses the browser's language
     .init({
-        debug: true,
-        fallbackLng: "en",
+        debug: process.env.NODE_ENV !== "production",
+        fallbackLng: "en", // Defaults to English
         interpolation: {
-            escapeValue: false
+            escapeValue: false, // React automatically escapes values such as "<"
         },
+        // All the translations are contained in this file for simplicity
         resources: {
             en: {
                 translation: {
-                    "title": "Sudoku Solver",
+                    title: "Sudoku Solver",
                     wrongSolutionRow: "Your solution is wrong. See row {{row}}",
                     wrongSolutionCol: "Your solution is wrong. See column {{col}}",
                     wrongSolutionBlock: "Your solution is wrong. See block {{blockRow}},{{blockCol}}",
@@ -35,13 +37,15 @@ i18next
                     nextStepButton: "Next step",
                     next10StepsButton: "Next 10 steps",
                     step: "Step {{num}}: {{message}}",
-                    found: "Found solution in {{ms}}µ",
+                    found: "Found solution in {{ms}}µs",
                     tried: "Tried number {{num}} in {{row}},{{col}}",
                     gaveUp: "Gave up",
                     canContainOnly: "Cell {{row}},{{col}} can only contain number {{num}}",
                     numberOnlyFitsInRow: "Number {{num}} can only be placed in one cell in row {{row}}",
                     numberOnlyFitsInCol: "Number {{num}} can only be placed in one cell in col {{col}}",
                     numberOnlyFitsInBlock: "Number {{num}} can only be placed in one cell in block {{row}},{{col}}",
+                    generate: "Generate board",
+                    solve: "Solution",
                 }
             },
             "pt-BR": {
@@ -65,13 +69,15 @@ i18next
                     nextStepButton: "Avançar passo",
                     next10StepsButton: "Avançar 10 passos",
                     step: "Passo {{num}}: {{message}}",
-                    found: "Solução encontrada em {{ms}}µ",
+                    found: "Solução encontrada em {{ms}}µs",
                     tried: "Tentar número {{num}} em {{row}},{{col}}",
                     gaveUp: "Desistir",
                     canContainOnly: "Casa {{row}},{{col}} apenas pode conter o número {{num}}",
                     numberOnlyFitsInRow: "O número {{num}} apenas pode ser colocado em uma casa na linha {{row}}",
                     numberOnlyFitsInCol: "O número {{num}} apenas pode ser colocado em uma casa na coluna {{col}}",
                     numberOnlyFitsInBlock: "O número {{num}} apenas pode ser colocado em uma casa no bloco {{row}},{{col}}",
+                    generate: "Gerar tabuleiro",
+                    solve: "Solução",
                 }
             }
         }

wasm/src/lib.rs

@@ -47,7 +47,7 @@ fn solve_with_size<const SIZE: usize, const BLOCK_SIZE: usize>(board_literal: &s
 
     for step in solver.steps {
         steps.push(object! {
-            message: step.message.to_object(),
+            message: step.message.into_object(),
             highlightRow: step.highlight_row,
             highlightCol: step.highlight_col,
             highlightBlock: step.highlight_block.map(|[a, b]| array![a, b]),
@@ -57,7 +57,7 @@ fn solve_with_size<const SIZE: usize, const BLOCK_SIZE: usize>(board_literal: &s
 
     let solution = result.unwrap().to_literal();
     steps.push(object! {
-        message: Message::Found(elapsed as u64).to_object(),
+        message: Message::Found(elapsed as u64).into_object(),
         highlightRow: JsonValue::Null,
         highlightCol: JsonValue::Null,
         highlightBlock: JsonValue::Null,

wasm/src/solve_report.rs

@@ -11,7 +11,7 @@ pub enum Message {
 }
 
 impl Message {
-    pub fn to_object(self) -> JsonValue {
+    pub fn into_object(self) -> JsonValue {
         use Message::*;
         match self {
             Found(ms) => object! {

wasm/src/sudoku_board.rs

@@ -5,6 +5,8 @@ use crate::util::Array2D;
 
 pub type DefaultBoard = SudokuBoard<9, 3>;
 
+/// Struct that keeps track of the numbers in the board and also what values are already used
+/// in each row/column/block
 #[derive(Clone, Eq, PartialEq)]
 pub struct SudokuBoard<const SIZE: usize, const BLOCK_SIZE: usize> {
     pub numbers: Array2D<Option<u8>, SIZE>,
@@ -31,16 +33,14 @@ impl<const SIZE: usize, const BLOCK_SIZE: usize> SudokuBoard<SIZE, BLOCK_SIZE> {
 
     pub fn set_number(&mut self, value: Option<u8>, row: usize, col: usize) {
         let prev = self.numbers[row][col];
-        if prev.is_some() {
-            let val = prev.unwrap();
+        if let Some(val) = prev {
             self.rows[row].remove_number(val);
             self.cols[col].remove_number(val);
             self.blocks[row / BLOCK_SIZE][col / BLOCK_SIZE].remove_number(val);
             self.numbers[row][col] = None;
         }
 
-        if value.is_some() {
-            let val = value.unwrap();
+        if let Some(val) = value {
             self.rows[row].add_number(val);
             self.cols[col].add_number(val);
             self.blocks[row / BLOCK_SIZE][col / BLOCK_SIZE].add_number(val);
@@ -60,9 +60,9 @@ impl<const SIZE: usize, const BLOCK_SIZE: usize> SudokuBoard<SIZE, BLOCK_SIZE> {
         let mut board = SudokuBoard::new();
 
         literal
-            .replace('\n', &" ")
-            .split(" ")
-            .filter(|o| o.len() != 0)
+            .replace('\n', " ")
+            .split(' ')
+            .filter(|o| !o.is_empty())
             .enumerate()
             .for_each(|(index, o)| {
                 board.set_number(u8::from_str(o).ok(), index / SIZE, index % SIZE)
@@ -71,6 +71,8 @@ impl<const SIZE: usize, const BLOCK_SIZE: usize> SudokuBoard<SIZE, BLOCK_SIZE> {
         board
     }
 
+    /// Return a more compact representation of the board, in the format "1 2 3 _ _ 6 7 8 _"
+    /// without newlines
     pub fn to_literal(&self) -> String {
         let mut result = String::new();
         for row in &self.numbers {
@@ -91,10 +93,10 @@ impl<const SIZE: usize, const BLOCK_SIZE: usize> SudokuBoard<SIZE, BLOCK_SIZE> {
         let mut board = SudokuBoard::new();
 
         for (index, number) in literal
-            .replace('\n', &" ")
-            .split(" ")
-            .filter(|o| o.len() != 0)
-            .map(|o| u8::from_str(o))
+            .replace('\n', " ")
+            .split(' ')
+            .filter(|o| !o.is_empty())
+            .map(u8::from_str)
             .enumerate()
             .filter(|(_, o)| o.is_ok())
             .map(|(index, o)| (index, o.unwrap())) {
@@ -132,14 +134,19 @@ impl<const SIZE: usize, const BLOCK_SIZE: usize> SudokuBoard<SIZE, BLOCK_SIZE> {
         true
     }
 
+    /// Returns a readable representation of the board
     pub fn board_to_string(&self) -> String {
         let mut result = String::new();
         result += "  ---------------------\n";
 
         for row in 0..SIZE {
             result += &format!("{} | ", row);
             for col in 0..SIZE {
-                result += &(self.numbers[row][col].map(|x| x.to_string()).unwrap_or("_".to_owned()).to_string() + " ");
+                match self.numbers[row][col] {
+                    Some(x) => result += &x.to_string(),
+                    None => result += "_",
+                }
+                result += " ";
             }
             result += "|\n";
         }
@@ -160,11 +167,6 @@ impl<const SIZE: usize, const BLOCK_SIZE: usize> Debug for SudokuBoard<SIZE, BLO
 mod tests {
     use crate::sudoku_board::{DefaultBoard};
 
-    #[test]
-    fn util() {
-        assert!(true);
-    }
-
     #[test]
     fn empty_board() {
         let board = DefaultBoard::new();