Permalink
Browse files

[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
  • Loading branch information...
1 parent 3b5dbf4 commit 4f6552be794c244770e40d3e5db12834a337e3ed @moritz moritz committed Dec 25, 2012
Showing with 34 additions and 28 deletions.
  1. +34 −28 lib/Str.pod
View
@@ -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

0 comments on commit 4f6552b

Please sign in to comment.