Better documented topo sorting

Cargo.toml

@@ -14,3 +14,6 @@ exclude = ["release-plz.toml", "cliff.tolm"]
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 [lib]
 name = "general_sam"
+
+[dev-dependencies]
+rand = "0.8.5"

README.md

@@ -42,10 +42,10 @@ use general_sam::sam::GeneralSAM;
 let sam = GeneralSAM::construct_from_bytes("abcbc");
 // => GeneralSAM<u8>
 
-// "cbc" is a suffix.
+// "cbc" is a suffix of "abcbc"
 assert!(sam.get_root_state().feed_bytes("cbc").is_accepting());
 
-// "bcb" isn't a suffix.
+// "bcb" is not a suffix of "abcbc"
 assert!(!sam.get_root_state().feed_bytes("bcb").is_accepting());
 ```
 
@@ -57,19 +57,19 @@ let sam = GeneralSAM::construct_from_chars("abcbc".chars());
 
 let state = sam.get_root_state();
 
-// "b" is not a suffix but a substring.
+// "b" is not a suffix but at least a substring of "abcbc"
 let state = state.feed_chars("b");
 assert!(!state.is_accepting());
 
-// "bc" is a suffix.
+// "bc" is a suffix of "abcbc"
 let state = state.feed_chars("c");
 assert!(state.is_accepting());
 
-// "bcbc" is also a suffix.
+// "bcbc" is a suffix of "abcbc"
 let state = state.feed_chars("bc");
 assert!(state.is_accepting());
 
-// "bcbcbc" is not a substring.
+// "bcbcbc" is not a substring, much less a suffix of "abcbc"
 let state = state.feed_chars("bc");
 assert!(!state.is_accepting() && state.is_nil());
 ```

src/lib.rs

@@ -1,11 +1,28 @@
 //! This crate provides an implementation of a general suffix automaton.
 //!
-//! |         [![the suffix automaton of abcbc][sam-of-abcbc]][sam-oi-wiki]          |
-//! | :----------------------------------------------------------------------------: |
-//! | The suffix automaton of abcbc, image from [后缀自动机 - OI Wiki][sam-oi-wiki]. |
+//! ```mermaid
+//! flowchart LR
+//!   init((ε))
+//!   a((a))
+//!   b((b))
+//!   ab((ab))
+//!   bc(((bc)))
+//!   abc((abc))
+//!   abcb((abcb))
+//!   abcbc(((abcbc)))
+//!
+//!   init -- a --> a
+//!   init -- b --> b
+//!   a -- b --> ab
+//!   b -- c --> bc
+//!   init -- c --> bc
+//!   ab -- c --> abc
+//!   bc -- b --> abcb
+//!   abc -- b --> abcb
+//!   abcb -- c --> abcbc
+//! ```
 //!
-//! [sam-of-abcbc]: https://oi-wiki.org/string/images/SAM/SA_suffix_links.svg
-//! [sam-oi-wiki]: https://oi-wiki.org/string/sam/
+//! > The suffix automaton of abcbc.
 //!
 //! # Examples
 //!
@@ -15,7 +32,10 @@
 //! let sam = GeneralSAM::construct_from_bytes("abcbc");
 //! // => GeneralSAM<u8>
 //!
+//! // "cbc" is a suffix of "abcbc"
 //! assert!(sam.get_root_state().feed_bytes("cbc").is_accepting());
+//!
+//! // "bcb" is not a suffix of "abcbc"
 //! assert!(!sam.get_root_state().feed_bytes("bcb").is_accepting());
 //! ```
 //!
@@ -26,12 +46,20 @@
 //! // => GeneralSAM<char>
 //!
 //! let state = sam.get_root_state();
+//!
+//! // "b" is not a suffix but at least a substring of "abcbc"
 //! let state = state.feed_chars("b");
 //! assert!(!state.is_accepting());
+//!
+//! // "bc" is a suffix of "abcbc"
 //! let state = state.feed_chars("c");
 //! assert!(state.is_accepting());
+//!
+//! // "bcbc" is a suffix of "abcbc"
 //! let state = state.feed_chars("bc");
 //! assert!(state.is_accepting());
+//!
+//! // "bcbcbc" is not a substring, much less a suffix of "abcbc"
 //! let state = state.feed_chars("bc");
 //! assert!(!state.is_accepting() && state.is_nil());
 //! ```

src/sam/mod.rs

