Go to the previous, next section.

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 this case the target string is just one character long.) 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 treats 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 or shorter, 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.

Go to the previous, next section.