Add examples of programmatic API

Cargo.toml

@@ -17,13 +17,16 @@ cli = ["bytelines", "bytesize", "clap", "cli-table", "format_num"]
 [dependencies]
 growable-bloom-filter = "2.1"
 identity-hash = "0.1"
-xxhash-rust = { version = "0.8", features = ["xxh64"] }
 strum = "0.25"
 strum_macros = "0.25"
+xxhash-rust = { version = "0.8", features = ["xxh64"] }
 
 # optional dependencies only use for CLI
 bytelines = { version = "2.4", optional = true }
 bytesize = { version = "1.3", optional = true }
 clap = { version = "4.4", optional = true, features = ["derive"] }
 cli-table = { version = "0.4", optional = true }
 format_num = { version = "0.1", optional = true }
+
+[dev-dependencies]
+jen = "1.6"

README.md

@@ -25,6 +25,8 @@ You should disable the default features as it includes several dependencies whic
 
 ### Examples
 
+Below are a few examples of using the Runiq CLI to filter duplicates out of input text.
+
 ```shell
 $ cat << EOF >> input.txt
 this is a unique line
@@ -47,6 +49,8 @@ this is a duplicate line
 this is another unique line
 ```
 
+For examples of the programmatic API, please see [the examples](./examples/basic.rs).
+
 ### Filters
 
 Runiq comes with several "filters", which control exactly how uniqueness is verified. Each of these filters has different use cases, and excels in different ways.

examples/basic.rs

@@ -0,0 +1,27 @@
+use jen::generator::Generator;
+use runiq::{Filter, QuickFilter};
+
+fn main() {
+    // First we create a filter to detect duplicates
+    let mut filter = QuickFilter::default();
+
+    // As well as a template to generate random inputs
+    let template = "{{ integer(start=1, end=6) }}";
+
+    // Then we generate some random input values
+    let inputs = Generator::from_string(template)
+        .unwrap()
+        .take(20)
+        .collect::<Vec<_>>();
+
+    // And filter uniques
+    let outputs = inputs
+        .iter()
+        .filter(|v| filter.detect(v.as_bytes()))
+        .map(|v| v.to_owned())
+        .collect::<Vec<_>>();
+
+    // Before we print the before/after to the console
+    println!("Generate values: {}", inputs.join(", "));
+    println!("Filtered values: {}", outputs.join(", "));
+}