GNU Info

Info Node: (emacs-lisp-intro.info)search-forward

(emacs-lisp-intro.info)search-forward


Next: progn Prev: zap-to-char body Up: zap-to-char
Enter node , (file) or (file)node

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.)  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