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