Struct simple_grid::Grid

#[non_exhaustive]
pub struct Grid<T> { /* fields omitted */ }

A two-dimensional array, indexed with x-and-y-coordinates (columns and rows).

Implementations

impl<T> Grid<T>

pub fn new(width: usize, height: usize, data: Vec<T>) -> Self

Construct a new Grid.

Panics

• If width * height != data.len()
• If one of (but not both) width and height is zero.

Example

// construct a 2x3 (width x height) grid of chars
let grid = Grid::new(2, 3, "abcdef".chars().collect());
println!("{}", grid.to_pretty_string());
// prints:
// a b
// c d
// e f

pub fn from_grid<U>(other: Grid<U>) -> Grid<T> where
    T: From<U>, 

Construct a Grid from another, by converting each element.

Example

let u32_grid: Grid<u32> = Grid::new(2, 2, vec![1, 2, 3, 4]);
let f64_grid: Grid<f64> = Grid::from_grid(u32_grid);
assert_eq!(f64_grid, Grid::new(2, 2, vec![1.0, 2.0, 3.0, 4.0]));

pub fn width(&self) -> usize

Returns the width (number of columns) of the Grid.

pub fn height(&self) -> usize

Returns the height (number of rows) of the Grid.

pub fn subgrid(
    self,
    column_start: usize,
    row_start: usize,
    width: usize,
    height: usize
) -> Grid<T>

Consumes the Grid, creating a new one from a subset of the original.

Arguments

• column_start - Left bound for the subgrid.
• row_start - Upper bound for the subgrid.
• width - Number of columns in the subgrid.
• height - Number of rows in the subgrid.

Panics

• If width or height (but not both) are 0. If both are 0, the resulting subgrid will be an empty (0 by 0) Grid.
• If column_start is out of bounds.
• If row_start is out of bounds.

Example

let original: Grid<u32> = Grid::new(3, 3, (1..=9).collect());
let subgrid = original.subgrid(1, 0, 2, 2);
assert_eq!(subgrid, Grid::new(2, 2, vec![2, 3, 5, 6]));

pub fn dimensions(&self) -> (usize, usize)

Returns a tuple containing the (width, height) of the grid.

Example

let grid = Grid::new(2, 3, vec![1, 2, 3, 4, 5, 6]);
assert_eq!(grid.dimensions(), (2, 3));

pub fn is_square(&self) -> bool

Checks if the Grid is square (number of columns and rows is equal).

Note: an empty Grid is not square (even though columns and rows is 0).

Example

let grid = Grid::new(2, 2, vec![1, 2, 3, 4]);
assert!(grid.is_square());
let grid = Grid::new(2, 3, vec![1, 2, 3, 4, 5, 6]);
assert!(!grid.is_square());

pub fn area(&self) -> usize

Returns the area (number of columns * number of rows) of the grid.

Example

let grid = Grid::new(2, 3, vec![2, 4, 8, 16, 32, 64]);
assert_eq!(grid.area(), 6);

pub fn get<I>(&self, idx: I) -> Option<&T> where
    GridIndex: From<I>, 

Attempts to get a reference to the element at idx.

Returns None if idx is out of bounds.

Example

let grid = Grid::new(2, 3, vec![2, 4, 8, 16, 32, 64]);
assert_eq!(grid.get((1, 1)), Some(&16));
assert!(grid.get((10, 15)).is_none());

pub fn get_mut<I>(&mut self, idx: I) -> Option<&mut T> where
    GridIndex: From<I>, 

Attempts to get a mutable reference to the element at idx

Returns None if idx is out of bounds.

pub fn cell_iter(&self) -> impl DoubleEndedIterator<Item = &T>

Return an iterator over the cells in the grid.

Iterates from left to right (starting with row 0, then row 1 etc.).

pub fn row_iter(&self, row: usize) -> impl DoubleEndedIterator<Item = &T>

Return an iterator over the columns in the row with index row.

Panics

• If row >= self.height

Example

let grid = Grid::new(10, 10, (1..=100).collect());
let items_in_row_2: Vec<u32> = grid.row_iter(2).cloned().collect();
assert_eq!(items_in_row_2, vec![21, 22, 23, 24, 25, 26, 27, 28, 29, 30]);

