@@ -427,12 +427,23 @@ impl Regex {
427427/// Note that using `$2` instead of `$first` or `$1` instead of `$last`
428428/// would produce the same result. To write a literal `$` use `$$`.
429429///
430- /// If `$name` isn't a valid capture group (whether the name doesn't exist
431- /// or isn't a valid index), then it is replaced with the empty string.
430+ /// Sometimes the replacement string requires use of curly braces to
431+ /// delineate a capture group replacement and surrounding literal text.
432+ /// For example, if we wanted to join two words together with an
433+ /// underscore:
432434///
433- /// The longest possible name is used. e.g., `$1a` looks up the capture
434- /// group named `1a` and not the capture group at index `1`. To exert more
435- /// precise control over the name, use braces, e.g., `${1}a`.
435+ /// ```rust
436+ /// # extern crate regex; use regex::bytes::Regex;
437+ /// # fn main() {
438+ /// let re = Regex::new(r"(?P<first>\w+)\s+(?P<second>\w+)").unwrap();
439+ /// let result = re.replace(b"deep fried", &b"${first}_$second"[..]);
440+ /// assert_eq!(result, &b"deep_fried"[..]);
441+ /// # }
442+ /// ```
443+ ///
444+ /// Without the curly braces, the capture group name `first_` would be
445+ /// used, and since it doesn't exist, it would be replaced with the empty
446+ /// string.
436447///
437448/// Finally, sometimes you just want to replace a literal string with no
438449/// regard for capturing group expansion. This can be done by wrapping a
@@ -778,6 +789,22 @@ impl<'t> Captures<'t> {
778789 /// Returns the match associated with the capture group at index `i`. If
779790/// `i` does not correspond to a capture group, or if the capture group
780791/// did not participate in the match, then `None` is returned.
792+ ///
793+ /// # Examples
794+ ///
795+ /// Get the text of the match with a default of an empty string if this
796+ /// group didn't participate in the match:
797+ ///
798+ /// ```rust
799+ /// # use regex::bytes::Regex;
800+ /// let re = Regex::new(r"[a-z]+(?:([0-9]+)|([A-Z]+))").unwrap();
801+ /// let caps = re.captures(b"abc123").unwrap();
802+ ///
803+ /// let text1 = caps.get(1).map_or(&b""[..], |m| m.as_bytes());
804+ /// let text2 = caps.get(2).map_or(&b""[..], |m| m.as_bytes());
805+ /// assert_eq!(text1, &b"123"[..]);
806+ /// assert_eq!(text2, &b""[..]);
807+ /// ```
781808pub fn get ( & self , i : usize ) -> Option < Match < ' t > > {
782809 self . locs . pos ( i) . map ( |( s, e) | Match :: new ( self . text , s, e) )
783810 }
0 commit comments