# std/rationals

Dark Mode
Search:
Source   Edit

This module implements rational numbers, consisting of a numerator and a denominator. The denominator can not be 0.

Example:

```import std/rationals
let
r1 = 1 // 2
r2 = -3 // 4

doAssert r1 + r2 == -1 // 4
doAssert r1 - r2 ==  5 // 4
doAssert r1 * r2 == -3 // 8
doAssert r1 / r2 == -2 // 3```

math, hashes

# Types

```Rational[T] = object
num*, den*: T
```
A rational number, consisting of a numerator num and a denominator den.   Source   Edit

# Procs

`func `\$`[T](x: Rational[T]): string`
Turns a rational number into a string.

Example:

`doAssert \$(1 // 2) == "1/2"`
Source   Edit
`func `*=`[T](x: var Rational[T]; y: Rational[T])`
Multiplies the rational x by y in-place.   Source   Edit
`func `*=`[T](x: var Rational[T]; y: T)`
Multiplies the rational x by the int y in-place.   Source   Edit
`func `*`[T](x, y: Rational[T]): Rational[T]`
Multiplies two rational numbers.   Source   Edit
`func `*`[T](x: Rational[T]; y: T): Rational[T]`
Multiplies the rational x with the int y.   Source   Edit
`func `*`[T](x: T; y: Rational[T]): Rational[T]`
Multiplies the int x with the rational y.   Source   Edit
`func `+=`[T](x: var Rational[T]; y: Rational[T])`
Adds the rational y to the rational x in-place.   Source   Edit
`func `+=`[T](x: var Rational[T]; y: T)`
Adds the int y to the rational x in-place.   Source   Edit
`func `+`[T](x, y: Rational[T]): Rational[T]`
Adds two rational numbers.   Source   Edit
`func `+`[T](x: Rational[T]; y: T): Rational[T]`
Adds the rational x to the int y.   Source   Edit
`func `+`[T](x: T; y: Rational[T]): Rational[T]`
Adds the int x to the rational y.   Source   Edit
`func `-=`[T](x: var Rational[T]; y: Rational[T])`
Subtracts the rational y from the rational x in-place.   Source   Edit
`func `-=`[T](x: var Rational[T]; y: T)`
Subtracts the int y from the rational x in-place.   Source   Edit
`func `-`[T](x, y: Rational[T]): Rational[T]`
Subtracts two rational numbers.   Source   Edit
`func `-`[T](x: Rational[T]): Rational[T]`
Unary minus for rational numbers.   Source   Edit
`func `-`[T](x: Rational[T]; y: T): Rational[T]`
Subtracts the int y from the rational x.   Source   Edit
`func `-`[T](x: T; y: Rational[T]): Rational[T]`
Subtracts the rational y from the int x.   Source   Edit
`func `//`[T](num, den: T): Rational[T]`
A friendlier version of initRational.

Example:

```let x = 1 // 3 + 1 // 5
doAssert x == 8 // 15```
Source   Edit
`func `/=`[T](x: var Rational[T]; y: Rational[T])`
Divides the rational x by the rational y in-place.   Source   Edit
`func `/=`[T](x: var Rational[T]; y: T)`
Divides the rational x by the int y in-place.   Source   Edit
`func `/`[T](x, y: Rational[T]): Rational[T]`
Divides the rational x by the rational y.   Source   Edit
`func `/`[T](x: Rational[T]; y: T): Rational[T]`
Divides the rational x by the int y.   Source   Edit
`func `/`[T](x: T; y: Rational[T]): Rational[T]`
Divides the int x by the rational y.   Source   Edit
`func `<=`(x, y: Rational): bool`
Returns tue if x is less than or equal to y.   Source   Edit
`func `<`(x, y: Rational): bool`
Returns true if x is less than y.   Source   Edit
`func `==`(x, y: Rational): bool`
Compares two rationals for equality.   Source   Edit
`func `div`[T: SomeInteger](x, y: Rational[T]): T`
Computes the rational truncated division.   Source   Edit
`func `mod`[T: SomeInteger](x, y: Rational[T]): Rational[T]`
Computes the rational modulo by truncated division (remainder). This is same as x - (x div y) * y.   Source   Edit
`func abs[T](x: Rational[T]): Rational[T]`
Returns the absolute value of x.

Example:

```doAssert abs(1 // 2) == 1 // 2
doAssert abs(-1 // 2) == 1 // 2```
Source   Edit
`func cmp(x, y: Rational): int`
Compares two rationals. Returns
• a value less than zero, if x < y
• a value greater than zero, if x > y
• zero, if x == y
Source   Edit
`func floorDiv[T: SomeInteger](x, y: Rational[T]): T`

Computes the rational floor division.

Floor division is conceptually defined as floor(x / y). This is different from the div operator, which is defined as trunc(x / y). That is, div rounds towards 0 and floorDiv rounds down.

Source   Edit
`func floorMod[T: SomeInteger](x, y: Rational[T]): Rational[T]`

Computes the rational modulo by floor division (modulo).

This is same as x - floorDiv(x, y) * y. This func behaves the same as the % operator in Python.

Source   Edit
`func hash[T](x: Rational[T]): Hash`
Computes the hash for the rational x.   Source   Edit
`func initRational[T: SomeInteger](num, den: T): Rational[T]`

Creates a new rational number with numerator num and denominator den. den must not be 0.

Note: den != 0 is not checked when assertions are turned off.

Source   Edit
`func reciprocal[T](x: Rational[T]): Rational[T]`
Calculates the reciprocal of x (1/x). If x is 0, raises DivByZeroDefect.   Source   Edit
`func reduce[T: SomeInteger](x: var Rational[T])`

Reduces the rational number x, so that the numerator and denominator have no common divisors other than 1 (and -1). If x is 0, raises DivByZeroDefect.

Note: This is called automatically by the various operations on rationals.

Example:

```var r = Rational[int](num: 2, den: 4) # 1/2
reduce(r)
doAssert r.num == 1
doAssert r.den == 2```
Source   Edit
`func toFloat[T](x: Rational[T]): float`
Converts a rational number x to a float.   Source   Edit
`func toInt[T](x: Rational[T]): int`
Converts a rational number x to an int. Conversion rounds towards 0 if x does not contain an integer value.   Source   Edit
```func toRational(x: float; n: int = high(int) shr 32): Rational[int] {.
...raises: [], tags: [].}```

Calculates the best rational approximation of x, where the denominator is smaller than n (default is the largest possible int for maximal resolution).

The algorithm is based on the theory of continued fractions.

Example:

```let x = 1.2
doAssert x.toRational.toFloat == x```
Source   Edit
`func toRational[T: SomeInteger](x: T): Rational[T]`
Converts some integer x to a rational number.

Example:

`doAssert toRational(42) == 42 // 1`
Source   Edit