diff --git a/lispref/searching.texi b/lispref/searching.texi index 1f4a82d3f1f..01d055c4a45 100644 --- a/lispref/searching.texi +++ b/lispref/searching.texi @@ -1486,12 +1486,13 @@ character of the buffer counts as 1.) write the entire match data, all at once. @defun match-data &optional integers reuse -This function returns a newly constructed list containing all the -information on what text the last search matched. Element zero is the -position of the beginning of the match for the whole expression; element -one is the position of the end of the match for the expression. The -next two elements are the positions of the beginning and end of the -match for the first subexpression, and so on. In general, element +This function returns a list of positions (markers or integers) that +record all the information on what text the last search matched. +Element zero is the position of the beginning of the match for the +whole expression; element one is the position of the end of the match +for the expression. The next two elements are the positions of the +beginning and end of the match for the first subexpression, and so on. +In general, element @ifnottex number 2@var{n} @end ifnottex @@ -1508,15 +1509,13 @@ number {\mathsurround=0pt $2n+1$} @end tex corresponds to @code{(match-end @var{n})}. -All the elements are markers or @code{nil} if matching was done on a -buffer and all are integers or @code{nil} if matching was done on a -string with @code{string-match}. If @var{integers} is -non-@code{nil}, then the elements are integers or @code{nil}, even if -matching was done on a buffer. In that case, the buffer itself is -appended as an additional element at the end of the list -to facilitate complete restoration of the match data. Also, -@code{match-beginning} and -@code{match-end} always return integers or @code{nil}. +Normally all the elements are markers or @code{nil}, but if +@var{integers} is non-@code{nil}, that means to use integers instead +of markers. (In that case, the buffer itself is appended as an +additional element at the end of the list, to facilitate complete +restoration of the match data.) If the last match was done on a +string with @code{string-match}, then integers are always used, +since markers can't point into a string. If @var{reuse} is non-@code{nil}, it should be a list. In that case, @code{match-data} stores the match data in @var{reuse}. That is, @@ -1524,8 +1523,8 @@ If @var{reuse} is non-@code{nil}, it should be a list. In that case, have the right length. If it is not long enough to contain the match data, it is extended. If it is too long, the length of @var{reuse} stays the same, but the elements that were not used are set to -@code{nil}. The purpose of this feature is to avoid producing too -much garbage, that would later have to be collected. +@code{nil}. The purpose of this feature is to reduce the need for +garbage collection. As always, there must be no possibility of intervening searches between the call to a search function and the call to @code{match-data} that is