pub fn column_iter(&self, column: usize) -> impl DoubleEndedIterator<Item = &T>

Return an iterator over the rows in the column with index column.

Panics

• If column >= self.width

Example

let grid = Grid::new(10, 10, (1..=100).collect());
let items_in_column_2: Vec<u32> = grid.column_iter(2).cloned().collect();
assert_eq!(items_in_column_2, vec![3, 13, 23, 33, 43, 53, 63, 73, 83, 93]);

pub fn insert_row(&mut self, row: usize, row_contents: Vec<T>)

Insert a row at index row, shifting all other rows downward (row n becomes row n+1 and so on).

Panics

• If row_contents.is_empty()
• If row_contents.len() != self.width
• If row > self.height (note that row == self.height is allowed, to add a row at the bottom of the Grid)

Example

let mut grid = Grid::new(2, 2, "abcd".chars().collect());
grid.insert_row(1, "xx".chars().collect());
assert_eq!(grid, Grid::new(2, 3, "abxxcd".chars().collect()));
println!("{}", grid.to_pretty_string());
// prints:
// a b
// x x
// c d

pub fn push_row(&mut self, row_contents: Vec<T>)

Add a row to the bottom of the Grid.

Example

let mut grid = Grid::new(2, 2, "abcd".chars().collect());
grid.push_row(vec!['x', 'x']);
assert_eq!(grid, Grid::new(2, 3, "abcdxx".chars().collect()));
println!("{}", grid.to_pretty_string());
// prints
// a b
// c d
// x x

pub fn replace_row(&mut self, row: usize, data: Vec<T>) -> Vec<T>

Replace the contents in a row.

Returns the old elements of the row.

Panics

• If row >= self.height
• If data.len() != self.width

pub fn remove_row(&mut self, row: usize) -> Vec<T>

Remove row at row, shifting all rows with higher indices “upward” (row n becomes row n-1).

Returns the row that was removed.

Panics

• If row >= self.height

Example

let mut grid = Grid::new(2, 2, "abcd".chars().collect());
grid.remove_row(1);
assert_eq!(grid, Grid::new(2, 1, "ab".chars().collect()));
println!("{}", grid.to_pretty_string());
// prints:
// a b

pub fn pop_row(&mut self) -> Option<Vec<T>>

Remove the bottom row, returning it (if it exists).

Returns None if the height of the Grid is zero.

Example

let mut grid = Grid::new(2, 2, "abcd".chars().collect());
let bottom_row = grid.pop_row();
assert_eq!(bottom_row, Some(vec!['c', 'd']));
assert_eq!(grid, Grid::new(2, 1, "ab".chars().collect()));

pub fn swap_rows(&mut self, row1: usize, row2: usize)

Swap two rows in the grid.

Panics

• If either of the row indices are out of bounds.

pub fn insert_column(&mut self, column: usize, column_contents: Vec<T>)

Insert a column at index column, shifting all other columns to the right (column n becomes column n+1 and so on).

Panics

• If column_contents.is_empty()
• If column_contents.len() != self.height
• If column > self.width (note that column == self.width is allowed, to add a column at the right of the Grid)

Example

let mut grid = Grid::new(2, 2, "abcd".chars().collect());
grid.insert_column(1, "xx".chars().collect());
assert_eq!(grid, Grid::new(3, 2, "axbcxd".chars().collect()));
println!("{}", grid.to_pretty_string());
// prints:
// a x b
// c x d

pub fn push_column(&mut self, column_contents: Vec<T>)

Add a column to the right of the Grid.

Example

let mut grid = Grid::new(2, 2, "abcd".chars().collect());
grid.push_column(vec!['x', 'x']);
assert_eq!(grid, Grid::new(3, 2, "abxcdx".chars().collect()));
println!("{}", grid.to_pretty_string());
// prints
// a b x
// c d x

pub fn replace_column(&mut self, column: usize, data: Vec<T>) -> Vec<T>

Replace the contents in a column.

Returns the old elements of the column.

Panics

• If column >= self.width
• If data.len() != self.height

pub fn swap_columns(&mut self, column1: usize, column2: usize)

Swap two columns in the grid.

Panics

• If either of the column indices are out of bounds.

