=begin pod

=TITLE class Cool

=SUBTITLE Value that can be treated as a string or number interchangeably

    class Cool is Any { }

C<Cool>, also known as the B<C>onvenient B<OO> B<L>oop, is a base class
for strings, numbers and other built-in classes that you are supposed to use
mostly interchangeably.

Methods in C<Cool> coerce the invocant to a more
specific type, and then call the same method on that type. For example both
L<Int> and L<Str> inherit from C<Cool>, and calling method C<substr> on an
C<Int> converts the integer to C<Str> first.

    123.substr(1, 1);   # '2', same as 123.Str.substr(1, 1)

The following built-in types inherit from C<Cool>:
L<Array> L<Bool> L<Complex> L<Cool>
L<Duration> L<Map> L<FatRat> L<Hash> L<Instant>
L<Int> L<List> L<Match> L<Nil> L<Num>
L<Range> L<Seq> L<Stash> L<Str>

The following table summarizes the methods that C<Cool> provides, and
what type they coerce to:

=begin table

    method          coercion type

    abs             Numeric
    conj            Numeric
    sqrt            Numeric
    sign            Real
    rand            Numeric
    sin             Numeric
    asin            Numeric
    cos             Numeric
    acos            Numeric
    tan             Numeric
    tanh            Numeric
    atan            Numeric
    atan2           Numeric
    atanh           Numeric
    sec             Numeric
    asec            Numeric
    cosec           Numeric
    acosec          Numeric
    cotan           Numeric
    cotanh          Numeric
    acotan          Numeric
    sinh            Numeric
    asinh           Numeric
    cosh            Numeric
    acosh           Numeric
    sech            Numeric
    asech           Numeric
    cosech          Numeric
    acosech         Numeric
    acotanh         Numeric
    cis             Numeric
    log             Numeric
    exp             Numeric
    roots           Numeric
    log10           Numeric
    unpolar         Numeric
    round           Numeric
    floor           Numeric
    ceiling         Numeric
    truncate        Numeric
    chr             Int
    ord             Str
    chars           Str
    fmt             Str
    uniname         Str
    uninames        Seq
    unival          Str
    univals         Str
    uniprop         Str
    uniprop-int     Str
    uniprop-str     Str
    uniprop-bool    Str
    unimatch        Str
    uc              Str
    lc              Str
    fc              Str
    tc              Str
    tclc            Str
    flip            Str
    trans           Str
    index           Str
    rindex          Str
    ords            Str
    split           Str
    match           Str
    comb            Str
    subst           Str
    sprintf         Str
    printf          Str
    samecase        Str
    trim            Str
    trim-leading    Str
    trim-trailing   Str
    EVAL            Str
    chomp           Str
    chop            Str
    codes           Str

=end table

=head1 Methods

=head2 routine abs

Defined as:

    sub abs(Numeric() $x)
    method abs()

Coerces the invocant (or in the sub form, the argument) to
L<Numeric|/type/Numeric> and returns the absolute value (that is, a
non-negative number).

    say (-2).abs;       # 2
    say abs "6+8i";     # 10

=head2 method conj

Defined as:

    method conj()

Coerces the invocant to L<Numeric|/type/Numeric> and returns the
L<complex|/type/Complex> conjugate (that is, the number with the sign of the
imaginary part negated).

    say (1+2i).conj;        # 1-2i

=head2 routine sqrt

Defined as:

    sub sqrt(Numeric(Cool) $x)
    method sqrt()

Coerces the invocant to L<Numeric|/type/Numeric> (or in the sub form, the
argument) and returns the square root,
that is, a non-negative number that, when multiplied with itself, produces the
original number.

    say 4.sqrt;             # 2
    say sqrt(2);            # 1.4142135623731

=head2 method sign

Defined as:

    method sign()

Coerces the invocant to L<Numeric|/type/Real> and returns its sign, that
is, 0 if the number is 0, 1 for positive and -1 for negative values.

    say 6.sign;             # 1
    say (-6).sign;          # -1
    say "0".sign;           # 0

=head2 method rand

Defined as:

    method rand()

Coerces the invocant to L<Num|/type/Num> and returns a pseudo-random value
between zero and the number.

    say 1e5.rand;           # 33128.495184283

=head2 routine sin

Defined as:

    sub sin(Numeric(Cool))
    method sin()

