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

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 145d2dbc4f5667c3099744149a1efc91058cb7f3..89174f3ca0ee0e86d89f72356ff00fc2ce685f5b 100644 (file)
--- 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 214815682761129d7e09a8e5a1340d74003681ce..3dc777897c1604fc804bec606494298a134e6235 100644 (file)
--- 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 9d37a04da2ca16980b7418660849a44ac06bfd0d..7222cfb9dd4a89960c03a743de3457ceec15b635 100644 (file)
--- 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 67323b3c6e7359342ce19dab55c9168a822dea3c..55a6d8934794b159f0b0714969c9d87ecbec3956 100644 (file)
--- 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.