regex

A Rust library for parsing, compiling, and executing regular expressions.
This particular implementation of regular expressions guarantees execution
in linear time with respect to the size of the regular expression and
search text by using finite automata. In particular, it makes use of both
NFAs and DFAs when matching. Much of the syntax and implementation is inspired
by RE2.

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::Regex;
const TO_SEARCH: &'static str = "
On 2010-03-14, foo happened. On 2014-10-14, bar happened.
";
fn main() {
let re = Regex::new(r"(\d{4})-(\d{2})-(\d{2})").unwrap();
for caps in re.captures_iter(TO_SEARCH) {
// Note that all of the unwraps are actually OK for this regex
// because the only way for the regex to match is if all of the
// capture groups match. This is not true in general though!
println!("year: {}, month: {}, day: {}",
caps.at(1).unwrap(),
caps.at(2).unwrap(),
caps.at(3).unwrap());
}
}

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.

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 &[u8]

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
regex::bytes::Regex, while . will match any encoded Unicode codepoint
using the main API.

This example shows how to find all null-terminated strings in a slice of bytes:

Usage: regex! compiler plugin

WARNING: The regex! compiler plugin is orders of magnitude slower than
the normal Regex::new(...) usage. You should not use the compiler plugin
unless you have a very special reason for doing so. The performance difference
may be the temporary, but the path forward at this point isn't clear.

The regex! compiler plugin will compile your regexes at compile time. This
only works with a nightly compiler.

Notice that we never unwrap the result of regex!. This is because your
program won't compile if the regex doesn't compile. (Try regex!("(").)

Usage: a regular expression parser

This repository contains a crate that provides a well tested regular expression
parser and abstract syntax. 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.