[Emacs-diffs] emacs-25 069fc05: Improve documentation of search functions

[Stephen Berman]

branch: emacs-25
commit 069fc05bd5fabdd5971e2c5230a8586248fb7f38
Author: Stephen Berman <address@hidden>
Commit: Stephen Berman <address@hidden>

    Improve documentation of search functions
    
    Make the documentation of the search functions more accurate,
    complete, and uniform; in particular, extend the description of
    the effect when the 'count' parameter is a negative number to all
    of these functions.
    
    * src/search.c (Fsearch_backward, Fsearch_forward)
    (Fre_search_backward, Fre_search_forward)
    (Fposix_search_backward, Fposix_search_forward):
    * lisp/isearch.el (word-search-backward, word-search-forward)
    (word-search-backward-lax, word-search-forward-lax): Improve doc
    strings as described above.
    
    * doc/lispref/searching.texi (String Search, Regexp Search)
    (POSIX Regexps): Use 'count' instead of 'repeat' as the name of
    the fourth parameter of the *-search-{forward,backward} functions
    and improve documentation as described above.
---
 doc/lispref/searching.texi |   67 ++++++++++++++++++++--------------
 lisp/isearch.el            |   48 +++++++++++++++++++------
 src/search.c               |   85 ++++++++++++++++++++++++++++++--------------
 3 files changed, 137 insertions(+), 63 deletions(-)

diff --git a/doc/lispref/searching.texi b/doc/lispref/searching.texi
index 1243d72..acf3d0e 100644
--- a/doc/lispref/searching.texi
+++ b/doc/lispref/searching.texi
@@ -44,7 +44,7 @@ Searching and Replacement, emacs, The GNU Emacs Manual}.
 buffer is multibyte; they convert the search string to unibyte if the
 buffer is unibyte.  @xref{Text Representations}.
 
address@hidden Command search-forward string &optional limit noerror repeat
address@hidden Command search-forward string &optional limit noerror count
 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
@@ -95,24 +95,24 @@ 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 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 address@hidden, it serves as a repeat count of @var{n} for a
-search in the opposite (backward) direction.
+If @var{count} is a positive number @var{n}, the search is done
address@hidden times; each successive search starts at the end of the
+previous match.  If all these successive searches succeed, the
+function call succeeds, moving point and returning its new value.
+Otherwise the function call fails, with results depending on the value
+of @var{noerror}, as described above.  If @var{count} is a negative
+number address@hidden, the search is done @var{n} times in the opposite
+(backward) direction.
 @end deffn
 
address@hidden Command search-backward string &optional limit noerror repeat
address@hidden Command search-backward string &optional limit noerror count
 This function searches backward from point for @var{string}.  It is
 like @code{search-forward}, except that it searches backwards rather
 than forwards.  Backward searches leave point at the beginning of the
 match.
 @end deffn
 
address@hidden Command word-search-forward string &optional limit noerror repeat
address@hidden Command word-search-forward string &optional limit noerror count
 This function searches forward from point for a word match for
 @var{string}.  If it finds a match, it sets point to the end of the
 match found, and returns the new value of point.
@@ -156,8 +156,10 @@ returns @code{nil} instead of signaling an error.  If 
@var{noerror} is
 neither @code{nil} nor @code{t}, it moves point to @var{limit} (or the
 end of the accessible portion of the buffer) and returns @code{nil}.
 
-If @var{repeat} is address@hidden, then the search is repeated that many
-times.  Point is positioned at the end of the last match.
+If @var{count} is a positive number, it specifies how many successive
+occurrences to search for.  Point is positioned at the end of the last
+match.  If @var{count} is a negative number, the search is backward
+and point is positioned at the beginning of the last match.
 
 @findex word-search-regexp
 Internally, @code{word-search-forward} and related functions use the
@@ -165,7 +167,7 @@ function @code{word-search-regexp} to convert @var{string} 
to a
 regular expression that ignores punctuation.
 @end deffn
 
address@hidden Command word-search-forward-lax string &optional limit noerror 
repeat
address@hidden Command word-search-forward-lax string &optional limit noerror 
count
 This command is identical to @code{word-search-forward}, except that
 the beginning or the end of @var{string} need not match a word
 boundary, unless @var{string} begins or ends in whitespace.
@@ -173,14 +175,14 @@ For instance, searching for @samp{ball boy} matches 
@samp{ball boyee},
 but does not match @samp{balls boy}.
 @end deffn
 
address@hidden Command word-search-backward string &optional limit noerror 
repeat
address@hidden Command word-search-backward string &optional limit noerror count
 This function searches backward from point for a word match to
 @var{string}.  This function is just like @code{word-search-forward}
 except that it searches backward and normally leaves point at the
 beginning of the match.
 @end deffn
 
