Next: , Previous: , Up: Searching and Matching   [Contents][Index]


44.3 Regular Expression Searching

In SXEmacs, you can search for the next match for a regexp either incrementally or not. Incremental search commands are described in the The SXEmacs Lisp Reference Manual. See Regular Expression Search in The SXEmacs Lisp Reference Manual. Here we describe only the search functions useful in programs. The principal one is re-search-forward.

Command: re-search-forward regexp &optional limit noerror count buffer

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.

What happens when the search 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.

If count 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 these successive searches succeed, the function succeeds, moving point and returning its new value. Otherwise the search fails.

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 count buffer

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 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 regexps from end to beginning. It’s not worth the trouble of implementing that.

Function: string-match regexp string &optional start buffer

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.

Optional arg buffer controls how case folding is done (according to the value of case-fold-search in buffer and buffer’s case tables) and defaults to the current buffer.

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). See Match Data.

(string-match
 "quick" "The quick brown fox jumped quickly." 8)
     ⇒ 27
(match-end 0)
     ⇒ 32
Function: split-string string &optional pattern

This function splits string to substrings delimited by pattern, and returns a list of substrings. If pattern is omitted, it defaults to ‘[ \f\t\n\r\v]+’, which means that it splits string by white–space.

(split-string "foo bar")
     ⇒ ("foo" "bar")
(split-string "something")
     ⇒ ("something")
(split-string "a:b:c" ":")
     ⇒ ("a" "b" "c")
(split-string ":a::b:c" ":")
     ⇒ ("" "a" "" "b" "c")
Function: split-path path

This function splits a search path into a list of strings. The path components are separated with the characters specified with path-separator. Under Unix, path-separator will normally be ‘:’, while under Windows, it will be ‘;’.

Function: looking-at regexp &optional buffer

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. See 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

Next: , Previous: , Up: Searching and Matching   [Contents][Index]