# aiken/math/rational

This module implements operations between rational numbers.

Internally, rational aren’t automatically reduced as this is

only done on-demand.Thus, for example:

`rational.new(2, 3) != rational.new(4, 6)`

Comparing rational values should, therefore, only happen after reduction (see reduce) or via the compare method.

# Types

Opaque type used to ensure the sign of the Rational is managed strictly in the numerator.

# Constants

# Functions

## Constructing

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
```

## Inspecting

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
```

## Modifying

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)
```

## Combining

### Arithmetic operations

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)
```

### Ordering

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
```

### Means

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)
```

## Transforming

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
```