# Crate bidivec

Expand description

A crate offering bidimensional arrays, vectors and slices, with batteries included. The crate tries to be as generic as possible, and after this, to be reasonably optimized.

## Features

The crate supports the bidimensional containers in a simple to use way thanks to a mix of macros, iterators and indexing.

For example (see `BidiVec`, `bidivec!`, `BidiRect`):

``````use bidivec::{BidiVec, bidivec, BidiRect};

// Create a new BidiVec<i32> using a macro
let mut bvec = bidivec!{
[1, 2, 3],
[4, 5, 6],
[7, 8, 9],
};

// Overwrite cell (1,1) - the 5 - with 7+8
bvec[(1, 1)] = bvec[(0, 2)] + bvec[(1, 2)];

assert_eq!(bvec, bidivec!{
[1, 2, 3],
[4, 15, 6],
[7, 8, 9]
});

// Using iterators, collect the items in a vec
let v = bvec.iter().copied().collect::<Vec<i32>>();

// Assert the result is the expected one
assert_eq!(v, vec![1, 2, 3, 4, 15, 6, 7, 8, 9]);

// Change the sign of all items in the 2x2 rect located at (1,1)
for item in bvec
.iter_mut()
.on_rect(&BidiRect::new(1, 1, 2, 2,))
{
*item = -(*item);
}

assert_eq!(bvec, bidivec!{
[1, 2, 3],
[4, -15, -6],
[7, -8, -9]
});``````

### Data structures:

All data structures offer (if appropriate) support for iterators, fast random access to any specific bidimensional location, insertion and removal of columns and row, rotations, transposition and cropping.

The supported data structures are:

• `BidiVec`: a bidimensional wrapper over `Vec<T>` that maintains a linear layout for best interoperability with native code. Can be constructed with the `bidivec!` macro.
• `BidiArray`: a bidimensional wrapper over `Box<[T]>` that also maintains a linear layout for best interoperability with native code and remains constant length (but may vary width and height). Can be constructed with the `bidiarray!` macro.
• `BidiGrowVec`: a bidimensional wrapper over a `Vec<Vec<T>>` that sacrifices memory layout and locality to offer better performances when inserting in the middle of the collection. Can be constructed with the `bidigrowvec!` macro.
• `BidiMutSlice`: a bidimensional wrapper over a `&mut [T]` slice, sacrificing some functionality to support an externally provided data store, including in-place transformations.
• `BidiSlice`: a bidimensional wrapper over a `&[T]` slice, with the same caveats as before, but immutable.

### Other functionalities:

When possible, functionalities (in addition to sometimes being implemented in optimized ways by the appropriate data structures) are applied to the `BidiView` and `BidiViewMut` traits, that are implemented by all the data strucures and easily implementable by other types.

Functionalities include:

## Modules

A module containing iterator types for bidimensional data structures.

A module containing functions to alter the contents of a `BidiViewMut`, by copy/cloning rectangles of data from another view, flood-filling, etc.

This module provides functionality to find the shortest path between two points on a 2D map represented by a `BidiView`, using Djikstra algorithm on single source (`pathfind_to_whole`), multiple destinations and either Djikstra or A* for singe-source, single-destination path findings (`pathfind_to_dest` and `pathfind_to_dest_heuristic`).

A module containing adapters that alter the behavior of a given `BidiView` (or `BidiViewMut`) to apply transformations like flips, rotations and crops.

## Macros

Creates a `BidiArray` containing the arguments.

Creates a `BidiGrowVec` containing the arguments.

Creates a `BidiVec` containing the arguments.

## Structs

A contiguous bidimensional array type with heap-allocated contents, based on an underlying `Box<[T]>`, non-growable (that is, preserving the same size, but not necessarily the same width and height).

A growable bidimensional array type with heap-allocated contents, which trades off linear layout (and memory locality) for faster performances when inserting and deleting items.

A bidimensional view over a mutable slice (for the immutable version, see `BidiSlice`). Items are expected to be linearly arranged per rows.

A simple data structure representing a bidimensional rectangle used to express ranges, areas and rects in bidimensional data structures. For an example, see `BidiVec::crop()`.

A simple data structure representing a bidimensional rectangle with a signed coordinate, used to express ranges, areas and rects in bidimensional data structures with an offset applied. For an example, see `Iter::on_border()`.

A bidimensional view over an immutable slice (for the mutable version, see `BidiMutSlice`). Items are expected to be linearly arranged per rows.

A contiguous growable bidimensional array type with heap-allocated contents, based on an underlying `Vec<T>`.

## Enums

The error type for operations on bidimensional data structures in the crate.

A definition of neighbouring elements, used in various algorithms throughout the crate.

## Traits

An object-safe trait that bidimensional data structures can implement to provide construction from other existing bidimensional data structures.

An object-safe trait providing a bidimensional view over a data structure.

An object-safe trait providing a mutable bidimensional view over a data structure.

An unsafe trait for views which can have a `BidiViewMut` mutable iterator. This is `unsafe` because additional constraints must be guaranteed by a `BidiViewMut` to be safely mutably iterable.