mirror/emacs
1
0
Fork 0
mirror of https://git.savannah.gnu.org/git/emacs.git synced 2025-01-03 11:33:37 +00:00
Code Issues Releases Activity

Improve documentation of search functions

Browse Source 
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.
This commit is contained in:
Stephen Berman 2016-07-12 22:11:22 +02:00
parent 0a0144a2e1
commit 069fc05bd5
3 changed files with 137 additions and 63 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

67
doc/lispref/searching.texi
View File

@ -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}.
@deffn Command search-forward string &optional limit noerror repeat
@deffn 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 -@var{n}, 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
@var{n} 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 -@var{n}, the search is done @var{n} times in the opposite
(backward) direction.
@end deffn
@deffn Command search-backward string &optional limit noerror repeat
@deffn 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
@deffn Command word-search-forward string &optional limit noerror repeat
@deffn 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 non-@code{nil}, 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
@deffn Command word-search-forward-lax string &optional limit noerror repeat
@deffn 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
@deffn Command word-search-backward string &optional limit noerror repeat
@deffn 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
@deffn Command word-search-backward-lax string &optional limit noerror repeat
@deffn 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}.
@deffn Command re-search-forward regexp &optional limit noerror repeat
@deffn 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 non-@code{nil}, 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
@var{noerror}.
If @var{count} is a positive number @var{n}, the search is done
@var{n} 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 -@var{n}, 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
@deffn Command re-search-backward regexp &optional limit noerror repeat
@deffn 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.
@deffn Command posix-search-forward regexp &optional limit noerror repeat
@deffn 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
@deffn Command posix-search-backward regexp &optional limit noerror repeat
@deffn 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.

48
lisp/isearch.el
View File

@ -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

85
src/search.c
View File

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