From 26e4efddd31e168b9cb644411ced89f0df6cdf53 Mon Sep 17 00:00:00 2001
From: Danny McClanahan <1305167+cosmicexplorer@users.noreply.github.com>
Date: Fri, 20 May 2022 05:41:14 -0400
Subject: [PATCH] doc: add a doctest to demonstrate a separately-compiled regex
 set

---
 src/re_set.rs | 33 +++++++++++++++++++++++++++++----
 1 file changed, 29 insertions(+), 4 deletions(-)

diff --git a/src/re_set.rs b/src/re_set.rs
index 73d59532e..3a82741f1 100644
--- a/src/re_set.rs
+++ b/src/re_set.rs
@@ -62,10 +62,35 @@ $(#[$doc_regexset_example])*
 /// As with the main `Regex` type, it is cheaper to ask (1) instead of (2)
 /// since the matching engines can stop after the first match is found.
 ///
-/// Other features like finding the location of successive matches or their
-/// sub-captures aren't supported. If you need this functionality, the
-/// recommended approach is to compile each regex in the set independently and
-/// selectively match them based on which regexes in the set matched.
+/// Other features like finding match locations or capture groups
+/// aren't supported. If you need this functionality, the
+/// recommended approach is to compile each pattern in the set independently and
+/// scan the exact same input a second time with those independently compiled
+/// patterns:
+/// ```rust
+/// # use regex::{Regex, RegexSet};
+/// let patterns = ["foo", "bar"];
+/// // Both patterns will match different ranges of this string.
+/// let text = "barfoo";
+///
+/// // Compile a set matching any of our patterns.
+/// let set = RegexSet::new(&patterns).unwrap();
+/// // Compile each pattern independently.
+/// let regexen: Vec<_> = patterns.iter().map(|pat| Regex::new(pat).unwrap()).collect();
+///
+/// // Match against the whole set first and identify the individual matching patterns.
+/// let matches: Vec<&str> = set.matches(text).into_iter()
+///     // Dereference the match index to get the corresponding compiled pattern.
+///     .map(|match_idx| &regexen[match_idx])
+///     // To get match locations or any other info, we then have to search
+///     // the exact same text again, using our separately-compiled pattern.
+///     .map(|pat| pat.find(text).unwrap().as_str())
+///     .collect();
+///
+/// // Matches arrive in the order the constituent patterns were declared,
+/// // not the order they appear in the input.
+/// assert_eq!(["foo", "bar"].as_ref(), &matches);
+/// ```
 ///
 /// # Performance
 ///