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

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

Does a Unicode "titlecase" operation, that is changes the first character in
the string to title case, or to upper case if the character has no title case
mapping

(Not implemented in Rakudo and Niecza)

=head2 tclc

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

Turns the first character to title case, and all other characters to lower
case

(not implemented in Niecza)

=head2 tcuc

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

Turns the first character to title case, and all other characters to upper
case

(Not implemented in Rakudo and Niecza)

=head2 wordcase

    multi sub    wordcase(Str:D  :&filter = &lc, :%exceptions = set()) returns Str
    multi method wordcase(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 L<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.

=head2 ucfirst

Perl 6 does not have a C<ucfirst> function.  See L<tc>.

=head2 length

Perl 6 does not have a C<length> function.  See L<chars> or L<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 L<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.

Examples:

    say index "Camelia is a butterfly", "a";     # 1
    say index "Camelia is a butterfly", "a", 2;  #6
    say index "Camelia is a butterfly", "er";    # 17
    say index "Camelia is a butterfly", "Camel"; # 0
    say index "Camelia is a butterfly", "Onion"; # Int()

    say index("Camelia is a butterfly", "Onion").defined ?? 'OK' !! 'NOT'; # NOT

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

Examples:

    say rindex "Camelia is a butterfly", "a";     # 11
    say rindex "Camelia is a butterfly", "a", 10; # 6

=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 L<comb> instead.

Examples:

    say split(';', "a;b;c").perl;          # ("a", "b", "c").list
    say split(';', "a;b;c", :all).perl;    # ("a", ";", "b", ";", "c").list
    say split(';', "a;b;c", 2).perl;       # ("a", "b;c").list
    say split(';', "a;b;c", 2, :all).perl; #("a", ";", "b;c").list

    say split(';', "a;b;c,d").perl;        # ("a", "b", "c,d").list
    say split(/\;/, "a;b;c,d").perl;       # ("a", "b", "c,d").list
    say split(/<[;,]>/, "a;b;c,d").perl;   # ("a", "b", "c", "d").list

=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 L<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
(e.g. C<$delimiter = rx/./>) is returned.

Examples:

    comb(/\w/, "a;b;c").perl;        # ("a", "b", "c").list
    comb(/\N/, "a;b;c").perl;        # ("a", ";", "b", ";", "c").list
    comb(/\w/, "a;b;c", 2).perl;     # ("a", "b").list
    comb(/\w\;\w/, "a;b;c", 2).perl; # ("a;b",).list

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

Examples:

    lines("a\nb").perl;    # ("a", "b").list
    lines("a\nb").elems;   # 2
    "a\nb".lines.elems;    # 2
    "a\n".lines.elems;     # 1

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

Examples:

    "a\nb\n".words.perl;       # ("a", "b").list
    "hello world".words.perl;  # ("hello", "world").list
    "foo:bar".words.perl;      # ("foo:bar",).list
    "foo:bar\tbaz".words.perl; # ("foo:bar", "baz").list

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

Examples:

    "Perl".flip;  # lreP
    "ABBA".flip;  # ABBA

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

=begin table

 %   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

=end table

Compatibility:

=begin table

 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

=end table

Perl 5 (non-)compatibility:

=begin table

 n   produces a runtime exception
 p   produces a runtime exception

=end table

Modifiers change the meaning of format directives, but are largely
no-ops (the semantics are still being determined).

=begin table

 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)

=end table

Examples:

 sprintf "%ld a big number, %lld a bigger number\n", 4294967295, 4294967296;

Special case:  sprintf("<b>%s</b>\n", "Perl 6")  will not work use either of the following:

 sprintf Q:b "<b>%s</b>\n",  "Perl 6";
 sprintf     "<b>\%s</b>\n", "Perl 6";
 sprintf     "<b>%s\</b>\n", "Perl 6";

=head2 subst

    multi method subst(Str:D: $matcher, $replacement, *%opts)

Returns the invocant string where C<$matcher> is replaced by C<$replacement>
(or the original string, if no match was found).

There is an in-place syntactic variant of C<subst> spelled
C<s/matcher/replacement>.

C<$matcher> an be a L<Regex>, or a literal C<Str>. Non-Str matcher arguments
of type L<Cool> are coerced to to C<Str> for literal matching.

	my $some-string = "Some foo";
	my $another-string = $some-string.subst(/foo/, "string"); # gives 'Some string'
	$some-string.=subst(/foo/, "string); # in-place substitution. $some-string is now 'Some string'

 
The replacement can be a closure:

	my $i = 41;
	my $str = "The answer is secret.";
	my $real-answer = $str.subst(/secret/, {++$i}); # The answer to everything

Here are other examples of usage:

	my $str = "Hey foo foo foo"; 
	$str.subst(/foo/, "bar", :g); # global substitution - returns Hey bar bar bar
	
	$str.subst(/foo/, "no subst", :x(0)); # targeted substitution. Number of times to substitute. Returns back unmodified.
	$str.subst(/foo/, "bar", :x(1)); #replace just the first occurrence. 
	
	$str.subst(/foo/, "bar", :nth(3)); # replace nth match alone. Replaces the third foo. Returns Hey foo foo bar

The following adverbs are supported

=begin table

    short       long        meaning
    =====       ====        =======
    :g          :global     tries to match as often as possible
    :nth(Int)               only substitute the nth's match
    :ss         :samespace  preserves whitespace on substitution
    :ii         :samecase   preserves case on substitution
    :x(Int)                 substitute exactly $x matches

=end table

Note that only in the C<s///> form C<:ii> implies C<:i> and C<:ss> implies
C<:s>. In the method form, the C<:s> and C<:i> modifiers must be added to the
regex, not the C<subst> method call.


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

Examples:

    substr("Long string", 6, 3);     # tri
    substr("Long string", 6);        # tring
    substr("Long string", 6, *-1);   # trin
    substr("Long string", *-3, *-1); # in

=head2 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 preceded 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 choosing 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.

=head2 pred

    method pred(Str:D:) returns Str:D

Returns the string decremented by one.

String decrementing is "magical" just like string increment (see
L<succ>). It fails on underflow

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

=head2 ord

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

Returns the codepoint number of the first character of the string

=head2 ords

    multi method ords(Str:D:) returns Positional

Returns a list of codepoint numbers, one for each character in the string.

=head2 trim

    method trim(Str:D:) returns Str

Remove leading and trailing whitespace. It can be use both as a method
on strings and as a function. When used as a method it will return
the trimmed string. In order to do in-place trimming, once needs to write
C<.=trim>


    my $line = '   hello world    ';
    say '<' ~ $line.trim ~ '>';        # <hello world>
    say '<' ~ trim($line) ~ '>';       # <hello world>
    $line.trim;
    say '<' ~ $line ~ '>';             # <   hello world    >
    $line.=trim;
    say '<' ~ $line ~ '>';             # <hello world>

See also L<trim-trailing> and L<trim-leading>

=head2 trim-trailing

Remove the whitespace characters from the end of a string. See also L<trim>.

=head2 trim-leading

Remove the whitespace characters from the beginning of a string. See also L<trim>.

=end pod

