toodee

TooDee is a lightweight and high performance two-dimensional wrapper around a Vec.

Core features

Raw access to the underlying vector's slice via data() and data_mut().
Creation of performant two-dimensional subsets using view() and view_mut().
Most operations are implemented for both TooDee and TooDeeViewMut structs - see below for how this pattern can be extended.
Get/set specific cells using indexing, e.g., toodee[row][col] = val.
Index with a Coordinate if you prefer, e.g., toodee[(col, row)] = val.
Index by row index (i.e., row major) to access row slices, e.g., &toodee[row].
Iteration, any which way - rows(), rows_mut(), col(), col_mut(), cells(), cells_mut().
#[no_std] compliant.
Can create a new TooDeeView from a &[T], or a TooDeeViewMut from a &mut [T].
insert_col(), remove_col(), insert_row(), and remove_row() implementations with good performance.

Additional Algorithms

CopyOps (`copy` feature, included by default)

Various operations that copy data within the same 2D array, or copy data from one array to another. Many of these operations are named like their slice counterparts, e.g., copy_from_slice() or copy_from_toodee().

TranslateOps (`translate` feature, included by default)

The TranslateOps trait provides common translation algorithms, including: - translate_with_wrap(), a way to shift data around vertically and horizontally. - flip_rows(), i.e., a mirror translation of data about the center row. - flip_cols(), i.e., a mirror translation of data about the center column.

SortOps (`sort` feature, included by default)

The SortOps trait provides efficient implementations of: - sort_by_row() operations, with stable and unstable variants. - sort_by_col() operations, with stable and unstable variants.

Build Your Own 2D Algorithms

Traits such as SortOps contain additional algorithms. These traits are defined by extending the TooDeeOpsMut trait, which has been implemented for TooDee and TooDeeViewMut. I recommend taking the same approach because the algorithms you implement will then work on both structs. This may not seem useful at first glance, but a great use case would be sorting a spreadsheet by column. If each column had a header row, you'd want to exclude that header row from sorting. You can achieve this by creating a TooDeeViewMut and sorting the view.

The implementation of your new trait could look something like:

``` pub trait FooOps : TooDeeOpsMut {

fn foo(&mut self) -> Bar {
    ...
    return bar;
}

} ```

The above code would provide a default foo() implementation that could be overridden if required. Then it's simply a matter of stating that both TooDee and TooDeeOpsMut implement FooOps:

``` impl FooOps for TooDeeViewMut<'_, T> {}

impl FooOps for TooDee {} ```

Then it's just a matter of calling the method, e.g.,

let bar = my_toodee.foo(); let bar_view = my_toodee_mut_view.foo();

Happy coding :)

TODO

More documentation, with examples.
tiles(..) and tiles_mut()?
Pathfinding algorithms?

Motivation

Similar libraries do exist, but they lacked either performance, flexibility, or functionality.

Here's a small feature comparison chart:

	Storage order	Structs supported	Growable?	Mutable views?	Raw data access?	Iterate over row slices?	Notes
`toodee::TooDee`	Row-major	Anything (`Sized`)	Yes	Yes	Yes	Yes
`image::ImageBuffer`	Row-major	`image::Pixel`	No	No	Yes	No	Good for image processing - see the `imageproc` crate.
`image::SubImage`	Row-major	`image::Pixel`	No	Yes	No	No
`grid::Grid`	Row-major	`Clone`	Yes	No	Yes	No	Similar to `TooDee`, but not as functionally rich.
`array2d::Array2D`	Row-major	`Clone`	No	No	No	No
`imgref::Img`	Row-major	Anything (`Sized`)	No	Yes	Yes	No
`nalgebra::Matrix`	Column-major	`Scalar`	Yes	Yes	Yes	No	Use this for vector/matrix math.

Goals

High performance and good flexibility, with the constraint of using a 1-D vector.
Suitable for use in image processing, but not restricted to this problem domain.
Provide solid implementations of non-trivial 2D operations.

Non-goals

GPU integration

Limitations

Views are not nested for the time being, The only impact is that the bounds() of a view are always relative to the underlying TooDee array.

License

Licensed under either of

Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.