add docs

Author: myfreess

sequence_matcher.mbt

@@ -1,4 +1,9 @@
 ///|
+/// A contiguous matching block between two sequences.
+///
+/// The coordinates are half-open intervals:
+/// - In the first sequence: `[first_start, first_start + size)`
+/// - In the second sequence: `[second_start, second_start + size)`
 #valtype
 priv struct Match {
   first_start : Int
@@ -7,11 +12,18 @@ priv struct Match {
 }
 
 ///|
+/// Build a `Match` value.
 fn Match::new(first_start : Int, second_start : Int, size : Int) -> Match {
   Match::{ first_start, second_start, size }
 }
 
 ///|
+/// Operation tag used in an edit script.
+///
+/// - `Equal`: unchanged range in both sequences.
+/// - `Insert`: range only exists in the second sequence.
+/// - `Delete`: range only exists in the first sequence.
+/// - `Replace`: range changed from first to second.
 priv enum OpTag {
   Equal
   Insert
@@ -20,6 +32,11 @@ priv enum OpTag {
 } derive(Eq)
 
 ///|
+/// One edit operation over two half-open intervals.
+///
+/// The operation always compares:
+/// - first sequence range: `[first_start, first_end)`
+/// - second sequence range: `[second_start, second_end)`
 priv struct OpCode {
   tag : OpTag
   first_start : Int
@@ -29,6 +46,7 @@ priv struct OpCode {
 }
 
 ///|
+/// Build an `OpCode` value.
 fn OpCode::new(
   tag : OpTag,
   first_start : Int,
@@ -40,13 +58,21 @@ fn OpCode::new(
 }
 
 ///|
+/// Sequence matcher used to compute LCS-like matching blocks and diff opcodes.
+///
+/// Internal cache `second_sequence_elements` maps each element in the second
+/// sequence to all its indices, which is reused by longest-match search.
 priv struct SequenceMatcher[T] {
   mut first_sequence : Array[T]
   mut second_sequence : Array[T]
   mut second_sequence_elements : @hashmap.HashMap[T, Array[Int]]
 }
 
 ///|
+/// Construct a matcher for two sequences.
+///
+/// `T` must support `Eq + Hash`, because matching uses hash-map based index
+/// lookups in `second_sequence_elements`.
 fn[T : Eq + Hash] SequenceMatcher::new(
   first_sequence : Array[T],
   second_sequence : Array[T],
@@ -61,6 +87,10 @@ fn[T : Eq + Hash] SequenceMatcher::new(
 }
 
 ///|
+/// Replace both sequences.
+///
+/// This updates the first sequence directly, then rebuilds the second-sequence
+/// index cache through `set_second_seq`.
 fn[T : Eq + Hash] SequenceMatcher::set_seqs(
   self : SequenceMatcher[T],
   first_sequence : Array[T],
@@ -71,6 +101,10 @@ fn[T : Eq + Hash] SequenceMatcher::set_seqs(
 }
 
 ///|
+/// Replace only the first sequence.
+///
+/// No cache rebuild is needed because the cache is keyed by the second
+/// sequence.
 fn[T] SequenceMatcher::set_first_seq(
   self : SequenceMatcher[T],
   sequence : Array[T],
@@ -79,6 +113,7 @@ fn[T] SequenceMatcher::set_first_seq(
 }
 
 ///|
+/// Replace only the second sequence and rebuild its index cache.
 fn[T : Eq + Hash] SequenceMatcher::set_second_seq(
   self : SequenceMatcher[T],
   sequence : Array[T],
@@ -88,17 +123,23 @@ fn[T : Eq + Hash] SequenceMatcher::set_second_seq(
 }
 
 ///|
+/// Build an index map from second-sequence element to all its positions.
+///
+/// For long sequences, very frequent elements are filtered out to avoid
+/// quadratic blowups in candidate expansion (`popular elements` optimization).
 fn[T : Eq + Hash] SequenceMatcher::chain_second_seq(
   self : SequenceMatcher[T],
 ) -> Unit {
   let second_sequence = self.second_sequence
   let mut second_sequence_elements = @hashmap.HashMap::new()
   for i, item in second_sequence.iter2() {
+    // Collect all indices where each element appears.
     let counter = second_sequence_elements.get_or_init(item, () => Array::new())
     counter.push(i)
   }
 
-  // keep popular elements in lookup table
+  // Keep only non-popular elements in the lookup table.
+  // Threshold follows difflib-style heuristic: frequency > len/100 + 1.
   let len = second_sequence.length()
   if len >= 200 {
     let test_len = (len.to_double() / 100.0).floor().to_int() + 1
@@ -117,6 +158,14 @@ fn[T : Eq + Hash] SequenceMatcher::chain_second_seq(
 }
 
 ///|
+/// Find the longest contiguous common block within two sub-ranges.
+///
+/// Search space is restricted to:
+/// - first sequence range `[first_start, first_end)`
+/// - second sequence range `[second_start, second_end)`
+///
+/// The core dynamic-programming state `j2len` stores the best length of a
+/// suffix match ending at the current `i` and each `j`.
 fn[T : Eq + Hash] SequenceMatcher::find_longest_match(
   self : SequenceMatcher[T],
   first_start : Int,
@@ -131,18 +180,24 @@ fn[T : Eq + Hash] SequenceMatcher::find_longest_match(
   let mut best_j = second_start
   let mut best_size = 0
   let mut j2len = @hashmap.HashMap::new()
+
+  // DP over diagonals: if first[i] == second[j],
+  // new_j2len[j] = j2len[j - 1] + 1.
   for i = first_start; i < first_end; i = i + 1 {
     let item = first_sequence[i]
     let new_j2len = @hashmap.HashMap::new()
     match second_sequence_elements.get(item) {
       Some(indexes) =>
         for j in indexes {
+          // Candidate index belongs to the current second-range window.
           if j < second_start {
             continue
           }
           if j >= second_end {
             break
           }
+
+          // Extend previous diagonal match by one.
           let mut size = match j2len.get(j - 1) {
             Some(k) if j > 0 => k
             _ => 0
@@ -160,7 +215,9 @@ fn[T : Eq + Hash] SequenceMatcher::find_longest_match(
     j2len = new_j2len
   }
 
-  // Extend the match backwards and forwards
+  // Extend around the best core match to absorb adjacent equal elements.
+  // Two passes are used so a backward extension discovered in pass 1 can
+  // enable additional forward extension in pass 2.
 
   for _ in 0..<2 {
     while best_i > first_start &&
@@ -181,6 +238,13 @@ fn[T : Eq + Hash] SequenceMatcher::find_longest_match(
 }
 
 ///|
+/// Compute edit operations that transform the first sequence into the second.
+///
+/// The algorithm:
+/// 1. Repeatedly find longest matches inside unmatched windows.
+/// 2. Sort and merge adjacent matches.
+/// 3. Convert gaps between matches into `Insert/Delete/Replace` operations.
+/// 4. Emit `Equal` operations for each merged match.
 fn[T : Eq + Hash] SequenceMatcher::get_opcodes(
   self : SequenceMatcher[T],
 ) -> Array[OpCode] {
@@ -189,6 +253,8 @@ fn[T : Eq + Hash] SequenceMatcher::get_opcodes(
   let matches = Array::new()
   let queue = Array::new()
   queue.push((0, first_length, 0, second_length))
+
+  // Split problem recursively (implemented with an explicit stack/queue).
   while !queue.is_empty() {
     let (first_start, first_end, second_start, second_end) = queue.unsafe_pop()
     let m = self.find_longest_match(
@@ -213,7 +279,7 @@ fn[T : Eq + Hash] SequenceMatcher::get_opcodes(
     }
   }
 
-  // Sort matches
+  // Ensure deterministic order before merging.
   matches.sort_by(fn(a, b) {
     if a.first_start < b.first_start {
       -1
@@ -228,7 +294,7 @@ fn[T : Eq + Hash] SequenceMatcher::get_opcodes(
     }
   })
 
-  // Merge adjacent matches
+  // Merge consecutive blocks that are contiguous in both sequences.
   let mut first_start = 0
   let mut second_start = 0
   let mut size = 0
@@ -253,6 +319,8 @@ fn[T : Eq + Hash] SequenceMatcher::get_opcodes(
   let opcodes = Array::new()
   let mut i = 0
   let mut j = 0
+
+  // Emit gap operations, then emit the equal block itself.
   for m in non_adjacent {
     let tag = if i < m.first_start && j < m.second_start {
       Some(OpTag::Replace)