Struct SudokuGrid

pub struct SudokuGrid { /* private fields */ }

A Sudoku grid is composed of cells that are organized into blocks of a given width and height in a way that makes the entire grid a square. Consequently, the number of blocks in a row is equal to the block height and vice versa. Each cell may or may not be occupied by a number.

In ordinary Sudoku, the block width and height are both 3. Here, however, more exotic variants are permitted, for example 4x2 blocks, which would result in a grid like this:

╔═══╤═══╤═══╤═══╦═══╤═══╤═══╤═══╗
║   │   │   │   ║   │   │   │   ║
╟───┼───┼───┼───╫───┼───┼───┼───╢
║   │   │   │   ║   │   │   │   ║
╠═══╪═══╪═══╪═══╬═══╪═══╪═══╪═══╣
║   │   │   │   ║   │   │   │   ║
╟───┼───┼───┼───╫───┼───┼───┼───╢
║   │   │   │   ║   │   │   │   ║
╠═══╪═══╪═══╪═══╬═══╪═══╪═══╪═══╣
║   │   │   │   ║   │   │   │   ║
╟───┼───┼───┼───╫───┼───┼───┼───╢
║   │   │   │   ║   │   │   │   ║
╠═══╪═══╪═══╪═══╬═══╪═══╪═══╪═══╣
║   │   │   │   ║   │   │   │   ║
╟───┼───┼───┼───╫───┼───┼───┼───╢
║   │   │   │   ║   │   │   │   ║
╚═══╧═══╧═══╧═══╩═══╧═══╧═══╧═══╝

SudokuGrid implements Display, but only grids with a size (that is, width or height) of less than or equal to 9 can be displayed with digits 1 to 9. Sudoku of all other sizes will raise an error.

Implementations

impl SudokuGrid

pub fn new(block_width: usize, block_height: usize) -> SudokuResult<SudokuGrid>

Creates a new, empty Sudoku grid where the blocks have the given dimensions. The total width and height of the grid will be equal to the product of block_width and block_height.

Arguments

• block_width: The horizontal dimension of one sub-block of the grid. To ensure a square grid, this is also the number of blocks that compose the grid vertically. For an ordinary Sudoku grid, this is 3. Must be greater than 0.
• block_height: The vertical dimension of one sub-block of the grid. To ensure a square grid, this is also the number of blocks that compose the grid horizontally. For an ordinary Sudoku grid, this is 3. Must be greater than 0.

Errors

If block_width or block_height is invalid (zero).

pub fn parse(code: &str) -> SudokuParseResult<SudokuGrid>

Parses a code encoding a Sudoku grid. The code has to be of the format <block_width>x<block_height>;<cells> where <cells> is a comma-separated list of entries, which are either empty or a number. The entries are assigned left-to-right, top-to-bottom, where each row is completed before the next one is started. Whitespace in the entries is ignored to allow for more intuitive formatting. The number of entries must match the amount of cells in a grid with the given dimensions, i.e. it must be (block_width · block_height)².

As an example, the code 2x2;1, ,2, , ,3, ,4, , , ,3, ,1, ,2 will parse to the following grid:

╔═══╤═══╦═══╤═══╗
║ 1 │   ║ 2 │   ║
╟───┼───╫───┼───╢
║   │ 3 ║   │ 4 ║
╠═══╪═══╬═══╪═══╣
║   │   ║ 3 │   ║
╟───┼───╫───┼───╢
║   │ 1 ║   │ 2 ║
╚═══╧═══╩═══╧═══╝

Errors

Any specialization of SudokuParseError (see that documentation).

pub fn to_parseable_string(&self) -> String

Converts the grid into a String in a way that is consistent with SudokuGrid::parse. That is, a grid that is converted to a string and parsed again will not change, as is illustrated below.

use sudoku_variants::SudokuGrid;

let mut grid = SudokuGrid::new(3, 2).unwrap();

// Just some arbitrary changes to create some content.
grid.set_cell(1, 1, 4).unwrap();
grid.set_cell(1, 2, 5).unwrap();

let grid_str = grid.to_parseable_string();
let grid_parsed = SudokuGrid::parse(grid_str.as_str()).unwrap();
assert_eq!(grid, grid_parsed);

pub fn block_width(&self) -> usize

Gets the width (number of columns) of one sub-block of the grid. To ensure a square grid, this is also the number of blocks that compose the grid vertically.

pub fn block_height(&self) -> usize

Gets the height (number of rows) of one sub-block of the grid. To ensure a square grid, this is also the number of blocks that compose the grid horizontally.

