8.1.3 The search-forward Function

The search-forward function is used to locate the zapped-for-character in zap-to-char. If the search is successful, search-forward leaves point immediately after the last character in the target string. (In zap-to-char, the target string is just one character long. zap-to-char uses the function char-to-string to ensure that the computer treats that character as a string.) If the search is backwards, search-forward leaves point just before the first character in the target. Also, search-forward returns t for true. (Moving point is therefore a side effect.)

In zap-to-char, the search-forward function looks like this:

(search-forward (char-to-string char) nil nil arg)

The search-forward function takes four arguments:

1. The first argument is the target, what is searched for. This must be a string, such as ‘"z"’.

   As it happens, the argument passed to zap-to-char is a single character. Because of the way computers are built, the Lisp interpreter may treat a single character as being different from a string of characters. Inside the computer, a single character has a different electronic format than a string of one character. (A single character can often be recorded in the computer using exactly one byte; but a string may be longer, and the computer needs to be ready for this.) Since the search-forward function searches for a string, the character that the zap-to-char function receives as its argument must be converted inside the computer from one format to the other; otherwise the search-forward function will fail. The char-to-string function is used to make this conversion.

2. The second argument bounds the search; it is specified as a position in the buffer. In this case, the search can go to the end of the buffer, so no bound is set and the second argument is nil.
3. The third argument tells the function what it should do if the search fails—it can signal an error (and print a message) or it can return nil. A nil as the third argument causes the function to signal an error when the search fails.
4. The fourth argument to search-forward is the repeat count—how many occurrences of the string to look for. This argument is optional and if the function is called without a repeat count, this argument is passed the value 1. If this argument is negative, the search goes backwards.

In template form, a search-forward expression looks like this:

(search-forward "target-string"
                limit-of-search
                what-to-do-if-search-fails
                repeat-count)

We will look at progn next.