Numeric.pod

=begin pod

=TITLE role Numeric

=SUBTITLE Number or object that can act as a number

    role Numeric { ... }

Common role for numbers and types that can act as numbers.

Binary numeric operations return an object of the "wider" type:

    Int         narrowest
    Rat
    FatRat
    Num
    Complex     widest

So for example the product of a L<Rat> and an L<Int> is a L<Rat>.

Unary operations that in pure math usually return an irrational number
generally return L<Num> in Perl 6.

=head1 Methods

=head2 method Real

Defined as:

    method Real(Numeric:D:) returns Real:D

Usage:

    NUMERIC.Real

If this C<Numeric> is equivalent to a C<Real>, return that C<Real>.
Fail with C<X::Numeric::Real> otherwise.

=head2 method Int

Defined as:

    method Int(Numeric:D:) returns Int:D

Usage:

    NUMERIC.Int

If this C<Numeric> is equivalent to a C<Real>, return the equivalent of
calling C<truncate> on that C<Real> to get an C<Int>. Fail with
C<X::Numeric::Real> otherwise.

=head2 method Rat

Defined as:

    method Rat(Numeric:D: Real $epsilon = 1.0e-6) returns Rat:D

Usage:

    NUMERIC.Rat

If this C<Numeric> is equivalent to a C<Real>, return a C<Rat> which is
within C<$epsilon> of that C<Real>'s value. Fail with C<X::Numeric::Real>
otherwise.

=head2 method Num

Defined as:

    method Num(Numeric:D:) returns Num:D

Usage:

    NUMERIC.Num

If this C<Numeric> is equivalent to a C<Real>, return that C<Real> as a C<Num>
as accurately as is possible. Fail with C<X::Numeric::Real> otherwise.

=head2 method narrow

Defined as:

    method narrow(Numeric:D) returns Numeric:D

Usage:

    NUMERIC.narrow

Returns the number converted to the narrowest type that can hold it without
loss of precision.

    say (4.0 + 0i).narrow.perl;     # 4
    say (4.0 + 0i).narrow.^name;    # Int

=head2 method ACCEPTS

Defined as:

    multi method ACCEPTS(Numeric:D: $other)

Usage:

    NUMERIC.ACCEPTS(OTHER)

Returns True if C<$other> is numerically the same as the invocant.

=head2 routine log

Defined as:

    multi sub    log(Numeric:D, Numeric $base = e) returns Numeric:D
    multi method log(Numeric:D: Numeric $base = e) returns Numeric:D

Usage:

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

Calculates the logarithm to base C<$base>. Defaults to the natural logarithm.

=head2 routine log10

Defined as:

    multi sub    log10(Numeric:D ) returns Numeric:D
    multi method log10(Numeric:D:) returns Numeric:D

Usage:

    log10 NUMERIC
    NUMERIC.log10

Calculates the logarithm to base 10.

=head2 routine exp

Defined as:

    multi sub    exp(Numeric:D, Numeric:D $base = e) returns Numeric:D
    multi method exp(Numeric:D: Numeric:D $base = e) returns Numeric:D

Usage:

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

Returns C<$base> to the power of the number, or C<e> to the power of the
number if called without a second argument.

=head2 method roots

Defined as:

    multi method roots(Numeric:D: Int:D $n) returns Positional

Usage:

    NUMERIC.roots(INTEGER)

Returns a list of the C<$n> complex roots, which evaluate to the original
number when raised to the C<$n>th power.

=head2 routine abs

Defined as:

    multi sub    abs(Numeric:D ) returns Real:D
    multi method abs(Numeric:D:) returns Real:D

Usage:

    abs NUMERIC
    NUMERIC.abs

Returns the absolute value of the number.

=head2 routine sqrt

Defined as:

    multi sub    sqrt(Numeric:D) returns Numeric:D
    multi method sqrt(Numeric:D) returns Numeric:D

Usage:

    sqrt NUMERIC
    NUMERIC.sqrt

Returns a square root of the number. For real numbers the positive square
root is returned.

On negative real numbers, C<sqrt> returns C<NaN> rather than a complex number,
in order to not confuse people who are not familiar with complex arithmetic.
If you want to calculate complex square roots, coerce to C<Complex> first, or
use the C<roots> method.

=head2 method conj

Defined as:

    multi method conj(Numeric:D) returns Numeric:D

Usage:

    NUMERIC.conj

Returns the complex conjugate of the number. Returns the number itself for
real numbers.

=head2 method Bool

Defined as:

    multi method Bool(Numeric:D:)

Usage:

    NUMERIC.Bool

Returns C<False> if the number is equivalent to zero, and C<True> otherwise.

=head2 method succ

Defined as:

    method succ(Numeric:D:)

Usage:

    NUMERIC.succ

Returns the number incremented by one (successor).

=head2 method pred

Defined as:

    method pred(Numeric:D:)

Usage:

    NUMERIC.pred

Returns the number decremented by one (predecessor).

=end pod