From 7a68ebe0485d049a3fbbfd77d0ba5773e8e6ae87 Mon Sep 17 00:00:00 2001 From: Paul Eggert Date: Mon, 17 Aug 2015 23:46:38 -0700 Subject: [PATCH] Clarify what happens to match data on failure Problem reported by Ernesto Alfonso (Bug#21279). * doc/lispref/searching.texi (Regexp Search, Simple Match Data): Document more carefully what happens to match data after a failed search. * src/search.c (Fmatch_beginning, Fmatch_end): Document that the return value is undefined if the last search failed. (Fmatch_data): Simplify doc string line 1. --- doc/lispref/searching.texi | 7 ++++--- src/search.c | 10 +++++++--- 2 files changed, 11 insertions(+), 6 deletions(-) diff --git a/doc/lispref/searching.texi b/doc/lispref/searching.texi index 5a05c7c729d..60360cb98a9 100644 --- a/doc/lispref/searching.texi +++ b/doc/lispref/searching.texi @@ -1102,7 +1102,7 @@ For example, The index of the first character of the string is 0, the index of the second character is 1, and so on. -After this function returns, the index of the first character beyond +If this function finds a match, the index of the first character beyond the match is available as @code{(match-end 0)}. @xref{Match Data}. @example @@ -1425,8 +1425,9 @@ has no text properties. @end defun @defun match-beginning count -This function returns the position of the start of the text matched by the -last regular expression searched for, or a subexpression of it. +If the last regular expression search found a match, this function +returns the position of the start of the matching text or of a +subexpression of it. If @var{count} is zero, then the value is the position of the start of the entire match. Otherwise, @var{count} specifies a subexpression in diff --git a/src/search.c b/src/search.c index 5da99c408a5..106a462f804 100644 --- a/src/search.c +++ b/src/search.c @@ -2754,7 +2754,9 @@ SUBEXP, a number, specifies which parenthesized expression in the last regexp. Value is nil if SUBEXPth pair didn't match, or there were less than SUBEXP pairs. -Zero means the entire text matched by the whole regexp or whole string. */) +Zero means the entire text matched by the whole regexp or whole string. + +Return value is undefined if the last search failed. */) (Lisp_Object subexp) { return match_limit (subexp, 1); @@ -2766,14 +2768,16 @@ SUBEXP, a number, specifies which parenthesized expression in the last regexp. Value is nil if SUBEXPth pair didn't match, or there were less than SUBEXP pairs. -Zero means the entire text matched by the whole regexp or whole string. */) +Zero means the entire text matched by the whole regexp or whole string. + +Return value is undefined if the last search failed. */) (Lisp_Object subexp) { return match_limit (subexp, 0); } DEFUN ("match-data", Fmatch_data, Smatch_data, 0, 3, 0, - doc: /* Return a list containing all info on what the last search matched. + doc: /* Return a list describing what the last search matched. Element 2N is `(match-beginning N)'; element 2N + 1 is `(match-end N)'. All the elements are markers or nil (nil if the Nth pair didn't match) if the last match was on a buffer; integers or nil if a string was matched. -- 2.11.4.GIT