Documentation for method subst assembled from the following pages:

Class: Allomorph §

From Allomorph

(Allomorph) method subst §

method subst(Allomorph:D: |c)

Calls Str.subst on the invocant's Str value.

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

short long meaning
:g :global tries to match as often as possible
:nth(Int|Callable|Whatever) only substitute the nth match; aliases: :st, :nd, :rd, and :th
:ss :samespace preserves whitespace on substitution
:ii :samecase preserves case on substitution
:mm :samemark preserves character marks (e.g. 'ü' replaced with 'o' will result in 'ö')
:x(Int|Range|Whatever) substitute exactly $x matches

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.