Struct VecGrid

pub struct VecGrid<T> { /* private fields */ }

A grid that stores its elements in a Vec<T>, in row-major order.

Implementations

impl<T> VecGrid<T>

pub fn new_fill_with( dimensions: impl VectorLike, gen: impl Fn() -> T, ) -> Option<Self>

Create a new VecGrid, filled with elements by repeatedly calling a function. The function is called once per cell in an unspecified order; use new_with if you want to have per-cell initialization logic.

Returns the grid, or None if the dimensions were invalid.

Example:

use gridly_grids::VecGrid;
use gridly::prelude::*;

let grid = VecGrid::new_fill_with((Rows(2), Columns(2)), || "Hello, World!".to_string()).unwrap();
assert_eq!(grid[(1, 0)], "Hello, World!")

See also new for filling a grid with a type’s default value, and new_fill for filling a grid with a clone of a value.

pub fn new_with( dimensions: impl VectorLike, gen: impl Fn(Location) -> T, ) -> Option<Self>

Create a new VecGrid by calling a function with the location of each cell in the grid, storing the return value of that function in that cell.

The function is called once per cell in an unspecified order; users should not rely on it being called in row-major order.

Returns the grid, or None if the dimensions were invalid.

Example:

use gridly_grids::VecGrid;
use gridly::prelude::*;

let grid = VecGrid::new_with((Rows(2), Columns(2)), |loc| loc.row.0 + loc.column.0).unwrap();
assert_eq!(grid.get((0, 0)), Ok(&0));
assert_eq!(grid.get((0, 1)), Ok(&1));
assert_eq!(grid.get((1, 0)), Ok(&1));
assert_eq!(grid.get((1, 1)), Ok(&2));
assert!(grid.get((1, 2)).is_err());

pub fn new_row_major( dimensions: impl VectorLike, input: impl IntoIterator<Item = T>, ) -> Option<Self>

Create a new VecGrid with the given dimensions. Fills the grid in row-major order (that is, by filling the first row, then the next row, etc) by evaluating the input iterator. Returns None if the iterator was too short, or if the dimensions were invalid. If the iterator is longer than required, the remaining elements are left un-iterated.

This method will return prematurely if the iterator reports (via size_hint) that it is definitely too short.

Example:

use gridly_grids::VecGrid;
use gridly::prelude::*;

let data = [1, 2, 3, 4, 5];
let mut data_iter = data[..].iter().copied();

let grid = VecGrid::new_row_major(
    (Rows(2), Columns(2)),
    &mut data_iter
).unwrap();

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

// excess elements in the iterator are still available
assert_eq!(data_iter.next(), Some(5));
assert_eq!(data_iter.next(), None);

pub fn new_from_rows<R, C>(rows: R) -> Option<Self>

where R: IntoIterator<Item = C>, C: IntoIterator<Item = T>,

Create a new VecGrid from an iterator of rows. Each row should be an iterator of items in the row. The dimensions are deduced automatically from the number of rows and columns. Returns None If the number of columns is mismatched between any two rows. If the rows iterator is empty, the returned dimensions are (0, 0).

Examples

Basic example

use gridly_grids::VecGrid;
use gridly::prelude::*;

let rows = vec![
    vec![1, 2, 3],
    vec![4, 5, 6],
    vec![7, 8, 9],
];

let grid = VecGrid::new_from_rows(&rows).unwrap();

assert_eq!(grid[(0, 0)], &1);
assert_eq!(grid[(1, 1)], &5);
assert_eq!(grid[(2, 2)], &9);

Empty grid example

use gridly_grids::VecGrid;
use gridly::prelude::*;

// Note that, even though the column width here is 5, no rows
// are ever iterated, so VecGrid is forced to assume (0, 0)
// dimensions.
let rows: [[isize; 5]; 0] = [];

let grid = VecGrid::new_from_rows(&rows).unwrap();

assert_eq!(grid.dimensions(), (0, 0));

Mismatched row length example

use gridly_grids::VecGrid;
use gridly::prelude::*;

let rows = vec![
    vec![1, 2, 3],
    vec![4, 5],
];

let grid = VecGrid::new_from_rows(&rows);

assert!(grid.is_none());

pub fn fill_with(&mut self, gen: impl Fn() -> T)

Fill every cell in the grid with the values produced by repeatedly calling gen. Called in an unspecified order.

