Class: MatchData

Inherits:
Object show all
Defined in:
re.c,
re.c

Overview

MatchData is the type of the special variable $~, and is the type of the object returned by Regexp#match and Regexp#last_match. It encapsulates all the results of a pattern match, results normally accessed through the special variables $&, $', $`, $1, $2, and so on. Matchdata is also known as MatchingData.

Instance Method Summary collapse

Instance Method Details

#[](i) ⇒ Object #[](start, length) ⇒ Array #[](range) ⇒ Array

Match Reference—MatchData acts as an array, and may be accessed using the normal array indexing techniques. mtch[0] is equivalent to the special variable $&, and returns the entire matched string. mtch[1], mtch[2], and so on return the values of the matched backreferences (portions of the pattern between parentheses).

m = /(.)(.)(\d+)(\d)/.match("THX1138.")
m[0]       #=> "HX1138"
m[1, 2]    #=> ["H", "X"]
m[1..3]    #=> ["H", "X", "113"]
m[-3, 2]   #=> ["X", "113"]

Overloads:



1195
1196
1197
 
# File 're.c', line 1195

static VALUE
match_aref(argc, argv, match)
int argc;

#begin(n) ⇒ Integer

Returns the offset of the start of the nth element of the match array in the string.

m = /(.)(.)(\d+)(\d)/.match("THX1138.")
m.begin(0)   #=> 1
m.begin(2)   #=> 2

Returns:



765
766
767
 
# File 're.c', line 765

static VALUE
match_begin(match, n)
VALUE match, n;

#captures ⇒ Array

Returns the array of captures; equivalent to mtch.to_a[1..-1].

f1,f2,f3,f4 = /(.)(.)(\d+)(\d)/.match("THX1138.").captures
f1    #=> "H"
f2    #=> "X"
f3    #=> "113"
f4    #=> "8"

Returns:



1168
1169
1170
 
# File 're.c', line 1168

static VALUE
match_captures(match)
VALUE match;

#end(n) ⇒ Integer

Returns the offset of the character immediately following the end of the nth element of the match array in the string.

m = /(.)(.)(\d+)(\d)/.match("THX1138.")
m.end(0)   #=> 7
m.end(2)   #=> 3

Returns:



793
794
795
 
# File 're.c', line 793

static VALUE
match_end(match, n)
VALUE match, n;

#initialize_copy ⇒ Object

:nodoc:



686
687
688
 
# File 're.c', line 686

static VALUE
match_init_copy(obj, orig)
VALUE obj, orig;

#inspect ⇒ String

Returns a printable version of mtch.

puts /.$/.match("foo").inspect
#=> #<MatchData "o">

puts /(.)(.)(.)/.match("foo").inspect
#=> #<MatchData "foo" 1:"f" 2:"o" 3:"o">

puts /(.)(.)?(.)/.match("fo").inspect
#=> #<MatchData "fo" 1:"f" 2:nil 3:"o">

Returns:



1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
 
# File 're.c', line 1340

static VALUE
match_inspect(VALUE match)
{
    const char *cname = rb_obj_classname(match);
    VALUE str;
    int i;
    struct re_registers *regs = RMATCH(match)->regs;
    int num_regs = regs->num_regs;

    str = rb_str_buf_new2("#<");
    rb_str_buf_cat2(str, cname);

    for (i = 0; i < num_regs; i++) {
        VALUE v;
        rb_str_buf_cat2(str, " ");
        if (0 < i) {
            char buf[sizeof(i)*3+1];
            snprintf(buf, sizeof(buf), "%d", i);
            rb_str_buf_cat2(str, buf);
            rb_str_buf_cat2(str, ":");
        }
        v = rb_reg_nth_match(i, match);
        if (v == Qnil)
            rb_str_buf_cat2(str, "nil");
        else
            rb_str_buf_append(str, rb_str_inspect(v));
    }
    rb_str_buf_cat2(str, ">");

    return str;
}

#length ⇒ Integer #size ⇒ Integer

