{"id":13440104,"url":"https://github.com/rust-lang/regex","last_synced_at":"2025-05-13T11:10:30.308Z","repository":{"id":24486190,"uuid":"27890669","full_name":"rust-lang/regex","owner":"rust-lang","description":"An implementation of regular expressions for Rust. This implementation uses finite automata and guarantees linear time matching on all inputs.","archived":false,"fork":false,"pushed_at":"2024-11-11T15:16:30.000Z","size":7793,"stargazers_count":3690,"open_issues_count":68,"forks_count":461,"subscribers_count":50,"default_branch":"master","last_synced_at":"2025-05-13T00:01:57.583Z","etag":null,"topics":["automata","automaton","dfa","nfa","regex","regex-engine","regex-parser","regex-syntax","regexp","regular-expressions","rust"],"latest_commit_sha":null,"homepage":"https://docs.rs/regex","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rust-lang.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-12-11T20:39:09.000Z","updated_at":"2025-05-12T15:59:25.000Z","dependencies_parsed_at":"2024-04-22T15:48:27.326Z","dependency_job_id":"840986f4-a3f1-4616-9eea-3835f117f8bf","html_url":"https://github.com/rust-lang/regex","commit_stats":{"total_commits":1352,"total_committers":195,"mean_commits":6.933333333333334,"dds":0.2818047337278107,"last_synced_commit":"1a069b9232c607b34c4937122361aa075ef573fa"},"previous_names":[],"tags_count":202,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rust-lang%2Fregex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rust-lang%2Fregex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rust-lang%2Fregex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rust-lang%2Fregex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rust-lang","download_url":"https://codeload.github.com/rust-lang/regex/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253843215,"owners_count":21972873,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automata","automaton","dfa","nfa","regex","regex-engine","regex-parser","regex-syntax","regexp","regular-expressions","rust"],"created_at":"2024-07-31T03:01:19.804Z","updated_at":"2025-05-13T11:10:30.283Z","avatar_url":"https://github.com/rust-lang.png","language":"Rust","readme":"regex\n=====\nThis crate provides routines for searching strings for matches of a [regular\nexpression] (aka \"regex\"). The regex syntax supported by this crate is similar\nto other regex engines, but it lacks several features that are not known how to\nimplement efficiently. This includes, but is not limited to, look-around and\nbackreferences. In exchange, all regex searches in this crate have worst case\n`O(m * n)` time complexity, where `m` is proportional to the size of the regex\nand `n` is proportional to the size of the string being searched.\n\n[regular expression]: https://en.wikipedia.org/wiki/Regular_expression\n\n[![Build status](https://github.com/rust-lang/regex/workflows/ci/badge.svg)](https://github.com/rust-lang/regex/actions)\n[![Crates.io](https://img.shields.io/crates/v/regex.svg)](https://crates.io/crates/regex)\n\n### Documentation\n\n[Module documentation with examples](https://docs.rs/regex).\nThe module documentation also includes a comprehensive description of the\nsyntax supported.\n\nDocumentation with examples for the various matching functions and iterators\ncan be found on the\n[`Regex` type](https://docs.rs/regex/*/regex/struct.Regex.html).\n\n### Usage\n\nTo bring this crate into your repository, either add `regex` to your\n`Cargo.toml`, or run `cargo add regex`.\n\nHere's a simple example that matches a date in YYYY-MM-DD format and prints the\nyear, month and day:\n\n```rust\nuse regex::Regex;\n\nfn main() {\n    let re = Regex::new(r\"(?x)\n(?P\u003cyear\u003e\\d{4})  # the year\n-\n(?P\u003cmonth\u003e\\d{2}) # the month\n-\n(?P\u003cday\u003e\\d{2})   # the day\n\").unwrap();\n\n    let caps = re.captures(\"2010-03-14\").unwrap();\n    assert_eq!(\"2010\", \u0026caps[\"year\"]);\n    assert_eq!(\"03\", \u0026caps[\"month\"]);\n    assert_eq!(\"14\", \u0026caps[\"day\"]);\n}\n```\n\nIf you have lots of dates in text that you'd like to iterate over, then it's\neasy to adapt the above example with an iterator:\n\n```rust\nuse regex::Regex;\n\nfn main() {\n    let re = Regex::new(r\"(\\d{4})-(\\d{2})-(\\d{2})\").unwrap();\n    let hay = \"On 2010-03-14, foo happened. On 2014-10-14, bar happened.\";\n\n    let mut dates = vec![];\n    for (_, [year, month, day]) in re.captures_iter(hay).map(|c| c.extract()) {\n        dates.push((year, month, day));\n    }\n    assert_eq!(dates, vec![\n      (\"2010\", \"03\", \"14\"),\n      (\"2014\", \"10\", \"14\"),\n    ]);\n}\n```\n\n### Usage: Avoid compiling the same regex in a loop\n\nIt is an anti-pattern to compile the same regular expression in a loop since\ncompilation is typically expensive. (It takes anywhere from a few microseconds\nto a few **milliseconds** depending on the size of the regex.) Not only is\ncompilation itself expensive, but this also prevents optimizations that reuse\nallocations internally to the matching engines.\n\nIn Rust, it can sometimes be a pain to pass regular expressions around if\nthey're used from inside a helper function. Instead, we recommend using the\n[`once_cell`](https://crates.io/crates/once_cell) crate to ensure that\nregular expressions are compiled exactly once. For example:\n\n```rust\nuse {\n    once_cell::sync::Lazy,\n    regex::Regex,\n};\n\nfn some_helper_function(haystack: \u0026str) -\u003e bool {\n    static RE: Lazy\u003cRegex\u003e = Lazy::new(|| Regex::new(r\"...\").unwrap());\n    RE.is_match(haystack)\n}\n\nfn main() {\n    assert!(some_helper_function(\"abc\"));\n    assert!(!some_helper_function(\"ac\"));\n}\n```\n\nSpecifically, in this example, the regex will be compiled when it is used for\nthe first time. On subsequent uses, it will reuse the previous compilation.\n\n### Usage: match regular expressions on `\u0026[u8]`\n\nThe main API of this crate (`regex::Regex`) requires the caller to pass a\n`\u0026str` for searching. In Rust, an `\u0026str` is required to be valid UTF-8, which\nmeans the main API can't be used for searching arbitrary bytes.\n\nTo match on arbitrary bytes, use the `regex::bytes::Regex` API. The API is\nidentical to the main API, except that it takes an `\u0026[u8]` to search on instead\nof an `\u0026str`. The `\u0026[u8]` APIs also permit disabling Unicode mode in the regex\neven when the pattern would match invalid UTF-8. For example, `(?-u:.)` is\nnot allowed in `regex::Regex` but is allowed in `regex::bytes::Regex` since\n`(?-u:.)` matches any byte except for `\\n`. Conversely, `.` will match the\nUTF-8 encoding of any Unicode scalar value except for `\\n`.\n\nThis example shows how to find all null-terminated strings in a slice of bytes:\n\n```rust\nuse regex::bytes::Regex;\n\nlet re = Regex::new(r\"(?-u)(?\u003ccstr\u003e[^\\x00]+)\\x00\").unwrap();\nlet text = b\"foo\\xFFbar\\x00baz\\x00\";\n\n// Extract all of the strings without the null terminator from each match.\n// The unwrap is OK here since a match requires the `cstr` capture to match.\nlet cstrs: Vec\u003c\u0026[u8]\u003e =\n    re.captures_iter(text)\n      .map(|c| c.name(\"cstr\").unwrap().as_bytes())\n      .collect();\nassert_eq!(vec![\u0026b\"foo\\xFFbar\"[..], \u0026b\"baz\"[..]], cstrs);\n```\n\nNotice here that the `[^\\x00]+` will match any *byte* except for `NUL`,\nincluding bytes like `\\xFF` which are not valid UTF-8. When using the main API,\n`[^\\x00]+` would instead match any valid UTF-8 sequence except for `NUL`.\n\n### Usage: match multiple regular expressions simultaneously\n\nThis demonstrates how to use a `RegexSet` to match multiple (possibly\noverlapping) regular expressions in a single scan of the search text:\n\n```rust\nuse regex::RegexSet;\n\nlet set = RegexSet::new(\u0026[\n    r\"\\w+\",\n    r\"\\d+\",\n    r\"\\pL+\",\n    r\"foo\",\n    r\"bar\",\n    r\"barfoo\",\n    r\"foobar\",\n]).unwrap();\n\n// Iterate over and collect all of the matches.\nlet matches: Vec\u003c_\u003e = set.matches(\"foobar\").into_iter().collect();\nassert_eq!(matches, vec![0, 2, 3, 4, 6]);\n\n// You can also test whether a particular regex matched:\nlet matches = set.matches(\"foobar\");\nassert!(!matches.matched(5));\nassert!(matches.matched(6));\n```\n\n\n### Usage: regex internals as a library\n\nThe [`regex-automata` directory](./regex-automata/) contains a crate that\nexposes all of the internal matching engines used by the `regex` crate. The\nidea is that the `regex` crate exposes a simple API for 99% of use cases, but\n`regex-automata` exposes oodles of customizable behaviors.\n\n[Documentation for `regex-automata`.](https://docs.rs/regex-automata)\n\n\n### Usage: a regular expression parser\n\nThis repository contains a crate that provides a well tested regular expression\nparser, abstract syntax and a high-level intermediate representation for\nconvenient analysis. It provides no facilities for compilation or execution.\nThis may be useful if you're implementing your own regex engine or otherwise\nneed to do analysis on the syntax of a regular expression. It is otherwise not\nrecommended for general use.\n\n[Documentation for `regex-syntax`.](https://docs.rs/regex-syntax)\n\n\n### Crate features\n\nThis crate comes with several features that permit tweaking the trade off\nbetween binary size, compilation time and runtime performance. Users of this\ncrate can selectively disable Unicode tables, or choose from a variety of\noptimizations performed by this crate to disable.\n\nWhen all of these features are disabled, runtime match performance may be much\nworse, but if you're matching on short strings, or if high performance isn't\nnecessary, then such a configuration is perfectly serviceable. To disable\nall such features, use the following `Cargo.toml` dependency configuration:\n\n```toml\n[dependencies.regex]\nversion = \"1.3\"\ndefault-features = false\n# Unless you have a specific reason not to, it's good sense to enable standard\n# library support. It enables several optimizations and avoids spin locks. It\n# also shouldn't meaningfully impact compile times or binary size.\nfeatures = [\"std\"]\n```\n\nThis will reduce the dependency tree of `regex` down to two crates:\n`regex-syntax` and `regex-automata`.\n\nThe full set of features one can disable are\n[in the \"Crate features\" section of the documentation](https://docs.rs/regex/1.*/#crate-features).\n\n\n### Performance\n\nOne of the goals of this crate is for the regex engine to be \"fast.\" What that\nis a somewhat nebulous goal, it is usually interpreted in one of two ways.\nFirst, it means that all searches take worst case `O(m * n)` time, where\n`m` is proportional to `len(regex)` and `n` is proportional to `len(haystack)`.\nSecond, it means that even aside from the time complexity constraint, regex\nsearches are \"fast\" in practice.\n\nWhile the first interpretation is pretty unambiguous, the second one remains\nnebulous. While nebulous, it guides this crate's architecture and the sorts of\nthe trade offs it makes. For example, here are some general architectural\nstatements that follow as a result of the goal to be \"fast\":\n\n* When given the choice between faster regex searches and faster _Rust compile\ntimes_, this crate will generally choose faster regex searches.\n* When given the choice between faster regex searches and faster _regex compile\ntimes_, this crate will generally choose faster regex searches. That is, it is\ngenerally acceptable for `Regex::new` to get a little slower if it means that\nsearches get faster. (This is a somewhat delicate balance to strike, because\nthe speed of `Regex::new` needs to remain somewhat reasonable. But this is why\none should avoid re-compiling the same regex over and over again.)\n* When given the choice between faster regex searches and simpler API\ndesign, this crate will generally choose faster regex searches. For example,\nif one didn't care about performance, we could like get rid of both of\nthe `Regex::is_match` and `Regex::find` APIs and instead just rely on\n`Regex::captures`.\n\nThere are perhaps more ways that being \"fast\" influences things.\n\nWhile this repository used to provide its own benchmark suite, it has since\nbeen moved to [rebar](https://github.com/BurntSushi/rebar). The benchmarks are\nquite extensive, and there are many more than what is shown in rebar's README\n(which is just limited to a \"curated\" set meant to compare performance between\nregex engines). To run all of this crate's benchmarks, first start by cloning\nand installing `rebar`:\n\n```text\n$ git clone https://github.com/BurntSushi/rebar\n$ cd rebar\n$ cargo install --path ./\n```\n\nThen build the benchmark harness for just this crate:\n\n```text\n$ rebar build -e '^rust/regex$'\n```\n\nRun all benchmarks for this crate as tests (each benchmark is executed once to\nensure it works):\n\n```text\n$ rebar measure -e '^rust/regex$' -t\n```\n\nRecord measurements for all benchmarks and save them to a CSV file:\n\n```text\n$ rebar measure -e '^rust/regex$' | tee results.csv\n```\n\nExplore benchmark timings:\n\n```text\n$ rebar cmp results.csv\n```\n\nSee the `rebar` documentation for more details on how it works and how to\ncompare results with other regex engines.\n\n\n### Hacking\n\nThe `regex` crate is, for the most part, a pretty thin wrapper around the\n[`meta::Regex`](https://docs.rs/regex-automata/latest/regex_automata/meta/struct.Regex.html)\nfrom the\n[`regex-automata` crate](https://docs.rs/regex-automata/latest/regex_automata/).\nTherefore, if you're looking to work on the internals of this crate, you'll\nlikely either want to look in `regex-syntax` (for parsing) or `regex-automata`\n(for construction of finite automata and the search routines).\n\nMy [blog on regex internals](https://blog.burntsushi.net/regex-internals/)\ngoes into more depth.\n\n\n### Minimum Rust version policy\n\nThis crate's minimum supported `rustc` version is `1.65.0`.\n\nThe policy is that the minimum Rust version required to use this crate can be\nincreased in minor version updates. For example, if regex 1.0 requires Rust\n1.20.0, then regex 1.0.z for all values of `z` will also require Rust 1.20.0 or\nnewer. However, regex 1.y for `y \u003e 0` may require a newer minimum version of\nRust.\n\n\n### License\n\nThis project is licensed under either of\n\n * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or\n   https://www.apache.org/licenses/LICENSE-2.0)\n * MIT license ([LICENSE-MIT](LICENSE-MIT) or\n   https://opensource.org/licenses/MIT)\n\nat your option.\n\nThe data in `regex-syntax/src/unicode_tables/` is licensed under the Unicode\nLicense Agreement\n([LICENSE-UNICODE](https://www.unicode.org/copyright.html#License)).\n","funding_links":[],"categories":["Rust","Libraries","库 Libraries","库","Regex engines"],"sub_categories":["Text processing","文本处理 Text processing","文本处理","Source code"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frust-lang%2Fregex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frust-lang%2Fregex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frust-lang%2Fregex/lists"}