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