regex: add Captures::as_match method

To simplify getting the whole match from `Captures` without needing to
write `unwrap()`.

Fixes #1146, Closes #1227

Author: tmccombs

CHANGELOG.md

@@ -1,7 +1,12 @@
-1.11.4 (TBD)
+1.12.0 (TBD)
 ============
 TODO
 
+Improvements:
+
+* [FEATURE #1146](https://github.com/rust-lang/regex/issues/1146):
+Add `Capture::get_match` for returning the overall match without `unwrap()`.
+
 Bug fixes:
 
 * [BUG #1116](https://github.com/rust-lang/regex/issues/1116):

src/regex/bytes.rs

@@ -1665,6 +1665,26 @@ impl<'h> Captures<'h> {
             .map(|sp| Match::new(self.haystack, sp.start, sp.end))
     }
 
+    /// Return the overall match for the capture.
+    ///
+    /// This returns the match for index `0`. That is it is equivalent to
+    /// `m.get(0).unwrap()`
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use regex::bytes::Regex;
+    ///
+    /// let re = Regex::new(r"[a-z]+([0-9]+)").unwrap();
+    /// let caps = re.captures(b"   abc123-def").unwrap();
+    ///
+    /// assert_eq!(caps.get_match().as_bytes(), b"abc123");
+    /// ```
+    #[inline]
+    pub fn get_match(&self) -> Match {
+        self.get(0).unwrap()
+    }
+
     /// Returns the `Match` associated with the capture group named `name`. If
     /// `name` isn't a valid capture group or it refers to a group that didn't
     /// match, then `None` is returned.

src/regex/string.rs

@@ -1675,6 +1675,27 @@ impl<'h> Captures<'h> {
             .map(|sp| Match::new(self.haystack, sp.start, sp.end))
     }
 
+    /// Return the overall match for the capture.
+    ///
+    /// This returns the match for index `0`. That is it is equivalent to
+    /// `m.get(0).unwrap()`
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use regex::Regex;
+    ///
+    /// let re = Regex::new(r"[a-z]+([0-9]+)").unwrap();
+    /// let caps = re.captures("   abc123-def").unwrap();
+    ///
+    /// assert_eq!(caps.get_match().as_str(), "abc123");
+    ///
+    /// ```
+    #[inline]
+    pub fn get_match(&self) -> Match {
+        self.get(0).unwrap()
+    }
+
     /// Returns the `Match` associated with the capture group named `name`. If
     /// `name` isn't a valid capture group or it refers to a group that didn't
     /// match, then `None` is returned.