Returns the number of elements in the match array.

m = /(.)(.)(\d+)(\d)/.match("THX1138.")
m.length   #=> 5
m.size     #=> 5

Overloads:



716
717
718
 
# File 're.c', line 716

static VALUE
match_size(match)
VALUE match;

#offset(n) ⇒ Array

Returns a two-element array containing the beginning and ending offsets of the nth match.

m = /(.)(.)(\d+)(\d)/.match("THX1138.")
m.offset(0)   #=> [1, 7]
m.offset(4)   #=> [6, 7]

Returns:



736
737
738
 
# File 're.c', line 736

static VALUE
match_offset(match, n)
VALUE match, n;

#post_match ⇒ String

Returns the portion of the original string after the current match. Equivalent to the special variable $'.

m = /(.)(.)(\d+)(\d)/.match("THX1138: The Movie")
m.post_match   #=> ": The Movie"

Returns:



1042
1043
1044
 
# File 're.c', line 1042

VALUE
rb_reg_match_post(match)
VALUE match;

#pre_match ⇒ String

Returns the portion of the original string before the current match. Equivalent to the special variable $`.

m = /(.)(.)(\d+)(\d)/.match("THX1138.")
m.pre_match   #=> "T"

Returns:



1017
1018
1019
 
# File 're.c', line 1017

VALUE
rb_reg_match_pre(match)
VALUE match;

#select {|obj| ... } ⇒ Array

Returns an array containing match strings for which block gives true. MatchData#select will be removed from Ruby 1.9.

m = /(.)(.)(\d+)(\d)/.match("THX1138: The Movie")
p m.select{|x| /X/ =~ x}   #=> ["HX1138", "X"]

Yields:

  • (obj)

Returns:



1254
1255
1256
 
# File 're.c', line 1254

static VALUE
match_select(argc, argv, match)
int argc;

#length ⇒ Integer #size ⇒ Integer

Returns the number of elements in the match array.

m = /(.)(.)(\d+)(\d)/.match("THX1138.")
m.length   #=> 5
m.size     #=> 5

Overloads:



716
717
718
 
# File 're.c', line 716

static VALUE
match_size(match)
VALUE match;

#string ⇒ String

Returns a frozen copy of the string passed in to match.

m = /(.)(.)(\d+)(\d)/.match("THX1138.")
m.string   #=> "THX1138."

Returns:



1316
1317
1318
 
# File 're.c', line 1316

static VALUE
match_string(match)
VALUE match;

#to_a ⇒ Array

Returns the array of matches.

m = /(.)(.)(\d+)(\d)/.match("THX1138.")
m.to_a   #=> ["HX1138", "H", "X", "113", "8"]

Because to_a is called when expanding *variable, there’s a useful assignment shortcut for extracting matched fields. This is slightly slower than accessing the fields directly (as an intermediate array is generated).

all,f1,f2,f3 = *(/(.)(.)(\d+)(\d)/.match("THX1138."))
all   #=> "HX1138"
f1    #=> "H"
f2    #=> "X"
f3    #=> "113"

Returns:



1148
1149
1150
 
# File 're.c', line 1148

static VALUE
match_to_a(match)
VALUE match;

#to_s ⇒ String

Returns the entire matched string.

m = /(.)(.)(\d+)(\d)/.match("THX1138.")
m.to_s   #=> "HX1138"

Returns:



1293
1294
1295
 
# File 're.c', line 1293

static VALUE
match_to_s(match)
VALUE match;

#values_at([index]) ⇒ Array

Uses each index to access the matching values, returning an array of the corresponding matches.

m = /(.)(.)(\d+)(\d)/.match("THX1138: The Movie")
m.to_a               #=> ["HX1138", "H", "X", "113", "8"]
m.values_at(0, 2, -2)   #=> ["HX1138", "X", "113"]

Returns:



1233
1234
1235
 
# File 're.c', line 1233

static VALUE
match_values_at(argc, argv, match)
int argc;