@@ -23,7 +23,7 @@ pub struct GeneralSAMNode<T: Ord + Clone> {
 #[derive(Debug, Clone)]
 pub struct GeneralSAM<T: Ord + Clone> {
     node_pool: Vec<GeneralSAMNode<T>>,
-    topo_order: Vec<GeneralSAMNodeID>,
+    topo_and_suf_len_sorted_order: Vec<GeneralSAMNodeID>,
 }
 
 impl<T: Ord + Clone> GeneralSAMNode<T> {
@@ -81,7 +81,7 @@ impl<T: Ord + Clone> Default for GeneralSAM<T> {
                 GeneralSAMNode::new(false, 0, SAM_NIL_NODE_ID),
                 GeneralSAMNode::new(true, 0, SAM_NIL_NODE_ID),
             ],
-            topo_order: Default::default(),
+            topo_and_suf_len_sorted_order: Default::default(),
         }
     }
 }
@@ -91,6 +91,14 @@ impl<T: Ord + Clone> GeneralSAM<T> {
         self.node_pool.len()
     }
 
+    pub fn get_root_node(&self) -> &GeneralSAMNode<T> {
+        self.get_node(SAM_ROOT_NODE_ID).unwrap()
+    }
+
+    pub fn get_node(&self, node_id: GeneralSAMNodeID) -> Option<&GeneralSAMNode<T>> {
+        self.node_pool.get(node_id)
+    }
+
     pub fn get_root_state(&self) -> GeneralSAMState<T> {
         self.get_state(SAM_ROOT_NODE_ID)
     }
@@ -106,8 +114,11 @@ impl<T: Ord + Clone> GeneralSAM<T> {
         }
     }
 
