Combined from primary sources listed below.
See primary docmentation in context for method subst.
See primary docmentation in context for 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).
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»
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.»
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.
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»
See primary docmentation in context for method subst.
NOTE: .subst-mutate is deprecated in the 6.d version, and will be removed in future ones. You can use subst with .= method call assignment operator or s/// substitution operator instead.
Where subst returns the modified string and leaves the original unchanged, it is possible to mutate the original string by using subst-mutate. If the match is successful, the method returns a Match object representing the successful match, otherwise returns Nil. If :nth (or one of its aliases) with Iterable value, :g, :global, or :x arguments are used, returns a List of Match objects, or an empty List if no matches occurred.
my $some-string = "Some foo";
my $match = $some-string.subst-mutate(/foo/, "string");
say $some-string; # OUTPUT: «Some string»
say $match; # OUTPUT: «｢foo｣»
$some-string.subst-mutate(/<[oe]>/, '', :g); # remove every o and e, notice the :g named argument from .subst
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).
See primary docmentation in context for method subst.
method subst-mutate(Allomorph:D \SELF: |c)
Calls Str.subst-mutate on the invocant's Str value.
See primary docmentation in context for method subst.