add: iterators. mod: rethink crate's module structure.

.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.
@@ -160,17 +163,27 @@ Metric output format: x/y
     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        6/12         0/0    0/0     0/0
+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        5/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        15/15        0/0    0/0     3/3      ☢️          ├── proc-macro2 1.0.63
+0/0        4/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        15/15        0/0    0/0     3/3      ☢️          │   └── proc-macro2 1.0.63
+0/0        79/79        3/3    0/0     2/2      ☢️          └── syn 2.0.22
+0/0        15/15        0/0    0/0     3/3      ☢️              ├── proc-macro2 1.0.63
+0/0        0/0          0/0    0/0     0/0      ❓              ├── quote 1.0.28
+0/0        4/4          0/0    0/0     0/0      ☢️              └── unicode-ident 1.0.9
+
+0/0        109/115      3/3    0/0     5/5    
 ```
 
 ## License

RELEASE.md

@@ -47,7 +47,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,66 @@
+use criterion::{black_box, criterion_group, criterion_main, Criterion};
+
+use kodiak_sets::sequence::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);

criterion.toml

@@ -0,0 +1,2 @@
+output_format = "verbose"
+ploting_backend = "gnuplot"

examples/seq-fraction-sqlite/src/main.rs

@@ -32,12 +32,13 @@ async fn main() {
         seq.insert(n, "A".to_string());
     }
 
-    n = 0;
-    while n <= seq.len() {
-            if let Some((numerator, denominator, payload)) = seq.non_iterating_next() {
-            insert(&pool, numerator, denominator, payload).await.unwrap();
-        };
-        n += 1;
+    for node in seq {
+        match node.element_ref() {
+            None => {},
+            Some(element) => {
+                insert(&pool, node.numerator(), node.denominator(), element.as_str()).await.unwrap();
+            }
+        }
     }
 }
 
@@ -47,8 +48,8 @@ async fn insert(pool: &SqlitePool, n: u64, d: u64, payload: &str) -> Result<(),
 
     let result = sqlx::query!(
         r#"INSERT INTO sequence
-                       (numerator,   denominator, payload)
-                VALUES ($1,         $2,           $3);"#,
+                       (numerator, denominator, payload)
+                VALUES ($1,        $2,          $3);"#,
         numerator,
         denominator,
         payload

src/lib.rs

@@ -1,5 +1,5 @@
 #![forbid(unsafe_code)]
-// todo: #![deny(missing_docs)]
+//#![deny(missing_docs)]
 // Lints for rustdoc
 #![deny(rustdoc::missing_crate_level_docs)]
 #![deny(rustdoc::broken_intra_doc_links)]
@@ -20,18 +20,15 @@ Collection of useful rustdoc options awaiting their implementation.
 
 //! Get things organized with these powerful, yet easy to use sets. For the time being,
 //! `kodiak-sets` offers a `Sequence`, which is an ordered sets of elements, with each
-//! element at a unique position. `Sequence` allows to add and remove elements at
-//! any position, virtually infinitely.
+//! element at a unique, distinguishable position.
 
 // Keep crate's module structure completely private, see public re-exports below.
 // (also hides modules from crate documentation)
-mod position;
-mod sequence;
-mod tests;
+pub mod sequence;
 
 // Re-exports for convenient use within crate.
-pub(crate) use crate::position::Position;
+// none
 
 // Publicly re-exporting all items valuable to users.
 // (avoids explicitly listing re-exports in crate documentation as there is no alternate path to those items)
-pub use crate::sequence::Sequence;
+// none