[DOC] Enhanced RDoc for MatchData (#5818)

Treats:
    #regexp
    #names
    #size
    #offset

1 files changed, 32 insertions, 0 deletions

diff --git a/doc/matchdata/offset.rdoc b/doc/matchdata/offset.rdoc
new file mode 100644
index 0000000000..bbf157548a
--- /dev/null
+++ b/doc/matchdata/offset.rdoc
@@ -0,0 +1,32 @@
+Returns a 2-element array containing the beginning and ending
+offsets (in characters) of the specified match.
+
+When non-negative integer argument +n+ is given,
+returns the starting and ending offsets of the <tt>n</tt>th match:
+
+  m = /(.)(.)(\d+)(\d)/.match("THX1138.")
+  # => #<MatchData "HX1138" 1:"H" 2:"X" 3:"113" 4:"8">
+  m[0]        # => "HX1138"
+  m.offset(0) # => [1, 7]
+  m[3]        # => "113"
+  m.offset(3) # => [3, 6]
+
+  m = /(т)(е)(с)/.match('тест')
+  # => #<MatchData "тес" 1:"т" 2:"е" 3:"с">
+  m[0]        # => "тес"
+  m.offset(0) # => [0, 3]
+  m[3]        # => "с"
+  m.offset(3) # => [2, 3]
+
+When string or symbol argument +name+ is given,
+returns the starting and ending offsets for the named match:
+
+  m = /(?<foo>.)(.)(?<bar>.)/.match("hoge")
+  # => #<MatchData "hog" foo:"h" bar:"g">
+  m[:foo]         # => "h"
+  m.offset('foo') # => [0, 1]
+  m[:bar]         # => "g"
+  m.offset(:bar)  # => [2, 3]
+
+Related: MatchData#byteoffset, MatchData#begin, MatchData#end.
+