diff options
Diffstat (limited to 'devdocs/elisp/string-search.html')
| -rw-r--r-- | devdocs/elisp/string-search.html | 48 |
1 files changed, 48 insertions, 0 deletions
diff --git a/devdocs/elisp/string-search.html b/devdocs/elisp/string-search.html new file mode 100644 index 00000000..21ea652f --- /dev/null +++ b/devdocs/elisp/string-search.html @@ -0,0 +1,48 @@ + <h3 class="section">Searching for Strings</h3> <p>These are the primitive functions for searching through the text in a buffer. They are meant for use in programs, but you may call them interactively. If you do so, they prompt for the search string; the arguments <var>limit</var> and <var>noerror</var> are <code>nil</code>, and <var>repeat</var> is 1. For more details on interactive searching, see <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Search.html#Search">Searching and Replacement</a> in <cite>The GNU Emacs Manual</cite>. </p> <p>These search functions convert the search string to multibyte if the buffer is multibyte; they convert the search string to unibyte if the buffer is unibyte. See <a href="text-representations">Text Representations</a>. </p> <dl> <dt id="search-forward">Command: <strong>search-forward</strong> <em>string &optional limit noerror count</em> +</dt> <dd> +<p>This function searches forward from point for an exact match for <var>string</var>. If successful, it sets point to the end of the occurrence found, and returns the new value of point. If no match is found, the value and side effects depend on <var>noerror</var> (see below). </p> <p>In the following example, point is initially at the beginning of the line. Then <code>(search-forward "fox")</code> moves point after the last letter of ‘<samp>fox</samp>’: </p> <div class="example"> <pre class="example">---------- Buffer: foo ---------- +∗The quick brown fox jumped over the lazy dog. +---------- Buffer: foo ---------- +</pre> + +<pre class="example">(search-forward "fox") + ⇒ 20 + +---------- Buffer: foo ---------- +The quick brown fox∗ jumped over the lazy dog. +---------- Buffer: foo ---------- +</pre> +</div> <p>The argument <var>limit</var> specifies the bound to the search, and should be a position in the current buffer. No match extending after that position is accepted. If <var>limit</var> is omitted or <code>nil</code>, it defaults to the end of the accessible portion of the buffer. </p> <p>What happens when the search fails depends on the value of <var>noerror</var>. If <var>noerror</var> is <code>nil</code>, a <code>search-failed</code> error is signaled. If <var>noerror</var> is <code>t</code>, <code>search-forward</code> returns <code>nil</code> and does nothing. If <var>noerror</var> is neither <code>nil</code> nor <code>t</code>, then <code>search-forward</code> moves point to the upper bound and returns <code>nil</code>. </p> <p>The argument <var>noerror</var> only affects valid searches which fail to find a match. Invalid arguments cause errors regardless of <var>noerror</var>. </p> <p>If <var>count</var> is a positive number <var>n</var>, the search is done <var>n</var> times; each successive search starts at the end of the previous match. If all these successive searches succeed, the function call succeeds, moving point and returning its new value. Otherwise the function call fails, with results depending on the value of <var>noerror</var>, as described above. If <var>count</var> is a negative number -<var>n</var>, the search is done <var>n</var> times in the opposite (backward) direction. </p> +</dd> +</dl> <dl> <dt id="search-backward">Command: <strong>search-backward</strong> <em>string &optional limit noerror count</em> +</dt> <dd><p>This function searches backward from point for <var>string</var>. It is like <code>search-forward</code>, except that it searches backwards rather than forwards. Backward searches leave point at the beginning of the match. </p></dd> +</dl> <dl> <dt id="word-search-forward">Command: <strong>word-search-forward</strong> <em>string &optional limit noerror count</em> +</dt> <dd> +<p>This function searches forward from point for a word match for <var>string</var>. If it finds a match, it sets point to the end of the match found, and returns the new value of point. </p> <p>Word matching regards <var>string</var> as a sequence of words, disregarding punctuation that separates them. It searches the buffer for the same sequence of words. Each word must be distinct in the buffer (searching for the word ‘<samp>ball</samp>’ does not match the word ‘<samp>balls</samp>’), but the details of punctuation and spacing are ignored (searching for ‘<samp>ball boy</samp>’ does match ‘<samp>ball. Boy!</samp>’). </p> <p>In this example, point is initially at the beginning of the buffer; the search leaves it between the ‘<samp>y</samp>’ and the ‘<samp>!</samp>’. </p> <div class="example"> <pre class="example">---------- Buffer: foo ---------- +∗He said "Please! Find +the ball boy!" +---------- Buffer: foo ---------- +</pre> + +<pre class="example">(word-search-forward "Please find the ball, boy.") + ⇒ 39 + +---------- Buffer: foo ---------- +He said "Please! Find +the ball boy∗!" +---------- Buffer: foo ---------- +</pre> +</div> <p>If <var>limit</var> is non-<code>nil</code>, it must be a position in the current buffer; it specifies the upper bound to the search. The match found must not extend after that position. </p> <p>If <var>noerror</var> is <code>nil</code>, then <code>word-search-forward</code> signals an error if the search fails. If <var>noerror</var> is <code>t</code>, then it returns <code>nil</code> instead of signaling an error. If <var>noerror</var> is neither <code>nil</code> nor <code>t</code>, it moves point to <var>limit</var> (or the end of the accessible portion of the buffer) and returns <code>nil</code>. </p> <p>If <var>count</var> is a positive number, it specifies how many successive occurrences to search for. Point is positioned at the end of the last match. If <var>count</var> is a negative number, the search is backward and point is positioned at the beginning of the last match. </p> <p>Internally, <code>word-search-forward</code> and related functions use the function <code>word-search-regexp</code> to convert <var>string</var> to a regular expression that ignores punctuation. </p> +</dd> +</dl> <dl> <dt id="word-search-forward-lax">Command: <strong>word-search-forward-lax</strong> <em>string &optional limit noerror count</em> +</dt> <dd><p>This command is identical to <code>word-search-forward</code>, except that the beginning or the end of <var>string</var> need not match a word boundary, unless <var>string</var> begins or ends in whitespace. For instance, searching for ‘<samp>ball boy</samp>’ matches ‘<samp>ball boyee</samp>’, but does not match ‘<samp>balls boy</samp>’. </p></dd> +</dl> <dl> <dt id="word-search-backward">Command: <strong>word-search-backward</strong> <em>string &optional limit noerror count</em> +</dt> <dd><p>This function searches backward from point for a word match to <var>string</var>. This function is just like <code>word-search-forward</code> except that it searches backward and normally leaves point at the beginning of the match. </p></dd> +</dl> <dl> <dt id="word-search-backward-lax">Command: <strong>word-search-backward-lax</strong> <em>string &optional limit noerror count</em> +</dt> <dd><p>This command is identical to <code>word-search-backward</code>, except that the beginning or the end of <var>string</var> need not match a word boundary, unless <var>string</var> begins or ends in whitespace. </p></dd> +</dl><div class="_attribution"> + <p class="_attribution-p"> + Copyright © 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/String-Search.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/String-Search.html</a> + </p> +</div> |