Struct ingrid::Grid

pub struct Grid<T> { /* fields omitted */ }

A dynamic two-dimensional array

This structure defines a dynamic two-dimensional array named grid. Grids can grow and shrink, and its elements are indexed with coordinates. The grid is implemented from left-to-right and top-to-bottom, therefore the top-left element is index (0, 0).

Elements can be accessed directly with value() and its related methods or indirectly via row() and column() and their related methods.

To iterate over the elements of the grid, use the iterator() method, or get an iterator from an intermediary row or column instead.

Some common operations on grids are also available such as flipping the values on one of the two axis, or rotating to the left or right.

Just like regular vectors, grids also have a capacity indicating the actual allocated memory on each axis and allows you to control it with with the reserve() method.

Examples

Creating and resizing a grid.

// Create a 2x2 grid filled with value 0.
let mut grid = Grid::with_size(size!(2, 2), 0);

// Increase the grid size by one, and set the new values at 42.
grid.resize(size!(3, 3), 42);

Iterating over the elements of a grid.

let mut grid = Grid::from_rows(vec![vec![1, 2],
                                    vec![3, 4]]);

let mut iterator = grid.iterator();
assert_eq!(iterator.next(), Some(&1));
assert_eq!(iterator.next(), Some(&2));
assert_eq!(iterator.next(), Some(&3));
assert_eq!(iterator.next(), Some(&4));
assert_eq!(iterator.next(), None);

Indexing the grid.

let mut grid = Grid::with_size(size!(2, 2), 0);

grid[coord!(0, 0)] = 1;
grid[coord!(1, 0)] = 2;
grid[coord!(0, 1)] = 3;
grid[coord!(1, 1)] = 4;

Inserting and removing rows and columns.

let mut grid = Grid::with_size(size!(1, 1), 1);

grid.insert_column(1, vec![2]);
grid.insert_row(1, vec![3, 4]);

Methods

impl<T: Clone> Grid<T>

pub fn new() -> Grid<T>

Create an empty grid

This function creates an empty grid; a grid which has no width nor height, and thus contains no elements.

Examples

let grid = Grid::<char>::new();
assert_eq!(grid.size(), size!(0, 0));

pub fn with_size(size: Size, value: T) -> Grid<T>

Create a grid from a given size and value.

This function creates a grid from a given size and value. The grid is initialized with the given value which is cloned to fill the entire grid.

Arguments

• size - The size of the grid.
• value - The value to initialize the grid with.

Examples

let grid = Grid::with_size(size!(2, 2), 42);

assert_eq!(grid.value(coord!(0, 0)), &42);
assert_eq!(grid.value(coord!(1, 0)), &42);
assert_eq!(grid.value(coord!(0, 1)), &42);
assert_eq!(grid.value(coord!(1, 1)), &42);

pub fn with_capacity(capacity: Size) -> Grid<T>

Create a new grid with the specified capacity

This function creates a grid with the specified capacity. The grid will be able to hold exactly the number of elements specified by the specified capacity without reallocating. If capacity is (0, 0), the the grid will not allocate.

It is important to note that although the returned grid has the capacity specified, the grid will have a zero size.

Examples

let mut grid = Grid::with_capacity(size!(2, 3));

grid.resize(size!(2, 3), 42); // No allocation occurs here.
grid.resize(size!(3, 3), 42); // Allocation occurs here.

pub fn from_rows(rows: Vec<Vec<T>>) -> Grid<T>

Create a grid from rows

This function creates a grid from a list of vectors denoting the rows of the grid. All rows of the list must have the same length or it will panic.

Note that this is mostly used to create quick grids on the fly for testing. In real life situation, you will use the other constructors which offer better performance and flexibility.

Arguments

• rows - A list of vectors with elements of each row

Panics

This function panics if all vectors don't have the same length.

Examples

let grid = Grid::from_rows(vec![vec![1, 2],
                                vec![3, 4]]);

assert_eq!(grid.value(coord!(0, 0)), &1);
assert_eq!(grid.value(coord!(1, 0)), &2);
assert_eq!(grid.value(coord!(0, 1)), &3);
assert_eq!(grid.value(coord!(1, 1)), &4);

pub fn from_columns(columns: Vec<Vec<T>>) -> Grid<T>

Create a grid from columns

This function creates a grid from a list of vectors denoting the columns of the grid. All columns of the list must have the same length or it will panic.

