# Sudokugen
Sudoku puzzle solver and generator library.
Sudokugen can find a solution to a valid puzzle using a mixture of basic strategies
and bruteforce. It can also generate new minimal puzzles.
This library was built as a rust learning project for myself.
Read the documentation and explore the crate on [docs.rs/sudokugen](https://docs.rs/sudokugen)
## How to use Sudokugen
Sudokugen two structures to parse, manipulate and display sudoku board and puzzles.
The [Board](https://docs.rs/sudokugen/0.2.0/sudokugen/board/struct.Board.html) structure allows you to parse a board from a string, display it and try to solve it.
The [Puzzle](https://docs.rs/sudokugen/0.2.0/sudokugen/solver/generator/struct.Puzzle.html) strucutre contains the information relevant for a new puzzle, the initial board and it's solution.
You can parse a puzzle from a string:
```rust
use sudokugen::Board;
let board: Board = "
. . . | 4 . . | 8 7 .
4 . 3 | . . . | . . .
2 . . | . . 3 | . . 9
---------------------
. . 6 | 2 . . | . . 7
. . . | 9 . 6 | . . .
3 . 9 | . 8 . | . . .
---------------------
. . . | . . . | . 4 .
8 7 2 | 5 . . | . . .
. . . | 7 2 . | 6 . .
".parse().unwrap();
```
After it's parsed you can solve it using the [Board::solve](https://docs.rs/sudokugen/0.2.0/sudokugen/board/struct.Board.html#method.solve) function:
```rust
board.solve().unwrap();
assert_eq!(
board,
"695412873413879526287653419146235987728946135359187264561398742872564391934721658"
.parse()
.unwrap()
);
```
Finally you can generate new puzzles using
[Puzzle::generate](https://docs.rs/sudokugen/0.2.0/sudokugen/solver/generator/struct.Puzzle.html#method.generate),
when doing this you must specify what size of puzzle
do you want to generate, [BoardSize](https://docs.rs/sudokugen/0.2.0/sudokugen/board/enum.BoardSize.html) makes that very easy.
```rust
use sudokugen::{Puzzle, BoardSize};
let puzzle = Puzzle::generate(BoardSize::NineByNine);
println!("Puzzle\n{}", puzzle.board());
println!("Solution\n{}", puzzle.solution());
```
Which will print something like this:
```
> Puzzle
> . . . . . . . 6 .
> . 1 7 . 4 . . 9 .
> . . . . 9 . 5 3 .
> . . 5 . 7 2 8 . .
> 1 . . . . 8 4 5 .
> . 4 . 9 . . . . .
> 8 7 9 1 2 . . . .
> 4 5 . 8 . . . . .
> . . . . . . . . .
>
> Solution
> 9 2 3 5 8 1 7 6 4
> 5 1 7 6 4 3 2 9 8
> 6 8 4 2 9 7 5 3 1
> 3 6 5 4 7 2 8 1 9
> 1 9 2 3 6 8 4 5 7
> 7 4 8 9 1 5 6 2 3
> 8 7 9 1 2 6 3 4 5
> 4 5 6 8 3 9 1 7 2
> 2 3 1 7 5 4 9 8 6
```
# Puzzle quality
Grading puzzles is beyond the scope of this crate. Grading puzzles
correctly requires solving them like a human would, and some of the more complex techniques to solve
a puzzle like a human would require a lot of computations that do not always payoff performance-wise.
That being said, the generated puzzles consistently have between 22 and 26 clues making them likely
on the harder side of most generally available puzzles.
# Is it fast?
The quick answer is, it depends on your use case. The
[`Board::solve`](https://docs.rs/sudokugen/0.2.0/sudokugen/board/struct.Board.html#method.solve)
function is optimized to be
decently fast for a 9x9 sudoku puzzle, in my 2017 MacBook Pro it takes an average of 300μs
to solve a difficult puzzle, that is around 3000 puzzles per second.
The [`Puzzle::generate`](https://docs.rs/sudokugen/0.2.0/sudokugen/solver/generator/struct.Puzzle.html#method.generate)
function is less optimized and makes heavy usage of
[`Board::solve`](https://docs.rs/sudokugen/0.2.0/sudokugen/board/struct.Board.html#method.solve) without trying to
re-use repeated computations, as such it's much slower clocking at about 18ms to generate
a new puzzle in my benchmarks.
You can run your own benchmarks with `cargo bench`