400 lines
No EOL
41 KiB
HTML
400 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` 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="../../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'><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 struct">
|
||
<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 id='src-3281' class='srclink' href='../../src/regex/re_bytes.rs.html#43' 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'><code>impl <a class='struct' href='../../regex/bytes/struct.Regex.html' title='regex::bytes::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 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='core::result::Result'>Result</a><<a class='struct' href='../../regex/bytes/struct.Regex.html' title='regex::bytes::Regex'>Regex</a>, <a class='enum' href='../../regex/enum.Error.html' title='regex::Error'>Error</a>></code></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'><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='core::result::Result'>Result</a><<a class='struct' href='../../regex/bytes/struct.Regex.html' title='regex::bytes::Regex'>Regex</a>, <a class='enum' href='../../regex/enum.Error.html' title='regex::Error'>Error</a>></code></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'><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></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'><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='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></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'><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='regex::bytes::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-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'><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='core::option::Option'>Option</a><<a class='struct' href='../../regex/bytes/struct.Captures.html' title='regex::bytes::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'>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'><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='regex::bytes::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-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'><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='regex::bytes::Splits'>Splits</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-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'><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='regex::bytes::SplitsN'>SplitsN</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-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'><code>fn <a href='#method.replace' class='fnname'>replace</a><R: <a class='trait' href='../../regex/bytes/trait.Replacer.html' title='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/collections/vec/struct.Vec.html' title='collections::vec::Vec'>Vec</a><<a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.u8.html'>u8</a>></code></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'><code>fn <a href='#method.replace_all' class='fnname'>replace_all</a><R: <a class='trait' href='../../regex/bytes/trait.Replacer.html' title='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/collections/vec/struct.Vec.html' title='collections::vec::Vec'>Vec</a><<a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.u8.html'>u8</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 text.</p>
|
||
</div><h4 id='method.replacen' class='method'><code>fn <a href='#method.replacen' class='fnname'>replacen</a><R: <a class='trait' href='../../regex/bytes/trait.Replacer.html' title='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/collections/vec/struct.Vec.html' title='collections::vec::Vec'>Vec</a><<a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.u8.html'>u8</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 text.</p>
|
||
</div><h4 id='method.shortest_match' class='method'><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='core::option::Option'>Option</a><<a class='primitive' href='https://doc.rust-lang.org/nightly/std/primitive.usize.html'>usize</a>></code></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'><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></h4>
|
||
<div class='docblock'><p>Returns the original string of this regex.</p>
|
||
</div><h4 id='method.capture_names' class='method'><code>fn <a href='#method.capture_names' class='fnname'>capture_names</a>(&self) -> <a class='struct' href='../../regex/bytes/struct.CaptureNames.html' title='regex::bytes::CaptureNames'>CaptureNames</a></code></h4>
|
||
<div class='docblock'><p>Returns an iterator over the capture names.</p>
|
||
</div><h4 id='method.captures_len' class='method'><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></h4>
|
||
<div class='docblock'><p>Returns the number of captures.</p>
|
||
</div></div><h2 id='implementations'>Trait Implementations</h2><h3 class='impl'><code>impl <a class='trait' href='https://doc.rust-lang.org/nightly/core/fmt/trait.Display.html' title='core::fmt::Display'>Display</a> for <a class='struct' href='../../regex/bytes/struct.Regex.html' title='regex::bytes::Regex'>Regex</a></code></h3><div class='impl-items'><h4 id='method.fmt' class='method'><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='core::fmt::Formatter'>Formatter</a>) -> <a class='type' href='https://doc.rust-lang.org/nightly/core/fmt/type.Result.html' title='core::fmt::Result'>Result</a></code></h4>
|
||
<div class='docblock'><p>Shows the original regular expression.</p>
|
||
</div></div><h3 class='impl'><code>impl <a class='trait' href='https://doc.rust-lang.org/nightly/core/fmt/trait.Debug.html' title='core::fmt::Debug'>Debug</a> for <a class='struct' href='../../regex/bytes/struct.Regex.html' title='regex::bytes::Regex'>Regex</a></code></h3><div class='impl-items'><h4 id='method.fmt-1' class='method'><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='core::fmt::Formatter'>Formatter</a>) -> <a class='type' href='https://doc.rust-lang.org/nightly/core/fmt/type.Result.html' title='core::fmt::Result'>Result</a></code></h4>
|
||
<div class='docblock'><p>Shows the original regular expression.</p>
|
||
</div></div><h3 class='impl'><code>impl <a class='trait' href='https://doc.rust-lang.org/nightly/core/str/trait.FromStr.html' title='core::str::FromStr'>FromStr</a> for <a class='struct' href='../../regex/bytes/struct.Regex.html' title='regex::bytes::Regex'>Regex</a></code></h3><div class='impl-items'><h4 id='associatedtype.Err' class='type'><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='regex::Error'>Error</a></code></h4>
|
||
<h4 id='method.from_str' class='method'><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='core::result::Result'>Result</a><<a class='struct' href='../../regex/bytes/struct.Regex.html' title='regex::bytes::Regex'>Regex</a>, <a class='enum' href='../../regex/enum.Error.html' title='regex::Error'>Error</a>></code></h4>
|
||
<div class='docblock'><p>Attempts to parse a string into a regular expression</p>
|
||
</div></div><h3 id='derived_implementations'>Derived Implementations </h3><h3 class='impl'><code>impl <a class='trait' href='https://doc.rust-lang.org/nightly/core/clone/trait.Clone.html' title='core::clone::Clone'>Clone</a> for <a class='struct' href='../../regex/bytes/struct.Regex.html' title='regex::bytes::Regex'>Regex</a></code></h3><div class='impl-items'><h4 id='method.clone' class='method'><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='regex::bytes::Regex'>Regex</a></code></h4>
|
||
<h4 id='method.clone_from' class='method'><span class="since">1.0.0</span><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></h4>
|
||
</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>
|
||
</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> |