regex/
re_bytes.rs

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