Coerces the invocant (or in the sub form, the argument) to L<Numeric|/type/Numeric>, interprets it as radians,
returns its L<sine|https://en.wikipedia.org/wiki/Sine>.

    say sin(0);             # 0
    say sin(pi/4);          # 0.707106781186547
    say sin(pi/2);          # 1

Note that Perl 6 is no computer algebra system, so C<sin(pi)> typically does
not produce an exact 0, but rather a very small L<floating-point
number|/type/Num>.

=head2 routine asin

Defined as:

    sub asin(Numeric(Cool))
    method asin()

Coerces the invocant (or in the sub form, the argument) to L<Numeric|/type/Numeric>, and returns its
L<arc-sine|https://en.wikipedia.org/wiki/Inverse_trigonometric_functions> in
radians.

    say 0.1.asin;               # 0.10016742116156
    say asin(0.1);              # 0.10016742116156

=head2 routine cos

Defined as:

    sub cos(Numeric(Cool))
    method cos()

Coerces the invocant (or in sub form, the argument) to L<Numeric|/type/Numeric>, interprets it as radians,
returns its L<cosine|https://en.wikipedia.org/wiki/Cosine>.

    say 0.cos;                  # 1
    say pi.cos;                 # -1
    say cos(pi/2);              # 6.12323399573677e-17

=head2 routine acos

Defined as:

    sub acos(Numeric(Cool))
    method acos()

Coerces the invocant (or in sub form, the argument) to L<Numeric|/type/Numeric>, and returns its
L<arc-cosine|https://en.wikipedia.org/wiki/Inverse_trigonometric_functions> in
radians.

=head2 routine tan

Defined as:

    sub tan(Numeric(Cool))
    method tan()

Coerces the invocant (or in sub form, the argument) to L<Numeric|/type/Numeric>, interprets it as radians,
returns its L<tangent|https://en.wikipedia.org/wiki/Tangent>.

    say tan(3);                 # -0.142546543074278
    say 3.tan;                  # -0.142546543074278

=head2 routine atan

Defined as:

    sub atan(Numeric(Cool))
    method atan()

Coerces the invocant (or in sub form, the argument) to L<Numeric|/type/Numeric>, and returns its
L<arc-tangent|https://en.wikipedia.org/wiki/Inverse_trigonometric_functions> in
radians.

    say atan(3);                # 1.24904577239825
    say 3.atan;                 # 1.24904577239825

=head2 routine atan2

Defined as:

    sub atan2(Numeric() $x, Numeric() $y = 1e0)
    method atan2($y = 1e0)

Coerces the arguments (including the invocant in the method form) to L<Numeric|/type/Numeric>,
and returns their two-argument
L<arc-tangent|https://en.wikipedia.org/wiki/Inverse_trigonometric_functions> in
radians.

    say atan2(3);               # 1.24904577239825
    say 3.atan2;                # 1.24904577239825

=head2 method sec

Defined as:

    sub sec(Numeric(Cool))
    method sec()

Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>, interprets it as radians,
returns its L<secant|https://en.wikipedia.org/wiki/Trigonometric_functions#Reciprocal_functions>,
that is, the reciprocal of its cosine.

    say 45.sec;                 # 1.90359440740442
    say sec(45);                # 1.90359440740442

=head2 routine asec

Defined as:

    sub asec(Numeric(Cool))
    method asec()

Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>, and returns its
L<arc-secant|https://en.wikipedia.org/wiki/Inverse_trigonometric_functions> in
radians.

    say 0.45.sec;               # 1.11055940697373
    say sec(0.45);              # 1.11055940697373

=head2 routine cosec

Defined as:

    sub cosec(Numeric(Cool))
    method cosec()

Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>, interprets it as radians,
returns its L<cosecant|https://en.wikipedia.org/wiki/Trigonometric_functions#Reciprocal_functions>,
that is, the reciprocal of its sine.

    say 0.45.cosec;             # 2.29903273150897
    say cosec(0.45);            # 2.29903273150897

=head2 routine acosec

Defined as:

    sub acosec(Numeric(Cool))
    method acosec()

Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>, and returns its
L<arc-cosecant|https://en.wikipedia.org/wiki/Inverse_trigonometric_functions> in
radians.

    say 45.acosec;              # 0.0222240516182672
    say acosec(45)              # 0.0222240516182672

=head2 routine cotan

