Change must token API and prepare a 1.0 release.

- Breaking API change, bumping major from 0 to 1.
- Handle clippy suggestions.
  - There's only one error, but make it explicit.
  - .cloned()
- get_index helper to make use of ? and unindent code.

Author: Tomasz bla Fortuna

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "fuzzdex"
-version = "0.7.0"
+version = "1.0.0"
 authors = ["Tomasz bla Fortuna <[email protected]>"]
 edition = "2021"
 license = "MIT"

Cargo.toml

@@ -11,6 +11,3 @@ ipython = "*"
 [dev-packages]
 pytest = "==7.1.2"
 ipython = "*"
-
-[requires]
-python_version = "3"

Pipfile

@@ -67,23 +67,25 @@ cities.finish()
 streets.finish()
 
 # warszawa matches warsaw at editing distance 2.
-cities.search("warszawa", [], max_distance=2, limit=60)
+cities.search(["warszawa"], [], max_distance=2, limit=60)
 #    [{'origin': 'Warsaw', 'index': 1, 'token': 'warsaw',
 #      'distance': 2, 'score': 200000.0, 'should_score': 0.0}]
-
+#
+# NOTE: Currently only a single `must` token is supported.
+#
 # `świat` adds additional should score to the result and places it higher
 # in case the limit is set:
-streets.search("nowy", ["świat"], max_distance=2, constraint=1)
+streets.search(["nowy"], ["świat"], max_distance=2, constraint=1)
 #    [{'origin': 'Nowy Świat', 'index': 2, 'token': 'nowy',
 #      'distance': 0, 'score': 5.999, 'should_score': 7.4999}]
 
 # Won't match with constraint 2.
-streets.search("nowy", ["świat"], constraint=2)
+streets.search(["nowy"], ["świat"], constraint=2)
 #    []
 
 # Quering for `czerniawska` will return `czerniakowska` (no constraints),
 # but with a lower score and higher distance:
-In [22]: streets.search("czerniawska", [], max_distance=2)
+In [22]: streets.search(["czerniawska"], [], max_distance=2)
 Out[22]:
 #  [{'origin': 'Czerniawska', 'index': 4, 'token': 'czerniawska',
 #   'distance': 0, 'score': 9.49995231628418, 'should_score': 0.0},

README.md

@@ -11,6 +11,17 @@ pub mod seeker;
 #[cfg(test)]
 mod tests;
 
