5 files changed, 151 insertions, 0 deletions
diff --git a/doc/matchdata/begin.rdoc b/doc/matchdata/begin.rdoc
new file mode 100644
index 0000000000..6100617e19
--- /dev/null
+++ b/doc/matchdata/begin.rdoc
@@ -0,0 +1,30 @@
+Returns the offset (in characters) of the beginning of the specified match.
+
+When non-negative integer argument +n+ is given,
+returns the offset of the beginning 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.begin(0) # => 1
+  m[3]       # => "113"
+  m.begin(3) # => 3
+
+  m = /(ん)(に)(ち)/.match('こんにちは')
+  # => #<MatchData "んにち" 1:"ん" 2:"に" 3:"ち">
+  m[0]       # => "んにち"
+  m.begin(0) # => 1
+  m[3]       # => "ち"
+  m.begin(3) # => 3
+
+When string or symbol argument +name+ is given,
+returns the offset of the beginning for the named match:
+
+  m = /(?<foo>.)(.)(?<bar>.)/.match("hoge")
+  # => #<MatchData "hog" foo:"h" bar:"g">
+  m[:foo]        # => "h"
+  m.begin('foo') # => 0
+  m[:bar]        # => "g"
+  m.begin(:bar)  # => 2
+
+Related: MatchData#end, MatchData#offset, MatchData#byteoffset.
diff --git a/doc/matchdata/bytebegin.rdoc b/doc/matchdata/bytebegin.rdoc
new file mode 100644
index 0000000000..54e417a7fc
--- /dev/null
+++ b/doc/matchdata/bytebegin.rdoc
@@ -0,0 +1,30 @@
+Returns the offset (in bytes) of the beginning of the specified match.
+
+When non-negative integer argument +n+ is given,
+returns the offset of the beginning 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.bytebegin(0) # => 1
+  m[3]       # => "113"
+  m.bytebegin(3) # => 3
+
+  m = /(ん)(に)(ち)/.match('こんにちは')
+  # => #<MatchData "んにち" 1:"ん" 2:"に" 3:"ち">
+  m[0]           # => "んにち"
+  m.bytebegin(0) # => 3
+  m[3]           # => "ち"
+  m.bytebegin(3) # => 9
+
+When string or symbol argument +name+ is given,
+returns the offset of the beginning for the named match:
+
+  m = /(?<foo>.)(.)(?<bar>.)/.match("hoge")
+  # => #<MatchData "hog" foo:"h" bar:"g">
+  m[:foo]        # => "h"
+  m.bytebegin('foo') # => 0
+  m[:bar]        # => "g"
+  m.bytebegin(:bar)  # => 2
+
+Related: MatchData#byteend, MatchData#byteoffset.
diff --git a/doc/matchdata/byteend.rdoc b/doc/matchdata/byteend.rdoc
new file mode 100644
index 0000000000..0a03f76208
--- /dev/null
+++ b/doc/matchdata/byteend.rdoc
@@ -0,0 +1,30 @@
+Returns the offset (in bytes) of the end of the specified match.
+
+When non-negative integer argument +n+ is given,
+returns the offset of the end 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.byteend(0) # => 7
+  m[3]     # => "113"
+  m.byteend(3) # => 6
+
+  m = /(ん)(に)(ち)/.match('こんにちは')
+  # => #<MatchData "んにち" 1:"ん" 2:"に" 3:"ち">
+  m[0]         # => "んにち"
+  m.byteend(0) # => 12
+  m[3]         # => "ち"
+  m.byteend(3) # => 12
+
+When string or symbol argument +name+ is given,
+returns the offset of the end for the named match:
+
+  m = /(?<foo>.)(.)(?<bar>.)/.match("hoge")
+  # => #<MatchData "hog" foo:"h" bar:"g">
+  m[:foo]      # => "h"
+  m.byteend('foo') # => 1
+  m[:bar]      # => "g"
+  m.byteend(:bar)  # => 3
+
+Related: MatchData#bytebegin, MatchData#byteoffset.
diff --git a/doc/matchdata/end.rdoc b/doc/matchdata/end.rdoc
new file mode 100644
index 0000000000..c43a5428f3
--- /dev/null
+++ b/doc/matchdata/end.rdoc
@@ -0,0 +1,30 @@
+Returns the offset (in characters) of the end of the specified match.
+
+When non-negative integer argument +n+ is given,
+returns the offset of the end 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.end(0) # => 7
+  m[3]     # => "113"
+  m.end(3) # => 6
+
+  m = /(ん)(に)(ち)/.match('こんにちは')
+  # => #<MatchData "んにち" 1:"ん" 2:"に" 3:"ち">
+  m[0]     # => "んにち"
+  m.end(0) # => 4
+  m[3]     # => "ち"
+  m.end(3) # => 4
+
+When string or symbol argument +name+ is given,
+returns the offset of the end for the named match:
+
+  m = /(?<foo>.)(.)(?<bar>.)/.match("hoge")
+  # => #<MatchData "hog" foo:"h" bar:"g">
+  m[:foo]      # => "h"
+  m.end('foo') # => 1
+  m[:bar]      # => "g"
+  m.end(:bar)  # => 3
+
+Related: MatchData#begin, MatchData#offset, MatchData#byteoffset.
diff --git a/doc/matchdata/offset.rdoc b/doc/matchdata/offset.rdoc
new file mode 100644
index 0000000000..4194ef7ef9
--- /dev/null
+++ b/doc/matchdata/offset.rdoc
@@ -0,0 +1,31 @@
+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) # => [1, 4]
+  m[3]        # => "ち"
+  m.offset(3) # => [3, 4]
+
+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.