=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<Backtrace> L<Bag> L<Baggy> L<Bool> L<Complex> L<Cool>
L<Duration> L<Enumeration> L<Map> L<FatRat> L<Hash> L<Instant>
L<Int> L<List> L<Match>
L<Nil> L<Num> L<Numeric>
L<Range> L<Real> L<Seq> L<Set> L<Stash> L<Str> L<Stringy>

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
    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()

Usage:

    abs NUMERIC
    NUMERIC.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()

Usage:

    NUMERIC.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()

Usage:

    sqrt NUMERIC
    NUMERIC.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()

Usage:

    NUMERIC.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()

Usage:
    NUMERIC.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()

Usage:

    sin NUMERIC
    NUMERIC.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()

Usage:

    asin NUMERIC
    NUMERIC.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

=head2 routine cos

Defined as:

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

Usage:

    cos NUMERIC
    NUMERIC.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()

Usage:

    acos NUMERIC
    NUMERIC.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()

Usage:

    tan NUMERIC
    NUMERIC.tan

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

=head2 routine atan

Defined as:

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

Usage:

    atan NUMERIC
    NUMERIC.atan

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

=head2 routine atan2

Defined as:

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

Usage:

    atan2 NUMERIC, NUMERIC?
    NUMERIC.atan2(NUMERIC?)

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

=head2 method sec

Defined as:

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

Usage:

    sec NUMERIC
    NUMERIC.sec

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

=head2 routine asec

Defined as:

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

Usage:

    asec NUMERIC
    NUMERIC.asec

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

=head2 routine cosec

Defined as:

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

Usage:

    cosec NUMERIC
    NUMERIC.cosec

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

=head2 routine acosec

Defined as:

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

Usage:

    acosec NUMERIC
    NUMERIC.acosec

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

=head2 routine cotan

Defined as:

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

Usage:

    cotan NUMERIC
    NUMERIC.cotan

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

=head2 routine acotan

Defined as:

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

Usage:

    acotan NUMERIC
    NUMERIC.acotan

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

=head2 routine sinh

Defined as:

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

Usage:

    sinh NUMERIC
    NUMERIC.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>.

=head2 routine asinh

Defined as:

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

Usage:

    asinh NUMERIC
    NUMERIC.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>.

=head2 routine cosh

Defined as:

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

Usage:

    cosh NUMERIC
    NUMERIC.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>.

=head2 routine acosh

Defined as:

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

Usage:

    acosh NUMERIC
    NUMERIC.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>.

=head2 routine tanh

Defined as:

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

Usage:

    tanh NUMERIC
    NUMERIC.tanh

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

=head2 routine atanh

Defined as:

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

Usage:

    atanh NUMERIC
    NUMERIC.atanh

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

=head2 routine sech

Defined as:

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

Usage:

    sech NUMERIC
    NUMERIC.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()

Usage:

    asech NUMERIC
    NUMERIC.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()

Usage:

    cosech NUMERIC
    NUMERIC.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()

Usage:

    acosech NUMERIC
    NUMERIC.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()

Usage:

    cotanh NUMERIC
    NUMERIC.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()

Usage:

    acotanh NUMERIC
    NUMERIC.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()

Usage:

    cis NUMERIC
    NUMERIC.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?)

Usage:

    log NUMERIC, NUMERIC?
    NUMERIC.log(NUMERIC?)

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()

Usage:

    log10 NUMERIC
    NUMERIC.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?)

Usage:

    exp NUMERIC, NUMERIC?
    NUMERIC.exp(NUMERIC?)

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

Usage:

    unpolar NUMERIC, NUMERIC
    NUMERIC.unpolar(NUMERIC)

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)

Usage:

    round NUMERIC, NUMERIC?
    NUMERIC.round(NUMERIC?)

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

Usage:

    floor NUMERIC
    NUMERIC.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

Usage:

    ceiling NUMERIC
    NUMERIC.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()

Usage:

    truncate NUMERIC
    NUMERIC.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()

Usage:

    ord STRING
    STRING.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()

Usage:

    chr INTEGER
    INTEGER.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()

Usage:

    chars STRING
    STRING.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()

Usage:

    codes STRING
    STRING.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()

Usage:

    flip STRING
    STRING.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()

Usage:

    trim STRING
    STRING.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()

Usage:

    trim-leading STRING
    STRING.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()

Usage:

    trim-trailing STRING
    STRING.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()

Usage:

    lc STRING
    STRING.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()

Usage:

    uc STRING
    STRING.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 tc

Defined as:

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

Usage:

    tc STRING
    STRING.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()

Usage:

    tclc STRING
    STRING.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)

Usage:

    wordcase STRING, FILTER?, WHERE?
    STRING.wordcase(FILTER?, WHERE?)

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)

Usage:

    samecase STRING, PATTERN
    STRING.samecase(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

Usage:

    # 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␤»

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

=head2 routine uninames

Defined as:

    sub uninames(Str:D)
    method uninames()

Usage:

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

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

=head2 routine chop

Defined as:

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

Usage:

    chop STRING
    STRING.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()

Usage:

    chomp STRING
    STRING.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?)

Usage:

    substr(STRING, FROM, CHARS?)
    STRING.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()

Usage:

    ords(STRING)
    STRING.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 32 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) return Str:D
    method chrs()

Usage:

    chrs LIST
    LIST.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 32 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 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)

Usage:

    split DELIMITER, STRING, LIMIT?, [:k | :v | :kv | :p]?, :skip-empty?
    split /PATTERN/, STRING, LIMIT?, [:k | :v | :kv | :p]?, :skip-empty?
    STRING.split(DELIMITER, LIMIT?,  [:k | :v | :kv | :p]?, :skip-empty?)
    STRING.split(/PATTERN/, LIMIT?,  [: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.

    say split(';', "a;b;c").perl;          # ("a", "b", "c").list
    say split(';', "a;b;c", 2).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

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. C<:v> interleaves the values of that list:
s
    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)

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

and C<:p> adds them as L<Pairs|/type/Pair>:

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

Note that unlike in Perl 5, 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()

Usage:

    lines STRING
    STRING.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
for 'huge-csv'.IO.lines -> $line {
        # Do something with $line
}

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

=head2 method words

Defined as:

    method words(Int() $limit)

Usage:

    INTEGER.words(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

Usage:

    comb /PATTERN/, STRING, LIMIT?
    STRING.comb(/PATTERN/, LIMIT?)

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

Usage:

    index STRING, NEEDLE, STARTPOS?
    STRING.comb(NEEDLE, STARTPOS?)

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)

Usage:

    rindex STRING, NEEDLE, STARTPOS?
    STRING.rindex(NEEDLE, STARTPOS?)

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 routine roots

Defined as:

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

Usage:

    roots NUMERIC, INTEGER
    NUMERIC.roots(INTEGER)

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

Usage:

    EXPR.IO

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

    .say for '.'.IO.dir;        # gives a directory listing

=head2 routine EVAL

Defined as:

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

Usage:

    EVAL "say 'hello'";

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 }";

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 introduced symbols into the surrounding scope.

    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:

    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:

    EVAL "use v5.20; say 'Hello from perl5!'", :lang<Perl5>;

=head2 routine EVALFILE

Defined as:

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

Usage:

    EVALFILE "foo.p6";

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.

=begin comment

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

=end comment

=end pod

# vim: expandtab shiftwidth=4 ft=perl6
