From b074bc3d614cd4e783dc77e3602c424110230495 Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Mon, 18 Apr 2022 13:02:35 -0500 Subject: [PATCH] [DOC] Enhanced RDoc for MatchData (#5819) Treats: #begin #end #match #match_length --- doc/matchdata/begin.rdoc | 30 ++++++++++++++ doc/matchdata/end.rdoc | 30 ++++++++++++++ doc/matchdata/offset.rdoc | 1 - re.c | 86 ++++++++++++++++++++------------------- 4 files changed, 104 insertions(+), 43 deletions(-) create mode 100644 doc/matchdata/begin.rdoc create mode 100644 doc/matchdata/end.rdoc diff --git a/doc/matchdata/begin.rdoc b/doc/matchdata/begin.rdoc new file mode 100644 index 0000000000..8046dd9d55 --- /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 nth match: + + m = /(.)(.)(\d+)(\d)/.match("THX1138.") + # => # + m[0] # => "HX1138" + m.begin(0) # => 1 + m[3] # => "113" + m.begin(3) # => 3 + + m = /(т)(е)(с)/.match('тест') + # => # + m[0] # => "тес" + m.begin(0) # => 0 + m[3] # => "с" + m.begin(3) # => 2 + +When string or symbol argument +name+ is given, +returns the offset of the beginning for the named match: + + m = /(?.)(.)(?.)/.match("hoge") + # => # + 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/end.rdoc b/doc/matchdata/end.rdoc new file mode 100644 index 0000000000..0209b2d2fc --- /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 nth match: + + m = /(.)(.)(\d+)(\d)/.match("THX1138.") + # => # + m[0] # => "HX1138" + m.end(0) # => 7 + m[3] # => "113" + m.end(3) # => 6 + + m = /(т)(е)(с)/.match('тест') + # => # + m[0] # => "тес" + m.end(0) # => 3 + m[3] # => "с" + m.end(3) # => 3 + +When string or symbol argument +name+ is given, +returns the offset of the end for the named match: + + m = /(?.)(.)(?.)/.match("hoge") + # => # + 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 index bbf157548a..0985316d76 100644 --- a/doc/matchdata/offset.rdoc +++ b/doc/matchdata/offset.rdoc @@ -29,4 +29,3 @@ returns the starting and ending offsets for the named match: m.offset(:bar) # => [2, 3] Related: MatchData#byteoffset, MatchData#begin, MatchData#end. - diff --git a/re.c b/re.c index 0b4dfe6446..4b9f2a3849 100644 --- a/re.c +++ b/re.c @@ -1287,19 +1287,11 @@ match_byteoffset(VALUE match, VALUE n) /* * call-seq: - * mtch.begin(n) -> integer + * begin(n) -> integer + * begin(name) -> integer * - * Returns the offset of the start of the nth element of the match - * array in the string. - * n can be a string or symbol to reference a named capture. + * :include: doc/matchdata/begin.rdoc * - * m = /(.)(.)(\d+)(\d)/.match("THX1138.") - * m.begin(0) #=> 1 - * m.begin(2) #=> 2 - * - * m = /(?.)(.)(?.)/.match("hoge") - * p m.begin(:foo) #=> 0 - * p m.begin(:bar) #=> 2 */ static VALUE @@ -1321,19 +1313,11 @@ match_begin(VALUE match, VALUE n) /* * call-seq: - * mtch.end(n) -> integer + * end(n) -> integer + * end(name) -> integer * - * Returns the offset of the character immediately following the end of the - * nth element of the match array in the string. - * n can be a string or symbol to reference a named capture. + * :include: doc/matchdata/end.rdoc * - * m = /(.)(.)(\d+)(\d)/.match("THX1138.") - * m.end(0) #=> 7 - * m.end(2) #=> 3 - * - * m = /(?.)(.)(?.)/.match("hoge") - * p m.end(:foo) #=> 1 - * p m.end(:bar) #=> 3 */ static VALUE @@ -1354,19 +1338,26 @@ match_end(VALUE match, VALUE n) /* * call-seq: - * mtch.match(n) -> string or nil + * match(n) -> string or nil + * match(name) -> string or nil * - * Returns the captured substring corresponding to the argument. - * n can be a string or symbol to reference a named capture. + * Returns the matched substring corresponding to the given argument. * - * m = /(.)(.)(\d+)(\d)(\w)?/.match("THX1138.") - * m.match(0) #=> "HX1138" - * m.match(4) #=> "8" - * m.match(5) #=> nil + * When non-negative argument +n+ is given, + * returns the matched substring for the nth match: * - * m = /(?.)(.)(?.+)/.match("hoge") - * m.match(:foo) #=> "h" - * m.match(:bar) #=> "ge" + * m = /(.)(.)(\d+)(\d)(\w)?/.match("THX1138.") + * # => # + * m.match(0) # => "HX1138" + * m.match(4) # => "8" + * m.match(5) # => nil + * + * When string or symbol argument +name+ is given, + * returns the matched substring for the given name: + * + * m = /(?.)(.)(?.+)/.match("hoge") + * m.match('foo') # => "h" + * m.match(:bar) # => "ge" * */ @@ -1387,19 +1378,30 @@ match_nth(VALUE match, VALUE n) /* * call-seq: - * mtch.match_length(n) -> array + * match_length(n) -> integer or nil + * match_length(name) -> integer or nil * - * Returns the length of the captured substring corresponding to the argument. - * n can be a string or symbol to reference a named capture. + * Returns the length (in characters) of the matched substring + * corresponding to the given argument. * - * m = /(.)(.)(\d+)(\d)(\w)?/.match("THX1138.") - * m.match_length(0) #=> 6 - * m.match_length(4) #=> 1 - * m.match_length(5) #=> nil + * When non-negative argument +n+ is given, + * returns the length of the matched substring + * for the nth match: * - * m = /(?.)(.)(?.+)/.match("hoge") - * m.match_length(:foo) #=> 1 - * m.match_length(:bar) #=> 2 + * m = /(.)(.)(\d+)(\d)(\w)?/.match("THX1138.") + * # => # + * m.match_length(0) # => 6 + * m.match_length(4) # => 1 + * m.match_length(5) # => nil + * + * When string or symbol argument +name+ is given, + * returns the length of the matched substring + * for the named match: + * + * m = /(?.)(.)(?.+)/.match("hoge") + * # => # + * m.match_length('foo') # => 1 + * m.match_length(:bar) # => 2 * */