]>
Commit | Line | Data |
---|---|---|
8bb4bdeb XL |
1 | use std::borrow::Cow; |
2 | use std::collections::HashMap; | |
3 | use std::fmt; | |
5869c6ff | 4 | use std::iter::FusedIterator; |
f9f354fc | 5 | use std::ops::{Index, Range}; |
8bb4bdeb XL |
6 | use std::str::FromStr; |
7 | use std::sync::Arc; | |
8 | ||
c295e0f8 | 9 | use crate::find_byte::find_byte; |
8bb4bdeb | 10 | |
c295e0f8 XL |
11 | use crate::error::Error; |
12 | use crate::exec::{Exec, ExecNoSyncStr}; | |
13 | use crate::expand::expand_str; | |
14 | use crate::re_builder::unicode::RegexBuilder; | |
15 | use crate::re_trait::{self, RegularExpression, SubCapturesPosIter}; | |
8bb4bdeb XL |
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. | |
21 | pub fn escape(text: &str) -> String { | |
c295e0f8 | 22 | regex_syntax::escape(text) |
8bb4bdeb XL |
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)] | |
29 | pub struct Match<'t> { | |
30 | text: &'t str, | |
31 | start: usize, | |
32 | end: usize, | |
33 | } | |
34 | ||
35 | impl<'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 | ||
f9f354fc XL |
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 | ||
8bb4bdeb XL |
55 | /// Returns the matched text. |
56 | #[inline] | |
57 | pub fn as_str(&self) -> &'t str { | |
f9f354fc | 58 | &self.text[self.range()] |
8bb4bdeb XL |
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> { | |
f9f354fc | 64 | Match { text: haystack, start: start, end: end } |
8bb4bdeb XL |
65 | } |
66 | } | |
67 | ||
ff7c6d11 XL |
68 | impl<'t> From<Match<'t>> for &'t str { |
69 | fn from(m: Match<'t>) -> &'t str { | |
70 | m.as_str() | |
71 | } | |
72 | } | |
73 | ||
f9f354fc XL |
74 | impl<'t> From<Match<'t>> for Range<usize> { |
75 | fn from(m: Match<'t>) -> Range<usize> { | |
76 | m.range() | |
77 | } | |
78 | } | |
79 | ||
8bb4bdeb XL |
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)] | |
2c00a5a8 | 136 | pub struct Regex(Exec); |
8bb4bdeb XL |
137 | |
138 | impl fmt::Display for Regex { | |
139 | /// Shows the original regular expression. | |
c295e0f8 | 140 | fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
8bb4bdeb XL |
141 | write!(f, "{}", self.as_str()) |
142 | } | |
143 | } | |
144 | ||
145 | impl fmt::Debug for Regex { | |
146 | /// Shows the original regular expression. | |
c295e0f8 | 147 | fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
8bb4bdeb XL |
148 | fmt::Display::fmt(self, f) |
149 | } | |
150 | } | |
151 | ||
152 | #[doc(hidden)] | |
153 | impl From<Exec> for Regex { | |
154 | fn from(exec: Exec) -> Regex { | |
2c00a5a8 | 155 | Regex(exec) |
8bb4bdeb XL |
156 | } |
157 | } | |
158 | ||
159 | impl 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. | |
169 | impl 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 | ||
5869c6ff XL |
178 | /// Returns true if and only if there is a match for the regex in the |
179 | /// string given. | |
8bb4bdeb XL |
180 | /// |
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 | |
c295e0f8 | 191 | /// # use regex::Regex; |
8bb4bdeb XL |
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 | |
c295e0f8 | 214 | /// # use regex::Regex; |
8bb4bdeb XL |
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 | |
c295e0f8 | 236 | /// # use regex::Regex; |
8bb4bdeb XL |
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> { | |
2c00a5a8 | 245 | Matches(self.0.searcher_str().find_iter(text)) |
8bb4bdeb XL |
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 | |
c295e0f8 | 264 | /// # use regex::Regex; |
8bb4bdeb XL |
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 | |
c295e0f8 | 286 | /// # use regex::Regex; |
8bb4bdeb XL |
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(); | |
b7449926 XL |
292 | /// assert_eq!(caps.name("title").unwrap().as_str(), "Citizen Kane"); |
293 | /// assert_eq!(caps.name("year").unwrap().as_str(), "1941"); | |
8bb4bdeb XL |
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 | |
041b39d2 | 306 | /// capture groups are still accessible with `get` or the `Index` notation |
8bb4bdeb XL |
307 | /// with a `usize`. |
308 | /// | |
309 | /// The `0`th capture group is always unnamed, so it must always be | |
ff7c6d11 | 310 | /// accessed with `get(0)` or `[0]`. |
8bb4bdeb | 311 | pub fn captures<'t>(&self, text: &'t str) -> Option<Captures<'t>> { |
b7449926 XL |
312 | let mut locs = self.capture_locations(); |
313 | self.captures_read_at(&mut locs, text, 0).map(move |_| Captures { | |
8bb4bdeb | 314 | text: text, |
b7449926 | 315 | locs: locs.0, |
2c00a5a8 | 316 | named_groups: self.0.capture_name_idx().clone(), |
8bb4bdeb XL |
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 | |
c295e0f8 | 330 | /// # use regex::Regex; |
8bb4bdeb XL |
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> { | |
2c00a5a8 | 349 | CaptureMatches(self.0.searcher_str().captures_iter(text)) |
8bb4bdeb XL |
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 | |
c295e0f8 | 363 | /// # use regex::Regex; |
8bb4bdeb XL |
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> { | |
f9f354fc | 371 | Split { finder: self.find_iter(text), last: 0 } |
8bb4bdeb XL |
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 | |
c295e0f8 | 387 | /// # use regex::Regex; |
8bb4bdeb XL |
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 | /// ``` | |
f9f354fc XL |
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 } | |
8bb4bdeb XL |
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 | |
c295e0f8 | 434 | /// # use regex::Regex; |
8bb4bdeb XL |
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 | |
c295e0f8 | 447 | /// # use regex::Regex; |
8bb4bdeb XL |
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 | |
c295e0f8 | 463 | /// # use regex::Regex; |
8bb4bdeb XL |
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 | /// | |
041b39d2 XL |
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 | |
c295e0f8 | 480 | /// # use regex::Regex; |
041b39d2 XL |
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 | /// | |
8bb4bdeb XL |
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 | |
c295e0f8 | 497 | /// # use regex::Regex; |
8bb4bdeb XL |
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, | |
ee023bcb | 541 | // then we can use the fast path. The fast path can make a tremendous |
8bb4bdeb XL |
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() { | |
ff7c6d11 XL |
550 | let mut it = self.find_iter(text).enumerate().peekable(); |
551 | if it.peek().is_none() { | |
552 | return Cow::Borrowed(text); | |
553 | } | |
8bb4bdeb XL |
554 | let mut new = String::with_capacity(text.len()); |
555 | let mut last_match = 0; | |
ff7c6d11 | 556 | for (i, m) in it { |
8bb4bdeb | 557 | if limit > 0 && i >= limit { |
f9f354fc | 558 | break; |
8bb4bdeb XL |
559 | } |
560 | new.push_str(&text[last_match..m.start()]); | |
561 | new.push_str(&rep); | |
562 | last_match = m.end(); | |
563 | } | |
8bb4bdeb XL |
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 { | |
f9f354fc | 578 | break; |
8bb4bdeb XL |
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. | |
592 | impl 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 | |
c295e0f8 | 607 | /// # use regex::Regex; |
8bb4bdeb XL |
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`. | |
8bb4bdeb XL |
624 | pub fn shortest_match_at( |
625 | &self, | |
626 | text: &str, | |
627 | start: usize, | |
628 | ) -> Option<usize> { | |
2c00a5a8 | 629 | self.0.searcher_str().shortest_match_at(text, start) |
8bb4bdeb XL |
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`. | |
8bb4bdeb XL |
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`. | |
8bb4bdeb XL |
648 | pub fn find_at<'t>( |
649 | &self, | |
650 | text: &'t str, | |
651 | start: usize, | |
652 | ) -> Option<Match<'t>> { | |
f9f354fc XL |
653 | self.0 |
654 | .searcher_str() | |
655 | .find_at(text, start) | |
656 | .map(|(s, e)| Match::new(text, s, e)) | |
8bb4bdeb XL |
657 | } |
658 | ||
b7449926 XL |
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 | ||
8bb4bdeb XL |
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`. | |
b7449926 | 683 | pub fn captures_read_at<'t>( |
8bb4bdeb | 684 | &self, |
b7449926 | 685 | locs: &mut CaptureLocations, |
8bb4bdeb XL |
686 | text: &'t str, |
687 | start: usize, | |
688 | ) -> Option<Match<'t>> { | |
2c00a5a8 XL |
689 | self.0 |
690 | .searcher_str() | |
b7449926 | 691 | .captures_read_at(&mut locs.0, text, start) |
2c00a5a8 | 692 | .map(|(s, e)| Match::new(text, s, e)) |
8bb4bdeb | 693 | } |
b7449926 XL |
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 | } | |
8bb4bdeb XL |
709 | } |
710 | ||
711 | /// Auxiliary methods. | |
712 | impl Regex { | |
713 | /// Returns the original string of this regex. | |
714 | pub fn as_str(&self) -> &str { | |
2c00a5a8 | 715 | &self.0.regex_strings()[0] |
8bb4bdeb XL |
716 | } |
717 | ||
718 | /// Returns an iterator over the capture names. | |
c295e0f8 | 719 | pub fn capture_names(&self) -> CaptureNames<'_> { |
2c00a5a8 | 720 | CaptureNames(self.0.capture_names().iter()) |
8bb4bdeb XL |
721 | } |
722 | ||
723 | /// Returns the number of captures. | |
724 | pub fn captures_len(&self) -> usize { | |
2c00a5a8 | 725 | self.0.capture_names().len() |
8bb4bdeb XL |
726 | } |
727 | ||
b7449926 XL |
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. | |
8bb4bdeb | 738 | #[doc(hidden)] |
b7449926 XL |
739 | pub fn locations(&self) -> CaptureLocations { |
740 | CaptureLocations(self.0.searcher_str().locations()) | |
8bb4bdeb XL |
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. | |
5869c6ff | 750 | #[derive(Clone, Debug)] |
2c00a5a8 | 751 | pub struct CaptureNames<'r>(::std::slice::Iter<'r, Option<String>>); |
8bb4bdeb XL |
752 | |
753 | impl<'r> Iterator for CaptureNames<'r> { | |
754 | type Item = Option<&'r str>; | |
755 | ||
756 | fn next(&mut self) -> Option<Option<&'r str>> { | |
2c00a5a8 XL |
757 | self.0 |
758 | .next() | |
759 | .as_ref() | |
760 | .map(|slot| slot.as_ref().map(|name| name.as_ref())) | |
8bb4bdeb XL |
761 | } |
762 | ||
763 | fn size_hint(&self) -> (usize, Option<usize>) { | |
2c00a5a8 | 764 | self.0.size_hint() |
8bb4bdeb | 765 | } |
5869c6ff XL |
766 | |
767 | fn count(self) -> usize { | |
768 | self.0.count() | |
769 | } | |
8bb4bdeb XL |
770 | } |
771 | ||
5869c6ff XL |
772 | impl<'r> ExactSizeIterator for CaptureNames<'r> {} |
773 | ||
774 | impl<'r> FusedIterator for CaptureNames<'r> {} | |
775 | ||
8bb4bdeb XL |
776 | /// Yields all substrings delimited by a regular expression match. |
777 | /// | |
778 | /// `'r` is the lifetime of the compiled regular expression and `'t` is the | |
779 | /// lifetime of the string being split. | |
5869c6ff | 780 | #[derive(Debug)] |
8bb4bdeb XL |
781 | pub struct Split<'r, 't> { |
782 | finder: Matches<'r, 't>, | |
783 | last: usize, | |
784 | } | |
785 | ||
786 | impl<'r, 't> Iterator for Split<'r, 't> { | |
787 | type Item = &'t str; | |
788 | ||
789 | fn next(&mut self) -> Option<&'t str> { | |
2c00a5a8 | 790 | let text = self.finder.0.text(); |
8bb4bdeb XL |
791 | match self.finder.next() { |
792 | None => { | |
f9f354fc | 793 | if self.last > text.len() { |
8bb4bdeb XL |
794 | None |
795 | } else { | |
796 | let s = &text[self.last..]; | |
f9f354fc | 797 | self.last = text.len() + 1; // Next call will return None |
8bb4bdeb XL |
798 | Some(s) |
799 | } | |
800 | } | |
801 | Some(m) => { | |
802 | let matched = &text[self.last..m.start()]; | |
803 | self.last = m.end(); | |
804 | Some(matched) | |
805 | } | |
806 | } | |
807 | } | |
808 | } | |
809 | ||
5869c6ff XL |
810 | impl<'r, 't> FusedIterator for Split<'r, 't> {} |
811 | ||
8bb4bdeb XL |
812 | /// Yields at most `N` substrings delimited by a regular expression match. |
813 | /// | |
814 | /// The last substring will be whatever remains after splitting. | |
815 | /// | |
816 | /// `'r` is the lifetime of the compiled regular expression and `'t` is the | |
817 | /// lifetime of the string being split. | |
5869c6ff | 818 | #[derive(Debug)] |
8bb4bdeb XL |
819 | pub struct SplitN<'r, 't> { |
820 | splits: Split<'r, 't>, | |
821 | n: usize, | |
822 | } | |
823 | ||
824 | impl<'r, 't> Iterator for SplitN<'r, 't> { | |
825 | type Item = &'t str; | |
826 | ||
827 | fn next(&mut self) -> Option<&'t str> { | |
828 | if self.n == 0 { | |
f9f354fc | 829 | return None; |
8bb4bdeb | 830 | } |
f9f354fc | 831 | |
8bb4bdeb | 832 | self.n -= 1; |
f9f354fc XL |
833 | if self.n > 0 { |
834 | return self.splits.next(); | |
835 | } | |
836 | ||
837 | let text = self.splits.finder.0.text(); | |
838 | if self.splits.last > text.len() { | |
839 | // We've already returned all substrings. | |
840 | None | |
8bb4bdeb | 841 | } else { |
f9f354fc XL |
842 | // self.n == 0, so future calls will return None immediately |
843 | Some(&text[self.splits.last..]) | |
8bb4bdeb XL |
844 | } |
845 | } | |
5869c6ff XL |
846 | |
847 | fn size_hint(&self) -> (usize, Option<usize>) { | |
848 | (0, Some(self.n)) | |
849 | } | |
8bb4bdeb XL |
850 | } |
851 | ||
5869c6ff XL |
852 | impl<'r, 't> FusedIterator for SplitN<'r, 't> {} |
853 | ||
b7449926 XL |
854 | /// CaptureLocations is a low level representation of the raw offsets of each |
855 | /// submatch. | |
856 | /// | |
857 | /// You can think of this as a lower level | |
858 | /// [`Captures`](struct.Captures.html), where this type does not support | |
859 | /// named capturing groups directly and it does not borrow the text that these | |
860 | /// offsets were matched on. | |
861 | /// | |
862 | /// Primarily, this type is useful when using the lower level `Regex` APIs | |
863 | /// such as `read_captures`, which permits amortizing the allocation in which | |
864 | /// capture match locations are stored. | |
865 | /// | |
866 | /// In order to build a value of this type, you'll need to call the | |
867 | /// `capture_locations` method on the `Regex` being used to execute the search. | |
868 | /// The value returned can then be reused in subsequent searches. | |
869 | #[derive(Clone, Debug)] | |
870 | pub struct CaptureLocations(re_trait::Locations); | |
871 | ||
872 | /// A type alias for `CaptureLocations` for backwards compatibility. | |
873 | /// | |
874 | /// Previously, we exported `CaptureLocations` as `Locations` in an | |
875 | /// undocumented API. To prevent breaking that code (e.g., in `regex-capi`), | |
876 | /// we continue re-exporting the same undocumented API. | |
877 | #[doc(hidden)] | |
878 | pub type Locations = CaptureLocations; | |
879 | ||
880 | impl CaptureLocations { | |
881 | /// Returns the start and end positions of the Nth capture group. Returns | |
882 | /// `None` if `i` is not a valid capture group or if the capture group did | |
883 | /// not match anything. The positions returned are *always* byte indices | |
884 | /// with respect to the original string matched. | |
885 | #[inline] | |
886 | pub fn get(&self, i: usize) -> Option<(usize, usize)> { | |
887 | self.0.pos(i) | |
888 | } | |
889 | ||
890 | /// Returns the total number of capturing groups. | |
891 | /// | |
892 | /// This is always at least `1` since every regex has at least `1` | |
893 | /// capturing group that corresponds to the entire match. | |
894 | #[inline] | |
895 | pub fn len(&self) -> usize { | |
896 | self.0.len() | |
897 | } | |
898 | ||
899 | /// An alias for the `get` method for backwards compatibility. | |
900 | /// | |
901 | /// Previously, we exported `get` as `pos` in an undocumented API. To | |
902 | /// prevent breaking that code (e.g., in `regex-capi`), we continue | |
903 | /// re-exporting the same undocumented API. | |
904 | #[doc(hidden)] | |
905 | #[inline] | |
906 | pub fn pos(&self, i: usize) -> Option<(usize, usize)> { | |
907 | self.get(i) | |
908 | } | |
909 | } | |
910 | ||
8bb4bdeb XL |
911 | /// Captures represents a group of captured strings for a single match. |
912 | /// | |
913 | /// The 0th capture always corresponds to the entire match. Each subsequent | |
914 | /// index corresponds to the next capture group in the regex. If a capture | |
915 | /// group is named, then the matched string is *also* available via the `name` | |
916 | /// method. (Note that the 0th capture is always unnamed and so must be | |
041b39d2 | 917 | /// accessed with the `get` method.) |
8bb4bdeb XL |
918 | /// |
919 | /// Positions returned from a capture group are always byte indices. | |
920 | /// | |
921 | /// `'t` is the lifetime of the matched text. | |
922 | pub struct Captures<'t> { | |
923 | text: &'t str, | |
b7449926 | 924 | locs: re_trait::Locations, |
2c00a5a8 | 925 | named_groups: Arc<HashMap<String, usize>>, |
8bb4bdeb XL |
926 | } |
927 | ||
928 | impl<'t> Captures<'t> { | |
929 | /// Returns the match associated with the capture group at index `i`. If | |
930 | /// `i` does not correspond to a capture group, or if the capture group | |
931 | /// did not participate in the match, then `None` is returned. | |
041b39d2 XL |
932 | /// |
933 | /// # Examples | |
934 | /// | |
935 | /// Get the text of the match with a default of an empty string if this | |
936 | /// group didn't participate in the match: | |
937 | /// | |
938 | /// ```rust | |
939 | /// # use regex::Regex; | |
940 | /// let re = Regex::new(r"[a-z]+(?:([0-9]+)|([A-Z]+))").unwrap(); | |
941 | /// let caps = re.captures("abc123").unwrap(); | |
942 | /// | |
943 | /// let text1 = caps.get(1).map_or("", |m| m.as_str()); | |
944 | /// let text2 = caps.get(2).map_or("", |m| m.as_str()); | |
945 | /// assert_eq!(text1, "123"); | |
946 | /// assert_eq!(text2, ""); | |
947 | /// ``` | |
8bb4bdeb XL |
948 | pub fn get(&self, i: usize) -> Option<Match<'t>> { |
949 | self.locs.pos(i).map(|(s, e)| Match::new(self.text, s, e)) | |
950 | } | |
951 | ||
952 | /// Returns the match for the capture group named `name`. If `name` isn't a | |
953 | /// valid capture group or didn't match anything, then `None` is returned. | |
954 | pub fn name(&self, name: &str) -> Option<Match<'t>> { | |
2c00a5a8 | 955 | self.named_groups.get(name).and_then(|&i| self.get(i)) |
8bb4bdeb XL |
956 | } |
957 | ||
958 | /// An iterator that yields all capturing matches in the order in which | |
959 | /// they appear in the regex. If a particular capture group didn't | |
960 | /// participate in the match, then `None` is yielded for that capture. | |
961 | /// | |
962 | /// The first match always corresponds to the overall match of the regex. | |
963 | pub fn iter<'c>(&'c self) -> SubCaptureMatches<'c, 't> { | |
f9f354fc | 964 | SubCaptureMatches { caps: self, it: self.locs.iter() } |
8bb4bdeb XL |
965 | } |
966 | ||
2c00a5a8 XL |
967 | /// Expands all instances of `$name` in `replacement` to the corresponding |
968 | /// capture group `name`, and writes them to the `dst` buffer given. | |
8bb4bdeb | 969 | /// |
5869c6ff XL |
970 | /// `name` may be an integer corresponding to the index of the capture |
971 | /// group (counted by order of opening parenthesis where `0` is the | |
8bb4bdeb XL |
972 | /// entire match) or it can be a name (consisting of letters, digits or |
973 | /// underscores) corresponding to a named capture group. | |
974 | /// | |
975 | /// If `name` isn't a valid capture group (whether the name doesn't exist | |
976 | /// or isn't a valid index), then it is replaced with the empty string. | |
977 | /// | |
5869c6ff XL |
978 | /// The longest possible name consisting of the characters `[_0-9A-Za-z]` |
979 | /// is used. e.g., `$1a` looks up the capture group named `1a` and not the | |
980 | /// capture group at index `1`. To exert more precise control over the | |
981 | /// name, or to refer to a capture group name that uses characters outside | |
982 | /// of `[_0-9A-Za-z]`, use braces, e.g., `${1}a` or `${foo[bar].baz}`. When | |
983 | /// using braces, any sequence of characters is permitted. If the sequence | |
984 | /// does not refer to a capture group name in the corresponding regex, then | |
985 | /// it is replaced with an empty string. | |
8bb4bdeb XL |
986 | /// |
987 | /// To write a literal `$` use `$$`. | |
988 | pub fn expand(&self, replacement: &str, dst: &mut String) { | |
989 | expand_str(self, replacement, dst) | |
990 | } | |
991 | ||
992 | /// Returns the number of captured groups. | |
993 | /// | |
994 | /// This is always at least `1`, since every regex has at least one capture | |
995 | /// group that corresponds to the full match. | |
996 | #[inline] | |
997 | pub fn len(&self) -> usize { | |
998 | self.locs.len() | |
999 | } | |
1000 | } | |
1001 | ||
1002 | impl<'t> fmt::Debug for Captures<'t> { | |
c295e0f8 | 1003 | fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
8bb4bdeb XL |
1004 | f.debug_tuple("Captures").field(&CapturesDebug(self)).finish() |
1005 | } | |
1006 | } | |
1007 | ||
c295e0f8 | 1008 | struct CapturesDebug<'c, 't>(&'c Captures<'t>); |
8bb4bdeb XL |
1009 | |
1010 | impl<'c, 't> fmt::Debug for CapturesDebug<'c, 't> { | |
c295e0f8 | 1011 | fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
8bb4bdeb XL |
1012 | // We'd like to show something nice here, even if it means an |
1013 | // allocation to build a reverse index. | |
2c00a5a8 | 1014 | let slot_to_name: HashMap<&usize, &String> = |
8bb4bdeb XL |
1015 | self.0.named_groups.iter().map(|(a, b)| (b, a)).collect(); |
1016 | let mut map = f.debug_map(); | |
1017 | for (slot, m) in self.0.locs.iter().enumerate() { | |
1018 | let m = m.map(|(s, e)| &self.0.text[s..e]); | |
ff7c6d11 | 1019 | if let Some(name) = slot_to_name.get(&slot) { |
8bb4bdeb XL |
1020 | map.entry(&name, &m); |
1021 | } else { | |
1022 | map.entry(&slot, &m); | |
1023 | } | |
1024 | } | |
1025 | map.finish() | |
1026 | } | |
1027 | } | |
1028 | ||
1029 | /// Get a group by index. | |
1030 | /// | |
1031 | /// `'t` is the lifetime of the matched text. | |
1032 | /// | |
1033 | /// The text can't outlive the `Captures` object if this method is | |
1034 | /// used, because of how `Index` is defined (normally `a[i]` is part | |
041b39d2 | 1035 | /// of `a` and can't outlive it); to do that, use `get()` instead. |
8bb4bdeb XL |
1036 | /// |
1037 | /// # Panics | |
1038 | /// | |
1039 | /// If there is no group at the given index. | |
1040 | impl<'t> Index<usize> for Captures<'t> { | |
1041 | type Output = str; | |
1042 | ||
1043 | fn index(&self, i: usize) -> &str { | |
f9f354fc XL |
1044 | self.get(i) |
1045 | .map(|m| m.as_str()) | |
8bb4bdeb XL |
1046 | .unwrap_or_else(|| panic!("no group at index '{}'", i)) |
1047 | } | |
1048 | } | |
1049 | ||
1050 | /// Get a group by name. | |
1051 | /// | |
1052 | /// `'t` is the lifetime of the matched text and `'i` is the lifetime | |
1053 | /// of the group name (the index). | |
1054 | /// | |
1055 | /// The text can't outlive the `Captures` object if this method is | |
1056 | /// used, because of how `Index` is defined (normally `a[i]` is part | |
1057 | /// of `a` and can't outlive it); to do that, use `name` instead. | |
1058 | /// | |
1059 | /// # Panics | |
1060 | /// | |
1061 | /// If there is no group named by the given value. | |
1062 | impl<'t, 'i> Index<&'i str> for Captures<'t> { | |
1063 | type Output = str; | |
1064 | ||
1065 | fn index<'a>(&'a self, name: &'i str) -> &'a str { | |
f9f354fc XL |
1066 | self.name(name) |
1067 | .map(|m| m.as_str()) | |
8bb4bdeb XL |
1068 | .unwrap_or_else(|| panic!("no group named '{}'", name)) |
1069 | } | |
1070 | } | |
1071 | ||
1072 | /// An iterator that yields all capturing matches in the order in which they | |
1073 | /// appear in the regex. | |
1074 | /// | |
1075 | /// If a particular capture group didn't participate in the match, then `None` | |
1076 | /// is yielded for that capture. The first match always corresponds to the | |
1077 | /// overall match of the regex. | |
1078 | /// | |
1079 | /// The lifetime `'c` corresponds to the lifetime of the `Captures` value, and | |
1080 | /// the lifetime `'t` corresponds to the originally matched text. | |
5869c6ff | 1081 | #[derive(Clone, Debug)] |
c295e0f8 | 1082 | pub struct SubCaptureMatches<'c, 't> { |
8bb4bdeb XL |
1083 | caps: &'c Captures<'t>, |
1084 | it: SubCapturesPosIter<'c>, | |
1085 | } | |
1086 | ||
1087 | impl<'c, 't> Iterator for SubCaptureMatches<'c, 't> { | |
1088 | type Item = Option<Match<'t>>; | |
1089 | ||
1090 | fn next(&mut self) -> Option<Option<Match<'t>>> { | |
f9f354fc XL |
1091 | self.it |
1092 | .next() | |
8bb4bdeb XL |
1093 | .map(|cap| cap.map(|(s, e)| Match::new(self.caps.text, s, e))) |
1094 | } | |
1095 | } | |
1096 | ||
5869c6ff XL |
1097 | impl<'c, 't> FusedIterator for SubCaptureMatches<'c, 't> {} |
1098 | ||
8bb4bdeb XL |
1099 | /// An iterator that yields all non-overlapping capture groups matching a |
1100 | /// particular regular expression. | |
1101 | /// | |
1102 | /// The iterator stops when no more matches can be found. | |
1103 | /// | |
1104 | /// `'r` is the lifetime of the compiled regular expression and `'t` is the | |
1105 | /// lifetime of the matched string. | |
5869c6ff | 1106 | #[derive(Debug)] |
f9f354fc XL |
1107 | pub struct CaptureMatches<'r, 't>( |
1108 | re_trait::CaptureMatches<'t, ExecNoSyncStr<'r>>, | |
1109 | ); | |
8bb4bdeb XL |
1110 | |
1111 | impl<'r, 't> Iterator for CaptureMatches<'r, 't> { | |
1112 | type Item = Captures<'t>; | |
1113 | ||
1114 | fn next(&mut self) -> Option<Captures<'t>> { | |
2c00a5a8 XL |
1115 | self.0.next().map(|locs| Captures { |
1116 | text: self.0.text(), | |
1117 | locs: locs, | |
1118 | named_groups: self.0.regex().capture_name_idx().clone(), | |
1119 | }) | |
8bb4bdeb XL |
1120 | } |
1121 | } | |
1122 | ||
5869c6ff XL |
1123 | impl<'r, 't> FusedIterator for CaptureMatches<'r, 't> {} |
1124 | ||
8bb4bdeb XL |
1125 | /// An iterator over all non-overlapping matches for a particular string. |
1126 | /// | |
1127 | /// The iterator yields a `Match` value. The iterator stops when no more | |
1128 | /// matches can be found. | |
1129 | /// | |
1130 | /// `'r` is the lifetime of the compiled regular expression and `'t` is the | |
1131 | /// lifetime of the matched string. | |
5869c6ff | 1132 | #[derive(Debug)] |
2c00a5a8 | 1133 | pub struct Matches<'r, 't>(re_trait::Matches<'t, ExecNoSyncStr<'r>>); |
8bb4bdeb XL |
1134 | |
1135 | impl<'r, 't> Iterator for Matches<'r, 't> { | |
1136 | type Item = Match<'t>; | |
1137 | ||
1138 | fn next(&mut self) -> Option<Match<'t>> { | |
2c00a5a8 XL |
1139 | let text = self.0.text(); |
1140 | self.0.next().map(|(s, e)| Match::new(text, s, e)) | |
8bb4bdeb XL |
1141 | } |
1142 | } | |
1143 | ||
5869c6ff XL |
1144 | impl<'r, 't> FusedIterator for Matches<'r, 't> {} |
1145 | ||
8bb4bdeb XL |
1146 | /// Replacer describes types that can be used to replace matches in a string. |
1147 | /// | |
1148 | /// In general, users of this crate shouldn't need to implement this trait, | |
136023e0 XL |
1149 | /// since implementations are already provided for `&str` along with other |
1150 | /// variants of string types and `FnMut(&Captures) -> String` (or any | |
1151 | /// `FnMut(&Captures) -> T` where `T: AsRef<str>`), which covers most use cases. | |
8bb4bdeb XL |
1152 | pub trait Replacer { |
1153 | /// Appends text to `dst` to replace the current match. | |
1154 | /// | |
1155 | /// The current match is represented by `caps`, which is guaranteed to | |
1156 | /// have a match at capture group `0`. | |
1157 | /// | |
1158 | /// For example, a no-op replacement would be | |
5869c6ff | 1159 | /// `dst.push_str(caps.get(0).unwrap().as_str())`. |
c295e0f8 | 1160 | fn replace_append(&mut self, caps: &Captures<'_>, dst: &mut String); |
8bb4bdeb XL |
1161 | |
1162 | /// Return a fixed unchanging replacement string. | |
1163 | /// | |
1164 | /// When doing replacements, if access to `Captures` is not needed (e.g., | |
1165 | /// the replacement byte string does not need `$` expansion), then it can | |
1166 | /// be beneficial to avoid finding sub-captures. | |
1167 | /// | |
1168 | /// In general, this is called once for every call to `replacen`. | |
1169 | fn no_expansion<'r>(&'r mut self) -> Option<Cow<'r, str>> { | |
1170 | None | |
1171 | } | |
0531ce1d XL |
1172 | |
1173 | /// Return a `Replacer` that borrows and wraps this `Replacer`. | |
1174 | /// | |
1175 | /// This is useful when you want to take a generic `Replacer` (which might | |
1176 | /// not be cloneable) and use it without consuming it, so it can be used | |
1177 | /// more than once. | |
1178 | /// | |
1179 | /// # Example | |
1180 | /// | |
1181 | /// ``` | |
1182 | /// use regex::{Regex, Replacer}; | |
1183 | /// | |
1184 | /// fn replace_all_twice<R: Replacer>( | |
1185 | /// re: Regex, | |
1186 | /// src: &str, | |
1187 | /// mut rep: R, | |
1188 | /// ) -> String { | |
1189 | /// let dst = re.replace_all(src, rep.by_ref()); | |
1190 | /// let dst = re.replace_all(&dst, rep.by_ref()); | |
1191 | /// dst.into_owned() | |
1192 | /// } | |
1193 | /// ``` | |
1194 | fn by_ref<'r>(&'r mut self) -> ReplacerRef<'r, Self> { | |
1195 | ReplacerRef(self) | |
1196 | } | |
1197 | } | |
1198 | ||
1199 | /// By-reference adaptor for a `Replacer` | |
1200 | /// | |
1201 | /// Returned by [`Replacer::by_ref`](trait.Replacer.html#method.by_ref). | |
1202 | #[derive(Debug)] | |
c295e0f8 | 1203 | pub struct ReplacerRef<'a, R: ?Sized>(&'a mut R); |
0531ce1d XL |
1204 | |
1205 | impl<'a, R: Replacer + ?Sized + 'a> Replacer for ReplacerRef<'a, R> { | |
c295e0f8 | 1206 | fn replace_append(&mut self, caps: &Captures<'_>, dst: &mut String) { |
0531ce1d XL |
1207 | self.0.replace_append(caps, dst) |
1208 | } | |
c295e0f8 | 1209 | fn no_expansion(&mut self) -> Option<Cow<'_, str>> { |
0531ce1d XL |
1210 | self.0.no_expansion() |
1211 | } | |
8bb4bdeb XL |
1212 | } |
1213 | ||
1214 | impl<'a> Replacer for &'a str { | |
c295e0f8 | 1215 | fn replace_append(&mut self, caps: &Captures<'_>, dst: &mut String) { |
8bb4bdeb XL |
1216 | caps.expand(*self, dst); |
1217 | } | |
1218 | ||
c295e0f8 | 1219 | fn no_expansion(&mut self) -> Option<Cow<'_, str>> { |
136023e0 XL |
1220 | no_expansion(self) |
1221 | } | |
1222 | } | |
1223 | ||
1224 | impl<'a> Replacer for &'a String { | |
c295e0f8 | 1225 | fn replace_append(&mut self, caps: &Captures<'_>, dst: &mut String) { |
136023e0 XL |
1226 | self.as_str().replace_append(caps, dst) |
1227 | } | |
1228 | ||
c295e0f8 | 1229 | fn no_expansion(&mut self) -> Option<Cow<'_, str>> { |
136023e0 XL |
1230 | no_expansion(self) |
1231 | } | |
1232 | } | |
1233 | ||
1234 | impl Replacer for String { | |
c295e0f8 | 1235 | fn replace_append(&mut self, caps: &Captures<'_>, dst: &mut String) { |
136023e0 XL |
1236 | self.as_str().replace_append(caps, dst) |
1237 | } | |
1238 | ||
c295e0f8 | 1239 | fn no_expansion(&mut self) -> Option<Cow<'_, str>> { |
136023e0 XL |
1240 | no_expansion(self) |
1241 | } | |
1242 | } | |
1243 | ||
1244 | impl<'a> Replacer for Cow<'a, str> { | |
c295e0f8 | 1245 | fn replace_append(&mut self, caps: &Captures<'_>, dst: &mut String) { |
136023e0 XL |
1246 | self.as_ref().replace_append(caps, dst) |
1247 | } | |
1248 | ||
c295e0f8 | 1249 | fn no_expansion(&mut self) -> Option<Cow<'_, str>> { |
136023e0 XL |
1250 | no_expansion(self) |
1251 | } | |
1252 | } | |
1253 | ||
1254 | impl<'a> Replacer for &'a Cow<'a, str> { | |
c295e0f8 | 1255 | fn replace_append(&mut self, caps: &Captures<'_>, dst: &mut String) { |
136023e0 XL |
1256 | self.as_ref().replace_append(caps, dst) |
1257 | } | |
1258 | ||
c295e0f8 | 1259 | fn no_expansion(&mut self) -> Option<Cow<'_, str>> { |
136023e0 XL |
1260 | no_expansion(self) |
1261 | } | |
1262 | } | |
1263 | ||
c295e0f8 | 1264 | fn no_expansion<T: AsRef<str>>(t: &T) -> Option<Cow<'_, str>> { |
136023e0 XL |
1265 | let s = t.as_ref(); |
1266 | match find_byte(b'$', s.as_bytes()) { | |
1267 | Some(_) => None, | |
1268 | None => Some(Cow::Borrowed(s)), | |
8bb4bdeb XL |
1269 | } |
1270 | } | |
1271 | ||
f9f354fc XL |
1272 | impl<F, T> Replacer for F |
1273 | where | |
c295e0f8 | 1274 | F: FnMut(&Captures<'_>) -> T, |
f9f354fc XL |
1275 | T: AsRef<str>, |
1276 | { | |
c295e0f8 | 1277 | fn replace_append(&mut self, caps: &Captures<'_>, dst: &mut String) { |
0731742a | 1278 | dst.push_str((*self)(caps).as_ref()); |
8bb4bdeb XL |
1279 | } |
1280 | } | |
1281 | ||
ff7c6d11 | 1282 | /// `NoExpand` indicates literal string replacement. |
8bb4bdeb XL |
1283 | /// |
1284 | /// It can be used with `replace` and `replace_all` to do a literal string | |
1285 | /// replacement without expanding `$name` to their corresponding capture | |
1286 | /// groups. This can be both convenient (to avoid escaping `$`, for example) | |
1287 | /// and performant (since capture groups don't need to be found). | |
1288 | /// | |
1289 | /// `'t` is the lifetime of the literal text. | |
5869c6ff | 1290 | #[derive(Clone, Debug)] |
8bb4bdeb XL |
1291 | pub struct NoExpand<'t>(pub &'t str); |
1292 | ||
1293 | impl<'t> Replacer for NoExpand<'t> { | |
c295e0f8 | 1294 | fn replace_append(&mut self, _: &Captures<'_>, dst: &mut String) { |
8bb4bdeb XL |
1295 | dst.push_str(self.0); |
1296 | } | |
1297 | ||
c295e0f8 | 1298 | fn no_expansion(&mut self) -> Option<Cow<'_, str>> { |
8bb4bdeb XL |
1299 | Some(Cow::Borrowed(self.0)) |
1300 | } | |
1301 | } |