Rustdoc 搜索

在搜索栏中输入内容会立即搜索可用的文档，匹配项的名称和路径，或函数的近似类型签名。

按名称搜索

要按项目名称（项目包括模块、类型、特性、函数和宏）搜索，请写入其名称或路径。作为一种特殊情况，通常用 :: 双冒号分隔的路径部分可以改为用空格分隔。例如

• vec new 和 vec::new 都将函数 std::vec::Vec::new 显示为结果。
• vec、vec vec、std::vec 和 std::vec::Vec 都将结构体 std::vec::Vec 本身包含在结果中（除了最后一个，其他都还将模块包含在结果中）。

作为快速减少结果列表的方法，搜索输入框下方有一个下拉选择器，标记为“Results in [std]”。单击它可以更改要搜索的 crate。

Rustdoc 使用模糊匹配函数来容忍拼写错误，但这基于输入的名称的长度，因此一个很好的例子是 HahsMap。为了避免这种情况，请用引号将项目括起来，搜索 "HahsMap"（在本例中，将不会返回任何结果）。

按名称搜索界面中的选项卡

事实上，再次以 HahsMap 为例，它会告诉您默认情况下您正在使用“In Names”，但也在 crate 下拉列表下方列出了另外两个选项卡：“In Parameters”和“In Return Types”。

这两个选项卡是函数列表，定义在与搜索最匹配的类型上（对于 HahsMap，它会大声自动纠正为 hashmap）。只有在找不到与字面量匹配的内容时，才会启动此自动纠正。

这些选项卡不仅仅是方法。例如，在 alloc crate 中搜索 Layout 也会列出接受布局的函数，即使它们是 allocator 或 free 函数的方法。

按类型签名搜索函数

如果您更具体地知道要查找的函数的作用，Rustdoc 可以同时在参数和返回值中搜索多个类型。多个参数用 , 逗号分隔，返回值写在 -> 箭头之后。

在更详细地描述语法之前，这里有一些标准库的示例搜索以及结果列表中包含的函数

类型搜索的工作原理

在复杂的基于类型的搜索中，Rustdoc 始终将每个项目的名称视为字面量。如果使用了名称，但文档中没有任何内容与单个项目匹配，例如拼写错误的 uize -> vec 搜索，则项目 uize 被视为泛型类型参数（导致 vec::from 和其他泛型 vec 构造函数）。

在决定哪些项目是类型参数，哪些是实际类型之后，它会通过匹配函数参数（写在 -> 之前）和返回类型（写在 -> 之后）来进行搜索。类型匹配与顺序无关，并且允许从查询中省略项目，但是查询中存在的项目必须存在于函数中才能匹配。self 参数的处理方式与任何其他参数相同，Self 会解析为底层类型的名称。

函数签名搜索可以查询泛型，用尖括号括起来，如果类型参数与特性不匹配，特性将像搜索引擎中的类型一样被规范化。例如，签名 fn my_function<I: Iterator<Item=u32>>(input: I) -> usize 的函数可以使用以下查询匹配

• Iterator<Item=u32> -> usize
• Iterator<u32> -> usize（您可以省略 Item= 部分）
• Iterator -> usize（您可以完全省略 iterator 的泛型）
• T -> usize（您可以使用泛型参数匹配）

除了最后一个查询不会匹配 dyn Iterator，因为那不是类型参数，以上每个查询都逐渐宽松。

如果绑定有多个关联类型，指定名称允许您选择要匹配的类型。如果未指定名称，则查询将匹配其中任何一个。例如，

#![allow(unused)]
fn main() {
pub trait MyTrait {
    type First;
    type Second;
}

/// This function can be found using the following search queries:
///
///     MyTrait<First=u8, Second=u32> -> bool
///     MyTrait<Second=u32> -> bool
///
/// The following queries, however, will *not* match it:
///
///     MyTrait<First=u32> -> bool
///     MyTrait<u32, u32> -> bool
///     MyTrait<u32, First=u8> -> bool
///     MyTrait<u32, u8> -> bool
pub fn my_fn(x: impl MyTrait<First=u8, Second=u32>) -> bool { true }
}

函数参数与顺序无关，但对嵌套和匹配数量敏感。例如，签名 fn read_all(&mut self: impl Read) -> Result<Vec<u8>, Error> 的函数将匹配这些查询

• &mut Read -> Result<Vec<u8>, Error>
• Read -> Result<Vec<u8>, Error>
• Read -> Result<Vec<u8>>
• Read -> Vec<u8>

但它不匹配 Result<Vec, u8> 或 Result<u8<Vec>>，因为这些嵌套不正确，并且它不匹配 Result<Error, Vec<u8>> 或 Result<Error>，因为这些顺序错误。它也不匹配 Read -> u8，因为只有某些泛型包装器类型可以省略，而 Vec 不是其中之一。

要搜索接受函数作为参数的函数，例如 Iterator::all，请将嵌套签名括在括号中，如 Iterator<T>, (T -> bool) -> bool。您也可以搜索特定的闭包特性，例如 Iterator<T>, (FnMut(T) -> bool) -> bool，但您需要知道您想要哪一个。

可以省略的包装器

• 引用
• Box
• Rc
• Arc
• Option
• Result
• From
• Into
• Future

具有特殊语法的原始类型