address@hidden Command word-search-backward-lax string &optional limit noerror 
repeat
address@hidden Command word-search-backward-lax string &optional limit noerror 
count
 This command is identical to @code{word-search-backward}, except that
 the beginning or the end of @var{string} need not match a word
 boundary, unless @var{string} begins or ends in whitespace.
@@ -1005,7 +1007,7 @@ only the search functions useful in programs.  The 
principal one is
 the buffer is multibyte; they convert the regular expression to unibyte
 if the buffer is unibyte.  @xref{Text Representations}.
 
address@hidden Command re-search-forward regexp &optional limit noerror repeat
address@hidden Command re-search-forward regexp &optional limit noerror count
 This function searches forward in the current buffer for a string of
 text that is matched by the regular expression @var{regexp}.  The
 function skips over any amount of text that is not matched by
@@ -1014,14 +1016,12 @@ It returns the new value of point.
 
 If @var{limit} is address@hidden, it must be a position in the current
 buffer.  It specifies the upper bound to the search.  No match
-extending after that position is accepted.
+extending after that position is accepted.  If @var{limit} is omitted
+or @code{nil}, it defaults to the end of the accessible portion of the
+buffer.
 
-If @var{repeat} is supplied, it must be a positive number; the search
-is repeated that many times; each repetition starts at the end of the
-previous match.  If all these successive searches succeed, the search
-succeeds, moving point and returning its new value.  Otherwise the
-search fails.  What @code{re-search-forward} does when the search
-fails depends on the value of @var{noerror}:
+What @code{re-search-forward} does when the search fails depends on
+the value of @var{noerror}:
 
 @table @asis
 @item @code{nil}
@@ -1033,6 +1033,19 @@ Move point to @var{limit} (or the end of the accessible 
portion of the
 buffer) and return @code{nil}.
 @end table
 
+The argument @var{noerror} only affects valid searches which fail to
+find a match.  Invalid arguments cause errors regardless of
address@hidden
+
+If @var{count} is a positive number @var{n}, the search is done
address@hidden times; each successive search starts at the end of the
+previous match.  If all these successive searches succeed, the
+function call succeeds, moving point and returning its new value.
+Otherwise the function call fails, with results depending on the value
+of @var{noerror}, as described above.  If @var{count} is a negative
+number address@hidden, the search is done @var{n} times in the opposite
+(backward) direction.
+
 In the following example, point is initially before the @samp{T}.
 Evaluating the search call moves point to the end of that line (between
 the @samp{t} of @samp{hat} and the newline).
@@ -1057,7 +1070,7 @@ comes back" twice.
 @end example
 @end deffn
 
address@hidden Command re-search-backward regexp &optional limit noerror repeat
address@hidden Command re-search-backward regexp &optional limit noerror count
 This function searches backward in the current buffer for a string of
 text that is matched by the regular expression @var{regexp}, leaving
 point at the beginning of the first text found.
@@ -1228,13 +1241,13 @@ non-greedy repetition operators (@pxref{Regexp Special, 
non-greedy}).
 This is because POSIX backtracking conflicts with the semantics of
 non-greedy repetition.
 
address@hidden Command posix-search-forward regexp &optional limit noerror 
repeat
address@hidden Command posix-search-forward regexp &optional limit noerror count
 This is like @code{re-search-forward} except that it performs the full
 backtracking specified by the POSIX standard for regular expression
 matching.
 @end deffn
 
address@hidden Command posix-search-backward regexp &optional limit noerror 
repeat
address@hidden Command posix-search-backward regexp &optional limit noerror 
count
 This is like @code{re-search-backward} except that it performs the full
 backtracking specified by the POSIX standard for regular expression
 matching.
diff --git a/lisp/isearch.el b/lisp/isearch.el
index 7360a0b..a972476 100644
--- a/lisp/isearch.el
+++ b/lisp/isearch.el
@@ -1624,10 +1624,17 @@ Used in `word-search-forward', `word-search-backward',
   "Search backward from point for STRING, ignoring differences in punctuation.
 Set point to the beginning of the occurrence found, and return point.
 An optional second argument bounds the search; it is a buffer position.
-The match found must not extend before that position.
+  The match found must not begin before that position.  A value of nil
+  means search to the beginning of the accessible portion of the buffer.
 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.
