A null Rational.

Create a new Rational from an Int.

Some(rational.from_int(14)) == rational.new(14, 1)
Some(rational.from_int(-5)) == rational.new(-5, 1)
Some(rational.from_int(0)) == rational.new(0, 1)

Make a Rational number from the ratio of two integers.

Returns None when the denominator is null.

rational.new(14, 42) == Some(r)
rational.new(14, 0) == None

Get the denominator of a rational value.

expect Some(x) = rational.new(2, 3)
rational.denominator(x) == 3

Get the numerator of a rational value.

expect Some(x) = rational.new(2, 3)
rational.numerator(x) == 2

Absolute value of a Rational.

expect Some(x) = rational.new(3, 2)
expect Some(y) = rational.new(-3, 2)

rational.abs(x) == x
rational.abs(y) == x

Change the sign of a Rational.

expect Some(x) = rational.new(3, 2)
expect Some(y) = rational.new(-3, 2)

rational.negate(x) == y
rational.negate(y) == x

Reciprocal of a Rational number. That is, a new Rational where the numerator and denominator have been swapped.

expect Some(x) = rational.new(2, 5)
rational.reciprocal(x) == rational.new(5, 2)

let y = rational.zero
rational.reciprocal(y) == None

Reduce a rational to its irreducible form. This operation makes the numerator and denominator coprime.

expect Some(x) = rational.new(80, 200)
Some(rational.reduce(x)) == rational.new(2, 5)

Addition: sum of two rational values

expect Some(x) = rational.new(2, 3)
expect Some(y) = rational.new(3, 4)

Some(rational.add(x, y)) == rational.new(17, 12)

Division: quotient of two rational values. Returns None when the second value is null.

expect Some(x) = rational.new(2, 3)
expect Some(y) = rational.new(3, 4)

rational.div(x, y) == rational.new(8, 9)

Multiplication: the product of two rational values.

expect Some(x) = rational.new(2, 3)
expect Some(y) = rational.new(3, 4)

Some(rational.mul(x, y)) == rational.new(6, 12)

Subtraction: difference of two rational values

expect Some(x) = rational.new(2, 3)
expect Some(y) = rational.new(3, 4)

Some(rational.sub(x, y)) == rational.new(-1, 12)

Compare two rationals for an ordering. This is safe to use even for non-reduced rationals.

expect Some(x) = rational.new(2, 3)
expect Some(y) = rational.new(3, 4)
expect Some(z) = rational.new(4, 6)

compare(x, y) == Less
compare(y, x) == Greater
compare(x, x) == Equal
compare(x, z) == Equal

Comparison of two rational values using a chosen heuristic. For example:

expect Some(x) = rational.new(2, 3)
expect Some(y) = rational.new(3, 4)

rational.compare_with(x, >, y) == False
rational.compare_with(y, >, x) == True
rational.compare_with(x, >, x) == False
rational.compare_with(x, >=, x) == True
rational.compare_with(x, ==, x) == True
rational.compare_with(x, ==, y) == False

Calculate the arithmetic mean between two Rational values.

let x = rational.from_int(0)
let y = rational.from_int(1)
let z = rational.from_int(2)

expect Some(result) = rational.arithmetic_mean([x, y, z])

rational.compare(result, y) == Equal

Calculate the geometric mean between two Rational values. This returns either the exact result or the smallest integer nearest to the square root for the numerator and denominator.

expect Some(x) = rational.new(1, 3)
expect Some(y) = rational.new(1, 6)

rational.geometric_mean(x, y) == rational.new(1, 4)

Returns the smallest Int not less than a given Rational

expect Some(x) = rational.new(2, 3)
rational.ceil(x) == 1

expect Some(y) = rational.new(44, 14)
rational.ceil(y) == 4

expect Some(z) = rational.new(-14, 3)
rational.ceil(z) == -4

Returns the greatest Int no greater than a given Rational

expect Some(x) = rational.new(2, 3)
rational.floor(x) == 0

expect Some(y) = rational.new(44, 14)
rational.floor(y) == 3

expect Some(z) = rational.new(-14, 3)
rational.floor(z) == -5

Computes the rational number x raised to the power y. Returns None for invalid exponentiation.

expect Some(x) = rational.new(50, 2500)
rational.reduce(rational.pow(x, 3)) == rational.new(1, 125000)

expect Some(x) = rational.new(50, 2500)
rational.reduce(rational.pow(x, -3)) == rational.new(125000, 1)

Returns the proper fraction of a given Rational r. That is, a 2-tuple of an Int and Rational (n, f) such that:

• r = n + f;
• n and f have the same sign as r;
• f has an absolute value less than 1.

Round the argument to the nearest whole number. If the argument is equidistant between two values, the greater value is returned (it rounds half towards positive infinity).

expect Some(x) = rational.new(2, 3)
rational.round(x) == 1

expect Some(y) = rational.new(3, 2)
rational.round(y) == 2

expect Some(z) = rational.new(-3, 2)
rational.round(z) == -1

This behaves differently than Haskell. If you’re coming from PlutusTx, beware that in Haskell, rounding on equidistant values depends on the whole number being odd or even. If you need this behaviour, use round_even.

Round the argument to the nearest whole number. If the argument is equidistant between two values, it returns the value that is even (it rounds half to even, also known as ‘banker’s rounding’).

expect Some(w) = rational.new(2, 3)
rational.round_even(w) == 1

expect Some(x) = rational.new(3, 2)
rational.round_even(x) == 2

expect Some(y) = rational.new(5, 2)
rational.round_even(y) == 2

expect Some(y) = rational.new(-3, 2)
rational.round_even(y) == -2

Returns the nearest Int between zero and a given Rational.

expect Some(x) = rational.new(2, 3)
rational.truncate(x) == 0

expect Some(y) = rational.new(44, 14)
rational.truncate(y) == 3

expect Some(z) = rational.new(-14, 3)
rational.truncate(z) == -4