Crate bidivec

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:

• Copy (blitting) of rectangles of one data structure to another, either through Copy and Clone traits (using the editing::copy and editing::clone_over methods) or using a custom blending function (editing::blend).
• Flood fill with customizable actions and comparisons (editing::flood_fill).
• Transformations implemented to view the data structures as transposed, cropped, BidiView::to_rotated270ccw(), and more.
• In-place transformations for mutable data structures to transpose, crop, rotate, etc.
• Iterators, including iterators over portions of data structures, and the possibility of enumerating the original coordinates together with items.
• Pathfinding algorithms for 2D tiled maps, doing Djikstra algorithm on single source, multiple destinations and either Djikstra or A* for singe-source, single-destination.

Modules

bidiiter

A module containing iterator types for bidimensional data structures.

editing

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

pathfinding

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).

transforming

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

Macros

bidiarray

Creates a BidiArray containing the arguments.

bidigrowvec

Creates a BidiGrowVec containing the arguments.

bidivec

Creates a BidiVec containing the arguments.

Structs

BidiArray

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).

BidiGrowVec

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.

BidiMutSlice

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

BidiRect

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().

BidiRectSigned

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().

BidiSlice

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

BidiVec

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

Enums

BidiError

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

BidiNeighbours

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

Traits

BidiFrom

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

BidiView

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

BidiViewMut

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

BidiViewMutIterable

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.