class MatchData
Ruby matcher methods create MatchData objects.
A MatchData object contains the detailed result of a match, including:
-
The target string used for the match.
-
The
Regexpused for the match. -
The matched substring.
-
The substring preceding the matched substring.
-
The substring following the matched substring.
-
Captured substrings.
In Brief
# Basics. s = 'https://docs.ruby-lang.org/en/2.5.0/MatchData.html' m = s.match(/(\d\.?)+/) # => #<MatchData "2.5.0" 1:"0"> m.string # => "https://docs.ruby-lang.org/en/2.5.0/MatchData.html" m.regexp # => /(\d\.?)+/ m[0] # => "2.5.0" # Matched substring. m.pre_match # => "https://docs.ruby-lang.org/en/" m.post_match # => "/MatchData.html" # Unnamed (numbered) captures. m = "2025-12-25".match(/(\d{4})-(\d{2})-(\d{2})/) # => #<MatchData "2025-12-25" 1:"2025" 2:"12" 3:"25"> m[0] # => "2025-12-25" # Entire matched substring. m[1] # => "2025" # First captured substring. m[2] # => "12" # Second captured substring. m[3] # => "25" # Third captured substring. m[4] # => nil # No more captured substrings. # Named captures. m = "2025-12-25".match(/(?<year>\d{4})-(?<month>\d{2})-(?<day>\d{2})/) m[:year] # "2025" m[:month] # "12" m[:day] # "25" # Also available by numbers. m[0] # => "2025-12-25" m[1] # => "2025" m[:nosuch] # Raises IndexError: undefined group name reference: nosuch.
Matcher Methods
Each of these methods creates a MatchData object, updates the matcher global variables, and returns the MatchData object:
Each of these methods creates a MatchData object, updates the matcher global variables, but does not return the MatchData object; the MatchData object is available in global variable $~:
Each of these methods, when called with a Regexp argument, creates a MatchData object, updates the matcher global variables, but does not return the MatchData object; the MatchData object is available in global variable $~:
Match-Related Methods
Each of these predicate methods performs a “fast match,” returning whether a match was found, but not creating a MatchData object, and not setting matcher global variables:
This method return the MatchData object resulting from the most recent match:
Public Instance Methods
(MatchData other) → bool
(untyped) → falseReturns whether object is a MatchData object whose string, regexp, and begin values are the same as those of self:
regexp = /a/ s = 'aba' match0 = regexp.match(s) match1 = regexp.match(s, 2) match0[0] # => "a" match1[0] # => "a" match0.begin(0) # => 0 match1.begin(0) # => 2 match0 == match0 # => true match0 == match1 # => false
(capture backref, ?nil) → String
(int start, int length) → Array[String?]
(range[int?] range) → Array[String?]Source
static VALUE
match_aref(int argc, VALUE *argv, VALUE match)
{
VALUE idx, length;
match_check(match);
rb_scan_args(argc, argv, "11", &idx, &length);
if (NIL_P(length)) {
if (FIXNUM_P(idx)) {
return rb_reg_nth_match(FIX2INT(idx), match);
}
else {
int num = namev_to_backref_number(match, idx);
if (num >= 0) {
return rb_reg_nth_match(num, match);
}
else {
return match_ary_aref(match, idx, Qnil);
}
}
}
else {
rb_len_t beg = NUM2LEN(idx);
rb_len_t len = NUM2LEN(length);
rb_len_t num_regs = RMATCH_NREGS(match);
if (len < 0) {
return Qnil;
}
if (beg < 0) {
beg += num_regs;
if (beg < 0) return Qnil;
}
else if (beg > num_regs) {
return Qnil;
}
if (beg+len > num_regs) {
len = num_regs - beg;
}
return match_ary_subseq(match, beg, len, Qnil);
}
}
With only integer argument n given, returns the matched substring at offset n:
regexp = /(\d{4})-(\d{2})-(\d{2})/ match = '2026-12-25'.match(regexp) # => #<MatchData "2026-12-25" 1:"2026" 2:"12" 3:"25"> match[0] # => "2026-12-25" # Entire matched string. match[1] # => "2026" # First matched substring. match[2] # => "12" # Second matched substring. match[3] # => "25" # Third matched substring. match[4] # => nil # No more matches. match[-1] # => "25" # For negative offset, counts backwards.
With integer arguments n and size given, returns size matched substrings beginning at offset n:
regexp = /(\d{4})-(\d{2})-(\d{2})/ match = '2026-12-25'.match(regexp) # => #<MatchData "2026-12-25" 1:"2026" 2:"12" 3:"25"> match[0, 1] # => ["2026-12-25"] match[0, 4] # => ["2026-12-25", "2026", "12", "25"] match[0, 10] # => ["2026-12-25", "2026", "12", "25"] match[-3, 2] # => ["2026", "12"] match[0, 0] # => []
With string or symbol argument name given, returns the named matched substring:
regexp = /(?<year>\d{4})-(?<month>\d{2})-(?<day>\d{2})/ match = regexp.match('2026-10-27') # => #<MatchData "2026-10-27" year:"2026" month:"10" day:"27"> match[:year] # => "2026" match['day'] # => "27" match[:nosuch] # Raises IndexError : undefined group name reference: nosuch.
If multiple captures have the same name, returns matched substring for the last one.
With bounded range argument range given, returns an array of matched substrings:
regexp = /(\d{4})-(\d{2})-(\d{2})/ match = '2026-12-25'.match(regexp) # => #<MatchData "2026-12-25" 1:"2026" 2:"12" 3:"25"> match[0..2] # => ["2026-12-25", "2026", "12"] match[0..10] # => ["2026-12-25", "2026", "12", "25"] match[0..-3] # => ["2026-12-25", "2026"] match[-3..2] # => ["2026", "12"]
With beginless range argument range given, returns an array of matched substrings:
match[..0] # => ["2026-12-25"] match[..1] # => ["2026-12-25", "2026"] match[..10] # => ["2026-12-25", "2026", "12", "25"]
With endless range argument range given, returns an array of matched substrings:
match[0..] # => ["2026-12-25", "2026", "12", "25"] match[2..] # => ["12", "25"] match[10..] # => nil
With unbounded range argument range given, returns an array of all matched substrings:
match[nil..nil] # => ["2026-12-25", "2026", "12", "25"]
Source
static VALUE
match_begin(VALUE match, VALUE n)
{
int i = match_backref_number(match, n);
match_check(match);
backref_number_check(match, i);
if (RMATCH_BEG(match, i) < 0)
return Qnil;
update_char_offset(match);
return LEN2NUM(RMATCH(match)->char_offset[i].beg);
}
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.") # => #<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.
Source
static VALUE
match_bytebegin(VALUE match, VALUE n)
{
int i = match_backref_number(match, n);
match_check(match);
backref_number_check(match, i);
if (RMATCH_BEG(match, i) < 0)
return Qnil;
return LEN2NUM(RMATCH_BEG(match, i));
}
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 nth 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.
Source
static VALUE
match_byteend(VALUE match, VALUE n)
{
int i = match_backref_number(match, n);
match_check(match);
backref_number_check(match, i);
if (RMATCH_BEG(match, i) < 0)
return Qnil;
return LEN2NUM(RMATCH_END(match, i));
}
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 nth 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.
static VALUE
match_byteoffset(VALUE match, VALUE n)
{
int i = match_backref_number(match, n);
match_check(match);
backref_number_check(match, i);
if (RMATCH_BEG(match, i) < 0)
return rb_assoc_new(Qnil, Qnil);
return rb_assoc_new(LEN2NUM(RMATCH_BEG(match, i)), LEN2NUM(RMATCH_END(match, i)));
}
Returns a two-element array containing the beginning and ending byte-based offsets of the nth match. n can be a string or symbol to reference a named capture.
m = /(.)(.)(\d+)(\d)/.match("THX1138.") m.byteoffset(0) #=> [1, 7] m.byteoffset(4) #=> [6, 7] m = /(?<foo>.)(.)(?<bar>.)/.match("hoge") p m.byteoffset(:foo) #=> [0, 1] p m.byteoffset(:bar) #=> [2, 3]
static VALUE
match_captures(VALUE match)
{
return match_array(match, 1);
}
Returns the array of captures, which are all matches except m[0]:
m = /(.)(.)(\d+)(\d)/.match("THX1138.") # => #<MatchData "HX1138" 1:"H" 2:"X" 3:"113" 4:"8"> m[0] # => "HX1138" m.captures # => ["H", "X", "113", "8"]
Related: MatchData.to_a.
Source
static VALUE
match_deconstruct_keys(VALUE match, VALUE keys)
{
VALUE h;
rb_len_t i;
match_check(match);
if (NIL_P(RMATCH(match)->regexp)) {
return rb_hash_new();
}
if (NIL_P(keys)) {
h = rb_hash_new_capa(onig_number_of_names(RREGEXP_PTR(RMATCH(match)->regexp)));
struct named_captures_data data = { h, match, 1 };
onig_foreach_name(RREGEXP_PTR(RMATCH(match)->regexp), match_named_captures_iter, &data);
return h;
}
Check_Type(keys, T_ARRAY);
if (onig_number_of_names(RREGEXP_PTR(RMATCH(match)->regexp)) < RARRAY_LEN(keys)) {
return rb_hash_new();
}
h = rb_hash_new_capa(RARRAY_LEN(keys));
for (i=0; i<RARRAY_LEN(keys); i++) {
VALUE key = RARRAY_AREF(keys, i);
VALUE name;
Check_Type(key, T_SYMBOL);
name = rb_sym2str(key);
int num = match_name_to_backref_number(match, name);
if (num >= 0) {
rb_hash_aset(h, key, rb_reg_nth_match(num, match));
}
else {
return h;
}
}
return h;
}
Returns a hash of the named captures for the given names.
m = /(?<hours>\d{2}):(?<minutes>\d{2}):(?<seconds>\d{2})/.match("18:37:22") m.deconstruct_keys([:hours, :minutes]) # => {:hours => "18", :minutes => "37"} m.deconstruct_keys(nil) # => {:hours => "18", :minutes => "37", :seconds => "22"}
Returns an empty hash if no named captures were defined:
m = /(\d{2}):(\d{2}):(\d{2})/.match("18:37:22") m.deconstruct_keys(nil) # => {}
Source
static VALUE
match_end(VALUE match, VALUE n)
{
int i = match_backref_number(match, n);
match_check(match);
backref_number_check(match, i);
if (RMATCH_BEG(match, i) < 0)
return Qnil;
update_char_offset(match);
return LEN2NUM(RMATCH(match)->char_offset[i].end);
}
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.") # => #<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.
Source
static VALUE
match_equal(VALUE match1, VALUE match2)
{
if (match1 == match2) return Qtrue;
if (!RB_TYPE_P(match2, T_MATCH)) return Qfalse;
if (!RMATCH(match1)->regexp || !RMATCH(match2)->regexp) return Qfalse;
if (!rb_str_equal(RMATCH(match1)->str, RMATCH(match2)->str)) return Qfalse;
if (!rb_reg_equal(match_regexp(match1), match_regexp(match2))) return Qfalse;
int num_regs = RMATCH_NREGS(match1);
if (num_regs != RMATCH_NREGS(match2)) return Qfalse;
if (memcmp(RMATCH_BEG_PTR(match1), RMATCH_BEG_PTR(match2), num_regs * sizeof(OnigPosition))) return Qfalse;
if (memcmp(RMATCH_END_PTR(match1), RMATCH_END_PTR(match2), num_regs * sizeof(OnigPosition))) return Qfalse;
return Qtrue;
}
() → IntegerSource
static VALUE
match_hash(VALUE match)
{
st_index_t hashval;
match_check(match);
hashval = rb_hash_start(rb_str_hash(RMATCH(match)->str));
hashval = rb_hash_uint(hashval, reg_hash(match_regexp(match)));
int num_regs = RMATCH_NREGS(match);
hashval = rb_hash_uint(hashval, num_regs);
hashval = rb_hash_uint(hashval, rb_memhash(RMATCH_BEG_PTR(match), num_regs * sizeof(OnigPosition)));
hashval = rb_hash_uint(hashval, rb_memhash(RMATCH_END_PTR(match), num_regs * sizeof(OnigPosition)));
hashval = rb_hash_end(hashval);
return ST2FIX(hashval);
}
Returns the integer hash value for self, based on the target string, regexp, match, and captures.
See also Object#hash.
() → StringSource
static VALUE
match_inspect(VALUE match)
{
VALUE cname = rb_class_path(rb_obj_class(match));
VALUE str;
int i;
int num_regs = RMATCH_NREGS(match);
struct backref_name_tag *names;
VALUE names_obj = Qnil;
VALUE regexp = RMATCH(match)->regexp;
if (regexp == 0) {
return rb_sprintf("#<%"PRIsVALUE":%p>", cname, (void*)match);
}
else if (NIL_P(regexp)) {
return rb_sprintf("#<%"PRIsVALUE": %"PRIsVALUE">",
cname, rb_reg_nth_match(0, match));
}
names = RB_ALLOCV_N(struct backref_name_tag, names_obj, num_regs);
MEMZERO(names, struct backref_name_tag, num_regs);
onig_foreach_name(RREGEXP_PTR(regexp),
match_inspect_name_iter, names);
str = rb_str_buf_new2("#<");
rb_str_append(str, cname);
for (i = 0; i < num_regs; i++) {
VALUE v;
rb_str_buf_cat2(str, " ");
if (0 < i) {
if (names[i].name)
rb_str_buf_cat(str, (const char *)names[i].name, names[i].len);
else {
rb_str_catf(str, "%d", i);
}
rb_str_buf_cat2(str, ":");
}
v = rb_reg_nth_match(i, match);
if (NIL_P(v))
rb_str_buf_cat2(str, "nil");
else
rb_str_buf_append(str, rb_str_inspect(v));
}
rb_str_buf_cat2(str, ">");
RB_ALLOCV_END(names_obj);
return str;
}
Returns a string representation of self:
m = /.$/.match("foo") # => #<MatchData "o"> m.inspect # => "#<MatchData \"o\">" m = /(.)(.)(.)/.match("foo") # => #<MatchData "foo" 1:"f" 2:"o" 3:"o"> m.inspect # => "#<MatchData \"foo\" 1:\"f\" 2:\"o\ m = /(.)(.)?(.)/.match("fo") # => #<MatchData "fo" 1:"f" 2:nil 3:"o"> m.inspect # => "#<MatchData \"fo\" 1:\"f\" 2:nil 3:\"o\">"
Related: MatchData#to_s.
static VALUE
match_integer_at(int argc, VALUE *argv, VALUE match)
{
match_check(match);
int base = 10;
VALUE idx;
int nth;
argc = rb_check_arity(argc, 1, 2);
if (FIXNUM_P(idx = argv[0])) {
nth = NUM2INT(idx);
}
else if ((nth = namev_to_backref_number(match, idx)) < 0) {
name_to_backref_error(idx);
}
if (argc > 1 && (base = NUM2INT(argv[1])) < 0) {
rb_raise(rb_eArgError, "invalid radix %d", base);
}
if (nth >= RMATCH_NREGS(match)) return Qnil;
if (nth < 0 && (nth += RMATCH_NREGS(match)) <= 0) return Qnil;
rb_len_t start = RMATCH_BEG(match, nth), end = RMATCH_END(match, nth);
if (start < 0) return Qnil;
RUBY_ASSERT(start <= end, "%"PRIdLEN" > %"PRIdLEN, start, end);
VALUE str = RMATCH(match)->str;
RUBY_ASSERT(end <= RSTRING_LEN(str), "%"PRIdLEN" > %"PRIdLEN, end, RSTRING_LEN(str));
char *endp;
return rb_int_parse_cstr(RSTRING_PTR(str) + start, end - start, &endp, NULL,
base, RB_INT_PARSE_DEFAULT);
}
Returns a captured substring converted to an integer; the substring is interpreted as a numeric string in the given radix, which defaults to 10.
With integer index n given, returns the nth capture converted to an integer:
re = /(\d+{4})(\d+{2})(\d+{2})/ # Capture year, month, day. m = re.match("20260308") # => #<MatchData "20260308" 1:"2026" 2:"03" 3:"08"> m.integer_at(0) # => 20260308 m.integer_at(1) # => 2026 m.integer_at(2) # => 3 m.integer_at(3) # => 8 m.integer_at(4) # => nil m.integer_at(-1) # => 8 # For negative index, counts backward in the captures.
With string name given, returns the named capture converted to an integer:
re = /(?<y>\d+{4})(?<m>\d+{2})(?<d>\d+{2})/ m = re.match("20260308") # => #<MatchData "20260308" y:"2026" m:"03" d:"08"> m.integer_at('y') # => 2026 m.integer_at('m') # => 3 m.integer_at('d') # => 8 m.integer_at('nosuch') # Raises IndexError: undefined group name reference: nosuch.
Returns nil if there were no captures:
re = /(\d+)?/ m = re.match('abc') m.integer_at(0) # => nil
The string is converted in the given radix:
re = /\d+/ m = re.match('11') m.integer_at(0) # => 11 m.integer_at(0, 2) # => 3 m.integer_at(0, 8) # => 9 m.integer_at(0, 16) # => 17 m.integer_at(0, 1) # Raises ArgumentError: invalid radix 1.
Related: MatchData#[], String#to_i.
Source
static VALUE
match_nth(VALUE match, VALUE n)
{
int i = match_backref_number(match, n);
backref_number_check(match, i);
rb_len_t start = RMATCH_BEG(match, i), end = RMATCH_END(match, i);
if (start < 0)
return Qnil;
return rb_str_subseq(RMATCH(match)->str, start, end - start);
}
Returns the matched substring corresponding to the given argument.
When non-negative argument n is given, returns the matched substring for the nth match:
m = /(.)(.)(\d+)(\d)(\w)?/.match("THX1138.") # => #<MatchData "HX1138" 1:"H" 2:"X" 3:"113" 4:"8" 5:nil> 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 = /(?<foo>.)(.)(?<bar>.+)/.match("hoge") # => #<MatchData "hoge" foo:"h" bar:"ge"> m.match('foo') # => "h" m.match(:bar) # => "ge"
Source
static VALUE
match_nth_length(VALUE match, VALUE n)
{
int i = match_backref_number(match, n);
match_check(match);
backref_number_check(match, i);
if (RMATCH_BEG(match, i) < 0)
return Qnil;
update_char_offset(match);
const struct rmatch_offset *const ofs =
&RMATCH(match)->char_offset[i];
return LEN2NUM(ofs->end - ofs->beg);
}
Returns the length (in characters) of the matched substring corresponding to the given argument.
When non-negative argument n is given, returns the length of the matched substring for the nth match:
m = /(.)(.)(\d+)(\d)(\w)?/.match("THX1138.") # => #<MatchData "HX1138" 1:"H" 2:"X" 3:"113" 4:"8" 5:nil> 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 = /(?<foo>.)(.)(?<bar>.+)/.match("hoge") # => #<MatchData "hoge" foo:"h" bar:"ge"> m.match_length('foo') # => 1 m.match_length(:bar) # => 2
() → Hash[String, String?]
(symbolize_names: true) → Hash[Symbol, String?]
(symbolize_names: boolish) → Hash[String | Symbol, String?]Source
static VALUE
match_named_captures(int argc, VALUE *argv, VALUE match)
{
VALUE hash;
match_check(match);
if (NIL_P(RMATCH(match)->regexp))
return rb_hash_new();
VALUE opt;
int symbolize_names = 0;
rb_scan_args(argc, argv, "0:", &opt);
if (!NIL_P(opt)) {
static ID keyword_ids[1];
VALUE symbolize_names_val;
if (!keyword_ids[0]) {
keyword_ids[0] = rb_intern_const("symbolize_names");
}
rb_get_kwargs(opt, keyword_ids, 0, 1, &symbolize_names_val);
if (!UNDEF_P(symbolize_names_val) && RTEST(symbolize_names_val)) {
symbolize_names = 1;
}
}
hash = rb_hash_new();
struct named_captures_data data = { hash, match, symbolize_names };
onig_foreach_name(RREGEXP_PTR(RMATCH(match)->regexp), match_named_captures_iter, &data);
return hash;
}
Returns a hash of the named captures; each key is a capture name; each value is its captured string or nil:
m = /(?<foo>.)(.)(?<bar>.+)/.match("hoge") # => #<MatchData "hoge" foo:"h" bar:"ge"> m.named_captures # => {"foo"=>"h", "bar"=>"ge"} m = /(?<a>.)(?<b>.)/.match("01") # => #<MatchData "01" a:"0" b:"1"> m.named_captures #=> {"a" => "0", "b" => "1"} m = /(?<a>.)(?<b>.)?/.match("0") # => #<MatchData "0" a:"0" b:nil> m.named_captures #=> {"a" => "0", "b" => nil} m = /(?<a>.)(?<a>.)/.match("01") # => #<MatchData "01" a:"0" a:"1"> m.named_captures #=> {"a" => "1"}
If keyword argument symbolize_names is given a true value, the keys in the resulting hash are Symbols:
m = /(?<a>.)(?<a>.)/.match("01") # => #<MatchData "01" a:"0" a:"1"> m.named_captures(symbolize_names: true) #=> {:a => "1"}
Source
static VALUE
match_names(VALUE match)
{
match_check(match);
if (NIL_P(RMATCH(match)->regexp))
return rb_ary_new_capa(0);
return rb_reg_names(RMATCH(match)->regexp);
}
Returns an array of the capture names (see 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.
Equivalent to:
m = /(?<foo>.)(?<bar>.)(?<baz>.)/.match("hoge") m.regexp.names # => ["foo", "bar", "baz"]
static VALUE
match_offset(VALUE match, VALUE n)
{
int i = match_backref_number(match, n);
match_check(match);
backref_number_check(match, i);
if (RMATCH_BEG(match, i) < 0)
return rb_assoc_new(Qnil, Qnil);
update_char_offset(match);
return rb_assoc_new(LEN2NUM(RMATCH(match)->char_offset[i].beg),
LEN2NUM(RMATCH(match)->char_offset[i].end));
}
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 nth 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.
() → StringSource
VALUE
rb_reg_match_post(VALUE match)
{
VALUE str;
rb_len_t pos;
if (NIL_P(match)) return Qnil;
match_check(match);
if (RMATCH_BEG(match, 0) == -1) return Qnil;
str = RMATCH(match)->str;
pos = RMATCH_END(match, 0);
str = rb_str_subseq(str, pos, RSTRING_LEN(str) - pos);
return str;
}
Returns the substring of the target string from the end of the first match in self (that is, self[0]) to the end of the string; equivalent to regexp global variable $':
m = /(.)(.)(\d+)(\d)/.match("THX1138: The Movie") # => #<MatchData "HX1138" 1:"H" 2:"X" 3:"113" 4:"8"> m[0] # => "HX1138" m.post_match # => ": The Movie"\
Related: MatchData.pre_match.
() → StringSource
VALUE
rb_reg_match_pre(VALUE match)
{
VALUE str;
if (NIL_P(match)) return Qnil;
match_check(match);
if (RMATCH_BEG(match, 0) == -1) return Qnil;
str = rb_str_subseq(RMATCH(match)->str, 0, RMATCH_BEG(match, 0));
return str;
}
Returns the substring of the target string from its beginning up to the first match in self (that is, self[0]); equivalent to regexp global variable $`:
m = /(.)(.)(\d+)(\d)/.match("THX1138.") # => #<MatchData "HX1138" 1:"H" 2:"X" 3:"113" 4:"8"> m[0] # => "HX1138" m.pre_match # => "T"
Related: MatchData#post_match.
() → RegexpSource
static VALUE
match_regexp(VALUE match)
{
VALUE regexp;
match_check(match);
regexp = RMATCH(match)->regexp;
if (NIL_P(regexp)) {
VALUE str = rb_reg_nth_match(0, match);
regexp = rb_reg_regcomp(rb_reg_quote(str));
RB_OBJ_WRITE(match, &RMATCH(match)->regexp, regexp);
}
return regexp;
}
Returns the regexp that produced the match:
m = /a.*b/.match("abc") # => #<MatchData "ab"> m.regexp # => /a.*b/
() → IntegerSource
static VALUE
match_size(VALUE match)
{
match_check(match);
return INT2FIX(RMATCH_NREGS(match));
}
Returns size of the match array:
m = /(.)(.)(\d+)(\d)/.match("THX1138.") # => #<MatchData "HX1138" 1:"H" 2:"X" 3:"113" 4:"8"> m.size # => 5
() → StringSource
static VALUE
match_string(VALUE match)
{
match_check(match);
return RMATCH(match)->str; /* str is frozen */
}
Returns the target string if it was frozen; otherwise, returns a frozen copy of the target string:
m = /(.)(.)(\d+)(\d)/.match("THX1138.") # => #<MatchData "HX1138" 1:"H" 2:"X" 3:"113" 4:"8"> m.string # => "THX1138."
static VALUE
match_to_a(VALUE match)
{
return match_array(match, 0);
}
Returns the array of matches:
m = /(.)(.)(\d+)(\d)/.match("THX1138.") # => #<MatchData "HX1138" 1:"H" 2:"X" 3:"113" 4:"8"> m.to_a # => ["HX1138", "H", "X", "113", "8"]
Related: MatchData#captures.
() → StringSource
static VALUE
match_to_s(VALUE match)
{
VALUE str = rb_reg_last_match(match_check(match));
if (NIL_P(str)) str = rb_str_new(0,0);
return str;
}
Returns the matched string:
m = /(.)(.)(\d+)(\d)/.match("THX1138.") # => #<MatchData "HX1138" 1:"H" 2:"X" 3:"113" 4:"8"> m.to_s # => "HX1138" m = /(?<foo>.)(.)(?<bar>.+)/.match("hoge") # => #<MatchData "hoge" foo:"h" bar:"ge"> m.to_s # => "hoge"
Related: MatchData.inspect.
static VALUE
match_values_at(int argc, VALUE *argv, VALUE match)
{
VALUE result;
int i;
match_check(match);
result = rb_ary_new2(argc);
for (i=0; i<argc; i++) {
if (FIXNUM_P(argv[i])) {
rb_ary_push(result, rb_reg_nth_match(FIX2INT(argv[i]), match));
}
else {
int num = namev_to_backref_number(match, argv[i]);
if (num >= 0) {
rb_ary_push(result, rb_reg_nth_match(num, match));
}
else {
match_ary_aref(match, argv[i], result);
}
}
}
return result;
}
Returns match and captures at the given indexes, which may include any mixture of:
-
Integers.
-
Ranges.
-
Names (strings and symbols).
Examples:
m = /(.)(.)(\d+)(\d)/.match("THX1138: The Movie") # => #<MatchData "HX1138" 1:"H" 2:"X" 3:"113" 4:"8"> m.values_at(0, 2, -2) # => ["HX1138", "X", "113"] m.values_at(1..2, -1) # => ["H", "X", "8"] m = /(?<a>\d+) *(?<op>[+\-*\/]) *(?<b>\d+)/.match("1 + 2") # => #<MatchData "1 + 2" a:"1" op:"+" b:"2"> m.values_at(0, 1..2, :a, :b, :op) # => ["1 + 2", "1", "+", "1", "2", "+"]