(std rational)

Reference

Overview

Exact fractions over bigint.

(import (std rational))

(def third (rational 1 3))
(rational+ third third)                   ; 2/3
(rational* (rational 3 4) (rational 2 3)) ; 1/2
(string->rational "0.3048")               ; (Some 381/1250)
(string->rational "1|60")                 ; (Some 1/60)
(rational->double third)                  ; 0.3333333333333333
(rational->decimal third)                 ; 0.3333333333333333333333333333

Rational is the built-in rational, so these functions and the operators are two ways to the same values: (rational+ a b) is (+ a b). It is always in lowest terms with a positive denominator, so two equal fractions are equal values. Ord compares by value. It is written (: <1|3> rational), which reads back, and displayed 1/3.

Errors. A zero denominator, the reciprocal of zero and zero to a negative power raise DivideByZeroException. rational->decimal raises OverflowException when the integer part does not fit. string->rational returns None for text it does not read.

See also: Rational, rational, string->rational, rational->double, rational->decimal

Reference

Types

Functions

Types

Rational

type alias ↑ Types

The built-in rational: an exact fraction, a bigint numerator and a positive bigint denominator, in lowest terms.

Functions

rational

function ↑ Functions

(: rational (-> bigint bigint Rational))
(rational n d)

The fraction n/d, in lowest terms.

n
The numerator.
d
The denominator. Raises DivideByZeroException when zero.
returns
The fraction, with a positive denominator.
(rational 6 -4)       ; -3/2

int->rational

function ↑ Functions

(: int->rational (-> int Rational))
(int->rational n)

An int as a fraction.

n
The int.
returns
n/1.

bigint->rational

function ↑ Functions

(: bigint->rational (-> bigint Rational))
(bigint->rational n)

A bigint as a fraction.

n
The bigint.
returns
n/1.

rational-num

function ↑ Functions

(: rational-num (-> Rational bigint))
(rational-num x)

The numerator.

x
The fraction.
returns
The numerator in lowest terms, with the sign of x.

rational-den

function ↑ Functions

(: rational-den (-> Rational bigint))
(rational-den x)

The denominator.

x
The fraction.
returns
The denominator in lowest terms. Always positive.

rational+

function ↑ Functions

(: rational+ (-> Rational Rational Rational))
(rational+ a b)

Addition.

a
The first term.
b
The second term.
returns
a + b.

rational-

function ↑ Functions

(: rational- (-> Rational Rational Rational))
(rational- a b)

Subtraction.

a
The minuend.
b
The subtrahend.
returns
a - b.

rational*

function ↑ Functions

(: rational* (-> Rational Rational Rational))
(rational* a b)

Multiplication.

a
The first factor.
b
The second factor.
returns
a * b.

rational/

function ↑ Functions

(: rational/ (-> Rational Rational Rational))
(rational/ a b)

Division.

a
The dividend.
b
The divisor. Raises DivideByZeroException when zero.
returns
a / b.

rational-negate

function ↑ Functions

(: rational-negate (-> Rational Rational))
(rational-negate x)

Negation.

x
The fraction.
returns
-x.

rational-recip

function ↑ Functions

(: rational-recip (-> Rational Rational))
(rational-recip x)

The reciprocal.

x
The fraction. Raises DivideByZeroException when zero.
returns
1/x.

rational-abs

function ↑ Functions

(: rational-abs (-> Rational Rational))
(rational-abs x)

The magnitude.

x
The fraction.
returns
|x|.

rational-expt

function ↑ Functions

(: rational-expt (-> Rational int Rational))
(rational-expt x n)

An integer power.

x
The base.
n
The exponent. Negative takes the reciprocal; 0 gives 1.
returns
x^n. Raises DivideByZeroException for zero to a negative power.
(rational-expt (rational 2 3) -2)   ; 9/4

rational-zero?

function ↑ Functions

(: rational-zero? (-> Rational bool))
(rational-zero? x)

Whether a fraction is zero.

x
The fraction.
returns
#t for 0.

rational-integer?

function ↑ Functions

(: rational-integer? (-> Rational bool))
(rational-integer? x)

Whether a fraction is an integer.

x
The fraction.
returns
#t when the denominator is 1.

rational-sign

function ↑ Functions

(: rational-sign (-> Rational int))
(rational-sign x)

The sign.

x
The fraction.
returns
-1, 0 or 1.

rational-floor

function ↑ Functions

(: rational-floor (-> Rational bigint))
(rational-floor x)

Rounding down.

x
The fraction.
returns
The largest integer at most x.

rational-ceiling

function ↑ Functions

(: rational-ceiling (-> Rational bigint))
(rational-ceiling x)

Rounding up.

x
The fraction.
returns
The smallest integer at least x.

rational-truncate

function ↑ Functions

(: rational-truncate (-> Rational bigint))
(rational-truncate x)

Rounding toward zero.

x
The fraction.
returns
x without its fractional part.

rational-round

function ↑ Functions

(: rational-round (-> Rational bigint))
(rational-round x)

Rounding to nearest.

x
The fraction.
returns
The nearest integer, ties to even.
(rational-round (rational 5 2))    ; 2
(rational-round (rational 7 2))    ; 4

rational->double

function ↑ Functions

(: rational->double (-> Rational double))
(rational->double x)

A fraction as a double.

x
The fraction.
returns
The nearest double, ties to even. Infinity of x's sign when too large.

Rounds once, subnormals included.

rational->decimal

function ↑ Functions

(: rational->decimal (-> Rational decimal))
(rational->decimal x)

A fraction as a decimal.

x
The fraction.
returns
The nearest decimal, ties to even, without trailing zeros.

Rounds once, at the largest scale (up to 28) at which the result fits. Raises OverflowException when the integer part does not fit.

(rational->decimal (rational 1 8))   ; 0.125
(rational->decimal (rational 2 3))   ; 0.6666666666666666666666666667

rational->string

function ↑ Functions

(: rational->string (-> Rational string))
(rational->string x)

A fraction as text.

x
The fraction.
returns
"3" for an integer, "-1/3" otherwise.

See also: string->rational

string->rational

function ↑ Functions

(: string->rational (-> string (Option Rational)))
(string->rational s)

The fraction a text writes.

s
The text.
returns
The fraction, or None.

Reads a decimal: an optional sign, digits with an optional point, and an optional exponent, as in -0.3048, .5 or 2.5E+10. Two decimals separated by | or / are their quotient, as in 1|60. No space is allowed. Returns None for anything else, and for a zero denominator.

(string->rational "1e-3")   ; (Some 1/1000)
(string->rational "1|60")   ; (Some 1/60)
(string->rational "1/0")    ; None
(string->rational "1 m")    ; None