[doc] Add /some/ documentation for .subst

lib/Str.pod

@@ -424,4 +424,33 @@ 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
+