routine split

Table of Contents
1	class Cool
1.1	(Cool) routine split
2	class Str
2.1	(Str) routine split
3	class IO::CatHandle
3.1	(IO::CatHandle) method split
4	class IO::Path
4.1	(IO::Path) method split
5	class IO::Handle
5.1	(IO::Handle) method split
6	class IO::Spec::Unix
6.1	(IO::Spec::Unix) method split
7	class IO::Spec::Win32
7.1	(IO::Spec::Win32) method split
8	class IO::Spec::Cygwin
8.1	(IO::Spec::Cygwin) method split

Documentation for routine split assembled from the following types:

class Cool

From Cool

(Cool) routine split

Defined as:

multi sub    split(  Str:D $delimiter, Str(Cool) $input, $limit = Inf, :$k, :$v, :$kv, :$p, :$skip-empty)
multi sub    split(Regex:D $delimiter, Str(Cool) $input, $limit = Inf, :$k, :$v, :$kv, :$p, :$skip-empty)
multi sub    split(@delimiters, Str(Cool) $input, $limit = Inf, :$k, :$v, :$kv, :$p, :$skip-empty)
multi method split(  Str:D $delimiter, $limit = Inf, :$k, :$v, :$kv, :$p, :$skip-empty)
multi method split(Regex:D $delimiter, $limit = Inf, :$k, :$v, :$kv, :$p, :$skip-empty)
multi method split(@delimiters, $limit = Inf, :$k, :$v, :$kv, :$p, :$skip-empty)

[1]

Coerces the invocant (or in the sub form, the second argument) to Str, and splits it into pieces based on delimiters found in the string.

If $delimiter is a string, it is searched for literally and not treated as a regex. You can also provide multiple delimiters by specifying them as a list; mixing Cool and Regex objects is OK.

say split(';', "a;b;c").perl;               # OUTPUT: «("a", "b", "c")␤» 
say split(';', "a;b;c", 2).perl;            # OUTPUT: «("a", "b;c").Seq␤» 
 
say split(';', "a;b;c,d").perl;             # OUTPUT: «("a", "b", "c,d")␤» 
say split(/\;/, "a;b;c,d").perl;            # OUTPUT: «("a", "b", "c,d")␤» 
say split(/<[;,]>/, "a;b;c,d").perl;        # OUTPUT: «("a", "b", "c", "d")␤» 
 
say split(['a', /b+/, 4], '1a2bb345').perl; # OUTPUT: «("1", "2", "3", "5")␤»

By default, split omits the matches, and returns a list of only those parts of the string that did not match. Specifying one of the :k, :v, :kv, :p adverbs changes that. Think of the matches as a list that is interleaved with the non-matching parts.

The :v interleaves the values of that list, which will be either Match objects, if a Regex was used as a matcher in the split, or Str objects, if a Cool was used as matcher. If multiple delimiters are specified, Match objects will be generated for all of them, unless all of the delimiters are Cool.

say 'abc'.split(/b/, :v);               # OUTPUT: «(a ｢b｣ c)␤» 
say 'abc'.split('b', :v);               # OUTPUT: «(a b c)␤»

:k interleaves the keys, that is, the indexes:

say 'abc'.split(/b/, :k);               # OUTPUT: «(a 0 c)␤»

:kv adds both indexes and matches:

say 'abc'.split(/b/, :kv);               # OUTPUT: «(a 0 ｢b｣ c)␤»

and :p adds them as Pairs, using the same types for values as :v does:

say 'abc'.split(/b/, :p);               # OUTPUT: «(a 0 => ｢b｣ c)␤» 
say 'abc'.split('b', :p);               # OUTPUT: «(a 0 => b c)␤»

You can only use one of the :k, :v, :kv, :p adverbs in a single call to split.

Note that empty chunks are not removed from the result list. For that behavior, use the :skip-empty named argument:

say ("f,,b,c,d".split: /","/             ).perl;  # OUTPUT: «("f", "", "b", "c", "d")␤» 
say ("f,,b,c,d".split: /","/, :skip-empty).perl;  # OUTPUT: «("f", "b", "c", "d")␤»

