regex

这个 Crate 提供了用于在字符串中搜索正则表达式匹配项的例程（即 "regex"）。此 Crate 支持的 regex 语法与其他 regex 引擎类似，但缺乏一些难以高效实现的特性。这包括但不限于前瞻和后引用。作为交换，此 Crate 中的所有 regex 搜索都有最坏情况的 O(m * n) 时间复杂度，其中 m 与正则表达式的大小成比例，n 与被搜索字符串的大小成比例。

文档

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

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

使用

要将此 Crate 添加到您的仓库，请将 regex 添加到您的 Cargo.toml，或运行 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"),
    ]);
}

使用说明：避免在循环中编译相同的 regex

在循环中编译相同的正则表达式是一种反模式，因为编译通常很昂贵。编译时间从几微秒到几毫秒不等，这取决于正则表达式的大小。编译本身就很昂贵，而且这也阻碍了匹配引擎内部重用分配的优化。

在Rust中，如果正则表达式在辅助函数内部使用，有时传递它们可能会很麻烦。相反，我们建议使用once_cell crate来确保正则表达式只编译一次。例如

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]上匹配正则表达式

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

要匹配任意字节，请使用regex::bytes::Regex API。该API与主API相同，只是它使用一个&[u8]来搜索，而不是一个&str。这些&[u8] API还允许在正则表达式中禁用Unicode模式，即使模式会匹配无效UTF-8。例如，在regex::Regex中不允许使用(?-u:.)，但在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]+将匹配除NUL之外的任何有效的UTF-8序列。

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

此示例演示了如何使用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，它暴露了《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