Example

use gridly_grids::VecGrid;
use gridly::prelude::*;

let mut grid: VecGrid<isize> = VecGrid::new((Rows(2), Columns(2))).unwrap();

grid.fill_with(|| 3);
assert_eq!(grid.get((0, 0)), Ok(&3));
assert_eq!(grid.get((0, 1)), Ok(&3));
assert_eq!(grid.get((1, 0)), Ok(&3));
assert_eq!(grid.get((1, 1)), Ok(&3));
assert!(grid.get((1, 2)).is_err());

pub fn fill_row_major(&mut self, input: impl IntoIterator<Item = T>)

Fill the grid in row-major order with values from an iterator. That is, fill the first row, then the next row, etc.

If the iterator is longer than the volume of the grid, the remaining elements are left un-iterated. If the iterator is shorter than the volume of the grid, the remaining existing elements in the grid are left unaltered.

Example

use gridly_grids::VecGrid;
use gridly::prelude::*;

let mut grid = VecGrid::new_fill((Rows(2), Columns(2)), &10).unwrap();
let values = [1, 2, 3];
let values_iter = values[..].iter().copied();

grid.fill_row_major(values_iter);

assert_eq!(grid[(0, 0)], 1);
assert_eq!(grid[(0, 1)], 2);
assert_eq!(grid[(1, 0)], 3);
assert_eq!(grid[(1, 1)], 10);

impl<T: Default> VecGrid<T>

pub fn new(dimensions: impl VectorLike) -> Option<Self>

Create a new VecGrid filled with the default value of T in each cell

Example

use gridly_grids::VecGrid;
use gridly::prelude::*;

let grid: VecGrid<isize> = VecGrid::new((Rows(2), Columns(2))).unwrap();
assert_eq!(grid.get((0, 0)), Ok(&0));
assert_eq!(grid.get((0, 1)), Ok(&0));
assert_eq!(grid.get((1, 0)), Ok(&0));
assert_eq!(grid.get((1, 1)), Ok(&0));
assert!(grid.get((1, 2)).is_err());

pub fn new_row_major_default( dimensions: impl VectorLike, input: impl IntoIterator<Item = T>, ) -> Option<Self>

Create a new VecGrid with the given dimensions. Fills the grid in row-major order (that is, by filling the first row, then the next row, etc) by evaluating the input iterator. Returns None if the dimensions were invalid. If the iterator is shorter than required to fill the grid, the remaining elements are filled with T::default. If the iterator is longer than required, the remaining elements are left un-iterated.

Example:

use gridly_grids::VecGrid;
use gridly::prelude::*;

let data = [1, 2, 3];
let data_iter = data[..].iter().copied();

let grid = VecGrid::new_row_major_default(
    (Rows(2), Columns(2)),
    data_iter
).unwrap();

assert_eq!(grid[(0, 0)], 1);
assert_eq!(grid[(0, 1)], 2);
assert_eq!(grid[(1, 0)], 3);
assert_eq!(grid[(1, 1)], 0);

pub fn clear(&mut self)

Replace all the cells in the grid with the default value. Doesn’t change the dimensions of the grid.

Example

use gridly_grids::VecGrid;
use gridly::prelude::*;

let mut grid = VecGrid::new_fill((Rows(2), Columns(2)), &5).unwrap();
grid.clear();
assert_eq!(grid.get((0, 0)), Ok(&0));
assert_eq!(grid.get((0, 1)), Ok(&0));
assert_eq!(grid.get((1, 0)), Ok(&0));
assert_eq!(grid.get((1, 1)), Ok(&0));
assert!(grid.get((1, 2)).is_err());

impl<T: Clone> VecGrid<T>

pub fn new_fill(dimensions: impl VectorLike, value: &T) -> Option<Self>

Create a new VecGrid filled with clones of value

Example

use gridly_grids::VecGrid;
use gridly::prelude::*;

let grid = VecGrid::new_fill((Rows(2), Columns(2)), &"Hello").unwrap();
assert_eq!(grid.get((0, 0)), Ok(&"Hello"));
assert_eq!(grid.get((0, 1)), Ok(&"Hello"));
assert_eq!(grid.get((1, 0)), Ok(&"Hello"));
assert_eq!(grid.get((1, 1)), Ok(&"Hello"));
assert!(grid.get((1, 2)).is_err());

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

