Commit 7a68ebe0 authored by Paul Eggert's avatar Paul Eggert

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.
parent 9a1175cb
......@@ -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
......
......@@ -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.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment