Documentation for method subst assembled from the following types:

class Str

From Str

(Str) method subst

multi method subst(Str:D: $matcher, $replacement = "", *%options)

Returns the invocant string where $matcher is replaced by $replacement (or the original string, if no match was found). If no $replacement is provided, the empty string is used (i.e., matched string(s) are removed).

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'

say "multi-hyphenate".subst("-"); # OUTPUT: «multihyphenate␤»

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";

say $str.subst(/foo/, "bar", :g);           # OUTPUT: «Hey bar bar bar␤»
say $str.subst(/\s+/, :g);                  # OUTPUT: «Heyfoofoofoo␤»

say $str.subst(/foo/, "bar", :x(0));        # OUTPUT: «Hey foo foo foo␤»
say $str.subst(/foo/, "bar", :x(1));        # OUTPUT: «Hey bar foo foo␤»
# Can not match 4 times, so no substitutions made
say $str.subst(/foo/, "bar", :x(4));        # OUTPUT: «Hey foo foo foo␤»
say $str.subst(/foo/, "bar", :x(2..4));     # OUTPUT: «Hey bar bar bar␤»
# Replace all of them, identical to :g
say $str.subst(/foo/, "bar", :x(*));        # OUTPUT: «Hey bar bar bar␤»

say $str.subst(/foo/, "bar", :nth(3));      # OUTPUT: «Hey foo foo bar␤»
# Replace last match
say $str.subst(/foo/, "bar", :nth(*));      # OUTPUT: «Hey foo foo bar␤»
# Replace next-to-last last match
say $str.subst(/foo/, "bar", :nth(*-1));    # OUTPUT: «Hey foo bar foo␤»

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␤»

class Cool

From Cool

(Cool) method subst

Defined as:

method subst(|)

Coerces the invocant to Stringy and calls Str.subst.