Document Cool.split

Author: moritz

lib/Type/Cool.pod

@@ -542,6 +542,35 @@ Unicode codepoint, and joining the characters.
 
 This is the list-input version of L<chr>. The inverse operation is L<ords>.
 
+=head2 routine split
+
+    multi method split(  Str:D $delimiter, $limit = Inf, :$all)
+    multi method split(Regex:D $delimiter, $limit = Inf, :$all)
+    multi sub    split(  Str:D $delimiter, Str(Cool) $input, $limit = Inf, :$all)
+    multi sub    split(Regex:D $delimiter, Str(Cool) $input, $limit = Inf, :$all)
+
+Coerces the invocant (or in the sub form, the second argument) to
+L<Str|/type/Str>, and splits it into pieces based on delimiters found in the
+string.
+
+If C<$delimiter> is a string, it is searched for literally and not treated
+as a regex.
+
+If the named parameter C<:all> is passed, the matches from C<$delimiter>
+are included in the result list.
+
+Note that unlike in Perl 5, empty chunks are not removed from the result list.
+If you want that behavior, consider using L<comb> instead.
+
+    say split(';', "a;b;c").perl;          # ("a", "b", "c").list
+    say split(';', "a;b;c", :all).perl;    # ("a", ";", "b", ";", "c").list
+    say split(';', "a;b;c", 2).perl;       # ("a", "b;c").list
+    say split(';', "a;b;c", 2, :all).perl; #("a", ";", "b;c").list
+
+    say split(';', "a;b;c,d").perl;        # ("a", "b", "c,d").list
+    say split(/\;/, "a;b;c,d").perl;       # ("a", "b", "c,d").list
+    say split(/<[;,]>/, "a;b;c,d").perl;   # ("a", "b", "c", "d").list
+
 =head2 method words
 
     method words(Int() $limit)
@@ -570,7 +599,7 @@ Coerces the invocant to L<IO::Path>.
 TODO: sech, asech, cosech, acosech, cotanh, acotanh, cis, roots, log10,
 unpolar, truncate, fmt, substr-rw,
 trans, index, rindex,
-split, match, comb, lines, subst, sprintf, printf, samecase,
+match, comb, lines, subst, sprintf, printf, samecase,
 EVAL
 
 TODO: subroutine forms (where they exist)