=begin pod

=head1  Str

    class Str is Cool does Stringy { }

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

=head2 Methods

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

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

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

=head3 uc

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

Returns an uppercase version of the string.

=head3 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)

=head3 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)

=head3 lcfirst

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

=head3 ucfirst

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

=head3 length

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

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

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

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

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

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

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

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

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

The directives are:

 %   a literal percent sign
 c   a character with the given codepoint
 s   a string
 d   a signed integer, in decimal
 u   an unsigned integer, in decimal
 o   an unsigned integer, in octal
 x   an unsigned integer, in hexadecimal
 e   a floating-point number, in scientific notation
 f   a floating-point number, in fixed decimal notation
 g   a floating-point number, in %e or %f notation
 X   like x, but using uppercase letters
 E   like e, but using an uppercase "E"
 G   like g, but with an uppercase "E" (if applicable)
 b   an unsigned integer, in binary

Compatibility:

 i   a synonym for %d
 D   a synonym for %ld
 U   a synonym for %lu
 O   a synonym for %lo
 F   a synonym for %f

Perl 5 (non-)compatibility:

 n   produces a runtime exception
 p   produces a runtime exception

Modifiers change the meaning of format directives. The most important being
support for complex numbers (a basic type in Perl). Here are all of the
modifiers and what they modify:

 h  interpret integer as native "short" (typically int16)
 l  interpret integer as native "long" (typically int32 or int64)
 ll interpret integer as native "long long" (typically int64)
 L  interpret integer as native "long long" (typically uint64)
 q  interpret integer as native "quads" (typically int64 or larger)
 m  interpret value as a complex number

The C<m> modifier works with C<d,u,o,x,F,E,G,X,E> and C<G> format
directives, and the directive applies to both the real and imaginary
parts of the complex number.

Examples:

 sprintf "%ld a big number, %lld a bigger number, %mf complexity\n",
    4294967295, 4294967296, 1+2i);

=head3 substr

    multi sub    substr(Str:D $s, Int:D $from, Int:D $chars = $s.chars - $from) returns Str:D
    multi method substr(Str:D $s: Int:D $from, Int:D $chars = $s.chars - $from) returns Str:D

Returns a part of the string, starting from the character with index C<$from>
(where the first character has index 0) and with length C<$chars>.

=head3 succ

    method succ(Str:D) returns Str:D

Returns the string incremented by one.

String increment is "magical". It searches for the last alphanumeric
sequence that is not preceeded by a dot, and increments it.

    '12.34'.succ      # 13.34
    'img001.png'.succ # img002.png

The actual incrementation step works by mapping the last alphanumeric
character to a character range it belongs to, and chosing the next
character in that range, carrying to the previous letter on overflow.

    'aa'.succ   # ab
    'az'.succ   # ba
    '109'.succ  # 110
    'α'.succ    # β
    'a9'.succ   # b0

String increment is Unicode-aware, and generally works for scripts where a
character can be uniquely classified as belonging to one range of characters.

=head3 pred

    method pred(Str:D) returns Str:D

Returns the string decremented by one.

String decrementing is "magical" just like string incrementation (see
C<Str.succ>). It fails on underflow

    'b0'.pred           # a9
    'a0'.pred           # Failure
    'img002.png'.pred   # img001.png

=end pod