Note that this is mostly used to create quick grids on the fly for testing. In real life situation, you will use the other constructors which offer better performance and flexibility.

Arguments

• columns - A list of vectors with elements of each columns

Panics

This function panics if all vectors don't have the same length.

Examples

let grid = Grid::from_columns(vec![vec![1, 3],
                                   vec![2, 4]]);

assert_eq!(grid.value(coord!(0, 0)), &1);
assert_eq!(grid.value(coord!(1, 0)), &2);
assert_eq!(grid.value(coord!(0, 1)), &3);
assert_eq!(grid.value(coord!(1, 1)), &4);

pub fn zero() -> Grid<T>

Create an empty grid.

This method is equivalent to the new() constructor. Use it to make your code more readable.

Examples

let grid = Grid::<()>::zero();
assert_eq!(grid.size(), size!(0, 0));

pub fn size(&self) -> Size

Return the size of the grid.

This method returns the size of the grid. Indirectly, that allows one to compute the actual number of elements in the grid.

Examples

let mut grid = Grid::from_rows(vec![vec![1, 2],
                                    vec![3, 4]]);

assert_eq!(grid.size(), size!(2, 2));
grid.resize(size!(5, 5), 42);
assert_eq!(grid.size(), size!(5, 5));

pub fn resize(&mut self, size: Size, value: T)

Resize the grid

This method resizes the grid, adding more elements to it and/or dropping existing values. It resizes it with a given value which is cloned when the grid grows on one of the two axis.

Note that it increases the size of the grid and if the capacity isn't high enough, reallocation occurs.

Arguments

• size - The new size of the grid
• value - The value to be cloned

Examples

let mut grid = Grid::zero();
grid.resize(size!(2, 2), 42);

assert_eq!(grid.size(), size!(2, 2));
assert_eq!(grid[coord!(0, 0)], 42);
assert_eq!(grid[coord!(1, 0)], 42);
assert_eq!(grid[coord!(0, 1)], 42);
assert_eq!(grid[coord!(1, 1)], 42);

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

Fill the grid with a given value.

This method fills the grid with a given value that is cloned for all the elements.

Arguments

• value - Value to fill the the grid with.

Examples

let mut grid = Grid::from_rows(vec![vec![1, 2],
                                    vec![3, 4]]);

grid.fill(42);
assert!(grid.iterator().all(|item| *item == 42))

pub fn clear(&mut self)

Clear the grid by removing all values.

This method clears the grid by removing all values and therefore setting its size to zero.

Note that this method has no effect on the allocated capacity of the grid.

Examples

let mut grid = Grid::from_rows(vec![vec![1, 2],
                                    vec![3, 4]]);

grid.clear();
assert_eq!(grid.size(), size!(0, 0));
assert_eq!(grid.capacity(), size!(2, 2));

pub fn value(&self, coordinate: Coordinate) -> &T

Return a reference to an element of the grid.

This method returns a reference to an element of the grid from its coordinate.

Note that coordinate (0, 0) corresponds to the top-left element in the grid.

Arguments

• coordinate - Coordinate of the element

Panics

It panics if the coordinate is out of bounds.

Examples

let mut grid = Grid::from_rows(vec![vec![1, 2],
                                    vec![3, 4]]);

assert_eq!(grid.value(coord!(0, 0)), &1);
assert_eq!(grid.value(coord!(1, 1)), &4);

grid.value(coord!(2, 0)); // It panics here !

pub fn value_mut<'a>(&'a mut self, coordinate: Coordinate) -> &'a mut T

Return a mutable reference to an element of the grid.

This method returns a mutable reference to an element of the grid from its coordinate.

Panics

It panics if the coordinate is out of bounds.

Arguments

• coordinate - Coordinate of the element

Examples

let mut grid = Grid::from_rows(vec![vec![1, 2],
                                    vec![3, 0]]);

let value = grid.value_mut(coord!(1, 1));
*value = 4;

assert_eq!(grid.value_mut(coord!(0, 0)), &1);
assert_eq!(grid.value_mut(coord!(1, 1)), &4);

grid.value(coord!(2, 0)); // It panics here !

pub fn set_value(&mut self, coordinate: Coordinate, value: T)

Replace an element of the grid.

This method replaces the value of an element of the grid from its coordinate and a new value, effectively dropping the previous value.

