new repository

1 files changed, 59 insertions, 0 deletions

diff --git a/devdocs/elisp/simple-match-data.html b/devdocs/elisp/simple-match-data.html
new file mode 100644
index 00000000..fad559e3
--- /dev/null
+++ b/devdocs/elisp/simple-match-data.html
@@ -0,0 +1,59 @@
+ <h4 class="subsection">Simple Match Data Access</h4> <p>This section explains how to use the match data to find out what was matched by the last search or match operation, if it succeeded. </p> <p>You can ask about the entire matching text, or about a particular parenthetical subexpression of a regular expression. The <var>count</var> argument in the functions below specifies which. If <var>count</var> is zero, you are asking about the entire match. If <var>count</var> is positive, it specifies which subexpression you want. </p> <p>Recall that the subexpressions of a regular expression are those expressions grouped with escaped parentheses, ‘<samp>\(…\)</samp>’. The <var>count</var>th subexpression is found by counting occurrences of ‘<samp>\(</samp>’ from the beginning of the whole regular expression. The first subexpression is numbered 1, the second 2, and so on. Only regular expressions can have subexpressions—after a simple string search, the only information available is about the entire match. </p> <p>Every successful search sets the match data. Therefore, you should query the match data immediately after searching, before calling any other function that might perform another search. Alternatively, you may save and restore the match data (see <a href="saving-match-data">Saving Match Data</a>) around the call to functions that could perform another search. Or use the functions that explicitly do not modify the match data; e.g., <code>string-match-p</code>. </p> <p>A search which fails may or may not alter the match data. In the current implementation, it does not, but we may change it in the future. Don’t try to rely on the value of the match data after a failing search. </p> <dl> <dt id="match-string">Function: <strong>match-string</strong> <em>count &amp;optional in-string</em>
+</dt> <dd>
+<p>This function returns, as a string, the text matched in the last search or match operation. It returns the entire text if <var>count</var> is zero, or just the portion corresponding to the <var>count</var>th parenthetical subexpression, if <var>count</var> is positive. </p> <p>If the last such operation was done against a string with <code>string-match</code>, then you should pass the same string as the argument <var>in-string</var>. After a buffer search or match, you should omit <var>in-string</var> or pass <code>nil</code> for it; but you should make sure that the current buffer when you call <code>match-string</code> is the one in which you did the searching or matching. Failure to follow this advice will lead to incorrect results. </p> <p>The value is <code>nil</code> if <var>count</var> is out of range, or for a subexpression inside a ‘<samp>\|</samp>’ alternative that wasn’t used or a repetition that repeated zero times. </p>
+</dd>
+</dl> <dl> <dt id="match-string-no-properties">Function: <strong>match-string-no-properties</strong> <em>count &amp;optional in-string</em>
+</dt> <dd><p>This function is like <code>match-string</code> except that the result has no text properties. </p></dd>
+</dl> <dl> <dt id="match-beginning">Function: <strong>match-beginning</strong> <em>count</em>
+</dt> <dd>
+<p>If the last regular expression search found a match, this function returns the position of the start of the matching text or of a subexpression of it. </p> <p>If <var>count</var> is zero, then the value is the position of the start of the entire match. Otherwise, <var>count</var> specifies a subexpression in the regular expression, and the value of the function is the starting position of the match for that subexpression. </p> <p>The value is <code>nil</code> for a subexpression inside a ‘<samp>\|</samp>’ alternative that wasn’t used or a repetition that repeated zero times. </p>
+</dd>
+</dl> <dl> <dt id="match-end">Function: <strong>match-end</strong> <em>count</em>
+</dt> <dd><p>This function is like <code>match-beginning</code> except that it returns the position of the end of the match, rather than the position of the beginning. </p></dd>
+</dl> <p>Here is an example of using the match data, with a comment showing the positions within the text: </p> <div class="example"> <pre class="example">(string-match "\\(qu\\)\\(ick\\)"
+              "The quick fox jumped quickly.")
+              ;0123456789
+     ⇒ 4
+</pre>
+
+<pre class="example">(match-string 0 "The quick fox jumped quickly.")
+     ⇒ "quick"
+(match-string 1 "The quick fox jumped quickly.")
+     ⇒ "qu"
+(match-string 2 "The quick fox jumped quickly.")
+     ⇒ "ick"
+</pre>
+
+<pre class="example">(match-beginning 1)       ; <span class="roman">The beginning of the match</span>
+     ⇒ 4                 ;   <span class="roman">with ‘<samp>qu</samp>’ is at index 4.</span>
+</pre>
+
+<pre class="example">(match-beginning 2)       ; <span class="roman">The beginning of the match</span>
+     ⇒ 6                 ;   <span class="roman">with ‘<samp>ick</samp>’ is at index 6.</span>
+</pre>
+
+<pre class="example">(match-end 1)             ; <span class="roman">The end of the match</span>
+     ⇒ 6                 ;   <span class="roman">with ‘<samp>qu</samp>’ is at index 6.</span>
+
+(match-end 2)             ; <span class="roman">The end of the match</span>
+     ⇒ 9                 ;   <span class="roman">with ‘<samp>ick</samp>’ is at index 9.</span>
+</pre>
+</div> <p>Here is another example. Point is initially located at the beginning of the line. Searching moves point to between the space and the word ‘<samp>in</samp>’. The beginning of the entire match is at the 9th character of the buffer (‘<samp>T</samp>’), and the beginning of the match for the first subexpression is at the 13th character (‘<samp>c</samp>’). </p> <div class="example"> <pre class="example">(list
+  (re-search-forward "The \\(cat \\)")
+  (match-beginning 0)
+  (match-beginning 1))
+    ⇒ (17 9 13)
+</pre>
+
+<pre class="example">---------- Buffer: foo ----------
+I read "The cat ∗in the hat comes back" twice.
+        ^   ^
+        9  13
+---------- Buffer: foo ----------
+</pre>
+</div> <p>(In this case, the index returned is a buffer position; the first character of the buffer counts as 1.) </p><div class="_attribution">
+  <p class="_attribution-p">
+    Copyright &copy; 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br>
+    <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Simple-Match-Data.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Simple-Match-Data.html</a>
+  </p>
+</div>