GNU Info

(elisp)Simple Match Data

---

Next: Entire Match Data Prev: Replacing Match Up: Match Data

---

Enter node , (file) or (file)node

Simple Match Data Access
------------------------

   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.

   A search which fails may or may not alter the match data.  In the
past, a failing search did not do this, but we may change it in the
future.

 - Function: match-string count &optional in-string
     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 the last such operation was done against a string with
     `string-match', then you should pass the same string as the
     argument IN-STRING.  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.

     The value is `nil' if COUNT is out of range, or for a
     subexpression inside a `\|' alternative that wasn't used or a
     repetition that repeated zero times.

 - Function: match-string-no-properties count &optional in-string
     This function is like `match-string' except that the result has no
     text properties.

 - Function: match-beginning count
     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 or a repetition that repeated zero times.

 - Function: match-end count
     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.)