Arguments

• coordinate - Coordinate of the element
• value - New value of the element

Panics

It panics if the coordinate is out of bounds.

Examples

let mut grid = Grid::from_rows(vec![vec![1, 2],
                                    vec![3, 0]]);

grid.set_value(coord!(1, 1), 4);

assert_eq!(grid.value_mut(coord!(0, 0)), &1);
assert_eq!(grid.value_mut(coord!(1, 1)), &4);

grid.set_value(coord!(2, 0), 5); // It panics here !

pub fn swap_value(&mut self, a: Coordinate, b: Coordinate)

Swap two elements of the grid.

This method swaps two elements of the grid from their coordinates.

Arguments

• a - Coordinate of one of the element to swap
• b - Coordinate of the other element to be swapped with

Panics

It panics if the coordinates are out of bounds.

Examples

let mut grid = Grid::from_rows(vec![vec![4, 2],
                                    vec![3, 1]]);

grid.swap_value(coord!(0, 0), coord!(1, 1));

assert_eq!(grid.value(coord!(0, 0)), &1);
assert_eq!(grid.value(coord!(1, 1)), &4);

grid.swap_value(coord!(2, 0), coord!(0, 0)); // It panics here !

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

Return the elements of the grid.

This method returns the elements of the grid as a vector of reference.

Examples

let grid = Grid::from_rows(vec![vec![1, 2],
                                vec![3, 4]]);

assert_eq!(grid.values(), vec![&1, &2, &3, &4]);

Important traits for IteratorGrid<'a, T>

impl<'a, T: Clone> Iterator for IteratorGrid<'a, T> type Item = &'a T;

pub fn iterator<'a>(&'a self) -> IteratorGrid<'a, T>

Returns an iterator over the grid.

This method returns an iterator over the grid.

Examples

let mut grid = Grid::from_rows(vec![vec![1, 2],
                                    vec![3, 4]]);

let mut iterator = grid.iterator();
assert_eq!(iterator.next(), Some(&1));
assert_eq!(iterator.next(), Some(&2));
assert_eq!(iterator.next(), Some(&3));
assert_eq!(iterator.next(), Some(&4));
assert_eq!(iterator.next(), None);

pub fn row<'a>(&'a self, index: usize) -> Row<'a, T>

Create a view onto a given row

This method creates a view onto a given row of the grid. The row is immutable; use row_mut() to compute a mutable row.

Panics

It panics if the index is out of bounds (less than the height of the grid).

Arguments

• index - Index of the row

Examples

let grid = Grid::from_rows(vec![vec![1, 2],
                                vec![3, 4]]);

assert_eq!(grid.row(1).values(), vec![&3, &4]);

pub fn row_mut<'a>(&'a mut self, index: usize) -> RowMut<'a, T>

Create a view onto a given row

This method creates a view onto a given row of the grid. The row is mutable; use row() to compute an immutable row.

Panics

It panics if the index is out of bounds (less than the height of the grid).

Arguments

• index - Index of the row

Examples

let mut grid = Grid::from_rows(vec![vec![1, 2],
                                    vec![0, 0]]);

let mut row = grid.row_mut(1);
row[0] = 3;
row[1] = 4;

assert_eq!(grid.row(1).values(), vec![&3, &4]);

pub fn swap_row(&mut self, a: usize, b: usize)

Swap two rows of the grid.

This method swaps two rows of the grid from their index.

Arguments

• a - Index of one of the row to swap
• b - Index of the other row to be swapped with

Panics

It panics if the indexes are out of bounds.

Examples

let mut grid = Grid::from_rows(vec![vec![1, 2, 3],
                                    vec![4, 5, 6]]);

grid.swap_row(0, 1);

assert_eq!(grid.row(0).values(), vec![&4, &5, &6]);
assert_eq!(grid.row(1).values(), vec![&1, &2, &3]);

grid.swap_row(1, 2); // It panics here !

pub fn rows<'a>(&'a self) -> Vec<Row<'a, T>>

Return the rows of the grid

This method returns the rows of the grid as a vector.

Examples

let grid = Grid::from_rows(vec![vec![1, 2],
                                vec![3, 4]]);

let rows = grid.rows();
assert_eq!(rows[0].values(), vec![&1, &2]);
assert_eq!(rows[1].values(), vec![&3, &4]);

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

