document Buf subbuf-rw routine and method

closes #1148

Author: dwarring

doc/Type/Buf.pod6

@@ -11,4 +11,31 @@ A C<Buf> is a mutable sequence of (usually unsigned) integers.
     my $b = Buf.new(1, 2, 3);
     $b[1] = 42;
 
+=head1 Methods
+
+=head2 method subbuf-rw
+
+    method subbuf-rw($from, $length?)
+
+A mutable version of C<subbuf> that returns a L<Proxy|/type/Proxy> functioning as a
+writable reference to a part of a buffer. Its first argument, C<$from>
+specifies the index in the buffer from which a substitution should occur, and
+its last argument, C<$length> specifies how many elements are to be replaced.
+
+For example, to replace one element at index 3 with two elements, C<100> and C<101>:
+
+    my Buf $b .= new(0..5);
+    $b.subbuf-rw(3,1) = Buf.new(100, 101);
+    dd $b;        # OUTPUT: Buf $b = Buf.new(0,1,2,100,101,4,5)
+
+=head2 routine subbuf-rw
+
+    sub subbuf-rw(Buf:D $buf, $from, $length?)
+
+Returns a writable reference to a part of a buffer. Similar to the C<subbuf-rw> method:
+
+    my Buf $b .= new(1,2,3);
+    subbuf-rw($b,2,1) = Buf.new(42);
+    dd $b;        # OUTPUT: Buf $b = Buf.new(1,2,42)
+
 =end pod