pub fn remove_column(&mut self, column: usize) -> Vec<T>

Remove column at column, shifting all columns with higher indices “left” (column n becomes column n-1).

Returns the column that was removed.

Panics

• If column >= self.width

Example

let mut grid = Grid::new(2, 2, "abcd".chars().collect());
grid.remove_column(1);
assert_eq!(grid, Grid::new(1, 2, "ac".chars().collect()));
println!("{}", grid.to_pretty_string());
// prints:
// a
// c

pub fn pop_column(&mut self) -> Option<Vec<T>>

Remove the rightmost column, returning it (if it exists).

Returns None if the width of the Grid is zero.

Example

let mut grid = Grid::new(2, 2, "abcd".chars().collect());
let rightmost_column = grid.pop_column();
assert_eq!(rightmost_column, Some(vec!['b', 'd']));
assert_eq!(grid, Grid::new(1, 2, "ac".chars().collect()));

pub fn swap_cells<I>(&mut self, a: I, b: I) where
    GridIndex: From<I>, 

Swap the values in two cells in the grid.

Panics

• If either index is out of bounds.

Example

let mut grid = Grid::new(2, 3, vec![1, 2, 3, 4, 5, 6]);
grid.swap_cells((1, 1), (0, 2));
assert_eq!(grid, Grid::new(2, 3, vec![1, 2, 3, 5, 4, 6]));

pub fn replace_cell<I>(&mut self, idx: I, elem: T) -> T where
    GridIndex: From<I>, 

Replace the contents in a cell.

Returns the old element of the cell.

Panics

• If idx is out of bounds.

pub fn rotate_ccw(&mut self)

Rotate the grid counter-clockwise 90 degrees.

Example

let mut grid = Grid::new(2, 2, "abcd".chars().collect());
println!("{}", grid.to_pretty_string());
// prints:
// a b
// c d

grid.rotate_ccw();
assert_eq!(grid, Grid::new(2, 2, "bdac".chars().collect()));
println!("{}", grid.to_pretty_string());
// prints:
// b d
// a c

pub fn rotate_cw(&mut self)

Rotate the grid clockwise 90 degrees.

Example

let mut grid = Grid::new(2, 2, "abcd".chars().collect());
println!("{}", grid.to_pretty_string());
// prints:
// a b
// c d

grid.rotate_cw();
assert_eq!(grid, Grid::new(2, 2, "cadb".chars().collect()));
println!("{}", grid.to_pretty_string());
// prints:
// c a
// d b

pub fn flip_horizontally(&mut self)

Flip the grid horizontally, so that the first column becomes the last.

Example

let mut grid = Grid::new(2, 2, "abcd".chars().collect());
println!("{}", grid.to_pretty_string());
// prints:
// a b
// c d

grid.flip_horizontally();
assert_eq!(grid, Grid::new(2, 2, "badc".chars().collect()));
println!("{}", grid.to_pretty_string());
// prints:
// b a
// d c

pub fn flip_vertically(&mut self)

Flip the grid vertically, so that the first row becomes the last.

Example

let mut grid = Grid::new(2, 2, "abcd".chars().collect());
println!("{}", grid.to_pretty_string());
// prints:
// a b
// c d

grid.flip_vertically();
assert_eq!(grid, Grid::new(2, 2, "cdab".chars().collect()));
println!("{}", grid.to_pretty_string());
// prints:
// c d
// a b

pub fn transpose(&mut self)

Transpose the grid along the diagonal, so that cells at index (x, y) end up at index (y, x).

Example

let mut grid = Grid::new(2, 3, "abcdef".chars().collect());
println!("{}", grid.to_pretty_string());
// prints:
// a b
// c d
// e f

grid.transpose();
assert_eq!(grid, Grid::new(3, 2, "acebdf".chars().collect()));
println!("{}", grid.to_pretty_string());
// prints:
// a c e
// b d f

pub fn rows(&self) -> impl DoubleEndedIterator<Item = usize>

Return an iterator over the row indices in this grid. Allows you to write for row in grid.rows() instead of for row in 0..grid.height().

Example

let grid: Grid<u32> = Grid::new_default(3, 5);
let rows: Vec<usize> = grid.rows().collect();
assert_eq!(rows, vec![0, 1, 2, 3, 4]);