Insert a row into the grid

This method inserts a row into the grid at position index, shifting all rows after it to the bottom. The row is a vector holding the elements of the inserted row, which are then moved to the grid. Its length must be equal to the length as the other rows.

Note that it increases the size of the grid and if the capacity isn't high enough, reallocation occurs.

Arguments

• index - Position index of the inserted row
• row - Vector with the element of the new row

Panics

It panics if the index is out of bounds or if the length of the vector doesn't equal the length of the other rows.

Examples

let mut grid = Grid::from_rows(vec![vec![1, 2, 3],
                                    vec![7, 8, 9]]);

grid.insert_row(1, vec![4, 5, 6]);

assert_eq!(grid.column(0).values(), vec![&1, &4, &7]);
assert_eq!(grid.column(1).values(), vec![&2, &5, &8]);
assert_eq!(grid.column(2).values(), vec![&3, &6, &9]);

pub fn remove_row(&mut self, index: usize)

Remove a row from the grid.

This method removes a row from the grid at position index, shifting all rows after it to the top.

Note that this method has no effect on the allocated capacity of the grid.

Arguments

• index - Position index of the row to remove

Panics

It panics if the index is out of bounds.

Examples

let mut grid = Grid::from_rows(vec![vec![1, 2, 3],
                                    vec![4, 5, 6],
                                    vec![7, 8, 9]]);

grid.remove_row(1);

assert_eq!(grid.column(0).values(), vec![&1, &7]);
assert_eq!(grid.column(1).values(), vec![&2, &8]);
assert_eq!(grid.column(2).values(), vec![&3, &9]);

pub fn column<'a>(&'a self, index: usize) -> Column<'a, T>

Create a view onto a given column

This method creates a view onto a given column of the grid. The column is immutable; use column_mut() to compute a mutable column.

Panics

This function panics if the index is out of bounds (less than the width of the grid).

Arguments

• index - Index of the column

Examples

let grid = Grid::from_rows(vec![vec![1, 2],
                                vec![3, 4]]);

assert_eq!(grid.column(1).values(), vec![&2, &4]);

pub fn column_mut<'a>(&'a mut self, index: usize) -> ColumnMut<'a, T>

Create a view onto a given column

This method creates a view onto a given column of the grid. The column is mutable; use column() to compute a immutable column.

Panics

This function panics if the index is out of bounds (less than the width of the grid).

Arguments

• index - Index of the column

Examples

let mut grid = Grid::from_rows(vec![vec![1, 0],
                                    vec![3, 0]]);

let mut column = grid.column_mut(1);
column[0] = 2;
column[1] = 4;

assert_eq!(grid.column(1).values(), vec![&2, &4]);

pub fn swap_column(&mut self, a: usize, b: usize)

Swap two columns of the grid.

This method swaps two columns of the grid from their index.

Arguments

• a - Index of one of the column to swap
• b - Index of the other column to be swapped with

Panics

It panics if the indexes are out of bounds.

Examples

let mut grid = Grid::from_rows(vec![vec![1, 2],
                                    vec![3, 4],
                                    vec![5, 6]]);

grid.swap_column(0, 1);

assert_eq!(grid.column(0).values(), vec![&2, &4, &6]);
assert_eq!(grid.column(1).values(), vec![&1, &3, &5]);

grid.swap_column(1, 2); // It panics here !

pub fn columns<'a>(&'a self) -> Vec<Column<'a, T>>

Return the columns of the grid

This method returns the columns of the grid as a vector.

Examples

let grid = Grid::from_rows(vec![vec![1, 2],
                                vec![3, 4]]);

let columns = grid.columns();
assert_eq!(columns[0].values(), vec![&1, &3]);
assert_eq!(columns[1].values(), vec![&2, &4]);

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

Insert a column into the grid

This method inserts a column into the grid at position index, shifting all columns after it to the right. The column is a vector holding the elements of the inserted column, which are then moved to the grid. Its length must be equal to the length as the other columns.

Note that it increases the size of the grid and if the capacity isn't high enough, reallocation occurs.

Arguments

• index - Position index of the inserted column
• column - Vector with the element of the new column

Panics

It panics if the index is out of bounds or if the length of the vector doesn't equal the length of the other columns.

Examples

let mut grid = Grid::from_rows(vec![vec![1, 3],
                                    vec![4, 6],
                                    vec![7, 9]]);