class Str

From Str

(Str) routine split

multi sub    split(  Str:D $delimiter, Str:D $input, $limit = Inf,
  :$skip-empty, :$v, :$k, :$kv, :$p)

multi sub    split(Regex:D $delimiter, Str:D $input, $limit = Inf,
  :$skip-empty, :$v, :$k, :$kv, :$p)

multi sub    split(List:D $delimiters, Str:D $input, $limit = Inf,
  :$skip-empty, :$v, :$k, :$kv, :$p)

multi method split(Str:D:   Str:D $delimiter, $limit = Inf,
  :$skip-empty, :$v, :$k, :$kv, :$p)

multi method split(Str:D: Regex:D $delimiter, $limit = Inf,
  :$skip-empty, :$v, :$k, :$kv, :$p)

multi method split(Str:D: List:D $delimiters, $limit = Inf,
  :$skip-empty, :$v, :$k, :$kv, :$p)

Splits a string up into pieces based on delimiters found in the string.

If DELIMITER is a string, it is searched for literally and not treated as a regex. If DELIMITER is the empty string, it effectively returns all characters of the string separately (plus an empty string at the begin and at the end). If PATTERN is a regular expression, then that will be used to split up the string. If DELIMITERS is a list, then all of its elements will be considered a delimiter (either a string or a regular expression) to split the string on.

The optional LIMIT indicates in how many segments the string should be split, if possible. It defaults to Inf (or *, whichever way you look at it), which means "as many as possible". Note that specifying negative limits will not produce any meaningful results.

A number of optional named parameters can be specified, which alter the result being returned. The :v, :k, :kv and :p named parameters all perform a special action with regards to the delimiter found.

:skip-empty

If specified, do not return empty strings before or after a delimiter.

Also return the delimiter. If the delimiter was a regular expression, then this will be the associated Match object. Since this stringifies as the delimiter string found, you can always assume it is the delimiter string if you're not interested in further information about that particular match.

Also return the index of the delimiter. Only makes sense if a list of delimiters was specified: in all other cases, this will be 0.

Also return both the index of the delimiter, as well as the delimiter.

Also return the index of the delimiter and the delimiter as a Pair.

Examples:

say split(";", "a;b;c").perl;           # OUTPUT: «("a", "b", "c").Seq␤» 
say split(";", "a;b;c", :v).perl;       # OUTPUT: «("a", ";", "b", ";", "c").Seq␤» 
say split(";", "a;b;c", 2).perl;        # OUTPUT: «("a", "b;c").Seq␤» 
say split(";", "a;b;c", 2, :v).perl;    # OUTPUT: «("a", ";", "b;c").Seq␤» 
say split(";", "a;b;c,d").perl;         # OUTPUT: «("a", "b", "c,d").Seq␤» 
say split(/\;/, "a;b;c,d").perl;        # OUTPUT: «("a", "b", "c,d").Seq␤» 
say split(<; ,>, "a;b;c,d").perl;       # OUTPUT: «("a", "b", "c", "d").Seq␤» 
say split(/<[;,]>/, "a;b;c,d").perl;    # OUTPUT: «("a", "b", "c", "d").Seq␤» 
say split(<; ,>, "a;b;c,d", :k).perl;   # OUTPUT: «("a", 0, "b", 0, "c", 1, "d").Seq␤» 
say split(<; ,>, "a;b;c,d", :kv).perl;  # OUTPUT: «("a", 0, ";", "b", 0, ";", "c", 1, ",", "d").Seq␤» 
 
say "".split("x").perl;                 # OUTPUT: «("",).Seq␤» 
say "".split("x", :skip-empty).perl;    # OUTPUT: «().Seq␤» 
 
say "abcde".split("").perl;             # OUTPUT: «("", "a", "b", "c", "d", "e", "").Seq␤» 
say "abcde".split("",:skip-empty).perl; # OUTPUT: «("a", "b", "c", "d", "e").Seq␤»

