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}