文档

模块文档及示例。模块文档还包括了对所支持语法的全面描述。

在 Regex 类型 上可以找到各种匹配函数和迭代器的示例文档。

用法

要将此 crate 添加到您的仓库中，请在您的 Cargo.toml 中添加 regex，或运行 cargo add regex。

以下是一个简单的示例，匹配 YYYY-MM-DD 格式的日期，并打印年份、月份和日期：

use regex::Regex;

fn main() {
    let re = Regex::new(r"(?x)
(?P<year>\d{4})  # the year
-
(?P<month>\d{2}) # the month
-
(?P<day>\d{2})   # the day
").unwrap();

    let caps = re.captures("2010-03-14").unwrap();
    assert_eq!("2010", &caps["year"]);
    assert_eq!("03", &caps["month"]);
    assert_eq!("14", &caps["day"]);
}

如果您有很多文本中的日期需要迭代，那么可以很容易地通过迭代器适配上述示例：

use regex::Regex;

fn main() {
    let re = Regex::new(r"(\d{4})-(\d{2})-(\d{2})").unwrap();
    let hay = "On 2010-03-14, foo happened. On 2014-10-14, bar happened.";

    let mut dates = vec![];
    for (_, [year, month, day]) in re.captures_iter(hay).map(|c| c.extract()) {
        dates.push((year, month, day));
    }
    assert_eq!(dates, vec![
      ("2010", "03", "14"),
      ("2014", "10", "14"),
    ]);
}

用法：避免在循环中编译相同的正则表达式

在循环中编译相同的正则表达式是一种反模式，因为编译通常代价很高。编译所需时间从几微秒到几毫秒不等，具体取决于正则表达式的大小。这不仅使编译本身代价高昂，还阻碍了匹配引擎内部重用分配的优化。

在Rust中，如果正则表达式在辅助函数内部使用，传递它们有时可能很痛苦。因此，我们建议使用once_cell库来确保正则表达式只编译一次。例如

use {
    once_cell::sync::Lazy,
    regex::Regex,
};

fn some_helper_function(haystack: &str) -> bool {
    static RE: Lazy<Regex> = Lazy::new(|| Regex::new(r"...").unwrap());
    RE.is_match(haystack)
}

fn main() {
    assert!(some_helper_function("abc"));
    assert!(!some_helper_function("ac"));
}

具体来说，在这个示例中，正则表达式将在第一次使用时进行编译。在随后的使用中，它将重用之前的编译。

用法：在&[u8]上匹配正则表达式

此库的主要API（regex::Regex）要求调用者传递一个用于搜索的&str。在Rust中，&str必须是有效的UTF-8，这意味着主要API不能用于搜索任意字节。

要匹配任意字节，请使用regex::bytes::Regex API。该API与主要API相同，不同之处在于它接受一个&[u8]进行搜索，而不是一个&str。这些&[u8] API还允许在正则表达式中禁用Unicode模式，即使模式会匹配无效的UTF-8。例如，(?-u:.)在regex::Regex中不允许，但在regex::bytes::Regex中允许，因为(?-u:.)匹配除了\n之外的所有字节。相反，.将匹配除了\n之外的任何Unicode标量值的UTF-8编码。

此示例展示了如何在字节数组切片中找到所有空终止的字符串

use regex::bytes::Regex;

let re = Regex::new(r"(?-u)(?<cstr>[^\x00]+)\x00").unwrap();
let text = b"foo\xFFbar\x00baz\x00";

// Extract all of the strings without the null terminator from each match.
// The unwrap is OK here since a match requires the `cstr` capture to match.
let cstrs: Vec<&[u8]> =
    re.captures_iter(text)
      .map(|c| c.name("cstr").unwrap().as_bytes())
      .collect();
assert_eq!(vec![&b"foo\xFFbar"[..], &b"baz"[..]], cstrs);

注意，这里的[^\x00]+将匹配任何字节，除了NUL，包括像\xFF这样的字节，它们不是有效的UTF-8。当使用主要API时，[^\x00]+将匹配任何有效的UTF-8序列，除了NUL。

用法：同时匹配多个正则表达式

本例演示了如何使用RegexSet在搜索文本的单次扫描中匹配多个（可能重叠的）正则表达式

use regex::RegexSet;

let set = RegexSet::new(&[
    r"\w+",
    r"\d+",
    r"\pL+",
    r"foo",
    r"bar",
    r"barfoo",
    r"foobar",
]).unwrap();

// Iterate over and collect all of the matches.
let matches: Vec<_> = set.matches("foobar").into_iter().collect();
assert_eq!(matches, vec![0, 2, 3, 4, 6]);

// You can also test whether a particular regex matched:
let matches = set.matches("foobar");
assert!(!matches.matched(5));
assert!(matches.matched(6));

用法：将正则表达式内部作为库使用

《regex-automata 目录》中包含一个crate，该crate公开了《regex》crate所使用的所有内部匹配引擎。其想法是，《regex》crate为99%的使用场景提供了简单的API，而《regex-automata》则公开了大量可定制的功能。

《regex-automata》的文档。

用法：正则表达式解析器

该仓库包含一个crate，它提供了一个经过良好测试的正则表达式解析器、抽象语法和高级中间表示，便于分析。它不提供编译或执行的功能。如果您正在实现自己的正则表达式引擎或需要对正则表达式的语法进行分析，这可能很有用。否则，不建议一般使用。

《regex-syntax》的文档。

crate功能

该crate附带一些功能，允许用户在二进制大小、编译时间和运行时性能之间进行权衡。该crate的用户可以选择性地禁用Unicode表，或从该crate提供的各种优化中选择禁用。

当所有这些功能都禁用时，运行时匹配性能可能会大大降低，但如果您正在匹配短字符串，或者高性能不是必需的，则这种配置完全可以满足需求。要禁用所有这些功能，请使用以下 Cargo.toml 依赖配置

[dependencies.regex]
version = "1.3"
default-features = false
# Unless you have a specific reason not to, it's good sense to enable standard
# library support. It enables several optimizations and avoids spin locks. It
# also shouldn't meaningfully impact compile times or binary size.
features = ["std"]

这将把 regex 的依赖树缩减到两个crate：regex-syntax 和 regex-automata。

可以禁用的完整功能集在文档的“crate功能”部分中。

性能

该crate的目标之一是让正则表达式引擎“快速”。这是一个有些模糊的目标，通常有两种解释方式。首先，这意味着所有搜索都将在最坏情况下花费 O(m * n) 的时间，其中 m 与 len(regex) 成正比，而 n 与 len(haystack) 成正比。其次，它还意味着即使在时间复杂度约束之外，正则表达式搜索在实践中也是“快速”的。

$ git clone https://github.com/BurntSushi/rebar
$ cd rebar
$ cargo install --path ./

$ rebar build -e '^rust/regex$'

$ rebar measure -e '^rust/regex$' -t

$ rebar measure -e '^rust/regex$' | tee results.csv

$ rebar cmp results.csv