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

```rust extern crate jaggedarray; extern crate streamingiterator; use std::iter::FromIterator; use jaggedarray::{Jagged2, Jagged2Builder}; use streamingiterator::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 = builder.into(); // Alternatively, we could have created the same array from a Vec> type: let altform = Jagged2::fromiter(vec![ vec![1, 2, 3], vec![4], vec![], vec![5, 6], ]); asserteq!(a, altform);

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

// Whole rows can also be accessed and modified asserteq!(a.getrow(3), Some(&[5, 6][..])); a.getrowmut(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 StreamingIterators. 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

sh $ 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.