Programming Ruby

The Pragmatic Programmer's Guide

Previous < Contents ^
Next >
class MatchData
Parent: Object
Version: 1.6

Index:

[ ] begin end length offset post_match pre_match size string to_a to_s


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.

instance methods
[ ] mtch[i] -> anObject
mtch[start, length] -> anArray
mtch[aRange] -> anArray

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"]

begin mtch.begin( n ) -> anInteger

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

end mtch.end( n ) -> anInteger

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

length mtch.length -> anInteger

Returns the number of elements in the match array.

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

offset mtch.offset( n ) -> anArray

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]

post_match mtch.post_match -> aString

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"

pre_match mtch.pre_match -> aString

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"

size mtch.size -> anInteger

A synonym for MatchData#length .

string mtch.string -> aString

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

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

to_a mtch.to_a -> anArray

Returns the array of matches.

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

to_s mtch.to_s -> aString

Returns the entire matched string.

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


Previous < Contents ^
Next >

Extracted from the book "Programming Ruby - The Pragmatic Programmer's Guide"
Copyright © 2001 by Addison Wesley Longman, Inc. This material may be distributed only subject to the terms and conditions set forth in the Open Publication License, v1.0 or later (the latest version is presently available at http://www.opencontent.org/openpub/)).

Distribution of substantively modified versions of this document is prohibited without the explicit permission of the copyright holder.

Distribution of the work or derivative of the work in any standard (paper) book form is prohibited unless prior permission is obtained from the copyright holder.