| <!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` struct in crate `regex`."> |
| <meta name="keywords" content="rust, rustlang, rust-lang, Regex"> |
| |
| <title>regex::bytes::Regex - Rust</title> |
| |
| <link rel="stylesheet" type="text/css" href="../../normalize.css"> |
| <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 struct"> |
| <!--[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'>Struct Regex</p><div class="block items"><ul><li><a href="#methods">Methods</a></li><li><a href="#implementations">Trait Implementations</a></li></ul></div><p class='location'><a href='../index.html'>regex</a>::<wbr><a href='index.html'>bytes</a></p><script>window.sidebarCurrent = {name: 'Regex', ty: 'struct', relpath: ''};</script><script defer src="sidebar-items.js"></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"> |
| <h1 class='fqn'><span class='in-band'>Struct <a href='../index.html'>regex</a>::<wbr><a href='index.html'>bytes</a>::<wbr><a class="struct" 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 class='srclink' href='../../src/regex/re_bytes.rs.html#39' title='goto source code'>[src]</a></span></h1> |
| <pre class='rust struct'>pub struct Regex(_);</pre><div class='docblock'><p>A compiled regular expression for matching arbitrary bytes.</p> |
| |
| <p>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>Like the <code>Regex</code> type in the parent module, matches with this regex return |
| byte offsets into the search text. <strong>Unlike</strong> the parent <code>Regex</code> type, |
| these byte offsets may not correspond to UTF-8 sequence boundaries since |
| the regexes in this module can match arbitrary bytes.</p> |
| </div><h2 id='methods'>Methods</h2><h3 class='impl'><span class='in-band'><code>impl <a class="struct" href="../../regex/bytes/struct.Regex.html" title="struct regex::bytes::Regex">Regex</a></code></span><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/regex/re_bytes.rs.html#74-561' title='goto source code'>[src]</a></span></h3> |
| <div class='impl-items'><h4 id='method.new' class="method"><span id='new.v' class='invisible'><code>fn <a href='#method.new' class='fnname'>new</a>(re: &<a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.str.html">str</a>) -> <a class="enum" href="https://doc.rust-lang.org/nightly/core/result/enum.Result.html" title="enum core::result::Result">Result</a><<a class="struct" href="../../regex/bytes/struct.Regex.html" title="struct regex::bytes::Regex">Regex</a>, <a class="enum" href="../../regex/enum.Error.html" title="enum regex::Error">Error</a>></code></span></h4> |
| <div class='docblock'><p>Compiles a 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"><span id='with_size_limit.v' class='invisible'><code>fn <a href='#method.with_size_limit' class='fnname'>with_size_limit</a>(size: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.usize.html">usize</a>, re: &<a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.str.html">str</a>) -> <a class="enum" href="https://doc.rust-lang.org/nightly/core/result/enum.Result.html" title="enum core::result::Result">Result</a><<a class="struct" href="../../regex/bytes/struct.Regex.html" title="struct regex::bytes::Regex">Regex</a>, <a class="enum" href="../../regex/enum.Error.html" title="enum regex::Error">Error</a>></code></span></h4> |
| <div class='docblock'><p>Compiles a 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> |
| </div><h4 id='method.is_match' class="method"><span id='is_match.v' class='invisible'><code>fn <a href='#method.is_match' class='fnname'>is_match</a>(&self, text: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.slice.html">&[</a><a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.u8.html">u8</a><a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.slice.html">]</a>) -> <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.bool.html">bool</a></code></span></h4> |
| <div class='docblock'><p>Returns true if and only if the regex matches the string given.</p> |
| |
| <p>It is recommended to use this method if all you need to do is test |
| a match, since the underlying matching engine may be able to do less |
| work.</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 ASCII word |
| bytes:</p> |
| |
| <pre class="rust rust-example-rendered"> |
| <span class="kw">let</span> <span class="ident">text</span> <span class="op">=</span> <span class="string">b"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"><span id='find.v' class='invisible'><code>fn <a href='#method.find' class='fnname'>find</a>(&self, text: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.slice.html">&[</a><a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.u8.html">u8</a><a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.slice.html">]</a>) -> <a class="enum" href="https://doc.rust-lang.org/nightly/core/option/enum.Option.html" title="enum core::option::Option">Option</a><<a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.tuple.html">(</a><a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.usize.html">usize</a>, <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.usize.html">usize</a><a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.tuple.html">)</a>></code></span></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-1' class='section-header'><a href='#example-1'>Example</a></h1> |
| <p>Find the start and end location of the first word with exactly 13 |
| ASCII word bytes:</p> |
| |
| <pre class="rust rust-example-rendered"> |
| <span class="kw">let</span> <span class="ident">text</span> <span class="op">=</span> <span class="string">b"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"><span id='find_iter.v' class='invisible'><code>fn <a href='#method.find_iter' class='fnname'>find_iter</a><'r, 't>(&'r self, text: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.slice.html">&'t [</a><a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.u8.html">u8</a><a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.slice.html">]</a>) -> <a class="struct" href="../../regex/bytes/struct.FindMatches.html" title="struct regex::bytes::FindMatches">FindMatches</a><'r, 't></code></span></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-2' class='section-header'><a href='#example-2'>Example</a></h1> |
| <p>Find the start and end location of every word with exactly 13 ASCII |
| word bytes:</p> |
| |
| <pre class="rust rust-example-rendered"> |
| <span class="kw">let</span> <span class="ident">text</span> <span class="op">=</span> <span class="string">b"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"><span id='captures.v' class='invisible'><code>fn <a href='#method.captures' class='fnname'>captures</a><'t>(&self, text: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.slice.html">&'t [</a><a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.u8.html">u8</a><a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.slice.html">]</a>) -> <a class="enum" href="https://doc.rust-lang.org/nightly/core/option/enum.Option.html" title="enum core::option::Option">Option</a><<a class="struct" href="../../regex/bytes/struct.Captures.html" title="struct regex::bytes::Captures">Captures</a><'t>></code></span></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">b"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="kw-2">&</span><span class="string">b"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="kw-2">&</span><span class="string">b"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="kw-2">&</span><span class="string">b"'Citizen Kane' (1941)"</span>[..])); |
| <span class="comment">// You can also access the groups by index using the Index notation.</span> |
| <span class="comment">// Note that this will panic on an invalid index.</span> |
| <span class="macro">assert_eq</span><span class="macro">!</span>(<span class="kw-2">&</span><span class="ident">caps</span>[<span class="number">1</span>], <span class="string">b"Citizen Kane"</span>); |
| <span class="macro">assert_eq</span><span class="macro">!</span>(<span class="kw-2">&</span><span class="ident">caps</span>[<span class="number">2</span>], <span class="string">b"1941"</span>); |
| <span class="macro">assert_eq</span><span class="macro">!</span>(<span class="kw-2">&</span><span class="ident">caps</span>[<span class="number">0</span>], <span class="string">b"'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">b"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="kw-2">&</span><span class="string">b"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="kw-2">&</span><span class="string">b"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="kw-2">&</span><span class="string">b"'Citizen Kane' (1941)"</span>[..])); |
| <span class="comment">// You can also access the groups by name using the Index notation.</span> |
| <span class="comment">// Note that this will panic on an invalid group name.</span> |
| <span class="macro">assert_eq</span><span class="macro">!</span>(<span class="kw-2">&</span><span class="ident">caps</span>[<span class="string">"title"</span>], <span class="string">b"Citizen Kane"</span>); |
| <span class="macro">assert_eq</span><span class="macro">!</span>(<span class="kw-2">&</span><span class="ident">caps</span>[<span class="string">"year"</span>], <span class="string">b"1941"</span>); |
| <span class="macro">assert_eq</span><span class="macro">!</span>(<span class="kw-2">&</span><span class="ident">caps</span>[<span class="number">0</span>], <span class="string">b"'Citizen Kane' (1941)"</span>); |
| </pre> |
| |
| <p>Here we name the capture groups, which we can access with the <code>name</code> |
| method or the <code>Index</code> notation with a <code>&str</code>. Note that the named |
| capture groups are still accessible with <code>at</code> or the <code>Index</code> notation |
| with a <code>usize</code>.</p> |
| |
| <p>The <code>0</code>th capture group is always unnamed, so it must always be |
| accessed with <code>at(0)</code> or <code>[0]</code>.</p> |
| </div><h4 id='method.captures_iter' class="method"><span id='captures_iter.v' class='invisible'><code>fn <a href='#method.captures_iter' class='fnname'>captures_iter</a><'r, 't>(&'r self, text: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.slice.html">&'t [</a><a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.u8.html">u8</a><a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.slice.html">]</a>) -> <a class="struct" href="../../regex/bytes/struct.FindCaptures.html" title="struct regex::bytes::FindCaptures">FindCaptures</a><'r, 't></code></span></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-3' class='section-header'><a href='#example-3'>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">b"'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="kw">let</span> <span class="ident">title</span> <span class="op">=</span> <span class="ident">str</span>::<span class="ident">from_utf8</span>(<span class="kw-2">&</span><span class="ident">caps</span>[<span class="string">"title"</span>]).<span class="ident">unwrap</span>(); |
| <span class="kw">let</span> <span class="ident">year</span> <span class="op">=</span> <span class="ident">str</span>::<span class="ident">from_utf8</span>(<span class="kw-2">&</span><span class="ident">caps</span>[<span class="string">"year"</span>]).<span class="ident">unwrap</span>(); |
| <span class="macro">println</span><span class="macro">!</span>(<span class="string">"Movie: {:?}, Released: {:?}"</span>, <span class="ident">title</span>, <span class="ident">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"><span id='split.v' class='invisible'><code>fn <a href='#method.split' class='fnname'>split</a><'r, 't>(&'r self, text: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.slice.html">&'t [</a><a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.u8.html">u8</a><a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.slice.html">]</a>) -> <a class="struct" href="../../regex/bytes/struct.Splits.html" title="struct regex::bytes::Splits">Splits</a><'r, 't></code></span></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-4' class='section-header'><a href='#example-4'>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">u8</span>]<span class="op">></span> <span class="op">=</span> <span class="ident">re</span>.<span class="ident">split</span>(<span class="string">b"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="kw-2">&</span><span class="string">b"a"</span>[..], <span class="kw-2">&</span><span class="string">b"b"</span>[..], <span class="kw-2">&</span><span class="string">b"c"</span>[..], <span class="kw-2">&</span><span class="string">b"d"</span>[..], <span class="kw-2">&</span><span class="string">b"e"</span>[..], |
| ]);</pre> |
| </div><h4 id='method.splitn' class="method"><span id='splitn.v' class='invisible'><code>fn <a href='#method.splitn' class='fnname'>splitn</a><'r, 't>(&'r self, text: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.slice.html">&'t [</a><a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.u8.html">u8</a><a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.slice.html">]</a>, limit: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.usize.html">usize</a>) -> <a class="struct" href="../../regex/bytes/struct.SplitsN.html" title="struct regex::bytes::SplitsN">SplitsN</a><'r, 't></code></span></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-5' class='section-header'><a href='#example-5'>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">u8</span>]<span class="op">></span> <span class="op">=</span> <span class="ident">re</span>.<span class="ident">splitn</span>(<span class="string">b"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="kw-2">&</span><span class="string">b"Hey"</span>[..], <span class="kw-2">&</span><span class="string">b"How"</span>[..], <span class="kw-2">&</span><span class="string">b"are you?"</span>[..]]);</pre> |
| </div><h4 id='method.replace' class="method"><span id='replace.v' class='invisible'><code>fn <a href='#method.replace' class='fnname'>replace</a><R: <a class="trait" href="../../regex/bytes/trait.Replacer.html" title="trait regex::bytes::Replacer">Replacer</a>>(&self, text: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.slice.html">&[</a><a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.u8.html">u8</a><a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.slice.html">]</a>, rep: R) -> <a class="struct" href="https://doc.rust-lang.org/nightly/alloc/vec/struct.Vec.html" title="struct alloc::vec::Vec">Vec</a><<a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.u8.html">u8</a>></code></span></h4> |
| <div class='docblock'><p>Replaces the leftmost-first match with the replacement provided. The |
| replacement can be a regular byte 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 byte string.</p> |
| |
| <p>If no match is found, then a copy of the byte string is returned |
| unchanged.</p> |
| |
| <h1 id='examples-1' class='section-header'><a href='#examples-1'>Examples</a></h1> |
| <p>Note that this function is polymorphic with respect to the replacement. |
| In typical usage, this can just be a normal byte 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">b"1078910"</span>, <span class="kw-2">&</span><span class="string">b""</span>[..]), <span class="string">b"1010"</span>);</pre> |
| |
| <p>But anything satisfying the <code>Replacer</code> trait will work. For example, a |
| closure of type <code>|&Captures| -> Vec<u8></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">b"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="kw">let</span> <span class="kw-2">mut</span> <span class="ident">replacement</span> <span class="op">=</span> <span class="ident">caps</span>[<span class="number">2</span>].<span class="ident">to_owned</span>(); |
| <span class="ident">replacement</span>.<span class="ident">push</span>(<span class="string">b' '</span>); |
| <span class="ident">replacement</span>.<span class="ident">extend</span>(<span class="kw-2">&</span><span class="ident">caps</span>[<span class="number">1</span>]); |
| <span class="ident">replacement</span> |
| }); |
| <span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">result</span>, <span class="string">b"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">b"Springsteen, Bruce"</span>, <span class="kw-2">&</span><span class="string">b"$first $last"</span>[..]); |
| <span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">result</span>, <span class="string">b"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>If <code>$name</code> isn't a valid capture group (whether the name doesn't exist |
| or isn't a valid index), then it is replaced with the empty string.</p> |
| |
| <p>The longest possible name is used. e.g., <code>$1a</code> looks up the capture |
| group named <code>1a</code> and not the capture group at index <code>1</code>. To exert more |
| precise control over the name, use braces, e.g., <code>${1}a</code>.</p> |
| |
| <p>Finally, sometimes you just want to replace a literal string with no |
| submatch expansion. This can be done by wrapping a byte 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">bytes</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">b"Springsteen, Bruce"</span>, <span class="ident">NoExpand</span>(<span class="string">b"$2 $last"</span>)); |
| <span class="macro">assert_eq</span><span class="macro">!</span>(<span class="ident">result</span>, <span class="string">b"$2 $last"</span>);</pre> |
| </div><h4 id='method.replace_all' class="method"><span id='replace_all.v' class='invisible'><code>fn <a href='#method.replace_all' class='fnname'>replace_all</a><R: <a class="trait" href="../../regex/bytes/trait.Replacer.html" title="trait regex::bytes::Replacer">Replacer</a>>(&self, text: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.slice.html">&[</a><a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.u8.html">u8</a><a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.slice.html">]</a>, rep: R) -> <a class="struct" href="https://doc.rust-lang.org/nightly/alloc/vec/struct.Vec.html" title="struct alloc::vec::Vec">Vec</a><<a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.u8.html">u8</a>></code></span></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 text.</p> |
| </div><h4 id='method.replacen' class="method"><span id='replacen.v' class='invisible'><code>fn <a href='#method.replacen' class='fnname'>replacen</a><R: <a class="trait" href="../../regex/bytes/trait.Replacer.html" title="trait regex::bytes::Replacer">Replacer</a>>(&self, text: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.slice.html">&[</a><a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.u8.html">u8</a><a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.slice.html">]</a>, limit: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.usize.html">usize</a>, rep: R) -> <a class="struct" href="https://doc.rust-lang.org/nightly/alloc/vec/struct.Vec.html" title="struct alloc::vec::Vec">Vec</a><<a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.u8.html">u8</a>></code></span></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 text.</p> |
| </div><h4 id='method.shortest_match' class="method"><span id='shortest_match.v' class='invisible'><code>fn <a href='#method.shortest_match' class='fnname'>shortest_match</a>(&self, text: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.slice.html">&[</a><a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.u8.html">u8</a><a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.slice.html">]</a>) -> <a class="enum" href="https://doc.rust-lang.org/nightly/core/option/enum.Option.html" title="enum core::option::Option">Option</a><<a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.usize.html">usize</a>></code></span></h4> |
| <div class='docblock'><p>Returns the end location of a match in the text given.</p> |
| |
| <p>This method may have the same performance characteristics as |
| <code>is_match</code>, except it provides an end location for a match. In |
| particular, the location returned <em>may be shorter</em> than the proper end |
| of the leftmost-first match.</p> |
| |
| <h1 id='example-6' class='section-header'><a href='#example-6'>Example</a></h1> |
| <p>Typically, <code>a+</code> would match the entire first sequence of <code>a</code> in some |
| text, but <code>shortest_match</code> can give up as soon as it sees the first |
| <code>a</code>.</p> |
| |
| <pre class="rust rust-example-rendered"> |
| <span class="kw">let</span> <span class="ident">text</span> <span class="op">=</span> <span class="string">b"aaaaa"</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"a+"</span>).<span class="ident">unwrap</span>().<span class="ident">shortest_match</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">1</span>));</pre> |
| </div><h4 id='method.as_str' class="method"><span id='as_str.v' class='invisible'><code>fn <a href='#method.as_str' class='fnname'>as_str</a>(&self) -> &<a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.str.html">str</a></code></span></h4> |
| <div class='docblock'><p>Returns the original string of this regex.</p> |
| </div><h4 id='method.capture_names' class="method"><span id='capture_names.v' class='invisible'><code>fn <a href='#method.capture_names' class='fnname'>capture_names</a>(&self) -> <a class="struct" href="../../regex/bytes/struct.CaptureNames.html" title="struct regex::bytes::CaptureNames">CaptureNames</a></code></span></h4> |
| <div class='docblock'><p>Returns an iterator over the capture names.</p> |
| </div><h4 id='method.captures_len' class="method"><span id='captures_len.v' class='invisible'><code>fn <a href='#method.captures_len' class='fnname'>captures_len</a>(&self) -> <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.usize.html">usize</a></code></span></h4> |
| <div class='docblock'><p>Returns the number of captures.</p> |
| </div></div><h2 id='implementations'>Trait Implementations</h2><h3 class='impl'><span class='in-band'><code>impl <a class="trait" href="https://doc.rust-lang.org/nightly/core/clone/trait.Clone.html" title="trait core::clone::Clone">Clone</a> for <a class="struct" href="../../regex/bytes/struct.Regex.html" title="struct regex::bytes::Regex">Regex</a></code></span><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/regex/re_bytes.rs.html#38' title='goto source code'>[src]</a></span></h3> |
| <div class='impl-items'><h4 id='method.clone' class="method"><span id='clone.v' class='invisible'><code>fn <a href='https://doc.rust-lang.org/nightly/core/clone/trait.Clone.html#tymethod.clone' class='fnname'>clone</a>(&self) -> <a class="struct" href="../../regex/bytes/struct.Regex.html" title="struct regex::bytes::Regex">Regex</a></code></span></h4> |
| <div class='docblock'><p>Returns a copy of the value. <a href="https://doc.rust-lang.org/nightly/core/clone/trait.Clone.html#tymethod.clone">Read more</a></p> |
| </div><h4 id='method.clone_from' class="method"><span id='clone_from.v' class='invisible'><code>fn <a href='https://doc.rust-lang.org/nightly/core/clone/trait.Clone.html#method.clone_from' class='fnname'>clone_from</a>(&mut self, source: &Self)</code><div class='since' title='Stable since Rust version 1.0.0'>1.0.0</div></span></h4> |
| <div class='docblock'><p>Performs copy-assignment from <code>source</code>. <a href="https://doc.rust-lang.org/nightly/core/clone/trait.Clone.html#method.clone_from">Read more</a></p> |
| </div></div><h3 class='impl'><span class='in-band'><code>impl <a class="trait" href="https://doc.rust-lang.org/nightly/core/fmt/trait.Display.html" title="trait core::fmt::Display">Display</a> for <a class="struct" href="../../regex/bytes/struct.Regex.html" title="struct regex::bytes::Regex">Regex</a></code></span><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/regex/re_bytes.rs.html#41-46' title='goto source code'>[src]</a></span></h3> |
| <div class='impl-items'><h4 id='method.fmt' class="method"><span id='fmt.v' class='invisible'><code>fn <a href='https://doc.rust-lang.org/nightly/core/fmt/trait.Display.html#tymethod.fmt' class='fnname'>fmt</a>(&self, f: &mut <a class="struct" href="https://doc.rust-lang.org/nightly/core/fmt/struct.Formatter.html" title="struct core::fmt::Formatter">Formatter</a>) -> <a class="type" href="https://doc.rust-lang.org/nightly/core/fmt/type.Result.html" title="type core::fmt::Result">Result</a></code></span></h4> |
| <div class='docblock'><p>Shows the original regular expression.</p> |
| </div></div><h3 class='impl'><span class='in-band'><code>impl <a class="trait" href="https://doc.rust-lang.org/nightly/core/fmt/trait.Debug.html" title="trait core::fmt::Debug">Debug</a> for <a class="struct" href="../../regex/bytes/struct.Regex.html" title="struct regex::bytes::Regex">Regex</a></code></span><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/regex/re_bytes.rs.html#48-53' title='goto source code'>[src]</a></span></h3> |
| <div class='impl-items'><h4 id='method.fmt-1' class="method"><span id='fmt.v-1' class='invisible'><code>fn <a href='https://doc.rust-lang.org/nightly/core/fmt/trait.Debug.html#tymethod.fmt' class='fnname'>fmt</a>(&self, f: &mut <a class="struct" href="https://doc.rust-lang.org/nightly/core/fmt/struct.Formatter.html" title="struct core::fmt::Formatter">Formatter</a>) -> <a class="type" href="https://doc.rust-lang.org/nightly/core/fmt/type.Result.html" title="type core::fmt::Result">Result</a></code></span></h4> |
| <div class='docblock'><p>Shows the original regular expression.</p> |
| </div></div><h3 class='impl'><span class='in-band'><code>impl <a class="trait" href="https://doc.rust-lang.org/nightly/core/str/trait.FromStr.html" title="trait core::str::FromStr">FromStr</a> for <a class="struct" href="../../regex/bytes/struct.Regex.html" title="struct regex::bytes::Regex">Regex</a></code></span><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/regex/re_bytes.rs.html#65-72' title='goto source code'>[src]</a></span></h3> |
| <div class='impl-items'><h4 id='associatedtype.Err' class="type"><span id='Err.t' class='invisible'><code>type <a href='https://doc.rust-lang.org/nightly/core/str/trait.FromStr.html#associatedtype.Err' class="type">Err</a> = <a class="enum" href="../../regex/enum.Error.html" title="enum regex::Error">Error</a></code></span></h4> |
| <div class='docblock'><p>The associated error which can be returned from parsing.</p> |
| </div><h4 id='method.from_str' class="method"><span id='from_str.v' class='invisible'><code>fn <a href='https://doc.rust-lang.org/nightly/core/str/trait.FromStr.html#tymethod.from_str' class='fnname'>from_str</a>(s: &<a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.str.html">str</a>) -> <a class="enum" href="https://doc.rust-lang.org/nightly/core/result/enum.Result.html" title="enum core::result::Result">Result</a><<a class="struct" href="../../regex/bytes/struct.Regex.html" title="struct regex::bytes::Regex">Regex</a>, <a class="enum" href="../../regex/enum.Error.html" title="enum regex::Error">Error</a>></code></span></h4> |
| <div class='docblock'><p>Attempts to parse a string into a regular expression</p> |
| </div></div></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> |
| <dt>+</dt> |
| <dd>Collapse/expand all sections</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"; |
| </script> |
| <script src="../../main.js"></script> |
| <script defer src="../../search-index.js"></script> |
| </body> |
| </html> |