Copyright (C) 2000-2012 |
GNU Info (emacs-lisp-intro.info)search-forwardThe `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.) 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. automatically generated by info2www version 1.2.2.9 |