Next: Replacing Match, Previous: Match Data, Up: Match Data [Contents][Index]
This section explains how to use the match data to find out what was matched by the last search or match operation.
You can ask about the entire matching text, or about a particular parenthetical subexpression of a regular expression. The count argument in the functions below specifies which. If count is zero, you are asking about the entire match. If count is positive, it specifies which subexpression you want.
Recall that the subexpressions of a regular expression are those expressions grouped with escaped parentheses, ‘\(…\)’. The countth subexpression is found by counting occurrences of ‘\(’ from the beginning of the whole regular expression. The first subexpression is numbered 1, the second 2, and so on. Only regular expressions can have subexpressions—after a simple string search, the only information available is about the entire match.
This function returns, as a string, the text matched in the last search
or match operation. It returns the entire text if count is zero,
or just the portion corresponding to the countth parenthetical
subexpression, if count is positive. If count is out of
range, or if that subexpression didn’t match anything, the value is
nil
.
If the last such operation was done against a string with
string-match
, then you should pass the same string as the
argument in-string. Otherwise, after a buffer search or match,
you should omit in-string or pass nil
for it; but you
should make sure that the current buffer when you call
match-string
is the one in which you did the searching or
matching.
This function returns the position of the start of text matched by the last regular expression searched for, or a subexpression of it.
If count is zero, then the value is the position of the start of the entire match. Otherwise, count specifies a subexpression in the regular expression, and the value of the function is the starting position of the match for that subexpression.
The value is nil
for a subexpression inside a ‘\|’
alternative that wasn’t used in the match.
This function is like match-beginning
except that it returns the
position of the end of the match, rather than the position of the
beginning.
Here is an example of using the match data, with a comment showing the positions within the text:
(string-match "\\(qu\\)\\(ick\\)" "The quick fox jumped quickly.") ;0123456789 ⇒ 4
(match-string 0 "The quick fox jumped quickly.") ⇒ "quick" (match-string 1 "The quick fox jumped quickly.") ⇒ "qu" (match-string 2 "The quick fox jumped quickly.") ⇒ "ick"
(match-beginning 1) ; The beginning of the match ⇒ 4 ; with ‘qu’ is at index 4.
(match-beginning 2) ; The beginning of the match ⇒ 6 ; with ‘ick’ is at index 6.
(match-end 1) ; The end of the match ⇒ 6 ; with ‘qu’ is at index 6. (match-end 2) ; The end of the match ⇒ 9 ; with ‘ick’ is at index 9.
Here is another example. Point is initially located at the beginning of the line. Searching moves point to between the space and the word ‘in’. The beginning of the entire match is at the 9th character of the buffer (‘T’), and the beginning of the match for the first subexpression is at the 13th character (‘c’).
(list (re-search-forward "The \\(cat \\)") (match-beginning 0) (match-beginning 1)) ⇒ (9 9 13)
---------- Buffer: foo ---------- I read "The cat ∗in the hat comes back" twice. ^ ^ 9 13 ---------- Buffer: foo ----------
(In this case, the index returned is a buffer position; the first character of the buffer counts as 1.)
Next: Replacing Match, Previous: Match Data, Up: Match Data [Contents][Index]