+  If not nil and not t, position at limit of search and return nil.
+Optional fourth argument COUNT, if a positive number, means to search
+  for COUNT successive occurrences.  If COUNT is negative, search
+  forward, instead of backward, for -COUNT occurrences.  A value of
+  nil means the same as 1.
+With COUNT positive, the match found is the COUNTth to last one (or
+  last, if COUNT is 1 or nil) in the buffer located entirely before
+  the origin of the search; correspondingly with COUNT negative.
 
 Relies on the function `word-search-regexp' to convert a sequence
 of words in STRING to a regexp used to search words without regard
@@ -1641,10 +1648,17 @@ has no effect on it."
   "Search forward from point for STRING, ignoring differences in punctuation.
 Set point to the end of the occurrence found, and return point.
 An optional second argument bounds the search; it is a buffer position.
-The match found must not extend after that position.
+  The match found must not end after that position.  A value of nil
+  means search to the end of the accessible portion of the buffer.
 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 a positive number, means to search
+  for COUNT successive occurrences.  If COUNT is negative, search
+  backward, instead of forward, for -COUNT occurrences.  A value of
+  nil means the same as 1.
+With COUNT positive, the match found is the COUNTth one (or first,
+  if COUNT is 1 or nil) in the buffer located entirely after the
+  origin of the search; correspondingly with COUNT negative.
 
 Relies on the function `word-search-regexp' to convert a sequence
 of words in STRING to a regexp used to search words without regard
@@ -1662,10 +1676,17 @@ Unlike `word-search-backward', the end of STRING need 
not match a word
 boundary, unless STRING ends in whitespace.
 
 An optional second argument bounds the search; it is a buffer position.
-The match found must not extend before that position.
+  The match found must not begin before that position.  A value of nil
+  means search to the beginning of the accessible portion of the buffer.
 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.
+  If not nil and not t, position at limit of search and return nil.
+Optional fourth argument COUNT, if a positive number, means to search
+  for COUNT successive occurrences.  If COUNT is negative, search
+  forward, instead of backward, for -COUNT occurrences.  A value of
+  nil means the same as 1.
+With COUNT positive, the match found is the COUNTth to last one (or
+  last, if COUNT is 1 or nil) in the buffer located entirely before
+  the origin of the search; correspondingly with COUNT negative.
 
 Relies on the function `word-search-regexp' to convert a sequence
 of words in STRING to a regexp used to search words without regard
@@ -1683,10 +1704,17 @@ Unlike `word-search-forward', the end of STRING need 
not match a word
 boundary, unless STRING ends in whitespace.
 
 An optional second argument bounds the search; it is a buffer position.
-The match found must not extend after that position.
+  The match found must not end after that position.  A value of nil
+  means search to the end of the accessible portion of the buffer.
 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 a positive number, means to search
+  for COUNT successive occurrences.  If COUNT is negative, search
+  backward, instead of forward, for -COUNT occurrences.  A value of
+  nil means the same as 1.
+With COUNT positive, the match found is the COUNTth one (or first,
+  if COUNT is 1 or nil) in the buffer located entirely after the
+  origin of the search; correspondingly with COUNT negative.
 
 Relies on the function `word-search-regexp' to convert a sequence
 of words in STRING to a regexp used to search words without regard
