first commit

.gitignore

@@ -0,0 +1,3 @@
+/target/
+**/*.rs.bk
+Cargo.lock

Cargo.toml

@@ -0,0 +1,18 @@
+[package]
+name = "nested"
+version = "0.1.0"
+authors = ["Johann Tuffe <[email protected]>"]
+description = "A memory efficient container for nested collections (like `Vec<String>` or `Vec<Vec<T>>`)"
+
+documentation = "https://docs.rs/nested"
+repository = "https://github.com/tafia/nested"
+
+readme = "README.md"
+keywords = ["vec", "packed", "heap", "collection", "container"]
+categories = ["caching", "data-structures"]
+license = "MIT"
+
+[badges]
+travis-ci = { repository = "tafia/nested" }
+
+[dependencies]

LICENSE-MIT.md

@@ -0,0 +1,23 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Johann Tuffe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

README.md

@@ -0,0 +1,58 @@
+# nested
+
+A memory efficient container for nested collections.
+
+This crate is intended to be used when:
+- you want a potentially large:
+  - `Vec<String>`
+  - `Vec<Vec<T>>`
+  - `Vec<C>` where `C` is heap allocated, dynamically sized and can implement `Collection` trait
+- you actually only need to use borrowed items (`&[T]` or `&str`)
+
+Instead of having n + 1 allocations, you'll only have 2.
+
+## Example
+
+```rust
+use nested::Nested;
+
+let mut v = Nested::<String>::new();
+
+// you can either populate it one by one
+v.push("a");
+v.push("bb".to_string());
+v.push("hhh");
+v.extend(vec!["iiiiii".to_string(), "jjjj".to_string()]);
+assert_eq!(v.len(), 5);
+assert_eq!(&v[0], "a");
+assert_eq!(&v[1], "bb");
+
+// or you can directly collect it
+let mut v = ["a", "b", "c", "d", "e", "f", "g"].iter().collect::<Nested<String>>();
+assert_eq!(v.len(), 7);
+
+// it also provides basic operations
+let u = v.split_off(2);
+assert_eq!(u.get(0), Some("c"));
+
+v.truncate(1);
+assert_eq!(v.pop(), Some("a".to_string()));
+assert_eq!(v.pop(), None);
+```
+
+## Benches
+
+See benches directory.
+
+Here are the benches for collecting all words in src/lib.rs file:
+
+```
+test bench_nested_string      ... bench:      92,909 ns/iter (+/- 17,258)
+test bench_nested_string_iter ... bench:     110,710 ns/iter (+/- 13,485)
+test bench_vec_string         ... bench:     159,431 ns/iter (+/- 37,868)
+test bench_vec_string_iter    ... bench:     173,718 ns/iter (+/- 14,779)
+```
+
+## Licence
+
+MIT

benches/bench.rs

@@ -0,0 +1,61 @@
+#![feature(test)]
+
+extern crate nested;
+extern crate test;
+
+use test::Bencher;
+use nested::Nested;
+
+/// A function which reads src/lib.rs and return a String.
+///
+/// Note:
+/// It is for benchmarking purpose where we want to remove IO.
+/// In general, you don't want to return a whole String but you prefer
+/// working with a Read or BufRead directly.
+fn src_lib() -> String {
+    use std::io::{Read, BufReader};
+    let mut file = BufReader::new(::std::fs::File::open("src/lib.rs").unwrap());
+    let mut res = String::new();
+    file.read_to_string(&mut res).unwrap();
+    res
+}
+
+#[bench]
+fn bench_vec_string(b: &mut Bencher) {
+    let src = src_lib();
+    b.iter(|| {
+        let words = src.split_whitespace().map(|s| s.to_string()).collect::<Vec<_>>();
+        assert!(words.len() > 1000)
+    });
+}
+
+#[bench]
+fn bench_nested_string(b: &mut Bencher) {
+    let src = src_lib();
+    b.iter(|| {
+        let words = src.split_whitespace().collect::<Nested<String>>();
+        assert!(words.len() > 1000)
+    });
+}
+
+#[bench]
+fn bench_vec_string_iter(b: &mut Bencher) {
+    let src = src_lib();
+    b.iter(|| {
+        let words = src.split_whitespace().map(|s| s.to_string()).collect::<Vec<_>>();
+        assert!(words.len() > 1000);
+        let words_with_a = words.iter().filter(|w| w.contains('a')).count();
+        assert!(words_with_a > 100)
+    });
+}
+
+#[bench]
+fn bench_nested_string_iter(b: &mut Bencher) {
+    let src = src_lib();
+    b.iter(|| {
+        let words = src.split_whitespace().collect::<Nested<String>>();
+        assert!(words.len() > 1000);
+        let words_with_a = words.iter().filter(|w| w.contains('a')).count();
+        assert!(words_with_a > 100)
+    });
+}