bigint-rational

rational arithmetic using built-in bigints

Use this module to represent arbitrary-precision fractions using speedier built-in BigInt types with tighter control over performance and allocation.

If you want to support engines that don't have BigInt support, consider big-rat.

example

var rat = require('bigint-rational')
var out = [0n,1n]
rat.add(out, [4n,17n], [15n,6n])
rat.multiply(out, out, [8n,5n])
rat.subtract(out, out, [37n,52n])
console.log(out) // [97194n,26520n]
rat.reduce(out, out)
console.log(out) // [16199n,4420n]

api

You can load all the methods:

var rat = require('bigint-rational')

Or you can load individual files by their name. For example, to only load the reduce method:

var reduce = require('bigint-rational/reduce')

The conventions of this module are very similar to gl-vec3 or gl-mat4 where the container is an array or array-like type (in this case, a 2-tuple array).

If the result of the calculation is another rational, this result is written to the first argument (out) and is also the return value. This allows you to have more control over memory allocations, although the built-in bigint type has its own allocation profile and engine optimizations. It is always safe to use the same rational in the output and any of the arguments.

As you perform operations on rationals, the numerator and denominator will tend to grow. Methods such as add() are implemented without computing a common denominator and instead work according to a/b + c/d = (a*d + b*c) / (b*d). However, there are some special cases (such as the denominators being equal for addition and subtraction) to prevent the denominator from growing.

You can simplify the fractions using the reduce() method. After reducing, operations will tend to be faster but the reduce method itself has a performance cost as it must compute the greatest common divisor of both terms (a recursive algorithm). None of the arithmetic operations will automatically reduce the rational so that you have more fine-grained control over performance. Only reduce() uses a recursive algorithm.

rat.abs(out:rat, a:rat)

Take the absolute value of the rational a, storing the result in out.

Returns the stored result out.

rat.add(out:rat, a:rat, b:rat)

Add two rationals a and b, storing the result in out.

Returns the stored result out.

var clone = rat.clone(a:rat)

Return a new rational clone based on the contents of the rational a.

rat.compare(a:rat, b:rat)

Return whether a is greater than b (+1), less than b (-1), or equal to b (0).

Rationals do not need to be reduced to be considered equal. 9/12 and 6/8 are considered equal.

rat.copy(out:rat, a:rat)

Copy the contents of the rational a into out.

Returns the stored result out.

var r = rat.create(n:bigint, d:bigint)

Return a new rational r from a numerator n and a denominator d.

If n or d is not a bigint, it will be converted to a bigint using BigInt() this means you can use javascript numbers, decimal strings, or hex strings (prefaced by 0x) for the numerator and denominator.

rat.divide(out:rat, a:rat, b:rat)

Divide the rational a by the rational b, storing the result in out.

Returns the stored result out.

rat.eq(a:rat, b:rat)

Return a boolean whether the rationals a and b are equivalent.

Rationals do not need to be reduced to be considered equal.

rat.gt(a:rat, b:rat)

Return a boolean whether the rational a is greater than the rational b.

rat.gte(a:rat, b:rat)

Return a boolean whether the rational a is greater than or equal to the rational b.

rat.inverse(out:rat, a:rat)

Calculate the reciprocal of a, storing the result in out.

Returns the stored result out.

rat.lt(a:rat, b:rat)

Return a boolean whether the rational a is less than to the rational b.

rat.lte(a:rat, b:rat)

Return a boolean whether the rational a is less than or equal to the rational b.

rat.max(out:rat, a:rat, ...)

Calculate the largest rational from the provided values after the first argument, storing the result in out.

Returns the stored result out.

rat.min(out:rat, a:rat, ...)

Calculate the smallest rational from the provided values after the first argument, storing the result in out.

Returns the stored result out.

rat.multiply(out:rat, a:rat, b:rat)

Multiply the rational a by the rational b, storing the result in out.

Returns the stored result out.

rat.negate(out:rat, a:rat)

Negate the rational a, storing the result in out.

rat.pow(out:rat, a:rat, p:bigint)

Raise the rational a to the power p, storing the result in out.

rat.set(out:rat, n:bigint, d:bigint)

Store the numerator n and the denominator d in out.

If n or d is not a bigint, it will be converted to a bigint using BigInt() this means you can use javascript numbers, decimal strings, or hex strings (prefaced by 0x) for the numerator and denominator.

rat.sign(a:rat)

Return the sign of the rational a as a bigint: 1n, +1n, or 0n.

rat.reduce(out:rat, a:rat)

Simplify and normalize the rational a by factoring out a common divisor and moving the negative sign to the numerator if a has a negative sign.

Returns the stored result out.

rat.subtract(out:rat, a:rat, b:rat)

Subtract the rational a from the rational b, storing the result in out.

Returns the stored result out.

rat.toDecimal(a:rat, precision:bigint=10n, radix:bigint=10n)

Return a decimal approximation of the rational a as a string.

The result will have the integer part followed by a '.' followed by precision digits (default: 10 digits).

All the digits in the result are displaysed in base radix (default: 10).

license

BSD