txt: ## comb.md
  comb
  
  Combined from primary sources listed below.
  
  # [In IO::Handle](#___top "go to top of document")[§](#(IO::Handle)_method_comb "direct link")
  
  See primary documentation
  [in context](/type/IO/Handle#method_comb)
  for **method comb**.
  
  ```raku
  method comb(IO::Handle:D: Bool :$close, |args --> Seq:D)
  ```
  
  Read the handle and processes its contents the same way [`Str.comb`](/type/Str#routine_comb) does, taking the same arguments, closing the handle when done if `$close` is set to a true value. Implementations may slurp the file in its entirety when this method is called.
  
  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;
  say "The file has {+$fh.comb: '♥', :close} ♥s in it";
  
  ```
  
  # [In IO::Path](#___top "go to top of document")[§](#(IO::Path)_method_comb "direct link")
  
  See primary documentation
  [in context](/type/IO/Path#method_comb)
  for **method comb**.
  
  ```raku
  method comb(IO::Path:D: |args --> Seq:D)
  ```
  
  Opens the file and processes its contents the same way [`Str.comb`](/type/Str#routine_comb) 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_comb "direct link")
  
  See primary documentation
  [in context](/type/IO/CatHandle#method_comb)
  for **method comb**.
  
  ```raku
  method comb(IO::CatHandle:D: |args --> Seq:D)
  ```
  
  Read the handle and processes its contents the same way [`Str.comb`](/type/Str#routine_comb) 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).comb(2).raku.say;
  # OUTPUT: «("fo", "ob", "ar").Seq␤»
  
  ```
  
  # [In Allomorph](#___top "go to top of document")[§](#(Allomorph)_method_comb "direct link")
  
  See primary documentation
  [in context](/type/Allomorph#method_comb)
  for **method comb**.
  
  ```raku
  method comb(Allomorph:D: |c)
  ```
  
  Calls [`Str.comb`](/type/Str#routine_comb) on the invocant's [`Str`](/type/Str) value.
  
  # [In Str](#___top "go to top of document")[§](#(Str)_routine_comb "direct link")
  
  See primary documentation
  [in context](/type/Str#routine_comb)
  for **routine comb**.
  
  ```raku
  multi        comb(Str:D   $matcher, Str:D $input, $limit = Inf)
  multi        comb(Regex:D $matcher, Str:D $input, $limit = Inf, Bool :$match)
  multi        comb(Int:D $size, Str:D $input, $limit = Inf)
  multi method comb(Str:D $input:)
  multi method comb(Str:D $input: Str:D   $matcher, $limit = Inf)
  multi method comb(Str:D $input: Regex:D $matcher, $limit = Inf, Bool :$match)
  multi method comb(Str:D $input: Int:D $size, $limit = Inf)
  ```
  
  Searches for `$matcher` in `$input` and returns a [`Seq`](/type/Seq) of non-overlapping matches limited to at most `$limit` matches.
  
  If `$matcher` is a Regex, each [`Match`](/type/Match) object is converted to a `Str`, unless `$match` is set (available as of the 2020.01 release of the Rakudo compiler).
  
  If no matcher is supplied, a Seq of characters in the string is returned, as if the matcher was `rx/./`.
  
  Examples:
  
  ```raku
  say "abc".comb.raku;                 # OUTPUT: «("a", "b", "c").Seq␤»
  say "abc".comb(:match).raku;         # OUTPUT: «(｢a｣ ｢b｣ ｢c｣)␤»
  say 'abcdefghijk'.comb(3).raku;      # OUTPUT: «("abc", "def", "ghi", "jk").Seq␤»
  say 'abcdefghijk'.comb(3, 2).raku;   # OUTPUT: «("abc", "def").Seq␤»
  say comb(/\w/, "a;b;c").raku;        # OUTPUT: «("a", "b", "c").Seq␤»
  say comb(/\N/, "a;b;c").raku;        # OUTPUT: «("a", ";", "b", ";", "c").Seq␤»
  say comb(/\w/, "a;b;c", 2).raku;     # OUTPUT: «("a", "b").Seq␤»
  say comb(/\w\;\w/, "a;b;c", 2).raku; # OUTPUT: «("a;b",).Seq␤»
  say comb(/.<(.)>/, "<>[]()").raku;   # OUTPUT: «(">", "]", ")").Seq␤»
  ```
  
  If the matcher is an integer value, `comb` behaves as if the matcher was `rx/ . ** {1..$matcher} /`, but which is optimized to be much faster.
  
  Note that a Regex matcher may control which portion of the matched text is returned by using features which explicitly set the top-level capture.
  
  ```raku
  multi        comb(Pair:D $rotor, Str:D $input, $limit = Inf, Bool :$partial)
  multi method comb(Str:D $input: Pair:D $rotor, $limit = Inf, Bool :$partial)
  ```
  
  Available as of 6.e language version (early implementation exists in Rakudo compiler 2022.12+). The `rotor` pair indicates the number of characters to fetch as the key (the "size"), and the number of "steps" forward to take afterwards. Its main intended use is to provide a way to create [N-grams](https://en.wikipedia.org/wiki/N-gram) from strings in an efficient manner. By default only strings of the specified size will be produced. This can be overridden by specifying the named argument `:partial` with a true value.
  
  Examples:
  
  ```raku
  say "abcde".comb(3 => -2);             # OUTPUT: «(abc bcd cde)␤»
  say "abcde".comb(3 => -2, :partial);   # OUTPUT: «(abc bcd cde de e)␤»
  say "abcdefg".comb(3 => -2, 2);        # OUTPUT: «(abc bcd)␤»
  say comb(3 => -2, "abcde");            # OUTPUT: «(abc bcd cde)␤»
  say comb(5 => -2, "abcde", :partial);  # OUTPUT: «(abc bcd cde de e)␤»
  say comb(5 => -2, "abcdefg", 2);       # OUTPUT: «(abc bcd)␤»
  ```
  
  # [In Cool](#___top "go to top of document")[§](#(Cool)_routine_comb "direct link")
  
  See primary documentation
  [in context](/type/Cool#routine_comb)
  for **routine comb**.
  
  ```raku
  multi        comb(Regex $matcher, Cool $input, $limit = *)
  multi        comb(Str $matcher, Cool $input, $limit = *)
  multi        comb(Int:D $size, Cool $input, $limit = *)
  multi method comb(|c)
  ```
  
  Returns a [`Seq`](/type/Seq) of all (or if supplied, at most `$limit`) matches of the invocant (method form) or the second argument (sub form) against the [`Regex`](/type/Regex), string or defined number.
  
  ```raku
  say "6 or 12".comb(/\d+/).join(", ");           # OUTPUT: «6, 12␤»
  say comb(/\d <[1..9]> /,(11..30)).join("--");
  # OUTPUT:
  # «11--12--13--14--15--16--17--18--19--21--22--23--24--25--26--27--28--29␤»
  ```
  
  The second statement exemplifies the first form of `comb`, with a [`Regex`](/type/Regex) that excludes multiples of ten, and a [`Range`](/type/Range) (which is `Cool`) as `$input`. `comb` stringifies the [`Range`](/type/Range) before applying `.comb` on the resulting string. Check [`Str.comb`](/type/Str#routine_comb) for its effect on different kind of input strings. When the first argument is an integer, it indicates the (maximum) size of the chunks the input is going to be divided in
  
  ```raku
  say comb(3,[3,33,333,3333]).join("*");  # OUTPUT: «3 3*3 3*33 *333*3␤»
  ```
  
  In this case the input is a list, which after transformation to [`Str`](/type/Str) (which includes the spaces) is divided in chunks of size 3.
  