txt: ## split.md
  split
  
  Combined from primary sources listed below.
  
  # [In IO::Handle](#___top "go to top of document")[§](#(IO::Handle)_method_split "direct link")
  
  See primary documentation
  [in context](/type/IO/Handle#method_split)
  for **method split**.
  
  ```raku
  method split(IO::Handle:D: :$close, |c)
  ```
  
  [Slurps](/routine/slurp) the handle's content and calls [`Str.split`](/type/Str#routine_split) on it, forwarding any of the given arguments. If `:$close` named parameter is set to `True`, will [close](/routine/close) the invocant after slurping.
  
  Attempting to call this method when the handle is [in binary mode](/type/IO/Handle#method_encoding) will result in [`X::IO::BinaryMode`](/type/X/IO/BinaryMode) exception being thrown.
  
  ```raku
  my $fh = 'path/to/file'.IO.open;
  $fh.split: '♥', :close; # Returns file content split on ♥
  
  ```
  
  # [In IO::Spec::Cygwin](#___top "go to top of document")[§](#(IO::Spec::Cygwin)_method_split "direct link")
  
  See primary documentation
  [in context](/type/IO/Spec/Cygwin#method_split)
  for **method split**.
  
  ```raku
  method split(IO::Spec::Cygwin: Cool:D $path)
  ```
  
  Same as [`IO::Spec::Win32.split`](/type/IO/Spec/Win32#method_split), except it replaces backslashes with slashes in all the values of the final result.
  
  # [In IO::Spec::Unix](#___top "go to top of document")[§](#(IO::Spec::Unix)_method_split "direct link")
  
  See primary documentation
  [in context](/type/IO/Spec/Unix#method_split)
  for **method split**.
  
  ```raku
  method split(IO::Spec::Unix: Cool:D $path)
  ```
  
  Creates an [`IO::Path::Parts`](/type/IO/Path/Parts) for `$path`, with an empty string as its `volume` attribute's value.
  
  ```raku
  IO::Spec::Unix.split('C:/foo/bar.txt').raku.say;
  # OUTPUT: «IO::Path::Parts.new("","C:/foo","bar.txt")␤»
  
  IO::Spec::Unix.split('/foo/').raku.say;
  # OUTPUT: «IO::Path::Parts.new("","/","foo")␤»
  
  IO::Spec::Unix.split('///').raku.say;
  # OUTPUT: «IO::Path::Parts.new("","/","/")␤»
  
  IO::Spec::Unix.split('./').raku.say;
  # OUTPUT: «IO::Path::Parts.new("",".",".")␤»
  
  IO::Spec::Unix.split('.').raku.say;
  # OUTPUT: «IO::Path::Parts.new("",".",".")␤»
  
  IO::Spec::Unix.split('').raku.say;
  # OUTPUT: «IO::Path::Parts.new("","","")␤»
  
  ```
  
  **Note**: Before Rakudo version 2020.06 this method split the given `$path` into "volume", "dirname", and "basename" and returned the result as a [`List`](/type/List) of three [`Pair`](/type/Pair)s, in that order.
  
  # [In Supply](#___top "go to top of document")[§](#(Supply)_method_split "direct link")
  
  See primary documentation
  [in context](/type/Supply#method_split)
  for **method split**.
  
  ```raku
  multi method split(Supply:D: \delimiter)
  multi method split(Supply:D: \delimiter, \limit)
  ```
  
  This method creates a supply of the values returned by the `Str.split` method called on the string collected from the invocant. See [`Str.split`](/type/Str#routine_split) for details on the `\delimiter` argument as well as available extra named parameters. The created supply can be limited with the `\limit` argument, see [`.head`](#method_head).
  
  ```raku
  my $words = Supply.from-list(<Hello World From Raku!>);
  my $s = $words.split(/ <?upper> /, 2, :skip-empty);
  $s.tap(&say); # OUTPUT: «Hello␤World␤»
  ```
  
  # [In IO::Path](#___top "go to top of document")[§](#(IO::Path)_method_split "direct link")
  
  See primary documentation
  [in context](/type/IO/Path#method_split)
  for **method split**.
  
  ```raku
  method split(IO::Path:D: |args --> Seq:D)
  ```
  
  Opens the file and processes its contents the same way [`Str.split`](/type/Str#routine_split) does, taking the same arguments. Implementations may slurp the file in its entirety when this method is called.
  
  # [In IO::CatHandle](#___top "go to top of document")[§](#(IO::CatHandle)_method_split "direct link")
  
  See primary documentation
  [in context](/type/IO/CatHandle#method_split)
  for **method split**.
  
  ```raku
  method split(IO::CatHandle:D: |args --> Seq:D)
  ```
  
  Read the handle and processes its contents the same way [`Str.split`](/type/Str#routine_split) does, taking the same arguments. **Implementations may slurp the contents of all the source handles** in their entirety when this method is called.
  
  ```raku
  (my $f1 = 'foo'.IO).spurt: 'foo';
  (my $f2 = 'bar'.IO).spurt: 'bar';
  IO::CatHandle.new($f1, $f2).split(/o+/).raku.say;
  # OUTPUT: «("f", "bar").Seq␤»
  
  ```
  
  # [In Allomorph](#___top "go to top of document")[§](#(Allomorph)_method_split "direct link")
  
  See primary documentation
  [in context](/type/Allomorph#method_split)
  for **method split**.
  
  ```raku
  method split(Allomorph:D: |c)
  ```
  
  Calls [`Str.split`](/type/Str#routine_split) on the invocant's [`Str`](/type/Str) value.
  
  # [In Str](#___top "go to top of document")[§](#(Str)_routine_split "direct link")
  
  See primary documentation
  [in context](/type/Str#routine_split)
  for **routine split**.
  
  ```raku
  multi        split(  Str:D $delimiter, Str:D $input, $limit = Inf,
    :$skip-empty, :$v, :$k, :$kv, :$p)
  
  ```
  
  ```raku
  multi        split(Regex:D $delimiter, Str:D $input, $limit = Inf,
    :$skip-empty, :$v, :$k, :$kv, :$p)
  
  ```
  
  ```raku
  multi        split(List:D $delimiters, Str:D $input, $limit = Inf,
    :$skip-empty, :$v, :$k, :$kv, :$p)
  
  ```
  
  ```raku
  multi method split(Str:D:   Str:D $delimiter, $limit = Inf,
    :$skip-empty, :$v, :$k, :$kv, :$p)
  
  ```
  
  ```raku
  multi method split(Str:D: Regex:D $delimiter, $limit = Inf,
    :$skip-empty, :$v, :$k, :$kv, :$p)
  
  ```
  
  ```raku
  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.
  
  * :v
  
  Also return the delimiter. If the delimiter was a regular expression, then this will be the associated [`Match`](/type/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.
  
  * :k
  
  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**.
  
  * :kv
  
  Also return both the **index** of the delimiter, as well as the delimiter.
  
  * :p
  
  Also return the **index** of the delimiter and the delimiter as a [`Pair`](/type/Pair).
  
  Examples:
  
  ```raku
  say split(";", "a;b;c").raku;           # OUTPUT: «("a", "b", "c").Seq␤»
  say split(";", "a;b;c", :v).raku;       # OUTPUT: «("a", ";", "b", ";", "c").Seq␤»
  say split(";", "a;b;c", 2).raku;        # OUTPUT: «("a", "b;c").Seq␤»
  say split(";", "a;b;c", 2, :v).raku;    # OUTPUT: «("a", ";", "b;c").Seq␤»
  say split(";", "a;b;c,d").raku;         # OUTPUT: «("a", "b", "c,d").Seq␤»
  say split(/\;/, "a;b;c,d").raku;        # OUTPUT: «("a", "b", "c,d").Seq␤»
  say split(<; ,>, "a;b;c,d").raku;       # OUTPUT: «("a", "b", "c", "d").Seq␤»
  say split(/<[;,]>/, "a;b;c,d").raku;    # OUTPUT: «("a", "b", "c", "d").Seq␤»
  say split(<; ,>, "a;b;c,d", :k).raku;   # OUTPUT: «("a", 0, "b", 0, "c", 1, "d").Seq␤»
  say split(<; ,>, "a;b;c,d", :kv).raku;  # OUTPUT: «("a", 0, ";", "b", 0, ";", "c", 1, ",", "d").Seq␤»
  
  say "".split("x").raku;                 # OUTPUT: «("",).Seq␤»
  say "".split("x", :skip-empty).raku;    # OUTPUT: «().Seq␤»
  
  say "abcde".split("").raku;             # OUTPUT: «("", "a", "b", "c", "d", "e", "").Seq␤»
  say "abcde".split("",:skip-empty).raku; # OUTPUT: «("a", "b", "c", "d", "e").Seq␤»
  ```
  
  # [In Cool](#___top "go to top of document")[§](#(Cool)_routine_split "direct link")
  
  See primary documentation
  [in context](/type/Cool#routine_split)
  for **routine split**.
  
  ```raku
  multi        split(  Str:D $delimiter, Str(Cool) $input, $limit = Inf, :$k, :$v, :$kv, :$p, :$skip-empty)
  multi        split(Regex:D $delimiter, Str(Cool) $input, $limit = Inf, :$k, :$v, :$kv, :$p, :$skip-empty)
  multi        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]](#fn1)
  
  Coerces the invocant (or in the sub form, the second argument) to [`Str`](/type/Str), splits it into pieces based on delimiters found in the string and returns the result as a [`Seq`](/type/Seq).
  
  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, which can mix `Cool` and [`Regex`](/type/Regex) objects.
  
  ```raku
  say split(';', "a;b;c").raku;               # OUTPUT: «("a", "b", "c").Seq␤»
  say split(';', "a;b;c", 2).raku;            # OUTPUT: «("a", "b;c").Seq␤»
  
  say split(';', "a;b;c,d").raku;             # OUTPUT: «("a", "b", "c,d").Seq␤»
  say split(/\;/, "a;b;c,d").raku;            # OUTPUT: «("a", "b", "c,d").Seq␤»
  say split(/<[;,]>/, "a;b;c,d").raku;        # OUTPUT: «("a", "b", "c", "d").Seq␤»
  
  say split(['a', /b+/, 4], '1a2bb345').raku; # OUTPUT: «("1", "2", "3", "5").Seq␤»
  ```
  
  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`](/type/Match) objects, if a [`Regex`](/type/Regex) was used as a matcher in the split, or [`Str`](/type/Str) objects, if a `Cool` was used as matcher. If multiple delimiters are specified, [`Match`](/type/Match) objects will be generated for all of them, unless **all** of the delimiters are `Cool`.
  
  ```raku
  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:
  
  ```raku
  say 'abc'.split(/b/, :k);               # OUTPUT: «(a 0 c)␤»
  ```
  
  `:kv` adds both indexes and matches:
  
  ```raku
  say 'abc'.split(/b/, :kv);               # OUTPUT: «(a 0 ｢b｣ c)␤»
  ```
  
  and `:p` adds them as [`Pair`](/type/Pair)s, using the same types for values as `:v` does:
  
  ```raku
  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:
  
  ```raku
  say ("f,,b,c,d".split: /","/             ).raku;  # OUTPUT: «("f", "", "b", "c", "d").Seq␤»
  say ("f,,b,c,d".split: /","/, :skip-empty).raku;  # OUTPUT: «("f", "b", "c", "d").Seq␤»
  ```
  
  # [In IO::Spec::Win32](#___top "go to top of document")[§](#(IO::Spec::Win32)_method_split "direct link")
  
  See primary documentation
  [in context](/type/IO/Spec/Win32#method_split)
  for **method split**.
  
  ```raku
  method split(IO::Spec::Win32: Cool:D $path)
  ```
  
  Creates an [`IO::Path::Parts`](/type/IO/Path/Parts) for `$path`.
  
  ```raku
  IO::Spec::Win32.split('C:/foo/bar.txt').raku.say;
  # OUTPUT: «IO::Path::Parts.new("C:","/foo","bar.txt")␤»
  
  IO::Spec::Win32.split('/foo/').raku.say;
  # OUTPUT: «IO::Path::Parts.new("","/","foo")␤»
  
  IO::Spec::Win32.split('///').raku.say;
  # OUTPUT: «IO::Path::Parts.new("","/","\\")␤»
  
  IO::Spec::Win32.split('./').raku.say;
  # OUTPUT: «IO::Path::Parts.new("",".",".")␤»
  
  IO::Spec::Win32.split('.').raku.say;
  # OUTPUT: «IO::Path::Parts.new("",".",".")␤»
  
  IO::Spec::Win32.split('').raku.say;
  # OUTPUT: «IO::Path::Parts.new("","","")␤»
  
  ```
  
  **Note**: Before Rakudo version 2020.06 this method split the given `$path` into "volume", "dirname", and "basename" and returned the result as a [`List`](/type/List) of three [`Pair`](/type/Pair)s, in that order.
  