12.2 The re-search-forward Function

The re-search-forward function is very like the search-forward function. (See The search-forward Function.)

re-search-forward searches for a regular expression. If the search is successful, it leaves point immediately after the last character in the target. If the search is backwards, it leaves point just before the first character in the target. You may tell re-search-forward to return t for true. (Moving point is therefore a side effect.)

Like search-forward, the re-search-forward function takes four arguments:

1. The first argument is the regular expression that the function searches for. The regular expression will be a string between quotation marks.
2. The optional second argument limits how far the function will search; it is a bound, which is specified as a position in the buffer.
3. The optional third argument specifies how the function responds to failure: nil as the third argument causes the function to signal an error (and print a message) when the search fails; any other value causes it to return nil if the search fails and t if the search succeeds.
4. The optional fourth argument is the repeat count. A negative repeat count causes re-search-forward to search backwards.

The template for re-search-forward looks like this:

(re-search-forward "regular-expression"
                limit-of-search
                what-to-do-if-search-fails
                repeat-count)

The second, third, and fourth arguments are optional. However, if you want to pass a value to either or both of the last two arguments, you must also pass a value to all the preceding arguments. Otherwise, the Lisp interpreter will mistake which argument you are passing the value to.

In the forward-sentence function, the regular expression will be the value of the variable sentence-end. In simple form, that is:

"[.?!][]\"')}]*\\($\\|  \\|  \\)[
]*"

The limit of the search will be the end of the paragraph (since a sentence cannot go beyond a paragraph). If the search fails, the function will return nil; and the repeat count will be provided by the argument to the forward-sentence function.