From bcc1770bf64c62dc5c6404596017cf73a6c9e25e Mon Sep 17 00:00:00 2001
From: Kaz Kylheku <kaz@kylheku.com>
Date: Mon, 27 Jan 2014 00:27:47 -0800
Subject: * regex.c (match_regex_right): Fix semantics of second argument to
 something more useful.

* regex.h (match_regex_right): Change name of parameter.

* txr.1: Documented match-regex-right.
---
 regex.c | 11 +++++-----
 regex.h |  2 +-
 txr.1   | 72 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-----
 3 files changed, 74 insertions(+), 11 deletions(-)

diff --git a/regex.c b/regex.c
index 67f17f60..090846b1 100644
--- a/regex.c
+++ b/regex.c
@@ -1854,20 +1854,21 @@ val match_regex(val str, val reg, val pos)
   return nil;
 }
 
-val match_regex_right(val str, val regex, val pos)
+val match_regex_right(val str, val regex, val end)
 {
+  val pos = zero;
   val slen = length(str);
 
-  if (!pos)
-    pos = zero;
+  if (!end || gt(end, slen))
+    end = slen;
 
-  for (;;) {
+  while (lt(pos, end)) {
     cons_bind (from, len, search_regex(str, regex, pos, nil));
 
     if (!from)
       return nil;
 
-    if (eql(plus(from, len), slen))
+    if (eql(plus(from, len), end))
       return len;
 
     pos = plus(pos, one);
diff --git a/regex.h b/regex.h
index 1ea148bd..1c531cff 100644
--- a/regex.h
+++ b/regex.h
@@ -31,7 +31,7 @@ val regex_compile(val regex, val error_stream);
 val regexp(val);
 val search_regex(val haystack, val needle_regex, val start_num, val from_end);
 val match_regex(val str, val regex, val pos);
-val match_regex_right(val str, val regex, val pos);
+val match_regex_right(val str, val regex, val end);
 val regsub(val regex, val repl, val str);
 
 void regex_init(void);
diff --git a/txr.1 b/txr.1
index c962539c..43b08e3f 100644
--- a/txr.1
+++ b/txr.1
@@ -9604,19 +9604,16 @@ and error.
 
 .SH REGULAR EXPRESSION LIBRARY
 
-.SS Functions search-regex and match-regex
+.SS Function search-regex
 
 .TP
 Syntax:
 
  (search-regex <haystack-string> <needle-regex> : <start> <from-end>)
- (match-regex <string> <regex> : <position>)
 
 .TP
 Description
 
-These functions perform regular-expression-based searching and matching.
-
 The search-regex function searches through <haystack-string> starting
 at position <start> for a match for <needle-regex>. If <start> is omitted,
 the search starts at position 0. If <from-end> is specified, the search
@@ -9625,11 +9622,76 @@ This function returns nil if no match is found, otherwise it returns
 a cons pair, whose car indicates the position of the match, and whose
 cdr indicates the length of the match. 
 
+.SS Function match-regex
+
+.TP
+Syntax:
+
+ (match-regex <string> <regex> : <position>)
+
+.TP
+Description
+
 The match-regex function tests whether <regex> matches at <position>
 in <string>. If <position> is not specified, it is taken to be zero.
 If the regex matches, then the length of the match is returned.
 If it does not match, then nil is returned.
-.
+
+.SS Function match-regex-right
+
+.TP
+Syntax:
+
+ (match-regex-right <string> <regex> : <end-position>)
+
+.TP
+Description
+
+The match-regex function tests whether <string> contains a match which ends
+precisely on the character just before <end-position>.  If <end-position> is
+not specified, it defaults to the length of the string, and the function
+performs a right-anchored regex match.
+
+If a match is found, then the length of the match is returned, and
+the matching substring is then returned.
+
+The match must terminate just before <end-position> in the sense that
+additional characters at <end-position> and beyond can no longer satisfy the
+regular expression. More formally, the function searches, starting from
+position zero, for positions where there occurs a match for the regular
+expression, taking the longest possible match. The length of first such a match
+which terminates on the character just before <end-position> is returned.
+If no such a match is found, then nil is returned.
+
+.TP
+Examples:
+
+  ;; Return matching portion rather than length thereof.
+
+  (defun match-regex-right-substring (str reg : end-pos)
+    (set end-pos (or end-pos (length str)))
+    (let ((len (match-regex-right str reg end-pos)))
+      (if len
+        [str (- end-pos len)..end-pos]
+        nil)))
+     
+  (match-regex-right-substring "abc" #/c/) -> ""
+
+  (match-regex-right-substring "acc" #/c*/) -> "cc"
+
+  ;; Regex matches starting at multiple positions, but all
+  ;; the matches extend past the limit.
+  (match-regex-right-substring "acc" #/c*/ 2) -> nil
+
+  ;; If the above behavior is not wanted, then
+  ;; we can extract the string up to the limiting
+  ;; position and do the match on that.
+  (match-regex-right-substring ["acc" 0..2] #/c*/) -> "c"
+
+  ;; Equivalent of above call
+  (match-regex-right-substring "ac" #/c*/) -> "c"
+
+
 .SS Function regsub
 
 .TP
-- 
cgit v1.2.3