1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
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>
|