Fill every element in the grid with clones of value.

Example

use gridly_grids::VecGrid;
use gridly::prelude::*;

let mut grid = VecGrid::new((Rows(2), Columns(2))).unwrap();

grid.fill(&"Hello");
assert_eq!(grid.get((0, 0)), Ok(&"Hello"));
assert_eq!(grid.get((0, 1)), Ok(&"Hello"));
assert_eq!(grid.get((1, 0)), Ok(&"Hello"));
assert_eq!(grid.get((1, 1)), Ok(&"Hello"));
assert!(grid.get((1, 2)).is_err());

impl<T: Copy> VecGrid<T>

pub fn new_fill_copied(dimensions: impl VectorLike, value: T) -> Option<Self>

Create a new VecGrid filled with copies of value.

Example

use gridly_grids::VecGrid;
use gridly::prelude::*;

let grid = VecGrid::new_fill_copied((Rows(2), Columns(2)), 10).unwrap();
assert_eq!(grid.get((0, 0)), Ok(&10));
assert_eq!(grid.get((0, 1)), Ok(&10));
assert_eq!(grid.get((1, 0)), Ok(&10));
assert_eq!(grid.get((1, 1)), Ok(&10));
assert!(grid.get((1, 2)).is_err());

Trait Implementations

impl<T: Clone> Clone for VecGrid<T>

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

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T: Debug> Debug for VecGrid<T>

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

Formats the value using the given formatter.

impl<T> Grid for VecGrid<T>

type Item = T

The item type stored in the grid

unsafe fn get_unchecked(&self, location: Location) -> &T

Get a reference to a cell, without doing bounds checking. Implementors of this method are allowed to assume that bounds checking has already been performed on the location, which means that implementors are allowed to do their own unsafe get operations on the underlying storage, where relevant / possible.

fn get(&self, location: impl LocationLike) -> Result<&Self::Item, BoundsError>

Get a reference to a cell in a grid. Returns an error if the location is out of bounds with the specific boundary violation.

fn view<T>(&self) -> View<'_, Self, T>

where T: Component,

Get a view of a grid, over its rows or columns. A view of a grid is similar to a slice, but instead of being a view over specific elements, it’s a view over the rows and columns. See [View] for details.

fn rows(&self) -> View<'_, Self, Row>

Get a view of a grid’s rows. See [View] for details.

fn columns(&self) -> View<'_, Self, Column>

Get a view of a grid’s columns. See [View] for details.

unsafe fn single_view_unchecked<T>(&self, index: T) -> SingleView<'_, Self, T>

where T: Component,

Get a view of a single row or column in a grid, without bounds checking that row or column index.

unsafe fn row_unchecked(&self, row: Row) -> SingleView<'_, Self, Row>

Get a view of a single row in a grid, without bounds checking that row’s index.

unsafe fn column_unchecked( &self, column: Column, ) -> SingleView<'_, Self, Column>

Get a view of a single column in a grid, without bounds checking that column’s index.

fn single_view<T>( &self, index: T, ) -> Result<SingleView<'_, Self, T>, RangeError<T>>

where T: Component,

Get a view of a single row or column in a grid. Returns an error if the index of the row or column is out of bounds for the grid.

fn row( &self, row: impl Into<Row>, ) -> Result<SingleView<'_, Self, Row>, RangeError<Row>>

Get a view of a single row in a grid. Returns an error if the index of the row is out of bounds for the grid.

fn column( &self, column: impl Into<Column>, ) -> Result<SingleView<'_, Self, Column>, RangeError<Column>>

Get a view of a single column in a grid. Returns an error if the index of the column is out of bounds for the grid.

fn display_with<T, F>(&self, func: F) -> DisplayAdapter<&Self, F>

where F: Fn(&Self::Item) -> T, T: Display,

Make a grid Displayable, using a function that defines how each of its cells are printed. For each row, the adapter simply prints each cell in the row, followed by a newline.

impl<T> GridBounds for VecGrid<T>

fn dimensions(&self) -> Vector

Get the dimensions of the grid, as a Vector. The dimensions of must be >= 0.

fn root(&self) -> Location

Return the root location (ie, the top left) of the grid. All valid locations on the grid have location >= root. For most grids, this can just be Location::zero

fn outer_bound(&self) -> Location

