Match Reference
Result of a successful regex match
What it is #
Position in the hierarchy #
| Inherits from | — |
| Does | — |
| Inherited by | Grammar |
Routines #
Signatures are reproduced from the documentation, including their declared return types. A routine listed here is part of the type's published interface; whether Raku++ implements it is a separate question, answered by the examples below.
method pos #
Returns the current position as a string index into Match.target for a regex match in progress: You should not use this method on a finished Match, as the output can be implementation specific or is, in any case, unspecified.
method target #
method target()Returns a string representation of the object against which the regex matches. This is the value that the regex engine works with internally.
method chars #
method chars()Returns the numbers of characters in the matched string or 0 if there's been no match. Returns the same as .Str.chars.
method clone #
method clone()Clones the Match object.
method orig #
method orig()Returns the original input to the regex engine, which is usually a string, but doesn't need to be (could be anything that can be coerced to a string): See method target for a close equivalent that always returns a string.
method from #
method from()Returns the index of the starting position of the match.
method to #
method to()Returns the index of the position next to the end of the match. It will return the match position if the end of the match is negative, and Nil if there has been no match.
method made #
method made()Returns the payload that was set with make.
routine make #
method make(Match:D: Mu $payload)
sub make(Mu $payload)Sets the .ast attribute, which will be retrieved using .made. That is, it stores an arbitrary payload into the Match object that can later be retrieved via .made method. Since the sub form operates, by default, on $/, that example is equivalent to: This is typically used in a grammar's actions class methods, where a piece of data is stored by one method and then later retrieved
method actions #
method actions(Match:D: --> Mu)Returns Mu.
Returns the actions object (if any was set; else Mu) that the grammar used from which this Match object was created.
method ast #
Alias for method made.
method Bool #
method Bool(Capture:D: --> Bool:D)Returns Bool:D.
Returns True on successful and False on unsuccessful matches. Please note that any zero-width match can also be successful.
method Str #
method Str(Match:D: --> Str:D)Returns Str:D.
Returns the matched text.
method Int #
method Int(Match:D: --> Int:D)Returns Int:D.
Tries to convert stringified result of the matched text into Int.
method caps #
Returns a list of pairs, with the index or submatch name as key and the submatches as values. The list is ordered by starting position of the submatches.
method chunks #
Returns a list of pairs, with the index or submatch name as key and the submatches as values. The list is ordered by starting position of the submatches. Those parts of the string that were not matched by submatches are interleaved with the other pairs, with the string ~ as key.
method list #
Returns a list of positional submatches.
method hash #
Returns a hash of named submatches.
method prematch #
method prematch(Match:D: --> Str:D)Returns Str:D.
Returns the part of the original string leading up to the match.
method postmatch #
method postmatch(Match:D: --> Str:D)Returns Str:D.
Returns the part of the original string following the match.
method replace-with #
multi method replace-with(Match:D: Str() $replacement --> Str:D)Returns Str:D.
Returns the invocant string where the Match object is replaced by $replacement.
infix eqv #
multi infix:<eqv>(Match:D \a, Match:D \b)Returns True if the attributes pos, from and orig for a and b are equal, and if made, Capture::list and Capture::hash are either the same or both undefined.
Examples, run three ways #
Every example below comes from the official documentation, together with the output that documentation asserts. Each was then executed by Rakudo and by Raku++ when this page was built. Where the three agree, one result is shown; where they do not, all three are — because which of them is wrong is exactly the information worth having.
6 no-output · 13 ok · 1 rakupp-differs
class Match is Capture is Cool does NQPMatchRole {}Not executed: the documentation states no expected output for this example.
my $c;
'abc' ~~ /.$${ $c = $¢ }/;
say $c; # OUTPUT: «｢c｣»｢c｣
Documentation, Rakudo and Raku++ all agree.
my $c; 'camelia' ~~ /<[ l m ]> {$c = $¢}/;
say $c; # OUTPUT: «｢m｣»
say $/; # OUTPUT: «｢m｣»｢m｣
｢m｣
Documentation, Rakudo and Raku++ all agree.
'123' ~~ / (\d) { say $0; say $/; } \d+ /; # OUTPUT: «｢1｣｢1｣ 0 => ｢1｣»｢1｣
｢1｣
0 => ｢1｣
Documentation, Rakudo and Raku++ all agree.
'123' ~~ / (\d) { say $/; say $¢; } \d+ /; # OUTPUT: «｢1｣ 0 => ｢1｣｢1｣ 0 => ｢1｣»
say "¢ → ", $¢, "/ is $/"; ; # OUTPUT: «¢ → Nil/ is 123»｢1｣
0 => ｢1｣
｢1｣
0 => ｢1｣
¢ → Nil/ is 123
Documentation, Rakudo and Raku++ all agree.
my constant Cursor = Match
Not executed: the documentation states no expected output for this example.
my $a = 'abcdef';
$a ~~ /b. {say $/.pos }../; # OUTPUT: «3»3
Documentation, Rakudo and Raku++ all agree.
my $a = "þor" ~~ /o/; say $a.target # OUTPUT: «þor»
þor
Documentation, Rakudo and Raku++ all agree.
42 ~~ /.+/; say $/.orig; # OUTPUT: «42» say $/.orig.^name; # OUTPUT: «Int»
42
Int
42
Int
42
Str
Raku++ disagrees with both the documentation and Rakudo — a defect.
$/.make("your payload here");Not executed: the documentation states no expected output for this example.
make("your payload here");Not executed: the documentation states no expected output for this example.
method my-action ($/) {
make "foo: $/";
}Not executed: the documentation states no expected output for this example.
say 'abc' ~~ /^/; # OUTPUT: «｢｣» say $/.from, ' ', $/.to, ' ', ?$/; # OUTPUT: «0 0 True»
｢｣
0 0 True
Documentation, Rakudo and Raku++ all agree.
"abc123def" ~~ /\d+/; say $/.Str; # OUTPUT: «123»
123
Documentation, Rakudo and Raku++ all agree.
say ('12345' ~~ /234/).Int; # OUTPUT: «234»
say ('12345' ~~ /234/).Int.^name; # OUTPUT: «Int»
# the next line produces a warning about using Nil (result of a no match) in numeric context
say ('one-two' ~~ /234/).Int; # OUTPUT: «0» # because Nil.Int returns 0234
Int
0
Documentation, Rakudo and Raku++ all agree.
'abcdefg' ~~ /cd/; say $/.prematch; # OUTPUT: «ab»
ab
Documentation, Rakudo and Raku++ all agree.
# will return a list of three match objects "abc123def" ~~ m:g/\d/; say $/.[1].prematch; # OUTPUT: «abc1»
abc1
Documentation, Rakudo and Raku++ all agree.
'abcdefg' ~~ /cd/; say $/.postmatch; # OUTPUT: «efg»
efg
Documentation, Rakudo and Raku++ all agree.
# will return a list of three match objects "abc123def" ~~ m:g/\d/; say $/.[1].postmatch; # OUTPUT: «3def»
3def
Documentation, Rakudo and Raku++ all agree.
my Str $some-string = "Some foo";
my Match $match = $some-string.match(/foo/);
my $another-string = $match.replace-with("string"); # «Some string»Not executed: the documentation states no expected output for this example.