> For the complete documentation index, see [llms.txt](https://emacs-lisp.ivory.cafe/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://emacs-lisp.ivory.cafe/suo-xie-ji-suo-xie-tuo-zhan/untitled/34.1-wen-ben-sou-suo.md).

# 34.1 文本搜索

这一小节介绍几个基础的搜索函数。这些函数可以交互性的使用。如果你交互性的使用这些函数，那么，这些函数会在交互的过程中提示被搜索的词语，并且它们的参数 limit 和 noerror 都默认为 nil，repeat 默认为 1。想要更详细的交互式用法，请查阅 GNU Emacs Manual 中的 搜索和替换章节。

如果当前缓冲区为多字节，那么这些搜索函数会返回多字节的搜索结果；如果是单字节，那返回的结果就是单字节。

Command: search-forward string \&optional limit noerror count\
  这个函数从当前位置点开始向前进行精确匹配。如果搜索到了，那么 Emacs 会立刻把当前位置点转移到咪表位置，然后返回位置点的新位置。如果没有查找到，那么返回值和副作用具体取决于 参数 noerror（下面有例子）。

下面这个例子里，初始位置点点初始在本行行首。在调用 (search-forward "fox") 之后，位置点会移到 ‘fox’ 的最后一个字母上：

```
---------- Buffer: foo ----------
∗The quick brown fox jumped over the lazy dog.
---------- Buffer: foo ----------

(search-forward "fox")
     ⇒ 20

---------- Buffer: foo ----------
The quick brown fox∗ jumped over the lazy dog.
---------- Buffer: foo ----------
```

limit 参数限定了搜索的范围，而且 limit 应在当前缓冲区的编辑范围之内。在限定范围外不会进行搜索。如果这个参数被忽略或者为 il，那么默认会把限定位置放在缓冲区的末尾。

当搜索失败时，具体会发生什么，取决于参数 noerror 的值。如果 noerror 值为 nil，那么搜索失败时会抛出 search-failed 错误。如果 noerror 值为 t，那么在搜索失败时，search-forward 会返回 nil，然后啥也不做。如果 noerror 既不是 nil，也不是 t，那么 search-forward 会把位置点移到上界，然后返回 nil。

参数 noerror 只会影响合法的搜索，在合法的搜索中失败是发挥作用。而不合法的参数抛出的错误和 noerror 没啥关系。

如果参数 count 时一个正的整数 n，那么函数会搜索 n 次；其中每次搜索都会从上一次成功搜索的位置开始新的搜索。如果每次搜索都成功，那么会这次函数调用就是成功的，并且会将位置点移到最新的搜索位置上。否则，称这次函数调用是失败的。而搜索失败了具体会发生什么，会取决于 noerror 的值。如果 count 是个负数 -n，那么搜索就会按照反方向进行 n 次。

Command: search-backward string \&optional limit noerror count\
  这个函数从当前位置点向前搜索字符串。这个函数看起来和 search-forward 非常像，只不过它的搜索方向是反过来的。反向搜索最后会把位置点放在匹配位置的开头。

Command: word-search-forward string \&optional limit neorror count\
  这个函数从当前位置点开始搜索目标单词。当它搜索成功时，它会把位置点放在匹配单词的末尾，然后返回位置点的位置。

单词匹配会将 string 当作单词序列，会在搜索的过程中忽略掉标点。这个函数会搜索直到出现能匹配的单词序列。而缓冲区的被搜索的单词需要时分隔开的（比如对 'ball' 的搜索并不会匹配 'balls'），不过所有的标点和空白都会别忽略（比如对 'ball boy' 的搜索可以匹配到 'ball. Boy'）。

在下面的这个例子里，我们假设位置点的初始位置在缓冲区的起始位置，那么当搜索结束时，会将位置点放到 'y' 和 '!' 之间。

```
---------- Buffer: foo ----------
∗He said "Please!  Find
the ball boy!"
---------- Buffer: foo ----------

(word-search-forward "Please find the ball, boy.")
     ⇒ 39

---------- Buffer: foo ----------
He said "Please!  Find
the ball boy∗!"
---------- Buffer: foo ----------
```

如果参数 limit 的值非nil，那么它的值必须要在当前缓冲区的编辑范围内。limit 参数指明了搜索的上确界。超出上确界的文本将不会被搜索。

如果参数 noerror 的值为 nil，那么当搜索不到时，函数会抛出一个 word-search-forward 错误。如果 noerror 的值为 t，那么函数会返回 nil，而不是抛出错误。如果 noerror 既不是 nil，也不是 t，那么最终会将位置点移到 limit 位置（或者是编辑范围的最后位置），然后返回 nil。

如果 count 是一个正整数，那么函数会明确进行多少次成功匹配。最终的位置点会停在最后一次成功匹配的末尾。如果 count 是一个负数，那么搜索就会反向进行，最后位置点会停留在最后一次成功匹配的开头。

在内部的实现中，word-search-forward 和相关的函数使用了 word-search-regexp 函数将 string 转换为忽略标点的相应正则匹配。

Command: word-search-forward-lax string \&optional limit noerror count\
  这个函数和 word-search-forward 差不多，不过这个函数不需要强制匹配到单词结尾。举个例子，用来搜索 'ball boy' 的函数可以匹配到 'ball boyee'， 但是不能匹配 'balls boy'。

Command: word-search-backward string \&optional limit noerror count\
  这个函数用于从当前位置点反向匹配字符串。这个函数简直和 word-search-forward 如出一辙。只不过这个函数的搜索方向是反过来的。而且正常情况下会把位置点停留在匹配位置的开头。

Command: word-search-backward-lax string \&optional limit noerror count\
  这个函数和 word-search-backward 差不多，和 word-search-backward-lax 也差不多，读者自己分析吧。（这个手册也太详细了，要是我的高等代数课本有这手册一半的详尽，也不至于上不了85）


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://emacs-lisp.ivory.cafe/suo-xie-ji-suo-xie-tuo-zhan/untitled/34.1-wen-ben-sou-suo.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.