bug#27659: 26.0.50; Add string-matched-text: string-match + match-string

[Tino Calancha]

Severity: wishlist

Just wondering if the following is of any interest:

(defun string-matched-text (regexp string num &optional start)
  ""
  (when (string-match regexp string start)
    (match-string num string)))
    
Then,

(let ((str "foo-123"))
  (when (string-match "[[:alpha:]]+-\\([0-9]+\\)" str)
    (match-string 1 str)))
=> "123"

is equivalent to:
(string-matched-text "[[:alpha:]]+-\\([0-9]+\\)" "foo-123" 1)
=> "123"

--8<-----------------------------cut here---------------start------------->8---
commit 65741b74d8999beaacd5093e128030a8635aff05
Author: Tino Calancha <tino.calancha@gmail.com>
Date:   Wed Jul 12 14:29:08 2017 +0900

    string-matched-text: New function
    
    * lisp/subr.el (string-matched-text): New defun.
    * doc/lispref/searching.texi (Simple Match Data): Update manual.
    * etc/NEWS: Announce it.

diff --git a/doc/lispref/searching.texi b/doc/lispref/searching.texi
index 67d4c22464..81bcad1740 100644
--- a/doc/lispref/searching.texi
+++ b/doc/lispref/searching.texi
@@ -1457,6 +1457,16 @@ Simple Match Data
 repetition that repeated zero times.
 @end defun
 
+@defun string-matched-text regexp string count &optional start
+This function returns, as a string, the text matched by @var{regexp}
+in @var{string}, or @code{nil} if there is no match.  The meaning
+of @var{count} is same as in @code{match-string}.  If @var{start}
+is non-@code{nil}, the search starts at that index in @var{string}.
+The behavior of this function is equivalent to
+@w{@code{(and (string-match @var{regexp} @var{string} @var{start})
+(match-string @var{count} @var{string}))}}.
+@end defun
+
 @defun match-string-no-properties count &optional in-string
 This function is like @code{match-string} except that the result
 has no text properties.
diff --git a/etc/NEWS b/etc/NEWS
index 68ebdb3c15..794edef9cd 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1105,6 +1105,8 @@ break.

 * Lisp Changes in Emacs 26.1
 
+** New function 'string-matched-text'.
+
 ** New function 'seq-set-equal-p' to check if SEQUENCE1 and SEQUENCE2
 contain the same elements, regardless of the order.
 
diff --git a/lisp/subr.el b/lisp/subr.el
index a9edff6166..1482787842 100644
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -3635,6 +3635,15 @@ match-string
          (substring string (match-beginning num) (match-end num))
        (buffer-substring (match-beginning num) (match-end num)))))
 
+(defun string-matched-text (regexp string num &optional start)
+  "Return string of text matched by REGEXP in STRING.
+NUM specifies which parenthesized expression in REGEXP.
+  Value is nil if NUMth pair didn’t match, or there were less than NUM pairs.
+Zero means the entire text matched by the whole regexp or whole string.
+If optional arg START is non-nil, then start search at that index in STRING."
+  (when (string-match regexp string start)
+    (match-string num string)))
+
 (defun match-string-no-properties (num &optional string)
   "Return string of text matched by last search, without text properties.
 NUM specifies which parenthesized expression in the last regexp.
--8<-----------------------------cut here---------------end--------------->8---

In GNU Emacs 26.0.50 (build 4, x86_64-pc-linux-gnu, GTK+ Version 3.22.11)
 of 2017-07-11
Repository revision: d014a5e15c1110af77e7a96f06ccd0f0cafb099f