Add more comments about Knuth-Morris-Pratt algorithm.

[gnulib.git] / lib / mbscasestr.c

diff --git a/lib/mbscasestr.c b/lib/mbscasestr.c
index 592c815..a5491e4 100644 (file)
--- a/lib/mbscasestr.c
+++ b/lib/mbscasestr.c
@@ -48,34 +48,67 @@ knuth_morris_pratt_unibyte (const char *haystack, const char *needle,
   /* Fill the table.
      For 0 < i < m:
        0 < table[i] <= i is defined such that
-       rhaystack[0..i-1] == needle[0..i-1] and rhaystack[i] != needle[i]
-       implies
-       forall 0 <= x < table[i]: rhaystack[x..x+m-1] != needle[0..m-1],
+       forall 0 < x < table[i]: needle[x..i-1] != needle[0..i-1-x],
        and table[i] is as large as possible with this property.
+     This implies:
+     1) For 0 < i < m:
+          If table[i] < i,
+          needle[table[i]..i-1] = needle[0..i-1-table[i]].
+     2) For 0 < i < m:
+          rhaystack[0..i-1] == needle[0..i-1]
+          and exists h, i <= h < m: rhaystack[h] != needle[h]
+          implies
+          forall 0 <= x < table[i]: rhaystack[x..x+m-1] != needle[0..m-1].
      table[0] remains uninitialized.  */
   {
     size_t i, j;
 
+    /* i = 1: Nothing to verify for x = 0.  */
     table[1] = 1;
     j = 0;
+
     for (i = 2; i < m; i++)
       {
+       /* Here: j = i-1 - table[i-1].
+          The inequality needle[x..i-1] != needle[0..i-1-x] is known to hold
+          for x < table[i-1], by induction.
+          Furthermore, if j>0: needle[i-1-j..i-2] = needle[0..j-1].  */
        unsigned char b = TOLOWER ((unsigned char) needle[i - 1]);
 
        for (;;)
          {
+           /* Invariants: The inequality needle[x..i-1] != needle[0..i-1-x]
+              is known to hold for x < i-1-j.
+              Furthermore, if j>0: needle[i-1-j..i-2] = needle[0..j-1].  */
            if (b == TOLOWER ((unsigned char) needle[j]))
              {
+               /* Set table[i] := i-1-j.  */
                table[i] = i - ++j;
                break;
              }
+           /* The inequality needle[x..i-1] != needle[0..i-1-x] also holds
+              for x = i-1-j, because
+                needle[i-1] != needle[j] = needle[i-1-x].  */
            if (j == 0)
              {
+               /* The inequality holds for all possible x.  */
                table[i] = i;
                break;
              }
+           /* The inequality needle[x..i-1] != needle[0..i-1-x] also holds
+              for i-1-j < x < i-1-j+table[j], because for these x:
+                needle[x..i-2]
+                = needle[x-(i-1-j)..j-1]
+                != needle[0..j-1-(x-(i-1-j))]  (by definition of table[j])
+                   = needle[0..i-2-x],
+              hence needle[x..i-1] != needle[0..i-1-x].
+              Furthermore
+                needle[i-1-j+table[j]..i-2]
+                = needle[table[j]..j-1]
+                = needle[0..j-1-table[j]]  (by definition of table[j]).  */
            j = j - table[j];
          }
+       /* Here: j = i - table[i].  */
       }
   }
 
@@ -154,34 +187,67 @@ knuth_morris_pratt_multibyte (const char *haystack, const char *needle,
   /* Fill the table.
      For 0 < i < m:
        0 < table[i] <= i is defined such that
-       rhaystack[0..i-1] == needle[0..i-1] and rhaystack[i] != needle[i]
-       implies
-       forall 0 <= x < table[i]: rhaystack[x..x+m-1] != needle[0..m-1],
+       forall 0 < x < table[i]: needle[x..i-1] != needle[0..i-1-x],
        and table[i] is as large as possible with this property.
+     This implies:
+     1) For 0 < i < m:
+          If table[i] < i,
+          needle[table[i]..i-1] = needle[0..i-1-table[i]].
+     2) For 0 < i < m:
+          rhaystack[0..i-1] == needle[0..i-1]
+          and exists h, i <= h < m: rhaystack[h] != needle[h]
+          implies
+          forall 0 <= x < table[i]: rhaystack[x..x+m-1] != needle[0..m-1].
      table[0] remains uninitialized.  */
   {
     size_t i, j;
 
+    /* i = 1: Nothing to verify for x = 0.  */
     table[1] = 1;
     j = 0;
+
     for (i = 2; i < m; i++)
       {
+       /* Here: j = i-1 - table[i-1].
+          The inequality needle[x..i-1] != needle[0..i-1-x] is known to hold
+          for x < table[i-1], by induction.
+          Furthermore, if j>0: needle[i-1-j..i-2] = needle[0..j-1].  */
        mbchar_t *b = &needle_mbchars[i - 1];
 
        for (;;)
          {
+           /* Invariants: The inequality needle[x..i-1] != needle[0..i-1-x]
+              is known to hold for x < i-1-j.
+              Furthermore, if j>0: needle[i-1-j..i-2] = needle[0..j-1].  */
            if (mb_equal (*b, needle_mbchars[j]))
              {
+               /* Set table[i] := i-1-j.  */
                table[i] = i - ++j;
                break;
              }
+           /* The inequality needle[x..i-1] != needle[0..i-1-x] also holds
+              for x = i-1-j, because
+                needle[i-1] != needle[j] = needle[i-1-x].  */
            if (j == 0)
              {
+               /* The inequality holds for all possible x.  */
                table[i] = i;
                break;
              }
+           /* The inequality needle[x..i-1] != needle[0..i-1-x] also holds
+              for i-1-j < x < i-1-j+table[j], because for these x:
+                needle[x..i-2]
+                = needle[x-(i-1-j)..j-1]
+                != needle[0..j-1-(x-(i-1-j))]  (by definition of table[j])
+                   = needle[0..i-2-x],
+              hence needle[x..i-1] != needle[0..i-1-x].
+              Furthermore
+                needle[i-1-j+table[j]..i-2]
+                = needle[table[j]..j-1]
+                = needle[0..j-1-table[j]]  (by definition of table[j]).  */
            j = j - table[j];
          }
+       /* Here: j = i - table[i].  */
       }
   }