GNU Info

(elisp)Regexp Search

---

Next: POSIX Regexps Prev: Regular Expressions Up: Searching and Matching

---

Enter node , (file) or (file)node

Regular Expression Searching
============================

   In GNU Emacs, you can search for the next match for a regular
expression either incrementally or not.  For incremental search
commands, see Note: Regular Expression Search.
Here we describe only the search functions useful in programs.  The
principal one is `re-search-forward'.

   These search functions convert the regular expression to multibyte if
the buffer is multibyte; they convert the regular expression to unibyte
if the buffer is unibyte.  Note: Text Representations.

 - Command: re-search-forward regexp &optional limit noerror repeat
     This function searches forward in the current buffer for a string
     of text that is matched by the regular expression REGEXP.  The
     function skips over any amount of text that is not matched by
     REGEXP, and leaves point at the end of the first match found.  It
     returns the new value of point.

     If LIMIT is non-`nil' (it must be a position in the current
     buffer), then it is the upper bound to the search.  No match
     extending after that position is accepted.

     If REPEAT is supplied (it must be a positive number), then the
     search is repeated that many times (each time starting at the end
     of the previous time's match).  If all these successive searches
     succeed, the function succeeds, moving point and returning its new
     value.  Otherwise the function fails.

     What happens when the function fails depends on the value of
     NOERROR.  If NOERROR is `nil', a `search-failed' error is
     signaled.  If NOERROR is `t', `re-search-forward' does nothing and
     returns `nil'.  If NOERROR is neither `nil' nor `t', then
     `re-search-forward' moves point to LIMIT (or the end of the
     buffer) and returns `nil'.

     In the following example, point is initially before the `T'.
     Evaluating the search call moves point to the end of that line
     (between the `t' of `hat' and the newline).

          ---------- Buffer: foo ----------
          I read "-!-The cat in the hat
          comes back" twice.
          ---------- Buffer: foo ----------
          
          (re-search-forward "[a-z]+" nil t 5)
               => 27
          
          ---------- Buffer: foo ----------
          I read "The cat in the hat-!-
          comes back" twice.
          ---------- Buffer: foo ----------

 - Command: re-search-backward regexp &optional limit noerror repeat
     This function searches backward in the current buffer for a string
     of text that is matched by the regular expression REGEXP, leaving
     point at the beginning of the first text found.

     This function is analogous to `re-search-forward', but they are not
     simple mirror images.  `re-search-forward' finds the match whose
     beginning is as close as possible to the starting point.  If
     `re-search-backward' were a perfect mirror image, it would find the
     match whose end is as close as possible.  However, in fact it
     finds the match whose beginning is as close as possible.  The
     reason for this is that matching a regular expression at a given
     spot always works from beginning to end, and starts at a specified
     beginning position.

     A true mirror-image of `re-search-forward' would require a special
     feature for matching regular expressions from end to beginning.
     It's not worth the trouble of implementing that.

 - Function: string-match regexp string &optional start
     This function returns the index of the start of the first match for
     the regular expression REGEXP in STRING, or `nil' if there is no
     match.  If START is non-`nil', the search starts at that index in
     STRING.

     For example,

          (string-match
           "quick" "The quick brown fox jumped quickly.")
               => 4
          (string-match
           "quick" "The quick brown fox jumped quickly." 8)
               => 27

     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 the match is available as `(match-end 0)'.  Note: Match
     Data.

          (string-match
           "quick" "The quick brown fox jumped quickly." 8)
               => 27
          
          (match-end 0)
               => 32

 - Function: looking-at regexp
     This function determines whether the text in the current buffer
     directly following point matches the regular expression REGEXP.
     "Directly following" means precisely that: the search is
     "anchored" and it can succeed only starting with the first
     character following point.  The result is `t' if so, `nil'
     otherwise.

     This function does not move point, but it updates the match data,
     which you can access using `match-beginning' and `match-end'.
     Note: Match Data.

     In this example, point is located directly before the `T'.  If it
     were anywhere else, the result would be `nil'.

          ---------- Buffer: foo ----------
          I read "-!-The cat in the hat
          comes back" twice.
          ---------- Buffer: foo ----------
          
          (looking-at "The cat in the hat$")
               => t