Struct grid::Grid

source ·
pub struct Grid<T> { /* private fields */ }
Expand description

Stores elements of a certain type in a 2D grid structure.

Uses a rust Vec<T> type to reference the grid data on the heap. Also the number of rows and columns are stored in the grid data structure.

The size limit of a grid is rows * cols < usize.

The grid data is stored in a row-major memory layout.

Implementations§

source§

impl<T> Grid<T>

source

pub fn new(rows: usize, cols: usize) -> Grid<T>
where T: Default,

Init a grid of size rows x columns with default values of the given type. For example this will generate a 2x3 grid of zeros:

use grid::Grid;
let grid : Grid<u8> = Grid::new(2,3);
assert_eq!(grid[0][0], 0);

If rows == 0 or cols == 0 the grid will be empty with no cols and rows.

Panics

Panics if rows * cols > usize.

source

pub fn init(rows: usize, cols: usize, data: T) -> Grid<T>
where T: Clone,

Init a grid of size rows x columns with the given data element.

If rows == 0 or cols == 0 the grid will be empty with no cols and rows.

Panics

Panics if rows * cols > usize.

source

pub fn from_vec(vec: Vec<T>, cols: usize) -> Grid<T>

Returns a grid from a vector with a given column length. The length of vec must be a multiple of cols.

For example:

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

will create a grid with the following layout: [1,2,3] [4,5,6]

This example will fail, because vec.len() is not a multiple of cols:

use grid::Grid;
Grid::from_vec(vec![1,2,3,4,5], 3);
Panics

This panics if the vector length isn’t a multiple of the number of columns.

source

pub unsafe fn get_unchecked(&self, row: usize, col: usize) -> &T

Returns a reference to an element, without performing bound checks. Generally not recommended, use with caution!

Safety

Calling this method with an out-of-bounds index is undefined behavior even if the resulting reference is not used.

source

pub unsafe fn get_unchecked_mut(&mut self, row: usize, col: usize) -> &mut T

Returns a mutable reference to an element, without performing bound checks. Generally not recommended, use with caution!

Safety

Calling this method with an out-of-bounds index is undefined behavior even if the resulting reference is not used.

source

pub fn get(&self, row: usize, col: usize) -> Option<&T>

Access a certain element in the grid. Returns None if an element beyond the grid bounds is tried to be accessed.

source

pub fn get_mut(&mut self, row: usize, col: usize) -> Option<&mut T>

Mutable access to a certain element in the grid. Returns None if an element beyond the grid bounds is tried to be accessed.

source

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

Returns the size of the gird as a two element tuple. First element are the number of rows and the second the columns.

source

pub fn rows(&self) -> usize

Returns the number of rows of the grid.

source

pub fn cols(&self) -> usize

Returns the number of columns of the grid.

source

pub fn is_empty(&self) -> bool

Returns true if the grid contains no elements. For example:

use grid::*;
let grid : Grid<u8> = grid![];
assert!(grid.is_empty());
source

pub fn clear(&mut self)

Clears the grid.

source

pub fn iter(&self) -> Iter<'_, T>

Returns an iterator over the whole grid, starting from the first row and column.

use grid::*;
let grid: Grid<u8> = grid![[1,2][3,4]];
let mut iter = grid.iter();
assert_eq!(iter.next(), Some(&1));
assert_eq!(iter.next(), Some(&2));
assert_eq!(iter.next(), Some(&3));
assert_eq!(iter.next(), Some(&4));
assert_eq!(iter.next(), None);
source

pub fn iter_mut(&mut self) -> IterMut<'_, T>

Returns an mutable iterator over the whole grid that allows modifying each value.

use grid::*;
let mut grid: Grid<u8> = grid![[1,2][3,4]];
let mut iter = grid.iter_mut();
let next = iter.next();
assert_eq!(next, Some(&mut 1));
*next.unwrap() = 10;
source

pub fn iter_col(&self, col: usize) -> StepBy<Iter<'_, T>>

Returns an iterator over a column.

Examples
use grid::*;
let grid: Grid<u8> = grid![[1, 2, 3][3, 4, 5]];
let mut col_iter = grid.iter_col(1);
assert_eq!(col_iter.next(), Some(&2));
assert_eq!(col_iter.next(), Some(&4));
assert_eq!(col_iter.next(), None);
Panics

Panics if the col index is out of bounds.

source

pub fn iter_col_mut(&mut self, col: usize) -> StepBy<IterMut<'_, T>>

Returns a mutable iterator over a column.

Examples
use grid::*;
let mut grid: Grid<u8> = grid![[1, 2, 3][3, 4, 5]];
let mut col_iter = grid.iter_col_mut(1);
let next = col_iter.next();
assert_eq!(next, Some(&mut 2));
*next.unwrap() = 10;
assert_eq!(grid[0][1], 10);
Panics

