elisp: String Search
33.1 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. For more
details on interactive searching, 
Searching and Replacement
(emacs)Search.
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. Text Representations.
-- Command: search-forward string &optional limit noerror count
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 bound to the search, and should 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’.
The argument NOERROR only affects valid searches which fail to find
a match. Invalid arguments cause errors regardless of NOERROR.
If COUNT is a positive number N, the search is done N times; each
successive search starts at the end of the previous match. If all
these successive searches succeed, the function call succeeds,
moving point and returning its new value. Otherwise the function
call fails, with results depending on the value of NOERROR, as
described above. If COUNT is a negative number -N, the search is
done N times in the opposite (backward) direction.
-- Command: search-backward string &optional limit noerror count
This function searches backward from point for STRING. It is like
‘search-forward’, except that it searches backwards rather than
forwards. Backward searches leave point at the beginning of the
match.
-- Command: word-search-forward string &optional limit noerror count
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.")
⇒ 39
---------- 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;
it specifies 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 accessible portion of the
buffer) and returns ‘nil’.
If COUNT is a positive number, it specifies how many successive
occurrences to search for. Point is positioned at the end of the
last match. If COUNT is a negative number, the search is backward
and point is positioned at the beginning of the last match.
Internally, ‘word-search-forward’ and related functions use the
function ‘word-search-regexp’ to convert STRING to a regular
expression that ignores punctuation.
-- Command: word-search-forward-lax string &optional limit noerror
count
This command is identical to ‘word-search-forward’, except that the
beginning or the end of STRING need not match a word boundary,
unless STRING begins or ends in whitespace. For instance,
searching for ‘ball boy’ matches ‘ball boyee’, but does not match
‘balls boy’.
-- Command: word-search-backward string &optional limit noerror count
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.
-- Command: word-search-backward-lax string &optional limit noerror
count
This command is identical to ‘word-search-backward’, except that
the beginning or the end of STRING need not match a word boundary,
unless STRING begins or ends in whitespace.
Info Catalog
elisp: Searching and Matching
elisp: Searching and Case