feat!: iterators and benchmarks. (#5)

.github/workflows/README.md

@@ -19,6 +19,8 @@ Todo: cargo geiger
 
 [https://gist.github.com/LukeMathWalker/5ae1107432ce283310c3e601fac915f3|Github Actions by Luca Palmieri]
 
-[https://github.com/actions-rs|Rust support for Github Actions]
+[https://shift.click/blog/github-actions-rust/|A Few Github Action “Recipes” for Rust]
+
+[https://github.com/actions-rs|Rust support for Github Actions (unmaintained)]
 
 [https://github.com/codecov/codecov-action|Action for Codecov Integration]

CONTRIBUTING.md

@@ -6,9 +6,12 @@ dual licensed as above, without any additional terms or conditions.
 
 # Conventions
 
-- Semver Versioning Scheme: https://semver.org/spec/v2.0.0.html
-- Commit Messages: https://www.conventionalcommits.org/en/v1.0.0/
-- API Guidelines: https://rust-lang.github.io/api-guidelines/
+- [Semver Versioning Scheme](https://semver.org/spec/v2.0.0.html)
+- [Commit Messages](https://www.conventionalcommits.org/en/v1.0.0/)
+- [API Guidelines](https://rust-lang.github.io/api-guidelines/)
+- [Std Dev Guidelines](https://std-dev-guide.rust-lang.org/about.html)
+  - When to [`#[inline]`](https://std-dev-guide.rust-lang.org/policy/inline.html)
+  - When to add [`#[must use]`](https://std-dev-guide.rust-lang.org/policy/must-use.html)
 
 # Version control
 

Cargo.toml

@@ -34,7 +34,12 @@ optional = true
 
 # Required for integration tests
 [dev-dependencies]
+criterion = { version = "0.5.1", features = ["html_reports"] }
+rand = "0.8.1"
 
+[[bench]]
+name = "inserts"
+harness = false
 
 # Dedicated target for tests to avoid having one crate per test file, allows code sharing across multiple test files
 # How to run tests:

README.md

@@ -128,12 +128,15 @@ Demonstrate capabilities!
 - Example showing how to use this library with MySQL.
 
 ## Version 0.3.0 (planned)
+- Reimplement using std::collections::BTreeMap.
+- Complete docs `#![deny(missing_docs)]`.
 - Example showing how to use this library with PostgreSQL.
 
-## Version 0.2.0 (in progress)
-- Support iterators for `Sequence`
-- Support serde's `#[derive(Serialize, Deserialize)]`
-- Support the trait `Clone`
+## Version 0.2.0 (delivered)
+- Implement `Iterator` and `IntoIterator` for `Sequence`.
+- Support serde's `#[derive(Serialize, Deserialize)]`.
+- Support the trait `Clone`.
+- Introduce benchmarking and publish results on GitHub.
 
 ## Version 0.1.0 (delivered)
 - Initial release.
@@ -153,26 +156,36 @@ See [CONTRIBUTING](CONTRIBUTING.md) for more details.
 # Appendix
 
 ## Cargo Geiger Safety Report
-
 ```
+
 Metric output format: x/y
     x = unsafe code used by the build
     y = total unsafe code found in the crate
 
 Symbols: 
-    :) = No `unsafe` usage found, declares #![forbid(unsafe_code)]
-    ?  = No `unsafe` usage found, missing #![forbid(unsafe_code)]
-    !  = `unsafe` usage found
+    🔒  = No `unsafe` usage found, declares #![forbid(unsafe_code)]
+    ❓  = No `unsafe` usage found, missing #![forbid(unsafe_code)]
+    ☢️  = `unsafe` usage found
 
 Functions  Expressions  Impls  Traits  Methods  Dependency
 
-0/0        0/0          0/0    0/0     0/0      :) kodiak-sets 0.1.0
-0/0        0/0          0/0    0/0     0/0      ?  └── num-integer 0.1.45
-0/0        6/12         0/0    0/0     0/0      !      └── num-traits 0.2.15
+0/0        0/0          0/0    0/0     0/0      🔒  kodiak-sets 0.2.0
+0/0        0/0          0/0    0/0     0/0      ❓  ├── num-integer 0.1.45
+0/0        0/12         0/0    0/0     0/0      ❓  │   └── num-traits 0.2.15
+0/0        0/5          0/0    0/0     0/0      ❓  └── serde 1.0.164
+0/0        0/0          0/0    0/0     0/0      ❓      └── serde_derive 1.0.164
+0/0        0/15         0/0    0/0     0/3      ❓          ├── proc-macro2 1.0.63
+0/0        0/4          0/0    0/0     0/0      ❓          │   └── unicode-ident 1.0.9
+0/0        0/0          0/0    0/0     0/0      ❓          ├── quote 1.0.28
+0/0        0/15         0/0    0/0     0/3      ❓          │   └── proc-macro2 1.0.63
+0/0        0/79         0/3    0/0     0/2      ❓          └── syn 2.0.22
+0/0        0/15         0/0    0/0     0/3      ❓              ├── proc-macro2 1.0.63
+0/0        0/0          0/0    0/0     0/0      ❓              ├── quote 1.0.28
+0/0        0/4          0/0    0/0     0/0      ❓              └── unicode-ident 1.0.9
+
+0/0        0/115        0/3    0/0     0/5    
 
-0/0        6/12         0/0    0/0     0/0
 ```
-
 ## License
 
 Licensed under either of

RELEASE.md

@@ -1,22 +1,72 @@
 Just a short checklist on merging a feature branch and publishing a release.
 
+# Preflight check
+
+No matter what you plan to do, make the preflight check.
+
+* Run the benchmarks.
+```
+cargo criterion
+```
+
+* Check the test coverage. Make sure to use LLVM as engine.
+```
+cargo tarpaulin --engine llvm
+```
+
+* Run the tests.
+```
+cargo test
+```
+
+* Check the linter.
+```
+cargo clippy
+```
+
+* Fix formatting issues.
+```
+cargo fmt
+```
+
 # Merge a feature branch
 
-* Review CI results of to be merged feature branch
-* Merge feature branch
+* Test all examples.
+* Update benchmarks.
+
+```
+cargo criterion
+```
+
+* Review benchmark results and add benchmarks to repo.
+
+```
+cp -a target/criterion benchmarks/VERSION
+```
+
+* Commit changes to feature branch.
+
+```
+git add .
+git commit -m "feat!: ... ."
+```
+
+* Review CI results of to be merged feature branch.
+* Merge feature branch.
 
 ```
 git checkout main
 git merge --squash <FEATURE_BRANCH>
 ```
 
 * Change version in Cargo.toml
+* Update Geiger report in README
 
 ```
 cargo clean
 cargo geiger --all-features --output-format GitHubMarkdown --update-readme
 ```
- 
+
 * Review README.md
 * Update roadmap in README.md
 
@@ -47,7 +97,7 @@ cargo publish
 On GitHub:
 
 * Create a tag with pattern vx.y.z
-* Release title: kodiak-sequence-vx.y.z
+* Release title: kodiak-sets-vx.y.z
 * Write some release notes (mainly inspired by roadmap and git log)
 
 # Links

benches/helper.rs

@@ -0,0 +1,14 @@
+#[cfg(not(tarpaulin_include))]
+#[inline]
+pub fn next_ascii_char(c: char, offset: u8) -> Option<char> {
+    if c.is_ascii() {
+        let ascii_val = c as u8;
+        if ascii_val + offset <= u8::MAX {
+            Some((ascii_val + offset) as char)
+        } else {
+            None // Max ASCII value reached
+        }
+    } else {
+        None // Not an ASCII character
+    }
+}

benches/inserts.rs

@@ -0,0 +1,74 @@
+use criterion::{black_box, criterion_group, criterion_main, Criterion};
+
+use kodiak_sets::Sequence;
+
+mod helper;
+use helper::next_ascii_char;
+
+fn seq_new_insert_at_last_index(n: usize) {
+    let mut seq: Sequence<char> = Sequence::new();
+    let mut i: usize = 0;
+
+    while i < n {
+        seq.insert(i, next_ascii_char('A', (i % 10) as u8).unwrap());
+        i += 1;
+    }
+}
+
+fn vew_new_insert_at_last_index(n: usize) {
+    let mut vec: Vec<char> = Vec::new();
+    let mut i: usize = 0;
+
+    while i < n {
+        vec.insert(i, next_ascii_char('A', (i % 10) as u8).unwrap());
+        i += 1;
+    }
+}
+
+fn seq_with_capacity_insert_at_last_index(n: usize) {
+    let mut seq: Sequence<char> = Sequence::with_capacity(n);
+    let mut i: usize = 0;
+
+    while i < n {
+        seq.insert(i, next_ascii_char('A', (i % 10) as u8).unwrap());
+        i += 1;
+    }
+}
+
+#[allow(unused)]
+fn vec_with_capacity_insert_at_last_index(n: usize) {
+    let mut vec: Vec<char> = Vec::with_capacity(n);
+    let mut i: usize = 0;
+
+    while i < n {
+        vec.insert(i, next_ascii_char('A', (i % 10) as u8).unwrap());
+        i += 1;
+    }
+}
+
+fn bench_seq_new_vs_with_capacity(c: &mut Criterion) {
+    let mut group = c.benchmark_group("bench_new_vs_with_capacity");
+    let n = 1_000_000;
+
+    group.bench_function(format!("seq new - insert {} chars", n).as_str(), |b| {
+        b.iter(|| seq_new_insert_at_last_index(black_box(n)))
+    });
+    group.bench_function(format!("seq with capacity - insert {} chars", n).as_str(), |b| {
+        b.iter(|| seq_with_capacity_insert_at_last_index(black_box(n)))
+    });
+}
+
+fn bench_seq_vs_vec_new(c: &mut Criterion) {
+    let mut group = c.benchmark_group("bench_seq_vs_vec_new");
+    let n = 1_000_000;
+
+    group.bench_function(format!("vec new - insert {} chars", n).as_str(), |b| {
+        b.iter(|| vew_new_insert_at_last_index(black_box(n)))
+    });
+    group.bench_function(format!("seq new - insert {} chars", n).as_str(), |b| {
+        b.iter(|| seq_new_insert_at_last_index(black_box(n)))
+    });
+}
+
+criterion_group!(benches, bench_seq_new_vs_with_capacity, bench_seq_vs_vec_new);
+criterion_main!(benches);

benchmarks/0.2.0/data/main/bench_new_vs_with_capacity/seq new - insert 1000000 chars/benchmark.cbor

@@ -0,0 +1 @@
+�bid�hgroup_idxbench_new_vs_with_capacitykfunction_idxseq new - insert 1000000 charsivalue_str�jthroughput�mlatest_recordxmeasurement_230819154548.cbor

benchmarks/0.2.0/data/main/bench_new_vs_with_capacity/seq with capacity - insert 1000000 chars/benchmark.cbor

@@ -0,0 +1 @@
+�bid�hgroup_idxbench_new_vs_with_capacitykfunction_idx(seq with capacity - insert 1000000 charsivalue_str�jthroughput�mlatest_recordxmeasurement_230819154604.cbor

benchmarks/0.2.0/data/main/bench_seq_vs_vec_new/seq new - insert 1000000 chars/benchmark.cbor

@@ -0,0 +1 @@
+�bid�hgroup_idtbench_seq_vs_vec_newkfunction_idxseq new - insert 1000000 charsivalue_str�jthroughput�mlatest_recordxmeasurement_230819154630.cbor

benchmarks/0.2.0/data/main/bench_seq_vs_vec_new/vec new - insert 1000000 chars/benchmark.cbor

@@ -0,0 +1 @@
+�bid�hgroup_idtbench_seq_vs_vec_newkfunction_idxvec new - insert 1000000 charsivalue_str�jthroughput�mlatest_recordxmeasurement_230819154618.cbor