Panics if the col index is out of bounds.

source

pub fn iter_row(&self, row: usize) -> Iter<'_, T>

Returns an iterator over a row.

Examples
use grid::*;
let grid: Grid<u8> = grid![[1, 2, 3][3, 4, 5]];
let mut col_iter = grid.iter_row(1);
assert_eq!(col_iter.next(), Some(&3));
assert_eq!(col_iter.next(), Some(&4));
assert_eq!(col_iter.next(), Some(&5));
assert_eq!(col_iter.next(), None);
Panics

Panics if the row index is out of bounds.

source

pub fn iter_row_mut(&mut self, row: usize) -> IterMut<'_, T>

Returns a mutable iterator over a row.

Examples
use grid::*;
let mut grid: Grid<u8> = grid![[1, 2, 3][3, 4, 5]];
let mut col_iter = grid.iter_row_mut(1);
let next = col_iter.next();
*next.unwrap() = 10;
assert_eq!(grid[1][0], 10);
Panics

Panics if the row index is out of bounds.

source

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

Add a new row to the grid.

Examples
use grid::*;
let mut grid: Grid<u8> = grid![[1, 2, 3][3, 4, 5]];
let row = vec![6,7,8];
grid.push_row(row);
assert_eq!(grid.rows(), 3);
assert_eq!(grid[2][0], 6);
assert_eq!(grid[2][1], 7);
assert_eq!(grid[2][2], 8);

Can also be used to init an empty grid:

use grid::*;
let mut grid: Grid<u8> = grid![];
let row = vec![1,2,3];
grid.push_row(row);
assert_eq!(grid.size(), (1, 3));
Panics

Panics if:

  • the grid is not empty and row.len() != grid.cols()
  • row.len() == 0
source

pub fn push_col(&mut self, col: Vec<T>)

Add a new column to the grid.

Important: Please note that Grid uses a Row-Major memory layout. Therefore, the push_col() operation will be significantly slower compared to a push_row() operation.

Examples
use grid::*;
let mut grid: Grid<u8> = grid![[1, 2, 3][3, 4, 5]];
let col = vec![4,6];
grid.push_col(col);
assert_eq!(grid.cols(), 4);
assert_eq!(grid[0][3], 4);
assert_eq!(grid[1][3], 6);

Can also be used to init an empty grid:

use grid::*;
let mut grid: Grid<u8> = grid![];
let col = vec![1,2,3];
grid.push_col(col);
assert_eq!(grid.size(), (3, 1));
Panics

Panics if:

  • the grid is not empty and col.len() != grid.rows()
  • col.len() == 0
source

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

Removes the last row from a grid and returns it, or None if it is empty.

Examples
use grid::*;
let mut grid = grid![[1,2,3][4,5,6]];
assert_eq![grid.pop_row(), Some(vec![4,5,6])];
assert_eq![grid.pop_row(), Some(vec![1,2,3])];
assert_eq![grid.pop_row(), None];
source

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

Remove a Row at the index and return a vector of it.

Examples
use grid::*;
let mut grid = grid![[1,2][3,4][5,6]];
assert_eq![grid.remove_row(1), Some(vec![3,4])];   
assert_eq![grid.remove_row(0), Some(vec![1,2])];
assert_eq![grid.remove_row(0), Some(vec![5,6])];
assert_eq![grid.remove_row(0), None];
source

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

Removes the last column from a grid and returns it, or None if it is empty.

Note that this operation is much slower than the pop_row() because the memory layout of Grid is row-major and removing a column requires a lot of move operations.

Examples
use grid::*;
let mut grid = grid![[1,2,3][4,5,6]];
assert_eq![grid.pop_col(), Some(vec![3,6])];
assert_eq![grid.pop_col(), Some(vec![2,5])];
assert_eq![grid.pop_col(), Some(vec![1,4])];
assert_eq![grid.pop_col(), None];
source

pub fn remove_col(&mut self, col_index: usize) -> Option<Vec<T>>

Remove a column at the index and return a vector of it.

Examples
use grid::*;
let mut grid = grid![[1,2,3,4][5,6,7,8][9,10,11,12][13,14,15,16]];
assert_eq![grid.remove_col(3), Some(vec![4,8,12,16])];
assert_eq![grid.remove_col(0), Some(vec![1,5,9,13])];
assert_eq![grid.remove_col(1), Some(vec![3,7,11,15])];
assert_eq![grid.remove_col(0), Some(vec![2,6,10,14])];
assert_eq![grid.remove_col(0), None];
source

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

Insert a new row at the index and shifts all rows after down.

Examples
use grid::*;
let mut grid = grid![[1,2,3][4,5,6]];
grid.insert_row(1, vec![7,8,9]);
assert_eq!(grid[0], [1,2,3]);
assert_eq!(grid[1], [7,8,9]);
assert_eq!(grid[2], [4,5,6]);
assert_eq!(grid.size(), (3,3))
Panics

