1 use std::borrow::Cow;
2 use std::collections::HashMap;
3 use std::fmt;
4 use std::ops::{Index, Range};
5 use std::str::FromStr;
6 use std::sync::Arc;
7 
8 use find_byte::find_byte;
9 use syntax;
10 
11 use error::Error;
12 use exec::{Exec, ExecNoSyncStr};
13 use expand::expand_str;
14 use re_builder::unicode::RegexBuilder;
15 use re_trait::{self, RegularExpression, SubCapturesPosIter};
16 
17 /// Escapes all regular expression meta characters in `text`.
18 ///
19 /// The string returned may be safely used as a literal in a regular
20 /// expression.
escape(text: &str) -> String21 pub fn escape(text: &str) -> String {
22     syntax::escape(text)
23 }
24 
25 /// Match represents a single match of a regex in a haystack.
26 ///
27 /// The lifetime parameter `'t` refers to the lifetime of the matched text.
28 #[derive(Copy, Clone, Debug, Eq, PartialEq)]
29 pub struct Match<'t> {
30     text: &'t str,
31     start: usize,
32     end: usize,
33 }
34 
35 impl<'t> Match<'t> {
36     /// Returns the starting byte offset of the match in the haystack.
37     #[inline]
start(&self) -> usize38     pub fn start(&self) -> usize {
39         self.start
40     }
41 
42     /// Returns the ending byte offset of the match in the haystack.
43     #[inline]
end(&self) -> usize44     pub fn end(&self) -> usize {
45         self.end
46     }
47 
48     /// Returns the range over the starting and ending byte offsets of the
49     /// match in the haystack.
50     #[inline]
range(&self) -> Range<usize>51     pub fn range(&self) -> Range<usize> {
52         self.start..self.end
53     }
54 
55     /// Returns the matched text.
56     #[inline]
as_str(&self) -> &'t str57     pub fn as_str(&self) -> &'t str {
58         &self.text[self.range()]
59     }
60 
61     /// Creates a new match from the given haystack and byte offsets.
62     #[inline]
new(haystack: &'t str, start: usize, end: usize) -> Match<'t>63     fn new(haystack: &'t str, start: usize, end: usize) -> Match<'t> {
64         Match { text: haystack, start: start, end: end }
65     }
66 }
67 
68 impl<'t> From<Match<'t>> for &'t str {
from(m: Match<'t>) -> &'t str69     fn from(m: Match<'t>) -> &'t str {
70         m.as_str()
71     }
72 }
73 
74 impl<'t> From<Match<'t>> for Range<usize> {
from(m: Match<'t>) -> Range<usize>75     fn from(m: Match<'t>) -> Range<usize> {
76         m.range()
77     }
78 }
79 
80 /// A compiled regular expression for matching Unicode strings.
81 ///
82 /// It is represented as either a sequence of bytecode instructions (dynamic)
83 /// or as a specialized Rust function (native). It can be used to search, split
84 /// or replace text. All searching is done with an implicit `.*?` at the
85 /// beginning and end of an expression. To force an expression to match the
86 /// whole string (or a prefix or a suffix), you must use an anchor like `^` or
87 /// `$` (or `\A` and `\z`).
88 ///
89 /// While this crate will handle Unicode strings (whether in the regular
90 /// expression or in the search text), all positions returned are **byte
91 /// indices**. Every byte index is guaranteed to be at a Unicode code point
92 /// boundary.
93 ///
94 /// The lifetimes `'r` and `'t` in this crate correspond to the lifetime of a
95 /// compiled regular expression and text to search, respectively.
96 ///
97 /// The only methods that allocate new strings are the string replacement
98 /// methods. All other methods (searching and splitting) return borrowed
99 /// pointers into the string given.
100 ///
101 /// # Examples
102 ///
103 /// Find the location of a US phone number:
104 ///
105 /// ```rust
106 /// # use regex::Regex;
107 /// let re = Regex::new("[0-9]{3}-[0-9]{3}-[0-9]{4}").unwrap();
108 /// let mat = re.find("phone: 111-222-3333").unwrap();
109 /// assert_eq!((mat.start(), mat.end()), (7, 19));
110 /// ```
111 ///
112 /// # Using the `std::str::pattern` methods with `Regex`
113 ///
114 /// > **Note**: This section requires that this crate is compiled with the
115 /// > `pattern` Cargo feature enabled, which **requires nightly Rust**.
116 ///
117 /// Since `Regex` implements `Pattern`, you can use regexes with methods
118 /// defined on `&str`. For example, `is_match`, `find`, `find_iter`
119 /// and `split` can be replaced with `str::contains`, `str::find`,
120 /// `str::match_indices` and `str::split`.
121 ///
122 /// Here are some examples:
123 ///
124 /// ```rust,ignore
125 /// # use regex::Regex;
126 /// let re = Regex::new(r"\d+").unwrap();
127 /// let haystack = "a111b222c";
128 ///
129 /// assert!(haystack.contains(&re));
130 /// assert_eq!(haystack.find(&re), Some(1));
131 /// assert_eq!(haystack.match_indices(&re).collect::<Vec<_>>(),
132 ///            vec![(1, 4), (5, 8)]);
133 /// assert_eq!(haystack.split(&re).collect::<Vec<_>>(), vec!["a", "b", "c"]);
134 /// ```
135 #[derive(Clone)]
136 pub struct Regex(Exec);
137 
138 impl fmt::Display for Regex {
139     /// Shows the original regular expression.
fmt(&self, f: &mut fmt::Formatter) -> fmt::Result140     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
141         write!(f, "{}", self.as_str())
142     }
143 }
144 
145 impl fmt::Debug for Regex {
146     /// Shows the original regular expression.
fmt(&self, f: &mut fmt::Formatter) -> fmt::Result147     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
148         fmt::Display::fmt(self, f)
149     }
150 }
151 
152 #[doc(hidden)]
153 impl From<Exec> for Regex {
from(exec: Exec) -> Regex154     fn from(exec: Exec) -> Regex {
155         Regex(exec)
156     }
157 }
158 
159 impl FromStr for Regex {
160     type Err = Error;
161 
162     /// Attempts to parse a string into a regular expression
from_str(s: &str) -> Result<Regex, Error>163     fn from_str(s: &str) -> Result<Regex, Error> {
164         Regex::new(s)
165     }
166 }
167 
168 /// Core regular expression methods.
169 impl Regex {
170     /// Compiles a regular expression. Once compiled, it can be used repeatedly
171     /// to search, split or replace text in a string.
172     ///
173     /// If an invalid expression is given, then an error is returned.
new(re: &str) -> Result<Regex, Error>174     pub fn new(re: &str) -> Result<Regex, Error> {
175         RegexBuilder::new(re).build()
176     }
177 
178     /// Returns true if and only if the regex matches the string given.
179     ///
180     /// It is recommended to use this method if all you need to do is test
181     /// a match, since the underlying matching engine may be able to do less
182     /// work.
183     ///
184     /// # Example
185     ///
186     /// Test if some text contains at least one word with exactly 13
187     /// Unicode word characters:
188     ///
189     /// ```rust
190     /// # extern crate regex; use regex::Regex;
191     /// # fn main() {
192     /// let text = "I categorically deny having triskaidekaphobia.";
193     /// assert!(Regex::new(r"\b\w{13}\b").unwrap().is_match(text));
194     /// # }
195     /// ```
is_match(&self, text: &str) -> bool196     pub fn is_match(&self, text: &str) -> bool {
197         self.is_match_at(text, 0)
198     }
199 
200     /// Returns the start and end byte range of the leftmost-first match in
201     /// `text`. If no match exists, then `None` is returned.
202     ///
203     /// Note that this should only be used if you want to discover the position
204     /// of the match. Testing the existence of a match is faster if you use
205     /// `is_match`.
206     ///
207     /// # Example
208     ///
209     /// Find the start and end location of the first word with exactly 13
210     /// Unicode word characters:
211     ///
212     /// ```rust
213     /// # extern crate regex; use regex::Regex;
214     /// # fn main() {
215     /// let text = "I categorically deny having triskaidekaphobia.";
216     /// let mat = Regex::new(r"\b\w{13}\b").unwrap().find(text).unwrap();
217     /// assert_eq!(mat.start(), 2);
218     /// assert_eq!(mat.end(), 15);
219     /// # }
220     /// ```
find<'t>(&self, text: &'t str) -> Option<Match<'t>>221     pub fn find<'t>(&self, text: &'t str) -> Option<Match<'t>> {
222         self.find_at(text, 0)
223     }
224 
225     /// Returns an iterator for each successive non-overlapping match in
226     /// `text`, returning the start and end byte indices with respect to
227     /// `text`.
228     ///
229     /// # Example
230     ///
231     /// Find the start and end location of every word with exactly 13 Unicode
232     /// word characters:
233     ///
234     /// ```rust
235     /// # extern crate regex; use regex::Regex;
236     /// # fn main() {
237     /// let text = "Retroactively relinquishing remunerations is reprehensible.";
238     /// for mat in Regex::new(r"\b\w{13}\b").unwrap().find_iter(text) {
239     ///     println!("{:?}", mat);
240     /// }
241     /// # }
242     /// ```
find_iter<'r, 't>(&'r self, text: &'t str) -> Matches<'r, 't>243     pub fn find_iter<'r, 't>(&'r self, text: &'t str) -> Matches<'r, 't> {
244         Matches(self.0.searcher_str().find_iter(text))
245     }
246 
247     /// Returns the capture groups corresponding to the leftmost-first
248     /// match in `text`. Capture group `0` always corresponds to the entire
249     /// match. If no match is found, then `None` is returned.
250     ///
251     /// You should only use `captures` if you need access to the location of
252     /// capturing group matches. Otherwise, `find` is faster for discovering
253     /// the location of the overall match.
254     ///
255     /// # Examples
256     ///
257     /// Say you have some text with movie names and their release years,
258     /// like "'Citizen Kane' (1941)". It'd be nice if we could search for text
259     /// looking like that, while also extracting the movie name and its release
260     /// year separately.
261     ///
262     /// ```rust
263     /// # extern crate regex; use regex::Regex;
264     /// # fn main() {
265     /// let re = Regex::new(r"'([^']+)'\s+\((\d{4})\)").unwrap();
266     /// let text = "Not my favorite movie: 'Citizen Kane' (1941).";
267     /// let caps = re.captures(text).unwrap();
268     /// assert_eq!(caps.get(1).unwrap().as_str(), "Citizen Kane");
269     /// assert_eq!(caps.get(2).unwrap().as_str(), "1941");
270     /// assert_eq!(caps.get(0).unwrap().as_str(), "'Citizen Kane' (1941)");
271     /// // You can also access the groups by index using the Index notation.
272     /// // Note that this will panic on an invalid index.
273     /// assert_eq!(&caps[1], "Citizen Kane");
274     /// assert_eq!(&caps[2], "1941");
275     /// assert_eq!(&caps[0], "'Citizen Kane' (1941)");
276     /// # }
277     /// ```
278     ///
279     /// Note that the full match is at capture group `0`. Each subsequent
280     /// capture group is indexed by the order of its opening `(`.
281     ///
282     /// We can make this example a bit clearer by using *named* capture groups:
283     ///
284     /// ```rust
285     /// # extern crate regex; use regex::Regex;
286     /// # fn main() {
287     /// let re = Regex::new(r"'(?P<title>[^']+)'\s+\((?P<year>\d{4})\)")
288     ///                .unwrap();
289     /// let text = "Not my favorite movie: 'Citizen Kane' (1941).";
290     /// let caps = re.captures(text).unwrap();
291     /// assert_eq!(caps.name("title").unwrap().as_str(), "Citizen Kane");
292     /// assert_eq!(caps.name("year").unwrap().as_str(), "1941");
293     /// assert_eq!(caps.get(0).unwrap().as_str(), "'Citizen Kane' (1941)");
294     /// // You can also access the groups by name using the Index notation.
295     /// // Note that this will panic on an invalid group name.
296     /// assert_eq!(&caps["title"], "Citizen Kane");
297     /// assert_eq!(&caps["year"], "1941");
298     /// assert_eq!(&caps[0], "'Citizen Kane' (1941)");
299     ///
300     /// # }
301     /// ```
302     ///
303     /// Here we name the capture groups, which we can access with the `name`
304     /// method or the `Index` notation with a `&str`. Note that the named
305     /// capture groups are still accessible with `get` or the `Index` notation
306     /// with a `usize`.
307     ///
308     /// The `0`th capture group is always unnamed, so it must always be
309     /// accessed with `get(0)` or `[0]`.
captures<'t>(&self, text: &'t str) -> Option<Captures<'t>>310     pub fn captures<'t>(&self, text: &'t str) -> Option<Captures<'t>> {
311         let mut locs = self.capture_locations();
312         self.captures_read_at(&mut locs, text, 0).map(move |_| Captures {
313             text: text,
314             locs: locs.0,
315             named_groups: self.0.capture_name_idx().clone(),
316         })
317     }
318 
319     /// Returns an iterator over all the non-overlapping capture groups matched
320     /// in `text`. This is operationally the same as `find_iter`, except it
321     /// yields information about capturing group matches.
322     ///
323     /// # Example
324     ///
325     /// We can use this to find all movie titles and their release years in
326     /// some text, where the movie is formatted like "'Title' (xxxx)":
327     ///
328     /// ```rust
329     /// # extern crate regex; use regex::Regex;
330     /// # fn main() {
331     /// let re = Regex::new(r"'(?P<title>[^']+)'\s+\((?P<year>\d{4})\)")
332     ///                .unwrap();
333     /// let text = "'Citizen Kane' (1941), 'The Wizard of Oz' (1939), 'M' (1931).";
334     /// for caps in re.captures_iter(text) {
335     ///     println!("Movie: {:?}, Released: {:?}",
336     ///              &caps["title"], &caps["year"]);
337     /// }
338     /// // Output:
339     /// // Movie: Citizen Kane, Released: 1941
340     /// // Movie: The Wizard of Oz, Released: 1939
341     /// // Movie: M, Released: 1931
342     /// # }
343     /// ```
captures_iter<'r, 't>( &'r self, text: &'t str, ) -> CaptureMatches<'r, 't>344     pub fn captures_iter<'r, 't>(
345         &'r self,
346         text: &'t str,
347     ) -> CaptureMatches<'r, 't> {
348         CaptureMatches(self.0.searcher_str().captures_iter(text))
349     }
350 
351     /// Returns an iterator of substrings of `text` delimited by a match of the
352     /// regular expression. Namely, each element of the iterator corresponds to
353     /// text that *isn't* matched by the regular expression.
354     ///
355     /// This method will *not* copy the text given.
356     ///
357     /// # Example
358     ///
359     /// To split a string delimited by arbitrary amounts of spaces or tabs:
360     ///
361     /// ```rust
362     /// # extern crate regex; use regex::Regex;
363     /// # fn main() {
364     /// let re = Regex::new(r"[ \t]+").unwrap();
365     /// let fields: Vec<&str> = re.split("a b \t  c\td    e").collect();
366     /// assert_eq!(fields, vec!["a", "b", "c", "d", "e"]);
367     /// # }
368     /// ```
split<'r, 't>(&'r self, text: &'t str) -> Split<'r, 't>369     pub fn split<'r, 't>(&'r self, text: &'t str) -> Split<'r, 't> {
370         Split { finder: self.find_iter(text), last: 0 }
371     }
372 
373     /// Returns an iterator of at most `limit` substrings of `text` delimited
374     /// by a match of the regular expression. (A `limit` of `0` will return no
375     /// substrings.) Namely, each element of the iterator corresponds to text
376     /// that *isn't* matched by the regular expression. The remainder of the
377     /// string that is not split will be the last element in the iterator.
378     ///
379     /// This method will *not* copy the text given.
380     ///
381     /// # Example
382     ///
383     /// Get the first two words in some text:
384     ///
385     /// ```rust
386     /// # extern crate regex; use regex::Regex;
387     /// # fn main() {
388     /// let re = Regex::new(r"\W+").unwrap();
389     /// let fields: Vec<&str> = re.splitn("Hey! How are you?", 3).collect();
390     /// assert_eq!(fields, vec!("Hey", "How", "are you?"));
391     /// # }
392     /// ```
splitn<'r, 't>( &'r self, text: &'t str, limit: usize, ) -> SplitN<'r, 't>393     pub fn splitn<'r, 't>(
394         &'r self,
395         text: &'t str,
396         limit: usize,
397     ) -> SplitN<'r, 't> {
398         SplitN { splits: self.split(text), n: limit }
399     }
400 
401     /// Replaces the leftmost-first match with the replacement provided.
402     /// The replacement can be a regular string (where `$N` and `$name` are
403     /// expanded to match capture groups) or a function that takes the matches'
404     /// `Captures` and returns the replaced string.
405     ///
406     /// If no match is found, then a copy of the string is returned unchanged.
407     ///
408     /// # Replacement string syntax
409     ///
410     /// All instances of `$name` in the replacement text is replaced with the
411     /// corresponding capture group `name`.
412     ///
413     /// `name` may be an integer corresponding to the index of the
414     /// capture group (counted by order of opening parenthesis where `0` is the
415     /// entire match) or it can be a name (consisting of letters, digits or
416     /// underscores) corresponding to a named capture group.
417     ///
418     /// If `name` isn't a valid capture group (whether the name doesn't exist
419     /// or isn't a valid index), then it is replaced with the empty string.
420     ///
421     /// The longest possible name is used. e.g., `$1a` looks up the capture
422     /// group named `1a` and not the capture group at index `1`. To exert more
423     /// precise control over the name, use braces, e.g., `${1}a`.
424     ///
425     /// To write a literal `$` use `$$`.
426     ///
427     /// # Examples
428     ///
429     /// Note that this function is polymorphic with respect to the replacement.
430     /// In typical usage, this can just be a normal string:
431     ///
432     /// ```rust
433     /// # extern crate regex; use regex::Regex;
434     /// # fn main() {
435     /// let re = Regex::new("[^01]+").unwrap();
436     /// assert_eq!(re.replace("1078910", ""), "1010");
437     /// # }
438     /// ```
439     ///
440     /// But anything satisfying the `Replacer` trait will work. For example,
441     /// a closure of type `|&Captures| -> String` provides direct access to the
442     /// captures corresponding to a match. This allows one to access
443     /// capturing group matches easily:
444     ///
445     /// ```rust
446     /// # extern crate regex; use regex::Regex;
447     /// # use regex::Captures; fn main() {
448     /// let re = Regex::new(r"([^,\s]+),\s+(\S+)").unwrap();
449     /// let result = re.replace("Springsteen, Bruce", |caps: &Captures| {
450     ///     format!("{} {}", &caps[2], &caps[1])
451     /// });
452     /// assert_eq!(result, "Bruce Springsteen");
453     /// # }
454     /// ```
455     ///
456     /// But this is a bit cumbersome to use all the time. Instead, a simple
457     /// syntax is supported that expands `$name` into the corresponding capture
458     /// group. Here's the last example, but using this expansion technique
459     /// with named capture groups:
460     ///
461     /// ```rust
462     /// # extern crate regex; use regex::Regex;
463     /// # fn main() {
464     /// let re = Regex::new(r"(?P<last>[^,\s]+),\s+(?P<first>\S+)").unwrap();
465     /// let result = re.replace("Springsteen, Bruce", "$first $last");
466     /// assert_eq!(result, "Bruce Springsteen");
467     /// # }
468     /// ```
469     ///
470     /// Note that using `$2` instead of `$first` or `$1` instead of `$last`
471     /// would produce the same result. To write a literal `$` use `$$`.
472     ///
473     /// Sometimes the replacement string requires use of curly braces to
474     /// delineate a capture group replacement and surrounding literal text.
475     /// For example, if we wanted to join two words together with an
476     /// underscore:
477     ///
478     /// ```rust
479     /// # extern crate regex; use regex::Regex;
480     /// # fn main() {
481     /// let re = Regex::new(r"(?P<first>\w+)\s+(?P<second>\w+)").unwrap();
482     /// let result = re.replace("deep fried", "${first}_$second");
483     /// assert_eq!(result, "deep_fried");
484     /// # }
485     /// ```
486     ///
487     /// Without the curly braces, the capture group name `first_` would be
488     /// used, and since it doesn't exist, it would be replaced with the empty
489     /// string.
490     ///
491     /// Finally, sometimes you just want to replace a literal string with no
492     /// regard for capturing group expansion. This can be done by wrapping a
493     /// byte string with `NoExpand`:
494     ///
495     /// ```rust
496     /// # extern crate regex; use regex::Regex;
497     /// # fn main() {
498     /// use regex::NoExpand;
499     ///
500     /// let re = Regex::new(r"(?P<last>[^,\s]+),\s+(\S+)").unwrap();
501     /// let result = re.replace("Springsteen, Bruce", NoExpand("$2 $last"));
502     /// assert_eq!(result, "$2 $last");
503     /// # }
504     /// ```
replace<'t, R: Replacer>( &self, text: &'t str, rep: R, ) -> Cow<'t, str>505     pub fn replace<'t, R: Replacer>(
506         &self,
507         text: &'t str,
508         rep: R,
509     ) -> Cow<'t, str> {
510         self.replacen(text, 1, rep)
511     }
512 
513     /// Replaces all non-overlapping matches in `text` with the replacement
514     /// provided. This is the same as calling `replacen` with `limit` set to
515     /// `0`.
516     ///
517     /// See the documentation for `replace` for details on how to access
518     /// capturing group matches in the replacement string.
replace_all<'t, R: Replacer>( &self, text: &'t str, rep: R, ) -> Cow<'t, str>519     pub fn replace_all<'t, R: Replacer>(
520         &self,
521         text: &'t str,
522         rep: R,
523     ) -> Cow<'t, str> {
524         self.replacen(text, 0, rep)
525     }
526 
527     /// Replaces at most `limit` non-overlapping matches in `text` with the
528     /// replacement provided. If `limit` is 0, then all non-overlapping matches
529     /// are replaced.
530     ///
531     /// See the documentation for `replace` for details on how to access
532     /// capturing group matches in the replacement string.
replacen<'t, R: Replacer>( &self, text: &'t str, limit: usize, mut rep: R, ) -> Cow<'t, str>533     pub fn replacen<'t, R: Replacer>(
534         &self,
535         text: &'t str,
536         limit: usize,
537         mut rep: R,
538     ) -> Cow<'t, str> {
539         // If we know that the replacement doesn't have any capture expansions,
540         // then we can fast path. The fast path can make a tremendous
541         // difference:
542         //
543         //   1) We use `find_iter` instead of `captures_iter`. Not asking for
544         //      captures generally makes the regex engines faster.
545         //   2) We don't need to look up all of the capture groups and do
546         //      replacements inside the replacement string. We just push it
547         //      at each match and be done with it.
548         if let Some(rep) = rep.no_expansion() {
549             let mut it = self.find_iter(text).enumerate().peekable();
550             if it.peek().is_none() {
551                 return Cow::Borrowed(text);
552             }
553             let mut new = String::with_capacity(text.len());
554             let mut last_match = 0;
555             for (i, m) in it {
556                 if limit > 0 && i >= limit {
557                     break;
558                 }
559                 new.push_str(&text[last_match..m.start()]);
560                 new.push_str(&rep);
561                 last_match = m.end();
562             }
563             new.push_str(&text[last_match..]);
564             return Cow::Owned(new);
565         }
566 
567         // The slower path, which we use if the replacement needs access to
568         // capture groups.
569         let mut it = self.captures_iter(text).enumerate().peekable();
570         if it.peek().is_none() {
571             return Cow::Borrowed(text);
572         }
573         let mut new = String::with_capacity(text.len());
574         let mut last_match = 0;
575         for (i, cap) in it {
576             if limit > 0 && i >= limit {
577                 break;
578             }
579             // unwrap on 0 is OK because captures only reports matches
580             let m = cap.get(0).unwrap();
581             new.push_str(&text[last_match..m.start()]);
582             rep.replace_append(&cap, &mut new);
583             last_match = m.end();
584         }
585         new.push_str(&text[last_match..]);
586         Cow::Owned(new)
587     }
588 }
589 
590 /// Advanced or "lower level" search methods.
591 impl Regex {
592     /// Returns the end location of a match in the text given.
593     ///
594     /// This method may have the same performance characteristics as
595     /// `is_match`, except it provides an end location for a match. In
596     /// particular, the location returned *may be shorter* than the proper end
597     /// of the leftmost-first match.
598     ///
599     /// # Example
600     ///
601     /// Typically, `a+` would match the entire first sequence of `a` in some
602     /// text, but `shortest_match` can give up as soon as it sees the first
603     /// `a`.
604     ///
605     /// ```rust
606     /// # extern crate regex; use regex::Regex;
607     /// # fn main() {
608     /// let text = "aaaaa";
609     /// let pos = Regex::new(r"a+").unwrap().shortest_match(text);
610     /// assert_eq!(pos, Some(1));
611     /// # }
612     /// ```
shortest_match(&self, text: &str) -> Option<usize>613     pub fn shortest_match(&self, text: &str) -> Option<usize> {
614         self.shortest_match_at(text, 0)
615     }
616 
617     /// Returns the same as shortest_match, but starts the search at the given
618     /// offset.
619     ///
620     /// The significance of the starting point is that it takes the surrounding
621     /// context into consideration. For example, the `\A` anchor can only
622     /// match when `start == 0`.
shortest_match_at( &self, text: &str, start: usize, ) -> Option<usize>623     pub fn shortest_match_at(
624         &self,
625         text: &str,
626         start: usize,
627     ) -> Option<usize> {
628         self.0.searcher_str().shortest_match_at(text, start)
629     }
630 
631     /// Returns the same as is_match, but starts the search at the given
632     /// offset.
633     ///
634     /// The significance of the starting point is that it takes the surrounding
635     /// context into consideration. For example, the `\A` anchor can only
636     /// match when `start == 0`.
is_match_at(&self, text: &str, start: usize) -> bool637     pub fn is_match_at(&self, text: &str, start: usize) -> bool {
638         self.shortest_match_at(text, start).is_some()
639     }
640 
641     /// Returns the same as find, but starts the search at the given
642     /// offset.
643     ///
644     /// The significance of the starting point is that it takes the surrounding
645     /// context into consideration. For example, the `\A` anchor can only
646     /// match when `start == 0`.
find_at<'t>( &self, text: &'t str, start: usize, ) -> Option<Match<'t>>647     pub fn find_at<'t>(
648         &self,
649         text: &'t str,
650         start: usize,
651     ) -> Option<Match<'t>> {
652         self.0
653             .searcher_str()
654             .find_at(text, start)
655             .map(|(s, e)| Match::new(text, s, e))
656     }
657 
658     /// This is like `captures`, but uses
659     /// [`CaptureLocations`](struct.CaptureLocations.html)
660     /// instead of
661     /// [`Captures`](struct.Captures.html) in order to amortize allocations.
662     ///
663     /// To create a `CaptureLocations` value, use the
664     /// `Regex::capture_locations` method.
665     ///
666     /// This returns the overall match if this was successful, which is always
667     /// equivalence to the `0`th capture group.
captures_read<'t>( &self, locs: &mut CaptureLocations, text: &'t str, ) -> Option<Match<'t>>668     pub fn captures_read<'t>(
669         &self,
670         locs: &mut CaptureLocations,
671         text: &'t str,
672     ) -> Option<Match<'t>> {
673         self.captures_read_at(locs, text, 0)
674     }
675 
676     /// Returns the same as captures, but starts the search at the given
677     /// offset and populates the capture locations given.
678     ///
679     /// The significance of the starting point is that it takes the surrounding
680     /// context into consideration. For example, the `\A` anchor can only
681     /// match when `start == 0`.
captures_read_at<'t>( &self, locs: &mut CaptureLocations, text: &'t str, start: usize, ) -> Option<Match<'t>>682     pub fn captures_read_at<'t>(
683         &self,
684         locs: &mut CaptureLocations,
685         text: &'t str,
686         start: usize,
687     ) -> Option<Match<'t>> {
688         self.0
689             .searcher_str()
690             .captures_read_at(&mut locs.0, text, start)
691             .map(|(s, e)| Match::new(text, s, e))
692     }
693 
694     /// An undocumented alias for `captures_read_at`.
695     ///
696     /// The `regex-capi` crate previously used this routine, so to avoid
697     /// breaking that crate, we continue to provide the name as an undocumented
698     /// alias.
699     #[doc(hidden)]
read_captures_at<'t>( &self, locs: &mut CaptureLocations, text: &'t str, start: usize, ) -> Option<Match<'t>>700     pub fn read_captures_at<'t>(
701         &self,
702         locs: &mut CaptureLocations,
703         text: &'t str,
704         start: usize,
705     ) -> Option<Match<'t>> {
706         self.captures_read_at(locs, text, start)
707     }
708 }
709 
710 /// Auxiliary methods.
711 impl Regex {
712     /// Returns the original string of this regex.
as_str(&self) -> &str713     pub fn as_str(&self) -> &str {
714         &self.0.regex_strings()[0]
715     }
716 
717     /// Returns an iterator over the capture names.
capture_names(&self) -> CaptureNames718     pub fn capture_names(&self) -> CaptureNames {
719         CaptureNames(self.0.capture_names().iter())
720     }
721 
722     /// Returns the number of captures.
captures_len(&self) -> usize723     pub fn captures_len(&self) -> usize {
724         self.0.capture_names().len()
725     }
726 
727     /// Returns an empty set of capture locations that can be reused in
728     /// multiple calls to `captures_read` or `captures_read_at`.
capture_locations(&self) -> CaptureLocations729     pub fn capture_locations(&self) -> CaptureLocations {
730         CaptureLocations(self.0.searcher_str().locations())
731     }
732 
733     /// An alias for `capture_locations` to preserve backward compatibility.
734     ///
735     /// The `regex-capi` crate uses this method, so to avoid breaking that
736     /// crate, we continue to export it as an undocumented API.
737     #[doc(hidden)]
locations(&self) -> CaptureLocations738     pub fn locations(&self) -> CaptureLocations {
739         CaptureLocations(self.0.searcher_str().locations())
740     }
741 }
742 
743 /// An iterator over the names of all possible captures.
744 ///
745 /// `None` indicates an unnamed capture; the first element (capture 0, the
746 /// whole matched region) is always unnamed.
747 ///
748 /// `'r` is the lifetime of the compiled regular expression.
749 pub struct CaptureNames<'r>(::std::slice::Iter<'r, Option<String>>);
750 
751 impl<'r> Iterator for CaptureNames<'r> {
752     type Item = Option<&'r str>;
753 
next(&mut self) -> Option<Option<&'r str>>754     fn next(&mut self) -> Option<Option<&'r str>> {
755         self.0
756             .next()
757             .as_ref()
758             .map(|slot| slot.as_ref().map(|name| name.as_ref()))
759     }
760 
size_hint(&self) -> (usize, Option<usize>)761     fn size_hint(&self) -> (usize, Option<usize>) {
762         self.0.size_hint()
763     }
764 }
765 
766 /// Yields all substrings delimited by a regular expression match.
767 ///
768 /// `'r` is the lifetime of the compiled regular expression and `'t` is the
769 /// lifetime of the string being split.
770 pub struct Split<'r, 't> {
771     finder: Matches<'r, 't>,
772     last: usize,
773 }
774 
775 impl<'r, 't> Iterator for Split<'r, 't> {
776     type Item = &'t str;
777 
next(&mut self) -> Option<&'t str>778     fn next(&mut self) -> Option<&'t str> {
779         let text = self.finder.0.text();
780         match self.finder.next() {
781             None => {
782                 if self.last > text.len() {
783                     None
784                 } else {
785                     let s = &text[self.last..];
786                     self.last = text.len() + 1; // Next call will return None
787                     Some(s)
788                 }
789             }
790             Some(m) => {
791                 let matched = &text[self.last..m.start()];
792                 self.last = m.end();
793                 Some(matched)
794             }
795         }
796     }
797 }
798 
799 /// Yields at most `N` substrings delimited by a regular expression match.
800 ///
801 /// The last substring will be whatever remains after splitting.
802 ///
803 /// `'r` is the lifetime of the compiled regular expression and `'t` is the
804 /// lifetime of the string being split.
805 pub struct SplitN<'r, 't> {
806     splits: Split<'r, 't>,
807     n: usize,
808 }
809 
810 impl<'r, 't> Iterator for SplitN<'r, 't> {
811     type Item = &'t str;
812 
next(&mut self) -> Option<&'t str>813     fn next(&mut self) -> Option<&'t str> {
814         if self.n == 0 {
815             return None;
816         }
817 
818         self.n -= 1;
819         if self.n > 0 {
820             return self.splits.next();
821         }
822 
823         let text = self.splits.finder.0.text();
824         if self.splits.last > text.len() {
825             // We've already returned all substrings.
826             None
827         } else {
828             // self.n == 0, so future calls will return None immediately
829             Some(&text[self.splits.last..])
830         }
831     }
832 }
833 
834 /// CaptureLocations is a low level representation of the raw offsets of each
835 /// submatch.
836 ///
837 /// You can think of this as a lower level
838 /// [`Captures`](struct.Captures.html), where this type does not support
839 /// named capturing groups directly and it does not borrow the text that these
840 /// offsets were matched on.
841 ///
842 /// Primarily, this type is useful when using the lower level `Regex` APIs
843 /// such as `read_captures`, which permits amortizing the allocation in which
844 /// capture match locations are stored.
845 ///
846 /// In order to build a value of this type, you'll need to call the
847 /// `capture_locations` method on the `Regex` being used to execute the search.
848 /// The value returned can then be reused in subsequent searches.
849 #[derive(Clone, Debug)]
850 pub struct CaptureLocations(re_trait::Locations);
851 
852 /// A type alias for `CaptureLocations` for backwards compatibility.
853 ///
854 /// Previously, we exported `CaptureLocations` as `Locations` in an
855 /// undocumented API. To prevent breaking that code (e.g., in `regex-capi`),
856 /// we continue re-exporting the same undocumented API.
857 #[doc(hidden)]
858 pub type Locations = CaptureLocations;
859 
860 impl CaptureLocations {
861     /// Returns the start and end positions of the Nth capture group. Returns
862     /// `None` if `i` is not a valid capture group or if the capture group did
863     /// not match anything. The positions returned are *always* byte indices
864     /// with respect to the original string matched.
865     #[inline]
get(&self, i: usize) -> Option<(usize, usize)>866     pub fn get(&self, i: usize) -> Option<(usize, usize)> {
867         self.0.pos(i)
868     }
869 
870     /// Returns the total number of capturing groups.
871     ///
872     /// This is always at least `1` since every regex has at least `1`
873     /// capturing group that corresponds to the entire match.
874     #[inline]
len(&self) -> usize875     pub fn len(&self) -> usize {
876         self.0.len()
877     }
878 
879     /// An alias for the `get` method for backwards compatibility.
880     ///
881     /// Previously, we exported `get` as `pos` in an undocumented API. To
882     /// prevent breaking that code (e.g., in `regex-capi`), we continue
883     /// re-exporting the same undocumented API.
884     #[doc(hidden)]
885     #[inline]
pos(&self, i: usize) -> Option<(usize, usize)>886     pub fn pos(&self, i: usize) -> Option<(usize, usize)> {
887         self.get(i)
888     }
889 }
890 
891 /// Captures represents a group of captured strings for a single match.
892 ///
893 /// The 0th capture always corresponds to the entire match. Each subsequent
894 /// index corresponds to the next capture group in the regex. If a capture
895 /// group is named, then the matched string is *also* available via the `name`
896 /// method. (Note that the 0th capture is always unnamed and so must be
897 /// accessed with the `get` method.)
898 ///
899 /// Positions returned from a capture group are always byte indices.
900 ///
901 /// `'t` is the lifetime of the matched text.
902 pub struct Captures<'t> {
903     text: &'t str,
904     locs: re_trait::Locations,
905     named_groups: Arc<HashMap<String, usize>>,
906 }
907 
908 impl<'t> Captures<'t> {
909     /// Returns the match associated with the capture group at index `i`. If
910     /// `i` does not correspond to a capture group, or if the capture group
911     /// did not participate in the match, then `None` is returned.
912     ///
913     /// # Examples
914     ///
915     /// Get the text of the match with a default of an empty string if this
916     /// group didn't participate in the match:
917     ///
918     /// ```rust
919     /// # use regex::Regex;
920     /// let re = Regex::new(r"[a-z]+(?:([0-9]+)|([A-Z]+))").unwrap();
921     /// let caps = re.captures("abc123").unwrap();
922     ///
923     /// let text1 = caps.get(1).map_or("", |m| m.as_str());
924     /// let text2 = caps.get(2).map_or("", |m| m.as_str());
925     /// assert_eq!(text1, "123");
926     /// assert_eq!(text2, "");
927     /// ```
get(&self, i: usize) -> Option<Match<'t>>928     pub fn get(&self, i: usize) -> Option<Match<'t>> {
929         self.locs.pos(i).map(|(s, e)| Match::new(self.text, s, e))
930     }
931 
932     /// Returns the match for the capture group named `name`. If `name` isn't a
933     /// valid capture group or didn't match anything, then `None` is returned.
name(&self, name: &str) -> Option<Match<'t>>934     pub fn name(&self, name: &str) -> Option<Match<'t>> {
935         self.named_groups.get(name).and_then(|&i| self.get(i))
936     }
937 
938     /// An iterator that yields all capturing matches in the order in which
939     /// they appear in the regex. If a particular capture group didn't
940     /// participate in the match, then `None` is yielded for that capture.
941     ///
942     /// The first match always corresponds to the overall match of the regex.
iter<'c>(&'c self) -> SubCaptureMatches<'c, 't>943     pub fn iter<'c>(&'c self) -> SubCaptureMatches<'c, 't> {
944         SubCaptureMatches { caps: self, it: self.locs.iter() }
945     }
946 
947     /// Expands all instances of `$name` in `replacement` to the corresponding
948     /// capture group `name`, and writes them to the `dst` buffer given.
949     ///
950     /// `name` may be an integer corresponding to the index of the
951     /// capture group (counted by order of opening parenthesis where `0` is the
952     /// entire match) or it can be a name (consisting of letters, digits or
953     /// underscores) corresponding to a named capture group.
954     ///
955     /// If `name` isn't a valid capture group (whether the name doesn't exist
956     /// or isn't a valid index), then it is replaced with the empty string.
957     ///
958     /// The longest possible name is used. e.g., `$1a` looks up the capture
959     /// group named `1a` and not the capture group at index `1`. To exert more
960     /// precise control over the name, use braces, e.g., `${1}a`.
961     ///
962     /// To write a literal `$` use `$$`.
expand(&self, replacement: &str, dst: &mut String)963     pub fn expand(&self, replacement: &str, dst: &mut String) {
964         expand_str(self, replacement, dst)
965     }
966 
967     /// Returns the number of captured groups.
968     ///
969     /// This is always at least `1`, since every regex has at least one capture
970     /// group that corresponds to the full match.
971     #[inline]
len(&self) -> usize972     pub fn len(&self) -> usize {
973         self.locs.len()
974     }
975 }
976 
977 impl<'t> fmt::Debug for Captures<'t> {
fmt(&self, f: &mut fmt::Formatter) -> fmt::Result978     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
979         f.debug_tuple("Captures").field(&CapturesDebug(self)).finish()
980     }
981 }
982 
983 struct CapturesDebug<'c, 't: 'c>(&'c Captures<'t>);
984 
985 impl<'c, 't> fmt::Debug for CapturesDebug<'c, 't> {
fmt(&self, f: &mut fmt::Formatter) -> fmt::Result986     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
987         // We'd like to show something nice here, even if it means an
988         // allocation to build a reverse index.
989         let slot_to_name: HashMap<&usize, &String> =
990             self.0.named_groups.iter().map(|(a, b)| (b, a)).collect();
991         let mut map = f.debug_map();
992         for (slot, m) in self.0.locs.iter().enumerate() {
993             let m = m.map(|(s, e)| &self.0.text[s..e]);
994             if let Some(name) = slot_to_name.get(&slot) {
995                 map.entry(&name, &m);
996             } else {
997                 map.entry(&slot, &m);
998             }
999         }
1000         map.finish()
1001     }
1002 }
1003 
1004 /// Get a group by index.
1005 ///
1006 /// `'t` is the lifetime of the matched text.
1007 ///
1008 /// The text can't outlive the `Captures` object if this method is
1009 /// used, because of how `Index` is defined (normally `a[i]` is part
1010 /// of `a` and can't outlive it); to do that, use `get()` instead.
1011 ///
1012 /// # Panics
1013 ///
1014 /// If there is no group at the given index.
1015 impl<'t> Index<usize> for Captures<'t> {
1016     type Output = str;
1017 
index(&self, i: usize) -> &str1018     fn index(&self, i: usize) -> &str {
1019         self.get(i)
1020             .map(|m| m.as_str())
1021             .unwrap_or_else(|| panic!("no group at index '{}'", i))
1022     }
1023 }
1024 
1025 /// Get a group by name.
1026 ///
1027 /// `'t` is the lifetime of the matched text and `'i` is the lifetime
1028 /// of the group name (the index).
1029 ///
1030 /// The text can't outlive the `Captures` object if this method is
1031 /// used, because of how `Index` is defined (normally `a[i]` is part
1032 /// of `a` and can't outlive it); to do that, use `name` instead.
1033 ///
1034 /// # Panics
1035 ///
1036 /// If there is no group named by the given value.
1037 impl<'t, 'i> Index<&'i str> for Captures<'t> {
1038     type Output = str;
1039 
index<'a>(&'a self, name: &'i str) -> &'a str1040     fn index<'a>(&'a self, name: &'i str) -> &'a str {
1041         self.name(name)
1042             .map(|m| m.as_str())
1043             .unwrap_or_else(|| panic!("no group named '{}'", name))
1044     }
1045 }
1046 
1047 /// An iterator that yields all capturing matches in the order in which they
1048 /// appear in the regex.
1049 ///
1050 /// If a particular capture group didn't participate in the match, then `None`
1051 /// is yielded for that capture. The first match always corresponds to the
1052 /// overall match of the regex.
1053 ///
1054 /// The lifetime `'c` corresponds to the lifetime of the `Captures` value, and
1055 /// the lifetime `'t` corresponds to the originally matched text.
1056 pub struct SubCaptureMatches<'c, 't: 'c> {
1057     caps: &'c Captures<'t>,
1058     it: SubCapturesPosIter<'c>,
1059 }
1060 
1061 impl<'c, 't> Iterator for SubCaptureMatches<'c, 't> {
1062     type Item = Option<Match<'t>>;
1063 
next(&mut self) -> Option<Option<Match<'t>>>1064     fn next(&mut self) -> Option<Option<Match<'t>>> {
1065         self.it
1066             .next()
1067             .map(|cap| cap.map(|(s, e)| Match::new(self.caps.text, s, e)))
1068     }
1069 }
1070 
1071 /// An iterator that yields all non-overlapping capture groups matching a
1072 /// particular regular expression.
1073 ///
1074 /// The iterator stops when no more matches can be found.
1075 ///
1076 /// `'r` is the lifetime of the compiled regular expression and `'t` is the
1077 /// lifetime of the matched string.
1078 pub struct CaptureMatches<'r, 't>(
1079     re_trait::CaptureMatches<'t, ExecNoSyncStr<'r>>,
1080 );
1081 
1082 impl<'r, 't> Iterator for CaptureMatches<'r, 't> {
1083     type Item = Captures<'t>;
1084 
next(&mut self) -> Option<Captures<'t>>1085     fn next(&mut self) -> Option<Captures<'t>> {
1086         self.0.next().map(|locs| Captures {
1087             text: self.0.text(),
1088             locs: locs,
1089             named_groups: self.0.regex().capture_name_idx().clone(),
1090         })
1091     }
1092 }
1093 
1094 /// An iterator over all non-overlapping matches for a particular string.
1095 ///
1096 /// The iterator yields a `Match` value. The iterator stops when no more
1097 /// matches can be found.
1098 ///
1099 /// `'r` is the lifetime of the compiled regular expression and `'t` is the
1100 /// lifetime of the matched string.
1101 pub struct Matches<'r, 't>(re_trait::Matches<'t, ExecNoSyncStr<'r>>);
1102 
1103 impl<'r, 't> Iterator for Matches<'r, 't> {
1104     type Item = Match<'t>;
1105 
next(&mut self) -> Option<Match<'t>>1106     fn next(&mut self) -> Option<Match<'t>> {
1107         let text = self.0.text();
1108         self.0.next().map(|(s, e)| Match::new(text, s, e))
1109     }
1110 }
1111 
1112 /// Replacer describes types that can be used to replace matches in a string.
1113 ///
1114 /// In general, users of this crate shouldn't need to implement this trait,
1115 /// since implementations are already provided for `&str` and
1116 /// `FnMut(&Captures) -> String` (or any `FnMut(&Captures) -> T`
1117 /// where `T: AsRef<str>`), which covers most use cases.
1118 pub trait Replacer {
1119     /// Appends text to `dst` to replace the current match.
1120     ///
1121     /// The current match is represented by `caps`, which is guaranteed to
1122     /// have a match at capture group `0`.
1123     ///
1124     /// For example, a no-op replacement would be
1125     /// `dst.extend(caps.get(0).unwrap().as_str())`.
replace_append(&mut self, caps: &Captures, dst: &mut String)1126     fn replace_append(&mut self, caps: &Captures, dst: &mut String);
1127 
1128     /// Return a fixed unchanging replacement string.
1129     ///
1130     /// When doing replacements, if access to `Captures` is not needed (e.g.,
1131     /// the replacement byte string does not need `$` expansion), then it can
1132     /// be beneficial to avoid finding sub-captures.
1133     ///
1134     /// In general, this is called once for every call to `replacen`.
no_expansion<'r>(&'r mut self) -> Option<Cow<'r, str>>1135     fn no_expansion<'r>(&'r mut self) -> Option<Cow<'r, str>> {
1136         None
1137     }
1138 
1139     /// Return a `Replacer` that borrows and wraps this `Replacer`.
1140     ///
1141     /// This is useful when you want to take a generic `Replacer` (which might
1142     /// not be cloneable) and use it without consuming it, so it can be used
1143     /// more than once.
1144     ///
1145     /// # Example
1146     ///
1147     /// ```
1148     /// use regex::{Regex, Replacer};
1149     ///
1150     /// fn replace_all_twice<R: Replacer>(
1151     ///     re: Regex,
1152     ///     src: &str,
1153     ///     mut rep: R,
1154     /// ) -> String {
1155     ///     let dst = re.replace_all(src, rep.by_ref());
1156     ///     let dst = re.replace_all(&dst, rep.by_ref());
1157     ///     dst.into_owned()
1158     /// }
1159     /// ```
by_ref<'r>(&'r mut self) -> ReplacerRef<'r, Self>1160     fn by_ref<'r>(&'r mut self) -> ReplacerRef<'r, Self> {
1161         ReplacerRef(self)
1162     }
1163 }
1164 
1165 /// By-reference adaptor for a `Replacer`
1166 ///
1167 /// Returned by [`Replacer::by_ref`](trait.Replacer.html#method.by_ref).
1168 #[derive(Debug)]
1169 pub struct ReplacerRef<'a, R: ?Sized + 'a>(&'a mut R);
1170 
1171 impl<'a, R: Replacer + ?Sized + 'a> Replacer for ReplacerRef<'a, R> {
replace_append(&mut self, caps: &Captures, dst: &mut String)1172     fn replace_append(&mut self, caps: &Captures, dst: &mut String) {
1173         self.0.replace_append(caps, dst)
1174     }
no_expansion(&mut self) -> Option<Cow<str>>1175     fn no_expansion(&mut self) -> Option<Cow<str>> {
1176         self.0.no_expansion()
1177     }
1178 }
1179 
1180 impl<'a> Replacer for &'a str {
replace_append(&mut self, caps: &Captures, dst: &mut String)1181     fn replace_append(&mut self, caps: &Captures, dst: &mut String) {
1182         caps.expand(*self, dst);
1183     }
1184 
no_expansion(&mut self) -> Option<Cow<str>>1185     fn no_expansion(&mut self) -> Option<Cow<str>> {
1186         match find_byte(b'$', self.as_bytes()) {
1187             Some(_) => None,
1188             None => Some(Cow::Borrowed(*self)),
1189         }
1190     }
1191 }
1192 
1193 impl<F, T> Replacer for F
1194 where
1195     F: FnMut(&Captures) -> T,
1196     T: AsRef<str>,
1197 {
replace_append(&mut self, caps: &Captures, dst: &mut String)1198     fn replace_append(&mut self, caps: &Captures, dst: &mut String) {
1199         dst.push_str((*self)(caps).as_ref());
1200     }
1201 }
1202 
1203 /// `NoExpand` indicates literal string replacement.
1204 ///
1205 /// It can be used with `replace` and `replace_all` to do a literal string
1206 /// replacement without expanding `$name` to their corresponding capture
1207 /// groups. This can be both convenient (to avoid escaping `$`, for example)
1208 /// and performant (since capture groups don't need to be found).
1209 ///
1210 /// `'t` is the lifetime of the literal text.
1211 pub struct NoExpand<'t>(pub &'t str);
1212 
1213 impl<'t> Replacer for NoExpand<'t> {
replace_append(&mut self, _: &Captures, dst: &mut String)1214     fn replace_append(&mut self, _: &Captures, dst: &mut String) {
1215         dst.push_str(self.0);
1216     }
1217 
no_expansion(&mut self) -> Option<Cow<str>>1218     fn no_expansion(&mut self) -> Option<Cow<str>> {
1219         Some(Cow::Borrowed(self.0))
1220     }
1221 }
1222