more Str examples

Author: szabgab

lib/Str.pod

@@ -199,6 +199,13 @@ C<$limit> matches.
 If no matcher is supplied, a list of characters in the string
 (ie C<$delimiter = rx/./>) is returned.
 
+Examples:
+
+    comb(/\w/, "a;b;c").perl;        # ("a", "b", "c").list
+    comb(/\N/, "a;b;c").perl;        # ("a", ";", "b", ";", "c").list
+    comb(/\w/, "a;b;c", 2).perl;     # ("a", "b").list
+    comb(/\w\;\w/, "a;b;c", 2).perl; # ("a;b",).list
+
 =head2 lines
 
     multi sub    lines(Str:D $input, $limit = Inf) returns Positional
@@ -207,6 +214,14 @@ If no matcher is supplied, a list of characters in the string
 Returns a list of lines (without trailing newline characters), i.e. the
 same as a call to C<$input.comb( / ^^ \N* /, $limit )> would.
 
+Examples:
+
+    lines("a\nb").perl;    # ("a", "b").list
+    lines("a\nb").elems;   # 2
+    "a\nb".lines.elems;    # 2
+
+	"a\n".lines.elems;     # 1
+
 =head2 words
 
     multi sub    words(Str:D $input, $limit = Inf) returns Positional
@@ -215,13 +230,25 @@ same as a call to C<$input.comb( / ^^ \N* /, $limit )> would.
 Returns a list of non-whitespace bits, i.e. the same as a call to
 C<$input.comb( / \S+ /, $limit )> would.
 
+Examples:
+
+    "a\nb\n".words.perl;       # ("a", "b").list
+    "hello world".words.perl;  # ("hello", "world").list
+    "foo:bar".words.perl;      # ("foo:bar",).list
+    "foo:bar\tbaz".words.perl; # ("foo:bar", "baz").list
+
 =head2 flip
 
     multi sub    flip(Str:D ) returns Str:D
     multi method flip(Str:D:) returns Str:D
 
 Returns the string reversed character by character.
 
+Examples:
+
+    "Perl".flip;  # lreP
+    "ABBA".flip;  # ABBA
+
 =head2 sprintf
 
  multi sub sprintf ( Str:D $format, *@args) returns Str:D
@@ -297,6 +324,13 @@ Examples:
 Returns a part of the string, starting from the character with index C<$from>
 (where the first character has index 0) and with length C<$chars>.
 
+Examples:
+
+    substr("Long string", 6, 3);     # tri
+    substr("Long string", 6);        # tring
+    substr("Long string", 6, *-1);   # trin
+    substr("Long string", *-3, *-1); # in
+
 =head2 succ
 
     method succ(Str:D) returns Str:D