Merge branch 'master' of github.com:perl6/doc

Author: jonathanstowe

WANTED

@@ -19,6 +19,3 @@ Syntax features:
 
 API docs:
     * KeyReducer
-
-Builtins:
-    * substr-rw

lib/Type/Str.pod

@@ -493,6 +493,50 @@ Also using a different value or an incorrect starting index won't match:
     say $integer.substr-eq(42, 3);  #-> False
     say $integer.substr-eq(7342, 0);  #-> False
 
+=head2 method substr-rw
+
+    method substr-rw($from, $length?)
+
+A version of C<substr> that returns a writable reference to a part of a
+string variable.  Its first argument, C<$from> specifies the index in the
+string from which a substitution should occur, and its last argument,
+C<$length> specifies how many characters are to be replaced.
+
+For example, in its method form, if one wants to take the string C<"abc">
+and replace the second character (at index 1) with the letter C<"z">, then
+one do this:
+
+    my $string = "abc";
+    $string.substr-rw(1, 1) = "z";
+    $string.say;                    #-> azc
+
+C<substr-rw> also has a function form, so the above example can also be
+written like so:
+
+    my $string = "abc";
+    substr-rw($string, 1, 1) = "z";
+    $string.say;                    #-> azc
+
+It is also possible to alias the writable reference returned by C<substr-rw>
+for repeated operations:
+
+    my $string = "A character in the 'Flintstones' is: barney";
+    $string ~~ /(barney)/;
+    my $ref := substr-rw($string, $0.from, $0.to);
+    $string.say;
+    #-> A character in the 'Flintstones' is: barney
+    $ref = "fred";
+    $string.say;
+    #-> A character in the 'Flintstones' is: fred
+    $ref = "wilma";
+    $string.say;
+    #-> A character in the 'Flintstones' is: wilma
+
+Notice that the start position and length of string to replace has been
+specified via the C<.from> and C<.to> methods on the C<Match> object, C<$0>.
+It is thus not necessary to count characters in order to replace a
+substring, hence making the code more flexible.
+
 =head2 method succ
 
     method succ(Str:D) returns Str:D