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