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
@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,
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
HCoop / bpt / emacs.git / blobdiff