struct

Regex::MatchData

Inherits Regex::PCRE2::MatchData / Struct / Value / Object

Regex::MatchData is the type of the special variable $~, and is the type returned by Regex#match and String#match. It encapsulates all the results of a regular expression match.

if md = "Crystal".match(/[p-s]/)
  md.string # => "Crystal"
  md[0]     # => "r"
  md[1]?    # => nil
end

Many Regex::MatchData methods deal with capture groups, and accept an integer argument to select the desired capture group. Capture groups are numbered starting from 1, so that 0 can be used to refer to the entire regular expression without needing to capture it explicitly.

Instance methods

==(other : Regex::MatchData) : Bool

[](start : Int, count : Int) : Array(String)

Returns count or less (if there aren't enough) matches starting at the given start index.

[](n : Int) : String

Returns the match of the nth capture group, or raises an IndexError if there is no nth capture group.

"Crystal".match!(/r(ys)/)[1] # => "ys"
"Crystal".match!(/r(ys)/)[2] # raises IndexError

[](group_name : String) : String

Returns the match of the capture group named by group_name, or raises an KeyError if there is no such named capture group.

"Crystal".match!(/r(?<ok>ys)/)["ok"] # => "ys"
"Crystal".match!(/r(?<ok>ys)/)["ng"] # raises KeyError

When there are capture groups having same name, it returns the last matched capture group.

"Crystal".match!(/(?<ok>Cr).*(?<ok>al)/)["ok"] # => "al"

[](range : Range) : Array(String)

Returns all matches that are within the given range.

[]?(start : Int, count : Int) : Array(String) | Nil

Like #[](Int, Int) but returns nil if the start index is out of range.

[]?(n : Int) : String | Nil

Returns the match of the nth capture group, or nil if there isn't an nth capture group.

When n is 0, returns the match for the entire Regex.

"Crystal".match!(/r(ys)/)[0]? # => "rys"
"Crystal".match!(/r(ys)/)[1]? # => "ys"
"Crystal".match!(/r(ys)/)[2]? # => nil

[]?(group_name : String) : String | Nil

Returns the match of the capture group named by group_name, or nil if there is no such named capture group.

"Crystal".match!(/r(?<ok>ys)/)["ok"]? # => "ys"
"Crystal".match!(/r(?<ok>ys)/)["ng"]? # => nil

When there are capture groups having same name, it returns the last matched capture group.

"Crystal".match!(/(?<ok>Cr).*(?<ok>al)/)["ok"]? # => "al"

[]?(range : Range) : Array(String) | Nil

Like #[](Range), but returns nil if the range's start is out of range.

begin(n : Int32 = 0) : Int32

Returns the position of the first character of the nth match.

When n is 0 or not given, uses the match of the entire Regex. Otherwise, uses the match of the nth capture group.

Raises IndexError if the index is out of range or the respective subpattern is unused.

"Crystal".match!(/r/).begin(0)     # => 1
"Crystal".match!(/r(ys)/).begin(1) # => 2
"クリスタル".match!(/リ(ス)/).begin(0)    # => 1
"Crystal".match!(/r/).begin(1)     # IndexError: Invalid capture group index: 1
"Crystal".match!(/r(x)?/).begin(1) # IndexError: Capture group 1 was not matched

byte_begin(n : Int32 = 0) : Int32

Returns the position of the first byte of the nth match.

When n is 0 or not given, uses the match of the entire Regex. Otherwise, uses the match of the nth capture group.

Raises IndexError if the index is out of range or the respective subpattern is unused.

"Crystal".match!(/r/).byte_begin(0)     # => 1
"Crystal".match!(/r(ys)/).byte_begin(1) # => 2
"クリスタル".match!(/リ(ス)/).byte_begin(0)    # => 3
"Crystal".match!(/r/).byte_begin(1)     # IndexError: Invalid capture group index: 1
"Crystal".match!(/r(x)?/).byte_begin(1) # IndexError: Capture group 1 was not matched

byte_end(n : Int32 = 0) : Int32

Returns the position of the next byte after the match.

When n is 0 or not given, uses the match of the entire Regex. Otherwise, uses the match of the nth capture group.

Raises IndexError if the index is out of range or the respective subpattern is unused.

"Crystal".match!(/r/).byte_end(0)     # => 2
"Crystal".match!(/r(ys)/).byte_end(1) # => 4
"クリスタル".match!(/リ(ス)/).byte_end(0)    # => 9
"Crystal".match!(/r/).byte_end(1)     # IndexError: Invalid capture group index: 1
"Crystal".match!(/r(x)?/).byte_end(1) # IndexError: Capture group 1 was not matched

captures

Returns an array of unnamed capture groups.

It is a difference from to_a that the result array does not contain the match for the entire Regex (self[0]).

match = "Crystal".match!(/(Cr)(?<name1>y)(st)(?<name2>al)/)
match.captures # => ["Cr", "st"]

# When this regex has an optional group, result array may contain
# a `nil` if this group is not matched.
match = "Crystal".match!(/(Cr)(stal)?/)
match.captures # => ["Cr", nil]

clone

dup

Returns a shallow copy of this object.

Because Value is a value type, this method returns self, which already involves a shallow copy of this object because value types are passed by value.

end(n : Int32 = 0) : Int32

Returns the position of the next character after the match.

When n is 0 or not given, uses the match of the entire Regex. Otherwise, uses the match of the nth capture group.

Raises IndexError if the index is out of range or the respective subpattern is unused.

"Crystal".match!(/r/).end(0)     # => 2
"Crystal".match!(/r(ys)/).end(1) # => 4
"クリスタル".match!(/リ(ス)/).end(0)    # => 3
"Crystal".match!(/r/).end(1)     # IndexError: Invalid capture group index: 1
"Crystal".match!(/r(x)?/).end(1) # IndexError: Capture group 1 was not matched

group_size

Returns the number of capture groups, including named capture groups.

"Crystal".match!(/[p-s]/).group_size          # => 0
"Crystal".match!(/r(ys)/).group_size          # => 1
"Crystal".match!(/r(ys)(?<ok>ta)/).group_size # => 2

hash(hasher)

See Object#hash(hasher)

inspect(io : IO) : Nil

Appends this struct's name and instance variables names and values to the given IO.

struct Point
  def initialize(@x : Int32, @y : Int32)
  end
end

p1 = Point.new 1, 2
p1.to_s    # "Point(@x=1, @y=2)"
p1.inspect # "Point(@x=1, @y=2)"

named_captures

Returns a hash of named capture groups.

match = "Crystal".match!(/(Cr)(?<name1>y)(st)(?<name2>al)/)
match.named_captures # => {"name1" => "y", "name2" => "al"}

# When this regex has an optional group, result hash may contain
# a `nil` if this group is not matched.
match = "Crystal".match!(/(?<name1>Cr)(?<name2>stal)?/)
match.named_captures # => {"name1" => "Cr", "name2" => nil}

post_match

Returns the part of the original string after the match. If the match ends at the end of the string, returns the empty string.

"Crystal".match!(/yst/).post_match # => "al"

pre_match

Returns the part of the original string before the match. If the match starts at the start of the string, returns the empty string.

"Crystal".match!(/yst/).pre_match # => "Cr"

pretty_print(pp) : Nil

regex

Returns the original regular expression.

"Crystal".match!(/[p-s]/).regex # => /[p-s]/

size

Returns the number of elements in this match object.

"Crystal".match!(/[p-s]/).size          # => 1
"Crystal".match!(/r(ys)/).size          # => 2
"Crystal".match!(/r(ys)(?<ok>ta)/).size # => 3

string

Returns the original string.

"Crystal".match!(/[p-s]/).string # => "Crystal"

to_a

Convert this match data into an array.

match = "Crystal".match!(/(Cr)(?<name1>y)(st)(?<name2>al)/)
match.to_a # => ["Crystal", "Cr", "y", "st", "al"]

# When this regex has an optional group, result array may contain
# a `nil` if this group is not matched.
match = "Crystal".match!(/(Cr)(?<name1>stal)?/)
match.to_a # => ["Cr", "Cr", nil]

to_h

Convert this match data into a hash.

match = "Crystal".match!(/(Cr)(?<name1>y)(st)(?<name2>al)/)
match.to_h # => {0 => "Crystal", 1 => "Cr", "name1" => "y", 3 => "st", "name2" => "al"}

# When this regex has an optional group, result array may contain
# a `nil` if this group is not matched.
match = "Crystal".match!(/(Cr)(?<name1>stal)?/)
match.to_h # => {0 => "Cr", 1 => "Cr", "name1" => nil}

to_s(io : IO) : Nil

Prints the matched substring to io.

to_s

Returns the matched substring.

"Crystal".match!(/yst/).to_s         # => "yst"
"Crystal".match!(/(y)(s)(?=t)/).to_s # => "ys"