# View Source Ratio(ratio v3.0.2)

This module allows you to use Rational numbers in Elixir, to enable exact calculations with all numbers big and small.

`Ratio` defines arithmetic and comparison operations to work with rational numbers.

Usually, you probably want to add the line `import Ratio, only: [<|>: 2]` to your code.

## shorthand-operator Shorthand operator

Rational numbers can be written using the operator `<|>` (as in: `1 <|> 2`), which is also how Ratio structs are pretty-printed when inspecting. `a <|> b` is a shorthand for `Ratio.new(a, b)`.

## inline-math-operators-and-casting Inline Math Operators and Casting

Ratio interopts with the `Numbers` library: If you want to overload Elixir's builtin math operators, you can use `use Numbers, overload_operators: true`.

This also allows you to pass in a rational number as one argument and an integer, float or Decimal (if you have installed the `Decimal` library), which are then cast to rational numbers whenever necessary.

# Link to this section Summary

## Functions

A Rational number is defined as a numerator and a denominator. Both the numerator and the denominator are integers. If you want to match for a rational number, you can do so by matching against this Struct.

Creates a new Rational number. This number is simplified to the most basic form automatically.

Returns the absolute version of the given number (which might be an integer, float or Rational).

Adds two rational numbers.

Rounds a number (rational, integer or float) to the largest whole number larger than or equal to num. For negative numbers, this means we are rounding towards negative infinity.

Compares two rational numbers, returning `:lt`, `:eg` or `:gt` depending on whether a is less than, equal to or greater than b, respectively.

Treats the passed number as a Rational number, and extracts its denominator. For integers, returns `1`.

Divides the rational number a by the rational number b.

True if a is equal to b

True if a is equal to b?

Rounds a number (rational, integer or float) to the largest whole number less than or equal to num. For negative numbers, this means we are rounding towards negative infinity.

True if a is larger than or equal to b

True if a is larger than or equal to b

Check to see whether something is a ratioal struct.

True if a is smaller than b

True if a is smaller than or equal to b

Negates the given rational number.

Multiplies two rational numbers.

Prefix-version of `numerator <|> denominator`. Useful when `<|>` is not available (for instance, when already in use by another module)

Converts the passed number as a Rational number, and extracts its denominator. For integers returns the passed number itself.

returns x to the n th power.

Returns the sign of the given number (which might be an integer, float or Rational)

Subtracts the rational number b from the rational number a.

Converts the given number to a Float. As floats do not have arbitrary precision, this operation is generally not reversible.

Returns a tuple, where the first element is the result of `to_float(number)` and the second is a conversion error.

Returns a binstring representation of the Rational number. If the denominator is `1` it will still be printed in the `a <|> 1` format.

Returns the integer part of number.

# Link to this section Types

Link to this type

# t()

View Source
`@type t() :: %Ratio{denominator: pos_integer(), numerator: integer()}`

# Link to this section Functions

Link to this function

# %Ratio{}

View Source (struct)

A Rational number is defined as a numerator and a denominator. Both the numerator and the denominator are integers. If you want to match for a rational number, you can do so by matching against this Struct.

Note that directly manipulating the struct, however, is usually a bad idea, as then there are no validity checks, nor wil the rational be simplified.

Use `Ratio.<|>/2` or `Ratio.new/2` instead.

Link to this function

# numerator <|> denominator

View Source

Creates a new Rational number. This number is simplified to the most basic form automatically.

Rational numbers with a `0` as denominator are not allowed.

Note that it is recommended to use integer numbers for the numerator and the denominator.

## floats Floats

If possible, don't use them.

Using Floats for the numerator or denominator is possible, however, because base-2 floats cannot represent all base-10 fractions properly, the results might be different from what you might expect. See The Perils of Floating Point for more information about this.

Floats are converted into rationals by using `Float.ratio` (since version 3.0).

## decimals Decimals

To use `Decimal` parameters, the decimal library must be configured in `mix.exs`.

## examples Examples

``````iex> 1 <|> 2
1 <|> 2
iex> 100 <|> 300
1 <|> 3
iex> 1.5 <|> 4
3 <|> 8
iex> (3 <|> 2) <|> 3
1 <|> 2
iex> 3 <|> (3<|>2)
2 <|> 1
iex> (3<|>2) <|> (1<|>3)
9 <|> 2``````
Link to this function

# abs(number)

View Source

Returns the absolute version of the given number (which might be an integer, float or Rational).

## examples Examples

``````iex>Ratio.abs(-5 <|> 2)
5 <|> 2``````
Link to this function

View Source

Adds two rational numbers.

Link to this function

# ceil(num)

View Source

Rounds a number (rational, integer or float) to the largest whole number larger than or equal to num. For negative numbers, this means we are rounding towards negative infinity.

iex> Ratio.ceil(Ratio.new(1, 2)) 1 iex> Ratio.ceil(Ratio.new(5, 4)) 2 iex> Ratio.ceil(Ratio.new(-3, 2)) -1 iex> Ratio.ceil(Ratio.new(400)) 400

Link to this function

# compare(a, b)

View Source

Compares two rational numbers, returning `:lt`, `:eg` or `:gt` depending on whether a is less than, equal to or greater than b, respectively.

This function is able to compare rational numbers against integers or floats as well.

