[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
In GNU Emacs, you can search for the next match for a regular
expression either incrementally or not. For incremental search
commands, see section `Regular Expression Search' in The GNU Emacs Manual. 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. See section 33.1 Text Representations.
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 ---------- |
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.
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)
. See section 34.6 The Match Data.
(string-match "quick" "The quick brown fox jumped quickly." 8) => 27 (match-end 0) => 32 |
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 section 34.6 The 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 |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |