struct Regex:: MatchData
Overview
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.
Included Modules
- Regex::PCRE2::MatchData
Defined in:
regex/match_data.crInstance Method Summary
- #==(other : Regex::MatchData)
-
#[](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. -
#[](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. -
#[](range : Range) : Array(String)
Returns all matches that are within the given range.
-
#[]?(start : Int, count : Int) : Array(String) | Nil
Like
#[](Int, Int)
but returnsnil
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. -
#[]?(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. -
#[]?(range : Range) : Array(String) | Nil
Like
#[](Range)
, but returnsnil
if the range's start is out of range. -
#begin(n = 0) : Int32
Returns the position of the first character of the nth match.
-
#byte_begin(n = 0) : Int32
Returns the position of the first byte of the nth match.
-
#byte_end(n = 0) : Int32
Returns the position of the next byte after the match.
-
#captures : Array(String | Nil)
Returns an array of unnamed capture groups.
- #clone
-
#dup
Returns a shallow copy of this object.
-
#end(n = 0) : Int32
Returns the position of the next character after the match.
-
#group_size : Int32
Returns the number of capture groups, including named capture groups.
- #hash(hasher)
-
#inspect(io : IO) : Nil
Appends this struct's name and instance variables names and values to the given IO.
-
#named_captures : Hash(String, String | Nil)
Returns a hash of named capture groups.
-
#post_match : String
Returns the part of the original string after the match.
-
#pre_match : String
Returns the part of the original string before the match.
- #pretty_print(pp) : Nil
-
#regex : Regex
Returns the original regular expression.
-
#size : Int32
Returns the number of elements in this match object.
-
#string : String
Returns the original string.
-
#to_a : Array(String | Nil)
Convert this match data into an array.
-
#to_h : Hash(Int32 | String, String | Nil)
Convert this match data into a hash.
-
#to_s(io : IO) : Nil
Prints the matched substring to io.
-
#to_s : String
Returns the matched substring.
Instance methods inherited from struct Struct
==(other) : Bool
==,
hash(hasher)
hash,
inspect(io : IO) : Nil
inspect,
pretty_print(pp) : Nil
pretty_print,
to_s(io : IO) : Nil
to_s
Instance methods inherited from struct Value
==(other : JSON::Any)==(other : YAML::Any)
==(other) ==, dup dup
Instance methods inherited from class Object
! : Bool
!,
!=(other)
!=,
!~(other)
!~,
==(other)
==,
===(other : JSON::Any)===(other : YAML::Any)
===(other) ===, =~(other) =~, as(type : Class) as, as?(type : Class) as?, class class, dup dup, hash(hasher)
hash hash, in?(collection : Object) : Bool
in?(*values : Object) : Bool in?, inspect(io : IO) : Nil
inspect : String inspect, is_a?(type : Class) : Bool is_a?, itself itself, nil? : Bool nil?, not_nil!(message)
not_nil! not_nil!, pretty_inspect(width = 79, newline = "\n", indent = 0) : String pretty_inspect, pretty_print(pp : PrettyPrint) : Nil pretty_print, responds_to?(name : Symbol) : Bool responds_to?, tap(&) tap, to_json(io : IO) : Nil
to_json : String to_json, to_pretty_json(indent : String = " ") : String
to_pretty_json(io : IO, indent : String = " ") : Nil to_pretty_json, to_s(io : IO) : Nil
to_s : String to_s, to_yaml(io : IO) : Nil
to_yaml : String to_yaml, try(&) try, unsafe_as(type : T.class) forall T unsafe_as
Class methods inherited from class Object
from_json(string_or_io, root : String)from_json(string_or_io) from_json, from_yaml(string_or_io : String | IO) from_yaml
Macros inherited from class Object
class_getter(*names, &block)
class_getter,
class_getter!(*names)
class_getter!,
class_getter?(*names, &block)
class_getter?,
class_property(*names, &block)
class_property,
class_property!(*names)
class_property!,
class_property?(*names, &block)
class_property?,
class_setter(*names)
class_setter,
def_clone
def_clone,
def_equals(*fields)
def_equals,
def_equals_and_hash(*fields)
def_equals_and_hash,
def_hash(*fields)
def_hash,
delegate(*methods, to object)
delegate,
forward_missing_to(delegate)
forward_missing_to,
getter(*names, &block)
getter,
getter!(*names)
getter!,
getter?(*names, &block)
getter?,
property(*names, &block)
property,
property!(*names)
property!,
property?(*names, &block)
property?,
setter(*names)
setter
Instance Method Detail
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
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"
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
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"
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
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
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
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]
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.
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
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
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)"
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}
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"
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"
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
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]
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}