From dca3b15c2c8f9ab3924054a85fcda845303a3e75 Mon Sep 17 00:00:00 2001
From: Kaz Kylheku <kaz@kylheku.com>
Date: Mon, 26 Apr 2021 07:05:54 -0700
Subject: match-str: return useful position instead of t.

* lib.c (match_str): The match_str function is hereby altered
to return an integer instead of the symbol t in the matching case.

* txr.1: Updated.
---
 lib.c |  4 ++--
 txr.1 | 26 ++++++++++++++++++++------
 2 files changed, 22 insertions(+), 8 deletions(-)

diff --git a/lib.c b/lib.c
index 917a59e1..ea90164b 100644
--- a/lib.c
+++ b/lib.c
@@ -4511,7 +4511,7 @@ val match_str(val bigstr, val str, val pos)
         return nil;
     }
 
-    return length_str_le(str, i) ? t : nil;
+    return length_str_le(str, i) ? succ(i) : nil;
   } else {
     pos = plus(pos, length(bigstr));
     pos = plus(minus(pos, length(str)), one);
@@ -4524,7 +4524,7 @@ val match_str(val bigstr, val str, val pos)
         return nil;
     }
 
-    return minusp(i);
+    return minusp(i) ? pos : nil;
   }
 }
 
diff --git a/txr.1 b/txr.1
index 1589215e..88663164 100644
--- a/txr.1
+++ b/txr.1
@@ -23606,12 +23606,7 @@ argument, the
 function determines whether
 .meta littlestring
 is a prefix of
-.metn bigstring ,
-returning a
-.code t
-or
-.code nil
-indication.
+.metn bigstring .
 
 If the
 .meta start
@@ -23648,6 +23643,25 @@ then this corresponds to testing whether
 is a suffix of
 .metn bigstring .
 
+The
+.code match-str
+function returns
+.code nil
+if there is no match.
+
+If a prefix match is successful,
+then an integer value is returned indicating the position, inside
+.metn bigstring ,
+one character past the matching prefix. If the entire string is matched, then
+this value corresponds to the length of
+.metn bigstring .
+
+If a suffix match is successful, the return value is the position within
+.meta bigstring
+where the leftmost character of
+.meta littlestring
+matched.
+
 .coNP Function @ match-str-tree
 .synb
 .mets (match-str-tree < bigstring < tree <> [ start ])
-- 
cgit v1.2.3