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:



1192
1193
1194
 
# File 're.c', line 1192

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:



1165
1166
1167
 
# File 're.c', line 1165

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;

#to_s ⇒ String

Returns a string representing obj. The default to_s prints the object’s class and an encoding of the object id. As a special case, the top-level object that is the initial execution context of Ruby programs returns “main.”

Returns:



313
314
315
 
# File 'object.c', line 313

VALUE
rb_any_to_s(obj)
VALUE obj;

#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:



1039
1040
1041
 
# File 're.c', line 1039

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:



1014
1015
1016
 
# File 're.c', line 1014

VALUE
rb_reg_match_pre(match)
VALUE match;

#select([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.select(0, 2, -2)   #=> ["HX1138", "X", "113"]

Returns:



1252
1253
1254
 
# File 're.c', line 1252

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:



1313
1314
1315
 
# File 're.c', line 1313

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:



1145
1146
1147
 
# File 're.c', line 1145

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:



1290
1291
1292
 
# File 're.c', line 1290

static VALUE
match_to_s(match)
VALUE match;

#select([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.select(0, 2, -2)   #=> ["HX1138", "X", "113"]

Returns:



1230
1231
1232
 
# File 're.c', line 1230

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