Expand description
Vecgrid provides a dynamically sized two-dimensional vec. It is more efficient
and is easier to use than a vector of vectors, i.e. Vec<Vec<T>>
.
This is beneficial when using a grid-like structure, which is common in image processing, game boards, and other situations. Vecgrid cannot be used when rows or columns might have different lengths—all rows and columns must be the same length.
How to use Vecgrid
Creating an Vecgrid
An Vecgrid
can be created in many different ways. These include:
- Providing the rows or the columns, which must all be the same size (see
from_rows
andfrom_columns
). - Providing a “flat” vector of elements in either row major or column
major order along with the dimensions, which must match the number of
elements in the vector (see
from_row_major
andfrom_column_major
). - Providing a value to repeatedly put in every location (see
filled_with
). - Providing a generator function that is repeatedly called to produce
values to fill the vecgrid (see
filled_by_row_major
andfilled_by_column_major
). - Providing an iterator that is used to produce values to fill the vecgrid
(see
from_iter_row_major
andfrom_iter_column_major
).
Extending a Vecgrid
Since Vecgrid
s are dynamically sized, it is possible to extend them:
- Providing singular rows of matching length alongside row indices to
insert_row
, or providing a mutable slice of rows toinsert_rows
. - Append the grid, either with matching length rows via
append_rows
… or future additions! - Remove singular or consecutive rows via
remove_row
andremove_rows
respectively.
Accessing data from an Vecgrid
Vecgrid
supports several forms of indexing:
- Using the indexing syntax (square brackets) with a tuple of
(usize, usize)
, which panics on out-of-bounds accesses. - Using the
get
,get_mut
, andset
methods, which return anOption
or aResult
on out-of-bounds accesses. - Using the row major or column major version of these methods,
i.e.
get_row_major
,get_mut_row_major
,set_row_major
,get_column_major
,get_mut_column_major
,set_column_major
. These perform the same tasks as the non row/column major methods, but take one index instead of two.
Vecgrid
also supports several forms of iteration. You can iterate
through:
- All of the elements, in either row major or column major order (see
elements_row_major_iter
andelements_column_major_iter
). - All of the elements as mutable references, in row major or column major order (see
elements_row_major_iter_mut
andelements_column_major_iter_mut
). - Individual rows or columns (see
row_iter
andcolumn_iter
). - Individual rows and columns of mutable entries (see
row_iter_mut
andcolumn_iter_mut
). - All rows or all columns (see
rows_iter
andcolumns_iter
). - All rows or all columns of mutable entries (see
rows_iter_mut
andcolumns_iter_mut
).
Extracting all data from an Vecgrid
An Vecgrid
can be converted back into a Vec
through several
methods. You can extract the data as:
- A
Vec
of rows or columns (seeas_rows
andas_columns
). - A “flat”
Vec
of elements in either row major or column major order (seeas_row_major
andas_column_major
).
Examples
use vecgrid::{Vecgrid, Error};
pub fn main() -> Result<(), Error> {
// Create a vecgrid filled with the same element.
let prefilled = Vecgrid::filled_with(42, 2, 3);
assert_eq!(prefilled.num_rows(), 2);
assert_eq!(prefilled.num_columns(), 3);
assert_eq!(prefilled[(0, 0)], 42);
// Create a vecgrid from the given rows. You can also use columns
// with the `columns` function
let rows = vec![vec![1, 2, 3], vec![4, 5, 6]];
let from_rows = Vecgrid::from_rows(rows)?;
assert_eq!(from_rows.num_rows(), 2);
assert_eq!(from_rows.num_columns(), 3);
assert_eq!(from_rows[(1, 1)], 5);
// Create a vecgrid from a flat Vec of elements in row major or
// column major order.
let column_major = vec![1, 4, 2, 5, 3, 6];
let from_column_major =
Vecgrid::from_column_major(column_major, 2, 3)?;
assert_eq!(from_column_major.num_rows(), 2);
assert_eq!(from_column_major.num_columns(), 3);
assert_eq!(from_column_major[(1, 1)], 5);
// Implements `Eq` if the element type does.
assert_eq!(from_rows, from_column_major);
// Index into a vecgrid using a tuple of usize to access or alter
// the vecgrid.
let rows = vec![vec![1, 2, 3], vec![4, 5, 6]];
let mut vecgrid = Vecgrid::from_rows(rows.clone())?;
vecgrid[(1, 1)] = 100;
// Convert the vecgrid back into a nested Vec using `as_rows` or
// `as_columns`.
let vecgrid_rows = vecgrid.as_rows();
assert_eq!(vecgrid_rows, vec![vec![1, 2, 3], vec![4, 100, 6]]);
// Convert the vecgrid back into a flat Vec using `as_row_major` or
// `as_column_major`.
let vecgrid_column_major = vecgrid.as_column_major();
assert_eq!(vecgrid_column_major, vec![1, 4, 2, 100, 3, 6]);
// Iterate over a single row or column
println!("First column:");
for element in vecgrid.column_iter(0)? {
println!("{}", element);
}
// Iterate over all rows or columns.
println!("All elements:");
for row_iter in vecgrid.rows_iter() {
for element in row_iter {
print!("{} ", element);
}
println!();
}
Ok(())
}
Structs
A dynamically sized two-dimensional vec.