701 lines
No EOL
41 KiB
HTML
701 lines
No EOL
41 KiB
HTML
<!DOCTYPE html>
|
||
<html lang="en">
|
||
<head>
|
||
<meta charset="utf-8">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
<meta name="generator" content="rustdoc">
|
||
<meta name="description" content="API documentation for the Rust `regex` crate.">
|
||
<meta name="keywords" content="rust, rustlang, rust-lang, regex">
|
||
|
||
<title>regex - Rust</title>
|
||
|
||
<link rel="stylesheet" type="text/css" href="../rustdoc.css">
|
||
<link rel="stylesheet" type="text/css" href="../main.css">
|
||
|
||
|
||
<link rel="shortcut icon" href="https://www.rust-lang.org/favicon.ico">
|
||
|
||
</head>
|
||
<body class="rustdoc">
|
||
<!--[if lte IE 8]>
|
||
<div class="warning">
|
||
This old browser is unsupported and will most likely display funky
|
||
things.
|
||
</div>
|
||
<![endif]-->
|
||
|
||
|
||
|
||
<nav class="sidebar">
|
||
<a href='../regex/index.html'><img src='https://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png' alt='logo' width='100'></a>
|
||
<p class='location'></p><script>window.sidebarCurrent = {name: 'regex', ty: 'mod', relpath: '../'};</script>
|
||
</nav>
|
||
|
||
<nav class="sub">
|
||
<form class="search-form js-only">
|
||
<div class="search-container">
|
||
<input class="search-input" name="search"
|
||
autocomplete="off"
|
||
placeholder="Click or press ‘S’ to search, ‘?’ for more options…"
|
||
type="search">
|
||
</div>
|
||
</form>
|
||
</nav>
|
||
|
||
<section id='main' class="content mod">
|
||
<h1 class='fqn'><span class='in-band'>Crate <a class='mod' href=''>regex</a></span><span class='out-of-band'><span id='render-detail'>
|
||
<a id="toggle-all-docs" href="javascript:void(0)" title="collapse all docs">
|
||
[<span class='inner'>−</span>]
|
||
</a>
|
||
</span><a id='src-0' class='srclink' href='../src/regex/lib.rs.html#11-649' title='goto source code'>[src]</a></span></h1>
|
||
<div class='docblock'><p>This crate provides a native implementation of regular expressions that is
|
||
heavily based on RE2 both in syntax and in implementation. Notably,
|
||
backreferences and arbitrary lookahead/lookbehind assertions are not
|
||
provided. In return, regular expression searching provided by this package
|
||
has excellent worst-case performance. The specific syntax supported is
|
||
documented further down.</p>
|
||
|
||
<p>This crate's documentation provides some simple examples, describes Unicode
|
||
support and exhaustively lists the supported syntax. For more specific
|
||
details on the API, please see the documentation for the
|
||
<a href="struct.Regex.html"><code>Regex</code></a> type.</p>
|
||
|
||
<h1 id='usage' class='section-header'><a href='#usage'>Usage</a></h1>
|
||
<p>This crate is <a href="https://crates.io/crates/regex">on crates.io</a> and can be
|
||
used by adding <code>regex</code> to your dependencies in your project's <code>Cargo.toml</code>.</p>
|
||
|
||
<pre><code class="language-toml">[dependencies]
|
||
regex = "0.1"
|
||
</code></pre>
|
||
|
||
<p>and this to your crate root:</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>extern</span> <span class='kw'>crate</span> <span class='ident'>regex</span>;</pre>
|
||
|
||
<h1 id='example-find-a-date' class='section-header'><a href='#example-find-a-date'>Example: find a date</a></h1>
|
||
<p>General use of regular expressions in this package involves compiling an
|
||
expression and then using it to search, split or replace text. For example,
|
||
to confirm that some text resembles a date:</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>use</span> <span class='ident'>regex</span>::<span class='ident'>Regex</span>;
|
||
<span class='kw'>let</span> <span class='ident'>re</span> <span class='op'>=</span> <span class='ident'>Regex</span>::<span class='ident'>new</span>(<span class='string'>r"^\d{4}-\d{2}-\d{2}$"</span>).<span class='ident'>unwrap</span>();
|
||
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>re</span>.<span class='ident'>is_match</span>(<span class='string'>"2014-01-01"</span>));</pre>
|
||
|
||
<p>Notice the use of the <code>^</code> and <code>$</code> anchors. In this crate, every expression
|
||
is executed with an implicit <code>.*?</code> at the beginning and end, which allows
|
||
it to match anywhere in the text. Anchors can be used to ensure that the
|
||
full text matches an expression.</p>
|
||
|
||
<p>This example also demonstrates the utility of
|
||
<a href="https://doc.rust-lang.org/stable/reference.html#raw-string-literals">raw strings</a>
|
||
in Rust, which
|
||
are just like regular strings except they are prefixed with an <code>r</code> and do
|
||
not process any escape sequences. For example, <code>"\\d"</code> is the same
|
||
expression as <code>r"\d"</code>.</p>
|
||
|
||
<h1 id='example-avoid-compiling-the-same-regex-in-a-loop' class='section-header'><a href='#example-avoid-compiling-the-same-regex-in-a-loop'>Example: Avoid compiling the same regex in a loop</a></h1>
|
||
<p>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 <strong>milliseconds</strong> 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.</p>
|
||
|
||
<p>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
|
||
<a href="https://crates.io/crates/lazy_static"><code>lazy_static</code></a> crate to ensure that
|
||
regular expressions are compiled exactly once.</p>
|
||
|
||
<p>For example:</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='attribute'>#[<span class='ident'>macro_use</span>]</span> <span class='kw'>extern</span> <span class='kw'>crate</span> <span class='ident'>lazy_static</span>;
|
||
<span class='kw'>extern</span> <span class='kw'>crate</span> <span class='ident'>regex</span>;
|
||
|
||
<span class='kw'>use</span> <span class='ident'>regex</span>::<span class='ident'>Regex</span>;
|
||
|
||
<span class='kw'>fn</span> <span class='ident'>some_helper_function</span>(<span class='ident'>text</span>: <span class='kw-2'>&</span><span class='ident'>str</span>) <span class='op'>-></span> <span class='ident'>bool</span> {
|
||
<span class='macro'>lazy_static</span><span class='macro'>!</span> {
|
||
<span class='kw'>static</span> <span class='kw-2'>ref</span> <span class='ident'>RE</span>: <span class='ident'>Regex</span> <span class='op'>=</span> <span class='ident'>Regex</span>::<span class='ident'>new</span>(<span class='string'>"..."</span>).<span class='ident'>unwrap</span>();
|
||
}
|
||
<span class='ident'>RE</span>.<span class='ident'>is_match</span>(<span class='ident'>text</span>)
|
||
}
|
||
|
||
<span class='kw'>fn</span> <span class='ident'>main</span>() {}</pre>
|
||
|
||
<p>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.</p>
|
||
|
||
<h1 id='the-regex-macro' class='section-header'><a href='#the-regex-macro'>The <code>regex!</code> macro</a></h1>
|
||
<p>Rust's compile-time meta-programming facilities provide a way to write a
|
||
<code>regex!</code> macro which compiles regular expressions <em>when your program
|
||
compiles</em>. Said differently, if you only use <code>regex!</code> to build regular
|
||
expressions in your program, then your program cannot compile with an
|
||
invalid regular expression. Moreover, the <code>regex!</code> macro compiles the
|
||
given expression to native Rust code, which ideally makes it faster.
|
||
Unfortunately (or fortunately), the dynamic implementation has had a lot
|
||
more optimization work put into it currently, so it is faster than
|
||
the <code>regex!</code> macro in almost every case.</p>
|
||
|
||
<p>To use the <code>regex!</code> macro, you must add <code>regex_macros</code> to your dependencies
|
||
in your project's <code>Cargo.toml</code>:</p>
|
||
|
||
<pre><code class="language-toml">[dependencies]
|
||
regex = "0.1"
|
||
regex_macros = "0.1"
|
||
</code></pre>
|
||
|
||
<p>and then enable the <code>plugin</code> feature and import the <code>regex_macros</code> crate as
|
||
a syntax extension:</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='attribute'>#<span class='op'>!</span>[<span class='ident'>feature</span>(<span class='ident'>plugin</span>)]</span>
|
||
<span class='attribute'>#<span class='op'>!</span>[<span class='ident'>plugin</span>(<span class='ident'>regex_macros</span>)]</span>
|
||
<span class='kw'>extern</span> <span class='kw'>crate</span> <span class='ident'>regex</span>;
|
||
|
||
<span class='kw'>fn</span> <span class='ident'>main</span>() {
|
||
<span class='kw'>let</span> <span class='ident'>re</span> <span class='op'>=</span> <span class='macro'>regex</span><span class='macro'>!</span>(<span class='string'>r"^\d{4}-\d{2}-\d{2}$"</span>);
|
||
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>re</span>.<span class='ident'>is_match</span>(<span class='string'>"2014-01-01"</span>));
|
||
}</pre>
|
||
|
||
<p>There are a few things worth mentioning about using the <code>regex!</code> macro.
|
||
Firstly, the <code>regex!</code> macro <em>only</em> accepts string <em>literals</em>.
|
||
Secondly, the <code>regex</code> crate <em>must</em> be linked with the name <code>regex</code> since
|
||
the generated code depends on finding symbols in the <code>regex</code> crate.</p>
|
||
|
||
<p>One downside of using the <code>regex!</code> macro is that it can increase the
|
||
size of your program's binary since it generates specialized Rust code.
|
||
The extra size probably won't be significant for a small number of
|
||
expressions, but 100+ calls to <code>regex!</code> will probably result in a
|
||
noticeably bigger binary.</p>
|
||
|
||
<p><strong>NOTE</strong>: This is implemented using a compiler plugin, which is not
|
||
available on the Rust 1.0 beta/stable channels. Therefore, you'll only
|
||
be able to use <code>regex!</code> on the nightly Rust releases.</p>
|
||
|
||
<h1 id='example-iterating-over-capture-groups' class='section-header'><a href='#example-iterating-over-capture-groups'>Example: iterating over capture groups</a></h1>
|
||
<p>This crate provides convenient iterators for matching an expression
|
||
repeatedly against a search string to find successive non-overlapping
|
||
matches. For example, to find all dates in a string and be able to access
|
||
them by their component pieces:</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>re</span> <span class='op'>=</span> <span class='ident'>Regex</span>::<span class='ident'>new</span>(<span class='string'>r"(\d{4})-(\d{2})-(\d{2})"</span>).<span class='ident'>unwrap</span>();
|
||
<span class='kw'>let</span> <span class='ident'>text</span> <span class='op'>=</span> <span class='string'>"2012-03-14, 2013-01-01 and 2014-07-05"</span>;
|
||
<span class='kw'>for</span> <span class='ident'>cap</span> <span class='kw'>in</span> <span class='ident'>re</span>.<span class='ident'>captures_iter</span>(<span class='ident'>text</span>) {
|
||
<span class='macro'>println</span><span class='macro'>!</span>(<span class='string'>"Month: {} Day: {} Year: {}"</span>,
|
||
<span class='ident'>cap</span>.<span class='ident'>at</span>(<span class='number'>2</span>).<span class='ident'>unwrap_or</span>(<span class='string'>""</span>), <span class='ident'>cap</span>.<span class='ident'>at</span>(<span class='number'>3</span>).<span class='ident'>unwrap_or</span>(<span class='string'>""</span>),
|
||
<span class='ident'>cap</span>.<span class='ident'>at</span>(<span class='number'>1</span>).<span class='ident'>unwrap_or</span>(<span class='string'>""</span>));
|
||
}
|
||
<span class='comment'>// Output:</span>
|
||
<span class='comment'>// Month: 03 Day: 14 Year: 2012</span>
|
||
<span class='comment'>// Month: 01 Day: 01 Year: 2013</span>
|
||
<span class='comment'>// Month: 07 Day: 05 Year: 2014</span></pre>
|
||
|
||
<p>Notice that the year is in the capture group indexed at <code>1</code>. This is
|
||
because the <em>entire match</em> is stored in the capture group at index <code>0</code>.</p>
|
||
|
||
<h1 id='example-replacement-with-named-capture-groups' class='section-header'><a href='#example-replacement-with-named-capture-groups'>Example: replacement with named capture groups</a></h1>
|
||
<p>Building on the previous example, perhaps we'd like to rearrange the date
|
||
formats. This can be done with text replacement. But to make the code
|
||
clearer, we can <em>name</em> our capture groups and use those names as variables
|
||
in our replacement text:</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>re</span> <span class='op'>=</span> <span class='ident'>Regex</span>::<span class='ident'>new</span>(<span class='string'>r"(?P<y>\d{4})-(?P<m>\d{2})-(?P<d>\d{2})"</span>).<span class='ident'>unwrap</span>();
|
||
<span class='kw'>let</span> <span class='ident'>before</span> <span class='op'>=</span> <span class='string'>"2012-03-14, 2013-01-01 and 2014-07-05"</span>;
|
||
<span class='kw'>let</span> <span class='ident'>after</span> <span class='op'>=</span> <span class='ident'>re</span>.<span class='ident'>replace_all</span>(<span class='ident'>before</span>, <span class='string'>"$m/$d/$y"</span>);
|
||
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>after</span>, <span class='string'>"03/14/2012, 01/01/2013 and 07/05/2014"</span>);</pre>
|
||
|
||
<p>The <code>replace</code> methods are actually polymorphic in the replacement, which
|
||
provides more flexibility than is seen here. (See the documentation for
|
||
<code>Regex::replace</code> for more details.)</p>
|
||
|
||
<p>Note that if your regex gets complicated, you can use the <code>x</code> flag to
|
||
enable insigificant whitespace mode, which also lets you write comments:</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>re</span> <span class='op'>=</span> <span class='ident'>Regex</span>::<span class='ident'>new</span>(<span class='string'>r"(?x)
|
||
(?P<y>\d{4}) # the year
|
||
-
|
||
(?P<m>\d{2}) # the month
|
||
-
|
||
(?P<d>\d{2}) # the day
|
||
"</span>).<span class='ident'>unwrap</span>();
|
||
<span class='kw'>let</span> <span class='ident'>before</span> <span class='op'>=</span> <span class='string'>"2012-03-14, 2013-01-01 and 2014-07-05"</span>;
|
||
<span class='kw'>let</span> <span class='ident'>after</span> <span class='op'>=</span> <span class='ident'>re</span>.<span class='ident'>replace_all</span>(<span class='ident'>before</span>, <span class='string'>"$m/$d/$y"</span>);
|
||
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>after</span>, <span class='string'>"03/14/2012, 01/01/2013 and 07/05/2014"</span>);</pre>
|
||
|
||
<h1 id='example-match-multiple-regular-expressions-simultaneously' class='section-header'><a href='#example-match-multiple-regular-expressions-simultaneously'>Example: match multiple regular expressions simultaneously</a></h1>
|
||
<p>This demonstrates how to use a <code>RegexSet</code> to match multiple (possibly
|
||
overlapping) regular expressions in a single scan of the search text:</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>use</span> <span class='ident'>regex</span>::<span class='ident'>RegexSet</span>;
|
||
|
||
<span class='kw'>let</span> <span class='ident'>set</span> <span class='op'>=</span> <span class='ident'>RegexSet</span>::<span class='ident'>new</span>(<span class='kw-2'>&</span>[
|
||
<span class='string'>r"\w+"</span>,
|
||
<span class='string'>r"\d+"</span>,
|
||
<span class='string'>r"\pL+"</span>,
|
||
<span class='string'>r"foo"</span>,
|
||
<span class='string'>r"bar"</span>,
|
||
<span class='string'>r"barfoo"</span>,
|
||
<span class='string'>r"foobar"</span>,
|
||
]).<span class='ident'>unwrap</span>();
|
||
|
||
<span class='comment'>// Iterate over and collect all of the matches.</span>
|
||
<span class='kw'>let</span> <span class='ident'>matches</span>: <span class='ident'>Vec</span><span class='op'><</span>_<span class='op'>></span> <span class='op'>=</span> <span class='ident'>set</span>.<span class='ident'>matches</span>(<span class='string'>"foobar"</span>).<span class='ident'>into_iter</span>().<span class='ident'>collect</span>();
|
||
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>matches</span>, <span class='macro'>vec</span><span class='macro'>!</span>[<span class='number'>0</span>, <span class='number'>2</span>, <span class='number'>3</span>, <span class='number'>4</span>, <span class='number'>6</span>]);
|
||
|
||
<span class='comment'>// You can also test whether a particular regex matched:</span>
|
||
<span class='kw'>let</span> <span class='ident'>matches</span> <span class='op'>=</span> <span class='ident'>set</span>.<span class='ident'>matches</span>(<span class='string'>"foobar"</span>);
|
||
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='op'>!</span><span class='ident'>matches</span>.<span class='ident'>matched</span>(<span class='number'>5</span>));
|
||
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>matches</span>.<span class='ident'>matched</span>(<span class='number'>6</span>));</pre>
|
||
|
||
<h1 id='pay-for-what-you-use' class='section-header'><a href='#pay-for-what-you-use'>Pay for what you use</a></h1>
|
||
<p>With respect to searching text with a regular expression, there are three
|
||
questions that can be asked:</p>
|
||
|
||
<ol>
|
||
<li>Does the text match this expression?</li>
|
||
<li>If so, where does it match?</li>
|
||
<li>Where are the submatches?</li>
|
||
</ol>
|
||
|
||
<p>Generally speaking, this crate could provide a function to answer only #3,
|
||
which would subsume #1 and #2 automatically. However, it can be
|
||
significantly more expensive to compute the location of submatches, so it's
|
||
best not to do it if you don't need to.</p>
|
||
|
||
<p>Therefore, only use what you need. For example, don't use <code>find</code> if you
|
||
only need to test if an expression matches a string. (Use <code>is_match</code>
|
||
instead.)</p>
|
||
|
||
<h1 id='unicode' class='section-header'><a href='#unicode'>Unicode</a></h1>
|
||
<p>This implementation executes regular expressions <strong>only</strong> on valid UTF-8
|
||
while exposing match locations as byte indices into the search string.</p>
|
||
|
||
<p>Only simple case folding is supported. Namely, when matching
|
||
case-insensitively, the characters are first mapped using the <a href="ftp://ftp.unicode.org/Public/UNIDATA/CaseFolding.txt">simple case
|
||
folding</a> mapping
|
||
before matching.</p>
|
||
|
||
<p>Regular expressions themselves are <strong>only</strong> interpreted as a sequence of
|
||
Unicode scalar values. This means you can use Unicode characters directly
|
||
in your expression:</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>re</span> <span class='op'>=</span> <span class='ident'>Regex</span>::<span class='ident'>new</span>(<span class='string'>r"(?i)Δ+"</span>).<span class='ident'>unwrap</span>();
|
||
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>re</span>.<span class='ident'>find</span>(<span class='string'>"ΔδΔ"</span>), <span class='prelude-val'>Some</span>((<span class='number'>0</span>, <span class='number'>6</span>)));</pre>
|
||
|
||
<p>Finally, Unicode general categories and scripts are available as character
|
||
classes. For example, you can match a sequence of numerals, Greek or
|
||
Cherokee letters:</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>re</span> <span class='op'>=</span> <span class='ident'>Regex</span>::<span class='ident'>new</span>(<span class='string'>r"[\pN\p{Greek}\p{Cherokee}]+"</span>).<span class='ident'>unwrap</span>();
|
||
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>re</span>.<span class='ident'>find</span>(<span class='string'>"abcΔᎠβⅠᏴγδⅡxyz"</span>), <span class='prelude-val'>Some</span>((<span class='number'>3</span>, <span class='number'>23</span>)));</pre>
|
||
|
||
<h1 id='opt-out-of-unicode-support' class='section-header'><a href='#opt-out-of-unicode-support'>Opt out of Unicode support</a></h1>
|
||
<p>The <code>bytes</code> sub-module provides a <code>Regex</code> type that can be used to match
|
||
on <code>&[u8]</code>. By default, text is interpreted as ASCII compatible text with
|
||
all Unicode support disabled (e.g., <code>.</code> matches any byte instead of any
|
||
Unicode codepoint). Unicode support can be selectively enabled with the
|
||
<code>u</code> flag. See the <code>bytes</code> module documentation for more details.</p>
|
||
|
||
<p>Unicode support can also be selectively <em>disabled</em> with the main <code>Regex</code>
|
||
type that matches on <code>&str</code>. For example, <code>(?-u:\b)</code> will match an ASCII
|
||
word boundary. Note though that invalid UTF-8 is not allowed to be matched
|
||
even when the <code>u</code> flag is disabled. For example, <code>(?-u:.)</code> will return an
|
||
error, since <code>.</code> matches <em>any byte</em> when Unicode support is disabled.</p>
|
||
|
||
<h1 id='syntax' class='section-header'><a href='#syntax'>Syntax</a></h1>
|
||
<p>The syntax supported in this crate is almost in an exact correspondence
|
||
with the syntax supported by RE2. It is documented below.</p>
|
||
|
||
<p>Note that the regular expression parser and abstract syntax are exposed in
|
||
a separate crate, <a href="../regex_syntax/index.html"><code>regex-syntax</code></a>.</p>
|
||
|
||
<h2 id='matching-one-character' class='section-header'><a href='#matching-one-character'>Matching one character</a></h2>
|
||
<pre class="rust">
|
||
. any character except new line (includes new line with s flag)
|
||
[xyz] A character class matching either x, y or z.
|
||
[^xyz] A character class matching any character except x, y and z.
|
||
[a-z] A character class matching any character in range a-z.
|
||
\d digit (\p{Nd})
|
||
\D not digit
|
||
[:alpha:] ASCII character class ([A-Za-z])
|
||
[:^alpha:] Negated ASCII character class ([^A-Za-z])
|
||
\pN One-letter name Unicode character class
|
||
\p{Greek} Unicode character class (general category or script)
|
||
\PN Negated one-letter name Unicode character class
|
||
\P{Greek} negated Unicode character class (general category or script)
|
||
</pre>
|
||
|
||
<p>Any named character class may appear inside a bracketed <code>[...]</code> character
|
||
class. For example, <code>[\p{Greek}\pN]</code> matches any Greek or numeral
|
||
character.</p>
|
||
|
||
<h2 id='composites' class='section-header'><a href='#composites'>Composites</a></h2>
|
||
<pre class="rust">
|
||
xy concatenation (x followed by y)
|
||
x|y alternation (x or y, prefer x)
|
||
</pre>
|
||
|
||
<h2 id='repetitions' class='section-header'><a href='#repetitions'>Repetitions</a></h2>
|
||
<pre class="rust">
|
||
x* zero or more of x (greedy)
|
||
x+ one or more of x (greedy)
|
||
x? zero or one of x (greedy)
|
||
x*? zero or more of x (ungreedy/lazy)
|
||
x+? one or more of x (ungreedy/lazy)
|
||
x?? zero or one of x (ungreedy/lazy)
|
||
x{n,m} at least n x and at most m x (greedy)
|
||
x{n,} at least n x (greedy)
|
||
x{n} exactly n x
|
||
x{n,m}? at least n x and at most m x (ungreedy/lazy)
|
||
x{n,}? at least n x (ungreedy/lazy)
|
||
x{n}? exactly n x
|
||
</pre>
|
||
|
||
<h2 id='empty-matches' class='section-header'><a href='#empty-matches'>Empty matches</a></h2>
|
||
<pre class="rust">
|
||
^ the beginning of text (or start-of-line with multi-line mode)
|
||
$ the end of text (or end-of-line with multi-line mode)
|
||
\A only the beginning of text (even with multi-line mode enabled)
|
||
\z only the end of text (even with multi-line mode enabled)
|
||
\b a Unicode word boundary (\w on one side and \W, \A, or \z on other)
|
||
\B not a Unicode word boundary
|
||
</pre>
|
||
|
||
<h2 id='grouping-and-flags' class='section-header'><a href='#grouping-and-flags'>Grouping and flags</a></h2>
|
||
<pre class="rust">
|
||
(exp) numbered capture group (indexed by opening parenthesis)
|
||
(?P<name>exp) named (also numbered) capture group (allowed chars: [_0-9a-zA-Z])
|
||
(?:exp) non-capturing group
|
||
(?flags) set flags within current group
|
||
(?flags:exp) set flags for exp (non-capturing)
|
||
</pre>
|
||
|
||
<p>Flags are each a single character. For example, <code>(?x)</code> sets the flag <code>x</code>
|
||
and <code>(?-x)</code> clears the flag <code>x</code>. Multiple flags can be set or cleared at
|
||
the same time: <code>(?xy)</code> sets both the <code>x</code> and <code>y</code> flags and <code>(?x-y)</code> sets
|
||
the <code>x</code> flag and clears the <code>y</code> flag.</p>
|
||
|
||
<p>All flags are by default disabled unless stated otherwise. They are:</p>
|
||
|
||
<pre class="rust">
|
||
i case-insensitive
|
||
m multi-line mode: ^ and $ match begin/end of line
|
||
s allow . to match \n
|
||
U swap the meaning of x* and x*?
|
||
u Unicode support (enabled by default)
|
||
x ignore whitespace and allow line comments (starting with `#`)
|
||
</pre>
|
||
|
||
<p>Here's an example that matches case-insensitively for only part of the
|
||
expression:</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>re</span> <span class='op'>=</span> <span class='ident'>Regex</span>::<span class='ident'>new</span>(<span class='string'>r"(?i)a+(?-i)b+"</span>).<span class='ident'>unwrap</span>();
|
||
<span class='kw'>let</span> <span class='ident'>cap</span> <span class='op'>=</span> <span class='ident'>re</span>.<span class='ident'>captures</span>(<span class='string'>"AaAaAbbBBBb"</span>).<span class='ident'>unwrap</span>();
|
||
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>cap</span>.<span class='ident'>at</span>(<span class='number'>0</span>), <span class='prelude-val'>Some</span>(<span class='string'>"AaAaAbb"</span>));</pre>
|
||
|
||
<p>Notice that the <code>a+</code> matches either <code>a</code> or <code>A</code>, but the <code>b+</code> only matches
|
||
<code>b</code>.</p>
|
||
|
||
<p>Here is an example that uses an ASCII word boundary instead of a Unicode
|
||
word boundary:</p>
|
||
|
||
<pre class='rust rust-example-rendered'>
|
||
<span class='kw'>let</span> <span class='ident'>re</span> <span class='op'>=</span> <span class='ident'>Regex</span>::<span class='ident'>new</span>(<span class='string'>r"(?-u:\b).+(?-u:\b)"</span>).<span class='ident'>unwrap</span>();
|
||
<span class='kw'>let</span> <span class='ident'>cap</span> <span class='op'>=</span> <span class='ident'>re</span>.<span class='ident'>captures</span>(<span class='string'>"$$abc$$"</span>).<span class='ident'>unwrap</span>();
|
||
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>cap</span>.<span class='ident'>at</span>(<span class='number'>0</span>), <span class='prelude-val'>Some</span>(<span class='string'>"abc"</span>));</pre>
|
||
|
||
<h2 id='escape-sequences' class='section-header'><a href='#escape-sequences'>Escape sequences</a></h2>
|
||
<pre class="rust">
|
||
\* literal *, works for any punctuation character: \.+*?()|[]{}^$
|
||
\a bell (\x07)
|
||
\f form feed (\x0C)
|
||
\t horizontal tab
|
||
\n new line
|
||
\r carriage return
|
||
\v vertical tab (\x0B)
|
||
\123 octal character code (up to three digits)
|
||
\x7F hex character code (exactly two digits)
|
||
\x{10FFFF} any hex character code corresponding to a Unicode code point
|
||
</pre>
|
||
|
||
<h2 id='perl-character-classes-unicode-friendly' class='section-header'><a href='#perl-character-classes-unicode-friendly'>Perl character classes (Unicode friendly)</a></h2>
|
||
<p>These classes are based on the definitions provided in
|
||
<a href="http://www.unicode.org/reports/tr18/#Compatibility_Properties">UTS#18</a>:</p>
|
||
|
||
<pre class="rust">
|
||
\d digit (\p{Nd})
|
||
\D not digit
|
||
\s whitespace (\p{White_Space})
|
||
\S not whitespace
|
||
\w word character (\p{Alphabetic} + \p{M} + \d + \p{Pc} + \p{Join_Control})
|
||
\W not word character
|
||
</pre>
|
||
|
||
<h2 id='ascii-character-classes' class='section-header'><a href='#ascii-character-classes'>ASCII character classes</a></h2>
|
||
<pre class="rust">
|
||
[:alnum:] alphanumeric ([0-9A-Za-z])
|
||
[:alpha:] alphabetic ([A-Za-z])
|
||
[:ascii:] ASCII ([\x00-\x7F])
|
||
[:blank:] blank ([\t ])
|
||
[:cntrl:] control ([\x00-\x1F\x7F])
|
||
[:digit:] digits ([0-9])
|
||
[:graph:] graphical ([!-~])
|
||
[:lower:] lower case ([a-z])
|
||
[:print:] printable ([ -~])
|
||
[:punct:] punctuation ([!-/:-@[-`{-~])
|
||
[:space:] whitespace ([\t\n\v\f\r ])
|
||
[:upper:] upper case ([A-Z])
|
||
[:word:] word characters ([0-9A-Za-z_])
|
||
[:xdigit:] hex digit ([0-9A-Fa-f])
|
||
</pre>
|
||
|
||
<h1 id='untrusted-input' class='section-header'><a href='#untrusted-input'>Untrusted input</a></h1>
|
||
<p>This crate can handle both untrusted regular expressions and untrusted
|
||
search text.</p>
|
||
|
||
<p>Untrusted regular expressions are handled by capping the size of a compiled
|
||
regular expression. (See <code>Regex::with_size_limit</code>.) Without this, it would
|
||
be trivial for an attacker to exhaust your system's memory with expressions
|
||
like <code>a{100}{100}{100}</code>.</p>
|
||
|
||
<p>Untrusted search text is allowed because the matching engine(s) in this
|
||
crate have time complexity <code>O(mn)</code> (with <code>m ~ regex</code> and <code>n ~ search text</code>), which means there's no way to cause exponential blow-up like with
|
||
some other regular expression engines. (We pay for this by disallowing
|
||
features like arbitrary look-ahead and backreferences.)</p>
|
||
|
||
<p>When a DFA is used, pathological cases with exponential state blow up are
|
||
avoided by constructing the DFA lazily or in an "online" manner. Therefore,
|
||
at most one new state can be created for each byte of input. This satisfies
|
||
our time complexity guarantees, but can lead to unbounded memory growth
|
||
proportional to the size of the input. As a stopgap, the DFA is only
|
||
allowed to store a fixed number of states. (When the limit is reached, its
|
||
states are wiped and continues on, possibly duplicating previous work. If
|
||
the limit is reached too frequently, it gives up and hands control of to
|
||
another matching engine with fixed memory requirements.)</p>
|
||
</div><h2 id='modules' class='section-header'><a href="#modules">Modules</a></h2>
|
||
<table>
|
||
<tr class=' module-item'>
|
||
<td><a class='mod' href='bytes/index.html'
|
||
title='regex::bytes'>bytes</a></td>
|
||
<td class='docblock short'>
|
||
<p>Match regular expressions on arbitrary bytes.</p>
|
||
</td>
|
||
</tr></table><h2 id='structs' class='section-header'><a href="#structs">Structs</a></h2>
|
||
<table>
|
||
<tr class=' module-item'>
|
||
<td><a class='struct' href='struct.CaptureNames.html'
|
||
title='regex::CaptureNames'>CaptureNames</a></td>
|
||
<td class='docblock short'>
|
||
<p>An iterator over the names of all possible captures.</p>
|
||
</td>
|
||
</tr>
|
||
<tr class=' module-item'>
|
||
<td><a class='struct' href='struct.Captures.html'
|
||
title='regex::Captures'>Captures</a></td>
|
||
<td class='docblock short'>
|
||
<p>Captures represents a group of captured strings for a single match.</p>
|
||
</td>
|
||
</tr>
|
||
<tr class=' module-item'>
|
||
<td><a class='struct' href='struct.FindCaptures.html'
|
||
title='regex::FindCaptures'>FindCaptures</a></td>
|
||
<td class='docblock short'>
|
||
<p>An iterator that yields all non-overlapping capture groups matching a
|
||
particular regular expression.</p>
|
||
</td>
|
||
</tr>
|
||
<tr class=' module-item'>
|
||
<td><a class='struct' href='struct.FindMatches.html'
|
||
title='regex::FindMatches'>FindMatches</a></td>
|
||
<td class='docblock short'>
|
||
<p>An iterator over all non-overlapping matches for a particular string.</p>
|
||
</td>
|
||
</tr>
|
||
<tr class=' module-item'>
|
||
<td><a class='struct' href='struct.NoExpand.html'
|
||
title='regex::NoExpand'>NoExpand</a></td>
|
||
<td class='docblock short'>
|
||
<p>NoExpand indicates literal string replacement.</p>
|
||
</td>
|
||
</tr>
|
||
<tr class=' module-item'>
|
||
<td><a class='struct' href='struct.Regex.html'
|
||
title='regex::Regex'>Regex</a></td>
|
||
<td class='docblock short'>
|
||
<p>A compiled regular expression for matching Unicode strings.</p>
|
||
</td>
|
||
</tr>
|
||
<tr class=' module-item'>
|
||
<td><a class='struct' href='struct.RegexBuilder.html'
|
||
title='regex::RegexBuilder'>RegexBuilder</a></td>
|
||
<td class='docblock short'>
|
||
<p>A configurable builder for a regular expression.</p>
|
||
</td>
|
||
</tr>
|
||
<tr class=' module-item'>
|
||
<td><a class='struct' href='struct.RegexSet.html'
|
||
title='regex::RegexSet'>RegexSet</a></td>
|
||
<td class='docblock short'>
|
||
<p>Match multiple (possibly overlapping) regular expressions in a single scan.</p>
|
||
</td>
|
||
</tr>
|
||
<tr class=' module-item'>
|
||
<td><a class='struct' href='struct.RegexSplits.html'
|
||
title='regex::RegexSplits'>RegexSplits</a></td>
|
||
<td class='docblock short'>
|
||
<p>Yields all substrings delimited by a regular expression match.</p>
|
||
</td>
|
||
</tr>
|
||
<tr class=' module-item'>
|
||
<td><a class='struct' href='struct.RegexSplitsN.html'
|
||
title='regex::RegexSplitsN'>RegexSplitsN</a></td>
|
||
<td class='docblock short'>
|
||
<p>Yields at most <code>N</code> substrings delimited by a regular expression match.</p>
|
||
</td>
|
||
</tr>
|
||
<tr class=' module-item'>
|
||
<td><a class='struct' href='struct.SetMatches.html'
|
||
title='regex::SetMatches'>SetMatches</a></td>
|
||
<td class='docblock short'>
|
||
<p>A set of matches returned by a regex set.</p>
|
||
</td>
|
||
</tr>
|
||
<tr class=' module-item'>
|
||
<td><a class='struct' href='struct.SetMatchesIntoIter.html'
|
||
title='regex::SetMatchesIntoIter'>SetMatchesIntoIter</a></td>
|
||
<td class='docblock short'>
|
||
<p>An owned iterator over the set of matches from a regex set.</p>
|
||
</td>
|
||
</tr>
|
||
<tr class=' module-item'>
|
||
<td><a class='struct' href='struct.SetMatchesIter.html'
|
||
title='regex::SetMatchesIter'>SetMatchesIter</a></td>
|
||
<td class='docblock short'>
|
||
<p>A borrowed iterator over the set of matches from a regex set.</p>
|
||
</td>
|
||
</tr>
|
||
<tr class=' module-item'>
|
||
<td><a class='struct' href='struct.SubCaptures.html'
|
||
title='regex::SubCaptures'>SubCaptures</a></td>
|
||
<td class='docblock short'>
|
||
<p>An iterator over capture groups for a particular match of a regular
|
||
expression.</p>
|
||
</td>
|
||
</tr>
|
||
<tr class=' module-item'>
|
||
<td><a class='struct' href='struct.SubCapturesNamed.html'
|
||
title='regex::SubCapturesNamed'>SubCapturesNamed</a></td>
|
||
<td class='docblock short'>
|
||
<p>An Iterator over named capture groups as a tuple with the group
|
||
name and the value.</p>
|
||
</td>
|
||
</tr>
|
||
<tr class=' module-item'>
|
||
<td><a class='struct' href='struct.SubCapturesPos.html'
|
||
title='regex::SubCapturesPos'>SubCapturesPos</a></td>
|
||
<td class='docblock short'>
|
||
<p>An iterator over capture group positions for a particular match of a
|
||
regular expression.</p>
|
||
</td>
|
||
</tr></table><h2 id='enums' class='section-header'><a href="#enums">Enums</a></h2>
|
||
<table>
|
||
<tr class=' module-item'>
|
||
<td><a class='enum' href='enum.Error.html'
|
||
title='regex::Error'>Error</a></td>
|
||
<td class='docblock short'>
|
||
<p>An error that occurred during parsing or compiling a regular expression.</p>
|
||
</td>
|
||
</tr></table><h2 id='traits' class='section-header'><a href="#traits">Traits</a></h2>
|
||
<table>
|
||
<tr class=' module-item'>
|
||
<td><a class='trait' href='trait.Replacer.html'
|
||
title='regex::Replacer'>Replacer</a></td>
|
||
<td class='docblock short'>
|
||
<p>Replacer describes types that can be used to replace matches in a string.</p>
|
||
</td>
|
||
</tr></table><h2 id='functions' class='section-header'><a href="#functions">Functions</a></h2>
|
||
<table>
|
||
<tr class=' module-item'>
|
||
<td><a class='fn' href='fn.is_match.html'
|
||
title='regex::is_match'>is_match</a></td>
|
||
<td class='docblock short'>
|
||
<p>Tests if the given regular expression matches somewhere in the text given.</p>
|
||
</td>
|
||
</tr>
|
||
<tr class=' module-item'>
|
||
<td><a class='fn' href='fn.quote.html'
|
||
title='regex::quote'>quote</a></td>
|
||
<td class='docblock short'>
|
||
<p>Escapes all regular expression meta characters in <code>text</code>.</p>
|
||
</td>
|
||
</tr></table></section>
|
||
<section id='search' class="content hidden"></section>
|
||
|
||
<section class="footer"></section>
|
||
|
||
<aside id="help" class="hidden">
|
||
<div>
|
||
<h1 class="hidden">Help</h1>
|
||
|
||
<div class="shortcuts">
|
||
<h2>Keyboard Shortcuts</h2>
|
||
|
||
<dl>
|
||
<dt>?</dt>
|
||
<dd>Show this help dialog</dd>
|
||
<dt>S</dt>
|
||
<dd>Focus the search field</dd>
|
||
<dt>⇤</dt>
|
||
<dd>Move up in search results</dd>
|
||
<dt>⇥</dt>
|
||
<dd>Move down in search results</dd>
|
||
<dt>⏎</dt>
|
||
<dd>Go to active search result</dd>
|
||
</dl>
|
||
</div>
|
||
|
||
<div class="infos">
|
||
<h2>Search Tricks</h2>
|
||
|
||
<p>
|
||
Prefix searches with a type followed by a colon (e.g.
|
||
<code>fn:</code>) to restrict the search to a given type.
|
||
</p>
|
||
|
||
<p>
|
||
Accepted types are: <code>fn</code>, <code>mod</code>,
|
||
<code>struct</code>, <code>enum</code>,
|
||
<code>trait</code>, <code>type</code>, <code>macro</code>,
|
||
and <code>const</code>.
|
||
</p>
|
||
|
||
<p>
|
||
Search functions by type signature (e.g.
|
||
<code>vec -> usize</code> or <code>* -> vec</code>)
|
||
</p>
|
||
</div>
|
||
</div>
|
||
</aside>
|
||
|
||
|
||
|
||
<script>
|
||
window.rootPath = "../";
|
||
window.currentCrate = "regex";
|
||
window.playgroundUrl = "";
|
||
</script>
|
||
<script src="../jquery.js"></script>
|
||
<script src="../main.js"></script>
|
||
|
||
<script defer src="../search-index.js"></script>
|
||
</body>
|
||
</html> |