Next: Regular Expressions, Previous: Searching and Matching, Up: Searching and Matching [Contents][Index]
These are the primitive functions for searching through the text in a
buffer. They are meant for use in programs, but you may call them
interactively. If you do so, they prompt for the search string;
limit and noerror are set to nil
, and count
is set to 1.
This function searches forward from point for an exact match for string. If successful, it sets point to the end of the occurrence found, and returns the new value of point. If no match is found, the value and side effects depend on noerror (see below).
In the following example, point is initially at the beginning of the
line. Then (search-forward "fox")
moves point after the last
letter of ‘fox’:
---------- Buffer: foo ---------- ∗The quick brown fox jumped over the lazy dog. ---------- Buffer: foo ----------
(search-forward "fox") ⇒ 20 ---------- Buffer: foo ---------- The quick brown fox∗ jumped over the lazy dog. ---------- Buffer: foo ----------
The argument limit specifies the upper bound to the search. (It
must be a position in the current buffer.) No match extending after
that position is accepted. If limit is omitted or nil
, it
defaults to the end of the accessible portion of the buffer.
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
, search-forward
returns nil
and does nothing. If noerror is neither
nil
nor t
, then search-forward
moves point to the
upper bound and returns nil
. (It would be more consistent now
to return the new position of point in that case, but some programs
may depend on a value of nil
.)
If count is supplied (it must be an integer), then the search is repeated that many times (each time starting at the end of the previous time’s match). If count is negative, the search direction is backward. If the successive searches succeed, the function succeeds, moving point and returning its new value. Otherwise the search fails.
buffer is the buffer to search in, and defaults to the current buffer.
This function searches backward from point for string. It is
just like search-forward
except that it searches backwards and
leaves point at the beginning of the match.
This function searches forward from point for a “word” match for string. If it finds a match, it sets point to the end of the match found, and returns the new value of point.
Word matching regards string as a sequence of words, disregarding punctuation that separates them. It searches the buffer for the same sequence of words. Each word must be distinct in the buffer (searching for the word ‘ball’ does not match the word ‘balls’), but the details of punctuation and spacing are ignored (searching for ‘ball boy’ does match ‘ball. Boy!’).
In this example, point is initially at the beginning of the buffer; the search leaves it between the ‘y’ and the ‘!’.
---------- Buffer: foo ---------- ∗He said "Please! Find the ball boy!" ---------- Buffer: foo ----------
(word-search-forward "Please find the ball, boy.") ⇒ 35 ---------- Buffer: foo ---------- He said "Please! Find the ball boy∗!" ---------- Buffer: foo ----------
If limit is non-nil
(it must be a position in the current
buffer), then it is the upper bound to the search. The match found must
not extend after that position.
If noerror is nil
, then word-search-forward
signals
an error if the search fails. If noerror is t
, then it
returns nil
instead of signaling an error. If noerror is
neither nil
nor t
, it moves point to limit (or the
end of the buffer) and returns nil
.
If count is non-nil
, then the search is repeated that many
times. Point is positioned at the end of the last match.
buffer is the buffer to search in, and defaults to the current buffer.
This function searches backward from point for a word match to
string. This function is just like word-search-forward
except that it searches backward and normally leaves point at the
beginning of the match.
Next: Regular Expressions, Previous: Searching and Matching, Up: Searching and Matching [Contents][Index]