Crate vecgrid 

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 and from_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 and from_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 and filled_by_column_major).
• Providing an iterator that is used to produce values to fill the vecgrid (see from_iter_row_major and from_iter_column_major).

Extending a Vecgrid

Since Vecgrids 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 to insert_rows.
• Append the grid, either with matching length rows via append_rows… or future additions!
• Remove singular or consecutive rows via remove_row and remove_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, and set methods, which return an Option or a Result 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 and elements_column_major_iter).
• All of the elements as mutable references, in row major or column major order (see elements_row_major_iter_mut and elements_column_major_iter_mut).
• Individual rows or columns (see row_iter and column_iter).
• Individual rows and columns of mutable entries (see row_iter_mut and column_iter_mut).
• All rows or all columns (see rows_iter and columns_iter).
• All rows or all columns of mutable entries (see rows_iter_mut and columns_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 (see as_rows and as_columns).
• A “flat” Vec of elements in either row major or column major order (see as_row_major and as_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

Vecgrid

A dynamically sized two-dimensional vec.

Enums

Error

An error that can arise during the use of an Vecgrid.