diff options
author | Burdette Lamar <BurdetteLamar@Yahoo.com> | 2022-04-18 11:31:30 -0500 |
---|---|---|
committer | GitHub <noreply@github.com> | 2022-04-18 11:31:30 -0500 |
commit | 9d1dd7a9ed189475730254fbfee52f890759afaf (patch) | |
tree | 30a0ef20d0de75df701d9ae949dc6ba92f528482 | |
parent | 96b2b0ee65edb9d5910b1a1bb63cc8a12feac8f4 (diff) | |
download | ruby-9d1dd7a9ed189475730254fbfee52f890759afaf.tar.gz |
[DOC] Enhanced RDoc for MatchData (#5818)
Treats:
#regexp
#names
#size
#offset
-rw-r--r-- | doc/matchdata/offset.rdoc | 32 | ||||
-rw-r--r-- | re.c | 63 |
2 files changed, 64 insertions, 31 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. + @@ -1101,13 +1101,14 @@ match_init_copy(VALUE obj, VALUE orig) /* - * call-seq: - * mtch.regexp -> regexp + * call-seq: + * regexp -> regexp + * + * Returns the regexp that produced the match: * - * Returns the regexp. + * m = /a.*b/.match("abc") # => #<MatchData "ab"> + * m.regexp # => /a.*b/ * - * m = /a.*b/.match("abc") - * m.regexp #=> /a.*b/ */ static VALUE @@ -1125,17 +1126,24 @@ match_regexp(VALUE match) } /* - * call-seq: - * mtch.names -> [name1, name2, ...] + * call-seq: + * names -> array_of_names + * + * Returns an array of the capture names + * (see {Named Captures}[rdoc-ref:Regexp@Named+Captures]): + * + * m = /(?<foo>.)(?<bar>.)(?<baz>.)/.match("hoge") + * # => #<MatchData "hog" foo:"h" bar:"o" baz:"g"> + * m.names # => ["foo", "bar", "baz"] + * + * m = /foo/.match('foo') # => #<MatchData "foo"> + * m.names # => [] # No named captures. * - * Returns a list of names of captures as an array of strings. - * This is the same as mtch.regexp.names. + * Equivalent to: * - * /(?<foo>.)(?<bar>.)(?<baz>.)/.match("hoge").names - * #=> ["foo", "bar", "baz"] + * m = /(?<foo>.)(?<bar>.)(?<baz>.)/.match("hoge") + * m.regexp.names # => ["foo", "bar", "baz"] * - * m = /(?<x>.)(?<y>.)?/.match("a") #=> #<MatchData "a" x:"a" y:nil> - * m.names #=> ["x", "y"] */ static VALUE @@ -1149,14 +1157,16 @@ match_names(VALUE match) /* * call-seq: - * mtch.length -> integer - * mtch.size -> integer + * size -> integer * - * Returns the number of elements in the match array. + * Returns size of the match array: + * + * m = /(.)(.)(\d+)(\d)/.match("THX1138.") + * # => #<MatchData "HX1138" 1:"H" 2:"X" 3:"113" 4:"8"> + * m.size # => 5 + * + * MatchData#length is an alias for MatchData.size. * - * m = /(.)(.)(\d+)(\d)/.match("THX1138.") - * m.length #=> 5 - * m.size #=> 5 */ static VALUE @@ -1218,19 +1228,10 @@ rb_reg_backref_number(VALUE match, VALUE backref) /* * call-seq: - * mtch.offset(n) -> array + * offset(n) -> [start_offset, end_offset] + * offset(name) -> [start_offset, end_offset] * - * Returns a two-element array containing the beginning and ending offsets of - * the <em>n</em>th match. - * <em>n</em> can be a string or symbol to reference a named capture. - * - * m = /(.)(.)(\d+)(\d)/.match("THX1138.") - * m.offset(0) #=> [1, 7] - * m.offset(4) #=> [6, 7] - * - * m = /(?<foo>.)(.)(?<bar>.)/.match("hoge") - * p m.offset(:foo) #=> [0, 1] - * p m.offset(:bar) #=> [2, 3] + * :include: doc/matchdata/offset.rdoc * */ |