ratio v0.6.1 Ratio

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

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 :: %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)
5 <|> 5
-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

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

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

mul(number1, number2)

Longhand for Ratio.*/2

negate(num)

Longhand for Ratio.-/1

new(numerator, denominator)

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

numerator(number)

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

pow(x, n)

Specs

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)

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

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"