jagged_array 0.2.3

Owned `[[T]]`-like 2D array where each row can differ in length.
Documentation

This crate provides a jagged array, i.e. a type that is semantically equivalent to Box<[Box<[T]>]>, but implemented with better memory locality and fewer heap allocations.

Example

extern crate jagged_array;
extern crate streaming_iterator;
use std::iter::FromIterator;
use jagged_array::{Jagged2, Jagged2Builder};
use streaming_iterator::StreamingIterator;

// Create a builder object for the array, and append some data.
// Each `extend` call builds another row.
let mut builder = Jagged2Builder::new();
builder.extend(&[1, 2, 3]); // row 0 = [1, 2, 3]
builder.extend(vec![4]);    // row 1 = [4]
builder.extend(&[]);        // row 2 = []
builder.extend(5..7);       // row 3 = [5, 6]

// Finalize the builder into a non-resizable jagged array.
let mut a: Jagged2<u32> = builder.into();
// Alternatively, we could have created the same array from a Vec<Vec<T>> type:
let alt_form = Jagged2::from_iter(vec![
    vec![1, 2, 3],
    vec![4],
    vec![],
    vec![5, 6],
]);
assert_eq!(a, alt_form);

// Indexing is done in [row, column] form and supports `get` and `get_mut` variants.
assert_eq!(a[[1, 0]], 4);
*a.get_mut([1, 0]).unwrap() = 11;
assert_eq!(a.get([1, 0]), Some(&11));

// Whole rows can also be accessed and modified
assert_eq!(a.get_row(3), Some(&[5, 6][..]));
a.get_row_mut(3).unwrap()[1] = 11;
// Note that although elements are modifiable, the structure is not;
// items cannot be inserted into rows, nor can new rows be added.

// Iteration via `StreamingIterator`s. See the docs for more detail.
let mut iter = a.stream();
while let Some(row) = iter.next() {
    println!("row: {:?}", row);
}

Documentation

Documentation can be found on docs.rs

Benchmarks

$ cargo bench
test bench_access_jag   ... bench:         109 ns/iter (+/- 4)
test bench_access_vec   ... bench:         122 ns/iter (+/- 4)
test bench_collect_jag  ... bench:       2,619 ns/iter (+/- 177)
test bench_collect_vec  ... bench:       3,638 ns/iter (+/- 854)
test bench_flat_len_jag ... bench:           0 ns/iter (+/- 0)
test bench_flat_len_vec ... bench:          50 ns/iter (+/- 5)
test bench_serde_jag    ... bench:     343,839 ns/iter (+/- 36,172)
test bench_serde_vec    ... bench:     378,089 ns/iter (+/- 37,954)

*_jag indicates runtime for the Jagged2<u32> implementation, *_vec indicates runtime for Vec<Vec<u32>>. See benches/jagged2.rs for more details.

License

The code in this repository is licensed under either of

at your option.

Contribution

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