This function accepts other types as input as well, comparing them using Erlang's Term Ordering. This is mostly useful if you have a collection that contains other kinds of numbers (builtin integers or floats) as well.

Link to this function

# denominator(number)

View Source

Treats the passed number as a Rational number, and extracts its denominator. For integers, returns `1`.

Link to this function

# div(a, b)

View Source

Divides the rational number a by the rational number b.

## examples Examples

iex> Ratio.div(2 <|> 3, 8 <|> 5) 5 <|> 12

Link to this function

# eq?(a, b)

View Source

True if a is equal to b

Link to this function

# equal?(a, b)

View Source

True if a is equal to b?

Link to this function

# floor(num)

View Source

Rounds a number (rational, integer or float) to the largest whole number less than or equal to num. For negative numbers, this means we are rounding towards negative infinity.

iex> Ratio.floor(Ratio.new(1, 2)) 0 iex> Ratio.floor(Ratio.new(5, 4)) 1 iex> Ratio.floor(Ratio.new(-3, 2)) -2

Link to this function

# gt?(a, b)

View Source

True if a is larger than or equal to b

Link to this function

# gte?(a, b)

View Source

True if a is larger than or equal to b

Link to this macro

# is_rational(val)

View Source (macro)

Check to see whether something is a ratioal struct.

On recent OTP versions that expose `:erlang.map_get/2` this function is guard safe.

iex> require Ratio iex> Ratio.is_rational(1 <|> 2) true iex> Ratio.is_rational(Ratio.new(10)) true iex> Ratio.is_rational(42) false iex> Ratio.is_rational(%{}) false iex> Ratio.is_rational("My quick brown fox") false

Link to this function

# lt?(a, b)

View Source

True if a is smaller than b

Link to this function

# lte?(a, b)

View Source

True if a is smaller than or equal to b

Link to this function

# minus(ratio)

View Source

Negates the given rational number.

## examples Examples

iex> Ratio.minus(5 <|> 3) -5 <|> 3

Link to this function

# mult(number1, number2)

View Source

Multiplies two rational numbers.

# Examples

iex> Ratio.mult( 1 <|> 3, 1 <|> 2) 1 <|> 6

Link to this function

# new(numerator, denominator \\ 1)

View Source

Prefix-version of `numerator <|> denominator`. Useful when `<|>` is not available (for instance, when already in use by another module)

Not imported when calling `use Ratio`, so always call it as `Ratio.new(a, b)`

To use `Decimal` parameters, the decimal library must be configured in `mix.exs`.

## examples Examples

``````iex> Ratio.new(1, 2)
1 <|> 2
iex> Ratio.new(100, 300)
1 <|> 3``````
Link to this function

# numerator(number)

View Source

Converts the passed number as a Rational number, and extracts its denominator. For integers returns the passed number itself.

Link to this function

# pow(x, n)

View Source
`@spec pow(number() | t(), pos_integer()) :: t()`

returns x to the n th power.

x is allowed to be an integer, rational or float (in the last case, this is first converted to a rational).

Will give the answer as a rational number when applicable. Note that the exponent n is only allowed to be an integer.

(so it is not possible to compute roots using this function.)

## examples Examples

``````iex> Ratio.pow(Ratio.new(2), 4)
16 <|> 1
iex> Ratio.pow(Ratio.new(2), -4)
1 <|> 16
iex> Ratio.pow(3 <|> 2, 10)
59049 <|> 1024
iex> Ratio.pow(Ratio.new(10), 0)
1 <|> 1``````
Link to this function

# sign(number)

View Source

Returns the sign of the given number (which might be an integer, float or Rational)

This is:

• 1 if the number is positive.
• -1 if the number is negative.
• 0 if the number is zero.
Link to this function

# sub(a, b)

View Source

Subtracts the rational number b from the rational number a.

Link to this function

# to_float(number)

View Source
`@spec to_float(t() | number()) :: float()`

Converts the given number to a Float. As floats do not have arbitrary precision, this operation is generally not reversible.

Not imported when calling `use Ratio`, so always call it as `Rational.to_float(number)`

Link to this function

# to_float_error(number)

View Source
`@spec to_float_error(t() | number()) :: {float(), error} when error: t() | number()`

Returns a tuple, where the first element is the result of `to_float(number)` and the second is a conversion error.

The conversion error is calculated by subtracting the original number from the conversion result.

## examples Examples

``````iex> Ratio.to_float_error(Ratio.new(1, 2))
{0.5, 0 <|> 1}
iex> Ratio.to_float_error(Ratio.new(2, 3))
{0.6666666666666666, -1 <|> 27021597764222976}``````
Link to this function

# to_string(rational)

View Source

Returns a binstring representation of the Rational number. If the denominator is `1` it will still be printed in the `a <|> 1` format.

## examples Examples

``````iex> Ratio.to_string 10 <|> 7
"10 <|> 7"
iex> Ratio.to_string 10 <|> 2
"5 <|> 1"``````
Link to this function

# trunc(num)

View Source
`@spec trunc(t() | number()) :: integer()`

Returns the integer part of number.

## examples Examples

``````iex> Ratio.trunc(1.7)
1
iex> Ratio.trunc(-1.7)
-1
iex> Ratio.trunc(3)
3
iex> Ratio.trunc(Ratio.new(5, 2))
2``````