pub fn size(&self) -> usize

Gets the total size of the grid on one axis (horizontally or vertically). Since a square grid is enforced at construction time, this is guaranteed to be valid for both axes.

pub fn get_cell(&self, column: usize, row: usize) -> SudokuResult<Option<usize>>

Gets the content of the cell at the specified position.

Arguments

• column: The column (x-coordinate) of the desired cell. Must be in the range [0, size[.
• row: The row (y-coordinate) of the desired cell. Must be in the range [0, size[.

Errors

If either column or row are not in the specified range. In that case, SudokuError::OutOfBounds is returned.

pub fn has_number( &self, column: usize, row: usize, number: usize, ) -> SudokuResult<bool>

Indicates whether the cell at the specified position has the given number. This will return false if there is a different number in that cell or it is empty.

Arguments

• column: The column (x-coordinate) of the checked cell. Must be in the range [0, size[.
• row: The row (y-coordinate) of the checked cell. Must be in the range [0, size[.
• number: The number to check whether it is in the specified cell. If it is not in the range [1, size], false will always be returned.

Errors

If either column or row are not in the specified range. In that case, SudokuError::OutOfBounds is returned.

pub fn set_cell( &mut self, column: usize, row: usize, number: usize, ) -> SudokuResult<()>

Sets the content of the cell at the specified position to the given number. If the cell was not empty, the old number will be overwritten.

Arguments

• column: The column (x-coordinate) of the assigned cell. Must be in the range [0, size[.
• row: The row (y-coordinate) of the assigned cell. Must be in the range [0, size[.
• number: The number to assign to the specified cell. Must be in the range [1, size].

Errors

• SudokuError::OutOfBounds If either column or row are not in the specified range.
• SudokuError::InvalidNumber If number is not in the specified range.

pub fn clear_cell(&mut self, column: usize, row: usize) -> SudokuResult<()>

Clears the content of the cell at the specified position, that is, if contains a number, that number is removed. If the cell is already empty, it will be left that way.

Arguments

• column: The column (x-coordinate) of the cleared cell. Must be in the range [0, size[.
• row: The row (y-coordinate) of the cleared cell. Must be in the range [0, size[.

Errors

If either column or row are not in the specified range. In that case, SudokuError::OutOfBounds is returned.

pub fn assign(&mut self, other: &SudokuGrid) -> SudokuResult<()>

Assigns the content of another grid to this one, i.e., changes the cells in this grid to the state in other. The other grid must have the same dimensions as this one.

Errors

If the dimensions are not the same. In that case, SudokuError::InvalidDimensions is returned.

pub fn count_clues(&self) -> usize

Counts the number of clues given by this grid. This is the number of non-empty cells. While on average Sudoku with less clues are harder, this is not a reliable measure of difficulty.

pub fn is_full(&self) -> bool

Indicates whether this grid is full, i.e. every cell is filled with a number. In this case, SudokuGrid::count_clues returns the square of SudokuGrid::size.

pub fn is_empty(&self) -> bool

Indicates whether this grid is empty, i.e. no cell is filled with a number. In this case, SudokuGrid::count_clues returns 0.

pub fn is_subset(&self, other: &SudokuGrid) -> SudokuResult<bool>

Indicates whether this grid configuration is a subset of another one. That is, all cells filled in this grid with some number must be filled in other with the same number. If this condition is met, true is returned, and false otherwise.

Errors

If the dimensions of this and the other grid are not the same. In that case, SudokuError::InvalidDimensions is returned.

pub fn is_superset(&self, other: &SudokuGrid) -> SudokuResult<bool>

Indicates whether this grid configuration is a superset of another one. That is, all cells filled in the other grid with some number must be filled in this one with the same number. If this condition is met, true is returned, and false otherwise.

Errors

If the dimensions of this and the other grid are not the same. In that case, SudokuError::InvalidDimensions is returned.

pub fn cells(&self) -> &Vec<Option<usize>>

Gets a reference to the vector which holds the cells. They are in left-to-right, top-to-bottom order, where rows are together.

pub fn cells_mut(&mut self) -> &mut Vec<Option<usize>>

Gets a mutable reference to the vector which holds the cells. They are in left-to-right, top-to-bottom order, where rows are together.

Trait Implementations

impl Clone for SudokuGrid

fn clone(&self) -> SudokuGrid

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SudokuGrid

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for SudokuGrid

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl PartialEq for SudokuGrid

fn eq(&self, other: &SudokuGrid) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for SudokuGrid

impl StructuralPartialEq for SudokuGrid