Documentation for method subst assembled from the following pages:
Class: Allomorph §
From Allomorph
(Allomorph) method subst §
method subst(Allomorph: |c)Calls Str.subst on the invocant's Str value.
Class: Str §
From Str
(Str) 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 made say .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 :g say .subst(/foo/, "bar", :x(*)); # OUTPUT: «Hey bar bar bar» say .subst(/foo/, "bar", :nth(3)); # OUTPUT: «Hey foo foo bar» # Replace last match say .subst(/foo/, "bar", :nth(*)); # OUTPUT: «Hey foo foo bar» # Replace next-to-last last match say .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(|)