Searching for Strings
=====================
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; the
arguments LIMIT and NOERROR are `nil', and REPEAT is 1.
These search functions convert the search string to multibyte if the
buffer is multibyte; they convert the search string to unibyte if the
buffer is unibyte. Note:Text Representations.
- Command: search-forward string &optional limit noerror repeat
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 existing programs may depend on a
value of `nil'.)
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 these successive searches
succeed, the function succeeds, moving point and returning its new
value. Otherwise the search fails.
- Command: search-backward string &optional limit noerror repeat
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.
- Command: word-search-forward string &optional limit noerror repeat
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 REPEAT is non-`nil', then the search is repeated that many
times. Point is positioned at the end of the last match.
- Command: word-search-backward string &optional limit noerror repeat
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.