<commit_before>=begin pod

=TITLE class Str

    class Str is Cool does Stringy { }

Built-in class for strings. Objects of type C<Str> are immutable.

=head1 Methods

=head2  chop

    multi sub    chop(Str:D)  returns Str:D
    multi method chop(Str:D:) returns Str:D

Returns the string with one character removed from the end.

=head2  chomp

    multi sub    chomp(Str:D ) returns Str:D
    multi method chomp(Str:D:) returns Str:D

Returns the string with a logical newline removed from the end.

=head2 lc

    multi sub    lc(Str:D ) returns Str:D
    multi method lc(Str:D:) returns Str:D

Returns a lower-case version of the string.

=head2 uc

    multi sub    uc(Str:D ) returns Str:D
    multi method uc(Str:D:) returns Str:D

Returns an uppercase version of the string.

=head2 fc

    multi sub    fc(Str:D ) returns Str:D
    multi method fc(Str:D:) returns Str:D 

Does a Unicode "fold case" operation suitable for doing caseless
string comparisons.  (In general, the returned string is unlikely to
be useful for any purpose other than comparison.)

(Not implemented in Rakudo and Niecza)

=head2 titlecase

    multi sub    titlecase(Str:D  :&filter = &lc, :%exceptions = set()) returns Str
    multi method titlecase(Str:D: :&filter = &lc, :%exceptions = set()) returns Str

Performs a Unicode titlecase operation on the first character of
each word of the string (as defined by a regex C<«> boundary),
and forces the rest of the letters through a filter that defaults
to C<lc>.  After this operation, if any exceptions are supplied and
if the word is found in the set of exceptions, the first character is also
forced through the filter.  Note that the exceptions must be spelled with
an initial titlecase, such as "By" or "And", to produce "by" or "and".

(Not implemented in Rakudo and Niecza)

=head2 lcfirst

Perl 6 does not have a C<lcfirst> function.  See X<titlecase>.

=head2 ucfirst

Perl 6 does not have a C<ucfirst> function.  See X<titlecase>.

=head2 length

Perl 6 does not have a C<length> function.  See X<chars> or X<elems>.

=head2 chars

    multi sub    chars(Str:D ) returns Int:D
    multi method chars(Str:D:) returns Int:D

Returns the number of characters in the string in the current
(lexically scoped) idea of what a normal character is, usually graphemes.

=head2 encode

    multi method encode(Str:D: $encoding = $?ENC, $nf = $?NF) returns Buf

Returns a C<Buf> which represents the original string in the given encoding
and normal form. The actual return type is as specific as possible, so
C<$str.encode('UTF-8')> returns a C<utf8> object,
C<$str.encode('ISO-8859-1')> a C<buf8>.

=head2 index

    multi sub    index(Str:D, Str:D $needle, Int $startpos = 0) returns StrPos
    multi method index(Str:D: Str:D $needle, Int $startpos = 0) returns StrPos

Searches for C<$needle> in the string starting from C<$startpos>. It returns
the offset into the string where C<$needle> was found, and an undefined value
if it was not found.

=head2 rindex

    multi sub    rindex(Str:D $haystack, Str:D $needle, Int $startpos = $haystack.chars) returns StrPos
    multi method rindex(Str:D $haystack: Str:D $needle, Int $startpos = $haystack.chars) returns StrPos

Returns the last position of C<$needle> in C<$haystack> not after C<$startpos>.
Returns an undefined value if C<$needle> wasn't found.

=head2 split

    multi sub    split(  Str:D $delimiter, Str:D $input, $limit = Inf, :$all) returns Positional
    multi sub    split(Regex:D $delimiter, Str:D $input, $limit = Inf, :$all) returns Positional

    multi method split(Str:D $input:   Str:D $delimiter, $limit = Inf, :$all) returns Positional
    multi method split(Str:D $input: Regex:D $delimiter, $limit = Inf, :$all) returns Positional

Splits a string up 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 C<Str.comb> instead.

=head2 comb

    multi sub    comb(Str:D   $matcher, Str:D $input, $limit = Inf, Bool :$match) 
    multi sub    comb(Regex:D $matcher, Str:D $input, $limit = Inf, Bool :$match) 
    multi method comb(Str:D $input:)
    multi method comb(Str:D $input: Str:D   $matcher, $limit = Inf, Bool :$match) 
    multi method comb(Str:D $input: Regex:D $matcher, $limit = Inf, Bool :$match) 

