enforced sorting at creation for ColumnDoc and TableDoc

Author: RPG-Alex

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "sql_docs"
-version = "1.0.5"
+version = "1.0.6"
 edition = "2024"
 description = "A crate for parsing comments from sql files and using them for documentation generation"
 documentation = "https://docs.rs/sql_docs"

Cargo.toml

@@ -68,7 +68,7 @@ pub struct TableDoc {
 }
 
 impl TableDoc {
-    /// Creates a new [`TableDoc`] after sorting [`ColumnDoc`] by name
+    /// Creates a new [`TableDoc`] after sorting [`ColumnDoc`] by `name`
     ///
     /// # Parameters
     /// - name: `String` - the name of the table
@@ -83,7 +83,7 @@ impl TableDoc {
         mut columns: Vec<ColumnDoc>,
         path: Option<PathBuf>,
     ) -> Self {
-        columns.sort_by(|a,b| a.name().cmp(b.name()));
+        columns.sort_by(|a, b| a.name().cmp(b.name()));
         Self { schema, name, doc, columns, path }
     }
 
@@ -649,35 +649,41 @@ CREATE TABLE posts (
     fn test_doc() {
         let col_doc = ColumnDoc::new("test".to_owned(), Some("comment".to_owned()));
         assert_eq!(&col_doc.to_string(), &"Column Name: test\nColumn Doc: comment\n".to_owned());
-        let col_doc_no_doc = ColumnDoc::new("test".to_owned(), None);
+        let col_doc_no_doc = ColumnDoc::new("id".to_owned(), None);
         assert_eq!(
             &col_doc_no_doc.to_string(),
-            &"Column Name: test\nNo Column Doc Found\n".to_owned()
+            &"Column Name: id\nNo Column Doc Found\n".to_owned()
         );
         assert_eq!(col_doc.doc(), Some("comment"));
         assert_eq!(col_doc.name(), "test");
         assert_eq!(col_doc_no_doc.doc(), None);
-        assert_eq!(col_doc_no_doc.name(), "test");
+        assert_eq!(col_doc_no_doc.name(), "id");
         let table_doc = TableDoc::new(
             Some("schema".to_owned()),
             "table".to_owned(),
             Some("table doc".to_owned()),
-            vec![col_doc],
+            vec![col_doc.clone(), col_doc_no_doc.clone()],
+            None,
+        );
+        let last_col = ColumnDoc::new("zed".to_owned(), Some("the last column".to_owned()));
+        let table_doc_no_doc = TableDoc::new(
+            None,
+            "table".to_owned(),
+            None,
+            vec![last_col, col_doc, col_doc_no_doc],
             None,
         );
-        let table_doc_no_doc =
-            TableDoc::new(None, "table".to_owned(), None, vec![col_doc_no_doc], None);
         assert_eq!(table_doc.name(), "table");
         assert_eq!(table_doc.schema(), Some("schema"));
         assert_eq!(
             table_doc.to_string(),
-            "Table Schema: schema\nTable Name: table\nTable Doc: table doc\nTable Column Docs: \n Column Name: test\nColumn Doc: comment\n"
+            "Table Schema: schema\nTable Name: table\nTable Doc: table doc\nTable Column Docs: \n Column Name: id\nNo Column Doc Found\n Column Name: test\nColumn Doc: comment\n"
         );
         assert_eq!(table_doc_no_doc.schema(), None);
         assert_eq!(table_doc_no_doc.name(), "table");
         assert_eq!(
             table_doc_no_doc.to_string(),
-            "No Table Schema\nTable Name: table\nNo Table Doc\nTable Column Docs: \n Column Name: test\nNo Column Doc Found\n"
+            "No Table Schema\nTable Name: table\nNo Table Doc\nTable Column Docs: \n Column Name: id\nNo Column Doc Found\n Column Name: test\nColumn Doc: comment\n Column Name: zed\nColumn Doc: the last column\n"
         );
     }
 
@@ -770,7 +776,7 @@ CREATE TABLE posts (
     }
 
     #[test]
-    fn display_propagates_every_question_mark_path_for_column_and_table() {
+    fn test_display_propagates_every_question_mark_path_for_column_and_table() {
         let col_with_doc = ColumnDoc::new("col_a".into(), Some("doc".into()));
         let col_without_doc = ColumnDoc::new("col_b".into(), None);
 

src/docs.rs

@@ -54,9 +54,11 @@ enum SqlFileDocSource<'a> {
 impl SqlDoc {
     /// Method for creating a new [`SqlDoc`]
     #[must_use]
-    pub const fn new(tables: Vec<TableDoc>) -> Self {
+    pub fn new(mut tables: Vec<TableDoc>) -> Self {
+        tables.sort_by(|a, b| a.name().cmp(b.name()));
         Self { tables }
     }
+
     /// Method for generating builder from a directory.
     pub fn from_dir<P: AsRef<Path>>(root: &P) -> SqlDocBuilder<'_> {
         SqlDocBuilder {
@@ -102,20 +104,11 @@ impl SqlDoc {
     ///
     /// # Errors
     /// - Will return [`DocError::TableNotFound`] if the expected table is not found
-    /// - Will return [`DocError::DuplicateTablesFound`] if more than one table is found
-    pub fn table(&self, table: &str) -> Result<&TableDoc, DocError> {
-        let matches = self
-            .tables
-            .iter()
-            .filter(|table_doc| table_doc.name() == table)
-            .collect::<Vec<&TableDoc>>();
-        match matches.as_slice() {
-            [] => Err(DocError::TableNotFound { name: table.to_owned() }),
-            [only] => Ok(*only),
-            _ => Err(DocError::DuplicateTablesFound {
-                tables: matches.into_iter().cloned().collect(),
-            }),
-        }
+    pub fn table(&self, name: &str) -> Result<&TableDoc, DocError> {
+        self.tables().binary_search_by(|t| t.name().cmp(name)).map_or_else(
+            |_| Err(DocError::TableNotFound { name: name.to_owned() }),
+            |id| Ok(&self.tables()[id]),
+        )
     }
 
     /// Method for finding a specific [`TableDoc`] from `schema` and table `name`
@@ -222,7 +215,7 @@ impl SqlDocBuilder<'_> {
         for sql_doc in docs {
             tables.extend(sql_doc);
         }
-        let mut sql_doc = SqlDoc { tables };
+        let mut sql_doc = SqlDoc::new(tables);
         match self.multiline_flat {
             MultiFlatten::FlattenWithNone => {
                 sql_doc = flatten_docs(sql_doc, None);
@@ -334,6 +327,11 @@ mod tests {
         stamp_table_paths(&mut expected_tables, &file);
         let expected_doc = SqlDoc::new(expected_tables);
         assert_eq!(sql_doc, expected_doc);
+        let names: Vec<&str> =
+            sql_doc.tables().iter().map(super::super::docs::TableDoc::name).collect();
+        let mut sorted = names.clone();
+        sorted.sort_unstable();
+        assert_eq!(names, sorted, "tables should be in alphabetical order");
         let _ = fs::remove_dir_all(&base);
         Ok(())
     }
@@ -396,12 +394,6 @@ mod tests {
             empty_table_err,
             Err(DocError::TableNotFound { name }) if name == "name"
         ));
-        let duplicate_set = SqlDoc::new(vec![
-            TableDoc::new(None, "duplicate".to_owned(), None, vec![], None),
-            TableDoc::new(None, "duplicate".to_owned(), None, vec![], None),
-        ]);
-        let duplicate_tables_err = duplicate_set.table("duplicate");
-        assert!(matches!(duplicate_tables_err, Err(DocError::DuplicateTablesFound { .. })));
     }
 
     #[test]
@@ -720,7 +712,7 @@ mod tests {
     }
 
     #[test]
-    fn test_fromstr_parse_sql_doc() -> Result<(), Box<dyn std::error::Error>> {
+    fn test_from_str_parse_sql_doc() -> Result<(), Box<dyn std::error::Error>> {
         let doc: SqlDoc = "CREATE TABLE t(id INTEGER);".parse()?;
         assert_eq!(doc.tables().len(), 1);
         Ok(())
@@ -764,4 +756,17 @@ mod tests {
         let _ = fs::remove_dir_all(&base);
         Ok(())
     }
+
+    #[test]
+    fn test_tables_binary_searchable_by_name() {
+        let sample = sample_sql();
+        let tables: Vec<TableDoc> =
+            sample.into_iter().flat_map(|(_, doc)| doc.into_tables()).collect();
+        let sql_doc = SqlDoc::new(tables);
+        let id = sql_doc
+            .tables()
+            .binary_search_by(|t| t.name().cmp("users"))
+            .unwrap_or_else(|_| panic!("expected to find table `users` via binary search"));
+        assert_eq!(sql_doc.tables()[id].name(), "users");
+    }
 }