pub fn columns(&self) -> impl DoubleEndedIterator<Item = usize>

Return an iterator over the column indices in this grid. Allows you to write for column in grid.columns() instead of for column in 0..grid.width().

Example

let grid: Grid<u32> = Grid::new_default(2, 5);
let rows: Vec<usize> = grid.columns().collect();
assert_eq!(rows, vec![0, 1]);

pub fn position<P>(&self, predicate: P) -> Option<GridIndex> where
    P: Fn(&T) -> bool, 

Searches for an element in the Grid matching a predicate, returning its index.

Iterates from left to right (looks through row 0 followed by row 1 etc.).

Returns the index of the first element that matches the predicate.

Example

let grid = Grid::new(2, 3, vec![1, 2, 3, 4, 5, 6]);
let position_of_4 = grid.position(|&e| e == 4);
assert_eq!(position_of_4, Some(GridIndex::new(1, 1)));

pub fn indices(&self) -> impl DoubleEndedIterator<Item = GridIndex>

Return an iterator over the cell indices in this grid. Iterates from top to bottom, left to right.

Example

let two_by_three: Grid<u32> = Grid::new(2, 3, vec![1, 2, 3, 4, 5, 6]);
let indices: Vec<GridIndex> = two_by_three.indices().collect();
assert_eq!(indices, vec![GridIndex::new(0, 0), GridIndex::new(1, 0), GridIndex::new(0, 1), GridIndex::new(1, 1), GridIndex::new(0, 2), GridIndex::new(1, 2)]);

impl<T> Grid<T> where
    T: Default, 

pub fn new_default(width: usize, height: usize) -> Grid<T>

Create a grid filled with default values.

Example

let grid: Grid<bool> = Grid::new_default(2, 2);
assert_eq!(grid, Grid::new(2, 2, vec![false, false, false, false]));

impl<T> Grid<T> where
    T: PartialEq, 

pub fn contains(&self, value: &T) -> bool

Returns true if the grid contains some element equal to value.

Example

let grid = Grid::new(2, 2, "abcd".chars().collect());
assert!(grid.contains(&'a'));
assert!(!grid.contains(&'e'));

impl<T> Grid<T> where
    T: Display, 

pub fn to_pretty_string(&self) -> String

Format this Grid as a string. This can look weird when the Display output of T has varying length.

Example

let grid = Grid::new(10, 10, (1..=100).collect::<Vec<u32>>());
assert_eq!(grid.get((5, 2)).unwrap(), &26);

println!("{}", grid.to_pretty_string());
// prints:
//  1   2   3   4   5   6   7   8   9  10
// 11  12  13  14  15  16  17  18  19  20
// 21  22  23  24  25  26  27  28  29  30
// 31  32  33  34  35  36  37  38  39  40
// 41  42  43  44  45  46  47  48  49  50
// 51  52  53  54  55  56  57  58  59  60
// 61  62  63  64  65  66  67  68  69  70
// 71  72  73  74  75  76  77  78  79  80
// 81  82  83  84  85  86  87  88  89  90
// 91  92  93  94  95  96  97  98  99 100

Trait Implementations

impl<T: Clone> Clone for Grid<T>

fn clone(&self) -> Grid<T>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T: Debug> Debug for Grid<T>

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

Formats the value using the given formatter.

impl<T: Hash> Hash for Grid<T>

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given Hasher.

impl<T, I> Index<I> for Grid<T> where
    GridIndex: From<I>, 

type Output = T

The returned type after indexing.

fn index(&self, index: I) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<T, I> IndexMut<I> for Grid<T> where
    GridIndex: From<I>, 

fn index_mut(&mut self, index: I) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.

impl<T> IntoIterator for Grid<T>

type Item = T

The type of the elements being iterated over.

type IntoIter = IntoIter<Self::Item>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<T: PartialEq> PartialEq<Grid<T>> for Grid<T>

fn eq(&self, other: &Grid<T>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Grid<T>) -> bool

This method tests for !=.

impl<T: Eq> Eq for Grid<T>

impl<T> StructuralEq for Grid<T>

impl<T> StructuralPartialEq for Grid<T>