Crate bidivec

Source
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§

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.