Readme

README.md

@@ -1,2 +1,92 @@
 # distributing-iterator
 Distributing iterator
+
+[![Rust](https://github.com/fetlife/distributing-iterator/actions/workflows/rust.yml/badge.svg)](https://github.com/fetlife/distributing-iterator/actions/workflows/rust.yml)
+
+# Synopsis
+
+## Rust
+
+```rust
+use distributing_iterator::DistributingIterator;
+
+#[derive(Debug, PartialEq)]
+struct Item {
+    id: u64,
+}
+
+let data = vec![
+    Item { id: 1 },
+    Item { id: 1 },
+    Item { id: 1 },
+    Item { id: 2 },
+    Item { id: 2 },
+    Item { id: 2 },
+    Item { id: 3 },
+    Item { id: 3 },
+    Item { id: 3 },
+];
+let iterator = DistributingIterator::new(data.into(), 3, |item| item.id);
+let result: Vec<Item> = iterator.collect();
+assert_eq!(
+    result,
+    vec![
+        Item { id: 1 }, Item { id: 2 }, Item { id: 3 },
+        Item { id: 1 }, Item { id: 2 }, Item { id: 3 },
+        Item { id: 1 }, Item { id: 2 }, Item { id: 3 },
+    ]
+);
+```
+
+
+## As a ruby gem:
+
+Gemfile:
+
+```ruby
+gem 'distributing_iterator', git: 'fetlife/distributing-iterator'
+```
+
+```ruby
+require 'distributing_iterator'
+
+csv = <<~CSV
+id,name
+1,foo
+1,bar
+1,baz
+2,qux
+3,quux
+3,corge
+2,grault
+2,garply
+3,waldo
+3,fred
+2,plugh
+3,xyzzy
+2,thud
+3,plugh
+3,xyzzy
+CSV
+
+output = DistributingIterator.distribute(csv, 'id', 3)
+
+puts output
+# id,name
+# 1,foo
+# 2,qux
+# 3,quux
+# 1,bar
+# 2,grault
+# 3,corge
+# 1,baz
+# 2,garply
+# 3,waldo
+# 2,plugh
+# 3,fred
+# 2,thud
+# 3,xyzzy
+# 3,plugh
+# 3,xyzzy
+
+```

src/distribute_csv.rs

@@ -18,7 +18,7 @@ pub fn distribute(data: &str, field: &str, spread: u64) -> Result<String> {
         .collect::<Result<VecDeque<_>>>()?;
     let id_func = move |item: &ByteRecord| item[field_index].to_vec();
     let iterator =
-        distributing_iterator::DistributionIterator::new(data, spread as usize, id_func);
+        distributing_iterator::DistributingIterator::new(data, spread as usize, id_func);
     let data: Vec<_> = iterator.collect();
     let mut wtr = csv::Writer::from_writer(vec![]);
     wtr.write_record(&headers).context("writing headers")?;

src/distributing_iterator.rs

@@ -2,7 +2,37 @@ use fnv::FnvHashMap;
 use indexmap::IndexMap;
 use std::collections::VecDeque;
 
-pub struct DistributionIterator<T, ID> {
+/// ```rust
+/// use distributing_iterator::DistributingIterator;
+///
+/// #[derive(Debug, PartialEq)]
+/// struct Item {
+///     id: u64,
+/// }
+///
+/// let data = vec![
+///     Item { id: 1 },
+///     Item { id: 1 },
+///     Item { id: 1 },
+///     Item { id: 2 },
+///     Item { id: 2 },
+///     Item { id: 2 },
+///     Item { id: 3 },
+///     Item { id: 3 },
+///     Item { id: 3 },
+/// ];
+/// let iterator = DistributingIterator::new(data.into(), 3, |item| item.id);
+/// let result: Vec<Item> = iterator.collect();
+/// assert_eq!(
+///     result,
+///     vec![
+///         Item { id: 1 }, Item { id: 2 }, Item { id: 3 },
+///         Item { id: 1 }, Item { id: 2 }, Item { id: 3 },
+///         Item { id: 1 }, Item { id: 2 }, Item { id: 3 },
+///     ]
+/// );
+/// ```
+pub struct DistributingIterator<T, ID> {
     data: VecDeque<T>,
     pos: usize,
     original_size: usize,
@@ -13,7 +43,7 @@ pub struct DistributionIterator<T, ID> {
     id_func: Box<dyn Fn(&T) -> ID + Send>,
 }
 
-impl<T, ID> DistributionIterator<T, ID>
+impl<T, ID> DistributingIterator<T, ID>
 where
     ID: Eq + std::hash::Hash,
 {
@@ -125,7 +155,7 @@ where
     }
 }
 
-impl<T, ID> Iterator for DistributionIterator<T, ID>
+impl<T, ID> Iterator for DistributingIterator<T, ID>
 where
     T: std::fmt::Debug,
     ID: Eq + std::hash::Hash + std::fmt::Debug,
@@ -146,7 +176,7 @@ where
 mod tests {
     use super::*;
 
-    #[derive(Debug, Clone, PartialEq, Eq, Hash)]
+    #[derive(Debug, PartialEq, Eq)]
     struct Item {
         id: u64,
     }
@@ -170,7 +200,7 @@ mod tests {
             Item { id: 3 },
             Item { id: 3 },
         ];
-        let iterator = DistributionIterator::new(data.into(), 3, |item| item.id);
+        let iterator = DistributingIterator::new(data.into(), 3, |item| item.id);
         let data: Vec<_> = iterator.collect();
         assert_eq!(
             data,

src/lib.rs

@@ -4,4 +4,4 @@ mod distributing_iterator;
 mod ruby_ext;
 
 pub use distribute_csv::distribute as distribute_csv;
-pub use distributing_iterator::DistributionIterator;
+pub use distributing_iterator::DistributingIterator;