role Rational
Error ReportCollection examples

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 (NuT) and denominator (DeT). By default, these are Int, but other types of Rational are possible by using a different parameterization. In addition, Rational objects are immutable throughout their life.

class Positive does Rational[UInt{};
my Positive $one-third = Positive.new(1,3);
say $one-third;                         # OUTPUT: «0.333333␤» 
my Positive $fail =Positive.new(-2,3);  # OUTPUT: «Type check failed in binding to parameter 'nu'; expected UInt but got Int (-2)␤»

Please note that, since DeT is by default equal to NuT, in this case both are instantiated to UInt. Built into Raku are Rat and FatRat, which both do the Rational role.


method new

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

Creates a new rational object from numerator and denominator, which it normalizes to the lowest terms. The $denominator can be zero, in which case the numerator is normalized to -1, 0, or 1 depending on whether the original is negative, zero, or positive, respectively.

method Bool

Defined as:

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

Returns False if numerator is 0, otherwise returns True. This applies for <0/0> zero-denominator Rational as well, despite ?<0/0>.Num being True.

method Bridge

Defined as:

method Bridge()

Returns the number, converted to Num.

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 Num

Defined as:

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

Coerces the invocant to Num by dividing numerator by denominator. If denominator is 0, returns Inf, -Inf, or NaN, based on whether numerator is a positive number, negative number, or 0, respectively.

method ceiling

Defined as:

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

Return the smallest integer not less than the invocant. If denominator is zero, fails with X::Numeric::DivideByZero.

method floor

Defined as:

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

Return the largest integer not greater than the invocant. If denominator is zero, fails with X::Numeric::DivideByZero.

method isNaN

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

Tests whether the invocant's Num value is a NaN, an acronym for Not available Number. 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)

DEPRECATED as of 6.d. The method is no longer needed, because as of 6.d language version, it's required for Rational type to be normalized on creation.

Returns a normalized Rational object, i.e. with positive denominator, and numerator and denominator coprime. The denominator can also by zero, but using it in any operation or a conversion to string will result in an exception.

use v6.c;
my Rational $by-zero = 3/0;
say $by-zero.norm.raku# OUTPUT: «<1/0>␤» 
say $by-zero# OUTPUT: «Attempt to divide by zero when coercing Rational to Str␤ 

method base-repeating

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

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).raku;          # OUTPUT: «("2.5", "")␤»

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

$base defaults to 10.

method Range

Returns a Range object that represents the range of values supported.