Mercurial > emacs
comparison lispref/searching.texi @ 63153:286783f742e6
(Entire Match Data): Explain new `reseat' argument to
match-data and set-match-data.
author | Kim F. Storm <storm@cua.dk> |
---|---|
date | Wed, 08 Jun 2005 23:03:29 +0000 |
parents | ade1be8b63fd |
children | 202050ef8d08 173dee4e2611 |
comparison
equal
deleted
inserted
replaced
63152:3f80de0be046 | 63153:286783f742e6 |
---|---|
1483 @subsection Accessing the Entire Match Data | 1483 @subsection Accessing the Entire Match Data |
1484 | 1484 |
1485 The functions @code{match-data} and @code{set-match-data} read or | 1485 The functions @code{match-data} and @code{set-match-data} read or |
1486 write the entire match data, all at once. | 1486 write the entire match data, all at once. |
1487 | 1487 |
1488 @defun match-data &optional integers reuse | 1488 @defun match-data &optional integers reuse reseat |
1489 This function returns a list of positions (markers or integers) that | 1489 This function returns a list of positions (markers or integers) that |
1490 record all the information on what text the last search matched. | 1490 record all the information on what text the last search matched. |
1491 Element zero is the position of the beginning of the match for the | 1491 Element zero is the position of the beginning of the match for the |
1492 whole expression; element one is the position of the end of the match | 1492 whole expression; element one is the position of the end of the match |
1493 for the expression. The next two elements are the positions of the | 1493 for the expression. The next two elements are the positions of the |
1524 data, it is extended. If it is too long, the length of @var{reuse} | 1524 data, it is extended. If it is too long, the length of @var{reuse} |
1525 stays the same, but the elements that were not used are set to | 1525 stays the same, but the elements that were not used are set to |
1526 @code{nil}. The purpose of this feature is to reduce the need for | 1526 @code{nil}. The purpose of this feature is to reduce the need for |
1527 garbage collection. | 1527 garbage collection. |
1528 | 1528 |
1529 If @var{reseat} is non-@code{nil}, all markers on the @var{reuse} list | |
1530 are reseated to point to nowhere, and if the value is @code{evaporate}, | |
1531 the markers are put back on the free list. | |
1532 | |
1533 @strong{Warning:} When @code{evaporate} is specified for @var{reseat}, | |
1534 no other references to the markers on the @var{reuse} list; otherwise, | |
1535 Emacs may crash during the next garbage collection. | |
1536 | |
1529 As always, there must be no possibility of intervening searches between | 1537 As always, there must be no possibility of intervening searches between |
1530 the call to a search function and the call to @code{match-data} that is | 1538 the call to a search function and the call to @code{match-data} that is |
1531 intended to access the match data for that search. | 1539 intended to access the match data for that search. |
1532 | 1540 |
1533 @example | 1541 @example |
1539 #<marker at 17 in foo>) | 1547 #<marker at 17 in foo>) |
1540 @end group | 1548 @end group |
1541 @end example | 1549 @end example |
1542 @end defun | 1550 @end defun |
1543 | 1551 |
1544 @defun set-match-data match-list | 1552 @defun set-match-data match-list &optional reseat |
1545 This function sets the match data from the elements of @var{match-list}, | 1553 This function sets the match data from the elements of @var{match-list}, |
1546 which should be a list that was the value of a previous call to | 1554 which should be a list that was the value of a previous call to |
1547 @code{match-data}. (More precisely, anything that has the same format | 1555 @code{match-data}. (More precisely, anything that has the same format |
1548 will work.) | 1556 will work.) |
1549 | 1557 |
1550 If @var{match-list} refers to a buffer that doesn't exist, you don't get | 1558 If @var{match-list} refers to a buffer that doesn't exist, you don't get |
1551 an error; that sets the match data in a meaningless but harmless way. | 1559 an error; that sets the match data in a meaningless but harmless way. |
1560 | |
1561 If @var{reseat} is non-@code{nil}, all markers on the @var{match-list} list | |
1562 are reseated to point to nowhere, and if the value is @code{evaporate}, | |
1563 the markers are put back on the free list. | |
1564 | |
1565 @strong{Warning:} When @code{evaporate} is specified for @var{reseat}, | |
1566 no other references to the markers on the @var{match-list} list; otherwise, | |
1567 Emacs may crash during the next garbage collection. | |
1552 | 1568 |
1553 @findex store-match-data | 1569 @findex store-match-data |
1554 @code{store-match-data} is a semi-obsolete alias for @code{set-match-data}. | 1570 @code{store-match-data} is a semi-obsolete alias for @code{set-match-data}. |
1555 @end defun | 1571 @end defun |
1556 | 1572 |