ratio v1.2.8 Ratio

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

It also defines the new <|> operator and (optionally) overrides the arithmetic +, -, * and / operators to work with ints, floats and Rational numbers all alike.

Floats are also automatically coerced into Rationals whenever possible.

And don’t worry: If you don’t like operator-overloading: There are longhand function aliases available too.

To use the module, use use Ratio where you need it.

If you do not want to override the Kernel’s built-in math operators, use

# Does not override *, /, -, +, div, abs
use Ratio, override_math: false

If you just do not want to override the Kernel’s built-in inline math operators, use use Ratio, inline_math: false

# Does not override *, /, -, +
use Ratio, override_math: false

If you do not want the new operator <|> to be imported, use

# Does not include <|>, construct Rational numbers using Ratio.new(a, b)
use Ratio, operator: false

These options can be combined (with override_math taking precedence over inline_math )

Summary

Functions

Multiplies two numbers. (one or both of which might be integers, floats or rationals)

Unary plus. Returns num. Coerces the number to a rational if it is a float

Adds two numbers, one or both of which might be integers, floats or rationals

Unary minus. Inverts the sign of the given num, which might be an integer, float or rational. Floats are converted to Rationals before inverting the sign

Subtracts b from a. One or both might be integers, floats or rationals

Divides a number by another number, one or both of which might be integers, floats or rationals

Creates a new Rational number. This number is simplified to the most basic form automatically. If the most basic form has the format _ <|> 1, it is returned in integer form

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

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

Longhand for Ratio.+/2

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

Longhand for Ratio.//2

True if a is larger than or equal to b

True if a is larger than or equal to b

Check if a number is a rational number. Returns false if the number is an integer, float or any other type

True if a is smaller than b

True if a is smaller than or equal to b

Alias for Ratio.negate(num); follows Numeric behaviour

Longhand for Ratio.-/1

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)

Longhand for Ratio.-/2

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

Returns a binstring representation of the Rational number. If the denominator is 1, it will be printed as a normal (integer) number

Types

t()
t() :: %Ratio{denominator: pos_integer, numerator: integer}

Functions

a * b

Multiplies two numbers. (one or both of which might be integers, floats or rationals)

Examples

iex> ((2 <|> 3) *  10)
20 <|> 3
iex> ( 1 <|> 3) * (1 <|> 2)
1 <|> 6
+num

Unary plus. Returns num. Coerces the number to a rational if it is a float.

a + b

Adds two numbers, one or both of which might be integers, floats or rationals.

The result is converted to a rational if applicable.

Examples

iex> 2 + 3
5
iex> 2.3 + 0.3
13 <|> 5
iex> 2 + (2 <|> 3)
8 <|> 3
-num

Unary minus. Inverts the sign of the given num, which might be an integer, float or rational. Floats are converted to Rationals before inverting the sign.

Examples

iex> -10
-10
iex> -10.0
-10
iex> -10.1
-101 <|> 10
iex> -(5 <|> 3)
-5 <|> 3
iex> -123.456
-15432 <|> 125
a - b

Subtracts b from a. One or both might be integers, floats or rationals.

The result is converted to a rational if applicable.

Examples

iex> 2 - 3
-1
iex> 2.3 - 0.3
2
iex> 2.3 - 0.1
11 <|> 5
iex> (2 <|> 3) - (1 <|> 5)
7 <|> 15
a / b

Divides a number by another number, one or both of which might be integers, floats or rationals.

The function will return integers whenever possible, and otherwise returns a rational number.

Examples

iex> (1 <|> 3) / 2
1 <|> 6
iex> (2 <|> 3) / (8 <|> 5)
5 <|> 12
numerator <|> denominator

Creates a new Rational number. This number is simplified to the most basic form automatically. If the most basic form has the format _ <|> 1, it is returned in integer form.

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

Tl;Dr: 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.

Passed floats are rounded to 10 digits, to make the result match expectations better. This number can be changed by adding max_float_to_rational_digits: 10 to your config file.

See Ratio.FloatConversion.float_to_rational/2 for more info about float -> rational parsing.

As Float-parsing is done by converting floats to a digit-list representation first, this is also far slower than when using integers or rationals.

Examples

iex> 1 <|> 2
1 <|> 2
iex> 100 <|> 300
1 <|> 3
iex> 1.5 <|> 4
3 <|> 8
__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.

abs(number)

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

Examples

iex>Ratio.abs(-5 <|> 2)
5 <|> 2
add(a, b)

Longhand for Ratio.+/2

ceil(num)
compare(a, b)
denominator(number)

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

div(a, b)

Longhand for Ratio.//2

floor(num)
gt?(a, b)

True if a is larger than or equal to b

gte?(a, b)

True if a is larger than or equal to b

is_rational?(arg1)

Check if a number is a rational number. Returns false if the number is an integer, float or any other type.

To check if a float representation will result in a rational number, combine it with the unary plus operation:

Examples

iex>Ratio.is_rational?(10)
false
iex>Ratio.is_rational?("foo")
false
iex>Ratio.is_rational?(10.0)
false
iex>Ratio.is_rational?(10.234)
false
iex>Ratio.is_rational?(10 <|> 3)
true
iex>Ratio.is_rational?(10 <|> 5)
false
iex>Ratio.is_rational?(+20.234)
true
iex>Ratio.is_rational?(+20.0)
false
lt?(a, b)

True if a is smaller than b

lte?(a, b)

True if a is smaller than or equal to b

minus(num)

Alias for Ratio.negate(num); follows Numeric behaviour.

mult(number1, number2)

Longhand for Ratio.*/2

negate(num)

Longhand for Ratio.-/1

new(numerator, denominator \\ 1)

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)

Examples

iex> Ratio.new(1, 2)
1 <|> 2
iex> Ratio.new(100, 300)
1 <|> 3
iex> Ratio.new(1.5, 4)
3 <|> 8
numerator(number)

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

pow(x, n)
pow(number | Ratio.t, pos_integer) :: number | Ratio.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

iex>pow(2, 4)
16
iex>pow(2, -4)
1 <|> 16
iex>pow(3 <|> 2, 10)
59049 <|> 1024
sign(number)

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.
sub(a, b)

Longhand for Ratio.-/2

to_float(number)
to_float(Ratio.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)

to_string(rational)

Returns a binstring representation of the Rational number. If the denominator is 1, it will be printed as a normal (integer) number.

Examples

iex> Ratio.to_string 10 <|> 7
"10 <|> 7"