class IO::CatHandle

From IO::CatHandle

(IO::CatHandle) method split

Defined as:

method split(IO::CatHandle:D: |args --> Seq:D)

Read the handle and processes its contents the same way Str.split does, taking the same arguments. Implementations may slurp the contents of all the source handles in their entirety when this method is called.

(my $f1 = 'foo'.IO).spurt: 'foo';
(my $f2 = 'bar'.IO).spurt: 'bar';
IO::CatHandle.new($f1, $f2).split(/o+/).perl.say;
# OUTPUT: «("f", "bar").Seq␤»

class IO::Path

From IO::Path

(IO::Path) method split

Defined as:

method split(IO::Path:D: |args --> Seq:D)

Opens the file and processes its contents the same way Str.split does, taking the same arguments. Implementations may slurp the file in its entirety when this method is called.

class IO::Handle

From IO::Handle

(IO::Handle) method split

Defined as:

method split(IO::Handle:D: :$close, |c)

Slurps the handle's content and calls Str.split on it, forwarding any of the given arguments. If :$close named parameter is set to True, will close the invocant after slurping.

Attempting to call this method when the handle is in binary mode will result in X::IO::BinaryMode exception being thrown.

my $fh = 'path/to/file'.IO.open;
$fh.split: '♥', :close; # Returns file content split on ♥

class IO::Spec::Unix

From IO::Spec::Unix

(IO::Spec::Unix) method split

Defined as:

method split(Cool:D $path --> List:D)

Splits the given $path into "volume", "dirname", and "basename" and returns the result as a List of three Pairs, in that order. The "volume" is always an empty string and exists for consistency with other IO::Spec classes.

IO::Spec::Unix.split('C:/foo/bar.txt').perl.say;
# OUTPUT: «(:volume(""), :dirname("C:/foo"), :basename("bar.txt"))␤» 
 
IO::Spec::Unix.split('/foo/').perl.say;
# OUTPUT: «(:volume(""), :dirname("/"), :basename("foo"))␤» 
 
IO::Spec::Unix.split('///').perl.say;
# OUTPUT: «(:volume(""), :dirname("/"), :basename("/"))␤» 
 
IO::Spec::Unix.split('./').perl.say;
# OUTPUT: «(:volume(""), :dirname("."), :basename("."))␤» 
 
IO::Spec::Unix.split('.').perl.say;
# OUTPUT: «(:volume(""), :dirname("."), :basename("."))␤» 
 
IO::Spec::Unix.split('').perl.say;
# OUTPUT: «(:volume(""), :dirname(""), :basename(""))␤»

class IO::Spec::Win32

From IO::Spec::Win32

(IO::Spec::Win32) method split

Defined as:

method split(Cool:D $path --> List:D)

IO::Spec::Win32.split('C:/foo/bar.txt').perl.say;
# OUTPUT: «(:volume("C:"), :dirname("/foo"), :basename("bar.txt"))␤» 
 
IO::Spec::Win32.split('/foo/').perl.say;
# OUTPUT: «(:volume(""), :dirname("/"), :basename("foo"))␤» 
 
IO::Spec::Win32.split('///').perl.say;
# OUTPUT: «(:volume(""), :dirname("/"), :basename("\\"))␤» 
 
IO::Spec::Win32.split('./').perl.say;
# OUTPUT: «(:volume(""), :dirname("."), :basename("."))␤» 
 
IO::Spec::Win32.split('.').perl.say;
# OUTPUT: «(:volume(""), :dirname("."), :basename("."))␤» 
 
IO::Spec::Win32.split('').perl.say;
# OUTPUT: «(:volume(""), :dirname(""), :basename(""))␤»

class IO::Spec::Cygwin

From IO::Spec::Cygwin

(IO::Spec::Cygwin) method split

Defined as:

method split(|c --> List:D)

Same as IO::Spec::Win32.split, except replaces backslashes with slashes in all the values of the final result.