AS guide: documents Regexp#number_of_captures

1 files changed, 26 insertions, 0 deletions

diff --git a/railties/guides/source/active_support_overview.textile b/railties/guides/source/active_support_overview.textile
index 8e53672abd..89c959c49f 100644
--- a/railties/guides/source/active_support_overview.textile
+++ b/railties/guides/source/active_support_overview.textile
@@ -1547,6 +1547,32 @@ The method +with_indifferent_access+ returns an +ActiveSupport::HashWithIndiffer
 {:a => 1}.with_indifferent_access["a"] # => 1
 </ruby>
 
+h3. Extensions to +Regexp+
+
+h4. +number_of_captures+
+
+The method +number_of_captures+ returns the number of capturing groups in a given regexp:
+
+<ruby>
+%r{}.number_of_captures                   # => 0
+%r{.(.).}.number_of_captures              # => 1
+%r{\A((#)(\w+|\s+))\z}.number_of_captures # => 3
+</ruby>
+
+Routing code for example uses that method to generate path recognizers:
+
+<ruby>
+def recognition_extraction
+  next_capture = 1
+  extraction = segments.collect do |segment|
+    x = segment.match_extraction(next_capture)
+    next_capture += segment.number_of_captures
+    x
+  end
+  extraction.compact
+end
+</ruby>
+
 h3. Extensions to +Range+
 
 ...