=begin pod

=TITLE 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
    atan            Numeric
    atan2           Numeric
    sec             Numeric
    asec            Numeric
    cosec           Numeric
    acosec          Numeric
    cotan           Numeric
    acotan          Numeric
    sinh            Numeric
    asinh           Numeric
    cosh            Numeric
    acosh           Numeric
    sech            Numeric
    asech           Numeric
    asech           Numeric
    cosech          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
    unival          Str
    univals         Str
    uniprop         Str
    uniprop-int     Str
    uniprop-str     Str
    uniprop-bool    Str
    unimatch        Str
    uc              Str
    lc              Str
    capitalize      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

=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 firm, 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 firm, 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 method 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 method 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 method 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 method 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 method 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 method 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 log

Defined as:

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 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 code point.

    say 'a'.ord;            # 65

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. Characters should actually be grapheme clusters,
though current implementations erroneously count codepoints instead.

    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 uniname

Defined as:

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

Usage:

    uniname STRING
    STRING.uniname

Interprets the invocant / first argument as a L</type/Str>, and returns the
Unicode codepoint name of the first character.

=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, :$all)
    multi sub    split(Regex:D $delimiter, Str(Cool) $input, $limit = Inf, :$all)
    multi method split(  Str:D $delimiter, $limit = Inf, :$all)
    multi method split(Regex:D $delimiter, $limit = Inf, :$all)

Usage:

    split DELIMITER, STRING, LIMIT?, :all?
    split /PATTERN/, STRING, LIMIT?, :all?
    STRING.split(DELIMITER, LIMIT?, :all?)
    STRING.split(/PATTERN/, LIMIT?, :all?)

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.

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.

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

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

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

=begin comment

TODO: sech, asech, cosech, acosech, cotanh, acotanh, cis,
unpolar, fmt, substr-rw, trans,
match, subst, sprintf, printf, samecase

=end comment

=end pod

# vim: expandtab shiftwidth=4 ft=perl6