Defined as:

    sub cotan(Numeric(Cool))
    method cotan()

Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>, interprets it as radians,
returns its L<cotangent|https://en.wikipedia.org/wiki/Trigonometric_functions#Reciprocal_functions>,
that is, the reciprocal of its tangent.

    say 45.cotan;               # 0.617369623783555
    say cotan(45);              # 0.617369623783555

=head2 routine acotan

Defined as:

    sub acotan(Numeric(Cool))
    method acotan()

Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>, and returns its
L<arc-cotangent|https://en.wikipedia.org/wiki/Inverse_trigonometric_functions> in
radians.

    say 45.acotan;              # 0.0222185653267191
    say acotan(45)              # 0.0222185653267191

=head2 routine sinh

Defined as:

    sub sinh(Numeric(Cool))
    method sinh()

Coerces the invocant (or in method form, its argument) to L<Numeric|/type/Numeric>, and returns its
L<Sine hyperbolicus|https://en.wikipedia.org/wiki/Hyperbolic_function>.

    say 1.sinh;                 # 1.1752011936438
    say sinh(1);                # 1.1752011936438

=head2 routine asinh

Defined as:

    sub asinh(Numeric(Cool))
    method asinh()

Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>, and returns its
L<Inverse Sine hyperbolicus|https://en.wikipedia.org/wiki/Inverse_hyperbolic_function>.

    say 1.asinh;                # 0.881373587019543
    say asinh(1);               # 0.881373587019543

=head2 routine cosh

Defined as:

    sub cosh(Numeric(Cool))
    method cosh()

Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>, and returns its
L<Cosine hyperbolicus|https://en.wikipedia.org/wiki/Hyperbolic_function>.

    say cosh(0.5);              # 1.12762596520638

=head2 routine acosh

Defined as:

    sub acosh(Numeric(Cool))
    method acosh()

Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>, and returns its
L<Inverse Cosine hyperbolicus|https://en.wikipedia.org/wiki/Inverse_hyperbolic_function>.

    say acosh(45);              # 4.4996861906715

=head2 routine tanh

Defined as:

    sub tanh(Numeric(Cool))
    method tanh()

Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>, and returns its
L<Tangent hyperbolicus|https://en.wikipedia.org/wiki/Hyperbolic_function>.

    say tanh(30);               # 30

=head2 routine atanh

Defined as:

    sub atanh(Numeric(Cool))
    method atanh()

Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>, and returns its
L<Inverse tangent hyperbolicus|https://en.wikipedia.org/wiki/Inverse_hyperbolic_function>.

    say atanh(0.5);              # 0.549306144334055

=head2 routine sech

Defined as:

    sub sech(Numeric(Cool))
    method sech()

Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>, and returns its
L<Secant hyperbolicus|https://en.wikipedia.org/wiki/Hyperbolic_function>.

    say 0.sech;                 # 1

=head2 routine asech

Defined as:

    sub asech(Numeric(Cool))
    method asech()

Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>, and returns its
L<Inverse hyperbolic secant|https://en.wikipedia.org/wiki/Hyperbolic_function>.

    say 0.8.asech;              # 0.693147180559945

=head2 routine cosech

Defined as:

    sub cosech(Numeric(Cool))
    method cosech()

Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>, and returns its
L<Hyperbolic cosecant|https://en.wikipedia.org/wiki/Hyperbolic_function>.

    say cosech(pi/2);           # 0.434537208094696

=head2 routine acosech

Defined as:

    sub acosech(Numeric(Cool))
    method acosech()

Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>, and returns its
L<Inverse hyperbolic cosecant|https://en.wikipedia.org/wiki/Inverse_hyperbolic_function>.

    say acosech(4.5);           # 0.220432720979802

=head2 routine cotanh

Defined as:

    sub cotanh(Numeric(Cool))
    method cotanh()

Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>, and returns its
L<Hyperbolic cotangent|https://en.wikipedia.org/wiki/Hyperbolic_function>.

    say cotanh(pi);             # 1.00374187319732

=head2 routine acotanh

Defined as:

    sub acotanh(Numeric(Cool))
    method acotanh()

Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>, and returns its
L<Inverse hyperbolic cotangent|https://en.wikipedia.org/wiki/Inverse_hyperbolic_function>.

    say acotanh(2.5);           # 0.423648930193602

=head2 routine cis

