Crate block_grid[][src]

Expand description

A quick, cache-conscious, blocked 2D array.

block-grid gives you a fixed-size 2D array with a blocked / tiled memory representation. This has the sweet benefit of being much more cache-friendly if you’re often accessing nearby coordinates. It also offers a bunch of utility methods and block access. If you don’t care about tiled memory and just want any 2D-grid, see the “Using without Blocks” section below.

Example

The following example offers a tour of basic usage and some features.

use block_grid::{BlockGrid, CoordsIterator, U2};

let data: Vec<_> = (0..(4 * 6)).collect();

// Construct from row-major ordered data
let grid = BlockGrid::<usize, U2>::from_row_major(4, 6, &data)?;

// The 2D grid looks like:
// +-----------------------+
// |  0  1 |  2  3 |  4  5 |
// |  6  7 |  8  9 | 10 11 |
// |-------+-------+-------|
// | 12 13 | 14 15 | 16 17 |
// | 18 19 | 20 21 | 22 23 |
// +-----------------------+

// Indexing
assert_eq!(grid[(1, 3)], 9);

// Access raw array
let first_five = &grid.raw()[..5];
assert_eq!(first_five, &[0, 1, 6, 7, 2]);

// Iterate over blocks, and access the last
let block = grid.block_iter().last().unwrap();
assert_eq!(block[(0, 1)], 17);

// Iterate in row-major order
for (i, &x) in grid.row_major_iter().enumerate() {
    assert_eq!(x, i);
}

// Iterate in memory order, with coordinates
for ((row, col), &x) in grid.each_iter().coords() {
    assert_eq!(row * 6 + col, x);
}

Usage

Types

The primary type is BlockGrid<T, B>, where T is the stored type and B is a generic parameter that controls the block size (all the U* types below). A view of a 2D block, which is stored as a contiguous piece of memory, is a Block or BlockMut.

Indexing

Indexing is by a pair of 2D coordinates, Coords, which is simply a tuple (row, column). You can use [(i, j)] or one of the many functions. When indexing elements in a specific Block or BlockMut, the coordinates are relative, meaning it’s the row and column within that block.

Element Coordinates vs. Block Coordinates

Coordinates typically refer to the locations of specific elements, but they can also be used to index entire blocks. When using BlockGrid::block_iter chained by a .coords() call, or the Block::coords method, the returned block coordinates instead refer to the entire block. This means that (i, j) would refer to the i-th row of blocks and then the j-th block in that row. If you want the coordinates of the first (top-left) element in a block, use the Block::starts_at method instead.

Iterating

There are multiple ways of iterating over a 2D array. If you simply want to visit each element, use BlockGrid::each_iter. You can alternatively iterate in row-major order using BlockGrid::row_major_iter. Instead of iterating over elements, you can also iterate over entire blocks with BlockGrid::block_iter. For any of these, if you also need coordinates while iterating, you can chain a .coords() call. If you only need a 1D iteration count, then there’s always Iterator::enumerate.

Using without Blocks (Good Ol’ Row-Major)

If you wanna test performance against an non-blocked memory representation, you need both, or you just like the rest of the interface but don’t care about the blocks, we got you. Just use the U1 block size or the handy Grid<T> alias. All the block related methods still exist and are correct, but are just functionally useless.

Optional Features

Serde

To use the serde framework, enable the optional serde feature in your Cargo.toml. There is an important subtlety to its usage. Because the block size is generic and compile-time, you have to know B when deserializing. You could write it decide based on the input data, but I think it would lead to a bunch of extra code-gen, so I’ve left it out. It does, however, verify that B is the same value as the one originally used to serialize. If you always know the B value, then this shouldn’t matter at all.

Re-exports

pub use crate::iters::CoordsIterator;

Modules

A bunch of custom 2D iterators.

Structs

A view of a 2D block contiguous in memory.

A fixed-size 2D array with a blocked memory representation.

A mutable view of a 2D block contiguous in memory.

Traits

A type that represents compile time block dimensions.

Type Definitions

Type alias for a 2-tuple of indices, representing 2D coordinates.

Type alias for a typical 2D grid with standard row-major memory.