vecgrid

Vecgrid 提供了一个动态大小的二维向量。它比向量向量更高效、更易用，即 Vec<Vec<T>>。

这在使用网格状结构时很有用，这在图像处理、游戏开发和其他情况下很常见。当行或列可能具有不同长度时，不能使用 Vecgrid（所有行和列的长度必须相同）。

Vecgrid 是静态大小二维数组库 Array2D 的分支。

路线图

此项目试图以有见地的风格扩展上游项目，通过添加可变迭代器和内部集合的动态调整大小。以下是进展情况

• row_iter_mut
• column_iter_mut
• rows_iter_mut
• columns_iter_mut
• elements_row_major_iter_mut
• elements_column_major_iter_mut
• insert_row
• insert_column
• insert_rows
• insert_columns
• remove_row
• remove_column
• remove_rows
• remove_columns
• append_rows
• append_columns
• extend_rows
• extend_columns

上游代码可能会在途中重构，以利用优化或使方法在整个 crate 中保持一致。从此 crate 的初始版本之前删除的上游弃用代码将被删除，未来可能或可能不会在此 crate 中弃用类似的上游弃用代码。此 crate 的主要版本发布表明其成熟度超过了上游存储库的积极跟踪，但在此之前，更改将按发生情况进行同步。

如何使用 Vecgrid

创建 Vecgrid

创建 Vecgrid 有许多不同的方式。这些包括

• 提供行或列，这些行或列必须具有相同的大小（参见 from_rows 和 from_columns）。
• 提供一个元素“平面”向量，这些元素按行主序或列主序排列，同时提供维度，这些维度必须与向量中的元素数量匹配（参见 from_row_major 和 from_column_major）。
• 提供一个值，该值将在每个位置重复使用（参见 filled_with）。
• 提供一个生成器函数，该函数被反复调用以生成填充vecgrid的值（参见 filled_by_row_major 和 filled_by_column_major）。
• 提供一个迭代器，用于生成填充vecgrid的值（参见 from_iter_row_major 和 from_iter_column_major）。

扩展Vecgrid

由于Vecgrid是动态大小的，因此可以扩展它们

• 提供与行索引匹配的单一行，并通过insert_row提供，或通过insert_rows提供行的可变切片。
• 通过append_rows... 添加匹配长度的行或未来的添加来扩展网格。
• 通过remove_row和remove_rows分别移除单一或连续的行。

访问Vecgrid中的数据

Vecgrid支持几种索引形式

• 使用索引语法（方括号）与一个(usize, usize)元组，在越界访问时引发恐慌。
• 使用get、get_mut和set方法，在越界访问时返回一个Option或一个Result。
• 使用这些方法的行优先或列优先版本，即 get_row_major、get_mut_row_major、set_row_major、get_column_major、get_mut_column_major、set_column_major。这些方法与行/列非优先方法执行相同的任务，但只使用一个索引而不是两个。

Vecgrid 还支持几种迭代形式。您可以遍历

• 所有元素，无论是按 行优先或列优先（参见 elements_row_major_iter 和 elements_column_major_iter）。
• 所有元素的可变引用，按 行优先或列优先（参见 elements_row_major_iter_mut 和 elements_column_major_iter_mut）。
• 单独的行或列（参见 row_iter 和 column_iter）。
• 单独的行和列的可变条目（参见 row_iter_mut 和 column_iter_mut）。
• 所有行或所有列（参见 rows_iter 和 columns_iter）。
• 所有行或所有列的可变条目（参见 rows_iter_mut 和 columns_iter_mut）。

从 Vecgrid 中提取所有数据

一个 Vecgrid 可以通过几个方法转换回一个 Vec。您可以将数据提取为

• 一个行或列的 Vec（参见 as_rows 和 as_columns）。
• 一个“扁平”的Vec元素数组，以行主序或列主序排列（参见as_row_major和as_column_major）。

示例

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  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)?;
    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(())
}

致谢

本库的实现得益于作者HarrisonMc555在Array2D中打下的坚实基础，以及tylerjw对上游项目的贡献。《Array2D》在MIT许可证下发布。

许可证：MIT