Defined as:

    sub cis(Numeric(Cool))
    method cis()

Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>, and returns
L<cos(argument) + i*sin(argument)|https://en.wikipedia.org/wiki/Cis_%28mathematics%29>.

    say cis(pi/4);              # 0.707106781186548+0.707106781186547i

=head2 routine log

Defined as:

    multi sub log(Numeric(Cool) $number, Numeric(Cool) $base?)
    multi method log(Cool:D: Cool:D $base?)

Coerces the arguments (including the invocant in the method form) to
L<Numeric|/type/Numeric>, and returns its
L<Logarithm|https://en.wikipedia.org/wiki/Logarithm> to base C<$base>, or to
base C<e> (Euler's Number) if no base was supplied
(L<Natural logarithm|https://en.wikipedia.org/wiki/Natural_logarithm>.

    say (e*e).log;              # 2

=head2 routine log10

Defined as:

    multi sub log10(Cool(Numeric))
    multi method log10()

Coerces the invocant (or in the sub form, the invocant) to
L<Numeric|/type/Numeric>, and returns its
L<Logarithm|https://en.wikipedia.org/wiki/Logarithm> to base 10, that is, a
number that approximately produces the original number when raised to the power
of 10.

    say log10(1001);            # 3.00043407747932

=head2 method exp

Defined as:

    multi sub exp(Cool:D $pow, Cool:D $base?)
    multi method exp(Cool:D: Cool:D $base?)

Coerces the arguments (including the invocant in the method from) to L<Numeric|/type/Numeric>, and returns C<$base>
raised to the power of the first number. If no C<$base> is supplied, C<e> (Euler's
Number) is used.

    say 0.exp;      # 1
    say 1.exp;      # 2.71828182845905
    say 10.exp;     # 22026.4657948067

=head2 method unpolar

Defined as:

    method unpolar(Numeric(Cool))

Coerces the arguments (including the invocant in the method form) to L<Numeric|/type/Numeric>, and returns
a complex number from the given polar coordinates. The invocant (or the first argument in sub form) is the magnitude while
the argument (i.e. the second argument in sub form) is the angle. The angle is assumed to be in radians.

    say sqrt(2).unpolar(pi/4);      # 1+1i

=head2 routine round

Defined as:

    multi sub round(Numeric(Cool))
    multi method round(Cool:D: $unit = 1)

Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>, and rounds it to the unit of
C<$unit>. If C<$unit> is 1, rounds to the nearest integer.

    say 1.7.round;          # 2
    say 1.07.round(0.1);    # 1.1
    say 21.round(10);       # 20

=head2 routine floor

Defined as:

    multi sub floor(Numeric(Cool))
    multi method floor

Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>, and rounds it downwards to
the nearest integer.

    say "1.99".floor;       # 1
    say "-1.9".floor;       # -2
    say 0.floor;            # 0

=head2 routine ceiling

Defined as:

    multi sub ceiling(Numeric(Cool))
    multi method ceiling

Coerces the invocant (or in sub form, its argument) to L<Numeric|/type/Numeric>, and rounds it upwards to
the nearest integer.

    say "1".ceiling;        # 1
    say "-0.9".ceiling;     # 0
    say "42.1".ceiling;     # 43

=head2 routine truncate

Defined as:

    multi sub truncate(Numeric(Cool))
    multi method truncate()

Coerces the invocant (or in sub form, its argument) to
L<Numeric|/type/Numeric>, and rounds it towards zero.

    say 1.2.truncate;       # 1
    say truncate -1.2;      # -1

=head2 routine ord

Defined as:

    sub ord(Str(Cool))
    method ord()

Coerces the invocant (or in sub form, its argument) to
L<Str|/type/Str>, and returns the L<Unicode code
point|https://en.wikipedia.org/wiki/Code_point> number of the first
code point.

    say 'a'.ord;            # 97

The inverse operation is L<chr|#method chr>.

Mnemonic: returns an ordinal number

=head2 routine chr

Defined as:

    sub chr(Int(Cool))
    method chr()

Coerces the invocant (or in sub form, its argument) to L<Int|/type/Int>, interprets it as a
L<Unicode code points|https://en.wikipedia.org/wiki/Code_point>,
and returns a L<string|/type/Str> made of that code point.

    say '65'.chr;       # A

The inverse operation is L<ord|#method ord>.

Mnemonic: turns an integer into a I<char>acter.

=head2 routine chars

Defined as:

    sub chars(Str(Cool))
    method chars()

Coerces the invocant (or in sub form, its argument) to L<Str|/type/Str>, and returns the
number of characters in the string. Please note that on the JVM, you currently get
codepoints instead of graphemes.

    say 'møp'.chars;    # 3

=head2 routine codes

Defined as:

    sub codes(Str(Cool))
    method codes()

Coerces the invocant (or in sub form, its argument) to L<Str|/type/Str>, and returns the number of
L<Unicode code points|https://en.wikipedia.org/wiki/Code_point>.

    say 'møp'.codes;    # 3

=head2 routine flip

Defined as:

    sub flip(Str(Cool))
    method flip()

Coerces the invocant (or in sub form, its argument) to L<Str|/type/Str>, and returns a reversed version.

    say 421.flip;       # 124

=head2 routine trim

Defined as:

    sub trim(Str(Cool))
    method trim()

Coerces the invocant (or in sub form, its argument) to L<Str|/type/Str>, and returns the string with both
leading and trailing whitespace stripped.

    my $stripped = '  abc '.trim;
    say "<$stripped>";          # <abc>

=head2 routine trim-leading

Defined as:

    sub trim-leading(Str(Cool))
    method trim-leading()

Coerces the invocant (or in sub form, its argument) to L<Str|/type/Str>, and returns the string with
leading whitespace stripped.

    my $stripped = '  abc '.trim-leading;
    say "<$stripped>";          # <abc >

=head2 routine trim-trailing

Defined as:

    sub trim-trailing(Str(Cool))
    method trim-trailing()

Coerces the invocant (or in sub form, its argument) to L<Str|/type/Str>, and
returns the string with trailing whitespace stripped.

    my $stripped = '  abc '.trim-trailing;
    say "<$stripped>";          # <  abc>

=head2 routine lc

Defined as:

    sub lc(Str(Cool))
    method lc()

Coerces the invocant (or in sub form, its argument) to L<Str|/type/Str>, and returns it case-folded to lower
case.

    say "ABC".lc;       # abc

=head2 routine uc

Defined as:

    sub uc(Str(Cool))
    method uc()

Coerces the invocant (or in sub form, its argument) to L<Str|/type/Str>, and returns it case-folded to upper
case (capital letters).

    say "Abc".uc;       # ABC

=head2 routine fc

Defined as:

    sub fc(Str(Cool))
    method fc()

Coerces the invocant (or in sub form, its argument) to L<Str|/type/Str>, and
returns the result a Unicode "case fold" operation suitable for doing caseless
string comparisons. (In general, the returned string is unlikely to be useful
for any purpose other than comparison.)

    say "groß".fc;       # gross

=head2 routine tc

Defined as:

    sub tc(Str(Cool))
    method tc()

Coerces the invocant (or in sub form, its argument) to L<Str|/type/Str>, and returns it with the first letter
case-folded to title case (or where not available, upper case).

    say "abC".tc;       # AbC

=head2 routine tclc

Defined as:

    sub tclc(Str(Cool))
    method tclc()

Coerces the invocant (or in sub form, its argument) to L<Str|/type/Str>, and returns it with the first letter
case-folded to title case (or where not available, upper case), and the rest
of the string case-folded to lower case..

    say 'abC'.tclc;     # Abc

=head2 routine wordcase

Defined as:

    sub wordcase(Str(Cool) $input, :&filter = &tclc, Mu :$where = True)
    method wordcase(:&filter = &tclc, Mu :$where = True)

Coerces the invocant (or in sub form, the first argument) to L<Str|/type/Str>, and filters each word that
smart-matches against C<$where> through the C<&filter>. With the default
filter (first character to upper case, rest to lower) and matcher (which
accepts everything), this title-cases each word:

    say "perl 6 programming".wordcase;      # Perl 6 Programming

With a matcher:

    say "have fun working on perl".wordcase(:where({ .chars > 3 }));
                                            # Have fun Working on Perl

With a customer filter too:

    say "have fun working on perl".wordcase(:filter(&uc), :where({ .chars > 3 }));
                                            # HAVE fun WORKING on PERL

=head2 routine samecase

Defined as:

    sub samecase(Cool $string, Cool $pattern)
    method samecase(Cool:D: Cool $pattern)

Coerces the invocant (or in sub form, the first argument) to L<Str|/type/Str>, and returns a
copy of C<$string> with case information for each individual character changed according to C<$pattern>.
(The pattern string can contain three types of characters, i.e. uppercase, lowercase and caseless.
For a given character in C<$pattern> its case information determines the case of the corresponding
character in the result.)
If C<$string> is longer than C<$pattern>, the case information from the last character of
C<$pattern> is applied to the remaining characters of C<$string>.

    say "perL 6".samecase("A__a__"); # Perl 6
    say "pERL 6".samecase("Ab");     # Perl 6

=head2 routine uniname

Defined as:

    sub uniname(Str(Cool)) returns Str
    method uniname() returns Str

Interprets the invocant / first argument as a L<Str|/type/Str>, and returns the
Unicode codepoint name of the first character. To convert a whole string use L<uninames|#routine_uninames>.

    # Camelia in Unicode
    say ‘»ö«’.comb».uniname;
    # «("RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK",
    #   "LATIN SMALL LETTER O WITH DIAERESIS", "LEFT-POINTING DOUBLE ANGLE QUOTATION MARK")␤»

    # Find the char with the longest Unicode name.
    say (0..0x1FFFF).sort(*.uniname.chars)[*-1].chr.uniname;
    # «ARABIC LIGATURE UIGHUR KIRGHIZ YEH WITH HAMZA ABOVE WITH ALEF MAKSURA INITIAL FORM␤»

=head2 routine uninames

Defined as:

    sub uninames(Str:D)
    method uninames()

Returns of a Seq of unicode names for the Str provided.

    dd ‘»ö«’.comb».uniname;
    # «("RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK",
    #  "LATIN SMALL LETTER O WITH DIAERESIS",
    #  "LEFT-POINTING DOUBLE ANGLE QUOTATION MARK").Seq␤»

=head2 routine chop

Defined as:

    sub chop(Str(Cool))
    method chop()

Coerces the invocant (or in sub form, its argument) to L<Str|/type/Str>, and returns it with the last
character removed.

    say 'perl'.chop;                        # per

=head2 routine chomp

Defined as:

    sub chomp(Str(Cool))
    method chomp()

Coerces the invocant (or in sub form, its argument) to L<Str|/type/Str>, and returns it with the last
character removed, if it is a logical newline.

    say 'ab'.chomp.chars;                   # 2
    say "a\n".chomp.chars;                  # 1

=head2 routine substr

Defined as:

    sub substr(Str(Cool) $str, $from, $chars?)
    method substr($from, $chars?)

Coerces the invocant (or in the sub form, the first argument) to
L<Str|/type/Str>, and returns the string starting from offset C<$from>. If
C<$chars> is supplied, at most C<$chars> characters are returned.

    say 'zenith'.substr(2);         # nith
    say 'zenith'.substr(0, 3);      # zen

    # works on non-strings too:
    say 20151224.substr(6);         # 24

    # sub form:
    say substr "zenith", 0, 3;      # zen

If the C<$from> parameter is a L<Callable|/type/Callable>, it is called with
the number of chars in the string as argument. This allows easy indexing
relative to the end:

    say 20151224.substr(*-2);       # 24

=head2 routine ords

Defined as:

    sub ords(Str(Cool) $str)
    method ords()

Coerces the invocant (or in the sub form, the first argument) to
L<Str|/type/Str>, and returns a list of Unicode codepoints for each character.

    say "Perl 6".ords;              # 80 101 114 108 160 54
    say ords 10;                    # 49 48

This is the list-returning version of L<ord>. The inverse operation in
L<chrs>.

=head2 routine chrs

Defined as:

    sub chrs(*@codepoints) returns Str:D
    method chrs()

Coerces the invocant (or in the sub form, the argument list) to a list of
integers, and returns the string created by interpreting each integer as a
Unicode codepoint, and joining the characters.

    say <80 101 114 108 160 54>.chrs;   # Perl 6

This is the list-input version of L<chr>. The inverse operation is L<ords>.

=head2 routine split

Defined as:

    multi sub    split(  Str:D $delimiter, Str(Cool) $input, $limit = Inf, :$k, :$v, :$kv, :$p, :$skip-empty)
    multi sub    split(Regex:D $delimiter, Str(Cool) $input, $limit = Inf, :$k, :$v, :$kv, :$p, :$skip-empty)
    multi sub    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)

Coerces the invocant (or in the sub form, the second argument) to
L<Str|/type/Str>, and splits it 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. You can also provide multiple delimiters by specifying them as a
list; mixing Cool and Regex objects is OK.

    say split(';', "a;b;c").perl;          # ("a", "b", "c")
    say split(';', "a;b;c", 2).perl;       # ("a", "b;c").Seq

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

    say split(['a', /b+/, 4], '1a2bb345').perl # ("1", "2", "3", "5")

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 C<:k, :v, :kv, :p> adverbs
changes that. Think of the matches as a list that is interleaved with the
non-matching parts.

The C<:v> interleaves the values of that list, which will be either
L<Match|/type/Match> objects, if a L<Regex|/type/Regex> was used as a matcher
in the split, or L<Str|/type/Str> objects, if a L<Cool|/type/Cool> was used
as matcher. If multiple delimiters are specified, L<Match|/type/Match> objects
will be generated for all of them, unless B<all> of the delimiters are
L<Cool|/type/Cool>.

    say 'abc'.split(/b/, :v);               # (a ｢b｣ c)
    say 'abc'.split('b', :v);               # (a b c)

C<:k> interleaves the keys, that is, the indexes:

    say 'abc'.split(/b/, :k);               # (a 0 c)

C<:kv> adds both indexes and matches:

    say 'abc'.split(/b/, :kv);               # (a 0 ｢b｣ c)

and C<:p> adds them as L<Pairs|/type/Pair>, using the same types for
values as C<:v> does:

    say 'abc'.split(/b/, :p)                # (a 0 => ｢b｣ c)
    say 'abc'.split('b', :p)                # (a 0 => b c)

You can only use one of the C<:k, :v, :kv, :p> adverbs in a single call
to C<split>.

Note that empty chunks are not removed from the result list.
For that behavior, use the `:skip-empty` named argument:

    say ("f,,b,c,d".split: /","/             ).perl;  # ("f", "", "b", "c", "d")
    say ("f,,b,c,d".split: /","/, :skip-empty).perl;  # ("f", "b", "c", "d")

See also: L<comb>.

=head2 routine lines

Defined as:

    sub lines(Str(Cool))
    method lines()

Coerces the invocant (and in sub form, the argument) to L<Str|/type/Str>,
decomposes it into lines (with the newline characters stripped), and returns
the list of lines.

    say lines("a\nb\n").join('|');          # a|b
    say "some\nmore\nlines".lines.elems;    # 3


This method can be used as part of an C<IO::Path> to process a file
line-by-line, since C<IO::Path> objects inherit from C<Cool>, e.g.:

=begin code :skip-test
'huge-csv'.IO.lines -> $line {
    # Do something with $line
}

# or if you'll be processing later
my @lines = 'huge-csv'.IO.lines;
=end code

Without any arguments, sub C<lines> operates on
C<$*ARGFILES>, which defaults to C<$*IN> in the absence of any filenames.

To modify values in place use C<is copy> to force a writeable container.

=for code :skip-test
for $*IN.lines -> $_ is copy { s/(\w+)/{$0 ~ $0}/; .say }

=head2 method words

Defined as:

    method words(Int() $limit)

Coerces the invocant to L<Str|/type/Str>, and returns a list of words that make
up the string (and if C<$limit> is supplied, only the first C<$limit> words).

    say 'The quick brown fox'.words.join('|');      # The|quick|brown|fox
    say 'The quick brown fox'.words(2).join('|');   # The|quick

Only whitespace counts as word boundaries

    say "isn't, can't".words.join('|');             # isn't,|can't

=head2 routine comb

Defined as:

    multi sub comb(Regex $matcher, Str(Cool) $input, $limit = *) returns List:D
    multi method comb(Regex $matcher, $limit = *) returns List:D

Returns all (or if supplied, at most C<$limit>) matches of the invocant
(method form) or the second argument (sub form) against the
L<Regex|/type/Regex> as a list of strings.

    say "6 or 12".comb(/\d+/).join(", ");           # 6, 12

=head2 method contains

    multi method contains(Cool:D: Str(Cool) $needle, Cool $start?) returns Bool:D

Returns C<True> if the invocant contains the C<$needle> at any position within
the string. If $start is provided skip as many characters.

    say "Hello, World".contains('hello');      # False
    say "Hello, World".contains(',');          # True

=head2 routine index

Defined as:

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

Coerces the first two arguments (in method form, also counting the invocant)
to L<Str|/type/Str>, and 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.

See L<the documentation in type Str|/type/Str#routine_index> for examples.

=head2 routine rindex

Defined as:

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

Coerces the first two arguments (including the invocant in method form) to
L<Str|/type/Str> and C<$startpos> to L<Int|/type/Int>, and
returns the last position of C<$needle> in C<$haystack> not after C<$startpos>.
Returns an undefined value if C<$needle> wasn't found.

See L<the documentation in type Str|/type/Str#routine_rindex> for examples.

=head2 method fmt

Defined as:

    method fmt($format = '%s') returns Str:D

Uses C<$format> to return a formatted representation of the invocant.

For more information about formats strings, see L<sprintf|/routine/sprintf>.

    say 11.fmt('This Int equals %03d');               # This Int equals 011
    say '16'.fmt('Hexadecimal %x');                   # Hexadecimal 10

=head2 routine roots

Defined as:

    multi sub roots(Numeric(Cool) $x, Int(Cool) $n)
    multi method roots(Int(Cool) $n)

Coerces the first argument (and in method form, the invocant) to
L<Numeric|/type/Numeric> and the second (C<$n>) to L<Int|/type/Int>, and produces a
list of C<$n> L<Complex|/type/Complex> C<$n>-roots, which means numbers that,
raised to the C<$n>th power, approximately produce the original number.

For example

=begin code
my $original = 16;
my @roots = $original.roots(4);
say @roots;

for @roots -> $r {
    say abs($r ** 4 - $original);
}
=end code

produces this output:

=begin code :skip-test
2+0i 1.22464679914735e-16+2i -2+2.44929359829471e-16i -3.67394039744206e-16-2i
1.77635683940025e-15
4.30267170434156e-15
8.03651692704705e-15
1.04441561648202e-14
=end code

=head2 method IO

Defined as:

    method IO() returns IO::Path:D

Coerces the invocant to L<IO::Path>.

=for code :skip-test
.say for '.'.IO.dir;        # gives a directory listing

=head2 routine EVAL

Defined as:

    sub EVAL(Cool $code, :$lang = { ... })

Coerces the invocant to L<Str>.

This works as-is with a literal string parameter. If you have a more complex
input, such as a variable or string with embedded code, you must enable the
C<MONKEY-SEE-NO-EVAL> pragma:

    use MONKEY-SEE-NO-EVAL;
    EVAL "say { 5 + 5 }";   # says 10

Symbols in the current lexical scope are visible to code in an C<EVAL>.

    my $answer = 42;
    EVAL 'say $answer;';    # says 42

However, since the set of symbols in a lexical scope is immutable after compile
time, an EVAL can never introduce symbols into the surrounding scope.

=for code :skip-test
EVAL 'my $lives = 9'; say $lives;   # error, $lives not declared

Furthermore, the C<EVAL> is evaluated in the current package:

    module M {
        EVAL 'our $answer = 42'
    }
    say $M::answer;         # says 42

And also the current language, meaning any added syntax is available:

    sub infix:<mean>(*@a) is assoc<list> {
        @a.sum / @a.elems
    }
    EVAL 'say 2 mean 6 mean 4';     # says 4

An C<EVAL> statement evaluates to the result of the last statement:

    sub infix:<mean>(*@a) is assoc<list> {
        @a.sum / @a.elems
    }
    say EVAL 'say 1; 2 mean 6 mean 4';         # says 1, then says 4

C<EVAL> is also a gateway for executing code in other languages:

=for code :skip-test
EVAL "use v5.20; say 'Hello from perl5!'", :lang<Perl5>;

=head2 routine EVALFILE

Defined as:

    sub EVALFILE(Cool $filename, :$lang = { ... })

Slurps the specified file and evaluates it. Behaves the same way as C<EVAL>
with regard to both scoping and the C<$lang> parameter. Evaluates to the value
produced by the final statement in the file.

=for code :skip-test
EVALFILE "foo.p6";

=begin comment

TODO:
unpolar, fmt, substr-rw, trans,
match, subst, sprintf, printf, samecase

=end comment

=end pod

# vim: expandtab shiftwidth=4 ft=perl6
