Merge pull request #2894 from tmtvl/2892-add-non-destructive-substitution-to-regex-documentation

Add the `S///` section from operators to regexes

Author: JJ

doc/Language/regexes.pod6

@@ -1390,6 +1390,22 @@ that their regular expression needs to match every piece of data in the line,
 including what they want to match. Write just enough to match the data you're
 looking for, no more, no less.
 
+=head2 X«C<S///> non-destructive substitution»
+
+    say S/o .+ d/new/ with 'old string';      # OUTPUT: «new string»
+    S:g/« (.)/$0.uc()/.say for <foo bar ber>; # OUTPUT: «Foo␤Bar␤Ber»
+
+C<S///> uses the same semantics as the C<s///> operator, except
+it leaves the original string intact
+and I<returns the resultant string> instead of C<$/> (C<$/> still being set
+to the same values as with C<s///>).
+
+B<Note:> since the result is obtained as a return value, using this
+operator with the C<~~> smartmatch operator is a mistake and will issue a
+warning. To execute the substitution on a variable that isn't the C<$_> this
+operator uses, alias it to C<$_> with C<given>, C<with>, or any other way.
+Alternatively, use the L«C<.subst> method|/routine/subst».
+
 =head1 X<Tilde for nesting structures|regex, tilde; regex, ~>
 
 The C<~> operator is a helper for matching nested subrules with a