role Rational

Number stored as numerator and denominator

role Rational[::NuT, ::DeTdoes Real { ... }

Rational is the common role for numbers that are stored as pairs of numerator and denominator. It is parameterized by the types of the numerator and denominator.

Built into Perl 6 are Rat and FatRat, which both do the Rational role.

Methods

method new

method new(NuT:D: $numeratorDeT:D: $denominator --> Rational:D)

Creates a new rational object from numerator and denominator.

method Int

Defined as:

method Int(Rational:D: --> Int:D)

Coerces the invocant to Int by truncating non-whole portion of the represented number, if any. If the denominator is zero, will fail with X::Numeric::DivideByZero.

method isNaN

method isNaN(Rational:D: --> Bool:D)

Tests whether the invocant's Num value is a NaN. That is both its numerator and denominator are zero.

method numerator

method numerator(Rational:D: --> NuT:D)

Returns the numerator.

method denominator

method denominator(Rational:D: --> DeT:D)

Returns the denominator.

method nude

method nude(Rational:D: --> Positional)

Returns a list of the numerator and denominator.

method norm

method norm(Rational:D: --> Rational:D)

Returns a normalized Rational object, i.e. with positive denominator, and numerator and denominator coprime.

method base-repeating

method base-repeating(Rational:D: Int:D() $base)

Returns a list of two strings that, when concatenated, represent the number in base $base. The second element is the one that repeats. For example:

my ($non-rep$repeating= (19/3).base-repeating(10);
say $non-rep;                               # OUTPUT: «6.␤» 
say $repeating;                             # OUTPUT: «3␤» 
printf '%s(%s)'$non-rep$repeating;      # OUTPUT: «6.(3)» 

19/3 is 6.333333... with the 3 repeating indefinitely.

If no repetition occurs, the second string is empty:

say (5/2).base-repeating(10).perl;          # OUTPUT: «("2.5", "")␤» 

The precision for determining the repeating group is limited to 1000 characters, above that, the second string is ???.

Type graph

Type relations for Rational
perl6-type-graph Rational Rational Real Real Rational->Real Numeric Numeric Real->Numeric Mu Mu Any Any Any->Mu Cool Cool Cool->Any FatRat FatRat FatRat->Rational FatRat->Cool Rat Rat Rat->Rational Rat->Cool Stringy Stringy Str Str Str->Cool Str->Stringy RatStr RatStr RatStr->Rat RatStr->Str

Stand-alone image: vector

Routines supplied by role Real

Rational does role Real, which provides the following methods:

(Real) method Rat

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

Converts the number to a Rat with the precision $epsilon.

(Real) routine rand

sub term:<rand> (--> Num:D)
method rand(Real:D: --> Real:D)

Returns a pseudo-random number between zero and the number.

The term form returns a pseudo-random Num between 0e0 and 1e0.

(Real) method sign

method sign(Real:D:)

Returns -1 if the number is negative, 0 if it is zero and 1 otherwise.

(Real) method round

method round(Real:D: $scale = 1)

Rounds the number to scale $scale. If $scale is 1, rounds to an integer. If scale is 0.1, rounds to one digit after the comma etc.

(Real) method floor

method floor(Real:D --> Int:D)

Return the largest integer not greater than the number.

(Real) method ceiling

method ceiling(Real:D --> Int:D)

Returns the smallest integer not less than the number.

(Real) method truncate

method truncate(Real:D --> Int:D)

Rounds the number towards zero.

(Real) method base

method base(Real:D: Int:D $base where 2..36$digits? --> Str:D)

Converts the number to a string, using $base as base. For $base larger than ten, capital Latin letters are used.

255.base(16);            # 'FF' 

The optional $digits argument asks for that many digits of fraction (which may not be negative). If omitted, a reasonable default is chosen based on type. For Int this default is 0. For Num, the default is 8. For Rational, the number of places is scaled to the size of the denominator, with a minimum of 6.

A special value of Whatever (*) can be given as $digits, which functions the same as when $digits is not specified for all Real types except the Rationals. For Rationals, the Whatever indicates that you wish all of the possible digits of the fractional part, but use caution: since there's no detection of repeating fractional parts (the algorithm will eventually stop after generating 2**63 digits).

The final digit produced is always rounded.

say pi.base(103);      # OUTPUT: «3.142␤» 
say (1/128).base(10*); # OUTPUT: «0.0078125␤» 
say (1/100).base(10*); # OUTPUT: «0.01␤» 
say (1/3)  .base(10*); # WRONG: endlessly repeating fractional part 

For reverse operation, see parse-base

Routines supplied by role Numeric

Rational does role Numeric, which provides the following methods:

(Numeric) method Real

method Real(Numeric:D: --> Real:D)

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

(Numeric) method Int

method Int(Numeric:D: --> Int:D)

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

(Numeric) method Rat

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

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

(Numeric) method Num

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

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

(Numeric) method narrow

method narrow(Numeric:D --> Numeric:D)

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

say (4.0 + 0i).narrow.perl;     # OUTPUT: «4␤» 
say (4.0 + 0i).narrow.^name;    # OUTPUT: «Int␤» 

(Numeric) method ACCEPTS

multi method ACCEPTS(Numeric:D: $other)

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

(Numeric) routine log

multi sub    log(Numeric:DNumeric $base = e --> Numeric:D)
multi method log(Numeric:D: Numeric $base = e --> Numeric:D)

Calculates the logarithm to base $base. Defaults to the natural logarithm. Returns NaN if $base is negative. Throws an exception if $base is 1.

(Numeric) routine log10

multi sub    log10(Numeric:D  --> Numeric:D)
multi method log10(Numeric:D: --> Numeric:D)

Calculates the logarithm to base 10. Returns NaN for negative arguments and -Inf for 0.

(Numeric) routine exp

multi sub    exp(Numeric:DNumeric:D $base = e --> Numeric:D)
multi method exp(Numeric:D: Numeric:D $base = e --> Numeric:D)

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

(Numeric) method roots

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

Returns a list of the $n complex roots, which evaluate to the original number when raised to the $nth power.

(Numeric) routine abs

multi sub    abs(Numeric:D  --> Real:D)
multi method abs(Numeric:D: --> Real:D)

Returns the absolute value of the number.

(Numeric) routine sqrt

multi sub    sqrt(Numeric:D --> Numeric:D)
multi method sqrt(Numeric:D --> Numeric:D)

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

On negative real numbers, sqrt returns 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 Complex first, or use the roots method.

(Numeric) method conj

multi method conj(Numeric:D --> Numeric:D)

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

(Numeric) method Bool

multi method Bool(Numeric:D:)

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

(Numeric) method succ

method succ(Numeric:D:)

Returns the number incremented by one (successor).

(Numeric) method pred

method pred(Numeric:D:)

Returns the number decremented by one (predecessor).