Panics if:

  • the grid is not empty and row.len() != grid.cols().
  • the index is greater than the number of rows
source

pub fn insert_col(&mut self, index: usize, col: Vec<T>)

Insert a new column at the index.

Important! Insertion of columns is a lot slower than the lines insertion. This is because of the memory layout of the grid data structure.

Examples
use grid::*;
let mut grid = grid![[1,2,3][4,5,6]];
grid.insert_col(1, vec![9,9]);
assert_eq!(grid[0], [1,9,2,3]);
assert_eq!(grid[1], [4,9,5,6]);
assert_eq!(grid.size(), (2,4))
Panics

Panics if:

  • the grid is not empty and col.len() != grid.rows().
  • the index is greater than the number of columns
source

pub fn flatten(&self) -> &Vec<T>

Returns a reference to the internal data structure of the grid.

Grid uses a row major layout. All rows are placed right after each other in the vector data structure.

Examples
use grid::*;
let grid = grid![[1,2,3][4,5,6]];
let flat = grid.flatten();
assert_eq!(flat, &vec![1,2,3,4,5,6]);
source

pub fn into_vec(self) -> Vec<T>

Converts self into a vector without clones or allocation.

source

pub fn transpose(&self) -> Grid<T>
where T: Clone,

Transpose the grid so that columns become rows in new grid.

source

pub fn fill(&mut self, value: T)
where T: Clone,

Fills the grid with elements by cloning value.

Examples
use grid::*;
let mut grid = grid![[1,2,3][4,5,6]];
grid.fill(7);
assert_eq!(grid[0], [7,7,7]);
assert_eq!(grid[1], [7,7,7]);
source

pub fn fill_with<F>(&mut self, f: F)
where F: FnMut() -> T,

Fills the grid with elements returned by calling a closure repeatedly.

This method uses a closure to create new values. If you’d rather Clone a given value, use fill. If you want to use the Default trait to generate values, you can pass Default::default as the argument.

Examples
use grid::*;
let mut grid = grid![[1,2,3][4,5,6]];
grid.fill_with(Default::default);
assert_eq!(grid[0], [0,0,0]);
assert_eq!(grid[1], [0,0,0]);
source

pub fn iter_rows(&self) -> GridRowIter<'_, T>

Iterate over the rows of the grid. Each time an iterator over a single row is returned.

An item in this iterator is equal to a call to Grid.iter_row(row_index) of the corresponding row.

Examples
use grid::*;
let mut grid = grid![[1,2,3][4,5,6]];
let sum_by_row: Vec<u8> = grid.iter_rows().map(|row| row.sum()).collect();
assert_eq!(sum_by_row, vec![1+2+3, 4+5+6])
source

pub fn iter_cols(&self) -> GridColIter<'_, T>

Iterate over the columns of the grid. Each time an iterator over a single column is returned.

An item in this iterator is equal to a call to Grid.iter_col(col_index) of the corresponding column.

Examples
use grid::*;
let mut grid = grid![[1,2,3][4,5,6]];
let sum_by_col: Vec<u8> = grid.iter_cols().map(|col| col.sum()).collect();
assert_eq!(sum_by_col, vec![1+4, 2+5, 3+6])

Trait Implementations§

source§

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

source§

fn clone(&self) -> Self

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

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

source§

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

Formats the value using the given formatter. Read more
source§

impl<T> Index<(usize, usize)> for Grid<T>

§

type Output = T

The returned type after indexing.
source§

fn index(&self, (row, col): (usize, usize)) -> &T

Performs the indexing (container[index]) operation. Read more
source§

impl<T> Index<usize> for Grid<T>

§

type Output = [T]

The returned type after indexing.
source§

fn index(&self, idx: usize) -> &[T]

Performs the indexing (container[index]) operation. Read more
source§

impl<T> IndexMut<(usize, usize)> for Grid<T>

source§

fn index_mut(&mut self, (row, col): (usize, usize)) -> &mut T

Performs the mutable indexing (container[index]) operation. Read more
source§

impl<T> IndexMut<usize> for Grid<T>

source§

fn index_mut(&mut self, idx: usize) -> &mut [T]

Performs the mutable indexing (container[index]) operation. Read more
source§

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

source§

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

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

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

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
source§

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

Auto Trait Implementations§

§

impl<T> RefUnwindSafe for Grid<T>
where T: RefUnwindSafe,

§

impl<T> Send for Grid<T>
where T: Send,

§

impl<T> Sync for Grid<T>
where T: Sync,

§

impl<T> Unpin for Grid<T>
where T: Unpin,

§

impl<T> UnwindSafe for Grid<T>
where T: UnwindSafe,

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> ToOwned for T
where T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.