# std/rationals

Theme:

- Manual
- Standard library
- Index
- Compiler docs
- Fusion docs
- devel, stable

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

# Imports

math, hashes, assertions

# 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, 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])

  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]

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

  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]

  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](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]

  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 `//`[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 `<`(x, y: Rational): bool

  Returns true if `x` is less than `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

  Compares two rationals for equality. Source Edit

    func `^`[T: SomeInteger](x: Rational[T]; y: T): Rational[T]

  Computes `x` to the power of `y`.

  The exponent `y` must be an integer. Negative exponents are supported but floating point exponents are not.

  Example:

      doAssert (-3 // 5) ^ 0 == (1 // 1)
      doAssert (-3 // 5) ^ 1 == (-3 // 5)
      doAssert (-3 // 5) ^ 2 == (9 // 25)
      doAssert (-3 // 5) ^ -2 == (25 // 9)

  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 `div`[T: SomeInteger](x, y: Rational[T]): T

  Computes the rational truncated division. 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 `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 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 16): Rational[int] {.
        ...raises: [], tags: [], forbids: [].}

  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