-    pub fn get_topo_sorted_node_ids(&self) -> &Vec<GeneralSAMNodeID> {
-        &self.topo_order
+    /// Returns topological sorted, maximum suffix length sorted
+    /// and suffix parent depth sorted node id sequence,
+    /// which is generated by topological sorting with a queue.
+    pub fn get_topo_and_suf_len_sorted_node_ids(&self) -> &Vec<GeneralSAMNodeID> {
+        &self.topo_and_suf_len_sorted_order
     }
 
     pub fn construct_from_trie<TN: TrieNodeAlike>(node: TN) -> Self
@@ -119,7 +130,7 @@ impl<T: Ord + Clone> GeneralSAM<T> {
         let accept_empty_string = node.is_accepting();
 
         sam.build_with_trie(node);
-        sam.topo_sort();
+        sam.topo_sort_with_queue();
         sam.update_accepting();
 
         sam.node_pool[SAM_ROOT_NODE_ID].accept = accept_empty_string;
@@ -151,37 +162,41 @@ impl<T: Ord + Clone> GeneralSAM<T> {
         .unwrap();
     }
 
-    fn topo_sort(&mut self) {
-        let mut in_degree: Vec<usize> = Vec::new();
-        in_degree.resize(self.node_pool.len(), 0);
+    fn topo_sort_with_queue(&mut self) {
+        let mut in_degree: Vec<usize> = vec![0; self.num_of_nodes()];
+
         self.node_pool.iter().for_each(|node| {
             node.trans.values().for_each(|v| {
                 in_degree[*v] += 1;
             });
         });
         assert!(in_degree[SAM_ROOT_NODE_ID] == 0);
 
-        self.topo_order.reserve(self.node_pool.len());
+        self.topo_and_suf_len_sorted_order
+            .reserve(self.node_pool.len());
 
-        self.topo_order.push(SAM_ROOT_NODE_ID);
+        self.topo_and_suf_len_sorted_order.push(SAM_ROOT_NODE_ID);
         let mut head = 0;
-        while head < self.topo_order.len() {
-            let u_id = self.topo_order[head];
+        while head < self.topo_and_suf_len_sorted_order.len() {
+            let u_id = self.topo_and_suf_len_sorted_order[head];
             head += 1;
             self.node_pool[u_id].trans.values().for_each(|v_id| {
                 in_degree[*v_id] -= 1;
                 if in_degree[*v_id] == 0 {
-                    self.topo_order.push(*v_id);
+                    self.topo_and_suf_len_sorted_order.push(*v_id);
                 }
             });
         }
     }
 
     fn update_accepting(&mut self) {
-        self.topo_order.iter().rev().for_each(|node_id| {
-            let link_id = self.node_pool[*node_id].link;
-            self.node_pool[link_id].accept |= self.node_pool[*node_id].accept;
-        });
+        self.topo_and_suf_len_sorted_order
+            .iter()
+            .rev()
+            .for_each(|node_id| {
+                let link_id = self.node_pool[*node_id].link;
+                self.node_pool[link_id].accept |= self.node_pool[*node_id].accept;
+            });
         self.node_pool[SAM_NIL_NODE_ID].accept = false;
     }
 

src/sam/state.rs

@@ -37,8 +37,8 @@ impl<'s, T: Ord + Clone> GeneralSAMState<'s, T> {
             .unwrap_or(false)
     }
 
-    pub fn get_node(&self) -> Option<&'_ GeneralSAMNode<T>> {
-        self.sam.node_pool.get(self.node_id)
+    pub fn get_node(&self) -> Option<&GeneralSAMNode<T>> {
+        self.sam.get_node(self.node_id)
     }
 
     pub fn goto_suffix_parent(&mut self) {

src/tests.rs

@@ -1,4 +1,10 @@
-use crate::{sam::GeneralSAM, trie::Trie};
+use rand::{
+    distributions::{Alphanumeric, DistString},
+    rngs::StdRng,
+    Rng, SeedableRng,
+};
+
+use crate::{sam::GeneralSAM, trie::Trie, SAM_ROOT_NODE_ID};
 
 #[test]
 fn test_example_from_chars() {
@@ -165,3 +171,53 @@ fn test_simple_trie_suffix() {
     let vocab = ["ac", "bb", "b", "cc", "aabb", "a", "ba", "c", "aa"];
     test_trie_suffix(&vocab);
 }
+
+#[test]
+fn test_topo_and_suf_len_sorted_order() {
+    let mut rng = StdRng::seed_from_u64(1134759173975);
+    for _ in 0..10000 {
+        let mut trie = Trie::default();
+        for _ in 0..rng.gen_range(0..32) {
+            let len = rng.gen_range(0..9);
+            let string = Alphanumeric.sample_string(&mut rng, len);
+            trie.insert_ref_iter(string.as_bytes().iter());
+        }
+
+        let sam: GeneralSAM<u8> = GeneralSAM::construct_from_trie(trie.get_root_state());
+
+        let order = sam.get_topo_and_suf_len_sorted_node_ids();
+        let rank = {
+            let mut rank = vec![0; sam.num_of_nodes()];
+            order.iter().enumerate().for_each(|(k, i)| {
+                rank[*i] = k;
+            });
+            rank
+        };
+
+        // verify that max suffix lengths should be sorted
+        for pos in 0..order.len() - 1 {
+            assert!(
+                sam.get_node(order[pos]).unwrap().max_suffix_len()
+                    <= sam.get_node(order[pos + 1]).unwrap().max_suffix_len()
+            );
+        }
+
+        // verify topological ordering
+        order.iter().for_each(|node_id| {
+            let node = sam.get_node(*node_id).unwrap();
+
+            node.get_trans().values().for_each(|next_node_id| {
+                assert!(rank[*next_node_id] > rank[*node_id]);
+            });
+        });
+
+        // verify suffix parent tree depth ordering
+        order.iter().for_each(|node_id| {
+            let node = sam.get_node(*node_id).unwrap();
+
+            if *node_id != SAM_ROOT_NODE_ID {
+                assert!(rank[node.get_suffix_parent_id()] < rank[*node_id]);
+            }
+        });
+    }
+}

src/trie.rs

@@ -45,7 +45,10 @@ impl<T: Ord + Clone> TrieNode<T> {
 impl<T: Ord + Clone> Default for Trie<T> {
     fn default() -> Self {
         Self {
-            node_pool: vec![TrieNode::new(TRIE_NIL_NODE_ID), TrieNode::new(TRIE_NIL_NODE_ID)],
+            node_pool: vec![
+                TrieNode::new(TRIE_NIL_NODE_ID),
+                TrieNode::new(TRIE_NIL_NODE_ID),
+            ],
         }
     }
 }
@@ -86,7 +89,10 @@ impl<T: Ord + Clone> Trie<T> {
         node_id
     }
 
-    pub fn insert_ref_iter<'s, Iter: Iterator<Item = &'s T>>(&'s mut self, iter: Iter) -> TrieNodeID {
+    pub fn insert_ref_iter<'s, Iter: Iterator<Item = &'s T>>(
+        &'s mut self,
+        iter: Iter,
+    ) -> TrieNodeID {
         self.insert_iter(iter.cloned())
     }