44.6.3 Accessing the Entire Match Data

The functions match-data and set-match-data read or write the entire match data, all at once.

Function: 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 corresponds to (match-beginning n); and element corresponds to (match-end n).

All the elements are markers or nil if matching was done on a buffer, and all are integers or nil if matching was done on a string with string-match. However, if the optional first argument integers is non-nil, always use integers (rather than markers) to represent buffer positions.

If the optional second argument reuse is a list, reuse it as part of the value. If reuse is long enough to hold all the values, and if integers is non-nil, no new lisp objects are created.

As always, there must be no possibility of intervening searches between the call to a search function and the call to match-data that is intended to access the match data for that search.

(match-data)
     ⇒  (#<marker at 9 in foo>
          #<marker at 17 in foo>
          #<marker at 13 in foo>
          #<marker at 17 in foo>)

Function: set-match-data match-list

This function sets the match data from the elements of match-list, which should be a list that was the value of a previous call to match-data.

If match-list refers to a buffer that doesn’t exist, you don’t get an error; that sets the match data in a meaningless but harmless way.

store-match-data is an alias for set-match-data.