Document negative repeat counts for search-forward and search-backward.

* doc/lispref/searching.texi (String Search): Document negative repeat count.

* src/search.c (Fsearch_forward, Fsearch_backward): Document negative
repeat counts (Bug#10507).

4 files changed, 27 insertions, 11 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 145d2dbc4f5..89174f3ca0e 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,8 @@
+2012-01-26  Chong Yidong  <cyd@gnu.org>
+
+        * searching.texi (String Search): Document negative repeat count
+        (Bug#10507).
+
 2012-01-26  Glenn Morris  <rgm@gnu.org>
 
         * variables.texi (Using Lexical Binding):
diff --git a/doc/lispref/searching.texi b/doc/lispref/searching.texi
index 21481568276..3dc777897c1 100644
--- a/doc/lispref/searching.texi
+++ b/doc/lispref/searching.texi
@@ -49,7 +49,6 @@ This function searches forward from point for an exact match for
 @var{string}.  If successful, it sets point to the end of the occurrence
 found, and returns the new value of point.  If no match is found, the
 value and side effects depend on @var{noerror} (see below).
-@c Emacs 19 feature
 
 In the following example, point is initially at the beginning of the
 line.  Then @code{(search-forward "fox")} moves point after the last
@@ -91,18 +90,21 @@ The argument @var{noerror} only affects valid searches which fail to
 find a match.  Invalid arguments cause errors regardless of
 @var{noerror}.
 
-If @var{repeat} is supplied (it must be a positive number), then the
-search is repeated that many times (each time starting at the end of the
-previous time's match).  If these successive searches succeed, the
-function succeeds, moving point and returning its new value.  Otherwise
-the search fails, with results depending on the value of
-@var{noerror}, as described above.
+If @var{repeat} is a positive number @var{n}, it serves as a repeat
+count: the search is repeated @var{n} times, each time starting at the
+end of the previous time's match.  If these successive searches
+succeed, the function succeeds, moving point and returning its new
+value.  Otherwise the search fails, with results depending on the
+value of @var{noerror}, as described above.  If @var{repeat} is a
+negative number -@var{n}, it serves as a repeat count of @var{n} for a
+search in the opposite (backward) direction.
 @end deffn
 
 @deffn Command search-backward string &optional limit noerror repeat
 This function searches backward from point for @var{string}.  It is
-just like @code{search-forward} except that it searches backwards and
-leaves point at the beginning of the match.
+like @code{search-forward}, except that it searches backwards rather
+than forwards.  Backward searches leave point at the beginning of the
+match.
 @end deffn
 
 @deffn Command word-search-forward string &optional limit noerror repeat
diff --git a/src/ChangeLog b/src/ChangeLog
index 9d37a04da2c..7222cfb9dd4 100644
--- a/src/ChangeLog
+++ b/src/ChangeLog
@@ -1,3 +1,8 @@
+2012-01-26  Chong Yidong  <cyd@gnu.org>
+
+        * search.c (Fsearch_forward, Fsearch_backward): Document negative
+        repeat counts (Bug#10507).
+
 2012-01-26  Glenn Morris  <rgm@gnu.org>
 
         * lread.c (syms_of_lread): Doc fix.
diff --git a/src/search.c b/src/search.c
index 67323b3c6e7..55a6d893479 100644
--- a/src/search.c
+++ b/src/search.c
@@ -2181,7 +2181,9 @@ An optional second argument bounds the search; it is a buffer position.
 The match found must not extend before that position.
 Optional third argument, if t, means if fail just return nil (no error).
  If not nil and not t, position at limit of search and return nil.
-Optional fourth argument is repeat count--search for successive occurrences.
+Optional fourth argument COUNT, if non-nil, means to search for COUNT
+ successive occurrences.  If COUNT is negative, search forward,
+ instead of backward, for -COUNT occurrences.
 
 Search case-sensitivity is determined by the value of the variable
 `case-fold-search', which see.
@@ -2200,7 +2202,9 @@ The match found must not extend after that position.  A value of nil is
   equivalent to (point-max).
 Optional third argument, if t, means if fail just return nil (no error).
   If not nil and not t, move to limit of search and return nil.
-Optional fourth argument is repeat count--search for successive occurrences.
+Optional fourth argument COUNT, if non-nil, means to search for COUNT
+ successive occurrences.  If COUNT is negative, search backward,
+ instead of forward, for -COUNT occurrences.
 
 Search case-sensitivity is determined by the value of the variable
 `case-fold-search', which see.