当搜索 [] 时，Rustdoc 将返回切片或数组的搜索结果。如果您知道您想要哪一个，您可以强制它使用显式名称语法返回 primitive:slice 或 primitive:array 的结果。空方括号 [] 将匹配任何切片或数组，无论它包含什么，或者可以提供项目类型，例如 [u8] 或 [T]，以显式查找对字节切片或泛型切片进行操作的函数。

用括号括起来的单个类型表达式与该类型表达式相同，因为括号充当分组运算符。但是，如果它们为空，它们将匹配 unit 和 tuple，如果存在多个类型（或尾随或前导逗号），则它与 primitive:tuple<...> 相同。

但是，由于项目可以从查询中省略，(T) 仍然会为匹配元组的类型返回结果，即使它也匹配类型本身。也就是说，(u32) 匹配 (u32,)，原因与它也匹配 Result<u32, Error> 完全相同。

-> 运算符的优先级低于逗号。如果它未括在括号中，则它会分隔正在搜索的函数的返回值。要搜索将函数作为参数的函数，请使用括号。

基于类型的搜索的限制和怪癖

基于类型的搜索仍然是一个有缺陷的、实验性的、正在进行中的功能。大多数这些限制应在 Rustdoc 的未来版本中得到解决。

• 无法在泛型参数上编写特性约束。您可以直接命名特性，如果存在具有该绑定的类型参数，它将匹配，但无法精确搜索 option<T> -> T where T: Default（使用 option<Default> -> Default）。

• 超特性、类型别名和 Deref 都被忽略。搜索主要对书写形式的类型签名进行操作，而不是它们在编译器中的表示形式。

• 类型参数匹配类型参数，例如 Option<A> 匹配 Option<T>，但永远不匹配函数签名中的具体类型。一个像类型一样命名的特性，例如 Option<Read>，将匹配受该特性约束的类型参数，例如 Option<T> where T: Read，以及匹配 dyn Trait 和 impl Trait。

• 参数位置中的 impl Trait 的处理方式与类型参数完全相同，但在返回位置中，它将不匹配类型参数。

• 如果在复杂的基于类型的搜索中命名的任何类型都找不到完全匹配的名称，则会被假定为类型参数。如果您想强制使用类型参数，请编写 generic:T，即使找到匹配的名称，它也会用作类型参数。如果您知道您不想要类型参数，您可以通过给它一个不同的前缀（如 struct:T）来强制它匹配其他内容。

• 不支持搜索生命周期。

• 无法根据数组的长度进行搜索。

项目过滤

搜索界面中的名称可以以项目类型开头，后跟冒号（例如 mod:）来将结果限制为仅该类型的项目。此外，搜索 println! 将搜索名为 println 的宏，就像搜索 macro:println 一样。可用过滤器的完整列表在 ? 帮助区域和下面的详细语法中给出。

项目过滤器可以用于基于名称的搜索和基于类型签名的搜索。

搜索查询语法

ident = *(ALPHA / DIGIT / "_")
path = ident *(DOUBLE-COLON ident) [BANG]
slice-like = OPEN-SQUARE-BRACKET [ nonempty-arg-list ] CLOSE-SQUARE-BRACKET
tuple-like = OPEN-PAREN [ nonempty-arg-list ] CLOSE-PAREN
borrow-ref = AMP *WS [MUT] *WS [arg]
arg = [type-filter *WS COLON *WS] (path [generics] / slice-like / tuple-like / borrow-ref)
type-sep = COMMA/WS *(COMMA/WS)
nonempty-arg-list = *(type-sep) arg *(type-sep arg) *(type-sep) [ return-args ]
generic-arg-list = *(type-sep) arg [ EQUAL arg ] *(type-sep arg [ EQUAL arg ]) *(type-sep)
normal-generics = OPEN-ANGLE-BRACKET [ generic-arg-list ] *(type-sep)
            CLOSE-ANGLE-BRACKET
fn-like-generics = OPEN-PAREN [ nonempty-arg-list ] CLOSE-PAREN [ RETURN-ARROW arg ]
generics = normal-generics / fn-like-generics
return-args = RETURN-ARROW *(type-sep) nonempty-arg-list

exact-search = [type-filter *WS COLON] [ RETURN-ARROW ] *WS QUOTE ident QUOTE [ generics ]
type-search = [ nonempty-arg-list ]

query = *WS (exact-search / type-search) *WS

type-filter = (
    "mod" /
    "externcrate" /
    "import" /
    "struct" /
    "enum" /
    "fn" /
    "type" /
    "static" /
    "trait" /
    "impl" /
    "tymethod" /
    "method" /
    "structfield" /
    "variant" /
    "macro" /
    "primitive" /
    "associatedtype" /
    "constant" /
    "associatedconstant" /
    "union" /
    "foreigntype" /
    "keyword" /
    "existential" /
    "attr" /
    "derive" /
    "traitalias" /
    "generic")

OPEN-ANGLE-BRACKET = "<"
CLOSE-ANGLE-BRACKET = ">"
OPEN-SQUARE-BRACKET = "["
CLOSE-SQUARE-BRACKET = "]"
OPEN-PAREN = "("
CLOSE-PAREN = ")"
COLON = ":"
DOUBLE-COLON = "::"
QUOTE = %x22
COMMA = ","
RETURN-ARROW = "->"
EQUAL = "="
BANG = "!"
AMP = "&"
MUT = "mut"

ALPHA = %x41-5A / %x61-7A ; A-Z / a-z
DIGIT = %x30-39
WS = %x09 / " "