Num.pod6

=begin pod

=TITLE class Num

=SUBTITLE Floating-point number

    class Num is Cool does Real { }

A C<Num> object stores a floating-point number. It is immutable. On most
platforms, it's an IEEE 754 64-bit floating point numbers, aka "double
precision".

=head2 Inf

The value X<C<Inf>|Inf (definition)> is an instance of C<Num> and represents
value that's too large to represent in 64-bit double-precision floating point
number (roughly, above C<1.7976931348623158e308> for positive C<Inf> and
below C<-1.7976931348623157e308> for negative C<Inf>) as well as returned
from certain operations as defined by the IEEE 754-2008 standard.

    say 2e300 ** 2e300; # OUTPUT: «Inf␤»
    say (-1/0).Num;     # OUTPUT: «-Inf␤»

The X<C<∞>|∞ (definition)> C<U+221E> Unicode character can be used instead of
the word C<Inf> and can be handy when C<Inf> would otherwise require an
L<unspace|/language/syntax#Unspace>, such as when writing L<Complex> numbers:

    say Inf+Inf\i; # Backslash (unspace) before `i` required
    say ∞+∞i;      # No backslash is needed

Note that there are just two infinities (positive and negative), so even if
an operation that would instinctively give a "larger" infinity is performed,
the result in still an infinity of the original magnitude. The infinities
can be compared and operated as if they were simply a number that's too big
to represent:

    say ∞²;              # OUTPUT: «Inf␤»
    say 42 + Inf === ∞;  # OUTPUT: «True␤»
    say atan ∞;          # OUTPUT: «1.5707963267949␤»
    say -∞ < 42 < ∞;     # OUTPUT: «True␤»

Division of an infinity by an infinity results in a C<NaN>:

    say ∞/∞;             # OUTPUT: «NaN␤»

=head2 NaN

The value X<C<NaN>|NaN (definition)> is an instance of C<Num> and represents a
floating point not-a-number value, which is returned from some routines where
a concrete number as the answer is not defined, but a L<Numeric> value is still
acceptable. C<NaN> is L<defined> and L<boolifies|/routine/Bool>
to C<True>, but is I<not> numerically equal to any value (including itself).

    say cos ∞;     # OUTPUT: «NaN␤»
    say (0/0).Num; # OUTPUT: «NaN␤»

To test for C<NaN>, use L<isNaN> method or L<=== operator|/routine/===>:

    say (0/0).isNaN;       # OUTPUT: «True␤»
    say (0/0).Num === NaN; # OUTPUT: «True␤»

=head2 method rand

    method rand(Num:D: --> Num)

Returns a pseudo random number between 0 and the invocant.

=head2 sub srand

    sub srand(Int $seed --> Int:D)

Seeds the pseudo random number generator used by L<Num.rand|/type/Num#rand> with
the provided value. Note that C<srand> is called with a platform dependent
value when a Perl 6 program is started.

=head2 method Capture

Defined as:

    method Capture()

Throws C<X::Cannot::Capture>.

=head2 Int

    method Int(Num:D:)

Converts the number to an L<Int>. L<Fails|/routine/fail> with
C<X::Numeric::CannotConvert> if the invocant is L«is a C<NaN>|/routine/isNaN»
or C<Inf>/C<-Inf>. No L<rounding|/routine/round> is performed.

=head2 Rat

    method Rat(Num:D: Real $epsilon = 1e-6)

Converts the number to a L<Rat> with the precision C<$epsilon>. If invocant
is a C<Inf>, C<-Inf>, or a C<NaN>, converts them to a L<Rat> with C<0>
L<denominator> and C<1>, C<-1>, or C<0> L<numerator>, respectively.

=head2 FatRat

    method FatRat(Num:D: Real $epsilon = 1e-6)

Converts the number to a L<FatRat> with the precision C<$epsilon>. If invocant
is a C<Inf>, C<-Inf>, or a C<NaN>, converts them to a L<FatRat> with C<0>
L<denominator> and C<1>, C<-1>, or C<0> L<numerator>, respectively.

=end pod

# vim: expandtab softtabstop=4 shiftwidth=4 ft=perl6