A Rust library for parsing, compiling, and executing regular expressions. Its syntax is similar to Perl-style regular expressions, but lacks a few features like look around and backreferences. In exchange, all searches execute in linear time with respect to the size of the regular expression and search text. Much of the syntax and implementation is inspired by RE2.
Module documentation with examples. The module documentation also includes a comprehensive description of the syntax supported.
Documentation with examples for the various matching functions and iterators
can be found on the
Add this to your
 = "0.2"
and this to your crate root:
extern crate regex;
Here's a simple example that matches a date in YYYY-MM-DD format and prints the year, month and day:
extern crate regex; use Regex;
If you have lots of dates in text that you'd like to iterate over, then it's easy to adapt the above example with an iterator:
extern crate regex; use Regex; const TO_SEARCH: &'static str = " On 2010-03-14, foo happened. On 2014-10-14, bar happened. ";
This example outputs:
year: 2010, month: 03, day: 14 year: 2014, month: 10, day: 14
Usage: Avoid compiling the same regex in a loop
It is an anti-pattern to compile the same regular expression in a loop since compilation is typically expensive. (It takes anywhere from a few microseconds to a few milliseconds depending on the size of the regex.) Not only is compilation itself expensive, but this also prevents optimizations that reuse allocations internally to the matching engines.
In Rust, it can sometimes be a pain to pass regular expressions around if
they're used from inside a helper function. Instead, we recommend using the
lazy_static crate to ensure that
regular expressions are compiled exactly once.
extern crate lazy_static; extern crate regex; use Regex;
Specifically, in this example, the regex will be compiled when it is used for the first time. On subsequent uses, it will reuse the previous compilation.
Usage: match regular expressions on
The main API of this crate (
regex::Regex) requires the caller to pass a
&str for searching. In Rust, an
&str is required to be valid UTF-8, which
means the main API can't be used for searching arbitrary bytes.
To match on arbitrary bytes, use the
regex::bytes::Regex API. The API
is identical to the main API, except that it takes an
&[u8] to search
on instead of an
&str. By default,
. will match any byte using
. will match any UTF-8 encoded Unicode scalar
value using the main API.
This example shows how to find all null-terminated strings in a slice of bytes:
use Regex; let re = new.unwrap; let text = b"foo\x00bar\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: = re.captures_iter .map .collect; assert_eq!;
Notice here that the
[^\x00]+ will match any byte except for
using the main API,
[^\x00]+ would instead match any valid UTF-8 sequence
Usage: match multiple regular expressions simultaneously
This demonstrates how to use a
RegexSet to match multiple (possibly
overlapping) regular expressions in a single scan of the search text:
use RegexSet; let set = new.unwrap; // Iterate over and collect all of the matches. let matches: = set.matches.into_iter.collect; assert_eq!; // You can also test whether a particular regex matched: let matches = set.matches; assert!; assert!;
Usage: enable SIMD optimizations
This crate provides an
unstable feature that can only be enabled on nightly
Rust. When this feature is enabled, the regex crate will use SIMD optimizations
if your CPU supports them. No additional compile time flags are required; the
regex crate will detect your CPU support at runtime.
std::arch becomes stable, then these optimizations will be enabled
Usage: a regular expression parser
This repository contains a crate that provides a well tested regular expression parser, abstract syntax and a high-level intermediate representation for convenient analysis. It provides no facilities for compilation or execution. This may be useful if you're implementing your own regex engine or otherwise need to do analysis on the syntax of a regular expression. It is otherwise not recommended for general use.
This project is licensed under either of
- Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.