Documentation for method subst-mutate assembled from the following types:

class Str

From Str

(Str) method subst-mutate

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).