1use alloc::{borrow::Cow, string::String, sync::Arc};
2
3use regex_automata::{meta, util::captures, Input, PatternID};
4
5use crate::{error::Error, RegexBuilder};
6
7/// A compiled regular expression for searching Unicode haystacks.
8///
9/// A `Regex` can be used to search haystacks, split haystacks into substrings
10/// or replace substrings in a haystack with a different substring. All
11/// searching is done with an implicit `(?s:.)*?` at the beginning and end of
12/// an pattern. To force an expression to match the whole string (or a prefix
13/// or a suffix), you must use an anchor like `^` or `$` (or `\A` and `\z`).
14///
15/// While this crate will handle Unicode strings (whether in the regular
16/// expression or in the haystack), all positions returned are **byte
17/// offsets**. Every byte offset is guaranteed to be at a Unicode code point
18/// boundary. That is, all offsets returned by the `Regex` API are guaranteed
19/// to be ranges that can slice a `&str` without panicking. If you want to
20/// relax this requirement, then you must search `&[u8]` haystacks with a
21/// [`bytes::Regex`](crate::bytes::Regex).
22///
23/// The only methods that allocate new strings are the string replacement
24/// methods. All other methods (searching and splitting) return borrowed
25/// references into the haystack given.
26///
27/// # Example
28///
29/// Find the offsets of a US phone number:
30///
31/// ```
32/// use regex::Regex;
33///
34/// let re = Regex::new("[0-9]{3}-[0-9]{3}-[0-9]{4}").unwrap();
35/// let m = re.find("phone: 111-222-3333").unwrap();
36/// assert_eq!(7..19, m.range());
37/// ```
38///
39/// # Example: extracting capture groups
40///
41/// A common way to use regexes is with capture groups. That is, instead of
42/// just looking for matches of an entire regex, parentheses are used to create
43/// groups that represent part of the match.
44///
45/// For example, consider a haystack with multiple lines, and each line has
46/// three whitespace delimited fields where the second field is expected to be
47/// a number and the third field a boolean. To make this convenient, we use
48/// the [`Captures::extract`] API to put the strings that match each group
49/// into a fixed size array:
50///
51/// ```
52/// use regex::Regex;
53///
54/// let hay = "
55/// rabbit 54 true
56/// groundhog 2 true
57/// does not match
58/// fox 109 false
59/// ";
60/// let re = Regex::new(r"(?m)^\s*(\S+)\s+([0-9]+)\s+(true|false)\s*$").unwrap();
61/// let mut fields: Vec<(&str, i64, bool)> = vec![];
62/// for (_, [f1, f2, f3]) in re.captures_iter(hay).map(|caps| caps.extract()) {
63/// fields.push((f1, f2.parse()?, f3.parse()?));
64/// }
65/// assert_eq!(fields, vec![
66/// ("rabbit", 54, true),
67/// ("groundhog", 2, true),
68/// ("fox", 109, false),
69/// ]);
70///
71/// # Ok::<(), Box<dyn std::error::Error>>(())
72/// ```
73///
74/// # Example: searching with the `Pattern` trait
75///
76/// **Note**: This section requires that this crate is compiled with the
77/// `pattern` Cargo feature enabled, which **requires nightly Rust**.
78///
79/// Since `Regex` implements `Pattern` from the standard library, one can
80/// use regexes with methods defined on `&str`. For example, `is_match`,
81/// `find`, `find_iter` and `split` can, in some cases, be replaced with
82/// `str::contains`, `str::find`, `str::match_indices` and `str::split`.
83///
84/// Here are some examples:
85///
86/// ```ignore
87/// use regex::Regex;
88///
89/// let re = Regex::new(r"\d+").unwrap();
90/// let hay = "a111b222c";
91///
92/// assert!(hay.contains(&re));
93/// assert_eq!(hay.find(&re), Some(1));
94/// assert_eq!(hay.match_indices(&re).collect::<Vec<_>>(), vec![
95/// (1, "111"),
96/// (5, "222"),
97/// ]);
98/// assert_eq!(hay.split(&re).collect::<Vec<_>>(), vec!["a", "b", "c"]);
99/// ```
100#[derive(Clone)]
101pub struct Regex {
102 pub(crate) meta: meta::Regex,
103 pub(crate) pattern: Arc<str>,
104}
105
106impl core::fmt::Display for Regex {
107 /// Shows the original regular expression.
108 fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
109 write!(f, "{}", self.as_str())
110 }
111}
112
113impl core::fmt::Debug for Regex {
114 /// Shows the original regular expression.
115 fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
116 f.debug_tuple("Regex").field(&self.as_str()).finish()
117 }
118}
119
120impl core::str::FromStr for Regex {
121 type Err = Error;
122
123 /// Attempts to parse a string into a regular expression
124 fn from_str(s: &str) -> Result<Regex, Error> {
125 Regex::new(s)
126 }
127}
128
129impl TryFrom<&str> for Regex {
130 type Error = Error;
131
132 /// Attempts to parse a string into a regular expression
133 fn try_from(s: &str) -> Result<Regex, Error> {
134 Regex::new(s)
135 }
136}
137
138impl TryFrom<String> for Regex {
139 type Error = Error;
140
141 /// Attempts to parse a string into a regular expression
142 fn try_from(s: String) -> Result<Regex, Error> {
143 Regex::new(&s)
144 }
145}
146
147/// Core regular expression methods.
148impl Regex {
149 /// Compiles a regular expression. Once compiled, it can be used repeatedly
150 /// to search, split or replace substrings in a haystack.
151 ///
152 /// Note that regex compilation tends to be a somewhat expensive process,
153 /// and unlike higher level environments, compilation is not automatically
154 /// cached for you. One should endeavor to compile a regex once and then
155 /// reuse it. For example, it's a bad idea to compile the same regex
156 /// repeatedly in a loop.
157 ///
158 /// # Errors
159 ///
160 /// If an invalid pattern is given, then an error is returned.
161 /// An error is also returned if the pattern is valid, but would
162 /// produce a regex that is bigger than the configured size limit via
163 /// [`RegexBuilder::size_limit`]. (A reasonable size limit is enabled by
164 /// default.)
165 ///
166 /// # Example
167 ///
168 /// ```
169 /// use regex::Regex;
170 ///
171 /// // An Invalid pattern because of an unclosed parenthesis
172 /// assert!(Regex::new(r"foo(bar").is_err());
173 /// // An invalid pattern because the regex would be too big
174 /// // because Unicode tends to inflate things.
175 /// assert!(Regex::new(r"\w{1000}").is_err());
176 /// // Disabling Unicode can make the regex much smaller,
177 /// // potentially by up to or more than an order of magnitude.
178 /// assert!(Regex::new(r"(?-u:\w){1000}").is_ok());
179 /// ```
180 pub fn new(re: &str) -> Result<Regex, Error> {
181 RegexBuilder::new(re).build()
182 }
183
184 /// Returns true if and only if there is a match for the regex anywhere
185 /// in the haystack given.
186 ///
187 /// It is recommended to use this method if all you need to do is test
188 /// whether a match exists, since the underlying matching engine may be
189 /// able to do less work.
190 ///
191 /// # Example
192 ///
193 /// Test if some haystack contains at least one word with exactly 13
194 /// Unicode word characters:
195 ///
196 /// ```
197 /// use regex::Regex;
198 ///
199 /// let re = Regex::new(r"\b\w{13}\b").unwrap();
200 /// let hay = "I categorically deny having triskaidekaphobia.";
201 /// assert!(re.is_match(hay));
202 /// ```
203 #[inline]
204 pub fn is_match(&self, haystack: &str) -> bool {
205 self.is_match_at(haystack, 0)
206 }
207
208 /// This routine searches for the first match of this regex in the
209 /// haystack given, and if found, returns a [`Match`]. The `Match`
210 /// provides access to both the byte offsets of the match and the actual
211 /// substring that matched.
212 ///
213 /// Note that this should only be used if you want to find the entire
214 /// match. If instead you just want to test the existence of a match,
215 /// it's potentially faster to use `Regex::is_match(hay)` instead of
216 /// `Regex::find(hay).is_some()`.
217 ///
218 /// # Example
219 ///
220 /// Find the first word with exactly 13 Unicode word characters:
221 ///
222 /// ```
223 /// use regex::Regex;
224 ///
225 /// let re = Regex::new(r"\b\w{13}\b").unwrap();
226 /// let hay = "I categorically deny having triskaidekaphobia.";
227 /// let mat = re.find(hay).unwrap();
228 /// assert_eq!(2..15, mat.range());
229 /// assert_eq!("categorically", mat.as_str());
230 /// ```
231 #[inline]
232 pub fn find<'h>(&self, haystack: &'h str) -> Option<Match<'h>> {
233 self.find_at(haystack, 0)
234 }
235
236 /// Returns an iterator that yields successive non-overlapping matches in
237 /// the given haystack. The iterator yields values of type [`Match`].
238 ///
239 /// # Time complexity
240 ///
241 /// Note that since `find_iter` runs potentially many searches on the
242 /// haystack and since each search has worst case `O(m * n)` time
243 /// complexity, the overall worst case time complexity for iteration is
244 /// `O(m * n^2)`.
245 ///
246 /// # Example
247 ///
248 /// Find every word with exactly 13 Unicode word characters:
249 ///
250 /// ```
251 /// use regex::Regex;
252 ///
253 /// let re = Regex::new(r"\b\w{13}\b").unwrap();
254 /// let hay = "Retroactively relinquishing remunerations is reprehensible.";
255 /// let matches: Vec<_> = re.find_iter(hay).map(|m| m.as_str()).collect();
256 /// assert_eq!(matches, vec![
257 /// "Retroactively",
258 /// "relinquishing",
259 /// "remunerations",
260 /// "reprehensible",
261 /// ]);
262 /// ```
263 #[inline]
264 pub fn find_iter<'r, 'h>(&'r self, haystack: &'h str) -> Matches<'r, 'h> {
265 Matches { haystack, it: self.meta.find_iter(haystack) }
266 }
267
268 /// This routine searches for the first match of this regex in the haystack
269 /// given, and if found, returns not only the overall match but also the
270 /// matches of each capture group in the regex. If no match is found, then
271 /// `None` is returned.
272 ///
273 /// Capture group `0` always corresponds to an implicit unnamed group that
274 /// includes the entire match. If a match is found, this group is always
275 /// present. Subsequent groups may be named and are numbered, starting
276 /// at 1, by the order in which the opening parenthesis appears in the
277 /// pattern. For example, in the pattern `(?<a>.(?<b>.))(?<c>.)`, `a`,
278 /// `b` and `c` correspond to capture group indices `1`, `2` and `3`,
279 /// respectively.
280 ///
281 /// You should only use `captures` if you need access to the capture group
282 /// matches. Otherwise, [`Regex::find`] is generally faster for discovering
283 /// just the overall match.
284 ///
285 /// # Example
286 ///
287 /// Say you have some haystack with movie names and their release years,
288 /// like "'Citizen Kane' (1941)". It'd be nice if we could search for
289 /// substrings looking like that, while also extracting the movie name and
290 /// its release year separately. The example below shows how to do that.
291 ///
292 /// ```
293 /// use regex::Regex;
294 ///
295 /// let re = Regex::new(r"'([^']+)'\s+\((\d{4})\)").unwrap();
296 /// let hay = "Not my favorite movie: 'Citizen Kane' (1941).";
297 /// let caps = re.captures(hay).unwrap();
298 /// assert_eq!(caps.get(0).unwrap().as_str(), "'Citizen Kane' (1941)");
299 /// assert_eq!(caps.get(1).unwrap().as_str(), "Citizen Kane");
300 /// assert_eq!(caps.get(2).unwrap().as_str(), "1941");
301 /// // You can also access the groups by index using the Index notation.
302 /// // Note that this will panic on an invalid index. In this case, these
303 /// // accesses are always correct because the overall regex will only
304 /// // match when these capture groups match.
305 /// assert_eq!(&caps[0], "'Citizen Kane' (1941)");
306 /// assert_eq!(&caps[1], "Citizen Kane");
307 /// assert_eq!(&caps[2], "1941");
308 /// ```
309 ///
310 /// Note that the full match is at capture group `0`. Each subsequent
311 /// capture group is indexed by the order of its opening `(`.
312 ///
313 /// We can make this example a bit clearer by using *named* capture groups:
314 ///
315 /// ```
316 /// use regex::Regex;
317 ///
318 /// let re = Regex::new(r"'(?<title>[^']+)'\s+\((?<year>\d{4})\)").unwrap();
319 /// let hay = "Not my favorite movie: 'Citizen Kane' (1941).";
320 /// let caps = re.captures(hay).unwrap();
321 /// assert_eq!(caps.get(0).unwrap().as_str(), "'Citizen Kane' (1941)");
322 /// assert_eq!(caps.name("title").unwrap().as_str(), "Citizen Kane");
323 /// assert_eq!(caps.name("year").unwrap().as_str(), "1941");
324 /// // You can also access the groups by name using the Index notation.
325 /// // Note that this will panic on an invalid group name. In this case,
326 /// // these accesses are always correct because the overall regex will
327 /// // only match when these capture groups match.
328 /// assert_eq!(&caps[0], "'Citizen Kane' (1941)");
329 /// assert_eq!(&caps["title"], "Citizen Kane");
330 /// assert_eq!(&caps["year"], "1941");
331 /// ```
332 ///
333 /// Here we name the capture groups, which we can access with the `name`
334 /// method or the `Index` notation with a `&str`. Note that the named
335 /// capture groups are still accessible with `get` or the `Index` notation
336 /// with a `usize`.
337 ///
338 /// The `0`th capture group is always unnamed, so it must always be
339 /// accessed with `get(0)` or `[0]`.
340 ///
341 /// Finally, one other way to to get the matched substrings is with the
342 /// [`Captures::extract`] API:
343 ///
344 /// ```
345 /// use regex::Regex;
346 ///
347 /// let re = Regex::new(r"'([^']+)'\s+\((\d{4})\)").unwrap();
348 /// let hay = "Not my favorite movie: 'Citizen Kane' (1941).";
349 /// let (full, [title, year]) = re.captures(hay).unwrap().extract();
350 /// assert_eq!(full, "'Citizen Kane' (1941)");
351 /// assert_eq!(title, "Citizen Kane");
352 /// assert_eq!(year, "1941");
353 /// ```
354 #[inline]
355 pub fn captures<'h>(&self, haystack: &'h str) -> Option<Captures<'h>> {
356 self.captures_at(haystack, 0)
357 }
358
359 /// Returns an iterator that yields successive non-overlapping matches in
360 /// the given haystack. The iterator yields values of type [`Captures`].
361 ///
362 /// This is the same as [`Regex::find_iter`], but instead of only providing
363 /// access to the overall match, each value yield includes access to the
364 /// matches of all capture groups in the regex. Reporting this extra match
365 /// data is potentially costly, so callers should only use `captures_iter`
366 /// over `find_iter` when they actually need access to the capture group
367 /// matches.
368 ///
369 /// # Time complexity
370 ///
371 /// Note that since `captures_iter` runs potentially many searches on the
372 /// haystack and since each search has worst case `O(m * n)` time
373 /// complexity, the overall worst case time complexity for iteration is
374 /// `O(m * n^2)`.
375 ///
376 /// # Example
377 ///
378 /// We can use this to find all movie titles and their release years in
379 /// some haystack, where the movie is formatted like "'Title' (xxxx)":
380 ///
381 /// ```
382 /// use regex::Regex;
383 ///
384 /// let re = Regex::new(r"'([^']+)'\s+\(([0-9]{4})\)").unwrap();
385 /// let hay = "'Citizen Kane' (1941), 'The Wizard of Oz' (1939), 'M' (1931).";
386 /// let mut movies = vec![];
387 /// for (_, [title, year]) in re.captures_iter(hay).map(|c| c.extract()) {
388 /// movies.push((title, year.parse::<i64>()?));
389 /// }
390 /// assert_eq!(movies, vec![
391 /// ("Citizen Kane", 1941),
392 /// ("The Wizard of Oz", 1939),
393 /// ("M", 1931),
394 /// ]);
395 /// # Ok::<(), Box<dyn std::error::Error>>(())
396 /// ```
397 ///
398 /// Or with named groups:
399 ///
400 /// ```
401 /// use regex::Regex;
402 ///
403 /// let re = Regex::new(r"'(?<title>[^']+)'\s+\((?<year>[0-9]{4})\)").unwrap();
404 /// let hay = "'Citizen Kane' (1941), 'The Wizard of Oz' (1939), 'M' (1931).";
405 /// let mut it = re.captures_iter(hay);
406 ///
407 /// let caps = it.next().unwrap();
408 /// assert_eq!(&caps["title"], "Citizen Kane");
409 /// assert_eq!(&caps["year"], "1941");
410 ///
411 /// let caps = it.next().unwrap();
412 /// assert_eq!(&caps["title"], "The Wizard of Oz");
413 /// assert_eq!(&caps["year"], "1939");
414 ///
415 /// let caps = it.next().unwrap();
416 /// assert_eq!(&caps["title"], "M");
417 /// assert_eq!(&caps["year"], "1931");
418 /// ```
419 #[inline]
420 pub fn captures_iter<'r, 'h>(
421 &'r self,
422 haystack: &'h str,
423 ) -> CaptureMatches<'r, 'h> {
424 CaptureMatches { haystack, it: self.meta.captures_iter(haystack) }
425 }
426
427 /// Returns an iterator of substrings of the haystack given, delimited by a
428 /// match of the regex. Namely, each element of the iterator corresponds to
429 /// a part of the haystack that *isn't* matched by the regular expression.
430 ///
431 /// # Time complexity
432 ///
433 /// Since iterators over all matches requires running potentially many
434 /// searches on the haystack, and since each search has worst case
435 /// `O(m * n)` time complexity, the overall worst case time complexity for
436 /// this routine is `O(m * n^2)`.
437 ///
438 /// # Example
439 ///
440 /// To split a string delimited by arbitrary amounts of spaces or tabs:
441 ///
442 /// ```
443 /// use regex::Regex;
444 ///
445 /// let re = Regex::new(r"[ \t]+").unwrap();
446 /// let hay = "a b \t c\td e";
447 /// let fields: Vec<&str> = re.split(hay).collect();
448 /// assert_eq!(fields, vec!["a", "b", "c", "d", "e"]);
449 /// ```
450 ///
451 /// # Example: more cases
452 ///
453 /// Basic usage:
454 ///
455 /// ```
456 /// use regex::Regex;
457 ///
458 /// let re = Regex::new(r" ").unwrap();
459 /// let hay = "Mary had a little lamb";
460 /// let got: Vec<&str> = re.split(hay).collect();
461 /// assert_eq!(got, vec!["Mary", "had", "a", "little", "lamb"]);
462 ///
463 /// let re = Regex::new(r"X").unwrap();
464 /// let hay = "";
465 /// let got: Vec<&str> = re.split(hay).collect();
466 /// assert_eq!(got, vec![""]);
467 ///
468 /// let re = Regex::new(r"X").unwrap();
469 /// let hay = "lionXXtigerXleopard";
470 /// let got: Vec<&str> = re.split(hay).collect();
471 /// assert_eq!(got, vec!["lion", "", "tiger", "leopard"]);
472 ///
473 /// let re = Regex::new(r"::").unwrap();
474 /// let hay = "lion::tiger::leopard";
475 /// let got: Vec<&str> = re.split(hay).collect();
476 /// assert_eq!(got, vec!["lion", "tiger", "leopard"]);
477 /// ```
478 ///
479 /// If a haystack contains multiple contiguous matches, you will end up
480 /// with empty spans yielded by the iterator:
481 ///
482 /// ```
483 /// use regex::Regex;
484 ///
485 /// let re = Regex::new(r"X").unwrap();
486 /// let hay = "XXXXaXXbXc";
487 /// let got: Vec<&str> = re.split(hay).collect();
488 /// assert_eq!(got, vec!["", "", "", "", "a", "", "b", "c"]);
489 ///
490 /// let re = Regex::new(r"/").unwrap();
491 /// let hay = "(///)";
492 /// let got: Vec<&str> = re.split(hay).collect();
493 /// assert_eq!(got, vec!["(", "", "", ")"]);
494 /// ```
495 ///
496 /// Separators at the start or end of a haystack are neighbored by empty
497 /// substring.
498 ///
499 /// ```
500 /// use regex::Regex;
501 ///
502 /// let re = Regex::new(r"0").unwrap();
503 /// let hay = "010";
504 /// let got: Vec<&str> = re.split(hay).collect();
505 /// assert_eq!(got, vec!["", "1", ""]);
506 /// ```
507 ///
508 /// When the empty string is used as a regex, it splits at every valid
509 /// UTF-8 boundary by default (which includes the beginning and end of the
510 /// haystack):
511 ///
512 /// ```
513 /// use regex::Regex;
514 ///
515 /// let re = Regex::new(r"").unwrap();
516 /// let hay = "rust";
517 /// let got: Vec<&str> = re.split(hay).collect();
518 /// assert_eq!(got, vec!["", "r", "u", "s", "t", ""]);
519 ///
520 /// // Splitting by an empty string is UTF-8 aware by default!
521 /// let re = Regex::new(r"").unwrap();
522 /// let hay = "☃";
523 /// let got: Vec<&str> = re.split(hay).collect();
524 /// assert_eq!(got, vec!["", "☃", ""]);
525 /// ```
526 ///
527 /// Contiguous separators (commonly shows up with whitespace), can lead to
528 /// possibly surprising behavior. For example, this code is correct:
529 ///
530 /// ```
531 /// use regex::Regex;
532 ///
533 /// let re = Regex::new(r" ").unwrap();
534 /// let hay = " a b c";
535 /// let got: Vec<&str> = re.split(hay).collect();
536 /// assert_eq!(got, vec!["", "", "", "", "a", "", "b", "c"]);
537 /// ```
538 ///
539 /// It does *not* give you `["a", "b", "c"]`. For that behavior, you'd want
540 /// to match contiguous space characters:
541 ///
542 /// ```
543 /// use regex::Regex;
544 ///
545 /// let re = Regex::new(r" +").unwrap();
546 /// let hay = " a b c";
547 /// let got: Vec<&str> = re.split(hay).collect();
548 /// // N.B. This does still include a leading empty span because ' +'
549 /// // matches at the beginning of the haystack.
550 /// assert_eq!(got, vec!["", "a", "b", "c"]);
551 /// ```
552 #[inline]
553 pub fn split<'r, 'h>(&'r self, haystack: &'h str) -> Split<'r, 'h> {
554 Split { haystack, it: self.meta.split(haystack) }
555 }
556
557 /// Returns an iterator of at most `limit` substrings of the haystack
558 /// given, delimited by a match of the regex. (A `limit` of `0` will return
559 /// no substrings.) Namely, each element of the iterator corresponds to a
560 /// part of the haystack that *isn't* matched by the regular expression.
561 /// The remainder of the haystack that is not split will be the last
562 /// element in the iterator.
563 ///
564 /// # Time complexity
565 ///
566 /// Since iterators over all matches requires running potentially many
567 /// searches on the haystack, and since each search has worst case
568 /// `O(m * n)` time complexity, the overall worst case time complexity for
569 /// this routine is `O(m * n^2)`.
570 ///
571 /// Although note that the worst case time here has an upper bound given
572 /// by the `limit` parameter.
573 ///
574 /// # Example
575 ///
576 /// Get the first two words in some haystack:
577 ///
578 /// ```
579 /// use regex::Regex;
580 ///
581 /// let re = Regex::new(r"\W+").unwrap();
582 /// let hay = "Hey! How are you?";
583 /// let fields: Vec<&str> = re.splitn(hay, 3).collect();
584 /// assert_eq!(fields, vec!["Hey", "How", "are you?"]);
585 /// ```
586 ///
587 /// # Examples: more cases
588 ///
589 /// ```
590 /// use regex::Regex;
591 ///
592 /// let re = Regex::new(r" ").unwrap();
593 /// let hay = "Mary had a little lamb";
594 /// let got: Vec<&str> = re.splitn(hay, 3).collect();
595 /// assert_eq!(got, vec!["Mary", "had", "a little lamb"]);
596 ///
597 /// let re = Regex::new(r"X").unwrap();
598 /// let hay = "";
599 /// let got: Vec<&str> = re.splitn(hay, 3).collect();
600 /// assert_eq!(got, vec![""]);
601 ///
602 /// let re = Regex::new(r"X").unwrap();
603 /// let hay = "lionXXtigerXleopard";
604 /// let got: Vec<&str> = re.splitn(hay, 3).collect();
605 /// assert_eq!(got, vec!["lion", "", "tigerXleopard"]);
606 ///
607 /// let re = Regex::new(r"::").unwrap();
608 /// let hay = "lion::tiger::leopard";
609 /// let got: Vec<&str> = re.splitn(hay, 2).collect();
610 /// assert_eq!(got, vec!["lion", "tiger::leopard"]);
611 ///
612 /// let re = Regex::new(r"X").unwrap();
613 /// let hay = "abcXdef";
614 /// let got: Vec<&str> = re.splitn(hay, 1).collect();
615 /// assert_eq!(got, vec!["abcXdef"]);
616 ///
617 /// let re = Regex::new(r"X").unwrap();
618 /// let hay = "abcdef";
619 /// let got: Vec<&str> = re.splitn(hay, 2).collect();
620 /// assert_eq!(got, vec!["abcdef"]);
621 ///
622 /// let re = Regex::new(r"X").unwrap();
623 /// let hay = "abcXdef";
624 /// let got: Vec<&str> = re.splitn(hay, 0).collect();
625 /// assert!(got.is_empty());
626 /// ```
627 #[inline]
628 pub fn splitn<'r, 'h>(
629 &'r self,
630 haystack: &'h str,
631 limit: usize,
632 ) -> SplitN<'r, 'h> {
633 SplitN { haystack, it: self.meta.splitn(haystack, limit) }
634 }
635
636 /// Replaces the leftmost-first match in the given haystack with the
637 /// replacement provided. The replacement can be a regular string (where
638 /// `$N` and `$name` are expanded to match capture groups) or a function
639 /// that takes a [`Captures`] and returns the replaced string.
640 ///
641 /// If no match is found, then the haystack is returned unchanged. In that
642 /// case, this implementation will likely return a `Cow::Borrowed` value
643 /// such that no allocation is performed.
644 ///
645 /// # Replacement string syntax
646 ///
647 /// All instances of `$ref` in the replacement string are replaced with
648 /// the substring corresponding to the capture group identified by `ref`.
649 ///
650 /// `ref` may be an integer corresponding to the index of the capture group
651 /// (counted by order of opening parenthesis where `0` is the entire match)
652 /// or it can be a name (consisting of letters, digits or underscores)
653 /// corresponding to a named capture group.
654 ///
655 /// If `ref` isn't a valid capture group (whether the name doesn't exist or
656 /// isn't a valid index), then it is replaced with the empty string.
657 ///
658 /// The longest possible name is used. For example, `$1a` looks up the
659 /// capture group named `1a` and not the capture group at index `1`. To
660 /// exert more precise control over the name, use braces, e.g., `${1}a`.
661 ///
662 /// To write a literal `$` use `$$`.
663 ///
664 /// # Example
665 ///
666 /// Note that this function is polymorphic with respect to the replacement.
667 /// In typical usage, this can just be a normal string:
668 ///
669 /// ```
670 /// use regex::Regex;
671 ///
672 /// let re = Regex::new(r"[^01]+").unwrap();
673 /// assert_eq!(re.replace("1078910", ""), "1010");
674 /// ```
675 ///
676 /// But anything satisfying the [`Replacer`] trait will work. For example,
677 /// a closure of type `|&Captures| -> String` provides direct access to the
678 /// captures corresponding to a match. This allows one to access capturing
679 /// group matches easily:
680 ///
681 /// ```
682 /// use regex::{Captures, Regex};
683 ///
684 /// let re = Regex::new(r"([^,\s]+),\s+(\S+)").unwrap();
685 /// let result = re.replace("Springsteen, Bruce", |caps: &Captures| {
686 /// format!("{} {}", &caps[2], &caps[1])
687 /// });
688 /// assert_eq!(result, "Bruce Springsteen");
689 /// ```
690 ///
691 /// But this is a bit cumbersome to use all the time. Instead, a simple
692 /// syntax is supported (as described above) that expands `$name` into the
693 /// corresponding capture group. Here's the last example, but using this
694 /// expansion technique with named capture groups:
695 ///
696 /// ```
697 /// use regex::Regex;
698 ///
699 /// let re = Regex::new(r"(?<last>[^,\s]+),\s+(?<first>\S+)").unwrap();
700 /// let result = re.replace("Springsteen, Bruce", "$first $last");
701 /// assert_eq!(result, "Bruce Springsteen");
702 /// ```
703 ///
704 /// Note that using `$2` instead of `$first` or `$1` instead of `$last`
705 /// would produce the same result. To write a literal `$` use `$$`.
706 ///
707 /// Sometimes the replacement string requires use of curly braces to
708 /// delineate a capture group replacement when it is adjacent to some other
709 /// literal text. For example, if we wanted to join two words together with
710 /// an underscore:
711 ///
712 /// ```
713 /// use regex::Regex;
714 ///
715 /// let re = Regex::new(r"(?<first>\w+)\s+(?<second>\w+)").unwrap();
716 /// let result = re.replace("deep fried", "${first}_$second");
717 /// assert_eq!(result, "deep_fried");
718 /// ```
719 ///
720 /// Without the curly braces, the capture group name `first_` would be
721 /// used, and since it doesn't exist, it would be replaced with the empty
722 /// string.
723 ///
724 /// Finally, sometimes you just want to replace a literal string with no
725 /// regard for capturing group expansion. This can be done by wrapping a
726 /// string with [`NoExpand`]:
727 ///
728 /// ```
729 /// use regex::{NoExpand, Regex};
730 ///
731 /// let re = Regex::new(r"(?<last>[^,\s]+),\s+(\S+)").unwrap();
732 /// let result = re.replace("Springsteen, Bruce", NoExpand("$2 $last"));
733 /// assert_eq!(result, "$2 $last");
734 /// ```
735 ///
736 /// Using `NoExpand` may also be faster, since the replacement string won't
737 /// need to be parsed for the `$` syntax.
738 #[inline]
739 pub fn replace<'h, R: Replacer>(
740 &self,
741 haystack: &'h str,
742 rep: R,
743 ) -> Cow<'h, str> {
744 self.replacen(haystack, 1, rep)
745 }
746
747 /// Replaces all non-overlapping matches in the haystack with the
748 /// replacement provided. This is the same as calling `replacen` with
749 /// `limit` set to `0`.
750 ///
751 /// The documentation for [`Regex::replace`] goes into more detail about
752 /// what kinds of replacement strings are supported.
753 ///
754 /// # Time complexity
755 ///
756 /// Since iterators over all matches requires running potentially many
757 /// searches on the haystack, and since each search has worst case
758 /// `O(m * n)` time complexity, the overall worst case time complexity for
759 /// this routine is `O(m * n^2)`.
760 ///
761 /// # Fallibility
762 ///
763 /// If you need to write a replacement routine where any individual
764 /// replacement might "fail," doing so with this API isn't really feasible
765 /// because there's no way to stop the search process if a replacement
766 /// fails. Instead, if you need this functionality, you should consider
767 /// implementing your own replacement routine:
768 ///
769 /// ```
770 /// use regex::{Captures, Regex};
771 ///
772 /// fn replace_all<E>(
773 /// re: &Regex,
774 /// haystack: &str,
775 /// replacement: impl Fn(&Captures) -> Result<String, E>,
776 /// ) -> Result<String, E> {
777 /// let mut new = String::with_capacity(haystack.len());
778 /// let mut last_match = 0;
779 /// for caps in re.captures_iter(haystack) {
780 /// let m = caps.get(0).unwrap();
781 /// new.push_str(&haystack[last_match..m.start()]);
782 /// new.push_str(&replacement(&caps)?);
783 /// last_match = m.end();
784 /// }
785 /// new.push_str(&haystack[last_match..]);
786 /// Ok(new)
787 /// }
788 ///
789 /// // Let's replace each word with the number of bytes in that word.
790 /// // But if we see a word that is "too long," we'll give up.
791 /// let re = Regex::new(r"\w+").unwrap();
792 /// let replacement = |caps: &Captures| -> Result<String, &'static str> {
793 /// if caps[0].len() >= 5 {
794 /// return Err("word too long");
795 /// }
796 /// Ok(caps[0].len().to_string())
797 /// };
798 /// assert_eq!(
799 /// Ok("2 3 3 3?".to_string()),
800 /// replace_all(&re, "hi how are you?", &replacement),
801 /// );
802 /// assert!(replace_all(&re, "hi there", &replacement).is_err());
803 /// ```
804 ///
805 /// # Example
806 ///
807 /// This example shows how to flip the order of whitespace (excluding line
808 /// terminators) delimited fields, and normalizes the whitespace that
809 /// delimits the fields:
810 ///
811 /// ```
812 /// use regex::Regex;
813 ///
814 /// let re = Regex::new(r"(?m)^(\S+)[\s--\r\n]+(\S+)$").unwrap();
815 /// let hay = "
816 /// Greetings 1973
817 /// Wild\t1973
818 /// BornToRun\t\t\t\t1975
819 /// Darkness 1978
820 /// TheRiver 1980
821 /// ";
822 /// let new = re.replace_all(hay, "$2 $1");
823 /// assert_eq!(new, "
824 /// 1973 Greetings
825 /// 1973 Wild
826 /// 1975 BornToRun
827 /// 1978 Darkness
828 /// 1980 TheRiver
829 /// ");
830 /// ```
831 #[inline]
832 pub fn replace_all<'h, R: Replacer>(
833 &self,
834 haystack: &'h str,
835 rep: R,
836 ) -> Cow<'h, str> {
837 self.replacen(haystack, 0, rep)
838 }
839
840 /// Replaces at most `limit` non-overlapping matches in the haystack with
841 /// the replacement provided. If `limit` is `0`, then all non-overlapping
842 /// matches are replaced. That is, `Regex::replace_all(hay, rep)` is
843 /// equivalent to `Regex::replacen(hay, 0, rep)`.
844 ///
845 /// The documentation for [`Regex::replace`] goes into more detail about
846 /// what kinds of replacement strings are supported.
847 ///
848 /// # Time complexity
849 ///
850 /// Since iterators over all matches requires running potentially many
851 /// searches on the haystack, and since each search has worst case
852 /// `O(m * n)` time complexity, the overall worst case time complexity for
853 /// this routine is `O(m * n^2)`.
854 ///
855 /// Although note that the worst case time here has an upper bound given
856 /// by the `limit` parameter.
857 ///
858 /// # Fallibility
859 ///
860 /// See the corresponding section in the docs for [`Regex::replace_all`]
861 /// for tips on how to deal with a replacement routine that can fail.
862 ///
863 /// # Example
864 ///
865 /// This example shows how to flip the order of whitespace (excluding line
866 /// terminators) delimited fields, and normalizes the whitespace that
867 /// delimits the fields. But we only do it for the first two matches.
868 ///
869 /// ```
870 /// use regex::Regex;
871 ///
872 /// let re = Regex::new(r"(?m)^(\S+)[\s--\r\n]+(\S+)$").unwrap();
873 /// let hay = "
874 /// Greetings 1973
875 /// Wild\t1973
876 /// BornToRun\t\t\t\t1975
877 /// Darkness 1978
878 /// TheRiver 1980
879 /// ";
880 /// let new = re.replacen(hay, 2, "$2 $1");
881 /// assert_eq!(new, "
882 /// 1973 Greetings
883 /// 1973 Wild
884 /// BornToRun\t\t\t\t1975
885 /// Darkness 1978
886 /// TheRiver 1980
887 /// ");
888 /// ```
889 #[inline]
890 pub fn replacen<'h, R: Replacer>(
891 &self,
892 haystack: &'h str,
893 limit: usize,
894 mut rep: R,
895 ) -> Cow<'h, str> {
896 // If we know that the replacement doesn't have any capture expansions,
897 // then we can use the fast path. The fast path can make a tremendous
898 // difference:
899 //
900 // 1) We use `find_iter` instead of `captures_iter`. Not asking for
901 // captures generally makes the regex engines faster.
902 // 2) We don't need to look up all of the capture groups and do
903 // replacements inside the replacement string. We just push it
904 // at each match and be done with it.
905 if let Some(rep) = rep.no_expansion() {
906 let mut it = self.find_iter(haystack).enumerate().peekable();
907 if it.peek().is_none() {
908 return Cow::Borrowed(haystack);
909 }
910 let mut new = String::with_capacity(haystack.len());
911 let mut last_match = 0;
912 for (i, m) in it {
913 new.push_str(&haystack[last_match..m.start()]);
914 new.push_str(&rep);
915 last_match = m.end();
916 if limit > 0 && i >= limit - 1 {
917 break;
918 }
919 }
920 new.push_str(&haystack[last_match..]);
921 return Cow::Owned(new);
922 }
923
924 // The slower path, which we use if the replacement may need access to
925 // capture groups.
926 let mut it = self.captures_iter(haystack).enumerate().peekable();
927 if it.peek().is_none() {
928 return Cow::Borrowed(haystack);
929 }
930 let mut new = String::with_capacity(haystack.len());
931 let mut last_match = 0;
932 for (i, cap) in it {
933 // unwrap on 0 is OK because captures only reports matches
934 let m = cap.get(0).unwrap();
935 new.push_str(&haystack[last_match..m.start()]);
936 rep.replace_append(&cap, &mut new);
937 last_match = m.end();
938 if limit > 0 && i >= limit - 1 {
939 break;
940 }
941 }
942 new.push_str(&haystack[last_match..]);
943 Cow::Owned(new)
944 }
945}
946
947/// A group of advanced or "lower level" search methods. Some methods permit
948/// starting the search at a position greater than `0` in the haystack. Other
949/// methods permit reusing allocations, for example, when extracting the
950/// matches for capture groups.
951impl Regex {
952 /// Returns the end byte offset of the first match in the haystack given.
953 ///
954 /// This method may have the same performance characteristics as
955 /// `is_match`. Behaviorlly, it doesn't just report whether it match
956 /// occurs, but also the end offset for a match. In particular, the offset
957 /// returned *may be shorter* than the proper end of the leftmost-first
958 /// match that you would find via [`Regex::find`].
959 ///
960 /// Note that it is not guaranteed that this routine finds the shortest or
961 /// "earliest" possible match. Instead, the main idea of this API is that
962 /// it returns the offset at the point at which the internal regex engine
963 /// has determined that a match has occurred. This may vary depending on
964 /// which internal regex engine is used, and thus, the offset itself may
965 /// change based on internal heuristics.
966 ///
967 /// # Example
968 ///
969 /// Typically, `a+` would match the entire first sequence of `a` in some
970 /// haystack, but `shortest_match` *may* give up as soon as it sees the
971 /// first `a`.
972 ///
973 /// ```
974 /// use regex::Regex;
975 ///
976 /// let re = Regex::new(r"a+").unwrap();
977 /// let offset = re.shortest_match("aaaaa").unwrap();
978 /// assert_eq!(offset, 1);
979 /// ```
980 #[inline]
981 pub fn shortest_match(&self, haystack: &str) -> Option<usize> {
982 self.shortest_match_at(haystack, 0)
983 }
984
985 /// Returns the same as [`Regex::shortest_match`], but starts the search at
986 /// the given offset.
987 ///
988 /// The significance of the starting point is that it takes the surrounding
989 /// context into consideration. For example, the `\A` anchor can only match
990 /// when `start == 0`.
991 ///
992 /// If a match is found, the offset returned is relative to the beginning
993 /// of the haystack, not the beginning of the search.
994 ///
995 /// # Panics
996 ///
997 /// This panics when `start >= haystack.len() + 1`.
998 ///
999 /// # Example
1000 ///
1001 /// This example shows the significance of `start` by demonstrating how it
1002 /// can be used to permit look-around assertions in a regex to take the
1003 /// surrounding context into account.
1004 ///
1005 /// ```
1006 /// use regex::Regex;
1007 ///
1008 /// let re = Regex::new(r"\bchew\b").unwrap();
1009 /// let hay = "eschew";
1010 /// // We get a match here, but it's probably not intended.
1011 /// assert_eq!(re.shortest_match(&hay[2..]), Some(4));
1012 /// // No match because the assertions take the context into account.
1013 /// assert_eq!(re.shortest_match_at(hay, 2), None);
1014 /// ```
1015 #[inline]
1016 pub fn shortest_match_at(
1017 &self,
1018 haystack: &str,
1019 start: usize,
1020 ) -> Option<usize> {
1021 let input =
1022 Input::new(haystack).earliest(true).span(start..haystack.len());
1023 self.meta.search_half(&input).map(|hm| hm.offset())
1024 }
1025
1026 /// Returns the same as [`Regex::is_match`], but starts the search at the
1027 /// given offset.
1028 ///
1029 /// The significance of the starting point is that it takes the surrounding
1030 /// context into consideration. For example, the `\A` anchor can only
1031 /// match when `start == 0`.
1032 ///
1033 /// # Panics
1034 ///
1035 /// This panics when `start >= haystack.len() + 1`.
1036 ///
1037 /// # Example
1038 ///
1039 /// This example shows the significance of `start` by demonstrating how it
1040 /// can be used to permit look-around assertions in a regex to take the
1041 /// surrounding context into account.
1042 ///
1043 /// ```
1044 /// use regex::Regex;
1045 ///
1046 /// let re = Regex::new(r"\bchew\b").unwrap();
1047 /// let hay = "eschew";
1048 /// // We get a match here, but it's probably not intended.
1049 /// assert!(re.is_match(&hay[2..]));
1050 /// // No match because the assertions take the context into account.
1051 /// assert!(!re.is_match_at(hay, 2));
1052 /// ```
1053 #[inline]
1054 pub fn is_match_at(&self, haystack: &str, start: usize) -> bool {
1055 let input =
1056 Input::new(haystack).earliest(true).span(start..haystack.len());
1057 self.meta.search_half(&input).is_some()
1058 }
1059
1060 /// Returns the same as [`Regex::find`], but starts the search at the given
1061 /// offset.
1062 ///
1063 /// The significance of the starting point is that it takes the surrounding
1064 /// context into consideration. For example, the `\A` anchor can only
1065 /// match when `start == 0`.
1066 ///
1067 /// # Panics
1068 ///
1069 /// This panics when `start >= haystack.len() + 1`.
1070 ///
1071 /// # Example
1072 ///
1073 /// This example shows the significance of `start` by demonstrating how it
1074 /// can be used to permit look-around assertions in a regex to take the
1075 /// surrounding context into account.
1076 ///
1077 /// ```
1078 /// use regex::Regex;
1079 ///
1080 /// let re = Regex::new(r"\bchew\b").unwrap();
1081 /// let hay = "eschew";
1082 /// // We get a match here, but it's probably not intended.
1083 /// assert_eq!(re.find(&hay[2..]).map(|m| m.range()), Some(0..4));
1084 /// // No match because the assertions take the context into account.
1085 /// assert_eq!(re.find_at(hay, 2), None);
1086 /// ```
1087 #[inline]
1088 pub fn find_at<'h>(
1089 &self,
1090 haystack: &'h str,
1091 start: usize,
1092 ) -> Option<Match<'h>> {
1093 let input = Input::new(haystack).span(start..haystack.len());
1094 self.meta
1095 .search(&input)
1096 .map(|m| Match::new(haystack, m.start(), m.end()))
1097 }
1098
1099 /// Returns the same as [`Regex::captures`], but starts the search at the
1100 /// given offset.
1101 ///
1102 /// The significance of the starting point is that it takes the surrounding
1103 /// context into consideration. For example, the `\A` anchor can only
1104 /// match when `start == 0`.
1105 ///
1106 /// # Panics
1107 ///
1108 /// This panics when `start >= haystack.len() + 1`.
1109 ///
1110 /// # Example
1111 ///
1112 /// This example shows the significance of `start` by demonstrating how it
1113 /// can be used to permit look-around assertions in a regex to take the
1114 /// surrounding context into account.
1115 ///
1116 /// ```
1117 /// use regex::Regex;
1118 ///
1119 /// let re = Regex::new(r"\bchew\b").unwrap();
1120 /// let hay = "eschew";
1121 /// // We get a match here, but it's probably not intended.
1122 /// assert_eq!(&re.captures(&hay[2..]).unwrap()[0], "chew");
1123 /// // No match because the assertions take the context into account.
1124 /// assert!(re.captures_at(hay, 2).is_none());
1125 /// ```
1126 #[inline]
1127 pub fn captures_at<'h>(
1128 &self,
1129 haystack: &'h str,
1130 start: usize,
1131 ) -> Option<Captures<'h>> {
1132 let input = Input::new(haystack).span(start..haystack.len());
1133 let mut caps = self.meta.create_captures();
1134 self.meta.search_captures(&input, &mut caps);
1135 if caps.is_match() {
1136 let static_captures_len = self.static_captures_len();
1137 Some(Captures { haystack, caps, static_captures_len })
1138 } else {
1139 None
1140 }
1141 }
1142
1143 /// This is like [`Regex::captures`], but writes the byte offsets of each
1144 /// capture group match into the locations given.
1145 ///
1146 /// A [`CaptureLocations`] stores the same byte offsets as a [`Captures`],
1147 /// but does *not* store a reference to the haystack. This makes its API
1148 /// a bit lower level and less convenient. But in exchange, callers
1149 /// may allocate their own `CaptureLocations` and reuse it for multiple
1150 /// searches. This may be helpful if allocating a `Captures` shows up in a
1151 /// profile as too costly.
1152 ///
1153 /// To create a `CaptureLocations` value, use the
1154 /// [`Regex::capture_locations`] method.
1155 ///
1156 /// This also returns the overall match if one was found. When a match is
1157 /// found, its offsets are also always stored in `locs` at index `0`.
1158 ///
1159 /// # Panics
1160 ///
1161 /// This routine may panic if the given `CaptureLocations` was not created
1162 /// by this regex.
1163 ///
1164 /// # Example
1165 ///
1166 /// ```
1167 /// use regex::Regex;
1168 ///
1169 /// let re = Regex::new(r"^([a-z]+)=(\S*)$").unwrap();
1170 /// let mut locs = re.capture_locations();
1171 /// assert!(re.captures_read(&mut locs, "id=foo123").is_some());
1172 /// assert_eq!(Some((0, 9)), locs.get(0));
1173 /// assert_eq!(Some((0, 2)), locs.get(1));
1174 /// assert_eq!(Some((3, 9)), locs.get(2));
1175 /// ```
1176 #[inline]
1177 pub fn captures_read<'h>(
1178 &self,
1179 locs: &mut CaptureLocations,
1180 haystack: &'h str,
1181 ) -> Option<Match<'h>> {
1182 self.captures_read_at(locs, haystack, 0)
1183 }
1184
1185 /// Returns the same as [`Regex::captures_read`], but starts the search at
1186 /// the given offset.
1187 ///
1188 /// The significance of the starting point is that it takes the surrounding
1189 /// context into consideration. For example, the `\A` anchor can only
1190 /// match when `start == 0`.
1191 ///
1192 /// # Panics
1193 ///
1194 /// This panics when `start >= haystack.len() + 1`.
1195 ///
1196 /// This routine may also panic if the given `CaptureLocations` was not
1197 /// created by this regex.
1198 ///
1199 /// # Example
1200 ///
1201 /// This example shows the significance of `start` by demonstrating how it
1202 /// can be used to permit look-around assertions in a regex to take the
1203 /// surrounding context into account.
1204 ///
1205 /// ```
1206 /// use regex::Regex;
1207 ///
1208 /// let re = Regex::new(r"\bchew\b").unwrap();
1209 /// let hay = "eschew";
1210 /// let mut locs = re.capture_locations();
1211 /// // We get a match here, but it's probably not intended.
1212 /// assert!(re.captures_read(&mut locs, &hay[2..]).is_some());
1213 /// // No match because the assertions take the context into account.
1214 /// assert!(re.captures_read_at(&mut locs, hay, 2).is_none());
1215 /// ```
1216 #[inline]
1217 pub fn captures_read_at<'h>(
1218 &self,
1219 locs: &mut CaptureLocations,
1220 haystack: &'h str,
1221 start: usize,
1222 ) -> Option<Match<'h>> {
1223 let input = Input::new(haystack).span(start..haystack.len());
1224 self.meta.search_captures(&input, &mut locs.0);
1225 locs.0.get_match().map(|m| Match::new(haystack, m.start(), m.end()))
1226 }
1227
1228 /// An undocumented alias for `captures_read_at`.
1229 ///
1230 /// The `regex-capi` crate previously used this routine, so to avoid
1231 /// breaking that crate, we continue to provide the name as an undocumented
1232 /// alias.
1233 #[doc(hidden)]
1234 #[inline]
1235 pub fn read_captures_at<'h>(
1236 &self,
1237 locs: &mut CaptureLocations,
1238 haystack: &'h str,
1239 start: usize,
1240 ) -> Option<Match<'h>> {
1241 self.captures_read_at(locs, haystack, start)
1242 }
1243}
1244
1245/// Auxiliary methods.
1246impl Regex {
1247 /// Returns the original string of this regex.
1248 ///
1249 /// # Example
1250 ///
1251 /// ```
1252 /// use regex::Regex;
1253 ///
1254 /// let re = Regex::new(r"foo\w+bar").unwrap();
1255 /// assert_eq!(re.as_str(), r"foo\w+bar");
1256 /// ```
1257 #[inline]
1258 pub fn as_str(&self) -> &str {
1259 &self.pattern
1260 }
1261
1262 /// Returns an iterator over the capture names in this regex.
1263 ///
1264 /// The iterator returned yields elements of type `Option<&str>`. That is,
1265 /// the iterator yields values for all capture groups, even ones that are
1266 /// unnamed. The order of the groups corresponds to the order of the group's
1267 /// corresponding opening parenthesis.
1268 ///
1269 /// The first element of the iterator always yields the group corresponding
1270 /// to the overall match, and this group is always unnamed. Therefore, the
1271 /// iterator always yields at least one group.
1272 ///
1273 /// # Example
1274 ///
1275 /// This shows basic usage with a mix of named and unnamed capture groups:
1276 ///
1277 /// ```
1278 /// use regex::Regex;
1279 ///
1280 /// let re = Regex::new(r"(?<a>.(?<b>.))(.)(?:.)(?<c>.)").unwrap();
1281 /// let mut names = re.capture_names();
1282 /// assert_eq!(names.next(), Some(None));
1283 /// assert_eq!(names.next(), Some(Some("a")));
1284 /// assert_eq!(names.next(), Some(Some("b")));
1285 /// assert_eq!(names.next(), Some(None));
1286 /// // the '(?:.)' group is non-capturing and so doesn't appear here!
1287 /// assert_eq!(names.next(), Some(Some("c")));
1288 /// assert_eq!(names.next(), None);
1289 /// ```
1290 ///
1291 /// The iterator always yields at least one element, even for regexes with
1292 /// no capture groups and even for regexes that can never match:
1293 ///
1294 /// ```
1295 /// use regex::Regex;
1296 ///
1297 /// let re = Regex::new(r"").unwrap();
1298 /// let mut names = re.capture_names();
1299 /// assert_eq!(names.next(), Some(None));
1300 /// assert_eq!(names.next(), None);
1301 ///
1302 /// let re = Regex::new(r"[a&&b]").unwrap();
1303 /// let mut names = re.capture_names();
1304 /// assert_eq!(names.next(), Some(None));
1305 /// assert_eq!(names.next(), None);
1306 /// ```
1307 #[inline]
1308 pub fn capture_names(&self) -> CaptureNames<'_> {
1309 CaptureNames(self.meta.group_info().pattern_names(PatternID::ZERO))
1310 }
1311
1312 /// Returns the number of captures groups in this regex.
1313 ///
1314 /// This includes all named and unnamed groups, including the implicit
1315 /// unnamed group that is always present and corresponds to the entire
1316 /// match.
1317 ///
1318 /// Since the implicit unnamed group is always included in this length, the
1319 /// length returned is guaranteed to be greater than zero.
1320 ///
1321 /// # Example
1322 ///
1323 /// ```
1324 /// use regex::Regex;
1325 ///
1326 /// let re = Regex::new(r"foo").unwrap();
1327 /// assert_eq!(1, re.captures_len());
1328 ///
1329 /// let re = Regex::new(r"(foo)").unwrap();
1330 /// assert_eq!(2, re.captures_len());
1331 ///
1332 /// let re = Regex::new(r"(?<a>.(?<b>.))(.)(?:.)(?<c>.)").unwrap();
1333 /// assert_eq!(5, re.captures_len());
1334 ///
1335 /// let re = Regex::new(r"[a&&b]").unwrap();
1336 /// assert_eq!(1, re.captures_len());
1337 /// ```
1338 #[inline]
1339 pub fn captures_len(&self) -> usize {
1340 self.meta.group_info().group_len(PatternID::ZERO)
1341 }
1342
1343 /// Returns the total number of capturing groups that appear in every
1344 /// possible match.
1345 ///
1346 /// If the number of capture groups can vary depending on the match, then
1347 /// this returns `None`. That is, a value is only returned when the number
1348 /// of matching groups is invariant or "static."
1349 ///
1350 /// Note that like [`Regex::captures_len`], this **does** include the
1351 /// implicit capturing group corresponding to the entire match. Therefore,
1352 /// when a non-None value is returned, it is guaranteed to be at least `1`.
1353 /// Stated differently, a return value of `Some(0)` is impossible.
1354 ///
1355 /// # Example
1356 ///
1357 /// This shows a few cases where a static number of capture groups is
1358 /// available and a few cases where it is not.
1359 ///
1360 /// ```
1361 /// use regex::Regex;
1362 ///
1363 /// let len = |pattern| {
1364 /// Regex::new(pattern).map(|re| re.static_captures_len())
1365 /// };
1366 ///
1367 /// assert_eq!(Some(1), len("a")?);
1368 /// assert_eq!(Some(2), len("(a)")?);
1369 /// assert_eq!(Some(2), len("(a)|(b)")?);
1370 /// assert_eq!(Some(3), len("(a)(b)|(c)(d)")?);
1371 /// assert_eq!(None, len("(a)|b")?);
1372 /// assert_eq!(None, len("a|(b)")?);
1373 /// assert_eq!(None, len("(b)*")?);
1374 /// assert_eq!(Some(2), len("(b)+")?);
1375 ///
1376 /// # Ok::<(), Box<dyn std::error::Error>>(())
1377 /// ```
1378 #[inline]
1379 pub fn static_captures_len(&self) -> Option<usize> {
1380 self.meta.static_captures_len()
1381 }
1382
1383 /// Returns a fresh allocated set of capture locations that can
1384 /// be reused in multiple calls to [`Regex::captures_read`] or
1385 /// [`Regex::captures_read_at`].
1386 ///
1387 /// The returned locations can be used for any subsequent search for this
1388 /// particular regex. There is no guarantee that it is correct to use for
1389 /// other regexes, even if they have the same number of capture groups.
1390 ///
1391 /// # Example
1392 ///
1393 /// ```
1394 /// use regex::Regex;
1395 ///
1396 /// let re = Regex::new(r"(.)(.)(\w+)").unwrap();
1397 /// let mut locs = re.capture_locations();
1398 /// assert!(re.captures_read(&mut locs, "Padron").is_some());
1399 /// assert_eq!(locs.get(0), Some((0, 6)));
1400 /// assert_eq!(locs.get(1), Some((0, 1)));
1401 /// assert_eq!(locs.get(2), Some((1, 2)));
1402 /// assert_eq!(locs.get(3), Some((2, 6)));
1403 /// ```
1404 #[inline]
1405 pub fn capture_locations(&self) -> CaptureLocations {
1406 CaptureLocations(self.meta.create_captures())
1407 }
1408
1409 /// An alias for `capture_locations` to preserve backward compatibility.
1410 ///
1411 /// The `regex-capi` crate used this method, so to avoid breaking that
1412 /// crate, we continue to export it as an undocumented API.
1413 #[doc(hidden)]
1414 #[inline]
1415 pub fn locations(&self) -> CaptureLocations {
1416 self.capture_locations()
1417 }
1418}
1419
1420/// Represents a single match of a regex in a haystack.
1421///
1422/// A `Match` contains both the start and end byte offsets of the match and the
1423/// actual substring corresponding to the range of those byte offsets. It is
1424/// guaranteed that `start <= end`. When `start == end`, the match is empty.
1425///
1426/// Since this `Match` can only be produced by the top-level `Regex` APIs
1427/// that only support searching UTF-8 encoded strings, the byte offsets for a
1428/// `Match` are guaranteed to fall on valid UTF-8 codepoint boundaries. That
1429/// is, slicing a `&str` with [`Match::range`] is guaranteed to never panic.
1430///
1431/// Values with this type are created by [`Regex::find`] or
1432/// [`Regex::find_iter`]. Other APIs can create `Match` values too. For
1433/// example, [`Captures::get`].
1434///
1435/// The lifetime parameter `'h` refers to the lifetime of the matched of the
1436/// haystack that this match was produced from.
1437///
1438/// # Numbering
1439///
1440/// The byte offsets in a `Match` form a half-open interval. That is, the
1441/// start of the range is inclusive and the end of the range is exclusive.
1442/// For example, given a haystack `abcFOOxyz` and a match of `FOO`, its byte
1443/// offset range starts at `3` and ends at `6`. `3` corresponds to `F` and
1444/// `6` corresponds to `x`, which is one past the end of the match. This
1445/// corresponds to the same kind of slicing that Rust uses.
1446///
1447/// For more on why this was chosen over other schemes (aside from being
1448/// consistent with how Rust the language works), see [this discussion] and
1449/// [Dijkstra's note on a related topic][note].
1450///
1451/// [this discussion]: https://github.com/rust-lang/regex/discussions/866
1452/// [note]: https://www.cs.utexas.edu/users/EWD/transcriptions/EWD08xx/EWD831.html
1453///
1454/// # Example
1455///
1456/// This example shows the value of each of the methods on `Match` for a
1457/// particular search.
1458///
1459/// ```
1460/// use regex::Regex;
1461///
1462/// let re = Regex::new(r"\p{Greek}+").unwrap();
1463/// let hay = "Greek: αβγδ";
1464/// let m = re.find(hay).unwrap();
1465/// assert_eq!(7, m.start());
1466/// assert_eq!(15, m.end());
1467/// assert!(!m.is_empty());
1468/// assert_eq!(8, m.len());
1469/// assert_eq!(7..15, m.range());
1470/// assert_eq!("αβγδ", m.as_str());
1471/// ```
1472#[derive(Copy, Clone, Eq, PartialEq)]
1473pub struct Match<'h> {
1474 haystack: &'h str,
1475 start: usize,
1476 end: usize,
1477}
1478
1479impl<'h> Match<'h> {
1480 /// Returns the byte offset of the start of the match in the haystack. The
1481 /// start of the match corresponds to the position where the match begins
1482 /// and includes the first byte in the match.
1483 ///
1484 /// It is guaranteed that `Match::start() <= Match::end()`.
1485 ///
1486 /// This is guaranteed to fall on a valid UTF-8 codepoint boundary. That
1487 /// is, it will never be an offset that appears between the UTF-8 code
1488 /// units of a UTF-8 encoded Unicode scalar value. Consequently, it is
1489 /// always safe to slice the corresponding haystack using this offset.
1490 #[inline]
1491 pub fn start(&self) -> usize {
1492 self.start
1493 }
1494
1495 /// Returns the byte offset of the end of the match in the haystack. The
1496 /// end of the match corresponds to the byte immediately following the last
1497 /// byte in the match. This means that `&slice[start..end]` works as one
1498 /// would expect.
1499 ///
1500 /// It is guaranteed that `Match::start() <= Match::end()`.
1501 ///
1502 /// This is guaranteed to fall on a valid UTF-8 codepoint boundary. That
1503 /// is, it will never be an offset that appears between the UTF-8 code
1504 /// units of a UTF-8 encoded Unicode scalar value. Consequently, it is
1505 /// always safe to slice the corresponding haystack using this offset.
1506 #[inline]
1507 pub fn end(&self) -> usize {
1508 self.end
1509 }
1510
1511 /// Returns true if and only if this match has a length of zero.
1512 ///
1513 /// Note that an empty match can only occur when the regex itself can
1514 /// match the empty string. Here are some examples of regexes that can
1515 /// all match the empty string: `^`, `^$`, `\b`, `a?`, `a*`, `a{0}`,
1516 /// `(foo|\d+|quux)?`.
1517 #[inline]
1518 pub fn is_empty(&self) -> bool {
1519 self.start == self.end
1520 }
1521
1522 /// Returns the length, in bytes, of this match.
1523 #[inline]
1524 pub fn len(&self) -> usize {
1525 self.end - self.start
1526 }
1527
1528 /// Returns the range over the starting and ending byte offsets of the
1529 /// match in the haystack.
1530 ///
1531 /// It is always correct to slice the original haystack searched with this
1532 /// range. That is, because the offsets are guaranteed to fall on valid
1533 /// UTF-8 boundaries, the range returned is always valid.
1534 #[inline]
1535 pub fn range(&self) -> core::ops::Range<usize> {
1536 self.start..self.end
1537 }
1538
1539 /// Returns the substring of the haystack that matched.
1540 #[inline]
1541 pub fn as_str(&self) -> &'h str {
1542 &self.haystack[self.range()]
1543 }
1544
1545 /// Creates a new match from the given haystack and byte offsets.
1546 #[inline]
1547 fn new(haystack: &'h str, start: usize, end: usize) -> Match<'h> {
1548 Match { haystack, start, end }
1549 }
1550}
1551
1552impl<'h> core::fmt::Debug for Match<'h> {
1553 fn fmt(&self, f: &mut core::fmt::Formatter) -> core::fmt::Result {
1554 f.debug_struct("Match")
1555 .field("start", &self.start)
1556 .field("end", &self.end)
1557 .field("string", &self.as_str())
1558 .finish()
1559 }
1560}
1561
1562impl<'h> From<Match<'h>> for &'h str {
1563 fn from(m: Match<'h>) -> &'h str {
1564 m.as_str()
1565 }
1566}
1567
1568impl<'h> From<Match<'h>> for core::ops::Range<usize> {
1569 fn from(m: Match<'h>) -> core::ops::Range<usize> {
1570 m.range()
1571 }
1572}
1573
1574/// Represents the capture groups for a single match.
1575///
1576/// Capture groups refer to parts of a regex enclosed in parentheses. They can
1577/// be optionally named. The purpose of capture groups is to be able to
1578/// reference different parts of a match based on the original pattern. For
1579/// example, say you want to match the individual letters in a 5-letter word:
1580///
1581/// ```text
1582/// (?<first>\w)(\w)(?:\w)\w(?<last>\w)
1583/// ```
1584///
1585/// This regex has 4 capture groups:
1586///
1587/// * The group at index `0` corresponds to the overall match. It is always
1588/// present in every match and never has a name.
1589/// * The group at index `1` with name `first` corresponding to the first
1590/// letter.
1591/// * The group at index `2` with no name corresponding to the second letter.
1592/// * The group at index `3` with name `last` corresponding to the fifth and
1593/// last letter.
1594///
1595/// Notice that `(?:\w)` was not listed above as a capture group despite it
1596/// being enclosed in parentheses. That's because `(?:pattern)` is a special
1597/// syntax that permits grouping but *without* capturing. The reason for not
1598/// treating it as a capture is that tracking and reporting capture groups
1599/// requires additional state that may lead to slower searches. So using as few
1600/// capture groups as possible can help performance. (Although the difference
1601/// in performance of a couple of capture groups is likely immaterial.)
1602///
1603/// Values with this type are created by [`Regex::captures`] or
1604/// [`Regex::captures_iter`].
1605///
1606/// `'h` is the lifetime of the haystack that these captures were matched from.
1607///
1608/// # Example
1609///
1610/// ```
1611/// use regex::Regex;
1612///
1613/// let re = Regex::new(r"(?<first>\w)(\w)(?:\w)\w(?<last>\w)").unwrap();
1614/// let caps = re.captures("toady").unwrap();
1615/// assert_eq!("toady", &caps[0]);
1616/// assert_eq!("t", &caps["first"]);
1617/// assert_eq!("o", &caps[2]);
1618/// assert_eq!("y", &caps["last"]);
1619/// ```
1620pub struct Captures<'h> {
1621 haystack: &'h str,
1622 caps: captures::Captures,
1623 static_captures_len: Option<usize>,
1624}
1625
1626impl<'h> Captures<'h> {
1627 /// Returns the `Match` associated with the capture group at index `i`. If
1628 /// `i` does not correspond to a capture group, or if the capture group did
1629 /// not participate in the match, then `None` is returned.
1630 ///
1631 /// When `i == 0`, this is guaranteed to return a non-`None` value.
1632 ///
1633 /// # Examples
1634 ///
1635 /// Get the substring that matched with a default of an empty string if the
1636 /// group didn't participate in the match:
1637 ///
1638 /// ```
1639 /// use regex::Regex;
1640 ///
1641 /// let re = Regex::new(r"[a-z]+(?:([0-9]+)|([A-Z]+))").unwrap();
1642 /// let caps = re.captures("abc123").unwrap();
1643 ///
1644 /// let substr1 = caps.get(1).map_or("", |m| m.as_str());
1645 /// let substr2 = caps.get(2).map_or("", |m| m.as_str());
1646 /// assert_eq!(substr1, "123");
1647 /// assert_eq!(substr2, "");
1648 /// ```
1649 #[inline]
1650 pub fn get(&self, i: usize) -> Option<Match<'h>> {
1651 self.caps
1652 .get_group(i)
1653 .map(|sp| Match::new(self.haystack, sp.start, sp.end))
1654 }
1655
1656 /// Returns the `Match` associated with the capture group named `name`. If
1657 /// `name` isn't a valid capture group or it refers to a group that didn't
1658 /// match, then `None` is returned.
1659 ///
1660 /// Note that unlike `caps["name"]`, this returns a `Match` whose lifetime
1661 /// matches the lifetime of the haystack in this `Captures` value.
1662 /// Conversely, the substring returned by `caps["name"]` has a lifetime
1663 /// of the `Captures` value, which is likely shorter than the lifetime of
1664 /// the haystack. In some cases, it may be necessary to use this method to
1665 /// access the matching substring instead of the `caps["name"]` notation.
1666 ///
1667 /// # Examples
1668 ///
1669 /// Get the substring that matched with a default of an empty string if the
1670 /// group didn't participate in the match:
1671 ///
1672 /// ```
1673 /// use regex::Regex;
1674 ///
1675 /// let re = Regex::new(
1676 /// r"[a-z]+(?:(?<numbers>[0-9]+)|(?<letters>[A-Z]+))",
1677 /// ).unwrap();
1678 /// let caps = re.captures("abc123").unwrap();
1679 ///
1680 /// let numbers = caps.name("numbers").map_or("", |m| m.as_str());
1681 /// let letters = caps.name("letters").map_or("", |m| m.as_str());
1682 /// assert_eq!(numbers, "123");
1683 /// assert_eq!(letters, "");
1684 /// ```
1685 #[inline]
1686 pub fn name(&self, name: &str) -> Option<Match<'h>> {
1687 self.caps
1688 .get_group_by_name(name)
1689 .map(|sp| Match::new(self.haystack, sp.start, sp.end))
1690 }
1691
1692 /// This is a convenience routine for extracting the substrings
1693 /// corresponding to matching capture groups.
1694 ///
1695 /// This returns a tuple where the first element corresponds to the full
1696 /// substring of the haystack that matched the regex. The second element is
1697 /// an array of substrings, with each corresponding to the to the substring
1698 /// that matched for a particular capture group.
1699 ///
1700 /// # Panics
1701 ///
1702 /// This panics if the number of possible matching groups in this
1703 /// `Captures` value is not fixed to `N` in all circumstances.
1704 /// More precisely, this routine only works when `N` is equivalent to
1705 /// [`Regex::static_captures_len`].
1706 ///
1707 /// Stated more plainly, if the number of matching capture groups in a
1708 /// regex can vary from match to match, then this function always panics.
1709 ///
1710 /// For example, `(a)(b)|(c)` could produce two matching capture groups
1711 /// or one matching capture group for any given match. Therefore, one
1712 /// cannot use `extract` with such a pattern.
1713 ///
1714 /// But a pattern like `(a)(b)|(c)(d)` can be used with `extract` because
1715 /// the number of capture groups in every match is always equivalent,
1716 /// even if the capture _indices_ in each match are not.
1717 ///
1718 /// # Example
1719 ///
1720 /// ```
1721 /// use regex::Regex;
1722 ///
1723 /// let re = Regex::new(r"([0-9]{4})-([0-9]{2})-([0-9]{2})").unwrap();
1724 /// let hay = "On 2010-03-14, I became a Tenneessee lamb.";
1725 /// let Some((full, [year, month, day])) =
1726 /// re.captures(hay).map(|caps| caps.extract()) else { return };
1727 /// assert_eq!("2010-03-14", full);
1728 /// assert_eq!("2010", year);
1729 /// assert_eq!("03", month);
1730 /// assert_eq!("14", day);
1731 /// ```
1732 ///
1733 /// # Example: iteration
1734 ///
1735 /// This example shows how to use this method when iterating over all
1736 /// `Captures` matches in a haystack.
1737 ///
1738 /// ```
1739 /// use regex::Regex;
1740 ///
1741 /// let re = Regex::new(r"([0-9]{4})-([0-9]{2})-([0-9]{2})").unwrap();
1742 /// let hay = "1973-01-05, 1975-08-25 and 1980-10-18";
1743 ///
1744 /// let mut dates: Vec<(&str, &str, &str)> = vec![];
1745 /// for (_, [y, m, d]) in re.captures_iter(hay).map(|c| c.extract()) {
1746 /// dates.push((y, m, d));
1747 /// }
1748 /// assert_eq!(dates, vec![
1749 /// ("1973", "01", "05"),
1750 /// ("1975", "08", "25"),
1751 /// ("1980", "10", "18"),
1752 /// ]);
1753 /// ```
1754 ///
1755 /// # Example: parsing different formats
1756 ///
1757 /// This API is particularly useful when you need to extract a particular
1758 /// value that might occur in a different format. Consider, for example,
1759 /// an identifier that might be in double quotes or single quotes:
1760 ///
1761 /// ```
1762 /// use regex::Regex;
1763 ///
1764 /// let re = Regex::new(r#"id:(?:"([^"]+)"|'([^']+)')"#).unwrap();
1765 /// let hay = r#"The first is id:"foo" and the second is id:'bar'."#;
1766 /// let mut ids = vec![];
1767 /// for (_, [id]) in re.captures_iter(hay).map(|c| c.extract()) {
1768 /// ids.push(id);
1769 /// }
1770 /// assert_eq!(ids, vec!["foo", "bar"]);
1771 /// ```
1772 pub fn extract<const N: usize>(&self) -> (&'h str, [&'h str; N]) {
1773 let len = self
1774 .static_captures_len
1775 .expect("number of capture groups can vary in a match")
1776 .checked_sub(1)
1777 .expect("number of groups is always greater than zero");
1778 assert_eq!(N, len, "asked for {} groups, but must ask for {}", N, len);
1779 // The regex-automata variant of extract is a bit more permissive.
1780 // It doesn't require the number of matching capturing groups to be
1781 // static, and you can even request fewer groups than what's there. So
1782 // this is guaranteed to never panic because we've asserted above that
1783 // the user has requested precisely the number of groups that must be
1784 // present in any match for this regex.
1785 self.caps.extract(self.haystack)
1786 }
1787
1788 /// Expands all instances of `$ref` in `replacement` to the corresponding
1789 /// capture group, and writes them to the `dst` buffer given. A `ref` can
1790 /// be a capture group index or a name. If `ref` doesn't refer to a capture
1791 /// group that participated in the match, then it is replaced with the
1792 /// empty string.
1793 ///
1794 /// # Format
1795 ///
1796 /// The format of the replacement string supports two different kinds of
1797 /// capture references: unbraced and braced.
1798 ///
1799 /// For the unbraced format, the format supported is `$ref` where `name`
1800 /// can be any character in the class `[0-9A-Za-z_]`. `ref` is always
1801 /// the longest possible parse. So for example, `$1a` corresponds to the
1802 /// capture group named `1a` and not the capture group at index `1`. If
1803 /// `ref` matches `^[0-9]+$`, then it is treated as a capture group index
1804 /// itself and not a name.
1805 ///
1806 /// For the braced format, the format supported is `${ref}` where `ref` can
1807 /// be any sequence of bytes except for `}`. If no closing brace occurs,
1808 /// then it is not considered a capture reference. As with the unbraced
1809 /// format, if `ref` matches `^[0-9]+$`, then it is treated as a capture
1810 /// group index and not a name.
1811 ///
1812 /// The braced format is useful for exerting precise control over the name
1813 /// of the capture reference. For example, `${1}a` corresponds to the
1814 /// capture group reference `1` followed by the letter `a`, where as `$1a`
1815 /// (as mentioned above) corresponds to the capture group reference `1a`.
1816 /// The braced format is also useful for expressing capture group names
1817 /// that use characters not supported by the unbraced format. For example,
1818 /// `${foo[bar].baz}` refers to the capture group named `foo[bar].baz`.
1819 ///
1820 /// If a capture group reference is found and it does not refer to a valid
1821 /// capture group, then it will be replaced with the empty string.
1822 ///
1823 /// To write a literal `$`, use `$$`.
1824 ///
1825 /// # Example
1826 ///
1827 /// ```
1828 /// use regex::Regex;
1829 ///
1830 /// let re = Regex::new(
1831 /// r"(?<day>[0-9]{2})-(?<month>[0-9]{2})-(?<year>[0-9]{4})",
1832 /// ).unwrap();
1833 /// let hay = "On 14-03-2010, I became a Tenneessee lamb.";
1834 /// let caps = re.captures(hay).unwrap();
1835 ///
1836 /// let mut dst = String::new();
1837 /// caps.expand("year=$year, month=$month, day=$day", &mut dst);
1838 /// assert_eq!(dst, "year=2010, month=03, day=14");
1839 /// ```
1840 #[inline]
1841 pub fn expand(&self, replacement: &str, dst: &mut String) {
1842 self.caps.interpolate_string_into(self.haystack, replacement, dst);
1843 }
1844
1845 /// Returns an iterator over all capture groups. This includes both
1846 /// matching and non-matching groups.
1847 ///
1848 /// The iterator always yields at least one matching group: the first group
1849 /// (at index `0`) with no name. Subsequent groups are returned in the order
1850 /// of their opening parenthesis in the regex.
1851 ///
1852 /// The elements yielded have type `Option<Match<'h>>`, where a non-`None`
1853 /// value is present if the capture group matches.
1854 ///
1855 /// # Example
1856 ///
1857 /// ```
1858 /// use regex::Regex;
1859 ///
1860 /// let re = Regex::new(r"(\w)(\d)?(\w)").unwrap();
1861 /// let caps = re.captures("AZ").unwrap();
1862 ///
1863 /// let mut it = caps.iter();
1864 /// assert_eq!(it.next().unwrap().map(|m| m.as_str()), Some("AZ"));
1865 /// assert_eq!(it.next().unwrap().map(|m| m.as_str()), Some("A"));
1866 /// assert_eq!(it.next().unwrap().map(|m| m.as_str()), None);
1867 /// assert_eq!(it.next().unwrap().map(|m| m.as_str()), Some("Z"));
1868 /// assert_eq!(it.next(), None);
1869 /// ```
1870 #[inline]
1871 pub fn iter<'c>(&'c self) -> SubCaptureMatches<'c, 'h> {
1872 SubCaptureMatches { haystack: self.haystack, it: self.caps.iter() }
1873 }
1874
1875 /// Returns the total number of capture groups. This includes both
1876 /// matching and non-matching groups.
1877 ///
1878 /// The length returned is always equivalent to the number of elements
1879 /// yielded by [`Captures::iter`]. Consequently, the length is always
1880 /// greater than zero since every `Captures` value always includes the
1881 /// match for the entire regex.
1882 ///
1883 /// # Example
1884 ///
1885 /// ```
1886 /// use regex::Regex;
1887 ///
1888 /// let re = Regex::new(r"(\w)(\d)?(\w)").unwrap();
1889 /// let caps = re.captures("AZ").unwrap();
1890 /// assert_eq!(caps.len(), 4);
1891 /// ```
1892 #[inline]
1893 pub fn len(&self) -> usize {
1894 self.caps.group_len()
1895 }
1896}
1897
1898impl<'h> core::fmt::Debug for Captures<'h> {
1899 fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
1900 /// A little helper type to provide a nice map-like debug
1901 /// representation for our capturing group spans.
1902 ///
1903 /// regex-automata has something similar, but it includes the pattern
1904 /// ID in its debug output, which is confusing. It also doesn't include
1905 /// that strings that match because a regex-automata `Captures` doesn't
1906 /// borrow the haystack.
1907 struct CapturesDebugMap<'a> {
1908 caps: &'a Captures<'a>,
1909 }
1910
1911 impl<'a> core::fmt::Debug for CapturesDebugMap<'a> {
1912 fn fmt(&self, f: &mut core::fmt::Formatter) -> core::fmt::Result {
1913 let mut map = f.debug_map();
1914 let names =
1915 self.caps.caps.group_info().pattern_names(PatternID::ZERO);
1916 for (group_index, maybe_name) in names.enumerate() {
1917 let key = Key(group_index, maybe_name);
1918 match self.caps.get(group_index) {
1919 None => map.entry(&key, &None::<()>),
1920 Some(mat) => map.entry(&key, &Value(mat)),
1921 };
1922 }
1923 map.finish()
1924 }
1925 }
1926
1927 struct Key<'a>(usize, Option<&'a str>);
1928
1929 impl<'a> core::fmt::Debug for Key<'a> {
1930 fn fmt(&self, f: &mut core::fmt::Formatter) -> core::fmt::Result {
1931 write!(f, "{}", self.0)?;
1932 if let Some(name) = self.1 {
1933 write!(f, "/{:?}", name)?;
1934 }
1935 Ok(())
1936 }
1937 }
1938
1939 struct Value<'a>(Match<'a>);
1940
1941 impl<'a> core::fmt::Debug for Value<'a> {
1942 fn fmt(&self, f: &mut core::fmt::Formatter) -> core::fmt::Result {
1943 write!(
1944 f,
1945 "{}..{}/{:?}",
1946 self.0.start(),
1947 self.0.end(),
1948 self.0.as_str()
1949 )
1950 }
1951 }
1952
1953 f.debug_tuple("Captures")
1954 .field(&CapturesDebugMap { caps: self })
1955 .finish()
1956 }
1957}
1958
1959/// Get a matching capture group's haystack substring by index.
1960///
1961/// The haystack substring returned can't outlive the `Captures` object if this
1962/// method is used, because of how `Index` is defined (normally `a[i]` is part
1963/// of `a` and can't outlive it). To work around this limitation, do that, use
1964/// [`Captures::get`] instead.
1965///
1966/// `'h` is the lifetime of the matched haystack, but the lifetime of the
1967/// `&str` returned by this implementation is the lifetime of the `Captures`
1968/// value itself.
1969///
1970/// # Panics
1971///
1972/// If there is no matching group at the given index.
1973impl<'h> core::ops::Index<usize> for Captures<'h> {
1974 type Output = str;
1975
1976 // The lifetime is written out to make it clear that the &str returned
1977 // does NOT have a lifetime equivalent to 'h.
1978 fn index<'a>(&'a self, i: usize) -> &'a str {
1979 self.get(i)
1980 .map(|m| m.as_str())
1981 .unwrap_or_else(|| panic!("no group at index '{}'", i))
1982 }
1983}
1984
1985/// Get a matching capture group's haystack substring by name.
1986///
1987/// The haystack substring returned can't outlive the `Captures` object if this
1988/// method is used, because of how `Index` is defined (normally `a[i]` is part
1989/// of `a` and can't outlive it). To work around this limitation, do that, use
1990/// [`Captures::get`] instead.
1991///
1992/// `'h` is the lifetime of the matched haystack, but the lifetime of the
1993/// `&str` returned by this implementation is the lifetime of the `Captures`
1994/// value itself.
1995///
1996/// `'n` is the lifetime of the group name used to index the `Captures` value.
1997///
1998/// # Panics
1999///
2000/// If there is no matching group at the given name.
2001impl<'h, 'n> core::ops::Index<&'n str> for Captures<'h> {
2002 type Output = str;
2003
2004 fn index<'a>(&'a self, name: &'n str) -> &'a str {
2005 self.name(name)
2006 .map(|m| m.as_str())
2007 .unwrap_or_else(|| panic!("no group named '{}'", name))
2008 }
2009}
2010
2011/// A low level representation of the byte offsets of each capture group.
2012///
2013/// You can think of this as a lower level [`Captures`], where this type does
2014/// not support named capturing groups directly and it does not borrow the
2015/// haystack that these offsets were matched on.
2016///
2017/// Primarily, this type is useful when using the lower level `Regex` APIs such
2018/// as [`Regex::captures_read`], which permits amortizing the allocation in
2019/// which capture match offsets are stored.
2020///
2021/// In order to build a value of this type, you'll need to call the
2022/// [`Regex::capture_locations`] method. The value returned can then be reused
2023/// in subsequent searches for that regex. Using it for other regexes may
2024/// result in a panic or otherwise incorrect results.
2025///
2026/// # Example
2027///
2028/// This example shows how to create and use `CaptureLocations` in a search.
2029///
2030/// ```
2031/// use regex::Regex;
2032///
2033/// let re = Regex::new(r"(?<first>\w+)\s+(?<last>\w+)").unwrap();
2034/// let mut locs = re.capture_locations();
2035/// let m = re.captures_read(&mut locs, "Bruce Springsteen").unwrap();
2036/// assert_eq!(0..17, m.range());
2037/// assert_eq!(Some((0, 17)), locs.get(0));
2038/// assert_eq!(Some((0, 5)), locs.get(1));
2039/// assert_eq!(Some((6, 17)), locs.get(2));
2040///
2041/// // Asking for an invalid capture group always returns None.
2042/// assert_eq!(None, locs.get(3));
2043/// # // literals are too big for 32-bit usize: #1041
2044/// # #[cfg(target_pointer_width = "64")]
2045/// assert_eq!(None, locs.get(34973498648));
2046/// # #[cfg(target_pointer_width = "64")]
2047/// assert_eq!(None, locs.get(9944060567225171988));
2048/// ```
2049#[derive(Clone, Debug)]
2050pub struct CaptureLocations(captures::Captures);
2051
2052/// A type alias for `CaptureLocations` for backwards compatibility.
2053///
2054/// Previously, we exported `CaptureLocations` as `Locations` in an
2055/// undocumented API. To prevent breaking that code (e.g., in `regex-capi`),
2056/// we continue re-exporting the same undocumented API.
2057#[doc(hidden)]
2058pub type Locations = CaptureLocations;
2059
2060impl CaptureLocations {
2061 /// Returns the start and end byte offsets of the capture group at index
2062 /// `i`. This returns `None` if `i` is not a valid capture group or if the
2063 /// capture group did not match.
2064 ///
2065 /// # Example
2066 ///
2067 /// ```
2068 /// use regex::Regex;
2069 ///
2070 /// let re = Regex::new(r"(?<first>\w+)\s+(?<last>\w+)").unwrap();
2071 /// let mut locs = re.capture_locations();
2072 /// re.captures_read(&mut locs, "Bruce Springsteen").unwrap();
2073 /// assert_eq!(Some((0, 17)), locs.get(0));
2074 /// assert_eq!(Some((0, 5)), locs.get(1));
2075 /// assert_eq!(Some((6, 17)), locs.get(2));
2076 /// ```
2077 #[inline]
2078 pub fn get(&self, i: usize) -> Option<(usize, usize)> {
2079 self.0.get_group(i).map(|sp| (sp.start, sp.end))
2080 }
2081
2082 /// Returns the total number of capture groups (even if they didn't match).
2083 /// That is, the length returned is unaffected by the result of a search.
2084 ///
2085 /// This is always at least `1` since every regex has at least `1`
2086 /// capturing group that corresponds to the entire match.
2087 ///
2088 /// # Example
2089 ///
2090 /// ```
2091 /// use regex::Regex;
2092 ///
2093 /// let re = Regex::new(r"(?<first>\w+)\s+(?<last>\w+)").unwrap();
2094 /// let mut locs = re.capture_locations();
2095 /// assert_eq!(3, locs.len());
2096 /// re.captures_read(&mut locs, "Bruce Springsteen").unwrap();
2097 /// assert_eq!(3, locs.len());
2098 /// ```
2099 ///
2100 /// Notice that the length is always at least `1`, regardless of the regex:
2101 ///
2102 /// ```
2103 /// use regex::Regex;
2104 ///
2105 /// let re = Regex::new(r"").unwrap();
2106 /// let locs = re.capture_locations();
2107 /// assert_eq!(1, locs.len());
2108 ///
2109 /// // [a&&b] is a regex that never matches anything.
2110 /// let re = Regex::new(r"[a&&b]").unwrap();
2111 /// let locs = re.capture_locations();
2112 /// assert_eq!(1, locs.len());
2113 /// ```
2114 #[inline]
2115 pub fn len(&self) -> usize {
2116 // self.0.group_len() returns 0 if the underlying captures doesn't
2117 // represent a match, but the behavior guaranteed for this method is
2118 // that the length doesn't change based on a match or not.
2119 self.0.group_info().group_len(PatternID::ZERO)
2120 }
2121
2122 /// An alias for the `get` method for backwards compatibility.
2123 ///
2124 /// Previously, we exported `get` as `pos` in an undocumented API. To
2125 /// prevent breaking that code (e.g., in `regex-capi`), we continue
2126 /// re-exporting the same undocumented API.
2127 #[doc(hidden)]
2128 #[inline]
2129 pub fn pos(&self, i: usize) -> Option<(usize, usize)> {
2130 self.get(i)
2131 }
2132}
2133
2134/// An iterator over all non-overlapping matches in a haystack.
2135///
2136/// This iterator yields [`Match`] values. The iterator stops when no more
2137/// matches can be found.
2138///
2139/// `'r` is the lifetime of the compiled regular expression and `'h` is the
2140/// lifetime of the haystack.
2141///
2142/// This iterator is created by [`Regex::find_iter`].
2143///
2144/// # Time complexity
2145///
2146/// Note that since an iterator runs potentially many searches on the haystack
2147/// and since each search has worst case `O(m * n)` time complexity, the
2148/// overall worst case time complexity for iteration is `O(m * n^2)`.
2149#[derive(Debug)]
2150pub struct Matches<'r, 'h> {
2151 haystack: &'h str,
2152 it: meta::FindMatches<'r, 'h>,
2153}
2154
2155impl<'r, 'h> Iterator for Matches<'r, 'h> {
2156 type Item = Match<'h>;
2157
2158 #[inline]
2159 fn next(&mut self) -> Option<Match<'h>> {
2160 self.it
2161 .next()
2162 .map(|sp| Match::new(self.haystack, sp.start(), sp.end()))
2163 }
2164
2165 #[inline]
2166 fn count(self) -> usize {
2167 // This can actually be up to 2x faster than calling `next()` until
2168 // completion, because counting matches when using a DFA only requires
2169 // finding the end of each match. But returning a `Match` via `next()`
2170 // requires the start of each match which, with a DFA, requires a
2171 // reverse forward scan to find it.
2172 self.it.count()
2173 }
2174}
2175
2176impl<'r, 'h> core::iter::FusedIterator for Matches<'r, 'h> {}
2177
2178/// An iterator over all non-overlapping capture matches in a haystack.
2179///
2180/// This iterator yields [`Captures`] values. The iterator stops when no more
2181/// matches can be found.
2182///
2183/// `'r` is the lifetime of the compiled regular expression and `'h` is the
2184/// lifetime of the matched string.
2185///
2186/// This iterator is created by [`Regex::captures_iter`].
2187///
2188/// # Time complexity
2189///
2190/// Note that since an iterator runs potentially many searches on the haystack
2191/// and since each search has worst case `O(m * n)` time complexity, the
2192/// overall worst case time complexity for iteration is `O(m * n^2)`.
2193#[derive(Debug)]
2194pub struct CaptureMatches<'r, 'h> {
2195 haystack: &'h str,
2196 it: meta::CapturesMatches<'r, 'h>,
2197}
2198
2199impl<'r, 'h> Iterator for CaptureMatches<'r, 'h> {
2200 type Item = Captures<'h>;
2201
2202 #[inline]
2203 fn next(&mut self) -> Option<Captures<'h>> {
2204 let static_captures_len = self.it.regex().static_captures_len();
2205 self.it.next().map(|caps| Captures {
2206 haystack: self.haystack,
2207 caps,
2208 static_captures_len,
2209 })
2210 }
2211
2212 #[inline]
2213 fn count(self) -> usize {
2214 // This can actually be up to 2x faster than calling `next()` until
2215 // completion, because counting matches when using a DFA only requires
2216 // finding the end of each match. But returning a `Match` via `next()`
2217 // requires the start of each match which, with a DFA, requires a
2218 // reverse forward scan to find it.
2219 self.it.count()
2220 }
2221}
2222
2223impl<'r, 'h> core::iter::FusedIterator for CaptureMatches<'r, 'h> {}
2224
2225/// An iterator over all substrings delimited by a regex match.
2226///
2227/// `'r` is the lifetime of the compiled regular expression and `'h` is the
2228/// lifetime of the byte string being split.
2229///
2230/// This iterator is created by [`Regex::split`].
2231///
2232/// # Time complexity
2233///
2234/// Note that since an iterator runs potentially many searches on the haystack
2235/// and since each search has worst case `O(m * n)` time complexity, the
2236/// overall worst case time complexity for iteration is `O(m * n^2)`.
2237#[derive(Debug)]
2238pub struct Split<'r, 'h> {
2239 haystack: &'h str,
2240 it: meta::Split<'r, 'h>,
2241}
2242
2243impl<'r, 'h> Iterator for Split<'r, 'h> {
2244 type Item = &'h str;
2245
2246 #[inline]
2247 fn next(&mut self) -> Option<&'h str> {
2248 self.it.next().map(|span| &self.haystack[span])
2249 }
2250}
2251
2252impl<'r, 'h> core::iter::FusedIterator for Split<'r, 'h> {}
2253
2254/// An iterator over at most `N` substrings delimited by a regex match.
2255///
2256/// The last substring yielded by this iterator will be whatever remains after
2257/// `N-1` splits.
2258///
2259/// `'r` is the lifetime of the compiled regular expression and `'h` is the
2260/// lifetime of the byte string being split.
2261///
2262/// This iterator is created by [`Regex::splitn`].
2263///
2264/// # Time complexity
2265///
2266/// Note that since an iterator runs potentially many searches on the haystack
2267/// and since each search has worst case `O(m * n)` time complexity, the
2268/// overall worst case time complexity for iteration is `O(m * n^2)`.
2269///
2270/// Although note that the worst case time here has an upper bound given
2271/// by the `limit` parameter to [`Regex::splitn`].
2272#[derive(Debug)]
2273pub struct SplitN<'r, 'h> {
2274 haystack: &'h str,
2275 it: meta::SplitN<'r, 'h>,
2276}
2277
2278impl<'r, 'h> Iterator for SplitN<'r, 'h> {
2279 type Item = &'h str;
2280
2281 #[inline]
2282 fn next(&mut self) -> Option<&'h str> {
2283 self.it.next().map(|span| &self.haystack[span])
2284 }
2285
2286 #[inline]
2287 fn size_hint(&self) -> (usize, Option<usize>) {
2288 self.it.size_hint()
2289 }
2290}
2291
2292impl<'r, 'h> core::iter::FusedIterator for SplitN<'r, 'h> {}
2293
2294/// An iterator over the names of all capture groups in a regex.
2295///
2296/// This iterator yields values of type `Option<&str>` in order of the opening
2297/// capture group parenthesis in the regex pattern. `None` is yielded for
2298/// groups with no name. The first element always corresponds to the implicit
2299/// and unnamed group for the overall match.
2300///
2301/// `'r` is the lifetime of the compiled regular expression.
2302///
2303/// This iterator is created by [`Regex::capture_names`].
2304#[derive(Clone, Debug)]
2305pub struct CaptureNames<'r>(captures::GroupInfoPatternNames<'r>);
2306
2307impl<'r> Iterator for CaptureNames<'r> {
2308 type Item = Option<&'r str>;
2309
2310 #[inline]
2311 fn next(&mut self) -> Option<Option<&'r str>> {
2312 self.0.next()
2313 }
2314
2315 #[inline]
2316 fn size_hint(&self) -> (usize, Option<usize>) {
2317 self.0.size_hint()
2318 }
2319
2320 #[inline]
2321 fn count(self) -> usize {
2322 self.0.count()
2323 }
2324}
2325
2326impl<'r> ExactSizeIterator for CaptureNames<'r> {}
2327
2328impl<'r> core::iter::FusedIterator for CaptureNames<'r> {}
2329
2330/// An iterator over all group matches in a [`Captures`] value.
2331///
2332/// This iterator yields values of type `Option<Match<'h>>`, where `'h` is the
2333/// lifetime of the haystack that the matches are for. The order of elements
2334/// yielded corresponds to the order of the opening parenthesis for the group
2335/// in the regex pattern. `None` is yielded for groups that did not participate
2336/// in the match.
2337///
2338/// The first element always corresponds to the implicit group for the overall
2339/// match. Since this iterator is created by a [`Captures`] value, and a
2340/// `Captures` value is only created when a match occurs, it follows that the
2341/// first element yielded by this iterator is guaranteed to be non-`None`.
2342///
2343/// The lifetime `'c` corresponds to the lifetime of the `Captures` value that
2344/// created this iterator, and the lifetime `'h` corresponds to the originally
2345/// matched haystack.
2346#[derive(Clone, Debug)]
2347pub struct SubCaptureMatches<'c, 'h> {
2348 haystack: &'h str,
2349 it: captures::CapturesPatternIter<'c>,
2350}
2351
2352impl<'c, 'h> Iterator for SubCaptureMatches<'c, 'h> {
2353 type Item = Option<Match<'h>>;
2354
2355 #[inline]
2356 fn next(&mut self) -> Option<Option<Match<'h>>> {
2357 self.it.next().map(|group| {
2358 group.map(|sp| Match::new(self.haystack, sp.start, sp.end))
2359 })
2360 }
2361
2362 #[inline]
2363 fn size_hint(&self) -> (usize, Option<usize>) {
2364 self.it.size_hint()
2365 }
2366
2367 #[inline]
2368 fn count(self) -> usize {
2369 self.it.count()
2370 }
2371}
2372
2373impl<'c, 'h> ExactSizeIterator for SubCaptureMatches<'c, 'h> {}
2374
2375impl<'c, 'h> core::iter::FusedIterator for SubCaptureMatches<'c, 'h> {}
2376
2377/// A trait for types that can be used to replace matches in a haystack.
2378///
2379/// In general, users of this crate shouldn't need to implement this trait,
2380/// since implementations are already provided for `&str` along with other
2381/// variants of string types, as well as `FnMut(&Captures) -> String` (or any
2382/// `FnMut(&Captures) -> T` where `T: AsRef<str>`). Those cover most use cases,
2383/// but callers can implement this trait directly if necessary.
2384///
2385/// # Example
2386///
2387/// This example shows a basic implementation of the `Replacer` trait. This
2388/// can be done much more simply using the replacement string interpolation
2389/// support (e.g., `$first $last`), but this approach avoids needing to parse
2390/// the replacement string at all.
2391///
2392/// ```
2393/// use regex::{Captures, Regex, Replacer};
2394///
2395/// struct NameSwapper;
2396///
2397/// impl Replacer for NameSwapper {
2398/// fn replace_append(&mut self, caps: &Captures<'_>, dst: &mut String) {
2399/// dst.push_str(&caps["first"]);
2400/// dst.push_str(" ");
2401/// dst.push_str(&caps["last"]);
2402/// }
2403/// }
2404///
2405/// let re = Regex::new(r"(?<last>[^,\s]+),\s+(?<first>\S+)").unwrap();
2406/// let result = re.replace("Springsteen, Bruce", NameSwapper);
2407/// assert_eq!(result, "Bruce Springsteen");
2408/// ```
2409pub trait Replacer {
2410 /// Appends possibly empty data to `dst` to replace the current match.
2411 ///
2412 /// The current match is represented by `caps`, which is guaranteed to
2413 /// have a match at capture group `0`.
2414 ///
2415 /// For example, a no-op replacement would be `dst.push_str(&caps[0])`.
2416 fn replace_append(&mut self, caps: &Captures<'_>, dst: &mut String);
2417
2418 /// Return a fixed unchanging replacement string.
2419 ///
2420 /// When doing replacements, if access to [`Captures`] is not needed (e.g.,
2421 /// the replacement string does not need `$` expansion), then it can be
2422 /// beneficial to avoid finding sub-captures.
2423 ///
2424 /// In general, this is called once for every call to a replacement routine
2425 /// such as [`Regex::replace_all`].
2426 fn no_expansion<'r>(&'r mut self) -> Option<Cow<'r, str>> {
2427 None
2428 }
2429
2430 /// Returns a type that implements `Replacer`, but that borrows and wraps
2431 /// this `Replacer`.
2432 ///
2433 /// This is useful when you want to take a generic `Replacer` (which might
2434 /// not be cloneable) and use it without consuming it, so it can be used
2435 /// more than once.
2436 ///
2437 /// # Example
2438 ///
2439 /// ```
2440 /// use regex::{Regex, Replacer};
2441 ///
2442 /// fn replace_all_twice<R: Replacer>(
2443 /// re: Regex,
2444 /// src: &str,
2445 /// mut rep: R,
2446 /// ) -> String {
2447 /// let dst = re.replace_all(src, rep.by_ref());
2448 /// let dst = re.replace_all(&dst, rep.by_ref());
2449 /// dst.into_owned()
2450 /// }
2451 /// ```
2452 fn by_ref<'r>(&'r mut self) -> ReplacerRef<'r, Self> {
2453 ReplacerRef(self)
2454 }
2455}
2456
2457impl<'a> Replacer for &'a str {
2458 fn replace_append(&mut self, caps: &Captures<'_>, dst: &mut String) {
2459 caps.expand(*self, dst);
2460 }
2461
2462 fn no_expansion(&mut self) -> Option<Cow<'_, str>> {
2463 no_expansion(self)
2464 }
2465}
2466
2467impl<'a> Replacer for &'a String {
2468 fn replace_append(&mut self, caps: &Captures<'_>, dst: &mut String) {
2469 self.as_str().replace_append(caps, dst)
2470 }
2471
2472 fn no_expansion(&mut self) -> Option<Cow<'_, str>> {
2473 no_expansion(self)
2474 }
2475}
2476
2477impl Replacer for String {
2478 fn replace_append(&mut self, caps: &Captures<'_>, dst: &mut String) {
2479 self.as_str().replace_append(caps, dst)
2480 }
2481
2482 fn no_expansion(&mut self) -> Option<Cow<'_, str>> {
2483 no_expansion(self)
2484 }
2485}
2486
2487impl<'a> Replacer for Cow<'a, str> {
2488 fn replace_append(&mut self, caps: &Captures<'_>, dst: &mut String) {
2489 self.as_ref().replace_append(caps, dst)
2490 }
2491
2492 fn no_expansion(&mut self) -> Option<Cow<'_, str>> {
2493 no_expansion(self)
2494 }
2495}
2496
2497impl<'a> Replacer for &'a Cow<'a, str> {
2498 fn replace_append(&mut self, caps: &Captures<'_>, dst: &mut String) {
2499 self.as_ref().replace_append(caps, dst)
2500 }
2501
2502 fn no_expansion(&mut self) -> Option<Cow<'_, str>> {
2503 no_expansion(self)
2504 }
2505}
2506
2507impl<F, T> Replacer for F
2508where
2509 F: FnMut(&Captures<'_>) -> T,
2510 T: AsRef<str>,
2511{
2512 fn replace_append(&mut self, caps: &Captures<'_>, dst: &mut String) {
2513 dst.push_str((*self)(caps).as_ref());
2514 }
2515}
2516
2517/// A by-reference adaptor for a [`Replacer`].
2518///
2519/// This permits reusing the same `Replacer` value in multiple calls to a
2520/// replacement routine like [`Regex::replace_all`].
2521///
2522/// This type is created by [`Replacer::by_ref`].
2523#[derive(Debug)]
2524pub struct ReplacerRef<'a, R: ?Sized>(&'a mut R);
2525
2526impl<'a, R: Replacer + ?Sized + 'a> Replacer for ReplacerRef<'a, R> {
2527 fn replace_append(&mut self, caps: &Captures<'_>, dst: &mut String) {
2528 self.0.replace_append(caps, dst)
2529 }
2530
2531 fn no_expansion(&mut self) -> Option<Cow<'_, str>> {
2532 self.0.no_expansion()
2533 }
2534}
2535
2536/// A helper type for forcing literal string replacement.
2537///
2538/// It can be used with routines like [`Regex::replace`] and
2539/// [`Regex::replace_all`] to do a literal string replacement without expanding
2540/// `$name` to their corresponding capture groups. This can be both convenient
2541/// (to avoid escaping `$`, for example) and faster (since capture groups
2542/// don't need to be found).
2543///
2544/// `'s` is the lifetime of the literal string to use.
2545///
2546/// # Example
2547///
2548/// ```
2549/// use regex::{NoExpand, Regex};
2550///
2551/// let re = Regex::new(r"(?<last>[^,\s]+),\s+(\S+)").unwrap();
2552/// let result = re.replace("Springsteen, Bruce", NoExpand("$2 $last"));
2553/// assert_eq!(result, "$2 $last");
2554/// ```
2555#[derive(Clone, Debug)]
2556pub struct NoExpand<'s>(pub &'s str);
2557
2558impl<'s> Replacer for NoExpand<'s> {
2559 fn replace_append(&mut self, _: &Captures<'_>, dst: &mut String) {
2560 dst.push_str(self.0);
2561 }
2562
2563 fn no_expansion(&mut self) -> Option<Cow<'_, str>> {
2564 Some(Cow::Borrowed(self.0))
2565 }
2566}
2567
2568/// Quickly checks the given replacement string for whether interpolation
2569/// should be done on it. It returns `None` if a `$` was found anywhere in the
2570/// given string, which suggests interpolation needs to be done. But if there's
2571/// no `$` anywhere, then interpolation definitely does not need to be done. In
2572/// that case, the given string is returned as a borrowed `Cow`.
2573///
2574/// This is meant to be used to implement the `Replacer::no_expandsion` method
2575/// in its various trait impls.
2576fn no_expansion<T: AsRef<str>>(replacement: &T) -> Option<Cow<'_, str>> {
2577 let replacement = replacement.as_ref();
2578 match crate::find_byte::find_byte(b'$', replacement.as_bytes()) {
2579 Some(_) => None,
2580 None => Some(Cow::Borrowed(replacement)),
2581 }
2582}
2583