+/// Single possible error type.
+#[derive(Debug)]
+pub struct DuplicateId;
+
+impl std::fmt::Display for DuplicateId {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "Duplicated Phrase ID")
+    }
+}
+impl std::error::Error for DuplicateId {}
+
 /// Token owning a trigram is uniquely identified by phrase index + token index.
 #[derive(Debug)]
 struct Position {

src/fuzzdex.rs

@@ -1,5 +1,4 @@
-use std::collections::HashMap;
-use std::collections::HashSet;
+use std::collections::{HashMap, HashSet};
 
 use crate::utils;
 use super::*;
@@ -45,9 +44,9 @@ impl Indexer {
     /// fuzzy-matched tokens. Phrase index must be unique within the index (or
     /// Err is returned) and can reference some external dictionary.
     pub fn add_phrase(&mut self, phrase: &str, phrase_idx: usize,
-                      constraints: Option<&HashSet<usize, FastHash>>) -> Result<(), ()> {
+                      constraints: Option<&HashSet<usize, FastHash>>) -> Result<(), DuplicateId> {
         if self.phrases.contains_key(&phrase_idx) {
-            Err(())
+            Err(DuplicateId {})
         } else {
             let entry = PhraseEntry::new(phrase_idx, phrase, constraints);
             for (token_idx, token) in entry.tokens.iter().enumerate() {

src/fuzzdex/indexer.rs

@@ -23,9 +23,16 @@ impl Query {
     /// pass a single token, but if the internal tokenizer splits must into many
     /// tokens, the longest will be set as a `must` and others moved to
     /// `should`.
-    pub fn new(must: &str, should: &[&str]) -> Self {
+    ///
+    /// Currently only a single `must` token is allowed, but API accepts list
+    /// for future compatibility.
+    pub fn new(must: &[&str], should: &[&str]) -> Self {
+
         let mut should_tokens: Vec<String> = should.iter().map(|s| s.to_string()).collect();
 
+        assert!(must.len() == 1, "Only one `must token` is currently supported");
+        let must = must[0];
+
         /* Sometimes must token passed in query is not tokenized in the same way we do */
         let mut tokens: Vec<String> = utils::tokenize(must, 1);
         let must_token: String = if tokens.len() > 1 {

src/fuzzdex/query.rs

@@ -112,7 +112,7 @@ impl Index {
         /* LRU cache updates position even on get and needs mutable reference */
         {
             let mut cache = self.cache.lock().unwrap();
-            let heatmap = cache.heatmaps.get(token).map(|h| h.clone());
+            let heatmap = cache.heatmaps.get(token).cloned();
             if let Some(heatmap) = heatmap {
                 /* We operate on reference-counted heatmaps to eliminate unnecessary copying */
                 cache.stats.hits += 1;

src/fuzzdex/seeker.rs

@@ -18,7 +18,7 @@ fn it_works() {
     assert_eq!(idx.cache_stats().inserts, 0);
 
     /* First query */
-    let query = Query::new("another", &["testing"]).limit(Some(60));
+    let query = Query::new(&["another"], &["testing"]).limit(Some(60));
     println!("Querying {:?}", query);
     let results = idx.search(&query);
 
@@ -33,7 +33,7 @@ fn it_works() {
     assert_eq!(idx.cache_stats().inserts, 1);
 
     /* Test constraint */
-    let query = Query::new("another", &["testing"])
+    let query = Query::new(&["another"], &["testing"])
         .constraint(Some(1));
     println!("Querying {:?}", query);
     let results = idx.search(&query);
@@ -47,7 +47,7 @@ fn it_works() {
     assert_eq!(idx.cache_stats().inserts, 1);
 
     /* Third query */
-    let query = Query::new("this", &["entry"]).limit(Some(60));
+    let query = Query::new(&["this"], &["entry"]).limit(Some(60));
     let results = idx.search(&query);
 
     for result in &results {
@@ -59,7 +59,7 @@ fn it_works() {
     assert!(results[0].should_score > 0.0, "First result should have non-zero should-score");
 
     /* Test multiple tokens matching in single phrase */
-    let query = Query::new("test", &[]).limit(Some(60));
+    let query = Query::new(&["test"], &[]).limit(Some(60));
     println!("Querying {:?}", query);
     let results = idx.search(&query);
 
@@ -86,7 +86,7 @@ fn it_works_with_case_change_and_spellerror() {
     let idx = idx.finish();
 
     /* Query with lowercase and single spell error */
-    let query = Query::new("waszawa", &[]).limit(Some(1));
+    let query = Query::new(&["waszawa"], &[]).limit(Some(1));
     println!("Querying {:?}", query);
     let results = idx.search(&query);
 
@@ -112,7 +112,7 @@ fn it_works_with_small_tokens() {
     let idx = idx.finish();
 
     /* First query */
-    let query = Query::new("may", &["1"]).limit(Some(1));
+    let query = Query::new(&["may"], &["1"]).limit(Some(1));
     println!("Querying {:?}", query);
     let results = idx.search(&query);
     for result in &results {
@@ -121,7 +121,7 @@ fn it_works_with_small_tokens() {
     assert_eq!(results.len(), 1);
     assert_eq!(results[0].index, 1);
 
-    let query = Query::new("may", &["2"]).limit(Some(1));
+    let query = Query::new(&["may"], &["2"]).limit(Some(1));
     println!("Querying {:?}", query);
     let results = idx.search(&query);
     for result in &results {
@@ -130,7 +130,7 @@ fn it_works_with_small_tokens() {
     assert_eq!(results.len(), 1);
     assert_eq!(results[0].index, 2);
 
-    let query = Query::new("may", &["3"]).limit(Some(1));
+    let query = Query::new(&["may"], &["3"]).limit(Some(1));
     println!("Querying {:?}", query);
     let results = idx.search(&query);
     for result in &results {
@@ -154,7 +154,7 @@ fn it_behaves_with_repeating_patterns() {
     assert!(idx.index.db.contains_key("bca"));
     assert!(idx.index.db.contains_key("cab"));
 
-    let query = Query::new("abc", &[]).max_distance(Some(3)).limit(Some(3));
+    let query = Query::new(&["abc"], &[]).max_distance(Some(3)).limit(Some(3));
     let results = idx.search(&query);
     assert_eq!(results.len(), 1);
     assert_eq!(results[0].index, 1);
@@ -166,7 +166,7 @@ fn it_behaves_with_repeating_patterns() {
     idx.add_phrase(&repeating_phrase, 1, None).unwrap();
     let idx = idx.finish();
 
-    let query = Query::new("abc", &[]).limit(Some(3));
+    let query = Query::new(&["abc"], &[]).limit(Some(3));
     let results = idx.search(&query);
     assert_eq!(results.len(), 1);
     assert_eq!(results[0].index, 1);
@@ -189,7 +189,7 @@ fn it_behaves_with_too_long_inputs() {
     assert!(idx.index.db.contains_key("cab"));
 
     println!("Added {}", long_string);
-    let query = Query::new(&long_string, &[]).limit(Some(3));
+    let query = Query::new(&[&long_string], &[]).limit(Some(3));
     let results = idx.search(&query);
     assert_eq!(results.len(), 1);
     assert_eq!(results[0].index, 1);
@@ -204,7 +204,7 @@ fn it_behaves_with_too_long_inputs() {
     assert_eq!(1, idx.index.db.len());
     assert!(idx.index.db.contains_key("abc"));
 
-    let query = Query::new("abc", &[]).limit(Some(3));
+    let query = Query::new(&["abc"], &[]).limit(Some(3));
     let results = idx.search(&query);
     assert_eq!(results.len(), 1);
     assert_eq!(results[0].index, 1);
@@ -220,12 +220,12 @@ fn it_detects_duplicate_phrase_idx() {
     assert!(idx.add_phrase("phrase three", 1, None).is_err());
     let idx = idx.finish();
 
-    let query = Query::new("rather", &[]).limit(Some(3));
+    let query = Query::new(&["rather"], &[]).limit(Some(3));
     let results = idx.search(&query);
     assert_eq!(results.len(), 1);
     assert_eq!(results[0].index, 1);
 
-    let query = Query::new("duplicated", &[]).limit(Some(3));
+    let query = Query::new(&["duplicated"], &[]).limit(Some(3));
     let results = idx.search(&query);
     assert_eq!(results.len(), 0);
 }