In type/Str§
See primary documentation in context for method subst
multi method subst(Str: , = "", *)
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 foo";my = .subst(/foo/, "string"); # gives '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+)/, );# OUTPUT: «abc before 123 after defg»# Using capture from $/ variable (the $<foo> is a named capture)say 'abc123defg'.subst(/=\d+/, );# 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 = 41;my = "The answer is secret.";say .subst(/secret/, ); # 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 = "Hey foo foo foo";say .subst(/foo/, "bar", :g); # OUTPUT: «Hey bar bar bar»say .subst(/\s+/, :g); # OUTPUT: «Heyfoofoofoo»say .subst(/foo/, "bar", :x(0)); # OUTPUT: «Hey foo foo foo»say .subst(/foo/, "bar", :x(1)); # OUTPUT: «Hey bar foo foo»# Can not match 4 times, so no substitutions madesay .subst(/foo/, "bar", :x(4)); # OUTPUT: «Hey foo foo foo»say .subst(/foo/, "bar", :x(2..4)); # OUTPUT: «Hey bar bar bar»# Replace all of them, identical to :gsay .subst(/foo/, "bar", :x(*)); # OUTPUT: «Hey bar bar bar»say .subst(/foo/, "bar", :nth(3)); # OUTPUT: «Hey foo foo bar»# Replace last matchsay .subst(/foo/, "bar", :nth(*)); # OUTPUT: «Hey foo foo bar»# Replace next-to-last last matchsay .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»
In type/Allomorph§
See primary documentation in context for method subst
method subst(Allomorph: |c)
Calls Str.subst on the invocant's Str value.
In type/Cool§
See primary documentation in context for method subst
method subst(|)