Merge pull request #13 from ArjArav98/refactor_to_c++_17

Rewrite in C++17 and add functionality

Author: ArjArav98

README.md

@@ -1,63 +1,225 @@
-# Introduction
-These are a suite of C++ programs which deal with Sudoku Puzzles. The name might be misleading, yes, but these programs don't just solve Sudoku puzzles, they also achieve other objectives such as Sudoku Puzzle Validation and Sudoku Puzzle Generation (Under development).
+# Sudoku-Suite
+A C++17-compatible header that provides useful functions which help with the solving, validation and generation of 9x9 Sudoku puzzles. 
 
 ## Contents
-* [Sudoku Solver](#sudoku-solver)
-    * [Getting Started (Usage)](#getting-started)
-    * [How It Works](#how-it-works)
-* [Sudoku Validator](#sudoku-validator)
-    * [Getting Started (Usage)](#getting-started-1)
-    * [How It Works](#how-it-works-1)
+* [Usage](#usage)
+* [Documentation](#documentation)
+* [Examples](#examples)
+    * [Solving and validating a Sudoku puzzle](#solving-and-validating-sudoku-puzzle)
+    * [Generating a Sudoku puzzle](#generating-a-sudoku-puzzle)
+    * [Initialising and reusing Grid objects](#initialising-and-reusing-grid-objects)
+    * [Reading Sudoku puzzles from a file](#reading-sudoku-puzzles-from-a-file)
+    * [Operations on Grid objects](#operations-on-grid-objects)
+* [How It Works](#sudoku-solver---how-it-works)
 * [Acknowledgements](#acknowledgements)
 * [Tools](#tools)
 
-# Sudoku-Solver
-This is a program which solves 9x9 Sudoku puzzles. **Written completely in C++** and **built wholly from scratch**, this program reads input either from a user or from a file containing the Sudoku values and solves the puzzle. It employs concepts such as backtracking and recursion.
-
-### Getting Started
-* Simply download the ```sudoku-solver.cpp``` file found in the ```Sudoku-Solver/``` directory. Run it using any standard C++ compiler. In case of any errors or compatibility issues, submit an issue in this git.
-* Once downloaded, compiled and run; the program will require the user to input the Sudoku puzzle into it. There are two ways to do this.
-    * The user can either input the values manually one-by-one when the program is running.
-    * The user can write all the values into a file, seperated by whitespaces. The file can have any name or extension. When the program is running, the user will be prompted to simply enter the name of the file (with extension). **Below** is an example of how the contents of such a file might look. Look at the ```sample.txt``` files in the same directory for more examples.
+## Usage 
+
+* Simply download the `src/sudoku_suite.h` file and move it to your project's directory.
+* Include the header file, as shown below in the examples, and use the functions you need!
+* **NOTE:** The code is incompatible with pre-C++17 versions. While compiling, you'll have to compile with the `--std=c++17` flag.
+    * For example; when using the clang compiler, the compile command would be `c++ --std=c++17 /path/to/file.cpp`
+
+## Documentation
+
+There are **three functions** that Sudoku-Suite provides the developer, along with **one class**. They are as follows:-
+
+* `Grid`
+    *  An object that represents a 9x9 Sudoku grid. The `Grid` object does not validate the grid in any way, i.e, it only holds the grid and values inside it.
+    * While initialising, if the given values are invalid, an `std::invalid_argument` exception is thrown.
+    * *Check out the examples below to see how we can initialise and use this object!*
+* `void solve(Grid *grid)`
+    *  A function that takes in a pointer to a `Grid` object and solves the Sudoku puzzle present in it. Returns nothing.
+    * If the puzzle cannot be solved, a `std::logic_error` exception is thrown.
+* `bool is_valid_solution(Grid &grid)`
+    *  A function that takes in a `Grid` object and returns a `bool` with a value of `true` if the `Grid` object contains a finished and valid Sudoku solution. 
+* `Grid generate_puzzle()`
+    *  A function that takes in nothing and returns a `Grid` object containing an unfinished Sudoku puzzle.
+
+## Examples
+
+**NOTE:** The following examples are also present in the repository in the `samples/` directory.
+
+* [Solving and validating a Sudoku puzzle](#solving-and-validating-sudoku-puzzle)
+* [Generating a Sudoku puzzle](#generating-a-sudoku-puzzle)
+* [Initialising and reusing Grid objects](#initialising-and-reusing-grid-objects)
+* [Reading Sudoku puzzles from a file](#reading-sudoku-puzzles-from-a-file)
+* [Operations on Grid objects](#operations-on-grid-objects)
+
+#### Solving and validating Sudoku puzzle
+```
+#include<iostream>
+#include"/path/to/sudoku_suite.h"
+
+int main() {
+    sudoku::Grid grid({{
+        {{ 0, 0, 0, 0, 0, 0, 6, 8, 0 }}, // The 0s represent blank cells.
+        {{ 0, 0, 0, 0, 7, 3, 0, 0, 9 }},
+        {{ 3, 0, 9, 0, 0, 0, 0, 4, 5 }},
+        {{ 4, 9, 0, 0, 0, 0, 0, 0, 0 }},
+        {{ 8, 0, 3, 0, 5, 0, 9, 0, 2 }},
+        {{ 0, 0, 0, 0, 0, 0, 0, 3, 6 }},
+        {{ 9, 6, 0, 0, 0, 0, 3, 0, 8 }},
+        {{ 7, 0, 0, 6, 8, 0, 0, 0, 0 }},
+        {{ 0, 2, 8, 0, 0, 0, 0, 0, 0 }}
+    }});
+
+    sudoku::solve(&grid);
+
+    std::cout << "Solution is valid? --> ";
+    std::cout << sudoku::is_valid_solution(grid) << std::endl;
+    
+    std::cout << grid << std::endl;
+
+    return 0;
+}
+```
+
+#### Generating a Sudoku puzzle 
+```
+#include<iostream>
+#include"/path/to/sudoku_suite.h"
+
+int main() {
+    sudoku::Grid grid = sudoku::generate_puzzle();
+    std::cout << grid << std::endl;
+
+    return 0;
+}
+```
+
+#### Initialising and reusing Grid objects 
+```
+#include<iostream>
+#include"/path/to/sudoku_suite.h"
+
+int main() {
+    //================
+    // Method 1: Use the constructor and pass in a
+    // 2D matrix of values.
+    //================
+    
+    sudoku::Grid grid({{
+        {{ 0, 0, 0, 0, 0, 0, 6, 8, 0 }},
+        {{ 0, 0, 0, 0, 7, 3, 0, 0, 9 }},
+        {{ 3, 0, 9, 0, 0, 0, 0, 4, 5 }},
+        {{ 4, 9, 0, 0, 0, 0, 0, 0, 0 }},
+        {{ 8, 0, 3, 0, 5, 0, 9, 0, 2 }},
+        {{ 0, 0, 0, 0, 0, 0, 0, 3, 6 }},
+        {{ 9, 6, 0, 0, 0, 0, 3, 0, 8 }},
+        {{ 7, 0, 0, 6, 8, 0, 0, 0, 0 }},
+        {{ 0, 2, 8, 0, 0, 0, 0, 0, 0 }}
+    }});
+    std::cout << grid << std::endl;
+    
+    //================
+    // Method 2: Declare a 2D matrix of values and pass it
+    // into the set_initial_state() method.
+    //================
+
+    std::array<std::array<int, 9>, 9> values = {{
+        {{ 9, 7, 8, 4, 1, 0, 0, 0, 5 }},
+        {{ 3, 0, 0, 8, 0, 0, 0, 6, 4 }},
+        {{ 6, 0, 0, 3, 5, 0, 0, 9, 0 }},
+        {{ 2, 6, 9, 0, 3, 0, 0, 0, 7 }},
+        {{ 5, 0, 7, 1, 0, 0, 0, 0, 0 }},
+        {{ 1, 0, 3, 0, 0, 2, 0, 8, 9 }},
+        {{ 7, 1, 0, 2, 0, 5, 0, 0, 3 }},
+        {{ 0, 0, 2, 7, 0, 3, 1, 5, 8 }},
+        {{ 0, 0, 5, 9, 4, 1, 0, 0, 0 }}
+    }};
+    grid.set_initial_state(values);
+    std::cout << grid << std::endl;
+
+    //================
+    // Method 3: Read the initial state of the puzzle
+    // from a file.
+    //================
     
-        ```
-        0 0 0  0 0 0  6 8 0
-        0 0 0  0 7 3  0 0 9
-        3 0 9  0 0 0  0 4 5
-        
-        4 9 0  0 0 0  0 0 0
-        8 0 3  0 5 0  9 0 2
-        0 0 0  0 0 0  0 3 6
-        
-        9 6 0  0 0 0  3 0 8
-        7 0 0  6 8 0  0 0 0
-        0 2 8  0 0 0  0 0 0
-        ```
-
-* Once solved, the Sudoku puzzles shall be displayed like this.
-    ```
-    ++=====================================++
-    || 1   7   2 || 5   4   9 || 6   8   3 ||
-    ++-----------++-----------++-----------++
-    || 6   4   5 || 8   7   3 || 2   1   9 ||
-    ++-----------++-----------++-----------++
-    || 3   8   9 || 2   6   1 || 7   4   5 ||
-    ++=====================================++
-    || 4   9   6 || 3   2   7 || 8   5   1 ||
-    ++-----------++-----------++-----------++
-    || 8   1   3 || 4   5   6 || 9   7   2 ||
-    ++-----------++-----------++-----------++
-    || 2   5   7 || 1   9   8 || 4   3   6 ||
-    ++=====================================++
-    || 9   6   4 || 7   1   5 || 3   2   8 ||
-    ++-----------++-----------++-----------++
-    || 7   3   1 || 6   8   2 || 5   9   4 ||
-    ++-----------++-----------++-----------++
-    || 5   2   8 || 9   3   4 || 1   6   7 ||
-    ++=====================================++
-    ```
-
-### How It Works
+    grid.set_initial_state_from_file("path/to/sample1.txt");
+    std::cout << grid << std::endl;
+
+    return 0;
+}
+```
+
+#### Reading Sudoku puzzles from a file 
+
+File: `sample1.txt`
+```
+5 3 0 0 7 0 0 0 0
+6 0 0 1 9 5 0 0 0
+0 9 8 0 0 0 0 6 0
+8 0 0 0 6 0 0 0 3
+4 0 0 8 0 3 0 0 1
+7 0 0 0 2 0 0 0 6
+0 6 0 0 0 0 2 8 0
+0 0 0 4 1 9 0 0 5
+0 0 0 0 8 0 0 7 9
+```
+
+```
+#include<iostream>
+#include"/path/to/sudoku_suite.h"
+
+int main() {
+    sudoku::Grid grid;
+    grid.set_initial_state_from_file("sample1.txt");
+    std::cout << grid << std::endl;
+
+    sudoku::solve(&grid);
+    std::cout << grid << std::endl;
+
+    return 0;
+}
+```
+
+#### Operations on Grid objects 
+```
+#include<iostream>
+#include"/path/to/sudoku_suite.h"
+
+int main() {
+
+    sudoku::Grid sample_grid_1({{
+        {{ 1, 7, 2, 5, 4, 9, 6, 8, 3 }},
+        {{ 6, 4, 5, 8, 7, 3, 2, 1, 9 }},
+        {{ 3, 8, 9, 2, 6, 1, 7, 4, 5 }},
+        {{ 4, 9, 6, 3, 2, 7, 8, 5, 1 }},
+        {{ 8, 1, 3, 4, 5, 6, 9, 7, 2 }},
+        {{ 2, 5, 7, 1, 9, 8, 4, 3, 6 }},
+        {{ 9, 6, 4, 7, 1, 5, 3, 2, 8 }},
+        {{ 7, 3, 1, 6, 8, 2, 5, 9, 4 }},
+        {{ 5, 2, 8, 9, 3, 4, 1, 6, 7 }}
+    }});
+    
+    sudoku::Grid sample_grid_2({{
+        {{ 1, 7, 2, 5, 4, 9, 6, 8, 3 }},
+        {{ 6, 4, 5, 8, 7, 3, 2, 1, 9 }},
+        {{ 3, 8, 9, 2, 6, 1, 7, 4, 5 }},
+        {{ 4, 9, 6, 3, 2, 7, 8, 5, 1 }},
+        {{ 8, 1, 3, 4, 5, 6, 9, 7, 2 }},
+        {{ 2, 5, 7, 1, 9, 8, 4, 3, 6 }},
+        {{ 9, 6, 4, 7, 1, 5, 3, 2, 8 }},
+        {{ 7, 3, 1, 6, 8, 2, 5, 9, 4 }},
+        {{ 5, 2, 8, 9, 3, 4, 1, 6, 7 }}
+    }});
+
+    if (sample_grid_1 == sample_grid_2) std::cout << "They're the same! \n\n";
+
+    // Get grid value for coordinate.
+    std::pair<int, int> last_coord = std::make_pair(8, 8);
+    int last_value = sample_grid_1.get(last_coord);
+
+    // Print the grid to the console.
+    std::cout << sample_grid_2 << std::endl;
+
+    return 0;
+}
+```
+
+### Sudoku Solver - How It Works
 This particular algorithm employs the use of backtracking, one of the more common methods to solve Sudoku puzzles. I've written a simple algorithm to give an idea of how the program works.
 
 1. Start.
@@ -69,47 +231,6 @@ This particular algorithm employs the use of backtracking, one of the more commo
 7. The puzzle has now been solved.
 8. Stop.
 
-# Sudoku Validator
-This is a program which validates solutions for 9x9 Sudoku puzzles. **Written completely in C++** and **built wholly from scratch**, this program takes in input from the user or from a file containing the values. It then validates the puzzle and then displays whether it is a valid solution or not.
-
-### Getting Started
-* Simply download the ```sudoku-validator.cpp``` file found in the ```Sudoku-Validator``` directory. Run it using any standard C++ compiler. In case of any errors or compatibility issues, submit an issue in this git.
-* Once downloaded, compiled and run; the program will require the user to input the Sudoku puzzle into it. There are two ways to do this.
-    * The user can either input the values manually one-by-one when the program is running.
-    * The user can write all the values into a file, seperated by whitespaces. The file can have any name or extension. When the program is running, the user will be prompted to simply enter the name of the file (with extension). **Below** is an example of how the contents of such a file might look. Look at the ```sample.txt``` files in the same directory for more examples.
-    
-        ```
-        8 4 6  9 3 7  1 5 2
-        3 1 9  6 2 5  8 4 7
-        7 5 2  1 8 4  9 6 3
-        
-        2 8 5  7 1 3  6 9 4
-        4 6 3  8 5 9  2 7 1
-        9 7 1  2 4 6  3 8 5
-        
-        1 2 7  5 9 8  4 3 6
-        6 3 8  4 7 1  5 2 9
-        5 9 4  3 6 2  7 1 8
-        ```
-
-
-### How It Works
-The workings of the Sudoku Validator are quite simple, to be honest. Here's a simple algorithm explaining them all.
-
-1. Start
-2. The values in all the cells are checked to see if they are in the range 1-9. If not, the puzzle is invalid.
-3. Every row is checked to see if it contains 1-9 atleast once. If not, the solution is invalid.
-4. Every column is checked to see if it contains 1-9 atleast once. If not, the solution is invalid.
-4. Every 3x3 grid is checked to see if it contains 1-9 atleast once. If not, the solution is invalid.
-5. If all the criteria have been satisfied, the solution is valid.
-6. Stop
-
-## Future Direction
-
-* Right now, the Sudoku Solver Suite is just a CLI application with a I/O interface. However, if we could make it into a CLI utility which takes in inputs through parameters and switches, that would make it easier for other developers to reuse.
-* I was thinking we could write a "backend" which could then be called by various "interface frontends". The backend is written in C++ and the frontends could be shell or maybe an API or something.
-* The objective would be for this to be used by web backends and things like that.
-
 ## Acknowledgements
 
 * Shriram R - Idea Inspiration