Searches for C<$matcher> in C<$input> and returns a list of all matches
(as C<Str> by default, or as C<Match> if C<$match> is True), limited to at most
C<$limit> matches.

If no matcher is supplied, a list of characters in the string
(ie C<$delimiter = rx/./>) is returned.

=head2 lines

    multi sub    lines(Str:D $input, $limit = Inf) returns Positional
    multi method lines(Str:D $input: $limit = Inf) returns Positional

Returns a list of lines (without trailing newline characters), i.e. the
same as a call to C<$input.comb( / ^^ \N* /, $limit )> would.

=item words

    multi sub    words(Str:D $input, $limit = Inf) returns Positional
    multi method words(Str:D $input: $limit = Inf) returns Positional

Returns a list of non-whitespace bits, i.e. the same as a call to
C<$input.comb( / \S+ /, $limit )> would.

=item flip

    multi sub    flip(Str:D ) returns Str:D
    multi method flip(Str:D:) returns Str:D

Returns the string reversed character by character.

=head2 sprintf

 multi sub sprintf ( Str:D $format, *@args) returns Str:D

This function is mostly identical to the C library sprintf function.

The C<$format> is scanned for C<%> characters. Any C<%> introduces a
format token. Format tokens have the following grammar:

 grammar Str::SprintfFormat {
  regex format_token { '%': <index>? <precision>? <modifier>? <directive> }
  token index { \d+ '$' }
  token precision { <flags>? <vector>? <precision_count> }
  token flags { <[ \x20 + 0 \# \- ]>+ }
  token precision_count { [ <[1..9]>\d* | '*' ]? [ '.' [ \d* | '*' ] ]? }
  token vector { '*'? v }
  token modifier { < ll l h m V q L > }
  token directive { < % c s d u o x e f g X E G b p n i D U O F > }
 }

Directives guide the use (if any) of the arguments. When a directive
(other than C<%>) is used, it indicates how the next argument
passed is to be formatted into the string.
<commit_msg>[Str] make pod for words and flip more consistent<commit_after>=begin pod

=TITLE class Str

    class Str is Cool does Stringy { }

Built-in class for strings. Objects of type C<Str> are immutable.

=head1 Methods

=head2  chop

    multi sub    chop(Str:D)  returns Str:D
    multi method chop(Str:D:) returns Str:D

Returns the string with one character removed from the end.

=head2  chomp

    multi sub    chomp(Str:D ) returns Str:D
    multi method chomp(Str:D:) returns Str:D

Returns the string with a logical newline removed from the end.

=head2 lc

    multi sub    lc(Str:D ) returns Str:D
    multi method lc(Str:D:) returns Str:D

Returns a lower-case version of the string.

=head2 uc

    multi sub    uc(Str:D ) returns Str:D
    multi method uc(Str:D:) returns Str:D

Returns an uppercase version of the string.

=head2 fc

    multi sub    fc(Str:D ) returns Str:D
    multi method fc(Str:D:) returns Str:D 

Does a Unicode "fold case" operation suitable for doing caseless
string comparisons.  (In general, the returned string is unlikely to
be useful for any purpose other than comparison.)

(Not implemented in Rakudo and Niecza)

=head2 titlecase

    multi sub    titlecase(Str:D  :&filter = &lc, :%exceptions = set()) returns Str
    multi method titlecase(Str:D: :&filter = &lc, :%exceptions = set()) returns Str

Performs a Unicode titlecase operation on the first character of
each word of the string (as defined by a regex C<«> boundary),
and forces the rest of the letters through a filter that defaults
to C<lc>.  After this operation, if any exceptions are supplied and
if the word is found in the set of exceptions, the first character is also
forced through the filter.  Note that the exceptions must be spelled with
an initial titlecase, such as "By" or "And", to produce "by" or "and".

(Not implemented in Rakudo and Niecza)

=head2 lcfirst

Perl 6 does not have a C<lcfirst> function.  See X<titlecase>.

=head2 ucfirst

Perl 6 does not have a C<ucfirst> function.  See X<titlecase>.

=head2 length

Perl 6 does not have a C<length> function.  See X<chars> or X<elems>.

=head2 chars

    multi sub    chars(Str:D ) returns Int:D
    multi method chars(Str:D:) returns Int:D

Returns the number of characters in the string in the current
(lexically scoped) idea of what a normal character is, usually graphemes.

=head2 encode

    multi method encode(Str:D: $encoding = $?ENC, $nf = $?NF) returns Buf

Returns a C<Buf> which represents the original string in the given encoding
and normal form. The actual return type is as specific as possible, so
C<$str.encode('UTF-8')> returns a C<utf8> object,
C<$str.encode('ISO-8859-1')> a C<buf8>.

=head2 index

    multi sub    index(Str:D, Str:D $needle, Int $startpos = 0) returns StrPos
    multi method index(Str:D: Str:D $needle, Int $startpos = 0) returns StrPos

Searches for C<$needle> in the string starting from C<$startpos>. It returns
the offset into the string where C<$needle> was found, and an undefined value
if it was not found.

=head2 rindex

    multi sub    rindex(Str:D $haystack, Str:D $needle, Int $startpos = $haystack.chars) returns StrPos
    multi method rindex(Str:D $haystack: Str:D $needle, Int $startpos = $haystack.chars) returns StrPos

Returns the last position of C<$needle> in C<$haystack> not after C<$startpos>.
Returns an undefined value if C<$needle> wasn't found.

=head2 split

    multi sub    split(  Str:D $delimiter, Str:D $input, $limit = Inf, :$all) returns Positional
    multi sub    split(Regex:D $delimiter, Str:D $input, $limit = Inf, :$all) returns Positional

    multi method split(Str:D $input:   Str:D $delimiter, $limit = Inf, :$all) returns Positional
    multi method split(Str:D $input: Regex:D $delimiter, $limit = Inf, :$all) returns Positional

Splits a string up 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 C<Str.comb> instead.

=head2 comb

    multi sub    comb(Str:D   $matcher, Str:D $input, $limit = Inf, Bool :$match) 
    multi sub    comb(Regex:D $matcher, Str:D $input, $limit = Inf, Bool :$match) 
    multi method comb(Str:D $input:)
    multi method comb(Str:D $input: Str:D   $matcher, $limit = Inf, Bool :$match) 
    multi method comb(Str:D $input: Regex:D $matcher, $limit = Inf, Bool :$match) 

Searches for C<$matcher> in C<$input> and returns a list of all matches
(as C<Str> by default, or as C<Match> if C<$match> is True), limited to at most
C<$limit> matches.

If no matcher is supplied, a list of characters in the string
(ie C<$delimiter = rx/./>) is returned.

=head2 lines

    multi sub    lines(Str:D $input, $limit = Inf) returns Positional
    multi method lines(Str:D $input: $limit = Inf) returns Positional

Returns a list of lines (without trailing newline characters), i.e. the
same as a call to C<$input.comb( / ^^ \N* /, $limit )> would.

=head2 words

    multi sub    words(Str:D $input, $limit = Inf) returns Positional
    multi method words(Str:D $input: $limit = Inf) returns Positional

Returns a list of non-whitespace bits, i.e. the same as a call to
C<$input.comb( / \S+ /, $limit )> would.

=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.

=head2 sprintf

 multi sub sprintf ( Str:D $format, *@args) returns Str:D

This function is mostly identical to the C library sprintf function.

The C<$format> is scanned for C<%> characters. Any C<%> introduces a
format token. Format tokens have the following grammar:

 grammar Str::SprintfFormat {
  regex format_token { '%': <index>? <precision>? <modifier>? <directive> }
  token index { \d+ '$' }
  token precision { <flags>? <vector>? <precision_count> }
  token flags { <[ \x20 + 0 \# \- ]>+ }
  token precision_count { [ <[1..9]>\d* | '*' ]? [ '.' [ \d* | '*' ] ]? }
  token vector { '*'? v }
  token modifier { < ll l h m V q L > }
  token directive { < % c s d u o x e f g X E G b p n i D U O F > }
 }

Directives guide the use (if any) of the arguments. When a directive
(other than C<%>) is used, it indicates how the next argument
passed is to be formatted into the string.

{'fraction_non_alphanumeric': 0.10138177301661233, 'fraction_numerical': 0.0058997050147492625, 'mean_word_length': 3.734656376332231, 'pattern_counts': {'":': 0, '<': 103, '<?xml version=': 0, '>': 103, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 6, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7002607', 'n_tokens_mistral': 4267, 'n_tokens_neox': 4101, 'n_words': 1816}