Documentation for method subst assembled from the following types:

class Cool

From Cool

(Cool) method subst

Defined as:

method subst(|)

Coerces the invocant to Stringy and calls Str.subst.

class Str

From Str

(Str) method subst

multi method subst(Str:D: $matcher, $replacement, *%opts)

Returns the invocant string where $matcher is replaced by $replacement (or the original string, if no match was found).

There is an in-place syntactic variant of subst spelled s/matcher/replacement/ and with adverb following the s or inside the matcher.

$matcher can be a Regex, or a literal Str. Non-Str matcher arguments of type Cool are coerced to Str for literal matching. If a Regex $matcher is used, the $/ special variable will be set to Nil (if no matches occurred), a Match object, or a List of Match objects (if multi-match options like :g are used).

Literal replacement substitution

my $some-string = "Some foo";
my $another-string = $some-string.subst(/foo/, "string"); # gives 'Some string' 
$some-string.=subst(/foo/, "string"); # in-place substitution. $some-string is now 'Some string'

Callable

The replacement can be a Callable in which the current Match object will be placed in the $/ variable, as well as the $_ topic variable. Using a Callable as replacement is how you can refer to any of the captures created in the regex:

# Using capture from $/ variable (the $0 is the first positional capture) 
say 'abc123defg'.subst(/(\d+)/, { " before $0 after " });
# OUTPUT: «abc before 123 after defg␤» 
 
# Using capture from $/ variable (the $<foo> is a named capture) 
say 'abc123defg'.subst(/$<foo>=\d+/, { " before $<foo> after " });
# OUTPUT: «abc before 123 after defg␤» 
 
# Using WhateverCode to operate on the Match given in $_: 
say 'abc123defg'.subst(/(\d+)/, "[ " ~ *.flip ~ " ]");
# OUTPUT: «abc[ 321 ]defg␤» 
 
# Using a Callable to generate substitution without involving current Match: 
my $i = 41;
my $str = "The answer is secret.";
say $str.subst(/secret/, {++$i}); # The answer to everything 
# OUTPUT: «The answer is 42.␤»

Adverbs

The following adverbs are supported

Note that only in the s/// form :ii implies :i and :ss implies :s. In the method form, the :s and :i modifiers must be added to the regex, not the subst method call.

More Examples

Here are other examples of usage:

my $str = "Hey foo foo foo";
$str.subst(/foo/, "bar", :g); # global substitution - returns Hey bar bar bar 
 
$str.subst(/foo/, "no subst", :x(0)); # targeted substitution. Number of times to substitute. Returns back unmodified. 
$str.subst(/foo/, "bar", :x(1)); #replace just the first occurrence. 
 
$str.subst(/foo/, "bar", :nth(3)); # replace nth match alone. Replaces the third foo. Returns Hey foo foo bar

The :nth adverb has readable English-looking variants:

say 'ooooo'.subst: 'o', 'x', :1st; # OUTPUT: «xoooo␤» 
say 'ooooo'.subst: 'o', 'x', :2nd; # OUTPUT: «oxooo␤» 
say 'ooooo'.subst: 'o', 'x', :3rd; # OUTPUT: «ooxoo␤» 
say 'ooooo'.subst: 'o', 'x', :4th; # OUTPUT: «oooxo␤»