Add SubCaptureMatches iterator on Captures.

Author: BurntSushi

src/lib.rs

@@ -463,7 +463,7 @@ pub use re_set::unicode::*;
 pub use re_trait::Locations;
 pub use re_unicode::{
     Regex, Match, Captures,
-    CaptureNames, Matches, CaptureMatches,
+    CaptureNames, Matches, CaptureMatches, SubCaptureMatches,
     Replacer, NoExpand, Split, SplitN,
     escape,
 };

src/re_bytes.rs

@@ -21,7 +21,7 @@ use exec::{Exec, ExecNoSync};
 use expand::expand_bytes;
 use error::Error;
 use re_builder::bytes::RegexBuilder;
-use re_trait::{self, RegularExpression, Locations};
+use re_trait::{self, RegularExpression, Locations, SubCapturesPosIter};
 
 /// Match represents a single match of a regex in a haystack.
 ///
@@ -789,6 +789,18 @@ impl<'t> Captures<'t> {
         self.named_groups.get(name).and_then(|&i| self.get(i))
     }
 
+    /// An iterator that yields all capturing matches in the order in which
+    /// they appear in the regex. If a particular capture group didn't
+    /// participate in the match, then `None` is yielded for that capture.
+    ///
+    /// The first match always corresponds to the overall match of the regex.
+    pub fn iter<'c>(&'c self) -> SubCaptureMatches<'c, 't> {
+        SubCaptureMatches {
+            caps: self,
+            it: self.locs.iter(),
+        }
+    }
+
     /// Expands all instances of `$name` in `text` to the corresponding capture
     /// group `name`, and writes them to the `dst` buffer given.
     ///
@@ -902,6 +914,29 @@ impl<'t, 'i> Index<&'i str> for Captures<'t> {
     }
 }
 
+/// An iterator that yields all capturing matches in the order in which they
+/// appear in the regex.
+///
+/// If a particular capture group didn't participate in the match, then `None`
+/// is yielded for that capture. The first match always corresponds to the
+/// overall match of the regex.
+///
+/// The lifetime `'c` corresponds to the lifetime of the `Captures` value, and
+/// the lifetime `'t` corresponds to the originally matched text.
+pub struct SubCaptureMatches<'c, 't: 'c> {
+    caps: &'c Captures<'t>,
+    it: SubCapturesPosIter<'c>,
+}
+
+impl<'c, 't> Iterator for SubCaptureMatches<'c, 't> {
+    type Item = Option<Match<'t>>;
+
+    fn next(&mut self) -> Option<Option<Match<'t>>> {
+        self.it.next()
+            .map(|cap| cap.map(|(s, e)| Match::new(self.caps.text, s, e)))
+    }
+}
+
 /// Replacer describes types that can be used to replace matches in a byte
 /// string.
 ///

src/re_unicode.rs

@@ -23,7 +23,7 @@ use exec::{Exec, ExecNoSyncStr};
 use expand::expand_str;
 use re_builder::unicode::RegexBuilder;
 use re_plugin::Plugin;
-use re_trait::{self, RegularExpression, Locations};
+use re_trait::{self, RegularExpression, Locations, SubCapturesPosIter};
 
 /// Escapes all regular expression meta characters in `text`.
 ///
@@ -927,6 +927,18 @@ impl<'t> Captures<'t> {
         self.named_groups.pos(name).and_then(|i| self.get(i))
     }
 
+    /// An iterator that yields all capturing matches in the order in which
+    /// they appear in the regex. If a particular capture group didn't
+    /// participate in the match, then `None` is yielded for that capture.
+    ///
+    /// The first match always corresponds to the overall match of the regex.
+    pub fn iter<'c>(&'c self) -> SubCaptureMatches<'c, 't> {
+        SubCaptureMatches {
+            caps: self,
+            it: self.locs.iter(),
+        }
+    }
+
     /// Expands all instances of `$name` in `text` to the corresponding capture
     /// group `name`, and writes them to the `dst` buffer given.
     ///
@@ -1025,6 +1037,29 @@ impl<'t, 'i> Index<&'i str> for Captures<'t> {
     }
 }
 
+/// An iterator that yields all capturing matches in the order in which they
+/// appear in the regex.
+///
+/// If a particular capture group didn't participate in the match, then `None`
+/// is yielded for that capture. The first match always corresponds to the
+/// overall match of the regex.
+///
+/// The lifetime `'c` corresponds to the lifetime of the `Captures` value, and
+/// the lifetime `'t` corresponds to the originally matched text.
+pub struct SubCaptureMatches<'c, 't: 'c> {
+    caps: &'c Captures<'t>,
+    it: SubCapturesPosIter<'c>,
+}
+
+impl<'c, 't> Iterator for SubCaptureMatches<'c, 't> {
+    type Item = Option<Match<'t>>;
+
+    fn next(&mut self) -> Option<Option<Match<'t>>> {
+        self.it.next()
+            .map(|cap| cap.map(|(s, e)| Match::new(self.caps.text, s, e)))
+    }
+}
+
 /// An iterator that yields all non-overlapping capture groups matching a
 /// particular regular expression.
 ///

tests/api.rs

@@ -140,6 +140,25 @@ fn capture_misc() {
     assert_eq!(t!("c"), match_text!(cap.name("b").unwrap()));
 }
 
+#[test]
+fn sub_capture_matches() {
+    let re = regex!(r"([a-z])(([a-z])|([0-9]))");
+    let cap = re.captures(t!("a5")).unwrap();
+    let subs: Vec<_> = cap.iter().collect();
+
+    assert_eq!(5, subs.len());
+    assert!(subs[0].is_some());
+    assert!(subs[1].is_some());
+    assert!(subs[2].is_some());
+    assert!(subs[3].is_none());
+    assert!(subs[4].is_some());
+
+    assert_eq!(t!("a5"), match_text!(subs[0].unwrap()));
+    assert_eq!(t!("a"), match_text!(subs[1].unwrap()));
+    assert_eq!(t!("5"), match_text!(subs[2].unwrap()));
+    assert_eq!(t!("5"), match_text!(subs[4].unwrap()));
+}
+
 expand!(expand1, r"(?P<foo>\w+)", "abc", "$foo", "abc");
 expand!(expand2, r"(?P<foo>\w+)", "abc", "$0", "abc");
 expand!(expand3, r"(?P<foo>\w+)", "abc", "$1", "abc");