Get the outer bound of the grid; that is, the location for which all valid locations in the grid have row < outer.row && column < outer.column

fn num_rows(&self) -> Rows

Get the height of the grid in Rows.

fn num_columns(&self) -> Columns

Get the width of the grid, in Columns.

fn dimension<C>(&self) -> C

where C: Component,

Get the height or width of this grid.

fn root_row(&self) -> Row

Return the index of the topmost row of this grid. For most grids, this is 0, but some grids may include negatively indexed locations, or even offsets.

fn root_column(&self) -> Column

Return the index of the leftmost column of this grid. For most grids, this is 0, but some grids may include negatively indexed locations, or even offsets.

fn root_component<C>(&self) -> C

where C: Component,

Return the index of the leftmost column or topmost row of this grid.

fn row_range(&self) -> ComponentRange<Row>

Get a range iterator over all the Row indexes in this grid

fn column_range(&self) -> ComponentRange<Column>

Get a range iterator over all the Column indexes in this grid

fn range<C>(&self) -> ComponentRange<C>

where C: Component,

Get a range iterator over the row or column indexes

fn check_component<C>(&self, c: C) -> Result<C, RangeError<C>>

where C: Component,

Check that a Row or a Column is inside the bounds described by this grid. Returns the component if it’s inside the bounds, or an error describing the violated boundary if not. This function is intended to help write more expressive code; ie, grid.check_component(Row(10)).and_then(|row| ...).

fn check_row(&self, row: impl Into<Row>) -> Result<Row, RangeError<Row>>

Check that a Row is inside the bounds described by this grid. Returns the component if it’s inside the bounds, or an error describing the violated boundary if not. This function is intended to help write more expressive code; ie, grid.check_row(10).and_then(|row| ...).

fn check_column( &self, column: impl Into<Column>, ) -> Result<Column, RangeError<Column>>

Check that a Column is inside the bounds described by this grid. Returns the component if it’s inside the bounds, or an error describing the violated boundary if not. This function is intended to help write more expressive code; ie, grid.check_column(10).and_then(|row| ...).

fn component_in_bounds<C>(&self, c: C) -> bool

where C: Component,

Returns true if a Row or Column is inside the bounds described by this grid.

fn row_in_bounds(&self, row: impl Into<Row>) -> bool

Returns true if a Row is inside the bounds described by this grid.

fn column_in_bounds(&self, column: impl Into<Column>) -> bool

Returns true if a Column is inside the bounds described by this grid.

fn check_location( &self, location: impl LocationLike, ) -> Result<Location, BoundsError>

Check that a location is inside the bounds of this grid.

fn location_in_bounds(&self, location: impl LocationLike) -> bool

Returns true if a locaton is inside the bounds of this grid.

impl<T> GridMut for VecGrid<T>

unsafe fn get_unchecked_mut(&mut self, location: Location) -> &mut T

Get a mutable reference to a cell, without doing bounds checking. Implementors of this method are allowed to assume that bounds checking has already been performed on the location, which means that implementors are allowed to do their own unsafe get_mut operations on the underlying storage, where relevant / possible.

fn get_mut( &mut self, location: impl LocationLike, ) -> Result<&mut Self::Item, BoundsError>

Get a reference to a cell in a grid. Returns an error if the location is out of bounds with the specific boundary violation.

impl<T> GridSetter for VecGrid<T>

unsafe fn replace_unchecked(&mut self, location: Location, value: T) -> T

Replace the value at the given location with value, without bounds checking location. Returns the previous value in the grid.

unsafe fn set_unchecked(&mut self, location: Location, value: T)

Replace the value at the given location with value, without bounds checking location.

fn replace( &mut self, location: impl LocationLike, value: Self::Item, ) -> Result<Self::Item, BoundsError>

Replace the value at the given location with value. Returns the previous value in the grid, or an error if the location was out of bounds.

fn set( &mut self, location: impl LocationLike, value: Self::Item, ) -> Result<(), BoundsError>

Set the value at the given location in the grid. Returns an error if the location was out of bounds.

impl<T, L: LocationLike> Index<L> for VecGrid<T>

type Output = T

The returned type after indexing.

fn index(&self, location: L) -> &T

Performs the indexing (container[index]) operation.

impl<T, L: LocationLike> IndexMut<L> for VecGrid<T>

fn index_mut(&mut self, location: L) -> &mut T

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