diff options
| author | 2015-06-29 20:16:15 +0000 | |
|---|---|---|
| committer | 2015-06-29 20:16:15 +0000 | |
| commit | 64106c4d3d4ddba8c7bc2af75376e6d3d3d75601 (patch) | |
| tree | 8c64d6e8be006486d975a651505fbbde61365cd6 /regex/enum.Regex.html | |
| download | irsc-gh-pages.tar.gz irsc-gh-pages.tar.xz irsc-gh-pages.zip | |
Update documentationgh-pages
Diffstat (limited to 'regex/enum.Regex.html')
| -rw-r--r-- | regex/enum.Regex.html | 401 |
1 files changed, 401 insertions, 0 deletions
diff --git a/regex/enum.Regex.html b/regex/enum.Regex.html new file mode 100644 index 0000000..ba1e058 --- /dev/null +++ b/regex/enum.Regex.html @@ -0,0 +1,401 @@ +<!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` enum in crate `regex`."> + <meta name="keywords" content="rust, rustlang, rust-lang, Regex"> + + <title>regex::Regex - Rust</title> + + <link rel="stylesheet" type="text/css" href="../main.css"> + + <link rel="shortcut icon" href="http://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]--> + + + + <section class="sidebar"> + <a href='../regex/index.html'><img src='http://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png' alt='' width='100'></a> + <p class='location'><a href='index.html'>regex</a></p><script>window.sidebarCurrent = {name: 'Regex', ty: 'enum', relpath: ''};</script><script defer src="sidebar-items.js"></script> + </section> + + <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 enum"> +<h1 class='fqn'><span class='in-band'>Enum <a href='index.html'>regex</a>::<wbr><a class='enum' 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-7629' class='srclink' href='../src/regex/re.rs.html#169-179' title='goto source code'>[src]</a></span></h1> +<pre class='rust enum'>pub enum Regex { + // some variants omitted +}</pre><div class='docblock'><p>A compiled regular expression</p> + +<p>It is represented as either a sequence of bytecode instructions (dynamic) +or as a specialized Rust function (native). It can be used to search, split +or replace text. All searching is done with an implicit <code>.*?</code> at the +beginning and end of an expression. To force an expression to match the +whole string (or a prefix or a suffix), you must use an anchor like <code>^</code> or +<code>$</code> (or <code>\A</code> and <code>\z</code>).</p> + +<p>While this crate will handle Unicode strings (whether in the regular +expression or in the search text), all positions returned are <strong>byte +indices</strong>. Every byte index is guaranteed to be at a Unicode code point +boundary.</p> + +<p>The lifetimes <code>'r</code> and <code>'t</code> in this crate correspond to the lifetime of a +compiled regular expression and text to search, respectively.</p> + +<p>The only methods that allocate new strings are the string replacement +methods. All other methods (searching and splitting) return borrowed +pointers into the string given.</p> + +<h1 id="examples" class='section-header'><a + href="#examples">Examples</a></h1> +<p>Find the location of a US phone number:</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'>"[0-9]{3}-[0-9]{3}-[0-9]{4}"</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'>"phone: 111-222-3333"</span>), <span class='prelude-val'>Some</span>((<span class='number'>7</span>, <span class='number'>19</span>))); +</pre> + +<h1 id="using-the-std::str::strext-methods-with-regex" class='section-header'><a + href="#using-the-std::str::strext-methods-with-regex">Using the <code>std::str::StrExt</code> methods with <code>Regex</code></a></h1> +<blockquote> +<p><strong>Note</strong>: This section requires that this crate is currently compiled with + the <code>pattern</code> Cargo feature enabled.</p> +</blockquote> + +<p>Since <code>Regex</code> implements <code>Pattern</code>, you can use regexes with methods +defined on <code>std::str::StrExt</code>. For example, <code>is_match</code>, <code>find</code>, <code>find_iter</code> +and <code>split</code> can be replaced with <code>StrExt::contains</code>, <code>StrExt::find</code>, +<code>StrExt::match_indices</code> and <code>StrExt::split</code>.</p> + +<p>Here are some examples:</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+"</span>).<span class='ident'>unwrap</span>(); +<span class='kw'>let</span> <span class='ident'>haystack</span> <span class='op'>=</span> <span class='string'>"a111b222c"</span>; + +<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>haystack</span>.<span class='ident'>contains</span>(<span class='kw-2'>&</span><span class='ident'>re</span>)); +<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>haystack</span>.<span class='ident'>find</span>(<span class='kw-2'>&</span><span class='ident'>re</span>), <span class='prelude-val'>Some</span>(<span class='number'>1</span>)); +<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>haystack</span>.<span class='ident'>match_indices</span>(<span class='kw-2'>&</span><span class='ident'>re</span>).<span class='ident'>collect</span>::<span class='op'><</span><span class='ident'>Vec</span><span class='op'><</span>_<span class='op'>>></span>(), + <span class='macro'>vec</span><span class='macro'>!</span>[(<span class='number'>1</span>, <span class='number'>4</span>), (<span class='number'>5</span>, <span class='number'>8</span>)]); +<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>haystack</span>.<span class='ident'>split</span>(<span class='kw-2'>&</span><span class='ident'>re</span>).<span class='ident'>collect</span>::<span class='op'><</span><span class='ident'>Vec</span><span class='op'><</span>_<span class='op'>>></span>(), <span class='macro'>vec</span><span class='macro'>!</span>[<span class='string'>"a"</span>, <span class='string'>"b"</span>, <span class='string'>"c"</span>]); +</pre> +</div><h2 id='methods'>Methods</h2><h3 class='impl'><code>impl <a class='enum' href='../regex/enum.Regex.html' title='regex::Regex'>Regex</a></code></h3><div class='impl-items'><h4 id='method.new' class='method'><code>fn <a href='#method.new' class='fnname'>new</a>(re: &<a href='http://doc.rust-lang.org/nightly/std/primitive.str.html'>str</a>) -> <a class='enum' href='http://doc.rust-lang.org/nightly/core/result/enum.Result.html' title='core::result::Result'>Result</a><<a class='enum' href='../regex/enum.Regex.html' title='regex::Regex'>Regex</a>, <a class='enum' href='../regex/enum.Error.html' title='regex::Error'>Error</a>></code></h4> +<div class='docblock'><p>Compiles a dynamic regular expression. Once compiled, it can be +used repeatedly to search, split or replace text in a string.</p> + +<p>If an invalid expression is given, then an error is returned.</p> +</div><h4 id='method.with_size_limit' class='method'><code>fn <a href='#method.with_size_limit' class='fnname'>with_size_limit</a>(size: <a href='http://doc.rust-lang.org/nightly/std/primitive.usize.html'>usize</a>, re: &<a href='http://doc.rust-lang.org/nightly/std/primitive.str.html'>str</a>) -> <a class='enum' href='http://doc.rust-lang.org/nightly/core/result/enum.Result.html' title='core::result::Result'>Result</a><<a class='enum' href='../regex/enum.Regex.html' title='regex::Regex'>Regex</a>, <a class='enum' href='../regex/enum.Error.html' title='regex::Error'>Error</a>></code></h4> +<div class='docblock'><p>Compiles a dynamic regular expression with the given size limit.</p> + +<p>The size limit is applied to the size of the <em>compiled</em> data structure. +If the data structure exceeds the size given, then an error is +returned.</p> + +<p>The default size limit used in <code>new</code> is 10MB.</p> +</div><h4 id='method.is_match' class='method'><code>fn <a href='#method.is_match' class='fnname'>is_match</a>(&self, text: &<a href='http://doc.rust-lang.org/nightly/std/primitive.str.html'>str</a>) -> <a href='http://doc.rust-lang.org/nightly/std/primitive.bool.html'>bool</a></code></h4> +<div class='docblock'><p>Returns true if and only if the regex matches the string given.</p> + +<h1 id="example" class='section-header'><a + href="#example">Example</a></h1> +<p>Test if some text contains at least one word with exactly 13 +characters:</p> +<pre class='rust rust-example-rendered'> +<span class='kw'>let</span> <span class='ident'>text</span> <span class='op'>=</span> <span class='string'>"I categorically deny having triskaidekaphobia."</span>; +<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>Regex</span>::<span class='ident'>new</span>(<span class='string'>r"\b\w{13}\b"</span>).<span class='ident'>unwrap</span>().<span class='ident'>is_match</span>(<span class='ident'>text</span>)); +</pre> +</div><h4 id='method.find' class='method'><code>fn <a href='#method.find' class='fnname'>find</a>(&self, text: &<a href='http://doc.rust-lang.org/nightly/std/primitive.str.html'>str</a>) -> <a class='enum' href='http://doc.rust-lang.org/nightly/core/option/enum.Option.html' title='core::option::Option'>Option</a><<a href='http://doc.rust-lang.org/nightly/std/primitive.tuple.html'>(<a href='http://doc.rust-lang.org/nightly/std/primitive.usize.html'>usize</a>, <a href='http://doc.rust-lang.org/nightly/std/primitive.usize.html'>usize</a>)</a>></code></h4> +<div class='docblock'><p>Returns the start and end byte range of the leftmost-first match in +<code>text</code>. If no match exists, then <code>None</code> is returned.</p> + +<p>Note that this should only be used if you want to discover the position +of the match. Testing the existence of a match is faster if you use +<code>is_match</code>.</p> + +<h1 id="example" class='section-header'><a + href="#example">Example</a></h1> +<p>Find the start and end location of the first word with exactly 13 +characters:</p> +<pre class='rust rust-example-rendered'> +<span class='kw'>let</span> <span class='ident'>text</span> <span class='op'>=</span> <span class='string'>"I categorically deny having triskaidekaphobia."</span>; +<span class='kw'>let</span> <span class='ident'>pos</span> <span class='op'>=</span> <span class='ident'>Regex</span>::<span class='ident'>new</span>(<span class='string'>r"\b\w{13}\b"</span>).<span class='ident'>unwrap</span>().<span class='ident'>find</span>(<span class='ident'>text</span>); +<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>pos</span>, <span class='prelude-val'>Some</span>((<span class='number'>2</span>, <span class='number'>15</span>))); +</pre> +</div><h4 id='method.find_iter' class='method'><code>fn <a href='#method.find_iter' class='fnname'>find_iter</a><'r, 't>(&'r self, text: &'t <a href='http://doc.rust-lang.org/nightly/std/primitive.str.html'>str</a>) -> <a class='struct' href='../regex/struct.FindMatches.html' title='regex::FindMatches'>FindMatches</a><'r, 't></code></h4> +<div class='docblock'><p>Returns an iterator for each successive non-overlapping match in +<code>text</code>, returning the start and end byte indices with respect to +<code>text</code>.</p> + +<h1 id="example" class='section-header'><a + href="#example">Example</a></h1> +<p>Find the start and end location of every word with exactly 13 +characters:</p> +<pre class='rust rust-example-rendered'> +<span class='kw'>let</span> <span class='ident'>text</span> <span class='op'>=</span> <span class='string'>"Retroactively relinquishing remunerations is reprehensible."</span>; +<span class='kw'>for</span> <span class='ident'>pos</span> <span class='kw'>in</span> <span class='ident'>Regex</span>::<span class='ident'>new</span>(<span class='string'>r"\b\w{13}\b"</span>).<span class='ident'>unwrap</span>().<span class='ident'>find_iter</span>(<span class='ident'>text</span>) { + <span class='macro'>println</span><span class='macro'>!</span>(<span class='string'>"{:?}"</span>, <span class='ident'>pos</span>); +} +<span class='comment'>// Output:</span> +<span class='comment'>// (0, 13)</span> +<span class='comment'>// (14, 27)</span> +<span class='comment'>// (28, 41)</span> +<span class='comment'>// (45, 58)</span> +</pre> +</div><h4 id='method.captures' class='method'><code>fn <a href='#method.captures' class='fnname'>captures</a><'t>(&self, text: &'t <a href='http://doc.rust-lang.org/nightly/std/primitive.str.html'>str</a>) -> <a class='enum' href='http://doc.rust-lang.org/nightly/core/option/enum.Option.html' title='core::option::Option'>Option</a><<a class='struct' href='../regex/struct.Captures.html' title='regex::Captures'>Captures</a><'t>></code></h4> +<div class='docblock'><p>Returns the capture groups corresponding to the leftmost-first +match in <code>text</code>. Capture group <code>0</code> always corresponds to the entire +match. If no match is found, then <code>None</code> is returned.</p> + +<p>You should only use <code>captures</code> if you need access to submatches. +Otherwise, <code>find</code> is faster for discovering the location of the overall +match.</p> + +<h1 id="examples" class='section-header'><a + href="#examples">Examples</a></h1> +<p>Say you have some text with movie names and their release years, +like "'Citizen Kane' (1941)". It'd be nice if we could search for text +looking like that, while also extracting the movie name and its release +year separately.</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"'([^']+)'\s+\((\d{4})\)"</span>).<span class='ident'>unwrap</span>(); +<span class='kw'>let</span> <span class='ident'>text</span> <span class='op'>=</span> <span class='string'>"Not my favorite movie: 'Citizen Kane' (1941)."</span>; +<span class='kw'>let</span> <span class='ident'>caps</span> <span class='op'>=</span> <span class='ident'>re</span>.<span class='ident'>captures</span>(<span class='ident'>text</span>).<span class='ident'>unwrap</span>(); +<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>caps</span>.<span class='ident'>at</span>(<span class='number'>1</span>), <span class='prelude-val'>Some</span>(<span class='string'>"Citizen Kane"</span>)); +<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>caps</span>.<span class='ident'>at</span>(<span class='number'>2</span>), <span class='prelude-val'>Some</span>(<span class='string'>"1941"</span>)); +<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>caps</span>.<span class='ident'>at</span>(<span class='number'>0</span>), <span class='prelude-val'>Some</span>(<span class='string'>"'Citizen Kane' (1941)"</span>)); +</pre> + +<p>Note that the full match is at capture group <code>0</code>. Each subsequent +capture group is indexed by the order of its opening <code>(</code>.</p> + +<p>We can make this example a bit clearer by using <em>named</em> capture groups:</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<title>[^']+)'\s+\((?P<year>\d{4})\)"</span>) + .<span class='ident'>unwrap</span>(); +<span class='kw'>let</span> <span class='ident'>text</span> <span class='op'>=</span> <span class='string'>"Not my favorite movie: 'Citizen Kane' (1941)."</span>; +<span class='kw'>let</span> <span class='ident'>caps</span> <span class='op'>=</span> <span class='ident'>re</span>.<span class='ident'>captures</span>(<span class='ident'>text</span>).<span class='ident'>unwrap</span>(); +<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>caps</span>.<span class='ident'>name</span>(<span class='string'>"title"</span>), <span class='prelude-val'>Some</span>(<span class='string'>"Citizen Kane"</span>)); +<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>caps</span>.<span class='ident'>name</span>(<span class='string'>"year"</span>), <span class='prelude-val'>Some</span>(<span class='string'>"1941"</span>)); +<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>caps</span>.<span class='ident'>at</span>(<span class='number'>0</span>), <span class='prelude-val'>Some</span>(<span class='string'>"'Citizen Kane' (1941)"</span>)); +</pre> + +<p>Here we name the capture groups, which we can access with the <code>name</code> +method. Note that the named capture groups are still accessible with +<code>at</code>.</p> + +<p>The <code>0</code>th capture group is always unnamed, so it must always be +accessed with <code>at(0)</code>.</p> +</div><h4 id='method.captures_iter' class='method'><code>fn <a href='#method.captures_iter' class='fnname'>captures_iter</a><'r, 't>(&'r self, text: &'t <a href='http://doc.rust-lang.org/nightly/std/primitive.str.html'>str</a>) -> <a class='struct' href='../regex/struct.FindCaptures.html' title='regex::FindCaptures'>FindCaptures</a><'r, 't></code></h4> +<div class='docblock'><p>Returns an iterator over all the non-overlapping capture groups matched +in <code>text</code>. This is operationally the same as <code>find_iter</code> (except it +yields information about submatches).</p> + +<h1 id="example" class='section-header'><a + href="#example">Example</a></h1> +<p>We can use this to find all movie titles and their release years in +some text, where the movie is formatted like "'Title' (xxxx)":</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<title>[^']+)'\s+\((?P<year>\d{4})\)"</span>) + .<span class='ident'>unwrap</span>(); +<span class='kw'>let</span> <span class='ident'>text</span> <span class='op'>=</span> <span class='string'>"'Citizen Kane' (1941), 'The Wizard of Oz' (1939), 'M' (1931)."</span>; +<span class='kw'>for</span> <span class='ident'>caps</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'>"Movie: {:?}, Released: {:?}"</span>, <span class='ident'>caps</span>.<span class='ident'>name</span>(<span class='string'>"title"</span>), <span class='ident'>caps</span>.<span class='ident'>name</span>(<span class='string'>"year"</span>)); +} +<span class='comment'>// Output:</span> +<span class='comment'>// Movie: Citizen Kane, Released: 1941</span> +<span class='comment'>// Movie: The Wizard of Oz, Released: 1939</span> +<span class='comment'>// Movie: M, Released: 1931</span> +</pre> +</div><h4 id='method.split' class='method'><code>fn <a href='#method.split' class='fnname'>split</a><'r, 't>(&'r self, text: &'t <a href='http://doc.rust-lang.org/nightly/std/primitive.str.html'>str</a>) -> <a class='struct' href='../regex/struct.RegexSplits.html' title='regex::RegexSplits'>RegexSplits</a><'r, 't></code></h4> +<div class='docblock'><p>Returns an iterator of substrings of <code>text</code> delimited by a match +of the regular expression. +Namely, each element of the iterator corresponds to text that <em>isn't</em> +matched by the regular expression.</p> + +<p>This method will <em>not</em> copy the text given.</p> + +<h1 id="example" class='section-header'><a + href="#example">Example</a></h1> +<p>To split a string delimited by arbitrary amounts of spaces or tabs:</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"[ \t]+"</span>).<span class='ident'>unwrap</span>(); +<span class='kw'>let</span> <span class='ident'>fields</span>: <span class='ident'>Vec</span><span class='op'><</span><span class='kw-2'>&</span><span class='ident'>str</span><span class='op'>></span> <span class='op'>=</span> <span class='ident'>re</span>.<span class='ident'>split</span>(<span class='string'>"a b \t c\td e"</span>).<span class='ident'>collect</span>(); +<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>fields</span>, <span class='macro'>vec</span><span class='macro'>!</span>(<span class='string'>"a"</span>, <span class='string'>"b"</span>, <span class='string'>"c"</span>, <span class='string'>"d"</span>, <span class='string'>"e"</span>)); +</pre> +</div><h4 id='method.splitn' class='method'><code>fn <a href='#method.splitn' class='fnname'>splitn</a><'r, 't>(&'r self, text: &'t <a href='http://doc.rust-lang.org/nightly/std/primitive.str.html'>str</a>, limit: <a href='http://doc.rust-lang.org/nightly/std/primitive.usize.html'>usize</a>) -> <a class='struct' href='../regex/struct.RegexSplitsN.html' title='regex::RegexSplitsN'>RegexSplitsN</a><'r, 't></code></h4> +<div class='docblock'><p>Returns an iterator of at most <code>limit</code> substrings of <code>text</code> delimited +by a match of the regular expression. (A <code>limit</code> of <code>0</code> will return no +substrings.) +Namely, each element of the iterator corresponds to text that <em>isn't</em> +matched by the regular expression. +The remainder of the string that is not split will be the last element +in the iterator.</p> + +<p>This method will <em>not</em> copy the text given.</p> + +<h1 id="example" class='section-header'><a + href="#example">Example</a></h1> +<p>Get the first two words in some 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"\W+"</span>).<span class='ident'>unwrap</span>(); +<span class='kw'>let</span> <span class='ident'>fields</span>: <span class='ident'>Vec</span><span class='op'><</span><span class='kw-2'>&</span><span class='ident'>str</span><span class='op'>></span> <span class='op'>=</span> <span class='ident'>re</span>.<span class='ident'>splitn</span>(<span class='string'>"Hey! How are you?"</span>, <span class='number'>3</span>).<span class='ident'>collect</span>(); +<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>fields</span>, <span class='macro'>vec</span><span class='macro'>!</span>(<span class='string'>"Hey"</span>, <span class='string'>"How"</span>, <span class='string'>"are you?"</span>)); +</pre> +</div><h4 id='method.replace' class='method'><code>fn <a href='#method.replace' class='fnname'>replace</a><R: <a class='trait' href='../regex/trait.Replacer.html' title='regex::Replacer'>Replacer</a>>(&self, text: &<a href='http://doc.rust-lang.org/nightly/std/primitive.str.html'>str</a>, rep: R) -> <a class='struct' href='http://doc.rust-lang.org/nightly/collections/string/struct.String.html' title='collections::string::String'>String</a></code></h4> +<div class='docblock'><p>Replaces the leftmost-first match with the replacement provided. +The replacement can be a regular string (where <code>$N</code> and <code>$name</code> are +expanded to match capture groups) or a function that takes the matches' +<code>Captures</code> and returns the replaced string.</p> + +<p>If no match is found, then a copy of the string is returned unchanged.</p> + +<h1 id="examples" class='section-header'><a + href="#examples">Examples</a></h1> +<p>Note that this function is polymorphic with respect to the replacement. +In typical usage, this can just be a normal string:</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'>"[^01]+"</span>).<span class='ident'>unwrap</span>(); +<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>re</span>.<span class='ident'>replace</span>(<span class='string'>"1078910"</span>, <span class='string'>""</span>), <span class='string'>"1010"</span>); +</pre> + +<p>But anything satisfying the <code>Replacer</code> trait will work. For example, +a closure of type <code>|&Captures| -> String</code> provides direct access to the +captures corresponding to a match. This allows one to access +submatches easily:</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"([^,\s]+),\s+(\S+)"</span>).<span class='ident'>unwrap</span>(); +<span class='kw'>let</span> <span class='ident'>result</span> <span class='op'>=</span> <span class='ident'>re</span>.<span class='ident'>replace</span>(<span class='string'>"Springsteen, Bruce"</span>, <span class='op'>|</span><span class='ident'>caps</span>: <span class='kw-2'>&</span><span class='ident'>Captures</span><span class='op'>|</span> { + <span class='macro'>format</span><span class='macro'>!</span>(<span class='string'>"{} {}"</span>, <span class='ident'>caps</span>.<span class='ident'>at</span>(<span class='number'>2</span>).<span class='ident'>unwrap_or</span>(<span class='string'>""</span>), <span class='ident'>caps</span>.<span class='ident'>at</span>(<span class='number'>1</span>).<span class='ident'>unwrap_or</span>(<span class='string'>""</span>)) +}); +<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>result</span>, <span class='string'>"Bruce Springsteen"</span>); +</pre> + +<p>But this is a bit cumbersome to use all the time. Instead, a simple +syntax is supported that expands <code>$name</code> into the corresponding capture +group. Here's the last example, but using this expansion technique +with named capture groups:</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<last>[^,\s]+),\s+(?P<first>\S+)"</span>).<span class='ident'>unwrap</span>(); +<span class='kw'>let</span> <span class='ident'>result</span> <span class='op'>=</span> <span class='ident'>re</span>.<span class='ident'>replace</span>(<span class='string'>"Springsteen, Bruce"</span>, <span class='string'>"$first $last"</span>); +<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>result</span>, <span class='string'>"Bruce Springsteen"</span>); +</pre> + +<p>Note that using <code>$2</code> instead of <code>$first</code> or <code>$1</code> instead of <code>$last</code> +would produce the same result. To write a literal <code>$</code> use <code>$$</code>.</p> + +<p>Finally, sometimes you just want to replace a literal string with no +submatch expansion. This can be done by wrapping a string with +<code>NoExpand</code>:</p> +<pre class='rust rust-example-rendered'> +<span class='kw'>use</span> <span class='ident'>regex</span>::<span class='ident'>NoExpand</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"(?P<last>[^,\s]+),\s+(\S+)"</span>).<span class='ident'>unwrap</span>(); +<span class='kw'>let</span> <span class='ident'>result</span> <span class='op'>=</span> <span class='ident'>re</span>.<span class='ident'>replace</span>(<span class='string'>"Springsteen, Bruce"</span>, <span class='ident'>NoExpand</span>(<span class='string'>"$2 $last"</span>)); +<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>result</span>, <span class='string'>"$2 $last"</span>); +</pre> +</div><h4 id='method.replace_all' class='method'><code>fn <a href='#method.replace_all' class='fnname'>replace_all</a><R: <a class='trait' href='../regex/trait.Replacer.html' title='regex::Replacer'>Replacer</a>>(&self, text: &<a href='http://doc.rust-lang.org/nightly/std/primitive.str.html'>str</a>, rep: R) -> <a class='struct' href='http://doc.rust-lang.org/nightly/collections/string/struct.String.html' title='collections::string::String'>String</a></code></h4> +<div class='docblock'><p>Replaces all non-overlapping matches in <code>text</code> with the +replacement provided. This is the same as calling <code>replacen</code> with +<code>limit</code> set to <code>0</code>.</p> + +<p>See the documentation for <code>replace</code> for details on how to access +submatches in the replacement string.</p> +</div><h4 id='method.replacen' class='method'><code>fn <a href='#method.replacen' class='fnname'>replacen</a><R: <a class='trait' href='../regex/trait.Replacer.html' title='regex::Replacer'>Replacer</a>>(&self, text: &<a href='http://doc.rust-lang.org/nightly/std/primitive.str.html'>str</a>, limit: <a href='http://doc.rust-lang.org/nightly/std/primitive.usize.html'>usize</a>, rep: R) -> <a class='struct' href='http://doc.rust-lang.org/nightly/collections/string/struct.String.html' title='collections::string::String'>String</a></code></h4> +<div class='docblock'><p>Replaces at most <code>limit</code> non-overlapping matches in <code>text</code> with the +replacement provided. If <code>limit</code> is 0, then all non-overlapping matches +are replaced.</p> + +<p>See the documentation for <code>replace</code> for details on how to access +submatches in the replacement string.</p> +</div><h4 id='method.as_str' class='method'><code>fn <a href='#method.as_str' class='fnname'>as_str</a><'a>(&'a self) -> &'a <a href='http://doc.rust-lang.org/nightly/std/primitive.str.html'>str</a></code></h4> +<div class='docblock'><p>Returns the original string of this regex.</p> +</div></div><h2 id='implementations'>Trait Implementations</h2><h3 class='impl'><code>impl <a class='trait' href='http://doc.rust-lang.org/nightly/core/fmt/trait.Display.html' title='core::fmt::Display'>Display</a> for <a class='enum' href='../regex/enum.Regex.html' title='regex::Regex'>Regex</a></code></h3><div class='impl-items'><h4 id='method.fmt' class='method'><code>fn <a href='http://doc.rust-lang.org/nightly/core/fmt/trait.Display.html#method.fmt' class='fnname'>fmt</a>(&self, f: &mut <a class='struct' href='http://doc.rust-lang.org/nightly/core/fmt/struct.Formatter.html' title='core::fmt::Formatter'>Formatter</a>) -> <a class='type' href='http://doc.rust-lang.org/nightly/core/fmt/type.Result.html' title='core::fmt::Result'>Result</a></code></h4> +</div><h3 class='impl'><code>impl <a class='trait' href='http://doc.rust-lang.org/nightly/core/fmt/trait.Debug.html' title='core::fmt::Debug'>Debug</a> for <a class='enum' href='../regex/enum.Regex.html' title='regex::Regex'>Regex</a></code></h3><div class='impl-items'><h4 id='method.fmt' class='method'><code>fn <a href='http://doc.rust-lang.org/nightly/core/fmt/trait.Debug.html#method.fmt' class='fnname'>fmt</a>(&self, f: &mut <a class='struct' href='http://doc.rust-lang.org/nightly/core/fmt/struct.Formatter.html' title='core::fmt::Formatter'>Formatter</a>) -> <a class='type' href='http://doc.rust-lang.org/nightly/core/fmt/type.Result.html' title='core::fmt::Result'>Result</a></code></h4> +</div><h3 class='impl'><code>impl <a class='trait' href='http://doc.rust-lang.org/nightly/core/cmp/trait.PartialEq.html' title='core::cmp::PartialEq'>PartialEq</a> for <a class='enum' href='../regex/enum.Regex.html' title='regex::Regex'>Regex</a></code></h3><div class='docblock'><p>Equality comparison is based on the original string. It is possible that +different regular expressions have the same matching behavior, but are +still compared unequal. For example, <code>\d+</code> and <code>\d\d*</code> match the same set +of strings, but are not considered equal.</p> +</div><div class='impl-items'><h4 id='method.eq' class='method'><code>fn <a href='http://doc.rust-lang.org/nightly/core/cmp/trait.PartialEq.html#method.eq' class='fnname'>eq</a>(&self, other: &<a class='enum' href='../regex/enum.Regex.html' title='regex::Regex'>Regex</a>) -> <a href='http://doc.rust-lang.org/nightly/std/primitive.bool.html'>bool</a></code></h4> +<h4 id='method.ne' class='method'><code>fn <a href='http://doc.rust-lang.org/nightly/core/cmp/trait.PartialEq.html#method.ne' class='fnname'>ne</a>(&self, other: &Rhs) -> <a href='http://doc.rust-lang.org/nightly/std/primitive.bool.html'>bool</a></code></h4> +</div><h3 class='impl'><code>impl <a class='trait' href='http://doc.rust-lang.org/nightly/core/cmp/trait.Eq.html' title='core::cmp::Eq'>Eq</a> for <a class='enum' href='../regex/enum.Regex.html' title='regex::Regex'>Regex</a></code></h3><div class='impl-items'></div><h3 class='impl'><code>impl <a class='trait' href='http://doc.rust-lang.org/nightly/core/str/trait.FromStr.html' title='core::str::FromStr'>FromStr</a> for <a class='enum' href='../regex/enum.Regex.html' title='regex::Regex'>Regex</a></code></h3><div class='impl-items'><h4 id='assoc_type.Err' class='type'><code>type Err = <a class='enum' href='../regex/enum.Error.html' title='regex::Error'>Error</a></code></h4> +<h4 id='method.from_str' class='method'><code>fn <a href='http://doc.rust-lang.org/nightly/core/str/trait.FromStr.html#method.from_str' class='fnname'>from_str</a>(s: &<a href='http://doc.rust-lang.org/nightly/std/primitive.str.html'>str</a>) -> <a class='enum' href='http://doc.rust-lang.org/nightly/core/result/enum.Result.html' title='core::result::Result'>Result</a><<a class='enum' href='../regex/enum.Regex.html' title='regex::Regex'>Regex</a>, <a class='enum' href='../regex/enum.Error.html' title='regex::Error'>Error</a>></code></h4> +</div><h3 class='impl'><code>impl<'r, 't> <a class='trait' href='http://doc.rust-lang.org/nightly/core/str/pattern/trait.Pattern.html' title='core::str::pattern::Pattern'>Pattern</a><'t> for &'r <a class='enum' href='../regex/enum.Regex.html' title='regex::Regex'>Regex</a></code></h3><div class='impl-items'><h4 id='assoc_type.Searcher' class='type'><code>type Searcher = RegexSearcher<'r, 't></code></h4> +<h4 id='method.into_searcher' class='method'><code>fn <a href='http://doc.rust-lang.org/nightly/core/str/pattern/trait.Pattern.html#method.into_searcher' class='fnname'>into_searcher</a>(self, haystack: &'t <a href='http://doc.rust-lang.org/nightly/std/primitive.str.html'>str</a>) -> RegexSearcher<'r, 't></code></h4> +<h4 id='method.is_contained_in' class='method'><code>fn <a href='http://doc.rust-lang.org/nightly/core/str/pattern/trait.Pattern.html#method.is_contained_in' class='fnname'>is_contained_in</a>(self, haystack: &'a <a href='http://doc.rust-lang.org/nightly/std/primitive.str.html'>str</a>) -> <a href='http://doc.rust-lang.org/nightly/std/primitive.bool.html'>bool</a></code></h4> +<h4 id='method.is_prefix_of' class='method'><code>fn <a href='http://doc.rust-lang.org/nightly/core/str/pattern/trait.Pattern.html#method.is_prefix_of' class='fnname'>is_prefix_of</a>(self, haystack: &'a <a href='http://doc.rust-lang.org/nightly/std/primitive.str.html'>str</a>) -> <a href='http://doc.rust-lang.org/nightly/std/primitive.bool.html'>bool</a></code></h4> +<h4 id='method.is_suffix_of' class='method'><code>fn <a href='http://doc.rust-lang.org/nightly/core/str/pattern/trait.Pattern.html#method.is_suffix_of' class='fnname'>is_suffix_of</a>(self, haystack: &'a <a href='http://doc.rust-lang.org/nightly/std/primitive.str.html'>str</a>) -> <a href='http://doc.rust-lang.org/nightly/std/primitive.bool.html'>bool</a> <span class='where'>where Self::<a class='trait' href='http://doc.rust-lang.org/nightly/core/str/pattern/trait.Pattern.html' title='core::str::pattern::Pattern'>Searcher</a>: <a class='trait' href='http://doc.rust-lang.org/nightly/core/str/pattern/trait.ReverseSearcher.html' title='core::str::pattern::ReverseSearcher'>ReverseSearcher</a><'a></span></code></h4> +</div><h3 id='derived_implementations'>Derived Implementations </h3><h3 class='impl'><code>impl <a class='trait' href='http://doc.rust-lang.org/nightly/core/clone/trait.Clone.html' title='core::clone::Clone'>Clone</a> for <a class='enum' href='../regex/enum.Regex.html' title='regex::Regex'>Regex</a></code></h3><div class='impl-items'><h4 id='method.clone' class='method'><code>fn <a href='http://doc.rust-lang.org/nightly/core/clone/trait.Clone.html#method.clone' class='fnname'>clone</a>(&self) -> <a class='enum' href='../regex/enum.Regex.html' title='regex::Regex'>Regex</a></code></h4> +<h4 id='method.clone_from' class='method'><code>fn <a href='http://doc.rust-lang.org/nightly/core/clone/trait.Clone.html#method.clone_from' class='fnname'>clone_from</a>(&mut self, source: &Self)</code></h4> +</div></section> + <section id='search' class="content hidden"></section> + + <section class="footer"></section> + + <div id="help" class="hidden"> + <div class="shortcuts"> + <h1>Keyboard shortcuts</h1> + <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"> + <h1>Search tricks</h1> + <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>typedef</code> (or + <code>tdef</code>). + </p> + <p> + Search functions by type signature (e.g. + <code>vec -> usize</code>) + </p> + </div> + </div> + + + + <script> + window.rootPath = "../"; + window.currentCrate = "regex"; + window.playgroundUrl = ""; + </script> + <script src="../jquery.js"></script> + <script src="../main.js"></script> + + <script async src="../search-index.js"></script> +</body> +</html>
\ No newline at end of file |