NAME
Sidef::Types::Regex::Match - Regular expression match object exposing captures and match metadata.
DESCRIPTION
This class implements a match object that represents the result of a regular expression matching operation in Sidef. A Match object is returned by regex-matching operations such as match, run, =~, gmatch, and gmatches on a Sidef::Types::Regex::Regex object; it is not normally constructed directly.
A Match object is truthy exactly when the match succeeded, and it stringifies to the joined text of its capture groups (see "matched" and "to_str" below for the exact rules).
SYNOPSIS
# Basic matching
var match = "Hello World".match(/(\w+)\s+(\w+)/)
# Access captured groups
say match.captures # ["Hello", "World"]
say match[0] # "Hello" (first capture group)
say match[1] # "World" (second capture group)
# Named captures
var m = "John Doe".match(/(?<first>\w+)\s+(?<last>\w+)/)
say m.named_captures # {first: "John", last: "Doe"}
# Check if match was successful
if ("test".match(/\d+/).matched) {
say "Contains digits"
}
# Get the [start, end] offsets of the match
var pos = "abc123def".match(/\d+/).pos
say pos # [3, 6]INHERITS
Inherits methods from Sidef::Object::Object.
CONSTRUCTION
new
Sidef::Types::Regex::Match.new(string => str, regex => re, pos => n)Low-level constructor for a Match object. It is used internally by Sidef::Types::Regex::Regex's matching methods; you will not normally call this directly, since it requires an already-constructed Regex object and other internal fields.
MATCH STATUS
matched
self.matchedReturns a boolean indicating whether the match was successful.
var text = "test123"
if (text.match(/\d+/).matched) {
say "Found digits"
}
if (!text.match(/[A-Z]+/).matched) {
say "No uppercase letters found"
}A Match object can also be used directly in boolean contexts (e.g. if (match) { ... }) without calling this method explicitly.
Aliases: to_bool, is_successful
CAPTURED GROUPS
captures
self.capturesReturns an array containing the captured groups from the regular expression match, in the order they appear in the pattern.
var match = "John Doe".match(/(\w+)\s+(\w+)/)
say match.captures # ["John", "Doe"]If the pattern has no capturing groups at all, a successful non-global match yields a single-element array containing the string "1" rather than an empty array or the whole matched text — this mirrors how Perl's own list-context matching behaves when there are no groups to capture. A successful global match (from gmatch/global_match/gmatches/global_matches) against a pattern without capturing groups instead yields an empty array. If you want the matched substring itself, wrap the whole pattern in a capturing group, e.g. match(/(\d+)/) rather than match(/\d+/).
var m1 = "abc".match(/abc/)
say m1.captures # ["1"] (no capture groups, non-global match)
var m2 = "abc123".match(/(\d+)/)
say m2.captures # ["123"]Aliases: cap, caps, to_a, to_array, groups
named_captures
self.named_capturesReturns a hash containing all named capture groups from the regular expression match. The keys are the capture group names, and the values are the matched strings. If the regex has no named captures, it returns an empty hash.
var match = "John Doe".match(/(?<first>\w+)\s+(?<last>\w+)/)
say match.named_captures # {first: "John", last: "Doe"}
say match.named_captures{:first} # "John"
var email = "user@example.com".match(/(?<user>\w+)@(?<domain>[\w.]+)/)
say email.named_captures{:user} # "user"
say email.named_captures{:domain} # "example.com"Aliases: ncap, ncaps, named_groups
join
self.join(separator)Joins all the captured groups into a single string using the specified separator.
var match = "2024-12-28".match(/(\d+)-(\d+)-(\d+)/)
say match.join('/') # "2024/12/28"
var m2 = "a,b,c".match(/(\w),(\w),(\w)/)
say m2.join(' ') # "a b c"Like captures, this reflects whatever is actually in the capture list, including the "1" placeholder described under "captures" when the pattern has no capturing groups.
MATCH POSITION
pos
self.posReturns a two-element array [start, end] giving the character offsets of the overall match within the original string.
var str = "abc123def"
var match = str.match(/\d+/)
say match.pos # [3, 6]This is only available for matches produced by a plain (non-global) match — that is, via match, run, or =~. Matches produced by gmatch, global_match, gmatches, or global_matches do not carry this position information and should not be queried with pos.
Aliases: match_pos
SOURCE INFORMATION
string
self.stringReturns the original string that was matched against, in full — not just the matched portion.
var str = "Hello World 2024"
var match = str.match(/\d+/)
say match.string # "Hello World 2024"regex
self.regexReturns the Sidef::Types::Regex::Regex object that produced this match.
var pattern = /\d+/
var match = "test123".match(pattern)
say match.regex # the Regex object /\d+/
say "abc456".match(match.regex).to_str # "456"STRING REPRESENTATION
to_str
self.to_strReturns a string built by joining all captured groups with a single space, the same text produced when a Match object is stringified implicitly (e.g. via interpolation). See "captures" for what ends up in the capture list, including the no-capturing-groups placeholder.
var match = "Hello World".match(/(\w+)\s+(\w+)/)
say match.to_str # "Hello World"
var m2 = "Price: $19.99".match(/\$(\d+\.\d+)/)
say m2.to_str # "19.99"Note that for a pattern with no capturing groups, this returns "1" on a successful non-global match rather than the matched substring — see "captures".
dump
self.dumpReturns a string representation of the Match object suitable for debugging, showing the original string and the regex it was matched against, in the form ("string" =~ /pattern/).
var match = "test123".match(/(\w+)(\d+)/)
say match.dump
# ("test123" =~ /(\w+)(\d+)/)LOW-LEVEL ACCESS
get_value
self.get_valueReturns the raw success/failure value backing this Match object (used internally to implement boolean context). Prefer "matched" in normal code.
...
match.(*)A low-level "spread" method that returns the capture list as a raw list of Sidef strings (the same data as "captures"), rather than wrapped in an Array. It backs contexts where a Match object is flattened/spread into multiple values.
ARRAY-LIKE ACCESS
Match objects support array-like indexing to access individual capture groups directly:
var match = "John Doe 30".match(/(\w+)\s+(\w+)\s+(\d+)/)
say match[0] # "John" (first capture group)
say match[1] # "Doe" (second capture group)
say match[2] # "30" (third capture group)This indexes into the same data returned by "captures", including the no-capturing-groups placeholder described there.
EXAMPLES
Extracting Email Components
var email = "user@example.com"
var match = email.match(/(?<user>[\w.]+)@(?<domain>[\w.]+)/)
if (match.matched) {
say "Username: #{match.named_captures{:user}}"
say "Domain: #{match.named_captures{:domain}}"
}Parsing Dates
var date = "2024-12-28"
var match = date.match(/(?<year>\d{4})-(?<month>\d{2})-(?<day>\d{2})/)
if (match.matched) {
say "Year: #{match.named_captures{:year}}"
say "Month: #{match.named_captures{:month}}"
say "Day: #{match.named_captures{:day}}"
}Validating and Extracting Phone Numbers
var phone = "Call me at (555) 123-4567"
var match = phone.match(/\((\d{3})\)\s+(\d{3})-(\d{4})/)
if (match.matched) {
var formatted = match.join('-')
say "Phone: #{formatted}" # "555-123-4567"
}Getting the Overall Match Position
var match = "abc123def".match(/(\d+)/)
if (match.matched) {
var offsets = match.pos
say "Matched from #{offsets[0]} to #{offsets[1]}" # "Matched from 3 to 6"
}