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, see Searching and Replacement.
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. See Text Representations.
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
search-failederror is signaled. If noerror is
niland does nothing. If noerror is neither
search-forwardmoves point to the upper bound and returns
The argument noerror only affects valid searches which fail to find a match. Invalid arguments cause errors regardless of noerror.
If repeat is a positive number n, it serves as a repeat count: the search is repeated n 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, with results depending on the value of noerror, as described above. If repeat is a negative number -n, it serves as a repeat count of n for a search in the opposite (backward) direction.
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.
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
word-search-forwardsignals an error if the search fails. If noerror is
t, then it returns
nilinstead of signaling an error. If noerror is neither
t, it moves point to limit (or the end of the accessible portion of the buffer) and returns
If repeat is non-
nil, then the search is repeated that many times. Point is positioned at the end of the last match.
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’.
This function searches backward from point for a word match to string. This function is just like
word-search-forwardexcept that it searches backward and normally leaves point at the beginning of the match.