diff --git a/src/search.c b/src/search.c
index bcdd8f1..5c949ad 100644
--- a/src/search.c
+++ b/src/search.c
@@ -2164,12 +2164,17 @@ DEFUN ("search-backward", Fsearch_backward, 
Ssearch_backward, 1, 4,
        doc: /* Search backward from point for STRING.
 Set point to the beginning of the occurrence found, and return point.
 An optional second argument bounds the search; it is a buffer position.
-The match found must not extend before that position.
+  The match found must not begin before that position.  A value of nil
+  means search to the beginning of the accessible portion of the buffer.
 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 COUNT, if non-nil, means to search for COUNT
- successive occurrences.  If COUNT is negative, search forward,
- instead of backward, for -COUNT occurrences.
+  If not nil and not t, position at limit of search and return nil.
+Optional fourth argument COUNT, if a positive number, means to search
+  for COUNT successive occurrences.  If COUNT is negative, search
+  forward, instead of backward, for -COUNT occurrences.  A value of
+  nil means the same as 1.
+With COUNT positive, the match found is the COUNTth to last one (or
+  last, if COUNT is 1 or nil) in the buffer located entirely before
+  the origin of the search; correspondingly with COUNT negative.
 
 Search case-sensitivity is determined by the value of the variable
 `case-fold-search', which see.
@@ -2184,13 +2189,17 @@ DEFUN ("search-forward", Fsearch_forward, 
Ssearch_forward, 1, 4, "MSearch: ",
        doc: /* Search forward from point for STRING.
 Set point to the end of the occurrence found, and return point.
 An optional second argument bounds the search; it is a buffer position.
-The match found must not extend after that position.  A value of nil is
-  equivalent to (point-max).
+  The match found must not end after that position.  A value of nil
+  means search to the end of the accessible portion of the buffer.
 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 COUNT, if non-nil, means to search for COUNT
- successive occurrences.  If COUNT is negative, search backward,
- instead of forward, for -COUNT occurrences.
+Optional fourth argument COUNT, if a positive number, means to search
+  for COUNT successive occurrences.  If COUNT is negative, search
+  backward, instead of forward, for -COUNT occurrences.  A value of
+  nil means the same as 1.
+With COUNT positive, the match found is the COUNTth one (or first,
+  if COUNT is 1 or nil) in the buffer located entirely after the
+  origin of the search; correspondingly with COUNT negative.
 
 Search case-sensitivity is determined by the value of the variable
 `case-fold-search', which see.
@@ -2204,14 +2213,19 @@ See also the functions `match-beginning', `match-end' 
and `replace-match'.  */)
 DEFUN ("re-search-backward", Fre_search_backward, Sre_search_backward, 1, 4,
        "sRE search backward: ",
        doc: /* Search backward from point for match for regular expression 
REGEXP.
-Set point to the beginning of the match, and return point.
-The match found is the one starting last in the buffer
-and yet ending before the origin of the search.
+Set point to the beginning of the occurrence found, and return point.
 An optional second argument bounds the search; it is a buffer position.
-The match found must start at or after that position.
+  The match found must not begin before that position.  A value of nil
+  means search to the beginning of the accessible portion of the buffer.
 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.
+  If not nil and not t, position at limit of search and return nil.
+Optional fourth argument COUNT, if a positive number, means to search
+  for COUNT successive occurrences.  If COUNT is negative, search
+  forward, instead of backward, for -COUNT occurrences.  A value of
+  nil means the same as 1.
+With COUNT positive, the match found is the COUNTth to last one (or
+  last, if COUNT is 1 or nil) in the buffer located entirely before
+  the origin of the search; correspondingly with COUNT negative.
 
 Search case-sensitivity is determined by the value of the variable
 `case-fold-search', which see.
@@ -2228,10 +2242,17 @@ DEFUN ("re-search-forward", Fre_search_forward, 
Sre_search_forward, 1, 4,
        doc: /* Search forward from point for regular expression REGEXP.
 Set point to the end of the occurrence found, and return point.
 An optional second argument bounds the search; it is a buffer position.
-The match found must not extend after that position.
+  The match found must not end after that position.  A value of nil
+  means search to the end of the accessible portion of the buffer.
 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 a positive number, means to search
+  for COUNT successive occurrences.  If COUNT is negative, search
+  backward, instead of forward, for -COUNT occurrences.  A value of
+  nil means the same as 1.
+With COUNT positive, the match found is the COUNTth one (or first,
+  if COUNT is 1 or nil) in the buffer located entirely after the
+  origin of the search; correspondingly with COUNT negative.
 
 Search case-sensitivity is determined by the value of the variable
 `case-fold-search', which see.
@@ -2247,14 +2268,19 @@ DEFUN ("posix-search-backward", Fposix_search_backward, 
Sposix_search_backward,
        "sPosix search backward: ",
        doc: /* Search backward from point for match for regular expression 
REGEXP.
 Find the longest match in accord with Posix regular expression rules.
-Set point to the beginning of the match, and return point.
-The match found is the one starting last in the buffer
-and yet ending before the origin of the search.
+Set point to the beginning of the occurrence found, and return point.
 An optional second argument bounds the search; it is a buffer position.
-The match found must start at or after that position.
+  The match found must not begin before that position.  A value of nil
+  means search to the beginning of the accessible portion of the buffer.
 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.
+  If not nil and not t, position at limit of search and return nil.
+Optional fourth argument COUNT, if a positive number, means to search
+  for COUNT successive occurrences.  If COUNT is negative, search
+  forward, instead of backward, for -COUNT occurrences.  A value of
+  nil means the same as 1.
+With COUNT positive, the match found is the COUNTth to last one (or
+  last, if COUNT is 1 or nil) in the buffer located entirely before
+  the origin of the search; correspondingly with COUNT negative.
 
 Search case-sensitivity is determined by the value of the variable
 `case-fold-search', which see.
@@ -2272,10 +2298,17 @@ DEFUN ("posix-search-forward", Fposix_search_forward, 
Sposix_search_forward, 1,
 Find the longest match in accord with Posix regular expression rules.
 Set point to the end of the occurrence found, and return point.
 An optional second argument bounds the search; it is a buffer position.
-The match found must not extend after that position.
+  The match found must not end after that position.  A value of nil
+  means search to the end of the accessible portion of the buffer.
 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 a positive number, means to search
+  for COUNT successive occurrences.  If COUNT is negative, search
+  backward, instead of forward, for -COUNT occurrences.  A value of
+  nil means the same as 1.
+With COUNT positive, the match found is the COUNTth one (or first,
+  if COUNT is 1 or nil) in the buffer located entirely after the
+  origin of the search; correspondingly with COUNT negative.
 
 Search case-sensitivity is determined by the value of the variable
 `case-fold-search', which see.