Rational

A module for rational numbers in Carp.

Fractions are expressed as pairs of integers: a numerator and a denominator. Mathematical operations and conversion primitives to and from integers and floating point numbers are provided.

(load "git@github.com:carpentry-org/rational@0.6.0")

(Rational.new 22 12) ; => (Rational 11/6)
(* (Rational.new 22 12) (Rational.new 1 6)) ; => (Rational 2/1)
(to-int (Rational.new 2 1)) ; => 2
(to-float (Rational.new 1 4)) ; => 0.25
(to-double (Rational.new 1 4)) ; => 0.25

<

defn

(Fn [(Ref Rational a), (Ref Rational b)] Bool) 

                        (< a b)

checks whether Rational a is less than b.

<=

defn

(Fn [a, a] Bool) 

                        (<= a b)

checks whether Rational a is less than or equal to b.

=

defn

(Fn [(Ref Rational a), (Ref Rational a)] Bool) 

                        (= a b)

compares two Rationals a and b.

>

defn

(Fn [a, a] Bool) 

                        (> a b)

checks whether Rational a is greater than b.

>=

defn

(Fn [a, a] Bool) 

                        (>= a b)

checks whether Rational a is greater than or equal to b.

abs

defn

(Fn [Rational] Rational) 

                        (abs r)

returns the absolute value of the Rational r.

add

defn

(Fn [(Ref Rational a), (Ref Rational b)] Rational) 

                        (add a b)

adds two Rationals a and b.

ceil

defn

(Fn [Rational] a) 

                        (ceil r)

returns the smallest integer not less than the Rational r (rounding toward positive infinity) as a whole Rational.

clamp

defn

(Fn [(Ref a b), (Ref a b), (Ref a b)] a) 

                        (clamp lo hi x)

clamps the Rational x into the inclusive range [lo, hi], which assumes lo is not greater than hi.

copy

instantiate

(Fn [(Ref Rational a)] Rational)

copies a Rational.

delete

instantiate

(Fn [Rational] ())

deletes a Rational. Should usually not be called manually.

denominator

instantiate

(Fn [(Ref Rational a)] (Ref Int a))

gets the denominator property of a Rational.

div

defn

(Fn [(Ref Rational a), (Ref Rational b)] Rational) 

                        (div a b)

divides two Rationals a and b.

floor

defn

(Fn [Rational] a) 

                        (floor r)

returns the largest integer not greater than the Rational r (rounding toward negative infinity) as a whole Rational.

from-double

defn

(Fn [Double] Rational) 

                        (from-double f)

builds a Rational from a Double d.

from-float

defn

(Fn [Float] Rational) 

                        (from-float f)

builds a Rational from a Float f.

from-int

defn

(Fn [Int] Rational) 

                        (from-int i)

builds a Rational from an Integer i.

from-string

defn

(Fn [(Ref String a)] (Maybe Rational)) 

                        (from-string s)

parses a Rational from text: either a fraction like 3/4 or -2/7, or a bare integer like 5. The result is reduced to lowest terms and its sign normalized onto the numerator, so 6/-8 yields -3/4. Returns Nothing for malformed input, an empty numerator or denominator, or a zero denominator.

hash

defn

(Fn [(Ref Rational a)] Int) 

                        (hash r)

calculates the hash of the Rational r.

max

defn

(Fn [(Ref a b), (Ref a b)] a) 

                        (max a b)

returns the larger of the Rationals a and b.

min

defn

(Fn [(Ref a b), (Ref a b)] a) 

                        (min a b)

returns the smaller of the Rationals a and b.

modulo

defn

(Fn [(Ref Rational a), (Ref Rational b)] Rational) 

                        (modulo a b)

calculates the modulo of two Rationals a and b.

mul

defn

(Fn [(Ref Rational a), (Ref Rational b)] Rational) 

                        (mul a b)

multiplies two Rationals a and b.

neg

defn

(Fn [Rational] Rational) 

                        (neg r)

negates the Rational r.

neg?

defn

(Fn [(Ref Rational a)] Bool) 

                        (neg? r)

returns whether the Rational r is strictly negative.

new

defn

(Fn [Int, Int] Rational) 

                        (new n d)

builds a Rational from a numerator n and a denominator d.

The resulting fraction is always in lowest terms. Negative denominators are normalized so the sign is carried by the numerator.

numerator

instantiate

(Fn [(Ref Rational a)] (Ref Int a))

gets the numerator property of a Rational.

pos?

defn

(Fn [(Ref Rational a)] Bool) 

                        (pos? r)

returns whether the Rational r is strictly positive. Since a Rational always carries its sign on the numerator, this is the sign of the numerator.

pow

defn

(Fn [(Ref Rational a), Int] Rational) 

                        (pow r n)

raises the Rational r to the integer power n. A negative exponent inverts the fraction, so r^-n is (1/r)^n, and r^0 is 1. Like the other arithmetic operations the result can overflow for large powers, and a negative power of zero is undefined.

prn

instantiate

(Fn [(Ref Rational a)] String)

converts a Rational to a string.

reciprocal

defn

(Fn [(Ref Rational a)] Rational) 

                        (reciprocal r)

returns the reciprocal (multiplicative inverse) 1/r of the Rational r. The reciprocal of zero is undefined, mirroring division by zero.

round

defn

(Fn [Rational] a) 

                        (round r)

rounds the Rational r to the nearest integer, with halves rounded away from zero, as a whole Rational.

set-denominator

instantiate

(Fn [Rational, Int] Rational)

sets the denominator property of a Rational.

set-denominator!

instantiate

(Fn [(Ref Rational a), Int] ())

sets the denominator property of a Rational in place.

set-numerator

instantiate

(Fn [Rational, Int] Rational)

sets the numerator property of a Rational.

set-numerator!

instantiate

(Fn [(Ref Rational a), Int] ())

sets the numerator property of a Rational in place.

sign

defn

(Fn [Rational] a) 

                        (sign r)

returns the sign of the Rational r as a Rational: -1 when r is negative, 0 when it is zero, and 1 when it is positive. The numerator carries the sign, so a positive denominator is guaranteed by new.

str

defn

(Fn [(Ref Rational a)] String) 

                        (str r)

stringifies the Rational r. The format is (Rational <numerator>/<denominator>).

sub

defn

(Fn [(Ref Rational a), (Ref Rational b)] Rational) 

                        (sub a b)

subtracts two Rationals a and b.

to-double

defn

(Fn [(Ref Rational a)] Double) 

                        (to-double r)

converts a Rational r to a Double.

This function might incur a precision loss.

to-float

defn

(Fn [(Ref Rational a)] Float) 

                        (to-float r)

converts a Rational r to a Float.

This function might incur a precision loss.

to-int

defn

(Fn [(Ref Rational a)] Int) 

                        (to-int r)

converts a Rational r to an Integer.

This function might incur a precision loss; it truncates toward zero. See floor, ceil, and round for other rounding modes.

update-denominator

instantiate

(Fn [Rational, (Ref (Fn [Int] Int a) b)] Rational)

updates the denominator property of a Rational using a function f.

update-numerator

instantiate

(Fn [Rational, (Ref (Fn [Int] Int a) b)] Rational)

updates the numerator property of a Rational using a function f.

zero

defn

(Fn [] Rational) 

                        (zero)

zero?

defn

(Fn [(Ref Rational a)] Bool) 

                        (zero? r)

returns whether the Rational r is zero, i.e. its numerator is zero.