grid.insert_column(1, vec![2, 5, 8]);

assert_eq!(grid.row(0).values(), vec![&1, &2, &3]);
assert_eq!(grid.row(1).values(), vec![&4, &5, &6]);
assert_eq!(grid.row(2).values(), vec![&7, &8, &9]);

pub fn remove_column(&mut self, index: usize)

Remove a column from the grid.

This method removes a column from the grid at position index, shifting all columns after it to the left.

Note that this method has no effect on the allocated capacity of the grid.

Arguments

• index - Position index of the column to remove

Panics

It panics if the index is out of bounds.

Examples

let mut grid = Grid::from_rows(vec![vec![1, 2, 3],
                                    vec![4, 5, 6],
                                    vec![7, 8, 9]]);

grid.remove_column(1);

assert_eq!(grid.row(0).values(), vec![&1, &3]);
assert_eq!(grid.row(1).values(), vec![&4, &6]);
assert_eq!(grid.row(2).values(), vec![&7, &9]);

pub fn flip_horizontally(&mut self)

Flip the grid horizontally

This method flips the grid horizontally, reversing the order of the elements of each row, one by one.

Examples

let mut grid = Grid::from_rows(vec![vec![1, 2],
                                    vec![3, 4]]);

grid.flip_horizontally();
assert_eq!(grid.row(0).values(), vec![&2, &1]);
assert_eq!(grid.row(1).values(), vec![&4, &3]);

pub fn flip_vertically(&mut self)

Flip the grid vertically

This method flips the grid vertically, reversing the order of the elements of each column, one by one.

Examples

let mut grid = Grid::from_rows(vec![vec![1, 2],
                                    vec![3, 4]]);

grid.flip_vertically();
assert_eq!(grid.row(0).values(), vec![&3, &4]);
assert_eq!(grid.row(1).values(), vec![&1, &2]);

pub fn rotate_left(&mut self)

Rotate the grid to the left

This method rotate the grid to the left, rearranging its elements.

Note that the capacity of the grid is also rotated; if capacity was (a, b), this is now (b, a).

Examples

let mut grid = Grid::from_rows(vec![vec![1, 2],
                                    vec![3, 4]]);

grid.rotate_left();
assert_eq!(grid.row(0).values(), vec![&2, &4]);
assert_eq!(grid.row(1).values(), vec![&1, &3]);

pub fn rotate_right(&mut self)

Rotate the grid to the right

This method rotate the grid to the right, rearranging its elements.

Note that the capacity of the grid is also rotated; if capacity was (a, b), this is now (b, a).

Examples

let mut grid = Grid::from_rows(vec![vec![1, 2],
                                    vec![3, 4]]);

grid.rotate_right();
assert_eq!(grid.row(0).values(), vec![&3, &1]);
assert_eq!(grid.row(1).values(), vec![&4, &2]);

pub fn capacity(&self) -> Size

Return the number of elements the grid can hold without reallocating.

This method returns the number of elements the grid can hold without reallocating on both axis.

Examples

let grid = Grid::<()>::with_capacity(size!(2, 3));
assert_eq!(grid.capacity(), size!(2, 3));

pub fn reserve(&mut self, additional: Size)

Reserve capacity for at least additional more elements to be inserted

This method reserves capacity for at least additional more elements to be inserted in the grid. The collection may reserve more space to avoid frequent reallocations. After calling reserve, capacity will be greater than or equal to self.size() + additional. Does nothing if capacity is already sufficient.

Arguments

• additional - Capacity to be added on both axis

Panics

It panics if the new capacity overflows usize.

Examples

let mut grid = Grid::<()>::with_capacity(size!(2, 3));
grid.reserve(size!(3, 2));
assert_eq!(grid.capacity(), size!(5, 5));

pub fn row_slice(&mut self, row: usize) -> &mut [T]

Trait Implementations

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

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

Formats the value using the given formatter.

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

impl<T> Index<Coordinate> for Grid<T>

type Output = T

The returned type after indexing.

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

Performs the indexing (container[index]) operation.

impl<T> IndexMut<Coordinate> for Grid<T>

fn index_mut(&mut self, coordinate: Coordinate) -> &mut Self::Output

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

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> StructuralEq for Grid<T>

impl<T> StructuralPartialEq for Grid<T>