[Str] subst documentation to the style usually used here

* move to section Methods. It is a method after all
* add a signature
* add a small amount of formal description

Author: moritz

lib/Str.pod

@@ -330,6 +330,40 @@ Examples:
 
  sprintf "%ld a big number, %lld a bigger number\n", 4294967295, 4294967296;
 
+=head2 subst
+
+    multi method subst(Str:D: $matcher, $replacement, *%opts)
+
+Returns the invocant string where C<$matcher> is replaced by C<$replacement>
+(or the original string, if no match was found).
+
+There is an in-place syntactic variant of C<subst> spelled
+C<s/matcher/replacement>.
+
+C<$matcher> an be a L<Regex>, or a literal C<Str>. Non-Str matcher arguments
+of type L<Cool> are coereced to to C<Str> for literal matching.
+
+	my $some-string = "Some foo";
+	my $another-string = $some-string.subst(/foo/, "string"); # gives 'Some string'
+	$some-string.=subst(/foo/, "string); # in-place substitution. $some-string is now 'Some string'
+
+ 
+The replacement can be a closure:
+
+	my $i = 41;
+	my $str = "The answer is secret.";
+	my $real-answer = $str.subst(/secret/, {++$i}); # The answer to everything
+
+Here are other examples of usage:
+
+	my $str = "Hey foo foo foo"; 
+	$str.subst(/foo/, "bar", :g); # global substitution - returns Hey bar bar bar
+	
+	$str.subst(/foo/, "no subst", :x(0)); # targeted substitution. Number of times to substitute. Returns back unmodified.
+	$str.subst(/foo/, "bar", :x(1)); #replace just the first occurrence. 
+	
+	$str.subst(/foo/, "bar", :nth(3)); # replace nth match alone. Replaces the third foo. Returns Hey foo foo bar
+
 =head2 substr
 
     multi sub    substr(Str:D $s, Int:D $from, Int:D $chars = $s.chars - $from) returns Str:D
@@ -424,33 +458,5 @@ Remove the white-space charecters from the end of a string. See also L<trim>.
 
 Remove the white-space charecters from the beginning of a string. See also L<trim>.
 
-=head2 Substitution and replacement operations
-
-=head2 subst
-
-Does string substitution, these behave like s/// does in perl5. 
-	
-	my $some-string = "Some foo";
-	my $another-string = $some-string.subst(/foo/, "string"); # gives 'Some string'
-	$some-string.=subst(/foo/, "string); # in-place substitution. $some-string is now 'Some string'
-	
-	The syntax usually goes like this:
-		STRING_TO_REPLACE.subst(/PATTERN/, REPLACEMENT);
-	
-	In the case of subst, REPLACEMENT can also be a closure:
-	my $i = 41;
-	my $str = "The answer is secret.";
-	my $real-answer = $str.subst(/secret/, {++$i}); # The answer to everything
-	
-	Here are other examples of usage:
-	my $str = "Hey foo foo foo"; 
-	$str.subst(/foo/, "bar", :g); # global substitution - returns Hey bar bar bar
-	
-	$str.subst(/foo/, "no subst", :x(0)); # targeted substitution. Number of times to substitute. Returns back unmodified.
-	$str.subst(/foo/, "bar", :x(1)); #replace just the first occurrence. 
-	
-	$str.subst(/foo/, "bar", :nth(3)); # replace nth match alone. Replaces the third foo. Returns Hey foo foo bar
-	
-	
 =end pod